Keep crew threads on their PR to the end and cap finished PRs at 10 before new fix threads (GST-2192) (#4240)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
Garry Tanandcapy-ai[bot] authored and GitHub committed 2026-11-09 21:16:27 +00:00
1 parent f75ce6fdcc
commit 6088c86f61
9 files changed
+44 -16

No files matched your search

+1 -1
View File
@@ -172,7 +172,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
| `/canary` | **SRE** | Post-deploy monitoring loop. Watches for console errors, performance regressions, and page failures. |
| `/benchmark` | **Performance Engineer** | Baseline page load times, Core Web Vitals, and resource sizes. Compare before/after on every PR. |
| `/ubicloud` | **Remote Runner** | Run a heavy suite, build or eval on an ephemeral 16-vCPU Ubicloud VM: owner- and TTL-named VMs with a reaper, quota preflight, a hang watchdog, and one committed verify per repository. |
| `/runaway-stopper` | **Spend Warden** | Find runaway agent threads and subagents on Capy (own context past 500M tokens, active past 3 days, a subagent past 100M, empty wakes, endless review rounds), stop them at a clean point, rotate threads through a handoff, and set the defaults that keep them from coming back. `gstack-runaway scan` reads the host's own thread data and never acts. |
| `/runaway-stopper` | **Spend Warden** | Find runaway agent threads and subagents on Capy (a standing thread past 500M own tokens or 3 days, a subagent past 100M, empty wakes, endless review rounds), stop them at a clean point, rotate standing threads through a handoff (a crew thread keeps its PR until it merges or closes), and set the defaults that keep them from coming back. `gstack-runaway scan` reads the host's own thread data and never acts. |
| `/eval-plan` | **Eval Planner** | Preregister a paid eval before the first priced call: bars, arms, decoys and stop rules, a $0 stub-model dry run over the real inputs, and a three-item priced pilot whose extrapolation and spend table gate the approval. |
| `/document-release` | **Technical Writer** | Audit changed behavior against project docs on every ship, before final verification and publication. Also runs standalone. Shows updated, reviewed/current or blocked docs and any remaining gaps. |
| `/document-generate` | **Documentation Author** | Generate missing docs from scratch using the Diataxis framework. Researches the codebase first, then writes reference / how-to / tutorial / explanation docs that actually match the code. Invokable standalone or chained from `/document-release` when the coverage map finds gaps. Learn more: [tutorial](docs/tutorial-document-generate.md) • [how-to](docs/howto-document-a-shipped-feature.md) • [why Diataxis](docs/explanation-diataxis-in-gstack.md). |
+2 -1
View File
@@ -13,5 +13,6 @@ Your crew's CREW.md and recorded approvals decide who may merge, update a base,
9. **Flakes: one rerun, a ledger, a daily fix.** Only the policy's rerun, never for a harness or infra red; a second red is real; never loosen a test. [crew/docs/captain.md: The daily flaky pass]
10. **Quiet.** Messages wake the Captain cold: send READY, a blocker, done or a Captain or owner call, else end_turn; no acks or progress notes. Broadcasts go in its notes.
11. **Ask once, plainly.** One ask per decision, explained like the owner is five: your Captain's name, then a lettered line each: "A: <code> hit problem p, which happens when h. We could do 1) x, 2) y or 3) z. Recommendation x because why. A1 to take recommendation." "do it" takes every recommendation; "A2" takes option 2. Owner tasks: the exact link (in Capy: path and field), numbered steps, the reply word. Never re-ask a standing rule; check what you can yourself. [crew/docs/captain.md: The ask format]
12. **Fresh threads, closed out.** One thread per unit of work; past 500M tokens, rotate [/runaway-stopper]. Crew threads never create threads: ask your Captain (Captain to Captain across projects), or report one you made by code for crew.add. Its Captain archives only its crew's threads, never one with an open PR or issue until a live successor holds it; a PR closes only as landed, superseded or dropped. Threads outside every crew are the owner's, even its automation's. Size reviews to the diff. [docs/ship-budget.md; crew/docs/captain.md: New threads join the crew]
12. **Fresh threads, closed out.** One thread per unit of work. A thread keeps its PR until it merges or closes and hands off only then, never mid-PR on a token count; past 1B own tokens it checks in with its Captain once and carries on. Standing threads that wake on every event (merge lanes, watchers) rotate at 500M tokens or 3 days [/runaway-stopper]. Crew threads never create threads: ask your Captain (Captain to Captain across projects), or report one you made by code for crew.add. Its Captain archives only its crew's threads, never one with an open PR or issue until a live successor holds it; a PR closes only as landed, superseded or dropped. Threads outside every crew are the owner's, even its automation's. Size reviews to the diff. [docs/ship-budget.md; crew/docs/captain.md: New threads join the crew]
13. **The owner's model preference.** `gstack-models resolve --role agent` picks agent models, except cross-family voices and eval subjects. [docs/model-policy.md: Your model preference]
14. **Finish before starting.** No new fix thread in a repo while more than 10 finished PRs (green, reviewed, waiting only to merge) sit in its queue: merge or close them first. Severe hotfixes are exempt: security, data loss, red main, a broken install. [crew/docs/captain.md: New threads join the crew]
+1
View File
@@ -31,6 +31,7 @@ For a crew lane (a thread working for a Captain). Read this once `gstack: ok <re
- Batch independent reads in one parallel program. Return 4k characters or less per call; write long output to a file under `~/.capy/work` and read the part you need.
- A wait you expect to last under about 30 minutes checks in every 240 s: `wait` on the operation with `duration_seconds: 240`, then re-issue it silently on a wake that brings nothing new. After about 30 minutes, or past the expected end, stop re-issuing and sleep on the operation or pull request watch. A longer wait sleeps on its operations. While /ship runs, sleep.
- Past twice the crew's median lane spend, write `handoffs/<code>/next.md` and tell the Captain in one line; it decides whether you continue, rotate or park.
- Keep your PR until it merges or closes; never hand off mid-PR on a token count. Past 1B own tokens (about $330), check in with the Captain once, then carry on unless told otherwise.
## Before a push
@@ -0,0 +1 @@
- **Crew threads keep their PR to the end, and a repo with more than 10 finished PRs waiting gets no new fix thread.** gstack's rules pages (factory.md, the lane start card, the Captain manual and /runaway-stopper) no longer tell a crew thread to hand off mid-PR on a token count: it keeps its PR until it merges or closes, and checks in with its Captain once when its own tokens pass 1 billion (about $330). Standing threads that wake on every event (merge lanes, watchers, an automation's standing thread) still rotate at 500M own tokens or 3 days, and subagent limits are unchanged. A Captain now starts no new fix thread in a repository while more than 10 green, reviewed PRs sit waiting only to merge; security, data-loss, red-main and broken-install hotfixes are exempt. Wording only: `gstack-runaway scan` still flags every non-Captain thread past 500M.
+17
View File
@@ -190,6 +190,16 @@ cheap:
per-PR figure in the controller's rules), where the lane stops and asks whether the PR
is still worth it. Spend is the
thread's credit meter, never a token count.
- **Keep the PR to the end.** A lane keeps its PR until it merges or closes and hands
off only at that boundary, never mid-PR on a token count. When its own tokens pass 1
billion (about $330), it checks in with the controller once, then carries on unless
told otherwise. Standing threads that wake on every event (merge lanes, watchers, an
automation's standing thread) still rotate at 500M own tokens or 3 days, and subagent
limits stay as they are: look at any subagent past 100M, and never reuse one across PRs
([/runaway-stopper](../../runaway-stopper/SKILL.md)). Why: every handoff wakes the
controller, whose tokens cost about 1.7 times a lane's, and handoffs are where orphaned
PRs came from. One PR went through four threads in eight hours (about 103k credits) on
per-thread token stops and was still a draft.
## New threads join the crew
@@ -213,6 +223,13 @@ the work's issue.
Why: a crew thread once created a thread in another project directly. That thread ran
outside every crew, so no Captain briefed it, tracked it or could archive it.
**Finish before starting.** The Captain starts no new fix thread in a repository while
more than 10 finished PRs (green, reviewed, waiting only to merge) sit in that
repository's queue. It merges or closes them first, closing only as landed, superseded or
dropped ([No orphaned work](#no-orphaned-work)). Severe hotfixes are exempt: security, data
loss, a red main or a broken install. Why: a finished PR that waits goes stale and
conflicting, and each new fix thread adds to a queue nobody is clearing.
## No orphaned work
A PR or issue whose owning thread is archived has nobody to wake. CI, reviews and merges
+3 -2
View File
@@ -968,9 +968,10 @@ sets the defaults that keep it from coming back.
- **Detect.** One program fetches each crew thread (`tools.thread.get`, with its transcript) to files, then
`gstack-runaway scan --dir <dir>` prints a `RUNAWAY:` line per thread and a `FLAG:` line per limit crossed:
own tokens past 500M or active past 3 days (rotate), a subagent past 100M (stop), empty wakes past 25% of the
own tokens past 500M or active past 3 days (rotate, for a standing thread that wakes on every event; a crew
thread keeps its PR until it merges or closes and checks in with its Captain once past 1B), a subagent past 100M (stop), empty wakes past 25% of the
last 40 turns (warm-wait check-ins are left out), and review rounds past 2 per PR. Captains are reported, never rotated.
- **Stop.** A live subagent past 100M is stopped with its reason. A thread is rotated at a clean point through
- **Stop.** A live subagent past 100M is stopped with its reason. A standing thread is rotated at a clean point through
a handoff file and a successor brief (`runaway-stopper/templates/`), then archived by its own Captain. A thread
mid-/ship or mid-merge gets `DEFER:` and nothing happens until that work finishes.
- **Prevent.** One wait on all pending operations, quiet wakes, compact program returns, one /ship subagent per
+8 -5
View File
@@ -188,17 +188,19 @@ return scan.output + (failed.length ? "\nFETCH_FAILED: " + failed.join(" ") : ""
A lane with nested subagents can also write `tools.subagent.list()` to `<code>.subagents.json` in that directory:
it lists the whole tree, where thread.get lists 200 rows at most (`own` is then an upper bound).
Limits (org rule R70): own tokens (total minus subagents) past 500M, or active (working, waiting, or a turn in the
last 24 hours) past 3 days: rotate, warn at 400M. A subagent past 100M: stop and look. Empty wakes past 25% of the
Limits (org rule R70, amended 2026-11-09): a standing thread that wakes on every event (a merge lane, a watcher, an
automation's standing thread) rotates past 500M own tokens (total minus subagents) or 3 days active (working,
waiting, or a turn in the last 24 hours), warn at 400M. A crew thread keeps its PR until it merges or closes, never
rotated mid-PR on a token count; past 1B own tokens it checks in with its Captain once. A subagent past 100M: stop and look. Empty wakes past 25% of the
last 40 turns (warm-wait check-ins left out). Review rounds past 2 per PR. Act on each line:
| Line | Do |
|---|---|
| `FLAG: ROTATE` | Step 3. |
| `FLAG: ROTATE` | A standing thread: Step 3. A crew thread holding a PR: nothing (the scan can't tell them apart). |
| `FLAG: REPORT` | A Captain over a limit: report it, never rotate it (Garry decides Captain rotation). |
| `FLAG: STOP` | Step 2. |
| `FLAG: LOOK` | A finished subagent past 100M: find why (reused for several runs? full-depth review?) and fix that cause from Step 4. |
| `FLAG: WARN` | Tell the thread the Step 4 rule it breaks, once. |
| `FLAG: WARN` | Tell the thread the Step 4 rule it breaks, once; an own-tokens WARN on a crew thread holding a PR needs nothing. |
| `DEFER:` | The thread is mid-/ship or mid-merge: act on nothing now; scan again when that work finishes. |
| `RUNAWAY_INPUT:`, `FETCH_FAILED:` | That thread wasn't read: fetch it again and rerun; never count it as OK. |
@@ -214,7 +216,7 @@ PR stays open; a fresh subagent with the run directory picks the work up if it i
## 3. Rotate a thread
Rotate only at a clean point: no `DEFER:`, no READY of that thread waiting on you, no merge in flight for its PR.
Rotate only a standing thread, and only at a clean point: no `DEFER:`, no READY of that thread waiting on you, no merge in flight for its PR.
1. Tell it: "Rotation (R70). Start nothing new; stop your working and waiting subagents, or list each with its run
directory; write handoffs/<code>-rotation.md from gstack's `runaway-stopper/templates/rotation-handoff.md` and
reply with its path."
@@ -240,6 +242,7 @@ Put the lines that apply into every brief you write:
(`#<n>`) so the scan can count them.
- **Rotate standing roles** at 500M own tokens or 3 days. An automation gets a fresh thread per run that archives
itself, or a slower schedule, instead of waking a standing thread.
- **Crew threads keep their PR to the end:** no token stop mid-PR; one Captain check-in past 1B own tokens.
## Report
+8 -5
View File
@@ -64,17 +64,19 @@ return scan.output + (failed.length ? "\nFETCH_FAILED: " + failed.join(" ") : ""
A lane with nested subagents can also write `tools.subagent.list()` to `<code>.subagents.json` in that directory:
it lists the whole tree, where thread.get lists 200 rows at most (`own` is then an upper bound).
Limits (org rule R70): own tokens (total minus subagents) past 500M, or active (working, waiting, or a turn in the
last 24 hours) past 3 days: rotate, warn at 400M. A subagent past 100M: stop and look. Empty wakes past 25% of the
Limits (org rule R70, amended 2026-11-09): a standing thread that wakes on every event (a merge lane, a watcher, an
automation's standing thread) rotates past 500M own tokens (total minus subagents) or 3 days active (working,
waiting, or a turn in the last 24 hours), warn at 400M. A crew thread keeps its PR until it merges or closes, never
rotated mid-PR on a token count; past 1B own tokens it checks in with its Captain once. A subagent past 100M: stop and look. Empty wakes past 25% of the
last 40 turns (warm-wait check-ins left out). Review rounds past 2 per PR. Act on each line:
| Line | Do |
|---|---|
| `FLAG: ROTATE` | Step 3. |
| `FLAG: ROTATE` | A standing thread: Step 3. A crew thread holding a PR: nothing (the scan can't tell them apart). |
| `FLAG: REPORT` | A Captain over a limit: report it, never rotate it (Garry decides Captain rotation). |
| `FLAG: STOP` | Step 2. |
| `FLAG: LOOK` | A finished subagent past 100M: find why (reused for several runs? full-depth review?) and fix that cause from Step 4. |
| `FLAG: WARN` | Tell the thread the Step 4 rule it breaks, once. |
| `FLAG: WARN` | Tell the thread the Step 4 rule it breaks, once; an own-tokens WARN on a crew thread holding a PR needs nothing. |
| `DEFER:` | The thread is mid-/ship or mid-merge: act on nothing now; scan again when that work finishes. |
| `RUNAWAY_INPUT:`, `FETCH_FAILED:` | That thread wasn't read: fetch it again and rerun; never count it as OK. |
@@ -90,7 +92,7 @@ PR stays open; a fresh subagent with the run directory picks the work up if it i
## 3. Rotate a thread
Rotate only at a clean point: no `DEFER:`, no READY of that thread waiting on you, no merge in flight for its PR.
Rotate only a standing thread, and only at a clean point: no `DEFER:`, no READY of that thread waiting on you, no merge in flight for its PR.
1. Tell it: "Rotation (R70). Start nothing new; stop your working and waiting subagents, or list each with its run
directory; write handoffs/<code>-rotation.md from gstack's `runaway-stopper/templates/rotation-handoff.md` and
reply with its path."
@@ -116,6 +118,7 @@ Put the lines that apply into every brief you write:
(`#<n>`) so the scan can count them.
- **Rotate standing roles** at 500M own tokens or 3 days. An automation gets a fresh thread per run that archives
itself, or a slower schedule, instead of waking a standing thread.
- **Crew threads keep their PR to the end:** no token stop mid-PR; one Captain check-in past 1B own tokens.
## Report
+3 -2
View File
@@ -680,13 +680,14 @@ describe('capy skill: factory.md, the auto-loaded "how we work" page', () => {
return [...new Set(problems)];
}
test('it fits the 3,650-byte budget, and every citation, heading and skill it names resolves', () => {
test('it fits the 4,200-byte budget, and every citation, heading and skill it names resolves', () => {
const text = fs.readFileSync(FACTORY, 'utf8');
// 3,300 since #3634; raised to 3,450 (the page's new size, rounded up to the next 25 bytes) for point 12's
// R68 clause (Garry, 2026-11-03: crew threads ask their Captain for new threads). Raise it only by what a rule needs.
// 3,475 for the crew/ prefix on its four Captain-manual citations (GST-1833 moved docs/captain.md to crew/docs/; no rule text changed).
// 3,650 for point 2's one-open-PR-per-lane rule and point 12's no-orphan and close-reason rule (GST-2077, Garry's "do it" 2026-11-09: lessons from gbrain's merge queue).
expect(Buffer.byteLength(text)).toBeLessThanOrEqual(3650);
// 4,200 for point 12's keep-the-PR-to-the-end and standing-thread rotation clause and point 14's cap of 10 finished PRs before a new fix thread (Garry's "do it" 2026-11-09, relayed by FOUN-32).
expect(Buffer.byteLength(text)).toBeLessThanOrEqual(4200);
expect(text).toMatch(/^# How we work/);
expect(citationProblems(text)).toEqual([]);
});