mirror of
https://github.com/garrytan/gstack.git
synced 2026-10-31 14:06:50 +01:00
docs: troubleshooting sections for the wave's new messages
Bun floor (setup, auto-update, /gstack-upgrade), /review stale base and fingerprint temp-dir errors, the design image model override, the unrecorded Chromium PID, and a contributor section for census report lines (pass-rates flags, failure causes, headroom, cost unknown, overlay v4, stale corpora, auq substance). A free test checks every troubleshooting.md#anchor printed by setup or bin scripts exists.
This commit is contained in:
garrytan committed
1 parent
3bd625d3b8
commit
971ec27e58
2 files changed
+152
No files matched your search
@@ -307,6 +307,30 @@ Or stop the reminder: `gstack-slug --adopt-legacy --dismiss <slug>`.
|
||||
|
||||
---
|
||||
|
||||
<a id="review-base-stale"></a>
|
||||
### `BASE_REFRESH: stale <rev>` / `Base coverage: stale at <rev>`
|
||||
|
||||
**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/<base>` at `<rev>`.
|
||||
|
||||
**Fix.** Run `git fetch origin <base>` outside the sandbox and rerun /review if
|
||||
the base has moved.
|
||||
|
||||
<a id="review-fingerprint-objects"></a>
|
||||
### `gstack-review-log: cannot create a private object directory under <dir>; no working-tree fingerprint.` / `gstack-wtree: cannot create a temp index under <dir>`
|
||||
|
||||
**Meaning.** The working-tree fingerprint needs a writable temp directory.
|
||||
|
||||
**Fix.** `export TMPDIR=<writable dir>` 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
|
||||
|
||||
<a id="design-not-available"></a>
|
||||
@@ -351,6 +375,15 @@ pick a new `--output`), then copy the recovery file to where you want it.
|
||||
|
||||
---
|
||||
|
||||
<a id="design-image-model-invalid"></a>
|
||||
### `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
|
||||
|
||||
<a id="gstack-no-install-found"></a>
|
||||
@@ -412,6 +445,32 @@ stopped instead of touching your project.
|
||||
|
||||
## Setup and auto-update
|
||||
|
||||
<a id="bun-too-old"></a>
|
||||
### `gstack needs Bun 1.3.3 or newer (1.4.0 recommended); found X at <path>. 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`.
|
||||
|
||||
<a id="auto-update-bun-too-old"></a>
|
||||
### `gstack auto-update: update held (bun-too-old: found Bun X at <path>; 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 <gstack checkout> && git pull --ff-only && ./setup` (or `/gstack-upgrade`).
|
||||
|
||||
<a id="auto-update-incomplete"></a>
|
||||
### `gstack auto-update: setup did not finish (<reason>); installed skills may be out of date. gstack retries automatically. Fix now: cd <dir> && ./setup`
|
||||
|
||||
@@ -524,6 +583,15 @@ after `--`).
|
||||
|
||||
---
|
||||
|
||||
<a id="browse-chromium-pid-unrecorded"></a>
|
||||
### `[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)
|
||||
|
||||
<a id="pass-rates-unknown-flag"></a>
|
||||
### `eval:pass-rates: unknown flag --x` / `unknown case <id>`
|
||||
|
||||
**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.
|
||||
|
||||
<a id="unknown-failure-cause"></a>
|
||||
### `unknown failure_cause "<x>" (written by a newer gstack; update this checkout to read it)`
|
||||
|
||||
**Fix.** `git pull` (or rebase your branch) and rerun.
|
||||
|
||||
<a id="case-registered-by-several"></a>
|
||||
### `--case <id>: registered by a, b; it needs exactly one`
|
||||
|
||||
**Fix.** Run the red shard's file: `EVALS=1 EVALS_TIER=<tier> bun test <file>`
|
||||
(the report's "after a repair:" line prints it).
|
||||
|
||||
<a id="evidence-too-large"></a>
|
||||
### `evidence: <artifact> too large to fetch (N MB)`
|
||||
|
||||
**Fix.** Download it from the run page, or
|
||||
`gh api repos/<owner>/<repo>/actions/artifacts/<id>/zip > slice.zip`.
|
||||
|
||||
<a id="headroom-alarm"></a>
|
||||
### `[headroom] <case> session <key>: 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.
|
||||
|
||||
<a id="cost-unknown"></a>
|
||||
### `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.
|
||||
|
||||
<a id="provider-stall"></a>
|
||||
### 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 <id> --case <id>`. A
|
||||
paid rerun only after a repair.
|
||||
|
||||
<a id="overlay-contract-v4"></a>
|
||||
### `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.
|
||||
|
||||
<a id="detector-corpora-stale"></a>
|
||||
### `[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-<case>.test.ts`.
|
||||
|
||||
<a id="auq-substance-mean"></a>
|
||||
### `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.
|
||||
@@ -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.');
|
||||
|
||||
Reference in new issue
Block a user