diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 73e67c7bc..88f0dc419 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -307,6 +307,30 @@ Or stop the reminder: `gstack-slug --adopt-legacy --dismiss `. --- + +### `BASE_REFRESH: stale ` / `Base coverage: stale at ` + +**Meaning.** /review could not fetch the base branch (offline, no credentials, +or a read-only `.git` such as Codex's sandbox), so it reviewed against your +local `origin/` at ``. + +**Fix.** Run `git fetch origin ` outside the sandbox and rerun /review if +the base has moved. + + +### `gstack-review-log: cannot create a private object directory under ; no working-tree fingerprint.` / `gstack-wtree: cannot create a temp index under ` + +**Meaning.** The working-tree fingerprint needs a writable temp directory. + +**Fix.** `export TMPDIR=` and rerun. + +### `gstack-wtree: cannot stage the working tree: ...` / `gstack-wtree: cannot write the tree: ...` + +**Meaning.** The object directory could not be written. `gstack-review-log` +supplies a private one; standalone `gstack-wtree` writes to `.git/objects`. + +**Fix.** Run it through `gstack-review-log`, or make `.git/objects` writable. + ## Design skills @@ -351,6 +375,15 @@ pick a new `--output`), then copy the recovery file to where you want it. --- + +### `GSTACK_DESIGN_IMAGE_MODEL="..." is not a gpt-image model name` + +**Meaning.** The image model override must look like `gpt-image-2`; anything +else is refused before a request is sent. The live model check always tests +the defaults, whatever this is set to. + +**Fix.** Set a gpt-image model name, or `unset GSTACK_DESIGN_IMAGE_MODEL`. + ## Codex and other env-var hosts @@ -412,6 +445,32 @@ stopped instead of touching your project. ## Setup and auto-update + +### `gstack needs Bun 1.3.3 or newer (1.4.0 recommended); found X at . Nothing was installed or changed.` + +Also: `warning: gstack is tested on Bun 1.4.0 (CI pin); found X` and +`warning: could not read the Bun version (...); continuing.` + +**Meaning.** Bun older than 1.3.3 accepts but ignores the flags that stop +gstack's compiled tools from reading a project's `.env`, so setup refuses it +before writing anything. Bun 1.3.3 to 1.3.x works but is untested; an +unreadable version only warns. + +**Fix.** `bun upgrade`, then `./setup`. + + +### `gstack auto-update: update held (bun-too-old: found Bun X at ; gstack V needs F or newer); nothing was installed or changed.` + +Also `/gstack-upgrade`'s `BUN_TOO_OLD: bun-too-old: ...; nothing was changed`. + +**Meaning.** The incoming release needs a newer Bun than the one setup would +run, so the update stopped before moving your checkout. Your installed version +keeps working. The first update run by an auto-updater older than this check +cannot do it. + +**Fix.** `bun upgrade`. The next session start resumes the update, or run +`cd && git pull --ff-only && ./setup` (or `/gstack-upgrade`). + ### `gstack auto-update: setup did not finish (); installed skills may be out of date. gstack retries automatically. Fix now: cd && ./setup` @@ -524,6 +583,15 @@ after `--`). --- + +### `[browse] Could not record the Chromium PID (CDP SystemInfo.getProcessInfo: ...); browse stop cannot reap a surviving Chromium.` + +**Meaning.** gstack reads the PID of a browser it launched over CDP so `browse +stop` can clean up a Chromium that outlives the server. That read failed, so +this session's browser is not reaped automatically. + +**Fix.** After `browse stop`, check `ps` for a leftover Chromium and kill it by hand. + ## Memory and gbrain Every message below is also in [docs/gbrain-sync-errors.md](gbrain-sync-errors.md) @@ -617,3 +685,78 @@ Bypass once: `GSTACK_REDACT_PREPUSH=skip git push`. **Fix.** Write it as `version: 1.2.3.4`, `"version": "..."` or `v1.2.3.4`. MEDIUM findings do not block pushes. + +--- + +## Evals and census reports (contributors) + + +### `eval:pass-rates: unknown flag --x` / `unknown case ` + +**Meaning.** The flag or case id is not recognized; it exits 2 before fetching anything. + +**Fix.** `bun run eval:pass-rates --help`; use a registry case id or a paid test file path. + + +### `unknown failure_cause "" (written by a newer gstack; update this checkout to read it)` + +**Fix.** `git pull` (or rebase your branch) and rerun. + + +### `--case : registered by a, b; it needs exactly one` + +**Fix.** Run the red shard's file: `EVALS=1 EVALS_TIER= bun test ` +(the report's "after a repair:" line prints it). + + +### `evidence: too large to fetch (N MB)` + +**Fix.** Download it from the run page, or +`gh api repos///actions/artifacts//zip > slice.zip`. + + +### `[headroom] session : max Xs of Ys (Z%) ... above the 85% cap` + +**Meaning.** The case's slowest session used more than 85% of the timeout it armed. + +**Fix.** Cut work in the skill or fixture. Budgets are never raised. + + +### `cost unknown (no billing captured for any of N trial(s))` / `... N of M trial(s) cost unknown` + +**Meaning.** PTY and Codex harnesses record no billing, so only the known sum is +shown. Informational. + + +### Red line `ยท cause provider_stall: no stream event for Ns ...` + +**Meaning.** The model request went silent for at least 120 s with no tool, +permission prompt, hook or subagent outstanding. Under EVAL_POLICY v1 this is +still a failure. + +**Fix.** Inspect it with `bun run eval:pass-rates --run --case `. A +paid rerun only after a repair. + + +### `overlay ... contract-v4 ... taskCorrect: false` with `answerError` set + +**Meaning.** The trial completed with a wrong answer; that is a valid +measurement in the comparison. Only an overlay-on wrong answer fails the case. + +**Fix.** Read `answerError` in the trial JSON. No rerun needed. + + +### `[detector-corpora] N stale entries (refresh from a current census when one fails)` + +**Meaning.** Corpus entries came from an older input series of their case. Informational. + +**Fix.** When that case goes red in a census, add the new capture and check it +with `bun test test/detector-corpus-.test.ts`. + + +### `recommendation substance mean X < 4 over samples [a,b,c]` (auq-matrix) + +**Meaning.** The 3-sample judge panel's mean was below the threshold. + +**Fix.** Read the logged samples and the captured question; fix the skill +text, then run one diagnostic. diff --git a/test/troubleshooting-anchors.test.ts b/test/troubleshooting-anchors.test.ts index d36da4ef4..58b63a23e 100644 --- a/test/troubleshooting-anchors.test.ts +++ b/test/troubleshooting-anchors.test.ts @@ -26,6 +26,15 @@ describe('docs/troubleshooting.md anchors', () => { for (const outcome of Object.values(GATE_OUTCOMES)) expect(outcome.fix.trim().length).toBeGreaterThan(0); }); + test('every docs/troubleshooting.md#anchor that setup or a bin script prints exists', () => { + const sources = ['setup', ...fs.readdirSync(path.join(ROOT, 'bin')).map(f => `bin/${f}`)] + .filter(f => fs.statSync(path.join(ROOT, f)).isFile()); + const linked = sources.flatMap(f => [...fs.readFileSync(path.join(ROOT, f), 'utf8').matchAll(/troubleshooting\.md#([a-z0-9-]+)/g)] + .map(m => `${f} -> #${m[1]}`)); + expect(linked.length).toBeGreaterThan(0); + expect(linked.filter(l => !anchors.has(l.split('#')[1]!))).toEqual([]); + }); + test('outcome lines follow the not run / unavailable / unverified shapes', () => { const line = (code: GateReason, detail?: string) => gateOutcomeLine('Codex outside review', code, detail); expect(line('disabled')).toBe('Codex outside review: not run (outside reviews are turned off (codex_reviews=disabled)). Fix: gstack-config set codex_reviews enabled.');