diff --git a/CHANGELOG.md b/CHANGELOG.md index 812145d5f..f6e40735e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## [Unreleased] +## [1.91.319.0] - 2026-10-29 **`gstack-pregate sealed` no longer prints a line that reads like a push confirmation.** On gstack-evals#29 the lane read `pushed aeb2413` in the `SEALED:` line as the push landing, while the remote stayed at 9036ab1 (#3565). `sealed` never pushes: it checks the commits a push would publish. `pushed ` was its label for the commit whose `sealed` policy it read beside the base branch's. @@ -11,6 +11,102 @@ ### Tests - `test/sealed-guard.test.ts`: `gstack-pregate sealed` names the checked commit, prints no `pushed`, and leaves the remote's refs exactly as they were. It failed before the fix on `policy=origin/main + pushed `. +## [1.91.318.0] - 2026-10-29 + +**/office-hours now has eval tasks for the shared skill eval, and /write-skill's diet locks its tasks before a paid run.** gstack-evals' Lane A will re-check the office-hours diet from #3525. To do that it needs office-hours' tasks in gstack's contract format, a sidecar for what Lane A adds, and a diet step that commits the lock a paid run requires. #3525 never committed the task set GSTA-134 ran, so these tasks rebuild it from the pilot's written summary. + +### Added +- **`test/fixtures/skill-evals/office-hours/`**: 11 tasks on a CSV-merge idea, with a `seed.sh` that makes the git repo and the `.gstack-home` state root. Nine follow the pilot's set, which covered the mode question, the first startup question, pushback on vague evidence, builder mode, the premise challenge, the second-opinion offer, alternatives, the UI visual step and the backend skip. Two are new safety tasks. One allows no code during a session (the hard gate), and the other allows no design doc before the user picks an approach (the Phase 4 stop). `no-code-mvp` failed in every arm of the pilot and is left out. +- **`tasks.ext.json`** beside it, in Lane A's sidecar format: every task is interactive, with a persona and scripted replies, a judge rubric per behavior task, and a violating `mutant` per safety task. Reply category names are provisional until gstack-evals publishes its list. + +### Changed +- **/write-skill diet step 6** starts with `gstack-evals skill-eval --lock` and a commit of `tasks.lock.json`. Without that commit the shared eval refuses a paid run (LOCK_MISSING). +- **`docs/designs/SKILL_EVAL_CONTRACT.md`** adds notes for implementers. The harness should set both `GSTACK_STATE_ROOT` and `GSTACK_HOME` to `/.gstack-home`. A verdict may carry an optional `resumable` field. The notes also cover the lock, the sidecar, and an open question about what `must` patterns grade when a host answers an interactive task's questions. + +### Tests +- `test/skill-eval-tasks.test.ts` checks office-hours' `tasks.json` against the contract. It also checks that each `tasks.ext.json` entry names a task in `tasks.json` and uses only known keys. No existing test, threshold or allowlist changed. + +## [1.91.317.0] - 2026-10-29 + +**Registered gstack skills now say when to use them where the harness model reads them, and OpenClaw lists the task skills directly.** HARN-5's paid cells showed OpenClaw and Hermes listing gstack's skills while the model rarely opened them. Router lines kept only each skill's first sentence and dropped its "Use when asked to ..." trigger, and Hermes's skills index shows only the first 57 characters of a description, which for gstack was capability prose. This release changes only what gstack writes into its own skills folders. Use rates are not claimed yet: HARN-5's fixed panel measures them next. + +### Changed +- **Router lines lead with the trigger** (`gstack-harness`, every router-mode target: OpenClaw, dots, `generic` and `--print`). Each line opens with the skill's own trigger sentence, or, when the description has none, `Use for:` and the skill's `triggers:` list, within 160 characters. The router's description now leads with task verbs (review, debug, QA test, plan, ship) in its first 200 characters, within the 300-character budget. The wording rule lives in `lib/skill-triggers.ts`. +- **Hermes descriptions open with a trigger list of at most 57 characters** (`frontmatter.descriptionLead` in `hosts/hermes.ts`), for example `Use for: review this pr, code review, check my diff.`, followed by the description without its own trigger sentence, which the lead repeats, so no Hermes render grows. Claude Code and every other host render their descriptions as before. +- **OpenClaw registers in `hybrid` mode by default**: `gstack-review`, `gstack-investigate`, `gstack-qa`, `gstack-ship` and `gstack-plan-eng-review` are top-level skills and the `gstack` router carries the rest. Dumped through OpenClaw 2026.10.6's own `buildSkillSnapshot`/`prepareSkillsForPrompt` with its 19 eligible bundled skills, hybrid's skills section is 10,290 characters in full format (budget 18,000). `--skills all` falls to compact format at 17,971 characters, and `--skills router` is 6,701. `--skills router` and `--skills all` remain, and a mode switch now removes the empty folders the previous mode left behind. +- **`--context ` is opt-in for OpenClaw and Hermes too**: the block is written only into the file named, after a `gstack-harness: context block: ( scope)` line. Setup, upgrades and refresh never add one and do not re-add a block you deleted. A second `--context` file keeps the first, because the ledger keys blocks by file. The block text follows the mode (with `--skills all` it names no router path). Uninstall now restores each file byte for byte (the blank separator line, a missing final newline and a file gstack created are undone). +- `HARNESS_MODE_UNSUPPORTED`'s fix text and docs/hosts.md describe Hermes's listing, not its loader, and docs/hosts.md states registered, listed and used as separate facts. + +### Fixed +- Re-registering an OpenClaw, Hermes or dots registration without `--context` (what setup and `gstack-harness auto` do) no longer cuts a block the user opted into. + +### Added +- `HARNESS_CONTEXT_REFUSED`: `--context` refuses `SOUL.md` (in any letter case), and for Hermes a new rules file that would outrank rules Hermes loads now: a file of an earlier group (`.hermes.md`/`HERMES.md` before `AGENTS.md` before `CLAUDE.md`), an earlier name in the same folder (`.hermes.md` before `HERMES.md`, `AGENTS.override.md` before `AGENTS.md`), or a `.hermes.md`/`HERMES.md` below one in a parent folder, which Hermes takes as the nearest. + +### Gate integrity +- `test/harness-register.test.ts`: three expectations change with the byte-for-byte restore and blocks keyed by file. The generic cut now expects the original bytes, without the extra newline. The second `--context` case now expects both blocks kept and both restored where it used to expect the first block cut. The OpenClaw router case passes `mode: 'router'` because the default is now hybrid. New cases cover router lines, Hermes leads (at most 57 characters), hybrid with mode switches through refresh and uninstall, context opt-in, refusal and scope, the CLI scope line, and Hermes's threat scanner on every block variant. The scanner case runs when `GSTACK_HERMES_SRC` names a Hermes checkout and is skipped otherwise. More new cases cover the same-folder and nearest-parent refusals, pre-blockpad ledgers, refresh keeping a block the user edited, `--json --context` output, and the Hermes check outside a git repository; new `test/skill-triggers.test.ts` covers the wording rule's fallbacks and cuts. +- `test/fixtures/skill-md-size-allowlist.json`: the Hermes pins for `gstack-autoplan` (108,982 to 108,891) and `gstack-plan-eng-review` (128,708 to 128,655) go down to the new render sizes, as the size guard directs. +- New `test/session-kind-marker.test.ts`: a marker-only environment (`GSTACK_SESSION_KIND=spawned`, no `GSTACK_CAPY`) gets the same soft admission from `bin/gstack-install-verdict.sh` and `lib/install-verdict.ts`. A ratchet fails when a file in `bin/`, `lib/`, `hosts/` or `scripts/` reads or sets `GSTACK_SESSION_KIND` outside its 13-file inventory; a planted-reader control and a comments-only control check it. + +## [1.91.316.0] - 2026-10-29 + +**/ship takes a token cap and stops cleanly at it, and long runs hand their heavy segments to fresh-context children.** On gstack-evals#31 a /ship spent 54M tokens against a 25M cap because the cap was only a number in a brief; #26, whose agent read the counter after every step, stopped at 39.40M of 40M. `/ship --token-cap 25M` (or `GSTACK_SHIP_TOKEN_CAP`) now admits each step and dispatch batch only when it fits, and a run started from a long-lived context, or one whose per-call charge passes 150k at Step 7 or Step 12, runs that segment in a fresh child. + +### Added +- **`gstack-ship-budget`** (`lib/ship-budget.ts`, `lib/ship-budget-cli.ts`, `lib/ship-handoff.ts`): an admission cap on a per-run token ledger under `/ship-runs//` (its own schema; only `withFileLock` is shared with `lib/spend-ledger.ts`). `start`, `check` (the `BUDGET:` line, `verdict=continue|delegate|stop`, a `RESERVATION:` id per admitted step or batch), `settle`/`release`, `handoff`/`launch`/`verify-handoff`/`return`/`reconcile`, `resume` (cap raises need `--approved-by` and the owner's words; `--rebuild-from-record`; restore from a private Drive checkpoint) and `close`. Exit 0 continue/delegate, 3 stop, 2 usage. Each meter is a versioned contract, and there are three: the Capy root counter (`--reading`), Claude Code journal usage (`lib/claude-usage.ts`, bound by `--session` or an echoed nonce) and `--meter estimate`. +- **`gstack-review-log --start ... --reservation `**: under a cap, a dispatch without an unspent, one-shot reservation refuses before launch (`BUDGET_CHECK_SKIPPED`), and `--finish` settles it. Without a cap nothing changes. +- **/ship**: the skeleton's Budget paragraph (`--token-cap`, `--resume `, `--continue `) and a new `budget-handoff` section with the meter recipes, reservations, stop and resume, and the delegate flow per host. +- **Result codes** `BUDGET_CAP_REACHED`, `BUDGET_READING_MISSING`, `BUDGET_READING_REJECTED`, `BUDGET_METER_UNAVAILABLE`, `BUDGET_LEDGER_INVALID`, `BUDGET_CHECK_SKIPPED`, `HANDOFF_PIN_MOVED` with docs/troubleshooting.md anchors; `lib/ship-budget-calibration.json` seeded from #19, #26 and #31. +- **Docs**: docs/ship-budget.md (linked from docs/unattended.md), and a paragraph each in the Capy skill's SKILL.md and captain.md. + +### Tests +- `test/ship-budget.test.ts`: the cap boundary, batch overshoot, the #31 replay, spend above a reservation, the no-cap path, meters and epochs, exit codes, start and segment delegation, the full handoff chain with an idempotent reconcile, moved pins and a tampered brief, refused and interrupted children, stop and RECOVER, checkpoint restore into an empty state root, ledger rebuild, concurrent ledgers, and an unchanged `gstack-wtree`. +- `test/ship-budget-review-log.test.ts`, `test/claude-usage.test.ts`, `test/ship-budget-calibration.test.ts` (leave-one-out), `test/ship-budget-section.test.ts`. + +## [1.91.315.0] - 2026-10-29 + +### Changed +- **Stacked PRs** (Fixes #3570): after a stack parent lands and the child is retargeted to the base with the base merged in, `carry --base ` compares HEAD's product diff against the base with the range the receipt reviewed against the parent branch. That is the recorded `product_patch_id`, or the range against `origin/` for an older receipt. HEAD's side is its whole product diff against the base, so a parent's `package.json` change that never reached the base refuses too. Equal carries with the reason `stack parent landed` and rebinds the receipt's `base` to the base; anything else refuses. Until now every stacked child paid a full /ship once its parent merged (gstack-evals#19). + +### Tests +- `test/ship-receipt-carry-squash.test.ts`: a child carries after its parent squash-merges and main is merged in, names main as its base, and carries again across a later main merge. A test-only child carries. A child edited after the merge, a parent that never landed, a parent `package.json` change that never reached main, and a merge that keeps the child's tree over the landed parent refuse. An older receipt falls back to `origin/` and refuses once that branch is deleted. + +## [1.91.314.0] - 2026-10-29 + +**A later autoplan gate that asks nothing new is now answered with the owner's earlier words instead of another round trip.** Captains were carrying approvals across gate revisions by hand (GSTA-140 reused a rev-1 "Do it" on rev 2; ALPH-50 lost about 27 minutes to one), and a replay over 23 recorded runs found 14 later gates, 8 of them holding only post-cap delta items. + +### Added +- **Carry-forward** (`lib/autoplan-carry.ts`): when gate_rev N+1 asks nothing new and gate_rev N was fully answered by the owner with `rec` or "do it", gstack answers N+1 with those recorded words and prints `CARRIED: gate_rev= <- gate_rev= …`; anything else prints `CARRY: no ()` and goes to the owner. `--no-carry-forward` on the first `next` turns it off. +- **"do it" covers new low-risk items.** When the owner's own words were "do it", a new item that changes no scope, cost, direction or plan text takes its recommendation, is marked `carried_under: do it`, and is listed in the approval record and the Captain brief as not shown to the owner. A Captain's "do it" never counts. +- **Delta check.** A "plan changed after cap" item gets one reviewer from another model family on the delta first (`CARRY_CHECK:`, `gstack-autoplan check`), within a per-gate spend cap (`--carry-check-cap`, default $5). High or above, no reviewer, an owner answer, or a plan edit after dispatch leaves the gate for the owner and releases the reservation. The verdict is recorded on `gate.json`, the decision rows and `decisions.tsv`. +- **`eli5` in gate.json**: the plan's `## ELI5` and the four approvals-shape sections; `gstack-gate render` opens page 1 with them, and the Captain brief requires `## ELI5` (older runs render as before). +- **`gstack-approvals import --autoplan --stack b1,b2`** writes the same rows to every branch of a stack, or to none when one branch is unknown. +- **`REVIEW_ESTIMATE:`** on the first `next`: phases, voices, rounds, attempts and the reservation total. + +### Changed +- `lib/decision-trail.ts` holds the trail append rules shared by `gstack-decision-trail` and the carry. + +## [1.91.313.0] - 2026-10-29 + +**The PII scanner stops flagging two kinds of ordinary text: a bare power-of-two or hash constant in code, and a package@version-style filename.** Eval artifacts and PR bodies that print a PRNG range or name a versioned results file no longer raise a MEDIUM phone or email finding, and real phone numbers and addresses next to them still report. + +### Fixed +- **`lib/redact-patterns.ts`**: `pii.phone.e164` skips a bare number that is exactly a power of two from 2^30 through 2^49, one less than one, or one of eleven well-known 32-bit hash and PRNG constants. The same digits written with a `+`, spaces, dashes, dots or parentheses still report (#3577). +- **`lib/redact-patterns.ts`**: `pii.email` skips a filename whose part after the `@` is a version or tag followed by file extensions no top-level domain uses, or a dotted version followed by an extension that doubles as one. A file named after a real address, an address at a numeric domain such as 163.com, and an address under a top-level domain that doubles as an extension (`.sh`, `.md`) still report (#3576). + +### Tests +- `test/redact-constant-and-at-filename.test.ts`: pins both exemptions in both directions, including files named after a real address. + +## [1.91.312.0] - 2026-10-29 + +**An install check run from inside /ship no longer upgrades gstack under it.** /ship's docs step runs `scripts/install.sh --for document-release`. That run fast-forwarded the checkout from 1.91.298 to 1.91.299 in the middle of a lane's /ship, so the receipt writer's rules changed partway through the run (#3571). + +### Fixed +- **`bin/gstack-capy-session`**: in install mode, a live workflow lease under 120 minutes old held by the caller's own process chain now skips the self-upgrade: `SELF_UPGRADE: skipped (a gstack run in this session holds a workflow lease on this installation: pid

(m ), so the upgrade waits until the lease is 120 minutes old; …(UPGRADE_BUSY))`. The install still certifies the installed revision and the trailer stays ok with `behind=`. `bin/gstack-upgrade` deliberately ignores the caller's own lease, and an install started from inside the run passed that check. Each `gstack-skill-start` renews the lease. The age bound matters on Capy, where the leased pid is the machine's long-lived `capy-server`, so a lease is never released by its process exiting. An older lease, or none, upgrades as before, and `GSTACK_UPGRADE_FORCE=1` or a hand-run `bin/gstack-upgrade` still moves the checkout. + +### Tests +- `test/capy-skill-wrapper.test.ts`: an install run under a shell that holds a fresh lease leaves HEAD where it was and stays ok. Once that lease is 121 minutes old, with its holder still alive, the same install upgrades. Before this change the first run printed `SELF_UPGRADE: done 1.0.1 -> 1.0.2`. + ## [1.91.311.0] - 2026-10-29 **A sealed policy can now refuse `sealed//tasks.json` while allowing the `MANIFEST.json` beside it, and can catch `HELDOUT/` with a `heldout` glob.** The sealed guard only had deny globs and one-commit waivers, so the gstack-evals layout, which keeps a public manifest of hashes and counts next to its sealed tasks, needed a fresh `.gstack/sealed-allow.tsv` line for every manifest commit (gstack-evals wiki/board/2026-10-28-gsta-9-sealed-manifest-glob-gap.md). Their first draft also wrote `sealed/**`, which never matched their nested `tasks//sealed/` directories, and garrytan/gstack-evals#3 (dc54796) hand-listed `Sealed/`, `HELDOUT/` and other case variants. diff --git a/README.md b/README.md index df7265150..222b96893 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ installs and passes the conformance tests but has no certification run yet; | GitHub Copilot CLI | experimental | `--host copilot` → `~/.copilot/skills/gstack-*/` | `/gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host copilot` | | Antigravity CLI | experimental | `--host agy` (or `--host antigravity`) → `~/.gemini/antigravity-cli/skills/gstack-*/` | `/gstack-office-hours` | advisory, not blocked | Codex CLI, signed in | `./setup --host agy` | | Slate | instruction-only | `--host slate` (points at the Claude install; Slate reads `.claude/skills`) | `/office-hours` via the Claude install | advisory, not blocked | — | `./setup --host claude` | -| OpenClaw | experimental | `--host openclaw` (one `gstack` router skill in OpenClaw's skills folder; automatic when setup runs inside OpenClaw; ACP route in [docs/OPENCLAW.md](docs/OPENCLAW.md)) | ask for the task; the agent opens the `gstack` skill | advisory, not blocked | — | `./setup --host openclaw` | +| OpenClaw | experimental | `--host openclaw` (five task skills and one `gstack` router skill in OpenClaw's skills folder; automatic when setup runs inside OpenClaw; ACP route in [docs/OPENCLAW.md](docs/OPENCLAW.md)) | ask for the task; the agent opens the matching task skill or the `gstack` router | advisory, not blocked | — | `./setup --host openclaw` | | Hermes | experimental | `--host hermes` (every skill in `$HERMES_HOME/skills/gstack`; automatic when setup runs inside Hermes) | ask for the task, or `/gstack-review` | advisory, not blocked | — | `./setup --host hermes` | | GBrain (mod) | instruction-only | `--host gbrain` (brain-aware variants ship from the GBrain repo) | — | advisory, not blocked | — | — | diff --git a/VERSION b/VERSION index 71dfc4396..c6d249a3f 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.91.311.0 +1.91.319.0 diff --git a/agents-digest/gstack-AGENTS.md b/agents-digest/gstack-AGENTS.md index 2ea2fcfa8..3a2793d5c 100644 --- a/agents-digest/gstack-AGENTS.md +++ b/agents-digest/gstack-AGENTS.md @@ -1,4 +1,4 @@ -# gstack digest v1.91.311.0 — regenerate/re-copy after upgrading gstack +# gstack digest v1.91.319.0 — regenerate/re-copy after upgrading gstack Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed for agent hosts without a full skill install. The full skills add workflows, diff --git a/autoplan/DRIVER.md b/autoplan/DRIVER.md index f1e1a3f96..875ea1068 100644 --- a/autoplan/DRIVER.md +++ b/autoplan/DRIVER.md @@ -26,7 +26,7 @@ line yourself; gstack never writes the plan. 1. `next` prints one `ATTEMPT: phase=

