mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-17 05:41:50 +01:00
Merge commit '0c84f4ee14c32734313e68b700417e0748ad1d55' into capy/gst620-sealed-identifiers
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> # Conflicts: # test/helpers/free-fixtures-data.ts
This commit is contained in:
commit
c0d1482b05
568 files changed
+36850
-8414
No files matched your search
+609
-30
@@ -314,6 +314,20 @@ network.
|
||||
|
||||
**Expected result.** `OUTSIDE_STATUS: completed`.
|
||||
|
||||
<a id="outside-review-truncated"></a>
|
||||
### `... outside review unavailable: the reviewer hit its output token limit and the response is cut off (...)`
|
||||
|
||||
**Meaning.** The api runner's provider stopped at the output token limit
|
||||
(Anthropic `stop_reason: max_tokens`, OpenAI `finish_reason: length`), so the
|
||||
review ends mid-sentence and its findings may be missing.
|
||||
|
||||
**Fix.** Re-run with a larger `--max-tokens` (`gstack-outside-voice run` or
|
||||
`gstack-autoplan run`), or shorten the prompt. `gstack-autoplan run` sends a
|
||||
default of 16384 to both providers, and OpenAI counts reasoning tokens toward
|
||||
it; `gstack-outside-voice run` sends that default to Anthropic only.
|
||||
|
||||
**Expected result.** `OUTSIDE_STATUS: completed`.
|
||||
|
||||
<a id="outside-review-missing-markers"></a>
|
||||
### `... outside review unavailable: the response lacks the markers this gate requires (...)`
|
||||
|
||||
@@ -550,6 +564,25 @@ local `origin/<base>` at `<rev>`.
|
||||
**Fix.** Run `git fetch origin <base>` outside the sandbox and rerun /review if
|
||||
the base has moved.
|
||||
|
||||
<a id="review-content-changed"></a>
|
||||
### `review_freshness: STALE content changed during review: the tree moved from <start> to <end> while <skill> ran ...` / **Review records missing or mismatched**
|
||||
|
||||
**Meaning.** The working tree changed between the pass's `gstack-review-log --start` and
|
||||
its logged row: an edit, commit or merge landed while reviewers were still reading. The
|
||||
reviewers may not have seen that change, so the row's `review_binding.state` is `changed`.
|
||||
Step 11.5 cannot bind it and inserts `9 → 10 → 11 → 11.5`. Logging the same results again
|
||||
cannot repair it.
|
||||
|
||||
**Fix.** Keep the checkout frozen (no edits, commits, merges or pushes) from a pass's start
|
||||
until every reviewer in it has returned and its row is logged. If the mid-pass change was
|
||||
your own fix to that pass's findings, log the pass with `"converged":false` and the fix
|
||||
as `"action":"fixed"`. `gstack-review-plan` then picks the repeat: one fix-check reading
|
||||
the touched hunks when every fix is below the blocking floor, and 11.5 accepts that
|
||||
fix-check record as Step 9's. Rerun Step 11's native pass on the same frozen tree.
|
||||
|
||||
**Expected result.** `gstack-review-read` shows both records at one tree with
|
||||
`review_freshness` `CURRENT`, and Step 11.5 continues to Step 12.
|
||||
|
||||
<a id="review-fingerprint-tmpdir"></a>
|
||||
### `gstack-wtree: cannot create a temp index under <dir>; set TMPDIR to a writable directory` / `gstack-review-log: cannot create a private object directory under <dir>; no working-tree fingerprint. Set TMPDIR to a writable directory.`
|
||||
|
||||
@@ -755,13 +788,67 @@ If the message names a missing timeout tool, install coreutils (`gtimeout`) or p
|
||||
**Expected result.** The next design skill prints `DESIGN_READY`.
|
||||
|
||||
<a id="design-image-model-invalid"></a>
|
||||
### `GSTACK_DESIGN_IMAGE_MODEL="<value>" is not a gpt-image model name (expected something like gpt-image-2); fix it or unset it to use gpt-image-2`
|
||||
### `GSTACK_DESIGN_IMAGE_MODEL="<value>" is not a gpt-image model name ...` (or `... is not a Gemini model name, and the design provider is gemini`)
|
||||
|
||||
**Meaning.** The design binary refuses an image tool model override that is not
|
||||
a `gpt-image-*` model name, before sending any request.
|
||||
**Meaning.** The design binary refuses a model override that does not fit the
|
||||
picked provider, before sending any request. On OpenAI the image tool model
|
||||
must be a `gpt-image-*` name; on Gemini, `GSTACK_DESIGN_IMAGE_MODEL` and
|
||||
`GSTACK_DESIGN_MODEL` must be `gemini-*` names. A Gemini 404 for a model also
|
||||
points here.
|
||||
|
||||
**Fix.** `export GSTACK_DESIGN_IMAGE_MODEL=gpt-image-2` (or another gpt-image
|
||||
model your key can use), or `unset GSTACK_DESIGN_IMAGE_MODEL`.
|
||||
**Fix.** `unset GSTACK_DESIGN_IMAGE_MODEL GSTACK_DESIGN_MODEL` to use the
|
||||
defaults, or set models the picked provider and your key can use.
|
||||
|
||||
<a id="design-no-image-key"></a>
|
||||
### `No image API key found (OpenAI or Gemini).`
|
||||
|
||||
**Meaning.** `$D` found neither an OpenAI key (`~/.gstack/openai.json`,
|
||||
`OPENAI_API_KEY`) nor a Gemini key (`~/.gstack/gemini.json`,
|
||||
`GEMINI_API_KEY`). Design skills fall back to HTML wireframes.
|
||||
|
||||
**What is kept.** Nothing was sent or spent.
|
||||
|
||||
**Fix.** Get a free Gemini key at https://aistudio.google.com/apikey, then
|
||||
`export GEMINI_API_KEY=<key>` or `printf %s "$KEY" | $D setup --provider gemini --key-stdin`.
|
||||
|
||||
**Expected result.** The next design command prints `Using Gemini key from ...`.
|
||||
|
||||
<a id="design-provider-invalid"></a>
|
||||
### `GSTACK_DESIGN_PROVIDER="<value>" is not a design provider (expected openai or gemini).`
|
||||
|
||||
**Fix.** `export GSTACK_DESIGN_PROVIDER=gemini` (or `openai`), or
|
||||
`unset GSTACK_DESIGN_PROVIDER` to let `$D` pick (OpenAI when its key is set,
|
||||
else Gemini).
|
||||
|
||||
<a id="design-provider-no-key"></a>
|
||||
### `GSTACK_DESIGN_PROVIDER=<provider> but no <Provider> key was found`
|
||||
|
||||
**Meaning.** You picked a provider explicitly and it has no key, so `$D`
|
||||
stopped before any request instead of quietly using the other one.
|
||||
|
||||
**Fix.** Set that provider's key (`GEMINI_API_KEY` or `OPENAI_API_KEY`), run
|
||||
`$D setup --provider <provider>`, or unset `GSTACK_DESIGN_PROVIDER`.
|
||||
|
||||
<a id="design-gemini-key-rejected"></a>
|
||||
### `Gemini API error (400|403, model <model>, key from <source>): ...`
|
||||
|
||||
**Meaning.** Google rejected the key (`API_KEY_INVALID`), or the key's Google
|
||||
Cloud project has the Generative Language API turned off. The message names
|
||||
where the key came from, never the key.
|
||||
|
||||
**Fix.** Create a key at https://aistudio.google.com/apikey and run
|
||||
`$D setup --provider gemini`, or enable the Generative Language API for the
|
||||
key's project. To use OpenAI instead: `export GSTACK_DESIGN_PROVIDER=openai`.
|
||||
|
||||
<a id="design-gemini-quota"></a>
|
||||
### `Gemini API error (429 ...): ... no image quota left today`
|
||||
|
||||
**Meaning.** The key's daily quota for the model is used up, or the key is on a
|
||||
free tier with no quota for image models. `$D` does not retry this; a
|
||||
short-term 429 is retried after Google's suggested delay.
|
||||
|
||||
**Fix.** Enable billing for the key in Google AI Studio, wait for the daily
|
||||
reset, or `export GSTACK_DESIGN_PROVIDER=openai`.
|
||||
|
||||
<a id="design-taste-profile-unavailable"></a>
|
||||
### `TASTE_PROFILE_UNAVAILABLE: could not resolve the project slug (gstack-slug failed). Fix: run ./setup.`
|
||||
@@ -793,7 +880,11 @@ pick a new `--output`), then copy the recovery file to where you want it.
|
||||
**Meaning.** On Codex, Factory, OpenCode, Cursor, Copilot and Kiro every bash
|
||||
block finds gstack on its own: an exported `GSTACK_ROOT` (with `bin/` and
|
||||
`lib/`), then a repo-local install, then the host's global install
|
||||
(`$CODEX_HOME/skills/gstack` on Codex). None existed.
|
||||
(`$CODEX_HOME/skills/gstack` on Codex). None existed. A skill installed for one
|
||||
folder (Hermes, or the Codex install `./setup` writes) is the exception for its
|
||||
first block: that block runs the folder's own `bin/gstack-skill-start` and
|
||||
ignores an exported `GSTACK_ROOT`. When the folder is missing, the block prints
|
||||
this line and its start command then fails.
|
||||
|
||||
**Fix.**
|
||||
|
||||
@@ -1109,6 +1200,28 @@ conflict yourself instead, finish or abort your merge (`git -C '<dir>' merge
|
||||
--abort`, `git -C '<dir>' checkout -- <file>`); gstack retries at the next
|
||||
check.
|
||||
|
||||
<a id="auto-update-tracked-by-project"></a>
|
||||
### `gstack auto-update: update held (tracked-by-project: ...)` / `(version-reverted: ...)` / `gstack-upgrade: tracked-by-project: ... (UPGRADE_REFUSED)` / `gstack-upgrade: version-reverted: ... (UPGRADE_REFUSED)`
|
||||
|
||||
**Meaning.** Your gstack install sits inside another git project, and that
|
||||
project has committed gstack's files as ordinary files. Every time you switch
|
||||
branches or check out files in that project, git puts its old copies of
|
||||
gstack's files back, so VERSION and other files fall behind the install's own
|
||||
HEAD while updates seem to succeed (#1022). `version-reverted` is the same
|
||||
symptom seen from the install: its VERSION disagrees with HEAD. Neither
|
||||
`gstack-upgrade`, `/gstack-upgrade` nor the auto-updater moves the install
|
||||
until it is fixed. A project that holds gstack as a git submodule is fine.
|
||||
`version-reverted` with no enclosing project means VERSION was edited by
|
||||
hand; only the `stash push` step below applies.
|
||||
|
||||
**Fix.** Print the exact commands with
|
||||
`bash <install>/bin/gstack-ff-update --preflight <install>`. They do three
|
||||
things: untrack the install in the project (`git rm -r --cached`), add it to
|
||||
the project's `.gitignore`, and commit both on every branch you check out
|
||||
(or vendor gstack as a submodule instead). Then
|
||||
`git -C <install> stash push` puts the install's own files back and keeps
|
||||
any edit you made in the stash, and the next update proceeds.
|
||||
|
||||
<a id="auto-update-autostash-unrecoverable"></a>
|
||||
### `gstack auto-update: update held (autostash-unrecoverable: <reason>); your local edits are where they were and nothing was installed. Look first: git -C '<dir>' status --short. Fix now (...)` / `autostash-unrecoverable: <reason>`
|
||||
|
||||
@@ -1163,8 +1276,8 @@ git -C ~/.claude/skills/gstack update-ref -d 'refs/gstack/rescue/<oid>'
|
||||
<a id="setup-runtime-root-contains-checkout"></a>
|
||||
### `gstack setup: refusing to replace <root> for <host>: this runtime directory contains the source checkout setup runs from (<checkout>), so replacing it would delete the checkout. Nothing was changed.`
|
||||
|
||||
**Meaning.** Setup installs Codex, Factory, OpenCode, Cursor, Copilot and
|
||||
Antigravity by building a runtime root (such as `~/.cursor/skills/gstack`) and
|
||||
**Meaning.** Setup installs Codex, Factory, OpenCode, Cursor, Copilot,
|
||||
Antigravity and Gemini CLI by building a runtime root (such as `~/.cursor/skills/gstack`) and
|
||||
swapping it in for the old one, and Kiro by writing into `~/.kiro/skills/gstack`.
|
||||
Your gstack checkout lives at that root or inside it, so the swap would delete
|
||||
the checkout (#3084), and Kiro would link the checkout into itself. Setup refuses before
|
||||
@@ -1551,6 +1664,8 @@ directory is not a gstack checkout, HEAD is detached or on another branch (a
|
||||
pin), a tracked file is modified, a local commit is not on the remote branch,
|
||||
the incoming release's Bun floor is above the Bun on PATH, or another updater
|
||||
holds `<state root>/.setup-lock`. It never stashes, resets or discards.
|
||||
A `tracked-by-project` or `version-reverted` cause has its own section:
|
||||
[an enclosing project tracks the install](#auto-update-tracked-by-project).
|
||||
|
||||
**Fix.** Resolve the named cause with the printed command (commit or move the
|
||||
listed changes, check out the default branch, move local commits to another
|
||||
@@ -1864,6 +1979,18 @@ owner's call: run the printed `RECOVER:` line; its resume needs
|
||||
**Fix.** In the execute program that runs the command, read
|
||||
`(await tools.thread.get({ thread_id: "<your own jam id>" })).cost.tokens` and pass it as `--reading <n>`.
|
||||
|
||||
<a id="meter-scope-parent"></a>
|
||||
### `gstack-ship-budget: ... (METER_SCOPE_PARENT)`
|
||||
|
||||
**Meaning.** `start` was told the run is a subagent (`--subagent` or `GSTACK_SHIP_SUBAGENT=1`) reading
|
||||
`"this"` (`--reading-from this`), the root thread's counter, which also holds every sibling lane, and
|
||||
asked for `--meter-scope self`. A self scope would print that counter as the run's own cost. Exit 2;
|
||||
no run started.
|
||||
|
||||
**Fix.** Start with `--meter-scope tree`. Every cost line then prints
|
||||
`METER: tree (root counter, upper bound)`. Exact per-run cost comes from a root replay thread
|
||||
(`docs/ship-budget.md`).
|
||||
|
||||
<a id="budget-reading-rejected"></a>
|
||||
### `gstack-ship-budget: ... (BUDGET_READING_REJECTED)`
|
||||
|
||||
@@ -2128,6 +2255,25 @@ anything.
|
||||
|
||||
---
|
||||
|
||||
<a id="setup-deps-migrate-failed"></a>
|
||||
### `gstack: WARN kept the full dependency install (SETUP_DEPS_MIGRATE_FAILED; ...): <cause>`
|
||||
|
||||
**Meaning.** Your install was made before v1.91.231.0, so it still carries the
|
||||
test and eval packages (about 520 MB, mostly the Claude Agent SDK). setup moved
|
||||
`node_modules` aside to install production dependencies only, that install
|
||||
failed, and setup put the full `node_modules` back. Nothing was removed, and
|
||||
gstack keeps working on the full install.
|
||||
|
||||
**Fix.** Fix the cause the warning names (no network, a proxy, a full disk),
|
||||
then run `./setup` again. Developing gstack in this checkout? Mark it, and
|
||||
setup keeps the dev packages from then on:
|
||||
|
||||
```bash
|
||||
git config gstack.contributor true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
<a id="chromium-install-exit-127"></a>
|
||||
### `Chromium bootstrap: chromium-install — <bun> x playwright install chromium exited 127 (command not found); install Bun from bun.sh (winget Bun ships no bunx), or skip with ./setup --no-browser (Git Bash) or .\setup.ps1 --no-browser (PowerShell)`
|
||||
|
||||
@@ -2818,6 +2964,34 @@ fetching it cannot create that ref, so pass a branch that exists on `origin`
|
||||
(`git branch -r --list 'origin/*'` lists them). `gstack-pregate` says so in
|
||||
its fix instead of suggesting the fetch.
|
||||
|
||||
<a id="history-read-failed"></a>
|
||||
### `cannot read <path> at <ref>. <cause> (git version <v>). Fix: see docs/troubleshooting.md#history-read-failed (HISTORY_READ_FAILED)`
|
||||
|
||||
**Meaning.** A CI job or a local release tool read a file at an older commit
|
||||
and git could not produce it. The PR and train path jobs (Free Tests' plan, the Version Gate,
|
||||
and E2E Evals' route, screen summary, planner, slices, reruns, bisect and
|
||||
report) check out blobless clones (`filter: blob:none`): every commit and
|
||||
tree is there, but an older file's contents are fetched from GitHub the first
|
||||
time something reads them. When that fetch fails three times (a GitHub outage,
|
||||
a network drop), or the ref does not resolve at all, the read fails here
|
||||
instead of counting as "the file is absent". A file the commit really does not
|
||||
have still reads as absent, as before. No ship policy at the base means no
|
||||
train, and no VERSION means `0.0.0.0`. The route and backstop policy reads (inline
|
||||
in their workflows), `.github/scripts/history-read.sh` (the Version Gate's base
|
||||
`VERSION`) and `lib/history-read.ts` (the Version Gate's train classification)
|
||||
print this line. The Version Gate prints the same code when
|
||||
`git fetch origin <base>` fails three times. `gstack-restamp` and
|
||||
`gstack-ship-queue land` print it too when they cannot read the base branch's
|
||||
CHANGELOG, which they check fragments against (`lib/changelog-fragments.ts`
|
||||
reads it through `lib/history-read.ts`); outside a partial clone they do not
|
||||
retry.
|
||||
|
||||
**Fix.** Rerun the failed job once GitHub is reachable. If it fails the same
|
||||
way on a healthy network, check that the ref exists on `origin` and that the
|
||||
runner's git supports partial clone (`git --version` 2.22 or newer; the eval
|
||||
image asserts it at build time in `.github/docker/Dockerfile.ci`). For a local
|
||||
tool, run `git fetch origin <base>` and rerun it.
|
||||
|
||||
<a id="policy-invalid"></a>
|
||||
### `POLICY_INVALID`
|
||||
|
||||
@@ -3003,9 +3177,14 @@ or pass `--force-gate <reason>` in `/ship` to run the full gate again.
|
||||
**Meaning.** The bundle (or ledger record) lacks a committed tree id, runtime
|
||||
versions, lockfile hashes or the command hash, so no reuse decision can rest on
|
||||
it. Imported assertions without verification count as unknown too.
|
||||
`gstack-tree-receipt` also fails with this code when git cannot produce the
|
||||
diff between the gated and current heads (a missing object, a timeout): the
|
||||
error names git's reason, and a failed diff is never read as no change.
|
||||
|
||||
**Fix.** Rebuild the bundle on the gate machine after the lanes ran on a
|
||||
committed head: `gstack-evidence bundle --out <file> --label <lane>...`.
|
||||
committed head: `gstack-evidence bundle --out <file> --label <lane>...`. For
|
||||
the tree receipt, fix what git's reason names (fetch a missing head with
|
||||
`git fetch origin <sha>`), then rerun.
|
||||
|
||||
<a id="evidence-bundle-invalid"></a>
|
||||
### `EVIDENCE_BUNDLE_INVALID`
|
||||
@@ -3102,6 +3281,42 @@ result.
|
||||
**Fix.** Run `gstack-autoplan status --out <dir>` and submit for the attempt
|
||||
the last `next` printed (`ATTEMPT: ... phase=<p> voice=<v>`).
|
||||
|
||||
<a id="ceo-only-conflict"></a>
|
||||
### `CEO_ONLY_CONFLICT`
|
||||
|
||||
**Meaning.** `gstack-autoplan next --ceo-only` was combined with `--ui`,
|
||||
`--developer-tool` or `--agent-primary` (on the command line or in the plan's
|
||||
`gstack-autoplan-scope` marker), each of which adds a phase a CEO-only run
|
||||
never opens; or the marker names `--ceo-only` (the mode is a command-line
|
||||
choice for one run, so a plan can't pin it); or the plan is `<out>/ceo-review.md`
|
||||
(directly, through a symlink or a hard link), the report the run would write
|
||||
over it. The finish checks that last case again before it writes the report.
|
||||
|
||||
**Fix.** Drop the conflicting flag (or the marker token), move the plan out of
|
||||
the report path, or run the full review without `--ceo-only`.
|
||||
|
||||
<a id="ceo-only-after-init"></a>
|
||||
### `CEO_ONLY_AFTER_INIT`
|
||||
|
||||
**Meaning.** `next --ceo-only` named a run directory that already holds a full
|
||||
review run. A run keeps the mode it started with.
|
||||
|
||||
**Fix.** Start the CEO-only run in a new `--out` directory, passing
|
||||
`--ceo-only` on its first `next`.
|
||||
|
||||
<a id="ceo-only-no-gate"></a>
|
||||
### `CEO_ONLY_NO_GATE`
|
||||
|
||||
**Meaning.** `answer`, `recommend` or `revise` was run on a CEO-only run, or
|
||||
`gstack-approvals import` was pointed at one. A CEO-only
|
||||
run writes no gate, ends `status=reviewed` and is never approved, so there is
|
||||
nothing to answer, change or import. (`budget` and `close --deferred` still
|
||||
work: they are how a budget-stopped CEO-only run recovers.)
|
||||
|
||||
**Fix.** Read `<run dir>/ceo-review.md`. For a gate and an approval, start a
|
||||
full review in a new directory: `gstack-autoplan next --out <new dir> --plan
|
||||
<file>` without `--ceo-only`.
|
||||
|
||||
<a id="attempt-mismatch"></a>
|
||||
### `ATTEMPT_MISMATCH`
|
||||
|
||||
@@ -3229,6 +3444,54 @@ makes the row a check rather than a claim.
|
||||
`REALITY: already-done pass 0 hits since 2026-10-09 for bin/gstack-doctor 91bbd9e`
|
||||
or `REALITY: surface-check finding bun upgrade --version absent on 1.3.14 bin/gstack-capy-install:52`.
|
||||
|
||||
<a id="office-hours-probe-refused"></a>
|
||||
### `OFFICE_HOURS_PROBE_REFUSED`
|
||||
|
||||
**Meaning.** The office-hours spec reviewer may check a cited flag with
|
||||
`gstack-office-hours-review probe --help <command> [<subcommand>]`, and nothing
|
||||
else runs. The command must be a gstack bin or one of the listed read-only CLIs
|
||||
(git, gh, bun, node, npm, pnpm, yarn, jq, rg, python3, uv, go, cargo, make,
|
||||
docker, claude, codex, gemini), found on PATH outside the repository; a gstack
|
||||
bin must handle `--help`. Subcommand words are allowed for git, gh,
|
||||
docker, cargo, go, npm and uv (one word for git, cargo and npm; up to two for gh, docker, go and uv), each from that CLI's list of built-in names in
|
||||
`lib/office-hours-probe.ts`; words that run a named program, script, image or
|
||||
extension (`uv run`, `docker run`, `go test`, `npm exec`, a gh extension) are
|
||||
refused. The probe never runs a shell or a repository-local program (PATH
|
||||
entries inside the repository are dropped), closes stdin, runs in an empty
|
||||
temporary directory, passes no keys or tokens in its environment and stops after
|
||||
10 seconds.
|
||||
|
||||
**Fix.** Nothing to repair. The claim stays unverified, not disproved; check it
|
||||
from the command's source or docs in the repository instead.
|
||||
|
||||
<a id="tasks-supersede-refused"></a>
|
||||
### `TASKS_SUPERSEDE_REFUSED`
|
||||
|
||||
**Meaning.** `gstack-tasks` refused a task list. Either `add` found a line in
|
||||
the rows file (`.gstack/tmp/tasks-<phase>-rows.jsonl`) that is not a valid
|
||||
task or disposition, or it leaves a task from the branch's earlier list neither
|
||||
carried nor closed (the error names each `<run_id>/<id>`), so nothing was written; or `supersede` was asked to retire the earlier lists
|
||||
but the new list (`--keep`) is missing, outside the tasks directory, has a
|
||||
malformed line, or holds a row for another phase or branch, so nothing was
|
||||
moved and both lists stay live.
|
||||
|
||||
**Fix.** Fix the line the error names in the rows file (`gstack-tasks --help`
|
||||
shows both row shapes), and rerun `gstack-tasks add --phase <phase>`.
|
||||
|
||||
<a id="reality-receipt-unresolved"></a>
|
||||
### `REALITY_RECEIPT_UNRESOLVED`
|
||||
|
||||
**Meaning.** `gstack-plan-reality check` opened a receipt and it is false in
|
||||
the checkout: the file is missing, it is a directory or a dangling link, the
|
||||
line is 0 or the range runs backward, or the cited line is past its end. The `RECEIPT_UNRESOLVED: <row> <receipt> <reason>` line names each
|
||||
one. A receipt the checkout cannot judge (a path outside every root, a bare
|
||||
file name no root has, a sha a shallow clone lacks) prints
|
||||
`RECEIPT_UNVERIFIABLE:` instead and never blocks.
|
||||
|
||||
**Fix.** Open the file and cite the line that holds the evidence. When the
|
||||
evidence lives in another checkout, run `check` with `--root <dir>` for it
|
||||
(repeatable; the default is the git top level of the working directory).
|
||||
|
||||
## Pre-gate: generated-file registry, gstack-pregate, issue links
|
||||
|
||||
Both tools read their pin file (`.gstack/generated.json`, `.gstack/pregate.json`)
|
||||
@@ -3388,9 +3651,12 @@ never runs them: declare `"**/integration_test/**": []` (and
|
||||
them. A `[]` declaration added only on the branch is refused under
|
||||
`--policy-from head` ([`PREGATE_HEAD_POLICY_LOOSENS`](#pregate-head-policy-loosens)),
|
||||
so land it in its own PR first.
|
||||
With no policy anywhere (no base copy, no user-owned file) an unmapped file is
|
||||
With no policy anywhere (no base copy, no user-owned file), or a policy with no
|
||||
`dependencies`, `empty_lanes`, `selection` or `local` key (a timeout-only file), an unmapped file is
|
||||
the warning [`PREGATE_NO_POLICY`](#pregate-no-policy) with a starter policy
|
||||
printed, not this error; `gstack-pregate init` writes that draft and lists the
|
||||
printed, not this error. Under `warn: ["lanes"]` it is a `warn` with this code,
|
||||
given only after the selected tests ran green (a red lane is still
|
||||
`PREGATE_LANE_FAILED`); `gstack-pregate init` writes that draft and lists the
|
||||
files it could not place. `--explain` prints every mapping and why. For a file with no lane it also prints the import
|
||||
specifiers in test files that resolved to no repo file (for example a
|
||||
`tsconfig.json` `paths` alias such as `@/lib/x` whose target is missing) and any
|
||||
@@ -3528,8 +3794,9 @@ differing path is a change.
|
||||
### `PREGATE_NO_POLICY`
|
||||
|
||||
**Meaning.** The repository has no pregate policy yet (no `.gstack/pregate.json`
|
||||
on the base branch and no user-owned `<state root>/projects/<slug>/pregate.json`)
|
||||
and a touched file maps to no test lane. Under no policy that is a `warn`, not
|
||||
on the base branch and no user-owned `<state root>/projects/<slug>/pregate.json`),
|
||||
or its policy declares no lanes (no `dependencies`, `empty_lanes`, `selection` or `local` key, a
|
||||
timeout-only file for example), and a touched file maps to no test lane. Under no policy that is a `warn`, not
|
||||
`PREGATE_NO_LANE`: the selected tests still ran (a red lane is still `fail`),
|
||||
and the table printed a starter policy drafted from the repository
|
||||
(`PREGATE_STARTER:` lines: runner, test directories, CI lanes, the JSON between
|
||||
@@ -3540,7 +3807,8 @@ Details: [docs/pregate.md](pregate.md#no-policy).
|
||||
overwrite an existing file without `--force`), edit each `TODO` (a test that
|
||||
names the file, a `dependencies` entry, or `[]` for a file with no behaviour),
|
||||
run `gstack-pregate validate`, then commit `.gstack/pregate.json` on the base
|
||||
branch. From then on an unmapped file is `PREGATE_NO_LANE`.
|
||||
branch. When a policy already exists, add the starter's `dependencies` to it
|
||||
instead. From then on an unmapped file is `PREGATE_NO_LANE`.
|
||||
|
||||
<a id="pregate-environment"></a>
|
||||
### `PREGATE_ENVIRONMENT`
|
||||
@@ -3685,6 +3953,21 @@ goes beside the variants. When no arm loads a skill stack, write
|
||||
`stack: none` with a `why:` line instead. The rule is in
|
||||
[docs/TESTING_INTERNALS.md](TESTING_INTERNALS.md#no-gstack-arm).
|
||||
|
||||
<a id="eval-report-no-gstack-row"></a>
|
||||
### `EVAL_REPORT_NO_GSTACK_ROW`
|
||||
|
||||
**Meaning.** `gstack-eval-plan results --check <prereg> <results>` found no
|
||||
single markdown table in the results file with a filled row for every arm
|
||||
identity the preregistration's Arms section lists. Usually the
|
||||
`<model>#no-gstack` row is missing, sits in a separate table from its
|
||||
variants, or holds only placeholders (`-`, `n/a`, `tbd`). It also fires when
|
||||
the preregistration itself fails `prereg --check`.
|
||||
|
||||
**Fix.** Put one row per arm identity, each no-gstack arm beside its variants,
|
||||
in one table, and rerun the check. Publish no number before it prints
|
||||
`RESULTS: ok`. A preregistration with `stack: none` needs no row. The rule is
|
||||
in [docs/TESTING_INTERNALS.md](TESTING_INTERNALS.md#no-gstack-arm).
|
||||
|
||||
<a id="eval-arm-duplicate"></a>
|
||||
### `EVAL_ARM_DUPLICATE`
|
||||
|
||||
@@ -4366,7 +4649,10 @@ train still building, running or merging, `train watch` on an unknown record,
|
||||
unreadable run), `verify --pr <n> --train <nonce>` when main's tree mismatches
|
||||
and whether a slot merged on GitHub cannot be read (so whether the queue must
|
||||
freeze is unknown; it never answers "nothing merged" from an unreadable
|
||||
state), `train land` when the base or the train branch cannot be fetched or
|
||||
state), `verify --pr <n> --train <nonce>` when GitHub does not report the PR
|
||||
MERGED and it is not a release-only PR whose stamp-only diff already matches
|
||||
main, or when it could not read the PR's current head (`--no-fetch` or a failed
|
||||
fetch), without freezing the queue, `train land` when the base or the train branch cannot be fetched or
|
||||
the record's T0 and S_1..S_k are not the gated head's first-parent chain
|
||||
(each S_i's second parent slot i's pin), `train land` when main's tree is the
|
||||
slot's S_i but GitHub does not report the PR as MERGED (a record whose slot
|
||||
@@ -4472,14 +4758,60 @@ the name already landed. Then rerun.
|
||||
<a id="queue-land-locked"></a>
|
||||
### `QUEUE_LAND_LOCKED`
|
||||
|
||||
**Meaning.** Another `gstack-ship-queue land` holds the repository land lock
|
||||
(`refs/notes/gstack-land`), or took it from under this run, so this one would
|
||||
race it for the next version. The line names the holder, its PR and phase.
|
||||
**Meaning.** Another `gstack-ship-queue land`, or a `train land` slot, holds the
|
||||
repository land lock (`refs/notes/gstack-land`), or took it from under this run,
|
||||
so this one would race it onto main. The line names the holder: `#<pr>` for a
|
||||
land, `train <nonce> slot <i> (#<pr>)` for a train, with its holder and phase. A
|
||||
train keeps the lock in phase `between` from one merged slot to the next, so no
|
||||
standalone land slips in between slots.
|
||||
|
||||
**Fix.** Wait for the holder to finish. If it crashed, rerun with
|
||||
`--break-lock`; that is refused while the holder entered a push or a merge
|
||||
less than 10 minutes ago. A lock in phase `drift` is released by landing its
|
||||
repair PR ([QUEUE_LAND_DRIFT](#queue-land-drift)).
|
||||
`--break-lock`, which prints the holder (`LOCK_HOLDER:`). That is refused while
|
||||
the holder entered a push or a merge less than 10 minutes ago, while a train is
|
||||
between slots for less than 10 minutes, and for a live train run unless you also
|
||||
pass `--break-train-lock`. A lock in phase `drift` is released by landing its
|
||||
repair PR ([QUEUE_LAND_DRIFT](#queue-land-drift)); a lock in phase `freeze` is
|
||||
released by the verify that clears the freeze
|
||||
([QUEUE_TRAIN_FROZEN](#queue-train-frozen)). If that release push failed, the
|
||||
next `land` or `train land` takes the lock over once the freeze record it fetches
|
||||
shows the freeze cleared after the lock was written; `--break-lock` never does.
|
||||
|
||||
<a id="queue-train-unstamped"></a>
|
||||
### `QUEUE_TRAIN_UNSTAMPED`
|
||||
|
||||
**Meaning.** `verify --pr <n> --train <nonce>` found the slot head it would let
|
||||
merge without its own stamp: the head's `VERSION` is not above main's, or its
|
||||
CHANGELOG's top section is not headed with that version directly above main's
|
||||
top release (or keeps an `[Unreleased]` section main does not have). The line
|
||||
names the rule, the head's version and main's. Train 33 merged #3527 this way
|
||||
(a no-commit base merge, a restamp whose files were never staged, a bare
|
||||
commit) and shipped it under #3526's version. Nothing was merged.
|
||||
|
||||
**Fix.** On the lane, run `gstack-restamp --next` on the head, commit what
|
||||
restamp staged, push, and rerun the verify.
|
||||
|
||||
<a id="restamp-not-staged"></a>
|
||||
### `RESTAMP_NOT_STAGED`
|
||||
|
||||
**Meaning.** `gstack-restamp` wrote the stamp but `git add` failed, so a bare
|
||||
`git commit` would leave the stamp out. The files stay written, and
|
||||
`.gstack/tmp/restamp-staging.json` records what is still to stage.
|
||||
|
||||
**Fix.** Clear what blocked `git add` (a stale `.git/index.lock`, for
|
||||
example) and rerun `gstack-restamp`; the rerun is a noop that stages the files
|
||||
it wrote. When any of them changed since restamp wrote it (you committed by
|
||||
hand, switched branches or merged the base), the marker is stale: the noop
|
||||
rerun drops it and stages nothing, and a stamp still owed is restamped as usual.
|
||||
|
||||
<a id="restamp-unstaged-edits"></a>
|
||||
### `RESTAMP_UNSTAGED_EDITS`
|
||||
|
||||
**Meaning.** A file `gstack-restamp` would stamp holds unstaged edits of yours.
|
||||
Restamp stages what it writes, so those edits would ride along in the stamp
|
||||
commit. Nothing was written.
|
||||
|
||||
**Fix.** Stage (`git add`) or stash your own edits to the named files, then
|
||||
rerun `gstack-restamp`.
|
||||
|
||||
<a id="queue-land-conflict"></a>
|
||||
### `QUEUE_LAND_CONFLICT`
|
||||
@@ -4581,6 +4913,12 @@ GitHub accepted the dispatch). It is never dispatched again blindly.
|
||||
run carrying the nonce, or marks the dispatch absent; only then does
|
||||
`train build --train <nonce>` dispatch it again, under the same nonce.
|
||||
|
||||
On a train with `gates`, a workflow is sent at most twice per prefix. When
|
||||
neither send shows a run carrying the nonce, `train build` (and `train watch`)
|
||||
refuses with this code instead of sending a third: run `train doctor` (a
|
||||
run-name without the nonce is the usual cause), fix the workflow on the base
|
||||
branch, then build a new train.
|
||||
|
||||
<a id="queue-train-waiting"></a>
|
||||
### `QUEUE_TRAIN_WAITING`
|
||||
|
||||
@@ -4601,9 +4939,12 @@ one-PR train.
|
||||
**Meaning.** The train's run (free tests, the full gate or the bisect) has
|
||||
not finished, so there is no verdict yet. The same code covers a `train watch`
|
||||
that reached its timeout, `verify --pr <n> --screen` on a screen run still
|
||||
going, `verify --post-merge` on checks that have not settled, and a
|
||||
`ready --dispatch-ci` workflow run still going at its `--timeout`; each prints
|
||||
the command to rerun as `NEXT:`.
|
||||
going, `verify --post-merge` on checks that have not settled, a
|
||||
`ready --dispatch-ci` workflow run still going at its `--timeout`, a `train
|
||||
build` or `train verdict` while another process holds the train's lease or
|
||||
runs one of its command gates, and a `train land` whose previous slot's
|
||||
post-merge checks have not settled; each prints the command to rerun as
|
||||
`NEXT:`.
|
||||
|
||||
**Fix.** Rerun the printed `NEXT:` command later. Nothing is dispatched again
|
||||
while a run is pending.
|
||||
@@ -4620,6 +4961,10 @@ record. An incomplete gate is never green.
|
||||
one re-dispatch EVAL_POLICY.infraRedispatch allows (`train rebuild --train
|
||||
<nonce> --infra`) and report both runs. Otherwise diagnose the run.
|
||||
|
||||
On a train with `gates` it means a prefix gate is incomplete (a required job
|
||||
that was skipped or never ran, for example); the `PREFIX:` line names the
|
||||
run. `train rebuild` refuses, so diagnose that run and build a new train.
|
||||
|
||||
<a id="queue-train-red"></a>
|
||||
### `QUEUE_TRAIN_RED`
|
||||
|
||||
@@ -4630,6 +4975,11 @@ verdict.
|
||||
**Fix.** Bisect the red cases (`train bisect --train <nonce> --spend-cap
|
||||
<usd>`). After a rebuild's second red, route the cases to a repair lane.
|
||||
|
||||
On a train with `gates` there is no bisect: T<i> is the first red prefix after
|
||||
a green one and every later prefix is red, so slot i is the culprit. The slots
|
||||
before it land (`train land`, or `train watch --land`), the culprit goes back
|
||||
to its lane, and `NEXT:` builds the rest into a new train.
|
||||
|
||||
<a id="queue-train-red-on-main"></a>
|
||||
### `QUEUE_TRAIN_RED_ON_MAIN`
|
||||
|
||||
@@ -4639,6 +4989,9 @@ included: main is broken, not the train's PRs.
|
||||
**Fix.** Fix forward on main first (a one-PR train), then rebuild this train
|
||||
unchanged.
|
||||
|
||||
On a train with `gates`, no bisect runs: T0 (main) is red on its own gate run,
|
||||
or red on anything other than exactly slot 1's `FIXES_BASE_RED` cases.
|
||||
|
||||
<a id="queue-train-unattributed"></a>
|
||||
### `QUEUE_TRAIN_UNATTRIBUTED`
|
||||
|
||||
@@ -4649,6 +5002,10 @@ monotone. One trial per prefix cannot tell a flake from a break.
|
||||
<nonce>`), reporting both runs. Any other pattern: a repair lane, then a
|
||||
changed train once the repair merges.
|
||||
|
||||
On a train with `gates` it means a red prefix is followed by a green one.
|
||||
Repair the red cases or seat the PRs in another order (`--order`); `train
|
||||
rebuild` refuses, so this train never runs again unchanged.
|
||||
|
||||
<a id="queue-train-bisect-capped"></a>
|
||||
### `QUEUE_TRAIN_BISECT_CAPPED`
|
||||
|
||||
@@ -4718,6 +5075,83 @@ ran with `--no-fetch`, verify freezes as before (`QUEUE_TRAIN_FROZEN`). A queue
|
||||
another machine already froze stays frozen; the refusal prints its freeze
|
||||
lines.
|
||||
|
||||
<a id="queue-train-base-red"></a>
|
||||
### `QUEUE_TRAIN_BASE_RED`
|
||||
|
||||
**Meaning.** A conditional (base-red) PR or its fixer cannot ride this train.
|
||||
The train's policy has no `gates`, the fixer is missing or not at slot 1, two
|
||||
PRs declare `FIXES_BASE_RED`, the condition expired, or the fixer's own prefix
|
||||
T1 is red.
|
||||
|
||||
**Fix.** Seat the fixer at slot 1 of a train with gates and build again. A red
|
||||
fixer prefix is the fixer lane's to repair; an expired condition is classified
|
||||
again by its lane ([ship-policy.md](ship-policy.md#train-gates)).
|
||||
|
||||
<a id="queue-train-spend-cap"></a>
|
||||
### `QUEUE_TRAIN_SPEND_CAP`
|
||||
|
||||
**Meaning.** A command gate's next Ubicloud run would pass that gate's spend
|
||||
cap for the train, or `UBI_OWNER` is not set. Nothing more ran; finished runs keep
|
||||
their outcomes.
|
||||
|
||||
**Fix.** Set `UBI_OWNER` to your thread code and rerun `train build --train
|
||||
<nonce>`. For the cap, raise `spend_cap_usd` (or lower `timeout_sec`) on the
|
||||
base branch, then build a new train on the new main: the policy commit moves
|
||||
main past T0.
|
||||
|
||||
<a id="queue-train-land-method"></a>
|
||||
### `QUEUE_TRAIN_LAND_METHOD`
|
||||
|
||||
**Meaning.** This slot must land through an update commit (stamped train,
|
||||
strict protection, conditional PR, or release-file resolution), and
|
||||
`train.land.merge_method` is `rebase`, which would replay commits instead of
|
||||
landing the gated tree.
|
||||
|
||||
**Fix.** Set `merge_method` to `squash` or `merge` on the base branch, then
|
||||
build a new train on the new main: the policy commit moves main off this
|
||||
train's prefixes.
|
||||
|
||||
<a id="queue-train-init-refused"></a>
|
||||
### `QUEUE_TRAIN_INIT_REFUSED`
|
||||
|
||||
**Meaning.** Open PRs bump the version and the policy neither declares
|
||||
`changelog_fragments` nor stamps at merge, so every train merge would conflict
|
||||
on the version. The `VERSION_PRS:` line names them.
|
||||
|
||||
**Fix.** Adopt `changelog_fragments` (recommended) or `queue_mode:
|
||||
stamp-at-merge` on the base branch, then run `train init` again.
|
||||
|
||||
<a id="queue-train-doctor-findings"></a>
|
||||
### `QUEUE_TRAIN_DOCTOR_FINDINGS`
|
||||
|
||||
**Meaning.** The live train block and the repository disagree. Each
|
||||
`FINDING:` line names one problem: a gate workflow missing, without the
|
||||
`nonce` input or run-name, a required job it does not define, a global
|
||||
concurrency group, a push trigger on `train-prefix/` refs, a workflow never
|
||||
green on the base, a command gate cap below what a full train reserves, a
|
||||
merge method GitHub refuses, or `rebase` as the merge method.
|
||||
|
||||
**Fix.** Fix each finding on the base branch (`train init` prints the
|
||||
snippet), then run `train doctor` again.
|
||||
|
||||
<a id="queue-base-red-no-train"></a>
|
||||
### `QUEUE_BASE_RED_NO_TRAIN`
|
||||
|
||||
**Meaning.** `ready --base-red` or `--fixes-base-red` needs a train that gates
|
||||
every prefix, and the base policy has no train block with `gates`.
|
||||
|
||||
**Fix.** Wait for the base to pass the cases and run `/ship --resume`, or turn
|
||||
on a train with gates on the base branch.
|
||||
|
||||
<a id="ship-base-red-fixer"></a>
|
||||
### `SHIP_BASE_RED_FIXER`
|
||||
|
||||
**Meaning.** `ready --base-red` names no fixer, the receipt carries no
|
||||
`base_red` block, or the condition was classified on an older base.
|
||||
|
||||
**Fix.** Pass `--fixer <pr>` naming the PR whose merge fixes the cases; after
|
||||
a base move, run `gstack-base-red classify` and /ship again first.
|
||||
|
||||
<a id="queue-train-frozen"></a>
|
||||
### `QUEUE_TRAIN_FROZEN`
|
||||
|
||||
@@ -4742,6 +5176,91 @@ trains and other trains' merges are refused until a repair lands.
|
||||
<n>@<sha>`). The freeze clears when verify finds main's tree after that merge
|
||||
in a green record; `NEXT:` then builds a train of the PRs still unmerged.
|
||||
|
||||
<a id="queue-wave-conflict"></a>
|
||||
### `QUEUE_WAVE_CONFLICT`
|
||||
|
||||
**Meaning.** `wave build` merged the constituents in order with the train's
|
||||
merge rules, and one conflicts with the wave so far outside the CHANGELOG and
|
||||
the stamp files. Nothing was pushed. The record (state `conflict`) names the
|
||||
PR, the files and a worktree under the state root where the merge is in
|
||||
progress. `--continue` refuses until that worktree holds one committed merge
|
||||
of the constituent's pin onto the recorded commit with a clean tree.
|
||||
|
||||
**Fix.** Resolve the files in the printed worktree, `git -C <worktree> commit
|
||||
--no-edit`, then `gstack-ship-queue wave build --wave <nonce> --continue`. Or
|
||||
build the wave without that PR.
|
||||
|
||||
<a id="queue-wave-moved"></a>
|
||||
### `QUEUE_WAVE_MOVED`
|
||||
|
||||
**Meaning.** A wave no longer lands what its record names: a constituent was
|
||||
pushed, closed or merged after it joined (heads freeze once in), the wave
|
||||
branch carries a merge that is not a constituent's pin (main merged in, for
|
||||
example), a pin is missing from the branch, or the wave was rebuilt and this
|
||||
PR is the old one. The same code refuses a constituent that targets a branch
|
||||
other than the base (a stacked PR's pin carries its parent's commits), a
|
||||
wave that was released, and a `--drop` or `--release` while the wave PR is
|
||||
still open, since a train that already admitted it would still land it.
|
||||
|
||||
**Fix.** Close the wave PR if one is open, then rebuild without the moved PR,
|
||||
`wave build --wave <nonce> --drop <pr>`, which makes a new wave branch and PR (never a
|
||||
force-push); run /ship and READY the new wave PR. The moved PR goes back to
|
||||
its owner and rides on its own or in a later wave. A stacked PR rides on its
|
||||
own; after a release, each constituent is READY'd on its own.
|
||||
|
||||
<a id="queue-wave-duplicate"></a>
|
||||
### `QUEUE_WAVE_DUPLICATE`
|
||||
|
||||
**Meaning.** A PR would land twice or waves would nest: it is already a
|
||||
constituent of another live wave, `train build` was handed both a wave PR and
|
||||
one of its constituents (or two waves sharing one), a wave PR was named as a
|
||||
constituent, or a constituent of a live wave was READY'd or handed to `train
|
||||
build` on its own.
|
||||
|
||||
**Fix.** Keep each PR in one place: drop the separate pin from `train build`,
|
||||
or rebuild one wave without the shared PR. A constituent of a live wave lands
|
||||
through the wave PR.
|
||||
|
||||
<a id="queue-wave-size"></a>
|
||||
### `QUEUE_WAVE_SIZE`
|
||||
|
||||
**Meaning.** A wave carries 3 to 6 PRs by default (R46). `--min` and `--max`
|
||||
change the bounds for one command.
|
||||
|
||||
**Fix.** Add or remove PRs; `wave plan` suggests area groups. Fewer PRs than
|
||||
the minimum ride as single train slots.
|
||||
|
||||
<a id="queue-wave-unknown"></a>
|
||||
### `QUEUE_WAVE_UNKNOWN`
|
||||
|
||||
**Meaning.** A PR's head branch is `wave/<nonce>`, or a command named a
|
||||
nonce, but no wave record exists in local state or on
|
||||
`refs/notes/gstack-trains`. `ready` and `train build` refuse rather than
|
||||
treat the PR as an ordinary one, since its constituents cannot be checked.
|
||||
|
||||
**Fix.** `gstack-ship-queue wave status` lists the known waves. When the
|
||||
record is gone, rebuild the wave with `wave build --prs`.
|
||||
|
||||
<a id="queue-wave-dependent"></a>
|
||||
### `QUEUE_WAVE_DEPENDENT`
|
||||
|
||||
**Meaning.** `wave build --drop <pr>` was asked to drop a PR whose pin is an
|
||||
ancestor of another constituent's pin (a stacked PR), so the rebuilt wave would
|
||||
still land the dropped code.
|
||||
|
||||
**Fix.** Drop the containing PR too, or keep the PR in the wave.
|
||||
|
||||
<a id="queue-wave-not-merged"></a>
|
||||
### `QUEUE_WAVE_NOT_MERGED`
|
||||
|
||||
**Meaning.** `wave settle` found no PR merged into the base branch whose head
|
||||
branch is the wave branch, its merge commit is not on the base branch, or that
|
||||
merge's tree is neither the PR's head tree nor that head merged onto the
|
||||
merge's parent, so it cannot say the constituents landed. Nothing was commented or closed.
|
||||
|
||||
**Fix.** Land the wave PR through its train (`train land`), then rerun
|
||||
`gstack-ship-queue wave settle --wave <nonce>`.
|
||||
|
||||
<a id="queue-receipt-missing"></a>
|
||||
### `QUEUE_RECEIPT_MISSING`
|
||||
|
||||
@@ -4783,7 +5302,9 @@ to fix this: the stamp comes only when the slot is called.
|
||||
**Meaning.** The PR body's ship receipt carries a `base_red` block: /ship's
|
||||
Step 5 failed on cases `gstack-base-red` proved are the base branch's own, so
|
||||
/ship paused before READY ([base_red](ship-policy.md#base-red)). Nothing
|
||||
READYs, trains, carries or merges on it.
|
||||
READYs, trains, carries or merges on it, except on a train with `gates`, where
|
||||
`ready --base-red --fixer <pr>` READYs it to ride behind its fixer at slot 1
|
||||
([base-red PRs](ship-policy.md#train-gates)).
|
||||
|
||||
**Fix.** Wait for the base to pass those cases (`gstack-base-red wait --pause
|
||||
<file>`), then run `/ship --resume <record>`, which reruns Step 5 and rewrites
|
||||
@@ -4975,7 +5496,10 @@ or `--timeout` (default 2700 s) passes, prints `POST_MERGE: <sha12>
|
||||
green|red|pending|none (passed= failed= pending= skipped=)` and one
|
||||
`CHECK: <name> <conclusion|status>` line per check, and a timeout is
|
||||
`QUEUE_TRAIN_PENDING` with the same command as `NEXT:`, so rerunning it after
|
||||
an interruption continues the watch.
|
||||
an interruption continues the watch. With `--checks <a,b>` (a workflows
|
||||
gate's `post_merge_checks`, which `train land` and `train watch --land` pass),
|
||||
each named check must also succeed; one that never ran is `QUEUE_TRAIN_PENDING`
|
||||
at the timeout.
|
||||
|
||||
**Fix.** Read the red run named on its `CHECK:` line. Repair on a new PR or
|
||||
roll back the merge; `gstack-ship-queue train status` names the freeze if the
|
||||
@@ -5138,7 +5662,9 @@ compare (a receipt written before `head_tree`, whose head is not in this
|
||||
clone), the PR was retargeted to the base after its stack parent landed but
|
||||
the receipt records no `product_patch_id` and `origin/<parent>` 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
|
||||
compare the two product diffs (including when carry cannot create its temp
|
||||
directory under `.git/gstack-patch-id`; the message names it) 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
|
||||
@@ -5201,11 +5727,41 @@ 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, 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
|
||||
the recorded product diff, a stacked PR's retarget once its parent fully
|
||||
landed on the base, or base context next to unchanged hunks after a clean
|
||||
scoped review ([`RECEIPT_CARRY_SCOPED_REVIEW`](#receipt-carry-scoped-review)), 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)).
|
||||
|
||||
<a id="receipt-carry-scoped-review"></a>
|
||||
### `RECEIPT_CARRY_SCOPED_REVIEW`
|
||||
|
||||
**Meaning.** Every product path the branch touches has the reviewed +/- lines
|
||||
in the same places, but the base edited context lines next to some of them, so
|
||||
the 3-line patches differ (GST-384: main reworded the line above the PR's
|
||||
hunk). The merge may have spliced the two, as in a JSON entry where the branch
|
||||
changed one key and the base the next, so the receipt does not carry silently.
|
||||
The refusal names the paths and a packet file with the hunks that differ and
|
||||
the base's own change. The same lines moved somewhere else are
|
||||
`RECEIPT_CARRY_PRODUCT_CHANGED`, not this code.
|
||||
|
||||
**Fix.** Dispatch one fix-check reviewer
|
||||
([review-policy.md](review-policy.md)) on the packet. When it comes back clean,
|
||||
write `{"head":"<HEAD>","paths":[...],"reviewer":"<model>","verdict":"clean"}`
|
||||
and rerun `gstack-ship-receipt carry ... --scoped-review <record.json>`; the
|
||||
carry reason records the reviewer and the paths. A blocking finding means /ship
|
||||
on the new head. `gstack-ship-release finish` stops the same way with
|
||||
`context=N` and takes `--context-reviewed <record.json>` bound to the tree;
|
||||
write that record beside the packet, outside the worktree, so it does not change
|
||||
the tree it is bound to. Finish also stops this way for test code changed since
|
||||
review with no gate edit (`tests=N`): the packet holds those test hunks, and the
|
||||
reviewer checks that each test still tests what it did. A packet that cannot be
|
||||
written (an unwritable `.git`) is a STOP or `RECEIPT_CARRY_REFUSED` naming the path.
|
||||
`carry --dry-run` reports this code without writing the packet, and only when
|
||||
none of carry's other checks would refuse; carry without `--dry-run` writes it.
|
||||
In /ship Step 1, `gstack-ship-preflight` prints the route as `NEXT: carry
|
||||
route (Step 1.4)`.
|
||||
|
||||
<a id="receipt-prose-mismatch"></a>
|
||||
### `RECEIPT_PROSE_MISMATCH`
|
||||
|
||||
@@ -5260,7 +5816,10 @@ over` line names (or raise its cap on the base branch). When the owner accepts
|
||||
the named risk instead, record it as `docs.exception: { accepted_by, date, via,
|
||||
reason }` and carry the `Documentation exception: accepted by <owner> <date> via
|
||||
<ref>: <reason>` line in the PR body's `## Documentation` section, word for word
|
||||
([ship-policy.md](ship-policy.md#ship-receipt)).
|
||||
([ship-policy.md](ship-policy.md#ship-receipt)). Then save the post-audit snapshot with
|
||||
`gstack-docs-candidate snapshot --exception .gstack/tmp/docs-audit.json`;
|
||||
`gstack-ship-release finish` stops on a blocked audit whose snapshot lacks the
|
||||
exception.
|
||||
<a id="gstack-pr-wait"></a>
|
||||
## gstack-pr-wait
|
||||
|
||||
@@ -5618,6 +6177,26 @@ The router's description (at most 300 bytes) and the context block (at most 600
|
||||
|
||||
There is no ledger for that harness or id under `$GSTACK_STATE_ROOT/harness`. `gstack-harness status` lists every registration on this machine with its id.
|
||||
|
||||
<a id="harness-hook-unsupported"></a>
|
||||
### `gstack-harness: <harness> has no start hook` / `the start hook goes into the <harness> profile <dir>, and this registration uses another skills folder` (HARNESS_HOOK_UNSUPPORTED)
|
||||
|
||||
The [start hook](hosts.md#start-hook) exists for OpenClaw and Hermes only, and it goes into the harness profile's own plugin folder, the one the harness scans. A registration with `--skills-dir` somewhere else has no profile gstack can trust, and with `OPENCLAW_CONFIG_PATH` set OpenClaw reads a config outside the profile, where gstack's settings change would not land, so `--start-hook` is refused and nothing is written. Register without `--skills-dir` (set `OPENCLAW_STATE_DIR` or `HERMES_HOME` to pick the profile), or drop `--start-hook`. When the choice comes from `GSTACK_HARNESS_START_HOOK` or `harness_start_hook` instead of the flag, such a registration just gets no hook, and its receipt says so.
|
||||
|
||||
<a id="harness-hook-choice-invalid"></a>
|
||||
### `gstack-harness: GSTACK_HARNESS_START_HOOK="<value>" is not on or off` (HARNESS_HOOK_CHOICE_INVALID)
|
||||
|
||||
The start hook switch takes `on` or `off` (`GSTACK_HARNESS_START_HOOK` also takes `1` or `0`). Nothing was registered. Fix the value, or unset it so each registration keeps its saved choice.
|
||||
|
||||
<a id="harness-hook-owned-elsewhere"></a>
|
||||
### `gstack-harness: a gstack-start plugin already exists at <dir> and this registration did not write it` (HARNESS_HOOK_OWNED_ELSEWHERE)
|
||||
|
||||
Each harness profile has one start hook, owned by the gstack registration that wrote it, so that removing one install can never take another install's hook away. This folder is not in this registration's ledger: another gstack checkout or state root wrote it, or someone made it by hand. Nothing was written. Run `gstack-harness register <harness> --no-start-hook` from the gstack install that wrote it (its `gstack-harness status` shows the hook), or move the folder aside, then register again.
|
||||
|
||||
<a id="harness-hook-inactive"></a>
|
||||
### `gstack-harness: <harness> start hook is written: <why>. Turn it on: <command>` (HARNESS_HOOK_INACTIVE, exit 4)
|
||||
|
||||
The skills are registered and the start hook's files are in place, but the hook is not active in the harness. gstack turns the hook on through the harness's own CLI and then reads it back, so this means the CLI was not on `PATH`, one of its commands failed or timed out (the message quotes its last output), or the harness's settings block the plugin: OpenClaw's `plugins.allow` set without `gstack-start`, `gstack-start` in `plugins.deny`, or `hooks.allowPromptInjection: false`. gstack never edits your allow or deny lists. Run the printed command, then `gstack-harness status`; `--start-hook` again retries the whole step. `./setup --host` exits 4 for the same reason. Refreshes and upgrades retry on their own without failing, and stop once you disable the plugin in the harness.
|
||||
|
||||
<a id="harness-qm-credentials"></a>
|
||||
### `gstack-harness: no QM admin credential in the environment` / `... needs --yes` (HARNESS_QM_CREDENTIALS)
|
||||
|
||||
|
||||
Reference in new issue
Block a user