voice=native|outside prompt= result=` per voice. Dispatch the native prompt to a subagent on your model and the outside prompt to - a subagent on another model family (or `gstack-outside-voice run`). Each writes `result=`. + a subagent on another model family (or `gstack-outside-voice run`). Each writes `result=`. The first `next` also prints `REVIEW_ESTIMATE:` (most attempts and reservations the review can take). 2. Submit each voice exactly once (`BOUND:`). Both voices in closes the phase (`PHASE_CLOSED:`). 3. Repeat `next` until `status=gate_pending` (`GATE: gate_rev=`); render it with `gstack-gate render

/gate.json --all` and relay every page with the two cost lines printed under `GATE:`: `GATE_SPEND:` (spent, worst case, cap, headroom, attempts; host-subagent attempts are priced unknown and counted at their reservation, so quote their real figure from the host's cost view) and `GATE_REC_COST:` (the phases `rec` can reopen and the estimate for them, an upper bound; `gate_cost` in `--json`). You never approve the gate for the owner. Offer `rec` (every recommendation, plan changes included) as the default. @@ -38,6 +38,7 @@ line yourself; gstack never writes the plan. 5. `REOPENED: ` means loop `next` again (Eng last). `APPROVED:` means `export` (`DISPATCHES: est_input_tokens=`, relative). 6. Rounds: one by default; a second only for High or Critical findings; cap 2 (`--max-rounds`). A `revise` whose decisions all resolve below High prints `APPLIED: without re-review (below High)`. At the cap with High open, `ESCALATE: evidence sufficient, decision needed`: relay it, never ask for another round. +7. Carry-forward ([docs/unattended.md#carry-forward](../docs/unattended.md#carry-forward); `--no-carry-forward` on the first `next` opts out): a later gate that asks nothing new takes the owner's words from the gate before it (`CARRIED:`, then `APPROVED:`); `CARRY: no ()` leaves it for the owner; `CARRY_CHECK:` means one reviewer from another model family reads the printed delta prompt, then `check --out --attempt --result --model ` (or `--unavailable ""`). ### On Capy @@ -51,9 +52,8 @@ line yourself; gstack never writes the plan. with `gstack-config set autoplan_checkpoint drive`) so a run survives machine replacement: a generation is published at rest, after each bound voice and after each phase transition; restore with `resume --out --from /`, which never redispatches a bound voice. -- Plans carry `## Before → after`, `## Why it matters`, `## What caused this work`, `## Big decisions`; - relay the printed `RELAY: gstack-owner-brief render --captain` output to your Captain (or the person), - then `gstack-approvals import --autoplan ` after `answer` (`capy/skill/gstack/captain.md`). +- Plans carry `## ELI5` (5-10 plain sentences), `## Before → after`, `## Why it matters`, `## What caused this work`, `## Big decisions`; + relay the printed `RELAY: gstack-owner-brief render --captain` output to your Captain (or the person), then `gstack-approvals import --autoplan ` after `answer` (`--stack ` for a stack; `capy/skill/gstack/captain.md`). ### Commands diff --git a/autoplan/DRIVER.md.tmpl b/autoplan/DRIVER.md.tmpl index b2ff2b001..9b3ed3765 100644 --- a/autoplan/DRIVER.md.tmpl +++ b/autoplan/DRIVER.md.tmpl @@ -23,7 +23,7 @@ line yourself; gstack never writes the plan. 1. `next` prints one `ATTEMPT: phase=

voice=native|outside prompt= result=` per voice. Dispatch the native prompt to a subagent on your model and the outside prompt to - a subagent on another model family (or `gstack-outside-voice run`). Each writes `result=`. + a subagent on another model family (or `gstack-outside-voice run`). Each writes `result=`. The first `next` also prints `REVIEW_ESTIMATE:` (most attempts and reservations the review can take). 2. Submit each voice exactly once (`BOUND:`). Both voices in closes the phase (`PHASE_CLOSED:`). 3. Repeat `next` until `status=gate_pending` (`GATE: gate_rev=`); render it with `gstack-gate render

/gate.json --all` and relay every page with the two cost lines printed under `GATE:`: `GATE_SPEND:` (spent, worst case, cap, headroom, attempts; host-subagent attempts are priced unknown and counted at their reservation, so quote their real figure from the host's cost view) and `GATE_REC_COST:` (the phases `rec` can reopen and the estimate for them, an upper bound; `gate_cost` in `--json`). You never approve the gate for the owner. Offer `rec` (every recommendation, plan changes included) as the default. @@ -35,6 +35,7 @@ line yourself; gstack never writes the plan. 5. `REOPENED: ` means loop `next` again (Eng last). `APPROVED:` means `export` (`DISPATCHES: est_input_tokens=`, relative). 6. Rounds: one by default; a second only for High or Critical findings; cap 2 (`--max-rounds`). A `revise` whose decisions all resolve below High prints `APPLIED: without re-review (below High)`. At the cap with High open, `ESCALATE: evidence sufficient, decision needed`: relay it, never ask for another round. +7. Carry-forward ([docs/unattended.md#carry-forward](../docs/unattended.md#carry-forward); `--no-carry-forward` on the first `next` opts out): a later gate that asks nothing new takes the owner's words from the gate before it (`CARRIED:`, then `APPROVED:`); `CARRY: no ()` leaves it for the owner; `CARRY_CHECK:` means one reviewer from another model family reads the printed delta prompt, then `check --out --attempt --result --model ` (or `--unavailable ""`). ### On Capy @@ -48,9 +49,8 @@ line yourself; gstack never writes the plan. with `gstack-config set autoplan_checkpoint drive`) so a run survives machine replacement: a generation is published at rest, after each bound voice and after each phase transition; restore with `resume --out --from /`, which never redispatches a bound voice. -- Plans carry `## Before → after`, `## Why it matters`, `## What caused this work`, `## Big decisions`; - relay the printed `RELAY: gstack-owner-brief render --captain` output to your Captain (or the person), - then `gstack-approvals import --autoplan ` after `answer` (`capy/skill/gstack/captain.md`). +- Plans carry `## ELI5` (5-10 plain sentences), `## Before → after`, `## Why it matters`, `## What caused this work`, `## Big decisions`; + relay the printed `RELAY: gstack-owner-brief render --captain` output to your Captain (or the person), then `gstack-approvals import --autoplan ` after `answer` (`--stack ` for a stack; `capy/skill/gstack/captain.md`). ### Commands diff --git a/bin/gstack-approvals b/bin/gstack-approvals index da97642a9..3d3d5a9ef 100755 --- a/bin/gstack-approvals +++ b/bin/gstack-approvals @@ -5,7 +5,7 @@ * gstack-approvals add --ask --words --by --scope * [--pending ] [--outcome approved|rejected|pending|standing] * [--date YYYY-MM-DD] [--source ] [--branch ] [--json] - * gstack-approvals import --autoplan [--by ] [--branch ] [--json] + * gstack-approvals import --autoplan [--by ] [--branch | --stack ] [--json] * gstack-approvals render [--no-heading] [--branch ] * gstack-approvals list [--json] [--branch ] * gstack-approvals sync [--branch ] @@ -20,14 +20,15 @@ */ import * as path from 'node:path'; import { EXIT, exitTableHelp } from '../lib/headless-artifacts'; -import { appendRows, buildRow, importAutoplan, locate, readRecord, renderRecord, syncRecord, type RecordError, type StoreLocation } from '../lib/approval-record'; +import { appendRows, branchExists, buildRow, importAutoplan, locate, readRecord, renderRecord, syncRecord, type RecordError, type StoreLocation } from '../lib/approval-record'; import { resultLine } from '../lib/result-codes'; const HELP = `gstack-approvals — the per-thread approval record (capy/skill/gstack/captain.md) add --ask --words --by --scope [--pending ] [--outcome approved|rejected|pending|standing] [--date YYYY-MM-DD] [--source ] - import --autoplan [--by ] + import --autoplan [--by ] [--stack ] + --stack writes the same rows to every branch of a stack; each branch is checked first, and one unknown branch writes none render [--no-heading] the ## Approvals section for a PR body or report list [--json] sync re-mirror the record (GSTACK_APPROVALS_DIR, the Captain's drive approvals/, or the project-user Drive) @@ -40,7 +41,7 @@ Example: ${exitTableHelp()}`; -const VALUE_FLAGS = new Set(['--ask', '--words', '--by', '--scope', '--pending', '--outcome', '--date', '--source', '--branch', '--autoplan']); +const VALUE_FLAGS = new Set(['--ask', '--words', '--by', '--scope', '--pending', '--outcome', '--date', '--source', '--branch', '--autoplan', '--stack']); function parse(args: string[]): { flags: Record; bools: Set; error?: string } { const flags: Record = {}; @@ -64,11 +65,45 @@ function fail(cmd: string, e: RecordError): number { return EXIT.refused; } +/** `import --stack`: every branch checked first, then the same rows (ids are branch-independent) written to each branch's record. */ +function importStack(cmd: string, flags: Record, json: boolean): number { + if (cmd !== 'import' || !flags['--autoplan'] || flags['--branch'] !== undefined) { process.stderr.write(`gstack-approvals: --stack goes with import --autoplan , without --branch\n`); return EXIT.usage; } + const branches = [...new Set(flags['--stack']!.split(',').map(b => b.trim()).filter(Boolean))]; + if (!branches.length) { process.stderr.write(`gstack-approvals: --stack needs \n`); return EXIT.usage; } + const cwd = process.cwd(); + const missing = branches.filter(b => !branchExists(cwd, b)); + if (missing.length) return fail(cmd, { code: 'APPROVAL_RECORD_NO_BRANCH', message: `no local or origin branch ${missing.join(', ')}; nothing was written` }); + const runDir = path.resolve(flags['--autoplan']); + const results: Array<{ branch: string; added: string[]; skipped: number; file: string; mirror: string | null; error?: string }> = []; + let firstError: RecordError | undefined; + const plans: Array<{ branch: string; loc: StoreLocation; rows: ReturnType & unknown[] }> = []; + for (const branch of branches) { + const loc = locate({ cwd, env: process.env, branch }); + if ('code' in loc) return fail(cmd, loc); + const rows = importAutoplan(runDir, branch, flags['--by']); + if ('code' in rows) return fail(cmd, rows); + plans.push({ branch, loc, rows }); + } + for (const { branch, loc, rows } of plans) { + const res = appendRows(loc, rows); + if ('code' in res) { firstError ??= res; results.push({ branch, added: [], skipped: 0, file: loc.file, mirror: loc.mirror ?? null, error: res.message }); continue; } + if (res.mirrorError) firstError ??= res.mirrorError; + results.push({ branch, added: res.added.map(r => r.id), skipped: res.skipped, file: loc.file, mirror: loc.mirror ?? null, ...(res.mirrorError ? { error: res.mirrorError.message } : {}) }); + } + if (json) process.stdout.write(JSON.stringify({ branches: results }) + '\n'); + else { + for (const r of results) process.stdout.write(`APPROVAL_IMPORTED: branch=${r.branch} n=${r.added.length} skipped=${r.skipped} ${r.file}${r.mirror ? ` mirror=${r.mirror}` : ''}${r.error ? ` error=${r.error}` : ''}\n`); + process.stdout.write(`APPROVAL_IMPORTED_STACK: branches=${results.length} added=${results.reduce((n, r) => n + r.added.length, 0)}\n`); + } + return firstError ? fail(cmd, firstError) : EXIT.ok; +} + function main(argv: string[]): number { const [cmd, ...rest] = argv; if (!cmd || cmd === '--help' || cmd === '-h') { process.stdout.write(HELP + '\n'); return cmd ? EXIT.ok : EXIT.usage; } const { flags, bools, error } = parse(rest); if (error) { process.stderr.write(`gstack-approvals: ${error}\n${HELP}\n`); return EXIT.usage; } + if (flags['--stack'] !== undefined) return importStack(cmd, flags, bools.has('--json')); const loc = locate({ cwd: process.cwd(), env: process.env, branch: flags['--branch'] }); if ('code' in loc) return fail(cmd, loc); const json = bools.has('--json'); diff --git a/bin/gstack-autoplan b/bin/gstack-autoplan index 0b0a1c45b..c42062867 100755 --- a/bin/gstack-autoplan +++ b/bin/gstack-autoplan @@ -19,13 +19,14 @@ * gstack-autoplan release --out --attempt drop a reservation for an attempt that never ran * gstack-autoplan close --out --phase

--deferred "" --by > close a phase accepted-with-findings * gstack-autoplan budget --out

[--spend-cap ] [--max-rounds ] --by > the owner's journaled cap change + * gstack-autoplan check --out --attempt --result --model | --unavailable the delta check before a carry * gstack-autoplan checkpoints --from list checkpoint generations, newest first, with hash ok|bad * gstack-autoplan contract print the coordinator contract every lane prompt inherits (plan E2) * * Logic: lib/autoplan-run.ts (next/submit/resume), lib/autoplan-gate.ts (close, gate, answer), * lib/autoplan-export.ts, lib/autoplan-prompts.ts, lib/spend-ledger.ts. Codes: lib/result-codes.ts. * Workflow commands end with GSTACK_RESULT: skill=autoplan status= run=; the run is never approved here. - * Mutating verbs (next, submit, answer, recommend, revise, close, budget, export, run) pass admission first (lib/autoplan-admission.ts) + * Mutating verbs (next, submit, answer, recommend, revise, close, budget, check, export, run) pass admission first (lib/autoplan-admission.ts) * and bring an older run directory forward (lib/autoplan-migrate.ts) under the run lock. */ import * as fs from 'node:fs'; @@ -33,6 +34,7 @@ import * as path from 'node:path'; import { amendmentSteps, answerGate, closeDeferred, finishGate, recommendGate } from '../lib/autoplan-gate'; import { gateCost, gateCostPayload, renderGateCost, type GateCost } from '../lib/autoplan-gate-cost'; import { attemptEstimate, changeBudget, escalateLine, liftStop } from '../lib/autoplan-budget'; +import { DEFAULT_CARRY_CHECK_CAP_USD, carryLines, submitCarryCheck } from '../lib/autoplan-carry'; import { ANSWERED_BY_RE } from '../lib/gate-list'; import { checkpointLines, checkpointRun, restoreCheckpoint, type CheckpointMoment } from '../lib/autoplan-checkpoint'; import { admit, touchInstallLease } from '../lib/autoplan-admission'; @@ -60,6 +62,9 @@ DRIVER: ${driverFile()} --estimate-usd: reserved per new attempt; unattended Capy runs reserve a default for host attempts so --spend-cap binds --scaffold (first next): a plan missing one of its two sections is reviewed from /plan-source.md with the heading added --light loads each phase's checklist plus the sections its scope needs (the unattended default); interactive kinds load everything + --no-carry-forward (first next): every later gate revision goes to the owner, even one that asks nothing new + --carry-check-cap (first next): the most one delta check may reserve before a carry (default ${DEFAULT_CARRY_CHECK_CAP_USD.toFixed(2)}) + the first next prints REVIEW_ESTIMATE: the most the review can reserve at this scope and round cap prepare the current phase; one ATTEMPT: line per voice; ends awaiting_result submit --out --phase

--voice native|outside --result | --record [--attest ] --model [--attempt ] [--runner ] [--usage-usd ] [--reconcile ] [--json] @@ -84,6 +89,9 @@ DRIVER: ${driverFile()} resume --out

[--from ] [--json] --from restores a hash-verified checkpoint into an empty --out first (a collection or root restores its newest valid generation; GSTACK_AUTOPLAN_CHECKPOINT_DIR set: every command leaving the run at rest publishes a generation under // and prints CHECKPOINT: on stderr) + check --out --attempt --result --model [--same-family ""] | --unavailable "" + bind the one-reviewer delta check a CARRY_CHECK: line asked for: nothing at High or above carries the owner's + last answer (CARRIED:); otherwise, or when unavailable, the gate goes to the owner as before checkpoints --from list checkpoint generations, newest first: run, gate_rev, time, hash ok|bad, current close --out --phase

--deferred "" --by > close the phase accepted-with-findings: open voices skipped (dispatched attempts settle unknown at their @@ -180,7 +188,10 @@ function doNext(out: string, rest: string[], json: boolean): number { const ui = rest.includes('--ui') ? true : rest.includes('--no-ui') ? false : undefined; const maxRounds = num(rest, '--max-rounds'); if (maxRounds !== undefined && (!Number.isInteger(maxRounds) || maxRounds < 1)) throw new RunError('ARTIFACT_SCHEMA', '--max-rounds needs an integer >= 1', 1); + const carryCheckCapUsd = num(rest, '--carry-check-cap'); + if (carryCheckCapUsd !== undefined && !(carryCheckCapUsd >= 0)) throw new RunError('ARTIFACT_SCHEMA', '--carry-check-cap needs a number >= 0', 1); initRun({ plan, out, cwd, planHeading: flag(rest, '--plan-heading'), outsideEnabled: !rest.includes('--no-outside'), spendCap: num(rest, '--spend-cap') ?? null, maxRounds, + carryForward: !rest.includes('--no-carry-forward'), carryCheckCapUsd, deadlineMin: num(rest, '--deadline'), light: rest.includes('--light'), scaffold: rest.includes('--scaffold'), scope: { ui, developerTool: rest.includes('--developer-tool'), agentPrimary: rest.includes('--agent-primary'), dx: rest.includes('--no-dx') ? false : undefined, ...(rest.includes('--docs-only') ? { docsOnly: true } : {}) } }, initLines); } const redispatch = rest.flatMap((a, i) => (a === '--redispatch' && rest[i + 1] ? [rest[i + 1]!] : [])); @@ -257,7 +268,7 @@ function doClose(out: string, rest: string[], json: boolean): number { const r = closeDeferred(state, phase as Phase, { reason: reason.trim(), by, cause: 'owner' }); moment = 'transition'; const lines = [...r.lines, ...(stopped ? liftStop(state, `${phase} closed deferred by ${by}`) : [])]; - if (!currentPhase(state)) { finishGate(state); lines.push(...gateLines(state, out)); } + if (!currentPhase(state)) { finishGate(state); lines.push(...carryLines(state), ...(state.status === 'gate_pending' ? gateLines(state, out) : [])); } else { state.status = 'running'; lines.push(`NEXT: gstack-autoplan next --out ${out}`); } writeState(state); lines.push(resultLineFor(state.status, out)); @@ -265,6 +276,19 @@ function doClose(out: string, rest: string[], json: boolean): number { return EXIT.ok; } +/** `check`: the delta reviewer's verdict before a carry (lib/autoplan-carry.ts). */ +function doCheck(out: string, rest: string[], json: boolean): number { + const unavailable = flag(rest, '--unavailable'); + const result = flag(rest, '--result'); + if (unavailable === undefined && (!result || !flag(rest, '--model'))) return usage('check needs --attempt and --result --model , or --unavailable ""'); + const r = submitCarryCheck({ out, attempt: flag(rest, '--attempt'), result: result ? path.resolve(result) : undefined, model: flag(rest, '--model'), unavailable, sameFamily: flag(rest, '--same-family') }); + moment = 'transition'; + const status = r.state.status; + const lines = [...r.lines, ...(status === 'gate_pending' ? gateLines(r.state, out) : []), ...(status === 'amend_pending' || status === 'running' ? [nextLine(r.state, out)] : []), resultLineFor(status, out)]; + emit(json, lines, { run: r.state.run, status, gate_rev: r.state.gate_rev ?? null, carry: r.state.carry ?? null, out }); + return EXIT.ok; +} + function doBudget(out: string, rest: string[], json: boolean): number { const state = readState(out); const lines = changeBudget(state, { spendCap: num(rest, '--spend-cap'), maxRounds: num(rest, '--max-rounds'), by: flag(rest, '--by') }); @@ -338,6 +362,7 @@ async function main(argv: string[]): Promise { if (cmd === 'revise') return mutating(out, json, () => doRevise(out, rest, json)); if (cmd === 'close') return mutating(out, json, () => doClose(out, rest, json)); if (cmd === 'budget') return mutating(out, json, () => doBudget(out, rest, json)); + if (cmd === 'check') return mutating(out, json, () => doCheck(out, rest, json)); if (cmd === 'run') { const admission = admit(process.env); if (admission.lines.length) process.stdout.write(admission.lines.join('\n') + '\n'); return await doRun(out, rest, json); } if (cmd === 'status') { const state = readState(out); @@ -416,7 +441,7 @@ async function main(argv: string[]): Promise { if (e instanceof RunError) { process.stderr.write(resultLine(`gstack-autoplan ${cmd}`, e.code, e.detail) + '\n'); if (e.after.lines?.length) process.stdout.write(e.after.lines.join('\n') + '\n'); - if (['next', 'submit', 'answer', 'resume', 'run', 'revise', 'recommend', 'close', 'budget'].includes(cmd)) process.stdout.write(resultLineFor(e.after.status ?? 'refused', out) + '\n'); + if (['next', 'submit', 'answer', 'resume', 'run', 'revise', 'recommend', 'close', 'budget', 'check'].includes(cmd)) process.stdout.write(resultLineFor(e.after.status ?? 'refused', out) + '\n'); return e.exit === 3 ? EXIT.refused : EXIT.fail; } process.stderr.write(`gstack-autoplan ${cmd}: ${e?.message ?? e}\n`); diff --git a/bin/gstack-capy-session b/bin/gstack-capy-session index 4296bdec8..3df25b12e 100755 --- a/bin/gstack-capy-session +++ b/bin/gstack-capy-session @@ -23,7 +23,13 @@ # applies: dirty, diverged, pinned, Bun hold, a live workflow lease) and on # success re-execs the NEW checkout's copy of this script with the same # arguments (GSTACK_CAPY_SELF_UPGRADED=1 stops a second attempt) before the -# installer runs. Lines: `SELF_UPGRADE: done -> ` | `skipped ()` +# installer runs. A live lease under 120 minutes old (the lease prune window) +# held by this session's own process chain also skips it (#3571): +# gstack-upgrade never counts the caller's own session, but an install run from +# inside a workflow (/ship's docs step) must not change gstack under it. The age +# bound matters on Capy, where the leased harness pid is the machine's +# long-lived capy-server and a live lease alone would never end the deferral; +# each gstack-skill-start renews it (UPGRADE_BUSY; GSTACK_UPGRADE_FORCE=1 overrides). Lines: `SELF_UPGRADE: done -> ` | `skipped ()` # | `none (current)` | `disabled ()`. # --check never moves the checkout; behind origin it prints @@ -107,6 +113,18 @@ elif [ "${GSTACK_CAPY_SELF_UPGRADED:-}" != 1 ]; then elif ! behind; then echo "SELF_UPGRADE: none (current)" elif [ ! -x "$ROOT/bin/gstack-upgrade" ]; then echo "SELF_UPGRADE: skipped ($ROOT/bin/gstack-upgrade is missing)"; report_behind "$RERUN" export GSTACK_CAPY_BEHIND_BLOCKED="$ROOT/bin/gstack-upgrade is missing; fix: $RERUN (UPGRADE_REFUSED)" + elif [ "${GSTACK_UPGRADE_FORCE:-}" != 1 ] && [ -x "$ROOT/bin/gstack-lease" ] \ + && OWN=$("$ROOT/bin/gstack-lease" live --root "$ROOT" 2>/dev/null | awk '{ a = $2; sub(/m$/, "", a); if (a + 0 < 120) print }') \ + && [ -n "$OWN" ] \ + && ! "$ROOT/bin/gstack-lease" live --root "$ROOT" --exclude-ancestry-of $$ >/dev/null 2>&1; then + HOLDERS="" + while read -r _pid _age; do HOLDERS="$HOLDERS${HOLDERS:+, }pid $_pid ($_age)"; done </dev/null) UP_OUT=$("$ROOT/bin/gstack-upgrade" --ff-only-no-reinstall 2>&1); UP_RC=$? diff --git a/bin/gstack-decision-trail b/bin/gstack-decision-trail index 297c6aee4..750b00da8 100755 --- a/bin/gstack-decision-trail +++ b/bin/gstack-decision-trail @@ -17,7 +17,8 @@ * and a cell whose first byte a spreadsheet would run as a formula (=, +, -, @) * gets a leading apostrophe, so evidence taken from PR titles, filenames or * generated text cannot execute when a reviewer opens the file. License text: - * licenses/MIT-pstack.txt; NOTICE.md carries the entry. + * licenses/MIT-pstack.txt; NOTICE.md carries the entry. The append rules live in + * lib/decision-trail.ts, shared with the autoplan runner. * * The start-row rule is gstack's mechanisation of the same skill's prose: a run * (one agent conversation, with its later turns) that writes to a trail already @@ -26,11 +27,8 @@ * id, and an append with `--run ` refuses until that run's start row is the * newest start row in the file (DECISION_TRAIL_START_REQUIRED, exit 3). */ -import * as fs from "node:fs"; -import * as path from "node:path"; +import { appendTrailRow as appendRow, readTrailRows as readRows, type TrailRow as Row } from "../lib/decision-trail"; -const COLUMNS = ["ts", "phase", "decision", "why", "evidence", "result"] as const; -const HEADER = COLUMNS.join("\t") + "\n"; const USAGE = `Usage: gstack-decision-trail [--run ] gstack-decision-trail start @@ -56,58 +54,6 @@ letters, digits and . _ : @ / - (a Capy jam_ id, a session id, a PR number). when the trail has rows and the newest start row is another run's. `; -type Row = { line: number; cells: string[] }; - -function clean(cell: string): string { - const flat = cell.replace(/[\t\n\r]/g, " "); - return /^[=+\-@]/.test(flat) ? `'${flat}` : flat; -} - -function readRows(file: string): Row[] { - if (!fs.existsSync(file)) return []; - const lines = fs.readFileSync(file, "utf8").split("\n"); - const rows: Row[] = []; - lines.forEach((raw, i) => { - let text = raw.endsWith("\r") ? raw.slice(0, -1) : raw; - if (i === 0 && text.startsWith("\uFEFF")) text = text.slice(1); - // A repeated header (the append-on-flaky-mount case) is never a row. - if (text === "" || text === HEADER.trimEnd()) return; - rows.push({ line: i + 1, cells: text.split("\t") }); - }); - return rows; -} - -function appendRow(file: string, cells: readonly string[]): number { - const dir = path.dirname(file); - if (dir && dir !== "." && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true }); - // Append the header too, never truncate: on a flaky mount the worst case is - // one stray header line, not lost rows. - // A file with no header line anywhere (empty, blank, or rows written by hand) - // gets one appended once; readRows skips a header line wherever it sits. - const size = fs.existsSync(file) ? fs.statSync(file).size : 0; - if (size > 0 && !endsWithNewline(file, size)) fs.appendFileSync(file, "\n"); - if (size === 0 || !hasHeader(file)) fs.appendFileSync(file, HEADER); - const ts = new Date().toISOString().replace(/\.\d{3}Z$/, "Z"); - fs.appendFileSync(file, [ts, ...cells.map(clean)].join("\t") + "\n"); - return readRows(file).length; -} - -function hasHeader(file: string): boolean { - return fs.readFileSync(file, "utf8").replace(/^\uFEFF/, "").split("\n") - .some(line => line.replace(/\r$/, "") === HEADER.trimEnd()); -} - -function endsWithNewline(file: string, size: number): boolean { - const fd = fs.openSync(file, "r"); - try { - const last = Buffer.alloc(1); - fs.readSync(fd, last, 0, 1, size - 1); - return last[0] === 0x0a; - } finally { - fs.closeSync(fd); - } -} - const RUN_ID = /^[A-Za-z0-9._:@/-]+$/; function checkRunId(runId: string): void { if (!RUN_ID.test(runId)) fail(`run id must match ${RUN_ID} (letters, digits, . _ : @ / -), got ${JSON.stringify(runId)}`, 2); diff --git a/bin/gstack-doctor-components.sh b/bin/gstack-doctor-components.sh index dda793216..f3c867766 100644 --- a/bin/gstack-doctor-components.sh +++ b/bin/gstack-doctor-components.sh @@ -332,6 +332,13 @@ gstack_result_anchor() { PROJECT_FLOOR_UNMET) printf '%s' 'project-floor-unmet' ;; PROJECT_NODE_PIN_UNMET) printf '%s' 'project-node-pin-unmet' ;; UPGRADE_SKIPPED) printf '%s' 'upgrade-skipped' ;; + BUDGET_CAP_REACHED) printf '%s' 'budget-cap-reached' ;; + BUDGET_READING_MISSING) printf '%s' 'budget-reading-missing' ;; + BUDGET_READING_REJECTED) printf '%s' 'budget-reading-rejected' ;; + BUDGET_METER_UNAVAILABLE) printf '%s' 'budget-meter-unavailable' ;; + BUDGET_LEDGER_INVALID) printf '%s' 'budget-ledger-invalid' ;; + BUDGET_CHECK_SKIPPED) printf '%s' 'budget-check-skipped' ;; + HANDOFF_PIN_MOVED) printf '%s' 'handoff-pin-moved' ;; *) return 1 ;; esac } diff --git a/bin/gstack-harness b/bin/gstack-harness index 5bb446904..5bd39f320 100755 --- a/bin/gstack-harness +++ b/bin/gstack-harness @@ -8,7 +8,10 @@ * * Usage: * gstack-harness detect [--json] - * gstack-harness register [--skills router|all] [--skills-dir

] [--context ] [--print] [--yes] [--no-registry] + * gstack-harness register [--skills router|hybrid|all] [--skills-dir ] [--context ] [--print] [--yes] [--no-registry] + * --context writes gstack's marked routing block into that file only + * (opt-in: setup, upgrades and refresh never add one, and a block you + * delete stays deleted); it prints the file and its scope before writing * gstack-harness unregister [--remote] * gstack-harness status [--json] [--no-check] * gstack-harness refresh @@ -20,7 +23,7 @@ import * as os from 'node:os'; import * as path from 'node:path'; import { resolveStateRoot } from '../lib/state-root'; import { - HarnessError, TARGETS, detect, getTarget, harnessSees, listLedgers, printPayload, refresh, register, sourceSkills, status, unregister, + HarnessError, TARGETS, contextScope, detect, getTarget, harnessSees, listLedgers, printPayload, refresh, register, sourceSkills, status, unregister, type RegisterResult, type SkillsMode, type TargetName, } from '../lib/harness-register'; import { registerQm, removeQmPack } from '../lib/harness-qm'; @@ -38,9 +41,10 @@ const self = path.join(checkout, 'bin', 'gstack-harness'); function receiptLines(r: RegisterResult): string[] { const t = TARGETS[r.target]; + const how = { router: 'reachable through one router skill', hybrid: 'registered, the task skills listed directly and the rest through one router skill', all: 'registered' }[r.mode]; return [ - 'gstack-harness: ' + t.displayName + ': ' + r.skills + ' gstack skills ' + (r.mode === 'router' ? 'reachable through one router skill' : 'registered') + ' at ' + r.dest + ' (' + r.status + (r.written ? ', ' + r.written + ' files written' : '') + ')', - ...(r.router ? [' router: ' + r.router + (r.mode === 'router' ? ' (register with --skills all to list every skill natively)' : '')] : []), + 'gstack-harness: ' + t.displayName + ': ' + r.skills + ' gstack skills ' + how + ' at ' + r.dest + ' (' + r.status + (r.written ? ', ' + r.written + ' files written' : '') + ')', + ...(r.router ? [' router: ' + r.router + ' (register with --skills all to list every skill natively)'] : []), ...r.kept.map(k => ' kept your edit: ' + k), ' ledger: ' + r.ledger, ' remove: ' + self + ' unregister ' + r.id, @@ -83,6 +87,7 @@ async function main(): Promise { console.log('gstack-harness: ' + t.displayName + ': unverified (' + (seen.checked ? seen.checked + ' did not list gstack' : t.name + ' is not on PATH') + '). Install gstack for Claude Code (./setup), or paste the block from: ' + self + ' register generic --print'); return 3; } + if (context) (json ? console.error : console.log)('gstack-harness: context block: ' + path.resolve(context) + ' (' + contextScope(t, context, env, home) + ' scope)'); const r = register({ ...base, target: t, mode, skillsDir, context, registry: !noRegistry }); if (json) console.log(JSON.stringify({ ...r, receipt: receiptLines(r).map(l => l.trim()).join('; ') })); else receipt(r); diff --git a/bin/gstack-harness-ledger.sh b/bin/gstack-harness-ledger.sh index 85a6d6c47..210e85326 100644 --- a/bin/gstack-harness-ledger.sh +++ b/bin/gstack-harness-ledger.sh @@ -13,8 +13,11 @@ # uninstall of the state root and the checkout. Only paths below the recorded # destination, reached through no symlink, are touched. A context block is cut # only when its file holds exactly one whole-line begin/end marker pair whose -# lines hash to the ledger's block hash; otherwise the file is left as it is -# (the file is removed only when nothing else is left in it). Folders gstack +# lines hash to the ledger's block hash; otherwise the file is left as it is. +# Its blockpad row says what gstack added before the block, so the cut restores +# the file byte for byte: the blank line (and newline) it appended are removed +# too, and a file gstack created is removed when nothing else is left in it +# (ledgers without the row: when only whitespace is left). Folders gstack # created are removed only when empty. A QM pack is never touched here: detaching it from # the org is `gstack-harness unregister qm --remote`. @@ -33,7 +36,7 @@ _gstack_harness_owned() { } _gstack_harness_cut_block() { - local file="$1" want="$2" span s e tmp + local file="$1" want="$2" pad="${3:-}" span s e tmp local begin='' end='' { [ -f "$file" ] && [ ! -L "$file" ]; } || return 0 span="$(awk -v B="$begin" -v E="$end" '$0 == B { nb++; s = NR } $0 == E { ne++; e = NR } END { if (nb == 1 && ne == 1 && e > s) print s, e; else if (nb || ne) print "bad" }' "$file")" @@ -44,13 +47,18 @@ _gstack_harness_cut_block() { return 0 fi tmp="$file.gstack-cut.$$" - awk -v s="$s" -v e="$e" 'NR < s || NR > e' "$file" > "$tmp" || { rm -f "$tmp"; return 1; } - if [ -z "$(tr -d '[:space:]' < "$tmp")" ]; then rm -f "$file"; else cat "$tmp" > "$file"; fi + awk -v s="$s" -v e="$e" -v pad="$pad" '{ line[NR] = $0 } + END { + from = s; if ((pad == "1" || pad == "2") && s > 1 && line[s - 1] == "") from = s - 1 + n = 0; for (i = 1; i <= NR; i++) if (i < from || i > e) out[++n] = line[i] + for (i = 1; i <= n; i++) { printf "%s", out[i]; if (i < n || !(pad == "2" && e == NR)) printf "\n" } + }' "$file" > "$tmp" || { rm -f "$tmp"; return 1; } + if { [ "$pad" = new ] && [ ! -s "$tmp" ]; } || { [ -z "$pad" ] && [ -z "$(tr -d '[:space:]' < "$tmp")" ]; }; then rm -f "$file"; else cat "$tmp" > "$file"; fi rm -f "$tmp" } gstack_harness_unregister_ledger() { - local ledger="$1" stamp kind a b target="" dest="" pack="" + local ledger="$1" stamp kind a b target="" dest="" pack="" pad="" padpath="" : "${GSTACK_STATE_ROOT:?gstack-harness-ledger: GSTACK_STATE_ROOT is not set}" [ -f "$ledger" ] || return 0 stamp="$(date -u +%Y-%m-%dT%H-%M-%SZ)" @@ -61,7 +69,8 @@ gstack_harness_unregister_ledger() { { [ -f "$b" ] && _gstack_harness_owned "$b" "$dest"; } || continue if [ "$(_gstack_harness_sha "$b")" = "$a" ]; then rm -f "$b" else mv "$b" "$b.edited-$stamp" && echo " kept your edit: $b.edited-$stamp"; fi ;; - block) _gstack_harness_cut_block "$b" "$a" ;; + blockpad) pad="$a"; padpath="$b" ;; + block) if [ "$padpath" = "$b" ]; then _gstack_harness_cut_block "$b" "$a" "$pad"; else _gstack_harness_cut_block "$b" "$a"; fi ;; esac done < "$ledger" while IFS=$'\t' read -r kind a b; do diff --git a/bin/gstack-review-log b/bin/gstack-review-log index b60832497..0a7037120 100755 --- a/bin/gstack-review-log +++ b/bin/gstack-review-log @@ -3,6 +3,10 @@ # Usage: gstack-review-log '{"skill":"...","timestamp":"...","status":"..."}' # # Before reading a diff: gstack-review-log --start review +# Under a /ship token cap (docs/ship-budget.md): --start SKILL --reservation ID +# with the RESERVATION id gstack-ship-budget check printed for this dispatch +# batch; refuses (exit 1, BUDGET_CHECK_SKIPPED) without an unspent one, and +# --finish settles it. Without a cap no marker exists and nothing changes. # Fix-range repeat (#3339): gstack-review-log --start review --fix-range # prints the token, then FIX_BASE=; refuses (exit 1) unless the latest # pass completed with fixes on unchanged content and its commit is an @@ -32,15 +36,18 @@ export GSTACK_REVIEW_DIR="$GSTACK_HOME/projects/$SLUG" export GSTACK_REVIEW_REPO="$(git rev-parse --show-toplevel 2>/dev/null || true)" export GSTACK_REVIEW_BRANCH="$(git symbolic-ref --short HEAD 2>/dev/null || git rev-parse HEAD 2>/dev/null || true)" export GSTACK_REVIEW_LIB="$SCRIPT_DIR/../lib/review-evidence.ts" +export GSTACK_SHIP_BUDGET_LIB="$SCRIPT_DIR/../lib/ship-budget.ts" case "$(uname -s)" in MINGW*|MSYS*|CYGWIN*) if command -v cygpath >/dev/null 2>&1; then GSTACK_REVIEW_LIB="$(cygpath -m "$GSTACK_REVIEW_LIB")" + GSTACK_SHIP_BUDGET_LIB="$(cygpath -m "$GSTACK_SHIP_BUDGET_LIB")" GSTACK_REVIEW_DIR="$(cygpath -m "$GSTACK_REVIEW_DIR")" fi ;; esac export GSTACK_REVIEW_LOG="$GSTACK_REVIEW_DIR/$BRANCH-reviews.jsonl" +export GSTACK_SHIP_BUDGET_MARKER="$GSTACK_REVIEW_DIR/$BRANCH-ship-budget.json" # Compute binding fields (best-effort; empty outside a git repo). COMMIT_FULL=$(git rev-parse HEAD 2>/dev/null || true) @@ -77,10 +84,28 @@ fi SESSION_KIND=$("$SCRIPT_DIR/gstack-session-kind" 2>/dev/null || echo interactive) export GSTACK_STAMP_COMMIT_FULL="$COMMIT_FULL" GSTACK_STAMP_TREE="$TREE" GSTACK_STAMP_WTREE="$WTREE" GSTACK_STAMP_DIRTY="$DIRTY" GSTACK_STAMP_SESSION_KIND="$SESSION_KIND" if [ "$INPUT" = --start ]; then - case "${3:-}" in ''|--fix-range) ;; *) echo 'Usage: gstack-review-log --start SKILL [--fix-range]' >&2; exit 2 ;; esac - GSTACK_REVIEW_SKILL="${2:-}" GSTACK_REVIEW_FIX_RANGE="${3:-}" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e ' + START_SKILL="${2:-}" START_FIX="" START_RESERVATION="" + if [ "$#" -ge 2 ]; then shift 2; else shift "$#"; fi + while [ "$#" -gt 0 ]; do + case "$1" in + --fix-range) START_FIX=--fix-range; shift ;; + --reservation) [ "$#" -ge 2 ] || { echo 'Usage: gstack-review-log --start SKILL [--fix-range] [--reservation ID]' >&2; exit 2; }; START_RESERVATION="$2"; shift 2 ;; + *) echo 'Usage: gstack-review-log --start SKILL [--fix-range] [--reservation ID]' >&2; exit 2 ;; + esac + done + if [ ! -f "$GSTACK_SHIP_BUDGET_MARKER" ]; then + GSTACK_REVIEW_SKILL="$START_SKILL" GSTACK_REVIEW_FIX_RANGE="$START_FIX" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e ' + const { captureReviewStart } = await import(process.env.GSTACK_REVIEW_LIB); + try { console.log(captureReviewStart(process.env.GSTACK_REVIEW_SKILL, process.env, process.env.GSTACK_REVIEW_FIX_RANGE === "--fix-range")); } + catch (e) { console.error(e.message); process.exit(1); } + ' + exit $? + fi + GSTACK_REVIEW_SKILL="$START_SKILL" GSTACK_REVIEW_FIX_RANGE="$START_FIX" GSTACK_REVIEW_RESERVATION="$START_RESERVATION" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e ' const { captureReviewStart } = await import(process.env.GSTACK_REVIEW_LIB); - try { console.log(captureReviewStart(process.env.GSTACK_REVIEW_SKILL, process.env, process.env.GSTACK_REVIEW_FIX_RANGE === "--fix-range")); } + const { admitReviewStart } = await import(process.env.GSTACK_SHIP_BUDGET_LIB); + const capture = () => captureReviewStart(process.env.GSTACK_REVIEW_SKILL, process.env, process.env.GSTACK_REVIEW_FIX_RANGE === "--fix-range"); + try { console.log(admitReviewStart(process.env.GSTACK_SHIP_BUDGET_MARKER, process.env.GSTACK_REVIEW_RESERVATION || undefined, capture)); } catch (e) { console.error(e.message); process.exit(1); } ' exit $? @@ -93,7 +118,7 @@ if [ "$INPUT" = --check-shared-libs ] && [ "$#" -eq 2 ]; then exit $? fi usage() { - echo 'Usage: gstack-review-log JSON [--finish TOKEN] [--findings FILE] | --start SKILL [--fix-range] | --check-shared-libs TOKEN < finding.json' >&2 + echo 'Usage: gstack-review-log JSON [--finish TOKEN] [--findings FILE] | --start SKILL [--fix-range] [--reservation ID] | --check-shared-libs TOKEN < finding.json' >&2 echo 'Exit codes: 0 written · 1 rejected · 2 usage' >&2 exit 2 } @@ -126,6 +151,16 @@ try { echo "$STAMPED" >> "$GSTACK_HOME/projects/$SLUG/$BRANCH-reviews.jsonl" +# A finished dispatch settles the budget reservation its start consumed (its +# completion receipt); stdout stays unchanged and a failure never undoes the row. +if [ -n "$TOKEN" ] && [ -f "$GSTACK_SHIP_BUDGET_MARKER" ]; then + GSTACK_REVIEW_TOKEN="$TOKEN" bun --no-env-file --config="${GSTACK_BUN_CONFIG:-/dev/null}" -e ' + const { settleReviewFinish } = await import(process.env.GSTACK_SHIP_BUDGET_LIB); + try { const id = settleReviewFinish(process.env.GSTACK_SHIP_BUDGET_MARKER, process.env.GSTACK_REVIEW_TOKEN); if (id) console.error("review-log: settled budget reservation " + id); } + catch (e) { console.error("review-log: budget reservation not settled: " + e.message); } + ' || true +fi + # gbrain-sync: enqueue for cross-machine sync (no-op if sync is off). Plan B1: # an unattended session never enqueues, whatever the inherited sync mode. if [ "$("$SCRIPT_DIR/gstack-session-kind" 2>/dev/null || echo interactive)" = "unattended" ]; then diff --git a/bin/gstack-ship-budget b/bin/gstack-ship-budget new file mode 100755 index 000000000..ecb3277dc --- /dev/null +++ b/bin/gstack-ship-budget @@ -0,0 +1,50 @@ +#!/usr/bin/env -S bun --no-env-file --config=/dev/null +/** + * gstack-ship-budget — the /ship token budget and fresh-context handoff + * (docs/ship-budget.md). An admission cap: no step or dispatch starts unless + * used + open reservations + unknown + its projection + the tail and stop + * reserve fit under the cap. + * + * start --record [--token-cap ] [--meter capy|claude|estimate] [--reading ] [--prior-reading ] + * [--session |--nonce ] [--reserve ] [--delegate auto|never] [--calibration ] [--ledger ] + * check --run |--record --step --next [,...]> [--reading ] [--prior-reading ] + * settle --run|--record --reservation [--unknown] release --run|--record --reservation + * handoff --run|--record --from --to --base origin/ [--reviewed-tree ] [--trail --trail-run ] + * [--sub-cap ] [--reading ] [--child-session ] + * launch --in (Claude Code: background headless child with explicit permissions) + * verify-handoff --in [--reading ] [--session ] + * return --run --to [--changed ] [--status complete|refused|incomplete] [--reading ] + * reconcile --run|--record (--return |--handoff ) [--reading ] + * resume --record |--run [--reading ] [--meter ] [--session ] [--token-cap --approved-by --words ] + * [--rebuild-from-record] + * close --run|--record [--reading ] [--approved-by --words ] + * + * Exit: 0 continue/delegate · 3 stop (the next step does not start) · 2 usage + * or validation (stderr). Logic: lib/ship-budget.ts, lib/ship-budget-cli.ts, + * lib/ship-handoff.ts. + */ +import { BudgetError } from '../lib/ship-budget'; +import { cmdCheck, cmdClose, cmdResume, cmdSettle, cmdStart, type Outcome } from '../lib/ship-budget-cli'; +import { cmdHandoff, cmdLaunch, cmdReconcile, cmdReturn, cmdVerifyHandoff } from '../lib/ship-handoff'; + +const [command, ...rest] = process.argv.slice(2); +const ctx = { env: process.env, cwd: process.cwd() }; +const commands: Record Outcome> = { + start: () => cmdStart(rest, ctx), check: () => cmdCheck(rest, ctx), settle: () => cmdSettle(rest, ctx), release: () => cmdSettle(rest, ctx, true), + handoff: () => cmdHandoff(rest, ctx), launch: () => cmdLaunch(rest, ctx), 'verify-handoff': () => cmdVerifyHandoff(rest, ctx), return: () => cmdReturn(rest, ctx), + reconcile: () => cmdReconcile(rest, ctx), resume: () => cmdResume(rest, ctx), close: () => cmdClose(rest, ctx), +}; +if (!command || command === '--help' || command === '-h' || !commands[command]) { + const text = (await Bun.file(import.meta.path).text()).split('\n').slice(2, 26).map(l => l.replace(/^ \* ?/, '')).join('\n'); + (command && command !== '--help' && command !== '-h' ? console.error : console.log)(text); + process.exit(command && command !== '--help' && command !== '-h' ? 2 : 0); +} +try { + const out = commands[command]!(); + if (out.stdout.length) console.log(out.stdout.join('\n')); + process.exit(out.exit); +} catch (e) { + if (!(e instanceof BudgetError)) throw e; + if (e.exit === 3) console.log(e.message); else console.error(e.message); + process.exit(e.exit); +} diff --git a/bin/gstack-ship-receipt b/bin/gstack-ship-receipt index 6d50425b1..1b24fd1af 100755 --- a/bin/gstack-ship-receipt +++ b/bin/gstack-ship-receipt @@ -547,6 +547,8 @@ function cmdCarry(rest: string[], json: boolean): number { if (!headTree) return refused('RECEIPT_CARRY_REFUSED', `git could not read the tree of HEAD ${head.slice(0, 12)}`); const headPatch = productPatchAgainstBase(repoRoot, rules, baseRef, head); if (typeof headPatch !== 'string') return refused('RECEIPT_CARRY_REFUSED', `git could not compute HEAD's product patch-id: ${headPatch.error}`); + const reviewedBase = receipt.base.replace(/^origin\//, ''); + const retarget = reviewedBase !== base.replace(/^origin\//, ''); let plan: ReturnType; if (!ancestor) { // Rewritten history: the receipt follows only onto a tree it already covers, with the product diff it recorded. @@ -565,11 +567,25 @@ function cmdCarry(rest: string[], json: boolean): number { const testFrom = asId(patchId(repoRoot, fromBase, from, spec.tests)); const testHead = asId(patchId(repoRoot, headBase, head, spec.tests)); for (const r of [productFrom, productHead]) if (typeof r !== 'string') return refused('RECEIPT_CARRY_REFUSED', `git could not compute the product patch-id at one of the heads: ${r.error}`); - // planCarry names at most CARRY_NAMED_PATHS differing paths, so the per-path comparison (two patch-ids each) stops there, - // and it walks only the paths the branch itself touched against the base at either head: a base merge brings in every - // path the base changed, none of which can differ between the two base diffs. + // A stacked child whose parent landed on the base (#3570): the receipt reviewed the child's own range against the + // parent branch, and the PR now targets the base. That reviewed range (the recorded product patch-id, else the one + // against origin/ when it still resolves) must be HEAD's whole product diff against the base, computed + // the way write records it (headPatch): the parent fully landed and the child is unchanged. Anything else fails closed. + let reviewed = productFrom; + if (retarget) { + const parentRef = `origin/${reviewedBase}`; + const recorded = receipt.product_patch_id !== undefined ? (receipt.product_patch_id === 'none' ? '' : receipt.product_patch_id) + : git(['rev-parse', '--verify', '--quiet', `${parentRef}^{commit}`], repoRoot) ? productPatchAgainstBase(repoRoot, rules, parentRef, from) : { error: `the receipt records no product patch-id and ${parentRef} no longer resolves` }; + if (typeof recorded !== 'string') return refused('RECEIPT_CARRY_REFUSED', `the receipt was reviewed against ${reviewedBase}, not ${base}, and its reviewed product diff is unavailable: ${recorded.error}; run /ship on ${head.slice(0, 12)}`); + reviewed = recorded; + } + const current = retarget ? headPatch : productHead; const changedProduct: string[] = []; - if (productFrom !== productHead) { + if (retarget && reviewed !== current) changedProduct.push(`HEAD's product diff against ${base} is not the one reviewed against ${reviewedBase} (the parent has not fully landed on ${base}, or the branch changed since)`); + else if (productFrom !== productHead && !retarget) { + // planCarry names at most CARRY_NAMED_PATHS differing paths, so the per-path comparison (two patch-ids each) stops there, + // and it walks only the paths the branch itself touched against the base at either head: a base merge brings in every + // path the base changed, none of which can differ between the two base diffs. const touched = new Set([...(git(['diff', '--name-only', fromBase, from], repoRoot) ?? '').split('\n'), ...(git(['diff', '--name-only', headBase, head], repoRoot) ?? '').split('\n')].filter(Boolean)); for (const p of [...touched].sort()) { if (changedProduct.length >= CARRY_NAMED_PATHS) break; @@ -583,7 +599,7 @@ function cmdCarry(rest: string[], json: boolean): number { // Evidence for the record, never the decision: a slow range-diff is reported unavailable rather than waited for. const rangeRaw = spawnSync('git', ['range-diff', '--no-color', `${fromBase}..${from}`, `${headBase}..${head}`], { cwd: repoRoot, encoding: 'utf8', timeout: 15_000, maxBuffer: 64 * 1024 * 1024 }); const rangeDiff = rangeRaw.status === 0 ? (rangeRaw.stdout.trim().split('\n').slice(0, 20).join('\n') || '(empty: identical ranges)') : `unavailable: ${(rangeRaw.stderr ?? '').trim().split('\n')[0] || (rangeRaw.signal ? `range-diff killed by ${rangeRaw.signal} after 15 s` : 'range-diff failed')}`; - plan = planCarry({ from, head, changed, productPatchId: { from: productFrom, head: productHead }, testPatchId: { from: testFrom, head: testHead }, changedProduct, mergeCommits: Number(mergeCommits) || 0, rangeDiff }); + plan = planCarry({ from, head, changed, productPatchId: { from: reviewed as string, head: current as string }, testPatchId: { from: testFrom, head: testHead }, changedProduct, mergeCommits: Number(mergeCommits) || 0, rangeDiff, ...(retarget ? { retargetedFrom: reviewedBase } : {}) }); } if (!plan.ok) return refused(plan.code, plan.message); // Eligibility is not publication: a receipt that recorded a pregate is rebound only with a pregate current for HEAD, @@ -611,7 +627,9 @@ function cmdCarry(rest: string[], json: boolean): number { if (depthBelow(receipt.review_depth.depth, now.depth)) return refused('RECEIPT_CARRY_REFUSED', `HEAD ${head.slice(0, 12)} needs ${now.depth} review depth (${now.reasons.join(', ')}), above the receipt's ${receipt.review_depth.depth}; run /ship on ${head.slice(0, 12)}`); depthField = { review_depth: { ...now, depth: deeper(receipt.review_depth.depth, now.depth) } }; } - const carried = carryReceipt({ ...receipt, ...pregateField, ...depthField }, head, plan.carry, { tree: headTree, fromTree, productPatchId: headPatch }); + // The rebound product_patch_id is HEAD's diff against the carry's base, so a retargeted receipt names that base from now on. + const rebound = { ...receipt, ...(retarget ? { base: base.replace(/^origin\//, '') } : {}), ...(pregateField ?? {}), ...depthField }; + const carried = carryReceipt(rebound, head, plan.carry, { tree: headTree, fromTree, productPatchId: headPatch }); const errors = validateReceipt(carried); if (errors.length) return refused('RECEIPT_CARRY_REFUSED', `the carried receipt does not validate: ${errors[0]!.message} at ${errors[0]!.path}`); const newBody = placeReceiptFirst(body, carried); diff --git a/captain/templates/brief.md b/captain/templates/brief.md index d185bc0bf..1f6b0decb 100644 --- a/captain/templates/brief.md +++ b/captain/templates/brief.md @@ -14,7 +14,7 @@ Spend cap: 1. Plan (when Plan: required). After the session-start install check, install for autoplan and follow autoplan/DRIVER.md "On Capy" (launch file sourced, GSTACK_AUTOPLAN_CHECKPOINT_DIR - set, run dir under ~/.capy/work). Write the plan with its ## Before → after, + set, run dir under ~/.capy/work). Write the plan with its ## ELI5, ## Before → after, ## Why it matters, ## What caused this work, ## Big decisions and ## Implementation plan sections, then run gstack-autoplan next --out --plan sized to this brief (a one-file fix: --no-ui --no-dx --max-rounds 1 --estimate-usd @@ -25,7 +25,8 @@ Spend cap: (gstack-autoplan answer --out --gate-rev --reply --rec-hash --by agent: --owner-reply ""), incorporate every accepted plan change (revise), finish every reopened phase, and start product edits only when the run - reports APPROVED. Then gstack-approvals import --autoplan --by "". + reports APPROVED (a later gate that asks nothing new prints CARRIED: and needs no second + ask). Then gstack-approvals import --autoplan --by "" (--stack b1,b2 for a stack). New scope you take on part-way goes back to step 1 with its own plan. 3. Ship. CHANGELOG entry under [Unreleased]; GUARD_CHECKS, pregate and /ship at the final head; one unstamped READY block (captain/templates/READY.md) to me; the PR body carries diff --git a/captain/templates/plan-ask.md b/captain/templates/plan-ask.md index fb298017f..854998ffc 100644 --- a/captain/templates/plan-ask.md +++ b/captain/templates/plan-ask.md @@ -7,6 +7,9 @@ shape from an autoplan run; write it by hand for any other plan. ```text Decision needed on : . Reply **rec** to take every recommendation. +## ELI5 +<5-10 plain sentences: what changes, for whom, and what it costs> + ## Before → after diff --git a/capy/skill/gstack/SKILL.md b/capy/skill/gstack/SKILL.md index d0e793395..bb629e753 100644 --- a/capy/skill/gstack/SKILL.md +++ b/capy/skill/gstack/SKILL.md @@ -42,6 +42,8 @@ Run directories and scratch on Capy live under `~/.capy/work/` (`--out ~/. Capy checklist for `/autoplan`: drive `gstack-autoplan`, never a hand adaptation presented as a run. Relay `gstack-gate render /gate.json --all` with `rec` (every recommendation, plan changes included) as the one-word default; answer with `--by agent: --owner-reply ""`. Set `GSTACK_AUTOPLAN_CHECKPOINT_DIR` to a private project-user Drive folder; after machine replacement, `gstack-autoplan resume --out --from ` restores the newest valid checkpoint. +Token caps on /ship: pass a brief's cap as `--token-cap `. /ship reads `cost.tokens` from `tools.thread.get({ thread_id: "this" })` (one execute program returning only that number) into `gstack-ship-budget --reading ` and obeys `verdict=` (`docs/ship-budget.md`). + ## Plan, approve, ship Every Capy thread that uses gstack follows these for new work, under a Captain or on its own. The rule in full is `docs/captain.md`, "Plan before build"; the lane side is section 3 of captain.md in this folder. diff --git a/capy/skill/gstack/captain.md b/capy/skill/gstack/captain.md index d403cbe55..057573665 100644 --- a/capy/skill/gstack/captain.md +++ b/capy/skill/gstack/captain.md @@ -48,6 +48,7 @@ gstack-approvals add --ask "Spend up to \$40 on a paid eval rerun for the ship c gstack-approvals add --outcome standing --ask "Merge #3330 when green" \ --words "yes merge when green" --by "Garry, 2026-10-16 (Captain rule)" --scope "every crew PR, through a train" gstack-approvals import --autoplan --by Garry # after gstack-autoplan answer; idempotent +gstack-approvals import --autoplan --by Garry --stack b1,b2 # a stacked PR set: every branch, or none gstack-approvals render # the ## Approvals section ``` @@ -93,15 +94,15 @@ project can follow it: the plan names (docs, trains, cleanups) included, and carry them through to done with no further ask. Say in one line what it covers. For an autoplan gate, "do it" answers as `rec`; record the words. -For an autoplan run, write parts 1 to 4 as `## Before → after`, `## Why it matters`, -`## What caused this work` and `## Big decisions` sections in the plan. Then, at the gate: +For an autoplan run, open the plan with `## ELI5` (5-10 plain sentences), then write parts 1 to 4 as +`## Before → after`, `## Why it matters`, `## What caused this work` and `## Big decisions` sections. Then, at the gate: ```bash gstack-owner-brief render --captain --out ``` -It prints a header line ("Decision needed … Reply **rec** …"), the four plan sections (each capped, with a -pointer to the plan for the rest), and "What we need from you", which lists every choice `rec` takes, in +It prints a header line ("Decision needed … Reply **rec** …"), the `### ELI5` summary (on a run whose gate +carries `eli5`), the four plan sections (each capped, with a pointer to the plan for the rest), and "What we need from you", which lists every choice `rec` takes, in words, and closes with the "do it" reply, then a `### Cost` section (spent so far, worst case, and the estimate for the phases `rec` can reopen). The last line, "For the relaying agent", carries the run, `gate_rev`, `rec_hash` and the exact `gstack-autoplan answer` command. Relay everything above that line. When the reply comes back: @@ -112,6 +113,11 @@ gstack-autoplan answer --out --gate-rev --reply rec --rec-hash gstack-approvals import --autoplan --by ``` +A later gate that asks nothing new is answered for you with the words you recorded (`CARRIED:`, then `APPROVED:`); +the brief says "Nothing pending. Carried forward", so import and build without a second ask. `CARRY_CHECK:` means +one reviewer from another model family reads the unreviewed delta first (`gstack-autoplan check`). Anything +else prints `CARRY: no ()` and goes to the person as today (`docs/unattended.md#carry-forward`). + If the person answers in words ("split it into two PRs"), map the words to tokens, answer, and confirm in one line what you recorded ("Recorded: split into two PRs; everything else as recommended"). A plan missing a section renders "Not ready for approval" with no reply invitation, and exits 1 (`CAPTAIN_BRIEF_INCOMPLETE`): @@ -142,3 +148,8 @@ Every PR you send READY on, and the READY report itself, has: The READY report attaches the key image (Capy message attachment), so the Captain can show it inline. /ship does all of this when `GSTACK_CAPY=1` (its `capy-pr` section). Outside Capy, the PR body is unchanged. + +A token cap in a brief goes to /ship as `--token-cap `. When /ship stops on it (`STOP: +reason=budget_exhausted`, `status=incomplete`), the lane reports the BUDGET and RECOVER lines and asks the +owner; it never raises the cap itself. The owner's answer runs the RECOVER line with +`--approved-by --words ""`, and `gstack-approvals add` records the same words. diff --git a/docs/OPENCLAW.md b/docs/OPENCLAW.md index 325c8d72d..d376b873a 100644 --- a/docs/OPENCLAW.md +++ b/docs/OPENCLAW.md @@ -181,9 +181,10 @@ The agent should: 4. Verify with a test spawn **Native skills or ACP.** `./setup --host openclaw` (or `./setup` run inside an -OpenClaw session) gives OpenClaw's own agent gstack's skills: one `gstack` -router skill in `$OPENCLAW_STATE_DIR/skills`, rendered with OpenClaw's tool -names and pointing at the installed gstack, so the agent runs gstack's +OpenClaw session) gives OpenClaw's own agent gstack's skills: the five task +skills (review, investigate, qa, ship, plan-eng-review) listed directly and one +`gstack` router skill for the rest in `$OPENCLAW_STATE_DIR/skills`, rendered +with OpenClaw's tool names and pointing at the installed gstack, so the agent runs gstack's workflows and helpers itself. Use ACP when the work should happen in a Claude Code session with the full install (hooks, Claude tool names); use native skills when the OpenClaw agent should do it. Both can be installed together. diff --git a/docs/captain.md b/docs/captain.md index 7c0b7aadf..e955acfb7 100644 --- a/docs/captain.md +++ b/docs/captain.md @@ -138,8 +138,9 @@ this rule shipped cites this section by name. **What the lane sends.** The plan and its gate in plain language a person outside the project can follow: what changes, why now, what the change does, what it costs, the lane's pick, and the recommended one-word reply. `gstack-owner-brief render --captain --out ` -prints that from the plan's `## Before → after`, `## Why it matters`, -`## What caused this work` and `## Big decisions` sections, with the cost lines +prints that from the plan's `## ELI5`, `## Before → after`, `## Why it matters`, +`## What caused this work` and `## Big decisions` sections (also saved as `eli5` in +`gate.json`, so `gstack-gate render` opens with them), with the cost lines (`GATE_SPEND:`, `GATE_REC_COST:`) and a last line for the controller; a plan missing a section exits `CAPTAIN_BRIEF_INCOMPLETE`, so the lane adds the section and renders again ([capy/skill/gstack/captain.md](../capy/skill/gstack/captain.md) § 3 lists them). The lane @@ -156,10 +157,12 @@ controller and been answered into the run every accepted plan change has been incorporated (`revise`), every reopened phase has finished, and the run reports `APPROVED` (`status=complete` after `export`). An answered gate that still prints `PLAN_AMEND_PENDING` or `REOPENED:` is not a completed plan, and an -imported approval row alone is not completion. +imported approval row alone is not completion. A later gate revision that asks nothing new +is answered with the owner's recorded words and says `CARRIED:`; that is the owner's word, +not a new ask ([carry-forward](unattended.md#carry-forward)). -**The record.** `gstack-approvals import --autoplan --by ""` writes the -approval row (date, the ask, the owner's exact words, the lane that answered as relayer, +**The record.** `gstack-approvals import --autoplan --by ""` (with +`--stack ` for a stacked PR set) writes the approval row (date, the ask, the owner's exact words, the lane that answered as relayer, what it covers); `gstack-approvals render` puts it in the report and the PR body. Before training the PR the controller compares that row's words and `gate_rev` with the ask it relayed and the reply it carried back; a row that does not match is not READY (shape A). diff --git a/docs/capy-install.md b/docs/capy-install.md index f98f87d6e..7de24710e 100644 --- a/docs/capy-install.md +++ b/docs/capy-install.md @@ -155,7 +155,16 @@ and `/proc` start time; elsewhere `ps -o lstart`), because a pid is reused after a reboot or a machine wake. `bin/gstack-upgrade`, and so the session-start self-upgrade, refuses with [UPGRADE_BUSY](troubleshooting.md#upgrade-busy) while a lease held by a live process outside its own chain exists, naming each -holder as `pid

(m )`. The team-mode SessionStart hook +holder as `pid

(m )`. The install-mode self-upgrade also +defers while its own chain holds a live lease under 120 minutes old. An install +run from inside a workflow (/ship's docs step running `install.sh --for +document-release`, #3571) prints `SELF_UPGRADE: skipped (a gstack run in this +session holds a workflow lease on this installation: ... (UPGRADE_BUSY))`, +leaves the checkout where the run started and stays ok with `behind=`. Each +`gstack-skill-start` renews the lease. On Capy the leased pid is the machine's +long-lived `capy-server`, so the deferral ends when the lease turns 120 +minutes old, not when the process exits; `bin/gstack-upgrade` run by hand +moves the checkout sooner. The team-mode SessionStart hook (`bin/gstack-session-update`) honors the same leases: it logs `SKIP leased pid=

/m` to `analytics/session-update.log` and tries again at the next session start, without writing its hourly throttle stamp. A lease whose diff --git a/docs/designs/SKILL_EVAL_CONTRACT.md b/docs/designs/SKILL_EVAL_CONTRACT.md index 16091f53c..21573f1f2 100644 --- a/docs/designs/SKILL_EVAL_CONTRACT.md +++ b/docs/designs/SKILL_EVAL_CONTRACT.md @@ -69,3 +69,26 @@ Raw transcripts stay under `/runs/`. - **Trials are fixed before the run.** No trials are added after a result. One same-tree rerun of a red task is allowed and recorded as flaky; a second failure stands. - **Blinded adjudication.** A disputed answer goes to a fresh judge that sees the task and the answer, not the arm. + +## Notes for implementers (2026-10-28) + +Offered to gstack-evals' Lane A (interface v0.4). Nothing above changes; these are conventions gstack's task files +already assume, and one optional field. + +- **State root.** gstack skills keep state under one root (docs/state-root.md): `GSTACK_STATE_ROOT` wins, then + `GSTACK_HOME`. Set both to `/.gstack-home` for the agent, `setup` and `check`; `GSTACK_HOME` alone loses + to a `GSTACK_STATE_ROOT` inherited from the caller's shell, and the agent then writes the caller's real state. A + task's `seed.sh` creates `.gstack-home` and lists it in `.git/info/exclude`, so `git diff` checks ignore it and + `check` reads state there (/learn's `add` and `prune-stale`, /office-hours' design-doc and mockup checks). +- **`resumable`** (optional, in `verdict.json` and any error record): `true` when an INCOMPLETE run can be finished + with `--resume `, which runs only cells that never ran, under the same lock and trial count, so it adds no + trials after a result; `false` for a terminal stop, which needs a fix and a fresh run. A missing field reads as + `false`. +- **Lock.** A paid run needs `tasks.lock.json` committed beside the tasks file; `/write-skill`'s diet step 6 runs + `--lock` and commits it. +- **Sidecar.** Extensions live in `tasks.ext.json` beside the tasks file, keyed by task id, so this format stays + unchanged. gstack's free test checks only that each entry names a task in `tasks.json` and uses known keys. +- **Interactive tasks.** /office-hours' `must` patterns grade a headless run that ends where the skill stops for + input, as upstream skill-diet's runs do. On a host that answers questions from the sidecar's `user` replies, the final answer is + the session's last message, so the sidecar's `judge` line carries the behavior there. Open for Lane A: grade + `must` over the run's assistant messages on such hosts, or keep it on the final answer and rely on `judge`. diff --git a/docs/hosts.md b/docs/hosts.md index df863d1ce..8750cbbf1 100644 --- a/docs/hosts.md +++ b/docs/hosts.md @@ -24,6 +24,14 @@ neither does `./setup --local`. **What it writes.** Copies in the harness's own skills folder, never edits to `openclaw.json`, Hermes's `config.yaml` or any context file you did not name. +A context block is opt-in: `gstack-harness register openclaw|hermes|generic +--context ` writes the marked block into that file only, after printing +the file and its scope (`profile` inside the harness's own home, else +`project`). Setup, upgrades and refresh never add one, a block you delete stays +deleted, a second `--context` file keeps the first (the ledger keys blocks by +file), and uninstall restores each file byte for byte. It refuses `SOUL.md`, +and for Hermes a new file that would outrank rules Hermes loads now +(`.hermes.md`/`HERMES.md` load before `AGENTS.md`): `HARNESS_CONTEXT_REFUSED`. Every file goes into a ledger, `$GSTACK_STATE_ROOT/harness/.ledger`, with its sha256. Registering again changes only what changed; a folder or skill name gstack did not write stops it (`HARNESS_UNOWNED_ENTRY`); `gstack-uninstall` @@ -35,10 +43,24 @@ when it is the one gstack wrote; an edited block is left for you. `./setup `gstack-harness status` lists them and runs the harness's own skill list where it has one (`visible to harness: yes`). Errors: [troubleshooting](troubleshooting.md#agent-harnesses-gstack-harness). +**Registered, listed, used.** These are three separate facts, and this page +claims only the first two. *Registered*: gstack's files are in the harness's +skills folder and its ledger (`gstack-harness status`). *Listed*: the harness +puts the skill in the skills section of the model's prompt (`visible to +harness: yes`, from the harness's own skill list). *Used*: in a task that fits, +the model opens the matching skill and runs its first step. Use rates are +pending HARN-5's fixed panel (OpenClaw and Hermes chat mode, five trials per +cell). When they land they are measured under the eval adapter's +`GSTACK_SESSION_KIND=spawned` marker, which auto-decides gstack's questions, so +they say nothing yet about interactive sessions. Two levers aim at use: +each router line opens with the skill's own trigger sentence ("Use when asked +to ..."), and each Hermes description opens with a trigger list of at most 57 +characters, the part of a description Hermes's skills index shows. + | Harness | What gstack registers | Install | Verify | Remove | |---|---|---|---|---| -| OpenClaw | one `gstack` router skill (one description line in every request; its body lists every skill and its path) in `${OPENCLAW_STATE_DIR:-~/.openclaw}/skills/gstack`; `--skills all` registers every skill as its own top-level folder | `./setup --host openclaw`, or `./setup` inside OpenClaw | `openclaw skills list --json` shows `gstack` (source `openclaw-managed`, eligible) | `gstack-harness unregister openclaw` | -| Hermes | every skill, as `gstack-` in one `gstack` category, in `${HERMES_HOME:-~/.hermes}/skills/gstack` (Hermes opens only skills it has indexed) | `./setup --host hermes`, or `./setup` inside Hermes | `hermes skills list` shows the `gstack-*` skills in category `gstack` | `gstack-harness unregister hermes` | +| OpenClaw | default `--skills hybrid`: `gstack-review`, `gstack-investigate`, `gstack-qa`, `gstack-ship` and `gstack-plan-eng-review` as top-level skills plus one `gstack` router skill whose body lists every other skill and its path, in `${OPENCLAW_STATE_DIR:-~/.openclaw}/skills`. With OpenClaw 2026.10.6's 19 eligible bundled skills, hybrid's skills section is 10,290 characters, full format, under its 18,000-character budget; `--skills all` (17,971, compact format, descriptions cut) lists every skill as its own folder, `--skills router` (6,701) only the router | `./setup --host openclaw`, or `./setup` inside OpenClaw | `openclaw skills list --json` shows `gstack` and the five task skills (source `openclaw-managed`, eligible) | `gstack-harness unregister openclaw` | +| Hermes | every skill, as `gstack-` in one `gstack` category, in `${HERMES_HOME:-~/.hermes}/skills/gstack`. Hermes's skills index lists only skills registered as folders, so a router would leave the rest out of the listing (`skill_view` still loads an unlisted skill by name, but nothing tells the model it exists) | `./setup --host hermes`, or `./setup` inside Hermes | `hermes skills list` shows the `gstack-*` skills in category `gstack` | `gstack-harness unregister hermes` | | dots (feder-cr) | the `gstack` router in `/home/dot/skills/gstack`, which the Dot lists every turn | `./setup` on the Dot's computer, or `gstack-harness register dots` | the Dot's Skills page, or `GET /skills` | `gstack-harness unregister dots` | | QM | **not available yet.** QM imports a skill pack by cloning the whole repository and caps it at 32 MiB and 5,000 files; gstack's repository is about 73 MiB, so `gstack-harness register qm --yes` stops before sending anything ([why](troubleshooting.md#harness-qm-pack-too-large)) | meanwhile, paste `gstack-harness register generic --print` into the agent's instructions | ask it for a gstack skill | delete the pasted text | | Muse Code, Grok Build | nothing: both read `~/.claude/skills`, so the Claude install (`./setup`) is what they see, with Claude tool names | `./setup` | `gstack-harness status` runs `muse skills list` / `grok inspect` and reports *discovered (Claude-rendered, unverified)* | `gstack-uninstall` | diff --git a/docs/ship-budget.md b/docs/ship-budget.md new file mode 100644 index 000000000..ef7558364 --- /dev/null +++ b/docs/ship-budget.md @@ -0,0 +1,159 @@ +# /ship token budget and fresh-context handoffs + +`/ship --token-cap 25M` (or `GSTACK_SHIP_TOKEN_CAP=25M`) bounds what one /ship run spends, and +long runs hand their heavy segments to fresh-context children. The helper is +`bin/gstack-ship-budget`; the skill's procedure is `ship/sections/budget-handoff.md`. +There is no default cap: without one, /ship meters usage when it can and prints it, and +nothing else changes. + +## What the cap guarantees + +It is an **admission cap**, not a hard ceiling. Before every step and every dispatch batch, +`check` admits the work only when + + used + open reservations + unknown charges + projection + tail reserve + stop overhead <= cap + +Exactly at the cap is admitted; one token over is not. A parallel review batch is reserved as +one sum before any of it starts. Admitted work can still cost more than its projection, and +gstack cannot stop a host mid-turn from bash, so a run can finish above the cap by the +misprojection of work already admitted. The tail reserve (default 2M, `--reserve `) keeps +room for the receipt steps, and the stop overhead (calibrated) keeps room to stop cleanly. + +## Quickstart + +**Capy.** Read the root counter in one execute program that returns only that number: + +```js +return (await tools.thread.get({ thread_id: "this" })).cost.tokens; +``` + +then + +```bash +gstack-ship-budget start --record --token-cap 25M --reading +gstack-ship-budget check --run --step 6 --next 7 --reading [--prior-reading ] +``` + +The counter rolls up every subagent of the thread, outside voices included; Capy exposes no +per-subagent counter, so other work in the same thread counts too (it only stops earlier). + +**Claude Code.** `gstack-ship-budget start --record --token-cap 25M --session `. Without the +session id, `start --meter claude` prints a nonce: echo it once, then rerun with `--nonce `. +The helper reads the session journal, its subagent journals and the journals of headless +children it launched; you never pass `--reading`. + +**Anywhere else.** `--meter estimate` projects with the calibration and prints `meter=estimate`. +With a cap set and no readable meter, start refuses +([BUDGET_METER_UNAVAILABLE](troubleshooting.md#budget-meter-unavailable)). + +## The BUDGET line + + BUDGET: used= reserved= unknown= admission_cap= tail= unit= meter= epoch= call= next= projected= verdict=continue|delegate|stop + +| Field | Meaning | +|---|---| +| `used` | Metered usage since start (all epochs), or settled estimates under `meter=estimate` | +| `reserved` | Open reservations: admitted steps, started dispatches, and each open child's sub-cap counted as max(sub_cap, child_used), never both | +| `unknown` | Charges the meter cannot see (an external-CLI outside voice on Claude Code), counted at their reservation | +| `admission_cap` | The cap, or `none` | +| `tail` | Tail reserve plus stop overhead, held back from every admission | +| `unit`, `meter`, `epoch` | The meter contract: `capy-tokens` (root counter), `claude-usage-tokens` (journal usage), `estimate-tokens`; a meter change opens a new epoch | +| `call` | The per-call charge: two Capy readings in consecutive calls, or the last Claude Code call's usage | +| `next`, `projected` | What the check was for and its calibrated projection | +| `verdict` | `continue` (exit 0, prints `RESERVATION:` under a cap), `delegate` (exit 0), `stop` (exit 3) | + +Any exit other than 0 means the next step does not start. Exit 2 is a usage or validation +error on stderr with the code, the value and the repair. GSTACK_RESULT appears only on a stop, +an incomplete close and a child's return; /ship's real terminal line stays Step 22's. + +## Dispatches + +Under a cap, `gstack-review-log --start` refuses a dispatch without an unspent, one-shot +reservation ([BUDGET_CHECK_SKIPPED](troubleshooting.md#budget-check-skipped)): + +```bash +gstack-ship-budget check --run --step 9 --next dispatch:specialist,red-team --reading +gstack-review-log --start review --reservation +``` + +Roles are review-depth's: `specialist`, `red-team`, `adversarial-native`, `outside-voice`, +`fix-check`. `--finish ` settles the reservation at the dispatch's completion receipt. +`close` audits after the fact: each review-log row of the run with no reservation gets one +BUDGET_CHECK_SKIPPED line and the run ends status=incomplete for the owner to accept +(`close --approved-by --words ""`); a reservation is never created after the fact. + +## Delegation + +At start, a per-call charge of 100k or more delegates the whole /ship. Before Step 7 and before +Step 12, 150k or more (or an unknown charge) delegates the next segment (7–11.5, 12–22): + +1. `gstack-ship-budget handoff --run --from 12 --to 22 --base origin/ --reading ` writes a + brief (mode 0600, under the run directory) with the pins (HEAD, merge base, working tree, + reviewed tree), the record with its six headings and start tokens, the decisions in scope + with the owner's words, the decision trail, the budget and the return contract. It reserves + the child's sub-cap: min(cap − used − reserved − tail, the segment estimate), or `--sub-cap`. +2. The child is a Capy subagent on the shared machine, or on Claude Code + `gstack-ship-budget launch --in `: a background `claude -p` (resolved through lib/claude-bin.ts) + with explicit permission flags and the return file named. +3. The child runs `verify-handoff` first; a moved pin refuses + ([HANDOFF_PIN_MOVED](troubleshooting.md#handoff-pin-moved)). It admits against its sub-cap + with child_used = reading − reading at handoff, is the only writer of the record, and never + delegates again: a delegate rule stops it. It ends with `return` (at most 40 lines). +4. `gstack-ship-budget reconcile --run --return --reading `; idempotent per handoff hash, + so a duplicate return charges nothing twice. A refused, incomplete or interrupted child + exits 3: regenerate the handoff or stop. + +`--delegate never` turns delegate into stop for hosts without children. + +## Stop and resume + +A stop prints + + STOP: reason=budget_exhausted spent= reserved= unknown= admission_cap= next= projected= + RECOVER: /ship --resume --token-cap + GSTACK_RESULT: skill=ship status=incomplete run=

+ +Raising the cap is the owner's call; the resume journals who raised it and their words: + +```bash +gstack-ship-budget resume --record --token-cap --approved-by Garry --words "raise it to finish" --reading +``` + +Every command takes `--run` or `--record`; runs are never found by branch or directory, and a +/ship without `--resume` or `--continue` always starts a new run. The ledger and record are +mirrored to a private Drive checkpoint (`GSTACK_SHIP_BUDGET_CHECKPOINT_DIR`, else the +project-user Drive folder on Capy) bound to the run id and their hashes, so after a machine +change `resume --run ` restores both. A corrupt ledger +([BUDGET_LEDGER_INVALID](troubleshooting.md#budget-ledger-invalid)) is rebuilt from the +record's block with `--rebuild-from-record`; open reservations are then charged as unknown. + +## Calibration + +`lib/ship-budget-calibration.json` holds per-meter constants (per call, per dispatch, stop +overhead, calls and dispatches per step) fitted from metered runs: each constant is the +largest observation times 1.5, rounded up to 10,000 tokens. The leave-one-out test +(test/ship-budget-calibration.test.ts) covers the per-call constant only, the one observed +across three runs; per-dispatch has two observations and stop overhead one. Only the Capy +meter has observations; the Claude Code and estimate units are seeded from it until a +Claude-metered /ship completes. + +## Token cap and USD spend cap + +A lane's `--spend-cap` (USD) bounds paid gates and evals through lib/spend-ledger.ts; `--token-cap` +bounds the /ship run's model tokens through its own ledger. They are independent: set both +when a lane runs paid gates inside /ship, and neither converts into the other. + +## Claiming savings + +Savings count completed ships only. Preregister the comparison with `/eval-plan` (arms, bars, +stop rules) before claiming a saving from the cap or from delegation. + +## Result codes + +[BUDGET_CAP_REACHED](troubleshooting.md#budget-cap-reached) · +[BUDGET_READING_MISSING](troubleshooting.md#budget-reading-missing) · +[BUDGET_READING_REJECTED](troubleshooting.md#budget-reading-rejected) · +[BUDGET_METER_UNAVAILABLE](troubleshooting.md#budget-meter-unavailable) · +[BUDGET_LEDGER_INVALID](troubleshooting.md#budget-ledger-invalid) · +[BUDGET_CHECK_SKIPPED](troubleshooting.md#budget-check-skipped) · +[HANDOFF_PIN_MOVED](troubleshooting.md#handoff-pin-moved) diff --git a/docs/ship-policy.md b/docs/ship-policy.md index c08973c92..168ccb678 100644 --- a/docs/ship-policy.md +++ b/docs/ship-policy.md @@ -953,6 +953,22 @@ receipt when the base moves: | a merge of the base whose resolution changed product code | a fresh /ship (`RECEIPT_CARRY_PRODUCT_CHANGED`) | | a rebase or force-push onto a tree the receipt covers, product diff against the new base unchanged | carries (`carry.ancestry: rewritten`) | | any other rebase or force-push | a fresh /ship (`RECEIPT_CARRY_TREE_MISMATCH`) | +| a stacked PR whose parent landed (squash or merge), retargeted to the base with the base merged in, HEAD's product diff exactly the one reviewed against the parent branch | carries (reason `stack parent landed`) | + +**Stacked PRs (#3570).** A child PR's receipt is written against its parent +branch, so its `base` names that branch and its `product_patch_id` is the +child's own range. After the parent lands, the PR is retargeted to the base, and +/ship's carry check runs with `--base `. When that base differs from the +receipt's, the carry compares the reviewed range (the recorded +`product_patch_id`, or for an older receipt the range against +`origin/` while that branch still resolves) with HEAD's whole product +diff against the base, computed the way `write` records it, so a parent's +release-metadata change that never reached the base counts too. Equal means +the parent fully landed and the child is unchanged, so the receipt carries +and from then on names the base it was carried to. A parent that has not landed, a child edited +since, or a parent that landed with changes the child never merged all leave a +different diff and refuse with `RECEIPT_CARRY_PRODUCT_CHANGED`. An older +receipt whose parent branch is gone refuses with `RECEIPT_CARRY_REFUSED`. Since the release that added `review_scope`. A `/ship` receipt names the head it reviewed, so a conflict-only merge of the base or a test-only fix used to diff --git a/docs/skills.md b/docs/skills.md index a1fb382e0..348777519 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -906,8 +906,10 @@ gstack's own templates and for any skill folder you own. - **Drift.** `test/skill-bin-drift.test.ts` fails when a template or rendered skill calls a gstack bin or flag that does not exist (`bun run scripts/skill-bin-drift.ts --skill ` for one skill). Its allowlist only shrinks. - **Full diet.** Report first, write the eval tasks before any cut - (`test/fixtures/skill-evals//tasks.json`), cut, then prove before vs after vs no skill with the shared skill - eval (`docs/designs/SKILL_EVAL_CONTRACT.md`). A diet ships only when no task that passed before fails after. + (`test/fixtures/skill-evals//tasks.json`), lock them (`gstack-evals skill-eval --lock`, then commit + `tasks.lock.json`; the shared eval refuses a paid run without it), cut, then prove before vs after vs no skill with + the shared skill eval (`docs/designs/SKILL_EVAL_CONTRACT.md`). A diet ships only when no task that passed before + fails after. `/write-skill` is not `/skillify`: `/skillify` codifies a browser scrape into a browser-skill. Adapted from [nicobailon/skill-diet](https://github.com/nicobailon/skill-diet) (MIT). The first diet, /learn, cut its template from diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 85c5d1543..b06d26507 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1566,11 +1566,19 @@ process has exited never blocks, and neither does a stale one: each lease records its process's start identity, so a pid reused after a reboot or a machine wake (GBRA-105's lease named pid 379, which had become dbus-daemon) is reclaimed instead of blocking. The upgrader's own session (the pid chain it -runs under) never counts. +runs under) never counts for `bin/gstack-upgrade` run by hand. A Capy install +in install mode (`bin/gstack-capy-session`) counts it while that lease is under +120 minutes old: an install run from inside a workflow that holds the lease +(/ship's docs step, #3571) prints `SELF_UPGRADE: skipped (a gstack run in this +session holds a workflow lease on this installation: pid

(m +), so the upgrade waits until the lease is 120 minutes old; fix: +/bin/gstack-upgrade once the run ends (UPGRADE_BUSY))` and leaves the +checkout where the run started. Each `gstack-skill-start` renews the lease. **Fix.** Wait for those sessions to finish (`bin/gstack-lease list` shows every lease with its age and `alive|dead|stale`; a holder is named as -`pid

(m )`), then re-run `bin/gstack-upgrade`. +`pid

(m )`), then re-run `bin/gstack-upgrade`. For the +session's own run, run the printed `bin/gstack-upgrade` after the run ends. When you know they are idle, `GSTACK_UPGRADE_FORCE=1 bin/gstack-upgrade` proceeds. At a Capy session start the same refusal appears as `SELF_UPGRADE: skipped (live gstack sessions hold this installation: ...)`, @@ -1729,8 +1737,11 @@ restate them. Rotate the secret if it was real. **Meaning.** The record is kept per branch (one Capy thread ships one branch), and HEAD is detached or the working directory is not a git repository. Exit 3. +From `import --autoplan

--stack ` it means a listed branch exists +neither locally nor on origin; the line names it, and no branch's record was written. -**Fix.** Check out the branch the work ships from, or pass `--branch `. +**Fix.** Check out the branch the work ships from, or pass `--branch `. For +`--stack`, correct or fetch the named branch and import again. ### `gstack-approvals: ... (APPROVAL_RECORD_UNAVAILABLE)` @@ -1769,7 +1780,9 @@ import again. Imports are idempotent, so a retry never records an answer twice. ### `gstack-owner-brief render --captain: ... (CAPTAIN_BRIEF_INCOMPLETE)` **Meaning.** The plan is missing at least one section the brief needs: `## Before → after`, -`## Why it matters`, `## What caused this work`, `## Big decisions`. The brief still prints, +`## Why it matters`, `## What caused this work`, `## Big decisions`, and `## ELI5` (alias +`## In plain words`) on a run whose `gate.json` carries an `eli5` field (gstack 1.91.305 and +later; older runs render as before). The brief still prints, but it opens with "Not ready for approval" and has no reply invitation. Exit 1. **Fix.** Add the named sections to the plan (`gstack-autoplan revise --plan ` if @@ -1810,6 +1823,92 @@ all the command prints `SHOT_PNG: unavailable (...)` and exits 0 instead. **Fix.** Screenshot `shot.html` with your own browser at 880 px wide, or use `text.md`. +## /ship token budget and fresh-context handoffs (gstack-ship-budget) + +The flow, the BUDGET line field by field and the meters are in [ship-budget.md](ship-budget.md). +Exit 2 lines go to stderr; exit 3 lines (a stop) go to stdout with the STOP, RECOVER and +GSTACK_RESULT lines. + + +### `gstack-ship-budget: ... (BUDGET_CAP_REACHED)` + +**Meaning.** The next step or dispatch batch would push used + open reservations + unknown +charges + its projection + the tail and stop reserve past the admission cap, so it did not +start. Exit 3. `gstack-review-log --start` prints the same code (exit 1) for a dispatch +after the run stopped. The cap admits work; it cannot stop a turn already running, so the +overshoot is bounded by the misprojection of work admitted before the stop. + +**Fix.** The run ended status=incomplete with a resumable record. Raising the cap is the +owner's call: run the printed `RECOVER:` line; its resume needs +`--approved-by --words ""`. + + +### `gstack-ship-budget: ... (BUDGET_READING_MISSING)` + +**Meaning.** The run's meter is the Capy root counter, a cap is set, and the command got no +`--reading`. Exit 2. No gstack binary can call Capy's API, so the agent reads it. + +**Fix.** In one execute program return only +`(await tools.thread.get({ thread_id: "this" })).cost.tokens` and pass it as `--reading `. + + +### `gstack-ship-budget: ... (BUDGET_READING_REJECTED)` + +**Meaning.** The reading breaks the run's meter contract: it is lower than the last reading +of the same epoch, `--prior-reading` is above `--reading`, or `--reading` went to a meter that +reads its own source (Claude Code journals, the estimate). Exit 2; nothing changed. + +**Fix.** Pass the counter the run started with (the BUDGET line names meter, unit and epoch). +A different meter opens a new epoch that keeps prior usage: +`gstack-ship-budget resume --run --meter `. + + +### `gstack-ship-budget: ... (BUDGET_METER_UNAVAILABLE)` + +**Meaning.** A cap is set and no meter is readable: no `--reading`, no bound Claude Code +session, no `--meter estimate`; or a `--session`/`--nonce` matched zero or several journals. +The line names what it tried. Exit 2. + +**Fix.** Capy: `--reading `. Claude Code: `--session `, or echo the nonce the line prints +once and rerun with `--nonce `. Elsewhere, with the owner's consent, `--meter estimate`. + + +### `gstack-ship-budget: ... (BUDGET_LEDGER_INVALID)` + +**Meaning.** The ledger (`/ship-runs//budget.json`), the record's +gstack-budget block, a handoff brief's block or a checkpoint is missing, unparseable, from +another schema version, or not bound to the run (identity or sha256 mismatch). The line names +the path, the schema version and the parse location. Exit 2. + +**Fix.** After a machine change, `gstack-ship-budget resume --run ` restores the ledger and +record from the Drive checkpoint. Otherwise rebuild: +`resume --record --rebuild-from-record --reading `; open reservations are charged as unknown. + + +### `gstack-review-log: ... (BUDGET_CHECK_SKIPPED)` / `gstack-ship-budget: ... role= step= started= spend=unknown (BUDGET_CHECK_SKIPPED)` + +**Meaning.** Under a cap, `gstack-review-log --start` got no reservation id, an id from another run +or a step reservation (mismatched), or an id already used (one-shot); it refused before the +dispatch (exit 1, nothing captured). From `close`: a review-log row of this run had no +reservation before it started; one line per dispatch, and the run ends status=incomplete (exit 3). + +**Fix.** Run `gstack-ship-budget check --run --step --next dispatch:` before the +batch and pass the printed id once with `--reservation`. A reservation is never created after the +fact: the owner accepts the unreserved spend with `close --approved-by --words ""` +or the dispatches rerun under reservations. + + +### `gstack-ship-budget: ... (HANDOFF_PIN_MOVED)` + +**Meaning.** `verify-handoff` found the brief no longer matches its tree: HEAD, the merge base +with the base ref, the working-tree fingerprint (`gstack-wtree`) or the reviewed tree moved, or the +brief's sha256 is not the one the parent recorded. Each line names the pin with its expected +and actual value. Main moving alone keeps the merge base and never refuses. Exit 3; the child +wrote its return with status=refused. + +**Fix.** The parent reconciles the refusal and regenerates the handoff at the current tree +(`gstack-ship-budget handoff ...`) or stops. + ## Browser @@ -2388,6 +2487,14 @@ and an E.164 `+14155551234` still report, so the finding means the id stands without a run word (`the id is 40269992077`, `40269992077 failed`) or follows a word that is not one (`see 40323989742`). +Separately, the scanner skips a bare number that is exactly a power of two +from 2^30 through 2^49, one less than such a power, or one of eleven 32-bit +hash and PRNG constants (Knuth's multiplicative hash, the golden-ratio +constant, the glibc and Numerical Recipes LCGs, FNV-1a, MurmurHash2 and 3, the +MT19937 seeder and the largest 32-bit prime; `isNumericConstant` in +`lib/redact-patterns.ts`). Only the exact digits with no separator are exempt: +the same digits with a `+`, spaces, dashes, dots or parentheses still report. + **Fix.** Write the id next to a run word (`run 40269992077`) or as an `/actions/runs/` link. For anything else, rerun with `--confirm ` using the `TOKEN:` line the refusal printed; MEDIUM findings do not block @@ -2428,6 +2535,15 @@ An address only another remote knows still reports. If the hook also printed `existing-email suppression was limited for this push`, it could not read the history in 5 seconds, so known authors may be listed too. +A filename with an `@` in the package@version style is not an address and +never reports: the part after the `@` is a version or tag (one dotless label +or a dotted version, never a domain name) followed by file extensions no +top-level domain uses, or a dotted all-digit version followed by +an extension that doubles as a top-level domain (`looksLikeAtFilename` in +`lib/redact-patterns.ts`). A file named after a real address, an address at an +all-digit domain and an address whose top-level domain doubles as a file +extension still report. + **Fix.** Remove the address, or allow it for this repo: `git config --add gstack.redact.allowEmail
`. If it is your own address, check `git config user.email`. The allowlist only covers `pii.email`; @@ -4740,8 +4856,10 @@ to HEAD: the PR body has no valid receipt, the working tree has uncommitted or untracked changes (a carry certifies a commit, never a tree that differs from it), the receipt's head left HEAD's history and the receipt records no tree to compare (a receipt written before `head_tree`, whose head is not in this -clone), or git could not compare the two product diffs or read the working -tree's status. It also refuses when an owner exception the receipt records +clone), the PR was retargeted to the base after its stack parent landed but +the receipt records no `product_patch_id` and `origin/` no longer +resolves, so the reviewed range cannot be recomputed, or git could not +compare the two product diffs or read the working tree's status. It also refuses when an owner exception the receipt records no longer stands, and, for a receipt from a gstack that records review depth, when HEAD needs a deeper review than the receipt records, `--head` is not the checked-out HEAD, or the receipt records `gstack_version` without @@ -4752,9 +4870,10 @@ ready` refuses `QUEUE_RECEIPT_STALE`. **Fix.** Commit or stash every working-tree change, then rerun `gstack-ship-receipt carry --pr ` at the new head. When the history is already rewritten and the receipt predates `head_tree`, run /ship on the new -head; next time merge the base in instead of rebasing. For a depth or -exception refusal, run /ship on the new head (or check out `--head` and carry -there). +head; next time merge the base in instead of rebasing. For a retargeted stacked +PR whose older receipt lost its parent branch, or a depth or exception +refusal, run /ship on the new head. When `--head` is not the checked-out HEAD, +check it out and carry there. ### `REVIEW_LOOP_EXCEPTION_INVALID` @@ -4793,13 +4912,18 @@ registered output the pregate's regen check proved (listed under `proven`, checked against the same base registry), nor part of the base merge has a different patch than the reviewed head had. After a rebase it means HEAD has the reviewed tree but the base moved under it, so the diff a reviewer would see -is not the reviewed one. The reviewed verdict does not cover HEAD, so the -receipt is not carried. The refusal names the changed product paths. +is not the reviewed one. For a stacked PR retargeted to the base after its +parent landed, it means HEAD's product diff against the base is not the range +reviewed against the parent branch: the parent has not fully landed, or the +branch changed since. The reviewed verdict does not cover HEAD, so the +receipt is not carried. The refusal names the changed product paths, or for a +retargeted stacked PR the parent branch and the base. **Fix.** Run /ship on the new head. The receipt carries only across a conflict-only base merge, a test-only change, release metadata, a registered -output the pregate's regen check proved, or a rebase onto a covered tree with -the recorded product diff, which the +output the pregate's regen check proved, a rebase onto a covered tree with +the recorded product diff, or a stacked PR's retarget once its parent fully +landed on the base, which the `carry` object in the carried receipt records with the product patch-id and the range-diff evidence ([unattended.md](unattended.md#the-terminal-line)). @@ -5180,7 +5304,7 @@ The name is not one of openclaw, hermes, dots, generic, qm, muse or grok. For a ### `gstack-harness: Hermes does not support --skills router` (HARNESS_MODE_UNSUPPORTED) -Hermes opens only skills it has indexed, so a router that points at unlisted files would not load. Drop `--skills` to take the harness's default (Hermes: all; OpenClaw, dots and generic: router). +Hermes lists in its skills index only the skills registered as folders in its skills tree, so a router would leave every other gstack skill out of the listing the model chooses from (Hermes's `skill_view` can still load an unlisted skill by name, but nothing tells the model it exists). Drop `--skills` to take the harness's default (Hermes: all; OpenClaw: hybrid; dots and generic: router). OpenClaw takes router, hybrid or all. ### `gstack-harness: refusing to write into : ` (HARNESS_UNSAFE_DESTINATION) @@ -5192,7 +5316,12 @@ The destination is your home folder, the filesystem root, inside the gstack chec gstack only replaces files its ledger says it wrote. A folder or a skill with the same name is yours (or another tool's), and harnesses resolve skills by name, so gstack stops instead of shadowing it. Rename or move that entry, then register again. -The same code stops `register generic --context ` when the file holds a `` or `` line without exactly one partner, or a gstack block someone edited. Delete those marker lines (and the lines between them, once you have kept what you want), then register again. +The same code stops `register --context ` when the file holds a `` or `` line without exactly one partner, or a gstack block someone edited. Delete those marker lines (and the lines between them, once you have kept what you want), then register again. + + +### `gstack-harness: refusing to write the gstack block into : ` (HARNESS_CONTEXT_REFUSED) + +`--context` writes the routing block only into a file you name, and two kinds of file are refused before anything is written. `SOUL.md` (in any letter case) is the harness's identity file (Hermes and OpenClaw both load it every session), and gstack never edits it. For Hermes, a new `.hermes.md`, `HERMES.md`, `AGENTS.override.md`, `AGENTS.md` or `CLAUDE.md` that would outrank a rules file Hermes loads now is refused too: Hermes loads one project context type, first match wins (`.hermes.md`/`HERMES.md`, then the `AGENTS.md` chain, then `CLAUDE.md`, then `.cursorrules`), takes the first name it finds in a folder (`.hermes.md` before `HERMES.md`, `AGENTS.override.md` before `AGENTS.md`), and takes the nearest `.hermes.md`/`HERMES.md` walking up to the git root, so creating it would hide those rules. Name the file Hermes already loads instead (the error names it), or a file in `$HERMES_HOME` for every session. ### `gstack-harness: could not render skills: ...` (HARNESS_RENDER_FAILED) diff --git a/docs/unattended.md b/docs/unattended.md index 8ebbc5791..905de39cc 100644 --- a/docs/unattended.md +++ b/docs/unattended.md @@ -187,6 +187,15 @@ most 300 words; a subagent brief names the files to read instead of pasting them. Evidence goes in files the report points to. Waits go on operations, never on polling wakes. +### Token caps and fresh-context handoffs + +A parent bounds a /ship run with `--token-cap ` (or `GSTACK_SHIP_TOKEN_CAP`). +It is an admission cap: /ship meters usage, reserves every step and dispatch +batch before it starts, and stops `status=incomplete` with a `RECOVER:` line +instead of starting work that would cross the cap. Long runs hand Steps 7–11.5 +and 12–22 to fresh-context children. The flow, the BUDGET line and the result +codes are in [ship-budget.md](ship-budget.md). + ### The outside voice on Capy Step 11's outside adversarial review prefers the Codex CLI. On a Capy machine @@ -495,6 +504,53 @@ by its runner. Result codes: `EXECUTION_UNKNOWN`, `RUN_LOCKED`, decision ids are renamed and journaled); one written by a newer gstack is refused. +### Carry-forward + +A gate revision after the first (`gate_rev` 2 and later, written after a +`revise`) is answered with the owner's recorded words from the revision before +it when nothing new needs their decision. `gstack-autoplan` prints +`CARRIED: gate_rev= <- gate_rev= words="" by= reason=`, +then the usual `APPROVED:` lines, and journals `gate_carried`. The carry needs +all of: the earlier gate approved (`p1a` or `p1b`) with `rec` or "do it" +(not item tokens), no item there left pending, and the owner's words +recorded; that gate was not itself carried; every accepted change incorporated +or settled; the plan file's bytes equal those recorded at the gate or at the +`revise` that took the changes (any later edit refuses, an ELI5-only one +included); no urgent or +outside-plan finding open; and every new gate item one of the cases below. +Anything else prints `CARRY: no ()` (journal `carry_refused`) and the gate +goes to the owner as before. `--no-carry-forward` on the first `next` turns it +off for the run. + +- **"do it".** When the owner's words were "do it" (their words, not a + `captain:` relay of them), a new `auto` item that changes no scope, cost or + direction, whose recommended option changes no plan text, and is no round + or budget grant takes its recommendation. The + decision row gets `carried_under: do it`, the output prints + `CARRIED_UNDER_DO_IT:` per item, and the approval record lists them as + "taken under "do it", not seen by the owner". `rec` carries no new item. +- **Unreviewed post-cap delta.** A "plan changed after cap" item + recommending `a` (accept) is read by one reviewer before it carries. `CARRY_CHECK:` names the attempt and + the prompt (the delta against `plan-at-gate.r.md`, the accepted changes, + the full plan); the run reserves the estimate in `spend.json` and refuses + when it is over `--carry-check-cap ` (default 5) or the run's cap. + Dispatch it to a model family other than the plan reviewers', then + `check --out --attempt --result --model ` + (`--same-family ""` when no other family is available). A High or + Critical finding, or `--unavailable ""`, leaves the gate for the + owner. The verdict is saved as `carry_check` on `gate.json`, on the + decision rows (`carry_check`) and in `/decisions.tsv`. A pending + check is void, its reservation released and the gate left for the owner, + when the owner answers the gate, the plan is revised, a new gate is + written, or the delta changed after dispatch. + +Carried rows keep `answered_by: agent:gstack-autoplan` and name their source +(`carried_gate_from`, `carried_gate_rev`, `carried_answered_by`); +`gstack-approvals import --autoplan` writes the carried gate as its own row, +and `gstack-owner-brief render --captain` opens with "Nothing pending. +Carried forward from gate_rev ", followed by any items taken under "do it" +without being shown to the owner. + ## Owner brief `gstack-owner-brief render --out ` is what the owner sees at the final diff --git a/hosts/hermes.ts b/hosts/hermes.ts index 520abbba6..18043b6dc 100644 --- a/hosts/hermes.ts +++ b/hosts/hermes.ts @@ -6,11 +6,14 @@ const hermes = defineHost({ tier: 'experimental', capabilities: { toolExecution: true, questions: 'native', planMode: false, delegation: true, browser: true, safetyHooks: 'advisory' }, - // Hermes indexes skills by frontmatter name, first match wins (#2825). + // Hermes indexes skills by frontmatter name, first match wins (#2825). Its + // skills index shows 57 chars of a description and "..." (agent/skill_utils.py + // SKILL_PROMPT_DESC_LIMIT = 60), so each description leads with when to use it. frontmatter: { mode: 'allowlist', keepFields: ['name', 'description'], descriptionLimit: null, + descriptionLead: 57, nameMatchesDirectory: true, }, diff --git a/hosts/openclaw.ts b/hosts/openclaw.ts index 1b1c431e5..ac9961e2f 100644 --- a/hosts/openclaw.ts +++ b/hosts/openclaw.ts @@ -15,8 +15,9 @@ const openclaw = defineHost({ suppressedResolvers: [...CROSS_MODEL_RESOLVERS, ...GBRAIN_RESOLVERS], // ./setup --host openclaw (and setup run inside OpenClaw) registers through - // gstack-harness: one gstack router skill in $OPENCLAW_STATE_DIR/skills, or - // every skill with --skills all. OpenClaw's ACP route (docs/OPENCLAW.md) stays. + // gstack-harness: the task skills plus one gstack router skill for the rest in + // $OPENCLAW_STATE_DIR/skills (hybrid), or --skills router|all. OpenClaw's ACP + // route (docs/OPENCLAW.md) stays. install: { linkingStrategy: 'symlink-generated', registration: 'harness', diff --git a/lib/approval-record.ts b/lib/approval-record.ts index ed8bcf738..38d798682 100644 --- a/lib/approval-record.ts +++ b/lib/approval-record.ts @@ -52,6 +52,11 @@ export type Env = NodeJS.ProcessEnv; const git = (cwd: string, args: string[]) => spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 10_000 }); +/** A branch this checkout knows: a local head or an origin remote-tracking ref. */ +export function branchExists(cwd: string, branch: string): boolean { + return [`refs/heads/${branch}`, `refs/remotes/origin/${branch}`].some(ref => git(cwd, ['rev-parse', '--verify', '--quiet', ref]).status === 0); +} + /** One contained path segment for a branch: readable prefix plus a hash of the exact ref. */ export function branchKey(branch: string): string { const readable = branch.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[.-]+/, '').slice(0, 60) || 'branch'; @@ -226,13 +231,15 @@ export function renderRecord(read: ReadResult, loc: StoreLocation, o: { heading? return [...head, ...lines, '', `Source: gstack-approvals record for ${cell(loc.branch)} (display only; not an approval citation).`, ''].join('\n'); } -interface DecisionLike { id?: string; title?: string; status?: string; chosen?: string | null; recommended?: string | null; gate_rev?: number; answered_at?: string; answered_by?: string; reply?: string; owner_reply?: string; carried_from?: string; label?: string; chosen_text?: string } +interface DecisionLike { id?: string; title?: string; status?: string; chosen?: string | null; recommended?: string | null; gate_rev?: number; answered_at?: string; answered_by?: string; reply?: string; owner_reply?: string; carried_from?: string; label?: string; chosen_text?: string; + carried_gate_from?: string; carried_gate_rev?: number; carried_answered_by?: string; carried_under?: string; carry_check?: string } const stripRef = (t: string) => t.replace(/\s*\[[^\]]*\]\s*$/, '').trim(); /** * Rows for every answered gate in an autoplan run: one row per answer event (gate_rev, time, answerer), covering - * the items it settled. Carried-forward answers were recorded when first given and are skipped. Ids are stable, + * the items it settled. Item answers carried from an earlier revision were recorded when first given and are skipped; + * a whole gate carried forward (lib/autoplan-carry.ts) gets its own row naming the revision its words came from. Ids are stable, * so a rerun (or a retry after an interrupted import) adds nothing twice. */ export function importAutoplan(runDir: string, branch: string, by?: string): ApprovalRow[] | RecordError { @@ -265,10 +272,16 @@ export function importAutoplan(runDir: string, branch: string, by?: string): App const changed = items.filter(r => r.chosen && r.recommended && r.chosen !== r.recommended); const stillPending = rows.filter(r => r.gate_rev === rev && r.status === 'pending'); const answerer = first.answered_by ?? 'unknown'; - const who = answerer === 'human' ? (by ? `${by}, typed at the gate` : 'the owner, typed at the gate') : `${by ?? 'the owner'}, relayed by ${answerer}`; - const scope = `the reviewed plan (sha256 ${planSha}), ${changed.length ? `${changed.length} recommendation(s) changed: ${changed.map(r => stripRef(r.title ?? '')).join('; ')}` : 'every recommendation taken'}`; + const carried = p1?.carried_gate_from ? p1 : undefined; + const relayed = carried?.carried_answered_by && carried.carried_answered_by !== 'human' ? `, relayed by ${carried.carried_answered_by}` : ''; + const who = carried ? `${by ?? 'the owner'} (words from gate_rev ${carried.carried_gate_rev}${relayed}), carried forward by gstack-autoplan` + : answerer === 'human' ? (by ? `${by}, typed at the gate` : 'the owner, typed at the gate') : `${by ?? 'the owner'}, relayed by ${answerer}`; + const unseen = items.filter(r => r.carried_under).map(r => stripRef(r.title ?? '')); + const checked = [...new Set(items.map(r => r.carry_check).filter((c): c is string => !!c))]; + const scope = [`the reviewed plan (sha256 ${planSha}), ${changed.length ? `${changed.length} recommendation(s) changed: ${changed.map(r => stripRef(r.title ?? '')).join('; ')}` : 'every recommendation taken'}`, + unseen.length ? `taken under "do it", not seen by the owner: ${unseen.join('; ')}` : '', checked.length ? `post-cap delta checked by ${checked.join(', ')}` : ''].filter(Boolean).join('; '); const built = buildRow({ - ask: `Approve the plan "${planTitle}" (autoplan run ${runId}, ${items.length + (p1 ? 1 : 0)} decisions)`.slice(0, CAPS.ask), + ask: `Approve the plan "${planTitle}" (autoplan run ${runId}, ${carried ? `gate_rev ${rev} carried forward from gate_rev ${carried.carried_gate_rev}, ` : ''}${items.length + (p1 ? 1 : 0)} decisions)`.slice(0, CAPS.ask), words: first.owner_reply ?? first.reply ?? '(no words recorded)', by: who.slice(0, CAPS.by), scope: scope.slice(0, CAPS.scope), diff --git a/lib/autoplan-carry.ts b/lib/autoplan-carry.ts new file mode 100644 index 000000000..0e6ae18ef --- /dev/null +++ b/lib/autoplan-carry.ts @@ -0,0 +1,252 @@ +/** + * autoplan-carry — carry the owner's last answer to a later gate revision (GSTA-155, + * docs/unattended.md#carry-forward). When a gate_rev N+1 asks nothing the owner has not + * already decided, the runner answers it with the owner's recorded gate_rev N words instead + * of a second round trip, and records that it did (decisions.jsonl `carried_gate_from`, + * journal `gate_carried`, `/decisions.tsv`). It never invents an answer: every + * carried answer is the owner's own earlier words, and every refusal says which condition failed. + * + * A carry needs all of: carry not turned off (`--no-carry-forward`); gate_rev N approved (p1 a or b) + * with the owner's words recorded, and not itself a carry; every change accepted at N + * incorporated or settled; the plan file unchanged since the gate or the revise that took those + * changes, and the reviewed plan equal to it; no open urgent finding; and every new item already + * carried. Two kinds of new item do not block: items a "do it" covers (the owner's words are + * "do it": an auto item that changes no scope, cost or direction and is no round grant), and a + * capped-delta item recommending "accept", which first gets one reviewer on just the delta + * (`CARRY_CHECK:`, answered with `gstack-autoplan check`); a High or Critical finding there + * means no carry, and the gate goes to the owner as before. + */ +import { createHash } from 'node:crypto'; +import * as fs from 'node:fs'; +import * as path from 'node:path'; +import { attemptEstimate } from './autoplan-budget'; +import { lineDiff } from './autoplan-confirm'; +import { answerGate } from './autoplan-gate'; +import { driftLine } from './autoplan-plan-text'; +import { BOUNDARY, RESULT_FORMAT, REVIEWER_TRAILER } from './autoplan-prompts'; +import { parseReviewResult } from './autoplan-reconcile'; +import { FILES, RunError, journal, now, readDecisions, readJournal, readState, writeDecisions, writeState, type RunState } from './autoplan-state'; +import { appendTrailRow } from './decision-trail'; +import { decisionId, parseReply, type GateItem, type GateList } from './gate-list'; +import { readJsonl } from './headless-artifacts'; +import { modelFamily } from './outside-voice-runner'; +import { release, reserve, settle } from './spend-ledger'; + +export const DEFAULT_CARRY_CHECK_CAP_USD = 5; +const HIGH = ['Critical', 'High']; +const DO_IT = /^\s*(?:(?![^:]*\bcaptain\b)[a-z]+(?: [a-z]+){0,2}:\s*)?do it[\s.!]*$/i; +/** The owner's verbatim words are a "do it" (optionally after their name), not a Captain's words or an item token (`p3b: do it`) naming one. */ +export const isDoIt = (words: string | undefined): boolean => !!words && DO_IT.test(words); + +export interface CarryCheck { + attempt: string; prompt: string; result: string; delta_sha256: string; items: string[]; estimate_usd: number; + status: 'dispatched' | 'passed' | 'failed' | 'unavailable'; model?: string; max_severity?: string; findings?: number; at: string; +} +export interface CarryRecord { + gate_rev: number; from_gate_rev?: number; verdict: 'carried' | 'refused' | 'check_pending'; + reason: string; words?: string; under_do_it?: string[]; check?: CarryCheck; lines: string[]; at: string; +} + +const sha256 = (text: string | Buffer) => createHash('sha256').update(text).digest('hex'); +const planFile = (state: RunState) => state.plan_input ?? state.plan_source; +const fileSha = (file: string) => (fs.existsSync(file) ? sha256(fs.readFileSync(file)) : undefined); +export const atGateCopy = (out: string, rev: number) => path.join(out, `plan-at-gate.r${rev}.md`); + +/** What finishGate journals beside gate_written: the plan file's bytes and a copy of the reviewed plan the owner is asked about. */ +export function gateEvidence(state: RunState, rev: number): { source_file_sha256?: string } { + if (fs.existsSync(state.active_plan)) fs.copyFileSync(state.active_plan, atGateCopy(state.out, rev)); + return { source_file_sha256: fileSha(planFile(state)) }; +} + +/** The lines the latest carry decision printed, for the command that wrote this gate revision. */ +export function carryLines(state: RunState): string[] { + const c = state.carry; + return c && c.gate_rev === state.gate_rev ? c.lines : []; +} + +function record(state: RunState, c: Omit): CarryRecord { + const full = { ...c, at: now() }; + state.carry = full; + journal(state.out, { event: c.verdict === 'carried' ? 'gate_carried' : c.verdict === 'check_pending' ? 'carry_check_dispatched' : 'carry_refused', gate_rev: c.gate_rev, from_gate_rev: c.from_gate_rev ?? null, reason: c.reason, ...(c.under_do_it?.length ? { under_do_it: c.under_do_it } : {}), ...(c.check ? { check: c.check.attempt, check_status: c.check.status } : {}) }); + appendTrailRow(path.join(state.out, 'decisions.tsv'), ['gate', c.verdict === 'carried' ? `carried gate_rev ${c.gate_rev} from gate_rev ${c.from_gate_rev}` : c.verdict === 'check_pending' ? `delta check before carrying gate_rev ${c.gate_rev}` : `no carry for gate_rev ${c.gate_rev}`, + c.reason, c.check ? path.basename(c.check.result) : 'decisions.jsonl', c.check?.status ?? c.verdict]); + return full; +} +const refuse = (state: RunState, rev: number, from: number | undefined, reason: string) => record(state, { gate_rev: rev, from_gate_rev: from, verdict: 'refused', reason, lines: [`CARRY: no (${reason})`] }); + +/** Drop a delta check still waiting for its reviewer (the owner answered, the plan was revised, a new gate was written) and release its reservation. */ +export function voidPendingCheck(state: RunState, why: string): string[] { + const c = state.carry; + if (c?.verdict !== 'check_pending' || !c.check) return []; + release(path.join(state.out, FILES.spend), c.check.attempt); + const out = refuse(state, c.gate_rev, c.from_gate_rev, `delta check ${c.check.attempt} void: ${why}`); + out.check = { ...c.check, status: 'unavailable' }; + return out.lines; +} + +/** The reviewed plan's changes since the copy taken when the owner was asked at `rev`, and their hash. */ +function deltaSince(state: RunState, rev: number): { diff: string; sha: string } | undefined { + const before = atGateCopy(state.out, rev); + if (!fs.existsSync(before)) return undefined; + const diff = lineDiff(fs.readFileSync(before, 'utf8'), fs.readFileSync(state.active_plan, 'utf8')).filter(l => l.op !== ' ').map(l => `${l.op} ${l.text}`).join('\n'); + return { diff, sha: sha256(diff) }; +} + +interface Source { id: string; gate_rev: number; words: string; by?: string } +type Plan = { source: Source; doIt: GateItem[]; deltas: GateItem[] } | { reason: string; from?: number }; + +/** Every condition but the delta check; returns why not, or what the carry takes. */ +function assess(state: RunState, prev: GateList, list: GateList): Plan { + const from = prev.gate_rev; + if (state.carry_forward === false) return { reason: 'carry-forward is off for this run (--no-carry-forward)', from }; + const p1 = readDecisions(state.out).find(r => r.gate_rev === from && (r.label ?? '').toLowerCase() === 'p1'); + if (!p1 || p1.status === 'pending' || !p1.answered_at) return { reason: `gate_rev ${from} was not answered`, from }; + const unanswered = readDecisions(state.out).find(r => r.gate_rev === from && r.status === 'pending'); + if (unanswered) return { reason: `gate_rev ${from} left ${unanswered.label ?? unanswered.id} unanswered`, from }; + if (p1.chosen !== 'a' && p1.chosen !== 'b') return { reason: `gate_rev ${from} answer was p1${p1.chosen}, not an approval`, from }; + if (p1.carried_gate_from) return { reason: `gate_rev ${from} was itself carried; the owner answers this one`, from }; + if (parseReply(p1.reply ?? '', prev).mode !== 'rec') return { reason: `gate_rev ${from} was answered with item tokens, not rec or "do it"`, from }; + const words = p1.owner_reply ?? (p1.answered_by === 'human' ? p1.reply : undefined); + if (!words?.trim()) return { reason: `no owner words recorded at gate_rev ${from}`, from }; + const amendments = (state.amendments ?? []).filter(a => a.gate_rev === from); + const open = amendments.find(a => a.status !== 'incorporated' && a.status !== 'settled'); + if (open) return { reason: `accepted change ${open.decision} is ${open.status}`, from }; + const journalRows = readJournal(state.out); + const at = journalRows.map(r => r.event === 'gate_written' && r.gate_rev === from).lastIndexOf(true); + let expected: string | undefined = at >= 0 ? journalRows[at]!.source_file_sha256 : undefined; + for (const r of journalRows.slice(at + 1)) if (r.event === 'plan_revised') expected = r.source_file_sha256; + if (!expected) return { reason: 'no plan evidence recorded for the gate or the revise (a run written before carry-forward)', from }; + if (fileSha(planFile(state)) !== expected) return { reason: `the plan file ${path.basename(planFile(state))} changed after the owner's answer or the revise that took it`, from }; + if (driftLine(state, 'PLAN_SOURCE_CHANGED')) return { reason: 'the reviewed plan differs from the plan file', from }; + const urgent = readJsonl(path.join(state.out, 'findings.jsonl')).rows.find(r => (r.urgent === true || r.outside_plan === true) && !r.settled_by); + if (urgent) return { reason: `urgent finding open: ${String(urgent.title ?? urgent.id)}`, from }; + const doIt: GateItem[] = []; const deltas: GateItem[] = []; + for (const item of list.items) { + if (item.id === 'p1' || item.carried) continue; + const option = item.options.find(o => o.key === item.recommended); + if (item.cap?.kind === 'delta' && !option?.changes_plan && item.recommended === 'a') { deltas.push(item); continue; } + if (isDoIt(words) && item.kind === 'auto' && !item.cap && !option?.changes_plan && !['scope', 'cost', 'direction'].includes(item.changes ?? '')) { doIt.push(item); continue; } + return { reason: `new item ${item.id}: ${item.title}`, from }; + } + return { source: { id: p1.id, gate_rev: from, words, by: p1.answered_by }, doIt, deltas }; +} + +/** Called by finishGate once gate_rev N+1 is written (status gate_pending): carry, set up the delta check, or say why not. */ +export function evaluateCarry(state: RunState, prev: GateList | undefined, list: GateList): CarryRecord | undefined { + voidPendingCheck(state, `gate_rev ${list.gate_rev} was written`); + if (!prev || list.gate_rev < 2) return undefined; + try { + const plan = assess(state, prev, list); + if ('reason' in plan) return refuse(state, list.gate_rev, plan.from, plan.reason); + if (plan.deltas.length) return dispatchCheck(state, prev, list, plan); + return carry(state, list, plan.source, plan.doIt, plan.deltas); + } catch (e: any) { + if (readDecisions(state.out).some(r => r.gate_rev === list.gate_rev && r.answered_at && !r.carried_from)) throw e; + return refuse(state, list.gate_rev, prev.gate_rev, `error: ${e instanceof RunError ? `${e.detail} (${e.code})` : e?.message ?? e}`); + } +} + +function dispatchCheck(state: RunState, prev: GateList, list: GateList, plan: Extract): CarryRecord { + const rev = list.gate_rev; + const cap = state.carry_check_cap_usd ?? DEFAULT_CARRY_CHECK_CAP_USD; + const estimate = attemptEstimate(state, undefined, process.env).usd; + if (estimate > cap) return refuse(state, rev, prev.gate_rev, `delta check estimate ${estimate.toFixed(2)} is over the per-gate cap ${cap.toFixed(2)} (--carry-check-cap)`); + const delta = deltaSince(state, prev.gate_rev); + if (!delta) return refuse(state, rev, prev.gate_rev, `no copy of the plan the owner answered at gate_rev ${prev.gate_rev}`); + const current = fs.readFileSync(state.active_plan, 'utf8'); + const { diff, sha: deltaSha } = delta; + const attempt = `${state.run}-c${rev}`; + const prompt = path.join(state.out, `carry-check-g${rev}-prompt.md`); + const result = path.join(state.out, `carry-check-g${rev}.md`); + try { reserve(path.join(state.out, FILES.spend), attempt, estimate, { cap: state.spend_cap_usd, label: 'carry-check' }); } + catch (e: any) { return refuse(state, rev, prev.gate_rev, `delta check does not fit the run's spend cap: ${e?.message ?? e}`); } + const accepted = (state.amendments ?? []).filter(a => a.gate_rev === prev.gate_rev).map(a => `- ${a.title} -> ${a.text}`).join('\n') || '- (none recorded)'; + fs.writeFileSync(prompt, [BOUNDARY, '', + `You are checking one edit to a reviewed plan before gstack reuses the owner's approval of gate_rev ${prev.gate_rev} for gate_rev ${rev}. The owner accepted these changes:`, accepted, '', + 'The plan was edited after that answer, but the phases that would re-review the edit were at their round cap, so no reviewer has read it. Read the delta and say whether it implements the accepted changes, adds nothing the owner did not accept (scope, cost or direction), and leaves the plan correct. Rate a finding High or Critical only when the edit adds an unaccepted change, contradicts an accepted one, or would make the plan fail a test, break production, or lose data or secrets; anything else is Medium or lower.', '', + `Delta (reviewed plan at gate_rev ${prev.gate_rev} -> now; + added, - removed; SHA-256 ${deltaSha}):`, '```diff', diff, '```', '', + 'The complete current plan follows as context.', '', current, + REVIEWER_TRAILER, RESULT_FORMAT('carry-check', deltaSha, result)].join('\n')); + const check: CarryCheck = { attempt, prompt, result, delta_sha256: deltaSha, items: plan.deltas.map(i => i.id), estimate_usd: estimate, status: 'dispatched', at: now() }; + const family = state.native_model ? `not ${modelFamily(state.native_model)}` : 'differs from the plan reviewers where available'; + return record(state, { gate_rev: rev, from_gate_rev: prev.gate_rev, verdict: 'check_pending', words: plan.source.words, under_do_it: plan.doIt.map(i => i.id), check, + reason: `only an unreviewed post-cap delta is new (${check.items.join(',')}); one reviewer reads it first`, + lines: [`CARRY_CHECK: attempt=${attempt} items=${check.items.join(',')} prompt=${prompt} result=${result} model_family=${family} estimate=${estimate.toFixed(2)} cap=${cap.toFixed(2)}`, + `NEXT: dispatch one reviewer on the prompt, then gstack-autoplan check --out ${state.out} --attempt ${attempt} --result ${result} --model (or --unavailable "" to relay the gate as today)`] }); +} + +function carry(state: RunState, list: GateList, source: Source, doIt: GateItem[], deltas: GateItem[], check?: CarryCheck): CarryRecord { + const rev = list.gate_rev; + const p1 = list.items.find(i => i.id === 'p1')!; + const reply = list.items.map(i => `${i.id}${i.id === 'p1' ? p1.recommended : i.carried?.chosen ?? i.recommended}`).join(' '); + const reason = [doIt.length || deltas.length ? '' : 'no new choice', doIt.length ? `"do it" covers ${doIt.map(i => i.id).join(',')}` : '', deltas.length ? `delta check passed on ${deltas.map(i => i.id).join(',')}` : '', + 'plan unchanged since the accepted changes'].filter(Boolean).join('; '); + const answered = answerGate(state, rev, reply, 'agent:gstack-autoplan', { carry: { from: source.id, gate_rev: source.gate_rev, words: source.words, by: source.by, reason } }); + const marks = new Map>([...doIt.map(i => [decisionId(list.run, rev, i.id), { carried_under: 'do it' }] as const), ...deltas.map(i => [decisionId(list.run, rev, i.id), { carry_check: check?.attempt ?? '' }] as const)]); + if (marks.size) writeDecisions(state.out, readDecisions(state.out).map(r => (marks.has(r.id) ? { ...r, ...marks.get(r.id) } : r))); + const lines = [`CARRIED: gate_rev=${rev} <- gate_rev=${source.gate_rev} words=${JSON.stringify(source.words)} by=${source.by ?? 'unknown'} reason=${reason}`, + ...doIt.map(i => `CARRIED_UNDER_DO_IT: ${i.id} ${i.title} -> ${i.options.find(o => o.key === i.recommended)?.text ?? i.recommended} (the owner has not seen this item)`), + ...answered.lines]; + return record(state, { gate_rev: rev, from_gate_rev: source.gate_rev, verdict: 'carried', reason, words: source.words, under_do_it: doIt.map(i => i.id), ...(check ? { check } : {}), lines }); +} + +export interface CheckOptions { out: string; attempt?: string; result?: string; model?: string; unavailable?: string; sameFamily?: string } + +/** `gstack-autoplan check`: bind the delta reviewer's result (or its absence) and carry, or leave the gate for the owner. */ +export function submitCarryCheck(o: CheckOptions): { state: RunState; lines: string[] } { + const state = readState(path.resolve(o.out)); + const c = state.carry; + if (!c || c.verdict !== 'check_pending' || !c.check || state.status !== 'gate_pending' || c.gate_rev !== state.gate_rev) throw new RunError('PHASE_NOT_AWAITING', `no delta check is pending (run is ${state.status}, gate_rev=${state.gate_rev ?? 'none'})`, 3); + const check = c.check; + if (o.attempt !== check.attempt) throw new RunError('ATTEMPT_MISMATCH', `pass --attempt ${check.attempt}`, 3); + const stale = readDecisions(state.out).some(r => r.gate_rev === c.gate_rev && r.answered_at && !r.carried_from) ? `the owner answered gate_rev ${c.gate_rev}` + : deltaSince(state, c.from_gate_rev ?? 0)?.sha !== check.delta_sha256 ? 'the plan changed after the delta check was dispatched' : undefined; + if (stale) { + const lines = voidPendingCheck(state, stale); + writeState(state); + return { state, lines }; + } + const gateFile = path.join(state.out, 'gate.json'); + const list = JSON.parse(fs.readFileSync(gateFile, 'utf8')) as GateList; + const spend = path.join(state.out, FILES.spend); + let out: CarryRecord; + if (o.unavailable !== undefined) { + release(spend, check.attempt); + list.carry_check = { attempt: check.attempt, model: 'none', verdict: 'unavailable', max_severity: 'none', findings: 0, at: now() }; + fs.writeFileSync(gateFile, JSON.stringify(list, null, 2) + '\n'); + out = refuse(state, c.gate_rev, c.from_gate_rev, `delta check unavailable: ${o.unavailable}`); + out.check = { ...check, status: 'unavailable' }; + } else { + if (!o.result || !o.model) throw new RunError('RESULT_RECEIPT_MISSING', 'check needs --result and --model , or --unavailable ""', 3); + if (!fs.existsSync(o.result)) throw new RunError('RESULT_RECEIPT_MISSING', `result file not found: ${o.result}`); + const family = modelFamily(o.model); + const author = state.native_model ? modelFamily(state.native_model) : undefined; + if (!o.sameFamily && (family === 'unknown' || family === author)) throw new RunError('MODEL_FAMILY_CONFLICT', `${o.model} is ${family === 'unknown' ? 'of no recognized family' : `the plan reviewers' family (${family})`}; use another family, or pass --same-family ""`, 3); + const text = fs.readFileSync(o.result, 'utf8'); + const parsed = parseReviewResult(text, { phase: 'carry-check', sha256: check.delta_sha256 }); + if (!parsed.receipt.ok) throw new RunError('RESULT_RECEIPT_MISSING', parsed.errors[0]!); + if (!parsed.fenceFound || parsed.errors.length) throw new RunError('RESULT_FINDINGS_MISSING', parsed.errors.join('; ')); + fs.writeFileSync(path.join(state.out, `carry-check-g${c.gate_rev}.bound.md`), text, process.platform === 'win32' ? {} : { mode: 0o444 }); + settle(spend, check.attempt, 'unknown'); + const order = ['Informational', 'Low', 'Medium', 'High', 'Critical']; + const max = parsed.findings.map(f => String(f.severity)).reduce((a, b) => (order.indexOf(b) > order.indexOf(a) ? b : a), 'none'); + const blocking = parsed.findings.find(f => HIGH.includes(String(f.severity))); + const done: CarryCheck = { ...check, status: blocking ? 'failed' : 'passed', model: o.model, max_severity: max, findings: parsed.findings.length, at: now() }; + list.carry_check = { attempt: check.attempt, model: o.model + (o.sameFamily ? ` (same family: ${o.sameFamily})` : ''), verdict: blocking ? 'failed' : 'passed', max_severity: max, findings: parsed.findings.length, at: done.at }; + if (blocking) for (const item of list.items) if (check.items.includes(item.id)) (item.flags ??= []).push(`carry check ${o.model}: ${blocking.severity} ${blocking.title}`); + fs.writeFileSync(gateFile, JSON.stringify(list, null, 2) + '\n'); + if (blocking) { + out = refuse(state, c.gate_rev, c.from_gate_rev, `delta check found ${blocking.severity}: ${blocking.title}`); + out.check = done; + } else { + const plan = assess(state, { ...list, gate_rev: c.from_gate_rev! } as GateList, list); + if ('reason' in plan) { out = refuse(state, c.gate_rev, c.from_gate_rev, plan.reason); out.check = done; } + else { + out = carry(state, list, plan.source, plan.doIt, plan.deltas, done); + out.lines.unshift(`CARRY_CHECK: passed attempt=${check.attempt} model=${o.model} findings=${done.findings} highest=${max}`); + } + } + } + writeState(state); + return { state, lines: out.lines }; +} diff --git a/lib/autoplan-gate.ts b/lib/autoplan-gate.ts index 98b381f4f..1488dbc05 100644 --- a/lib/autoplan-gate.ts +++ b/lib/autoplan-gate.ts @@ -24,7 +24,8 @@ import { consensusRecord, reconcile, remedyKey, renderConsensus, SETTLEABLE_CHAN import type { Phase } from './autoplan-prompts'; import { FILES, RunError, journal as journalRow, now, readDecisions, voiceRows, voiceTerminal, writeDecisions, type Amendment, type RunState, type VoiceState } from './autoplan-state'; import { applyCapChoices, pendingDeltas, releaseUndispatched, roundCap, roundOf } from './autoplan-budget'; -import { capyRelayLine } from './captain-brief'; +import { evaluateCarry, gateEvidence, voidPendingCheck } from './autoplan-carry'; +import { buildEli5, capyRelayLine } from './captain-brief'; import { previousReview, reviewRows, settledIds } from './autoplan-confirm'; import { phaseClose } from './autoplan-timing'; import { ANSWERED_BY_RE, applyReply, decisionId, decisionRows, keepDirection, parseReply, pendingHint, recHash, validateGateList, type GateChoice, type GateItem, type GateList, type GateOption, type ParsedReply } from './gate-list'; @@ -237,7 +238,8 @@ export function buildGate(state: RunState, gateRev: number): GateList { } items.push(...capItems(state, { d: () => `d${++d}`, uc: () => `uc${++uc}` })); items.push(planApproval(state, items)); - const list: GateList = { schema_version: 1, run: state.run, gate_rev: gateRev, items, title: '/autoplan final approval gate', rec_rev: 0 }; + const list: GateList = { schema_version: 1, run: state.run, gate_rev: gateRev, items, title: '/autoplan final approval gate', rec_rev: 0, + ...(fs.existsSync(state.active_plan) ? { eli5: buildEli5(fs.readFileSync(state.active_plan, 'utf8'), state.active_plan) } : {}) }; const problems = validateGateList(list); if (problems.length) throw new Error(`gate list invalid: ${problems.join('; ')}`); return list; @@ -285,9 +287,29 @@ export function recommendGate(state: RunState, gateRev: number, itemId: string, ...[capyRelayLine(state.out)].filter((l): l is string => !!l)]; } -/** Every phase closed: write the gate list, decisions, tasks and the exported files; the run ends gate_pending. Unchanged answered proposals carry forward. */ +/** The gate list the owner last answered: gate.json, or its archive (`gate.r[.v].json`) once a reopen moved it. */ +function previousGate(out: string, rev: number): GateList | undefined { + if (rev < 1) return undefined; + const re = new RegExp(`^gate\\.r${rev}(?:\\.v(\\d+))?\\.json$`); + const archived = fs.readdirSync(out).map(f => [f, re.exec(f)] as const).filter(([, m]) => m).sort((a, b) => Number(b[1]![1] ?? 1) - Number(a[1]![1] ?? 1)).map(([f]) => f); + for (const name of ['gate.json', ...archived]) { + const file = path.join(out, name); + if (!fs.existsSync(file)) continue; + const list = JSON.parse(fs.readFileSync(file, 'utf8')) as GateList; + if (list.gate_rev === rev) return list; + } + return undefined; +} + +/** + * Every phase closed: write the gate list, decisions, tasks and the exported files; the run ends gate_pending. Unchanged + * answered proposals carry forward, and a later revision that asks nothing new carries the owner's last answer + * (lib/autoplan-carry.ts; its lines are on `carryLines(state)`). + */ export function finishGate(state: RunState): GateList { const gateRev = (state.gate_rev ?? 0) + 1; + const gateFile = path.join(state.out, 'gate.json'); + const prev = previousGate(state.out, state.gate_rev ?? 0); const list = buildGate(state, gateRev); const kept = readDecisions(state.out).filter(r => r.gate_rev !== gateRev); const answered = new Map(kept.filter(r => r.origin && r.chosen != null && r.status !== 'pending').map(r => [r.origin!, r])); @@ -295,7 +317,7 @@ export function finishGate(state: RunState): GateList { const prev = item.origin ? answered.get(item.origin) : undefined; if (prev && item.options.some(o => o.key === prev.chosen)) item.carried = { from: prev.carried_from ?? prev.id, chosen: prev.chosen!, gate_rev: prev.gate_rev }; } - fs.writeFileSync(path.join(state.out, 'gate.json'), JSON.stringify(list, null, 2) + '\n'); + fs.writeFileSync(gateFile, JSON.stringify(list, null, 2) + '\n'); const rows = decisionRows(list).map(row => { const item = list.items.find(i => decisionId(list.run, gateRev, i.id) === row.id)!; if (!item.carried) return row; @@ -308,7 +330,8 @@ export function finishGate(state: RunState): GateList { state.status = 'gate_pending'; state.gate = { rev: gateRev, items: list.items.length, written_at: now() }; exportRun(state); - journalRow(state.out, { event: 'gate_written', gate_rev: gateRev, items: list.items.length, carried: list.items.filter(i => i.carried).map(i => i.id) }); + journalRow(state.out, { event: 'gate_written', gate_rev: gateRev, items: list.items.length, carried: list.items.filter(i => i.carried).map(i => i.id), ...gateEvidence(state, gateRev) }); + evaluateCarry(state, prev, list); return list; } @@ -321,6 +344,8 @@ export interface AnswerOptions { recHash?: string; /** The owner's verbatim words; required for every `--by agent:` answer. */ ownerReply?: string; + /** A whole-gate carry (lib/autoplan-carry.ts): the earlier p1 decision and the owner's words it reuses. Replaces ownerReply and its re-parse. */ + carry?: { from: string; gate_rev: number; words: string; by?: string; reason: string }; } /** How an accepted plan change is discharged: a packaging/ordering change settles without a plan edit. */ @@ -361,7 +386,7 @@ export function answerGate(state: RunState, gateRev: number, reply: string, answ if (state.status !== 'gate_pending' || !fs.existsSync(gateFile)) throw new RunError('PHASE_NOT_AWAITING', `run is ${state.status}, not gate_pending`, 3); if (answeredBy !== undefined && !ANSWERED_BY_RE.test(answeredBy)) throw new RunError('ANSWER_BY_REQUIRED', `--by ${JSON.stringify(answeredBy)} is neither human nor agent:`, 3); if (answeredBy === undefined && state.session_kind === 'unattended') throw new RunError('ANSWER_BY_REQUIRED', 'an unattended run records who answered; pass --by human or --by agent:', 3); - if (answeredBy?.startsWith('agent:') && o.ownerReply === undefined) throw new RunError('OWNER_REPLY_REQUIRED', `${answeredBy} relayed or decided this reply; pass the owner's words verbatim with --owner-reply "" (or --owner-reply - / --owner-reply-file )`, 3); + if (answeredBy?.startsWith('agent:') && o.ownerReply === undefined && !o.carry) throw new RunError('OWNER_REPLY_REQUIRED', `${answeredBy} relayed or decided this reply; pass the owner's words verbatim with --owner-reply "" (or --owner-reply - / --owner-reply-file )`, 3); const list = JSON.parse(fs.readFileSync(gateFile, 'utf8')) as GateList; const rows = readDecisions(state.out); const prior = Object.fromEntries(rows.filter(r => r.gate_rev === list.gate_rev && r.chosen != null && r.status !== 'pending' && r.label).map(r => [r.label!.toLowerCase(), r.chosen!])); @@ -372,12 +397,13 @@ export function answerGate(state: RunState, gateRev: number, reply: string, answ if (o.recHash !== undefined && o.recHash !== currentHash) throw new RunError('GATE_REC_STALE', `--rec-hash ${o.recHash} was rendered before the recommendations changed; current rec_hash=${currentHash}`, 3); if (parsed.mode === 'rec' && list.rec_rev === undefined && o.recHash === undefined) throw new RunError('GATE_REC_STALE', `this gate was written before \`rec\`/\`all\` took plan changes (gate.json has no rec_rev), so the owner saw a different meaning; render it again (gstack-gate render ${gateFile} --all), relay it, and answer with --rec-hash ${currentHash}, or reply with explicit