mirror of
https://github.com/garrytan/gstack.git
synced 2026-11-06 17:04:27 +01:00
Garry Tan
55f8151fbe
* docs: approved reliability follow-ups plan (Oct 2026)
* D1: score overlay wrong answers as comparison results (contract v4)
A completed answer that fails the fixture's output check is now a valid
measurement with taskCorrect false and answerError set, in either arm.
Only execution, scope and metric failures invalidate a trial. ON
correctness still gates the case, so an OFF wrong answer stays in the
comparison. OVERLAY_CONTRACT moves to v4; v3 verdicts are not
reinterpreted. Replays the 37198445662 sonnet trials (OFF-0 wrong).
* C4: score auq-matrix substance with a 3-sample judge panel
Each skill keeps one native capture in the same execution; the
recommendation-substance grader now runs as a JUDGE_PANEL_SAMPLES panel on
that capture and gates on the mean against the unchanged minimum of 4. A
failed sample fails the panel without resampling. Approved at the gate
2026-10-04 for censuses after this change.
* E1: one Bun version source; setup refuses below the 1.3.3 floor, updater checks before advancing
bin/gstack-bun-version.sh holds the security floor (1.3.3) and the tested
version (1.4.0, the CI pin and engines.bun). setup refuses Bun below the
floor before writing anything, warns between floor and tested, warns and
continues on an unparseable version, and prints a 1.4.0 install hint.
Prereleases sort below their release (semver).
gstack-session-update now fetches, reads the incoming release's floor and
checks the bun setup will run before fast-forwarding to that exact
revision; below it the update is held with reason bun-too-old and a
resume command, leaving the revision and installs untouched.
Fixture copies of setup (team-mode, claude-code migration) now include the
sourced file; the slow-git lock test sleeps on fetch, the updater's
network step.
* E3: record the owned Chromium's PID over CDP so the #2709 reap runs on Playwright 1.62
Playwright 1.62's Browser has no process(), so chromiumProcInfo was always
null and browse stop never reaped a surviving headless Chromium. The owned
headless launch now reads the browser PID from CDP SystemInfo.getProcessInfo
(bounded at 2s; a hung or failed call logs once and records nothing). The
reaper's start-time and cmdline identity checks are unchanged, so a recycled
PID or an externally owned browser is never signalled.
* A1: ship docs gate records post-child hashes with gstack-docs-candidate, saves each record once
Stored transcripts (37198445662 gate-census-2) show the parent's reads of
release files take ~1 s; the parent's own model time dominates (completion
268 s of 392 s, store ~270 s of 387 s), and 45-78 s of it is retyping hash
maps, child output and records into several artifacts after the child
returns. The child contract is unchanged.
* A2: /plan-ceo-review sends the mode handoff line before any other tool call
plan-ceo-mode-routing's HOLD SCOPE session spends its 240 s post-selection
window on model work: 37176837432 skipped the handoff helper and paraphrased
the mode, 37198445662 ran it, then wrote the plan, loaded sections and probed
Codex for 114 s before the posture chat. The handoff line is the posture.
* B3: accept wrapped unchanged rows in the cropped Edit preview
PR run 37176835584 timed out with the floor's owned Edit menu on screen:
unchanged diff rows soft-wrap under their gutter with a blank marker
column, and a trimmed empty unchanged row keeps only its number. The
parser accepted wrapped +/- rows only, so it never verified the owned
edit. Both forms are now parsed and still compared with the exact source
lines; the captured viewport is replayed with negative controls.
* A3: record per-phase headroom diagnosis for docsync, plan-mode-no-op, mode-routing and gate slice 11
* E4: /review Step 1 keeps going when the base fetch fails and reports stale base coverage
Under Codex's read-only .git, 'git fetch && merge-base && diff --stat'
stopped at the fetch, so the empty output read as 'Nothing to review'.
The fetch is now separate, prints BASE_REFRESH fresh or stale with the
local base revision, and the review states stale coverage.
* D2: reword the format-approach question prompt
Both plan-ceo-review-format-approach refusals in census 37195203538
(Fable 5.1 model_refusal_no_fallback, category reasoning_extraction:
"duplicating model outputs") were anchored on the session prompt, whose
capture instruction asked for the "verbatim" question and "the exact
prose you would have shown" in a "format-capture test". The approach
case now asks for the same question in the same file as the step's
output, without that wording. The other three plan-format cases keep
their unchanged prompt (no refusals in 72 trials).
* C2: /qa defines its outcome filename fields; QA report templates name the measured timing fields
Low judge samples in failing panels named both: qa workflow (37186854666)
'an undefined {user} in the outcome filename', and qa-only workflow
(37198445662) 'template asks for Duration / durationMs totals while
reporting.md mandates Probe budget and Guarded command time'. The qa
union stays under its 1.11 size ratio (93292 of 93294 bytes).
* 0.1: session ledger written by the claude -p, Agent SDK, PTY and Codex runners
Each armed model session appends one best-effort line to
$GSTACK_EVAL_DIR/session-ledger.jsonl: a stable session key, the timeout it
armed, monotonic elapsed time, its end reason (completed, session_timeout,
observer_timeout, api_error, refusal, aborted, error), one sanitized evidence
line and, for stream-JSON runners, a compact liveness summary (longest
in-request silence with nothing outstanding, last event kind, tool open at
end). Partial messages now stream for every claude -p session and for SDK
sessions without a custom query provider (runSharedInteractive opts in); their
rows feed only the summary, so transcripts keep their size unless
publicStreamDiagnostics is set. Structured refusal and API-error signals win
over phrases, and tool results are never read for them.
* 0.2: failure_cause beside failure_class, from runner facts and the session ledger
One pure failureCauseOf() beside failureClassOf() sets failure_cause
(contract > pre_turn_infra > api_error > refusal > provider_stall >
session_timeout > observer_timeout > assertion > unknown; no machine-set
'detector') with one bounded evidence line, and failureDetailOf() keeps a
Bun matcher's Expected/Received or a judge's failing dimensions in
failure_detail. Both record builders (classifyTrialShard, junitCensus) call
them and attach the trial's ledger sessions. failure_class, error and
TRIAL_ERROR_MAX are computed exactly as before; the new fields are optional,
bounded and validated only when present, and a frozen copy of the v1 reader
accepts every new record. A provider stall needs partial messages and
STALL_WINDOW_MS (120 s, eval-budgets.ts beside HEADROOM_WARN/FAIL) of
in-request silence with nothing outstanding; it stays a failure under
EVAL_POLICY v1.
* E4: fingerprint under a read-only .git via a private object dir owned by review-log
Codex's sandbox mounts .git read-only, so gstack-wtree's git add -A could not
write blobs and /review lost its start capture. gstack-review-log now creates
a private 0700 object directory under TMPDIR, passes it to gstack-wtree (which
writes new objects there with the common-dir object store, resolved before
exporting, as an alternate, so linked worktrees work), exposes it to the
bindReview/checkSharedLibsReuse consumers that read the tree and blobs, and
removes it on EXIT/INT/TERM after they finish. gstack-wtree prints one stderr
line and exits 1 on a failed write or unwritable TMPDIR instead of printing a
partial hash; review-log no longer swallows that line. Standalone gstack-wtree
keeps writing to the repository store so git diff between saved snapshots
(/ship) still works.
* 0.3: red lines name their values, evidence and an after-a-repair command; one published-text sanitizer
Each red line in the census report keeps its stored error and adds the
machine cause with its evidence, the failure_detail values (Expected/Received,
or each failing judge dimension with its mean, sample count and the sample
sentence naming it), the slice artifact and shard directory that hold the
transcript, a fetch command (eval:pass-rates --run <id> --case <id>), and
'after a repair:' with a command that selects only that case (E2E ids via
--case, judges via their selection and an exact test-name filter). A
session that completed and failed a check says so instead of 'assertion
(success)'. Report text that reaches a PR comment, issue or committed file
goes through scripts/lib/published-text.ts: control and bidi characters
stripped, credential-scan patterns redacted, mentions neutralized, HTML and
link brackets escaped inline, blocks in a fence longer than any backtick run,
length capped. Verdicts and collector verdict objects are unchanged.
* E2: one make-pdf resolver for readiness and every $P block on env-var hosts
make-pdf exported $P from its readiness block, which Codex and the other
env-var hosts lose between blocks. binaryAssignment gains 'make-pdf': the
MAKE-PDF SETUP readiness check and the runtime prelude both use it, so every
block that runs $P derives the same make-pdf/dist/pdf binary, with
MAKE_PDF_BIN (dev builds) winning when it is executable. Claude output keeps
its repo-local-first probe; only the false 'subsequent blocks' comment
changed. Root plus P=... fits the 400-byte prelude budget; the fixed
MAKE_PDF_OVERRIDE segment is the one exemption, named in runtime-root.ts and
the conformance test.
* 0.1: eval:pass-rates --headroom, --reds and --run report views; 85% headroom alarm in --gate
A new pure module, scripts/lib/eval-history.ts, reports per case the slowest
armed session against the timeout it armed (censored when it timed out,
insufficient below 3 samples, unknown without a session ledger, with the
case wall shown separately as an upper bound), the census critical path from
the slice jobs' timings, the verdict red ledger per census by failure class
and machine cause with shrunk per-case rates, and the all-green probability
(an approximation: the product of 1 - p_i, with an interval). --run <id>
lists one census's reds with their values and history and downloads only the
slice artifacts those reds name, reporting any over 64 MB instead of skipping
them. eval-flake-rank.ts only routes flags: --help works offline, an unknown
flag or case id exits 2 before any fetch, --case narrows the JSON and the
alarms, every view prints its run/branch scope, and --gate also alarms on a
session above HEADROOM_FAIL (85%) of its budget.
* E5: GSTACK_DESIGN_IMAGE_MODEL override; the live model check always tests the defaults
The image_generation tool model gains an env override validated against a
conservative gpt-image-<version> pattern; a bad value fails before any
request and the error names the variable. Pairing and rejection hints name
the tool model actually requested. design/scripts/live-model-check.ts now
ignores GSTACK_DESIGN_MODEL and GSTACK_DESIGN_IMAGE_MODEL (and says so), so
an override cannot mask a retirement of a default, and its exit 2 (no key)
says nothing was checked.
* C3: /deslop-shared-libs names a concrete risk for each recommendation, never 'none'
Both shared-libs-opportunity-judgment reds (37193478719 t3, 37195203538 t1)
failed adoption_and_risk because the top recommendation said 'Main risk:
none found inside the repo' / 'none in behavior'. The skill asked to 'name
the main risk or uncertainty' without saying what counts.
* B4: --case selects loop-registered cases; an unknown id exits before any process
caseSelection() resolves the one paid file that registers a case and how a
trial selects it: by its literal Bun test name, by the id a registration loop
names its test at runtime (coverage audits, TPA, journeys), or by running the
whole file when it registers no other case (plan-mode-no-op, whose test names
are not the id, so the old name pattern ran nothing). A whole-file case runs
one file shard per trial and is judged by shard status, as CI judges it.
--list prints the selection. Every E2E_TIERS id now resolves except
carve-section-loading, which fifteen files register (CI runs each as its own
shard) and which still fails with the owning files named.
* 0.3: after-a-repair runs the shard file when --case cannot resolve a case
A case that several files register (carve-section-loading) cannot be selected
by --case; its red line now prints the bun test command for the shard file
that went red, so every printed command selects exactly one case.
* C1: pre-register workflow-judge control bundles for qa, qa-only, review and setup-deploy
Positive (production bundle), negative (headings only) and one targeted
execution-blocking defect per judge, one 3-sample panel each, built with the
eval's own reader, prompt builder, options and floors.
* F: cost_known: a trial whose harness captured no billing says so; totals never hide it
cost_usd stays a finite number. Trial and eval records gain an optional
cost_known boolean (absent means known, so old records still parse; the
validator accepts only a boolean). Session-ledger rows record whether the
session's terminal result carried total_cost_usd; PTY and Codex sessions
never do, and SDK captures without a terminal result do not. A trial is
cost-known only when it has eval records and every record and session
captured billing, so JUnit-only PTY cases (125 of 298 trials in run
37198445662 recorded 0) now read cost unknown. The census headline prints the
known sum plus the unknown count, never a bare total over unknown costs, and
no total when every cost is unknown; the history import keeps the flag.
PTY transcripts are not priced: test/helpers/pricing.ts estimates exclude
cache writes, so they cannot give the billed cost.
* B1: replay corpora for the five repeat-offender cases
shared-libs-plan-callers, plan-ceo-section-loading, auto-decide-preserved,
plan-design-review-plan-mode and ship-docsync-late-result each get an
inventory of every wave census in scope (all artifacts still available)
and minimal, redacted detector or actor inputs replayed through the real
detector in the free suite: census passes, every distinct census red, and
derived negative controls labelled as derived. Fixed false reds stay as
expected passes with their history; the two genuine auto-decide product
failures (37176837432, 37179171083) stay refused. A contract test bounds
each entry at 64 KB, scans it for HIGH credentials, requires a pass and a
refusal per case, and reports entries whose series identity is stale.
Building the auto-decide corpus exposed a latent native detector misread:
a bold 'Mode application and rationale.' heading was parsed as a
withdrawn Mode field (37186854666). A field status now ends at its
sentence.
* B2: read approved stale-fill decisions from more valid ledger records
The structured ledger reader is authoritative before the prose fallback,
but it missed two valid approved records in passing censuses
(37186854666: a camelCase writeProfile subject; 37195203538: a
slash-joined 'D1 / STALE-FILL' row id), which then rested on the prose
detector that caused both historical reds. Both forms are accepted; an
unresolved row, an unrelated decision, the copied fixture plan and
non-write camelCase words stay refused.
* C1: record workflow-judge control results (negatives separated; qa and review miss a removed step)
* C2: record every low workflow-judge sample in the wave censuses with its disposition
* 0.3: published lines cannot break a fixed fence
evals.yml wraps collector-outcomes failures in a fixed three-backtick fence
for the PR comment, so those lines (and eval:pass-rates output meant for the
tracking issue) go through sanitizeFixedFenceLine: cleaned like every
published line, with backticks turned into quotes. Inline published text
also neutralizes backticks.
* A1: fit the post-child record wording under ship's 1.428 parity size cap
* E4: inline the Step 1 base refresh to fit review's 1.199 parity size cap
* B2: inventory of gate and periodic phrase-only detector checks
docs/evals/detector-inventory.md lists every pass/fail decision in gate
and periodic E2E cases that rests on phrases in model free text, with
its structured source (if any), whether the contract is user-visible,
and a disposition: already structured-first, convert candidate, phrase
witness required, or no structured source. Convert candidates are
ordered by census red history.
* 0.2: failureCauseOf takes the stall window instead of importing it; the PTY ledger never throws
eval-store.ts imported STALL_WINDOW_MS from eval-budgets.ts, which free tests
replace with mock.module stubs (review-finalization-budget, office-hours,
qa-fix-loop, qa-only), so loading eval-store failed there. failureCauseOf is
now dependency-free: the record builders pass STALL_WINDOW_MS. A PTY session
whose handle cannot show its text (test doubles) records no panel instead of
throwing from runPtySession's cleanup. The 37186854666 replay also runs
through classifyTrialShard.
* A2/auto-decide: the CEO handoff chat repeats the helper's printed line verbatim
Claude Code 2.1.284 collapses the helper's Bash output ('Ran 1 shell
command'), so the 'Auto-decided review mode → …' line reaches the user only
through chat. In lane D's auto-decide-preserved corpus every passing capture's
chat starts with that line, and the reds paraphrased it ('HOLD SCOPE was
auto-selected…', 'Mode decision done…', "I'm defaulting to HOLD SCOPE…").
The template now says verbatim and why.
* C2: record the judge panels rerun on the final ship and review wording
* integrate: touchfiles and module-size ratchet entries for the wave's new modules
GLOBAL_TOUCHFILES gains session-ledger.ts, published-text.ts and
auq-substance-panel.ts; bin/gstack-bun-version.sh joins every entry that
lists setup or the updater; auq-matrix stays a rule case with its C4
evidence beside E2E_KINDS; eval-history, published-text and session-ledger
are registered new modules.
* E1: BROWSE SETUP install hint pins the tested Bun (1.4.0)
* E2: quote "$P" in make-pdf commands so install paths with spaces work
* E1: /gstack-upgrade checks the incoming Bun floor before pulling
gstack_bun_incoming_hold (bin/gstack-bun-version.sh) is now the one
pre-advance check: the auto-updater calls it before its fast-forward and
/gstack-upgrade's git path calls it after fetching. Below the incoming
release's floor the upgrade stops with BUN_TOO_OLD and the checkout,
VERSION and installs stay untouched. Vendored installs were already safe:
setup refuses before writing and the swap restores the previous install.
* 0.3: only main posts or closes tracking issues; reports carry alarms, red ledger, headroom and all-green
A branch-dispatched periodic or marathon run writes its report to the step
summary and a report artifact; the upsert and close steps run only on
refs/heads/main. The periodic body now keeps every pass-rate alarm line (the
old grep kept only the header), adds the red ledger and session headroom read
with an explicit --branch, the all-green estimate and the triage guide link,
and routes report text through scripts/lib/published-text.ts. The marathon
lane gains the matching close-on-green step.
Migrated: evals-workflow-wiring pinned report-summary.md in the upsert step;
the body is now written by 'Write the census report'.
* C3: prosons neutral-posture detector ignores a negated "taste call"
Both plan-review-prosons-neutral-neg reds (37179171083 t3, 37193478719 t3)
recommended A and closed with "a coverage call, not a taste call"; the
old /taste call/i matched the negation. The detector moves to a helper so
the two census captures replay free as negatives, with positive controls.
* B2: credit the CEO mode handoff only when the chat shows its line
Claude Code 2.1.284 collapses the gstack-ceo-mode-handoff Bash result, so
the printed AUTO_DECIDE line is user-visible only when a later chat message
of the session begins with it. The native detector now requires that
witness; the helper's tool result locates it but no longer replaces it, and
a generic mode statement cannot stand in once a handoff ran. Census
37182865432 is relabelled a genuine miss (expected: refused): the chat said
"I'm defaulting to HOLD SCOPE…" and "Mode decided: HOLD SCOPE". Corpus
replay: 5 credited, 3 refused. ceo-mode-handoff tests migrated to the
witness rule (deliberate behavior change).
* test: baseline the wave's approved detector and harness replay tests
B1 corpora, B3, C3, C4 and D2 replay captures through paid-case detectors,
actors or fixtures (test code by design); each entry carries its reason.
* E6: live Codex multi-block periodic case in the host-run Codex job
test/codex-e2e-multiblock-live.test.ts runs ./setup --host codex once from the
job's checkout into a fresh HOME and CODEX_HOME (auth.json copied from the CI
login home), asserts codex debug prompt-input lists the gstack router as a
real file, seeds one learning, and runs /learn's Show recent block through
codex exec: that later block must root itself through its prelude, run the
installed gstack-learnings-search and print the seeded learning; no block may
report a missing install or an unresolved gstack helper path.
The file joins CODEX_CI_FILES so the planner gives it to the host-run Codex
job. paid-test-durations.json carries a 180 s packing estimate (refreshed by
--write-durations after the first census) so the plan keeps every slice
within max-parallel. Oracles live in test/helpers/codex-multiblock.ts with
free replays in test/codex-multiblock.test.ts. Registration (E2E_TOUCHFILES,
E2E_TIERS periodic, E2E_KINDS rule) is the integrator's.
* E5: design live-model check as a periodic case
test/skill-e2e-design-model-smoke.test.ts runs design/scripts/live-model-check.ts
(default models only) under a temp HOME. Without OPENAI_API_KEY the case is a
Bun skip that the census lists as SKIPPED with no coverage credit; with a key,
exit 0 passes and any other exit fails with the script output (exit 2 under a
present key fails as 'nothing was checked'). paid-test-durations.json carries
a 90 s packing estimate. Registration (E2E_TOUCHFILES, E2E_TIERS periodic,
E2E_KINDS rule) is the integrator's.
* A1: docsync parent points children at a saved interface file
The /ship docsync fixture saved its observation interface only in the
parent prompt and told the parent to copy it into every child prompt,
about 30-40 s of parent generation per session (lane S, 37198445662).
docsSessionOptions now writes it to <home>/fixture-interface.md (0600) and
the parent tells each child to Read that file first. Fault-actor prompts,
which prepare already writes to a file, are unchanged. Fixture-only.
* A3: a JUnit case's recorded wall is capped by its shard's wall
junitCensus summed a case's JUnit test times as duration_ms; for
plan-mode-no-op's concurrent PTY tests that is 346 s inside a 176 s shard
(the "432-613 s" history). The case wall headroom shows is now
min(sum, shard elapsed), a true upper bound. Session headroom already
used the ledger's per-session clocks.
* A3: refresh paid-test durations from census 37198445662
Recorded 2026-09-29 estimates under-packed gate slice 11 (17 files
estimated 1078 s ran 1353 s; plan-review-report 76 s -> 198 s,
plan-ceo-plan-mode 37 s -> 112 s, safety-codex-consult 83 s -> 150 s).
Refreshed both tiers with --report --write-durations from the latest
census's slice walls. Old plan re-costed with observed walls: worst slice
~677 s (slice 11); refreshed plan: every slice estimated <= 539 s.
* C2: Browser Quick gets a feasible budget; QA loop names its directory and stop path
Judge rationales on the qa-only panels (2 of the last 3) cited the 30 s
Browser Quick budget: homepage + 5 targets, each a checkpoint write and a
guarded command, left ~5 s per probe. Quick is now 180 s (method text: 3
minutes); the qa-only-no-fix paid check expects the same native deadline.
PROBE_DIR points at its source line, a stopped loop goes to the final
report steps (annotations, materialize, Markdown), and /review and /ship
say that after smoke expiry only plan checks rerun in revalidation.
* C2: name the flows judges found implicit in review resolvers
Structured outside review: MISSING COVERAGE asks no fix question and is
never reported clean (was "preserve the existing user decision flow").
/review's HIGH-impact plan gate: spawned or non-interactive runs report
REQUIREMENTS MISSING and continue, writing no TODOs. Value cards: the byte
clamp applies to card lines; JSON records you write keep full values.
* C1: a free test catches a removed workflow step, which the judges missed
C1 controls showed the qa workflow judge passing /qa without Phase 10 and
the review judge passing /review without Step 3. The new test pins every
step/phase heading of qa, qa-only, review, ship, plan-ceo-review,
plan-eng-review and setup-deploy (derived from the templates' step
headings) and names any that goes missing or out of order; new step
headings must be pinned. The judge rubric is unchanged (EVAL_POLICY).
* size: fit the wave's wording under ship, review and qa parity caps
Measured after all lane merges: ship -79, review -210, qa -68 bytes over.
Trimmed the added wording first (post-expiry rule, MISSING COVERAGE,
plan-gate default, value-card JSON, stop line) and folded /review's
redundant INFORMATIONAL sentence and findings bullet. ship 268,036 (room
8), review 130,118 (room 1). qa needed 11 more bytes: cap 1.11 -> 1.1102
with the measured 93,305 / 84,049 = 1.11013 and its reason beside it.
* 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.
* TODOS: reliability follow-ups deferrals; close the Bun floor, make-pdf $P and #2709 reap
* 0.4: 'A census went red' guide; docs for causes, session ledger, headroom and new messages
docs/evals/census-red.md walks one red line to a diagnosis: prerequisites, the
report fields, eval:pass-rates --run/--reds/--headroom with expected output,
what unknown/insufficient/unrecorded data means, free replay, and the single
'after a repair' paid run allowed by TESTING_INTERNALS. Linked from
CONTRIBUTING, TESTING_INTERNALS and both census reports.
TESTING_INTERNALS documents the failure_cause glossary (one row per
FAILURE_CAUSES value, diagnostic only under EVAL_POLICY v1), failure_detail,
sessions[], cost_known, the session ledger, the pass-rates views and the 85%
headroom alarm, main-only tracking issues, overlay contract v4, auq-matrix's
3-sample substance panel and the E5/E6 periodic cases. troubleshooting.md
gains #bun-too-old and an anchor per new user-facing message from lanes P, D
and F. README names GSTACK_DESIGN_IMAGE_MODEL. test/census-red-docs.test.ts
pins the glossary to FAILURE_CAUSES, parses every guide command and checks the
links.
* v1.91.20.0: CHANGELOG and version for the reliability follow-ups
* regen: SKILL.md and sections for all hosts, digest, context-budget fixture
bun run gen:skill-docs --host all; goldens and llms.txt re-rendered
unchanged; bun test/helpers/capture-context-budget.ts.
* integrate: register codex-multiblock-live and design-model-smoke (periodic, rule)
* 0.4: census report and eval:pass-rates views link the census-red guide
* test: cookie approval fixture reverses the Bun install-hint pin (E1)
The historical approved cookie-workflow prompt carried BUN_VERSION=1.3.10;
the regenerated install hint now pins 1.4.0, so the fixture's reversal
list gains that edit like the earlier waves' entries.
* test: release floor counts the two new periodic cases (E5, E6)
* fix: /freeze, /guard, /unfreeze and /investigate work on Codex and other env-var hosts
Templates quoted "$HOME/.claude/skills/gstack/...", which the env-var hosts'
rewrites turned into "$HOME/.agents/skills/gstack/..." on Codex (a path a
global install never has; same class on the other hosts), and setup's
runtime roots had no freeze/bin. Quoted runtime paths now use
{{RUNTIME_ROOT}}: $GSTACK_ROOT on env-var hosts (the fence gets the
runtime prelude), the unchanged $HOME path on Claude. _link_runtime_dists
links freeze/bin and the careful/bin helper it sources into every
env-var host's root. Also fixes the same guess in /benchmark-models,
/retro and /diagram. test/env-host-runtime-assets.test.ts fails on the
previous code: no fence guesses a $HOME/<dir>/skills/gstack path, every
$GSTACK_ROOT path a fence uses is in the host's runtime root, and the
installed Codex /freeze and /unfreeze fences run from a fresh shell.
Template-reading tests now read the Claude render or expect the
placeholder (deliberate change).
* CHANGELOG/TODOS: lane W's workflow, cases and guide; the env-var host freeze fix
* E6: a block that reads a SKILL.md is not a missing install
The first live codex-multiblock-live run passed its real check (the /learn
block found the install and printed the seeded learning) but the oracle
flagged a sed of the learn SKILL.md, whose prelude source quotes the
'gstack: no install found (tried $_r)' text. Only an emitted line that
starts with the message and names a real root counts now; free replay
negative added.
* test: qa-only fixture keeps its caller-set 30 s deadline
The qa-only-no-fix fixture tells the model to start the guard with 30 s
(a caller limit), so its deadline assertion's default stays 30 000 ms; the
product's Browser Quick default (180 s) does not apply to it. Reverts the
helper and its test to their base.
* C2: keep PROBE_DIR 'owned' (qa-functional-prompt pins it); qa measured 93,311
* test: paid file count and periodic floor include the two new periodic cases
* test: ship docs freshness pin checks meaning after A1's wording trim
The snapshot still hashes selected release paths (--select narrows them),
generated outputs and docs; the pin now checks that instead of the
pre-trim sentence.
* E3: reap the recorded Chromium only after the daemon has exited
With the PID now recorded (E3), browse stop reaped Chromium while the
daemon was still shutting down; the daemon read that as a crash, exited 1
and left its state file (chromium-profile-isolation's headless stop test
failed 3/3 locally, passes on base). The CLI waits up to 5 s for the daemon
to exit before reaping a survivor.
* regen: qa and qa-only exploratory sections (PROBE_DIR wording)
* B1: batching counter reads a target declared mid-line; replay corpus
GSTA-23's census 37228573062 failed plan-eng-multi-finding-batching with
reviewCount=0 after 975 s although D1-D10 were asked one per finding,
each with its saved decision-ledger record. The report wrote 'Report
destination requested by the user. Review target (fixed): `PLAN.md` ...'
and the counter read target fields only at a line start, so no brief
inherited the plan identity. A target field may now open any sentence of
its line; a mid-sentence mention or another file still gives no identity.
Floor (3), budget and kind unchanged. Corpus: 9 earlier passing censuses,
the red (now credited at D5), and a derived batching refusal; 975 s noted
in the headroom diagnosis.
* B1: shared-libs corpus labels its git path and covers the supported shape
Every census entry was recorded in CI's eval image (git 2.43), where
gstack-safe-git falls back because --no-lazy-fetch is rejected; each entry
now says so (git_path: fallback). Two synthetic supported-path entries
(HEAD and a history citation in the brief, as git >= 2.44 produces) keep
the 37193478719 pass and the 37195203538 refusal, and a test asserts both
shapes are covered and the actor reads no git-path-specific text.
* v1.91.21.0: move off v1.91.20.0 (claimed by #3031)
* test: settle nav-guard commands before asserting; make two new tests Windows-safe
navigation-guard: Bun's expect(promise).rejects slows each Playwright round-trip
to ~1s while it waits (50 page.evaluate: 43ms plain vs 46.6s inside the matcher),
so the click's 5s timeout expired before the guard saw the link-local request
(CI: 'click: Timeout 5000ms exceeded ... waiting for scheduled navigations').
Settle the command first, then assert on the refusal; a source check keeps it so.
env-host-runtime-assets: PROBE_FILES now matches either path separator.
detector-corpus ship-docsync-late-result: JSON-escape the <ROOT> substitution so a
Windows temp path's backslashes do not break JSON.parse.
* fix: CI run/job ids are not phone numbers; context-recovery fixture gets the full runtime bin
pii.phone.e164 redacted the run id in the published eval report's fetch command
(--run 37235771700), breaking the command it prints. Digit-only spans in a run/job
flag, gh run argument, actions/runs/ or /job/ URL segment, or run_id/job_id key are
now exempt; the same digits elsewhere still report.
context-recovery-artifacts: the fixture's ./bin/ lacked gstack-skill-start and
gstack-context-recovery (the preamble's runtime scripts since v1.71), so the agent
spent its 10 turns hunting for them and hit error_max_turns with no final message
(run 37235771700, 11 turns). Link the whole runtime bin; diagnostic rerun passed
in 6 turns.
* test: replay run 37237194905's late-result capture through the docs authority detector
The only failure was call 20's write to a mistyped shard root (3GanyY for 3GanyU),
which the model disclosed; the detector is correct and the A1 post-snapshot
--out under the fixture home stays permitted. Named red recorded in TODOS.
* test: keep docsync-authority in the Windows profile
The replay test's literal helper path tripped the Windows curator's shebang-spawn
pattern, dropping the whole file from the Windows profile (test-free-shards
invariant). The snapshot --out case is already covered by docsync-command-grammar,
so it is removed here, and the Linux-path replay skips on win32.
* fix: gstack-docs-candidate --help works; docs gate red lines name the denying tool failure
PR run 37239016858 ship-docsync-completion: the parent ran
'gstack-docs-candidate --help' (the helper's usage error points at --help, which
failed). That undeclared command made docsToolFailures non-empty, which denied
the atomic-replacement proof of the child's legitimate native Edit, so the red
line blamed the Edit's temp file. A replay of the capture proves the atomic
replace once --help is declared.
- the helper prints its usage for --help/-h and exits 0
- the fixture interface and command grammar admit the helper's bare --help
- the atomic-proof denial names its check and the tool failures behind it
(deny labels renumbered to their lines)
- replay with negative controls (undeclared command, temp left behind, renamed
elsewhere); diagnostic rerun of ship-docsync-completion passed
* test: retro-base-branch fixture uses main and a shallow report path
PR run 37241493377: the agent wrote retro-output.md one directory above the
requested <tmp>/retro-base/retro-output.md (it dropped the retro-base segment),
so the report check found nothing. The fixture also ran plain git init, which
makes master on CI's git while the prompt says the repo is on main; the agent
logged that mismatch as a learning. Init on main and use the temp dir itself as
the repo. Diagnostic rerun passed (18 turns, 203s).
* test: qa-quick sets a caller probe limit and drains past its session budget
C2 raised Browser Quick's native budget to 180 s. qa-quick is the only gate case
on the native budget, and its wall went 194 s (main periodic, pre-C2) -> 254 s and
274 s (this PR's runs) -> 300 s session timeout (run 37242691913): the agent now
probes every navigation target with a checkpoint, then needs ~80 s to report.
Like qa-only-no-fix, the eval now sets a caller probe limit (30 s), scopes the
fixture, and gives bun's outer timeout the session drain margin instead of racing
the 300 s session. The product's 180 s budget and the session budget are unchanged.
Diagnostic rerun passed in 195 s.
* review/ship: use main's post-expiry smoke sentence; v1.91.24.0
GSTA-23's measurement on the review workflow judge: main's 'Post-expiry smoke
rechecks are not-run.' passed 10/10; the C2 wording passed 6/10 and the
'..., even in 4c.' variant failed in PR run 37248650879. qa-probe-gates pins
main's sentence before step 4c.
* test: record the plan-design corpus test in the test-of-test baseline
#3031's ratchet now counts tests that slice a paid test file's source; the B1
plan-design-review-plan-mode replay corpus reads test/skill-e2e-design.test.ts
like its sibling corpora already listed.
* fix: --case no longer deadlocks importing the running CLI
runCaseDiagnosis loaded runPaidShards with a dynamic import of
scripts/test-paid-shards.ts; when that file is the entry it is still in its
top-level await, so the import never resolved and `--case` hung after its
first line (on main since #3031, found by the per-case measurement runs). The
CLI now passes its runner in; library callers keep the lazy import.
* test: name the in-flight file and the native error when bun dies before its summary (#3037)
* Bun 1.4.2 everywhere CI and setup pin the tested version
Bun 1.4.0 on Windows aborts about 3% of free-suite shards with native
bad-handle errors (main too; #3037); the same head on 1.4.2 had none in 180
shard runs. Every current 1.4.0 pin moves together, as bun-version-drift
requires: setup-bun in every workflow (CSO orchestration included), the eval
image (sha256 from bun-v1.4.2's SHASUMS256.txt, re-hashed locally), GitLab,
the Ubicloud free-suite setup, gstack-bun-version.sh's tested version,
engines.bun and @types/bun, the install hint in generated skills, the Dia and
cookie native-qualification pins, and docs and tests that state the current
pin. Recorded 1.4.0 observations, fixtures, CHANGELOG history and the CSO
images' oven/bun:1.3.10 base stay.
* fix: --case runs a single-case file whole
A session option naming the case (testName: 'office-hours-section-loading')
made caseSelection pick test-name mode, whose filter matched no Bun test, so
every trial would run hollow. A file that registers only this case now runs
whole before any name match is tried.
* fix(office-hours): reviewer returns a hash-bound receipt instead of echoing its verdict
The spec reviewer now Writes its verdict once, seals it with
gstack-office-hours-review seal (validates the saved JSON and prints
OFFICE_HOURS_VERDICT round=N sha256=<hash> path=<verdict>), and returns
only that line. check --receipt recomputes the hash and fails closed on a
missing, malformed, stale-round, wrong-path or mismatched receipt. The
saved file stays the sole findings inventory; validators bind the receipt
to the saved bytes and the judge reads those bytes.
* fix(office-hours): only blocking findings send a design back for another review round
Review findings carry severity blocking|minor (verdict schema v2). PASS when
no blocking findings remain; minor findings are recorded in Reviewer
Concerns and the Spec Review table, never a reason for another round.
CONVERGENCE needs a persisting blocking prior. A persisting or unverified
blocking prior cannot be relabeled minor. The 3-round cap is unchanged.
* fix(office-hours): rounds 2 and 3 are delta re-reviews of the captured design diff
prepare saves each reviewed design as round-N.design.md and gives later
reviewers the exact line diff since the previous round. A new later-round
blocking finding must cite (changed_text) an excerpt of a changed line;
seal, check and the validators verify it against the snapshots and fail
closed when a citation or snapshot is missing. Other new observations are
minor. Severity, anti-downgrade and CONVERGENCE rules are unchanged.
* test(office-hours): preservation judge accepts COMPLETED with recorded minor findings
* fix(office-hours): parent fixes only blocking findings; callers may set --max-rounds
Between rounds the parent edits for blocking findings only; minor findings
stay recorded. gstack-office-hours-review takes --max-rounds 1|2|3 (default
3) on every command; reaching it stops at MAX_ITERATIONS. The marathon
fixture sets 2 rounds so round 1 (full) and round 2 (delta) run live.
* docs(changelog): office-hours review loop changes in v1.91.28.0
* fix(cso): helper JSON keeps run URLs only in the validated workflow slot
The shared redactor now treats GitHub Actions run ids as CI metadata
(c245d1bc2), so main's #3041 invariant that the same run digits stay
redacted outside qualification.workflow held only through the phone
false positive. Make it explicit in the CSO sanitizer.
* test(plan-ceo): split-overflow progress detector accepts the skill's candidate wording
Collection never ended when the model wrote 'E1 Slack:' / 'E1-SLACK:' or
labels like 'Include in this quarter' / 'Defer with flip trigger', so the
session ran the whole review (930-1464 s) and failed on its extra findings
or the case deadline (6 of 21 runs). The candidate check now accepts a
platform-bound E-id and the action is the bucket's leading verb, as the
skill names them (Include/Defer/Cut/Hold). The semantic judge, call floor
and include/defer/cut validation are unchanged. Replays the captured CI
37374526437, t2, t9 and t15 menus with negative controls.
* test(plan-ceo): split-overflow candidate identity is the one E1-E5 token
The skill fixes no header or question wording, and shape-matching kept
missing new forms (header 'D1.1 Slack' with 'SCOPE-E1:', 'D1.1 E1 Slack',
'E1 Slack DM bot ...:', a misspelled 'Mattermst'). Identity is now exactly
one E1-E5 token across the header and the question's first line, with no
other candidate's platform named. Options rules, judge, call floor and
include/defer/cut validation are unchanged. Replays all 31 measured runs;
the quoted-row controls now quote a second ledger id.
* v1.91.30.0: move past #3044's claimed 1.91.29.0
* test: register the split-overflow wording replay as a free fixture
* fix(skills): resolve judge-cited ambiguities in /qa and /plan-eng-review
- tasks JSONL keeps the raw branch as GIT_BRANCH instead of overwriting
gstack-slug's sanitized BRANCH used for artifact names
- the Codex outside-voice block runs for ready or unverified, matching
its routing rule
- plan-eng startup names the preamble's own setup prompts; the
cross-project question waits for Step 0
- /qa 8c: a fix that applies but leaves the finding reproducing gets one
revised fix, else it is reverted; browser verification names its before
screenshot; the exploratory loop drops its duplicate 3-step summary
* fix(plan-eng): keep the startup steps in their pinned order
* fix(plan-eng): explicit spawned sessions follow the spawned rule at the scope gate; one announcement rule
A missing tool still sends the prose menu whatever the session type, but a
session the caller or host explicitly marks spawned selects the menu's
Recommendation without prose or BLOCKED. The pre-load announcement
sentence now states Step 0's single check.
* eval policy v3: judge panels gate on the per-dimension median of 3 samples
A judge dimension now passes when at least 2 of its 3 samples meet the
unchanged threshold (judgePanelMedian); any other sample count or a
non-numeric sample fails closed. Thresholds, sample count, judge model and
prompts are unchanged; panel logs show every sample and the mean, and name
the median as the gate. Applies to the skill-llm-eval panels, the
workflow-judge cache, the auq-matrix substance panel and the calibration
replicas. EVAL_POLICY 2 -> 3 and HARNESS_VERSION 1 -> 2 (verdicts change),
so every case starts a new pass-rate series. Replays the captured panels
from jobs 112032744416 and 112049856586 as replayed evidence.
1103 lines
70 KiB
Markdown
1103 lines
70 KiB
Markdown
# Testing internals: env keys, hermetic E2E
|
||
|
||
Moved verbatim from CLAUDE.md (token-load reduction). Read this before
|
||
writing or debugging E2E tests, passing `env:` to a runner, or touching
|
||
`test/helpers/hermetic-env.ts`.
|
||
|
||
**Env keys in Conductor workspaces.** The `GSTACK_*` env-shim (v1.39.2.0+,
|
||
`lib/conductor-env-shim.ts`) promotes `GSTACK_ANTHROPIC_API_KEY` /
|
||
`GSTACK_OPENAI_API_KEY` to their canonical names inside gstack's TS binaries.
|
||
Tests run through gstack entrypoints inherit this promotion automatically.
|
||
Don't echo the key value to stdout, logs, or shell history. The historical
|
||
"never pass `env:` to `runAgentSdkTest`" rule is retired: the failure was
|
||
partial-env replacement (the SDK's `Options.env` REPLACES the child's entire
|
||
environment, so an object without the key broke auth). The runner now always
|
||
passes a COMPLETE hermetic env with per-test `env:` merged last, so per-test
|
||
overrides are safe; ambient `process.env.ANTHROPIC_API_KEY` mutation also
|
||
still works (the env builder reads process.env at call time).
|
||
|
||
**Hermetic local E2E (default).** Every E2E runner (claude -p, PTY, Agent
|
||
SDK, codex, gemini) spawns children through `test/helpers/hermetic-env.ts`:
|
||
allowlist-scrubbed env (operator `CONDUCTOR_*`, `CLAUDE_*`, `GSTACK_*`,
|
||
`MCP_*`, `GBRAIN_*`, and credentials like `GH_TOKEN` never reach children),
|
||
a fresh seeded `CLAUDE_CONFIG_DIR` (no operator `~/.claude` CLAUDE.md /
|
||
MCP servers / skills), a temp `GSTACK_HOME`, and `--strict-mcp-config`.
|
||
Local eval signal matches CI. Debug against real operator state with
|
||
`EVALS_HERMETIC=0` (restores the legacy env AND drops the strict-MCP flag).
|
||
Per-test `env:` overrides merge last, so deliberate contamination
|
||
(`CONDUCTOR_WORKSPACE_PATH`, per-test `GSTACK_HOME`) keeps working. The
|
||
hermetic config dir seeds NO skills by default; a PTY test that types a
|
||
`/skill` slash command must pass `seedSkills: true` to the PTY runner, which
|
||
points the child's `CLAUDE_CONFIG_DIR` at `hermeticSkillsConfigDir()` — a
|
||
seeded registry that symlinks the LIVE working tree's SKILL.md files (by
|
||
design: the skills ARE the subject under test; a snapshot would measure stale
|
||
copies). Wiring is pinned by `test/hermetic-wiring.test.ts` (static tripwire),
|
||
two gate-tier canaries in `test/skill-e2e-hermetic-canary.test.ts`, and the
|
||
seeding tripwires in `test/hermetic-skills-seeding.test.ts` /
|
||
`test/pty-skill-seeding-wiring.test.ts`.
|
||
|
||
Seeded planning sessions also receive an isolated runtime home through
|
||
`test/helpers/hermetic-skill-runtime.ts`, so absolute lazy-section paths resolve
|
||
to the working tree under test. Explicit per-test home overrides remain intact.
|
||
Autoplan resolves each review skill from its own installed host registry.
|
||
|
||
**Interactive planning evidence.** Native plan-review count drivers use
|
||
`observeScreen: true` and await `currentScreen()` before choosing an input. The
|
||
existing xterm dependency interprets cursor moves and erases; old menus in the
|
||
raw stream cannot establish a current prompt. Snapshots preserve
|
||
`terminal.raw.log`, `terminal.visible.log`, and `terminal.screen.log` separately.
|
||
Setting `EVALS_RUN_ID` or `GSTACK_EVAL_DIR` retains these snapshots; an output
|
||
directory without a run ID gets a stable, unique local ID for that writer.
|
||
Completed native transcript calls establish question counts and phase coverage.
|
||
Report-aware count tests also require a fresh, complete report and native
|
||
completion evidence before accepting a completion heading.
|
||
|
||
The periodic first-question matrix uses `test/helpers/auq-native-capture.ts`
|
||
to match the first public `PreToolUse` AskUserQuestion payload to its current
|
||
native display. It grades that question's exact public fields without answering
|
||
it or reading model transcripts. `question_captured` records
|
||
`workflowCompleted: false`. With `GSTACK_EVAL_DIR`, `EVALS_RUN_ID`, or an explicit
|
||
run ID, `native-auq/<run-id>/<test>-<suffix>/capture.json` under the eval directory
|
||
retains the public payload, bounded current viewport, and capture outcome.
|
||
CEO mode selection uses the actual SDK `AskUserQuestion` permission callback
|
||
in `auq-sdk-capture.ts`, with the existing 12-turn and 240-second limits. It
|
||
captures the public question and stops without submitting an answer; its
|
||
`question_captured` outcome also records `workflowCompleted: false`. The retained
|
||
capture survives fixture cleanup. Provider refusals and malformed questions
|
||
remain failures. Section-loading captures retain their noninteractive contract.
|
||
|
||
Shared-code revalidation fixtures pair public tool calls with their successful
|
||
results to verify that the current trusted start record was inspected before
|
||
completion. A discovered path in tool output counts; a path mentioned only in
|
||
instructions or narration does not. Saved public captures cover absolute and
|
||
relative paths and discovery followed by a read. The revalidation prompt supplies
|
||
the path to the trusted start-record directory and declares the existing turn
|
||
limit. It asks the agent to batch independent reads and retrieve the complete
|
||
final record; every source, approval, persistence, and completion check still applies. The
|
||
path-boundary fixtures use this same execution contract for symlinks, submodules,
|
||
ignored files, index flags, and legacy or filtered evidence. Their skip actor
|
||
accepts an explicit no-change choice; a preservation word inside an option that
|
||
also approves changes cannot authorize edits. Captured native questions exercise
|
||
the actual answer callback, and native turn-limit failures still fail even after
|
||
a question was answered.
|
||
|
||
The engineering and DX finding fixtures check coverage of their seeded issues
|
||
rather than cap the total number of review questions. Each decision needs a
|
||
distinct, completed native question with an offered answer; accepting, rejecting,
|
||
or deferring a recommendation all count as reviewing it. Engineering's mandatory
|
||
legacy regression tests also need affirmative plan or public-narration evidence.
|
||
Additional useful questions are allowed within the existing time limits. Generic
|
||
question counts remain diagnostic, and a fresh final review report is required.
|
||
|
||
E2E tests stream progress in real-time (tool-by-tool via `--output-format stream-json
|
||
--verbose`). Results are persisted to `~/.gstack/projects/<slug>/evals/` (legacy
|
||
fallback `~/.gstack-dev/evals/`) with auto-comparison
|
||
against the previous finalized run (in-flight `_partial` files are never used as
|
||
a baseline, so a run can't compare against itself).
|
||
|
||
The periodic overlay fixtures use a versioned behavior gate with efficacy
|
||
reported separately. See [Overlay benchmark contract v4](OVERLAY_BENCHMARK_CONTRACT.md)
|
||
for exact correctness requirements, retired fanout cases, immutable evidence,
|
||
and the limits of a passing result. Under v4 a completed wrong answer is a
|
||
measured correctness result in either arm (`taskCorrect: false` with
|
||
`answerError`); only an overlay-ON wrong answer fails the case, so an
|
||
overlay-OFF wrong answer stays in the comparison. v3 verdicts keep their
|
||
original meaning.
|
||
|
||
## Coverage ownership
|
||
|
||
[The test portfolio audit](TEST_PORTFOLIO.md) separates deterministic harness
|
||
checks, prompt judges, live first-question captures, completed workflows and
|
||
platform integrations. Shared setup is reusable; evidence with different
|
||
scenario or independent-trial requirements is not. It records the preserved
|
||
coverage and measured component savings from the test-speed refactor.
|
||
|
||
## Runners: how the suites execute (2026-08 overhaul)
|
||
|
||
**Aside-only E2E tests self-skip without a live Aside; browser-driving tests
|
||
run on either engine.** Every skill that opens a web page drives the Aside AI
|
||
browser first (`scripts/resolvers/aside.ts`) and falls back to gstack's own
|
||
browse engine when Aside is absent (and Chromium bootstrapped). The cases that
|
||
need Aside itself (`test/skill-e2e-aside.test.ts`, `design-review-fix` in
|
||
`test/skill-e2e-design.test.ts`) call `asideAvailable()` from
|
||
`test/helpers/aside-available.ts` (the same probe the skills run in BROWSER
|
||
SETUP) and skip when the `aside` CLI or the Aside app is absent. CI runners have
|
||
no Aside, so those run only on macOS dev machines and sit in the periodic tier;
|
||
set `GSTACK_SKIP_ASIDE=1` to force the skip locally (which also exercises the
|
||
fallback hand-off). The qa E2E files (`test/skill-e2e-qa-workflow.test.ts`,
|
||
`test/skill-e2e-qa-bugs.test.ts`) gate on `asideAvailable() ||
|
||
fs.existsSync(browseBin)`: the skill's own BROWSER SETUP picks the engine, so
|
||
on a Mac they drive Aside and on Linux CI they drive the built browse binary,
|
||
skipping only when neither exists. The `$B`-driven E2E cases and `browse/test/`
|
||
run on every platform as before, so Linux CI proves the fallback engine live.
|
||
|
||
**Bootstrap dependency retention is opt-in qualification, not the behavior test.**
|
||
`qa-bootstrap` still runs its original unpinned Vitest installation and assertions
|
||
on macOS and Linux, including documented unsharded commands. Only a Linux paid
|
||
shard runner issues the owned retention scope: it binds each actual fixture and
|
||
native lifetime, retains locks, package manifests and the installed file/link
|
||
inventory, and acknowledges capture before deleting the fixture. The outer
|
||
runner also captures evidence when a callback is killed. Incomplete capture
|
||
fails qualification and preserves the source fixture as well as partial evidence.
|
||
Other platforms explicitly report retention as unavailable and still execute the
|
||
native behavior test. A run without the runner-issued scope earns no retained
|
||
dependency qualification credit; candidate acceptance requiring that evidence
|
||
must use the Linux sharded path and verify every attempt's complete capture,
|
||
acknowledgment and cleanup fallback. A passing unsharded or macOS behavior test
|
||
does not substitute for that evidence.
|
||
|
||
**The renderer picks the same way, so the render gates are engine-agnostic.**
|
||
`/make-pdf`, `/diagram`, and design previews print and screenshot their local
|
||
HTML through `lib/aside-render.ts` / `bin/gstack-render.ts`, which render in
|
||
Aside when `probeAside()` says `READY` and through the browse engine otherwise.
|
||
make-pdf's `*-gate.test.ts` and `test/skill-e2e-diagram.test.ts` (periodic,
|
||
paid) gate on `browserAvailable()` (`test/helpers/browser-available.ts`:
|
||
`asideAvailable() || resolveBrowseBin() !== null`) — on a Mac they print
|
||
through Aside, on Linux CI through the browse binary `bun run build:gates`
|
||
compiles, and they skip only when neither exists. Only
|
||
`test/aside-render.test.ts`'s two live Aside cases (a full round-trip and a
|
||
late-readiness `--wait-expr` poll) are Aside-only: its option
|
||
mapping and generated-script pins run everywhere, and its fake-executable cases
|
||
drive both engines hermetically (fake `aside` / `browse` scripts on PATH pin
|
||
probe classification, the stdout contract, loopback-server policy, the timeout
|
||
kill, engine choice and the mid-run fallback). `test/gstack-render-cli.test.ts`
|
||
does the same for `bin/gstack-render.ts` with `GSTACK_SKIP_ASIDE=1` and
|
||
`GSTACK_BROWSE_BIN` pointed at a fake daemon that logs every argv line. A green
|
||
gate on Linux proves the fallback engine, not Aside; the Mac run is the Aside
|
||
evidence.
|
||
The browse-binary leg presumes Chromium bootstrapped: `resolveBrowseBin()`
|
||
only checks that the binary (or the `find-browse` shim) exists, never that
|
||
Chromium can launch, so on an install where the best-effort Chromium step
|
||
was skipped (`GSTACK_SKIP_PLAYWRIGHT=1`) or failed, these gates run and fail
|
||
at browser launch instead of skipping. Fix the bootstrap (or move the binary
|
||
aside) before running them locally; CI always installs Chromium first.
|
||
`test/dom-dump-hygiene.test.ts` is the one free-suite case on the same leg: it
|
||
runs `lib/dom-dump.js` (the rendered-DOM dump `/design-review` hands the design
|
||
detector) inside a real Chromium page through the built browse binary, so it
|
||
self-skips when the binary is absent and, because a cold Chromium launch is
|
||
load-sensitive on a busy dev box, runs only in CI or on explicit opt-in
|
||
(`GSTACK_DOM_DUMP_HYGIENE=1`).
|
||
|
||
**Free suite (`bun run test:free`).** `scripts/test-free-shards.ts` runs N
|
||
concurrent shard processes (serial within each) with strict-output
|
||
classification per shard. Local defaults use the available CPU affinity
|
||
(which Bun also bounds by a container's cgroup CPU quota), floored at one and
|
||
capped at 16 on Linux and six on macOS and Windows; `GSTACK_FREE_JOBS` remains
|
||
an explicit override.
|
||
This does not change the separate CI machine count. Full-suite shards are packed by RECORDED PER-FILE
|
||
DURATIONS (LPT, `packShardsByDuration`) when the committed seed
|
||
`scripts/free-test-durations.json` exists — refresh it with
|
||
`bun run test:ubicloud --record-durations`, which times each file in its own
|
||
child on a VM with the CI lane's environment and copies the seed back; see
|
||
[Free suite duration seed](#free-suite-duration-seed). Missing seed → silent hash-shard fallback; corrupt seed → one warning +
|
||
fallback; unknown files get 99th-percentile pessimism, and both full-suite and
|
||
`--ci-plan` runs name them on stderr so a new slow file cannot silently become
|
||
the long pole. Packed
|
||
shards get duration-aware walls (`max(base, predicted × 3, files × 5s)`). The
|
||
legacy `--shards N --shard i` path keeps stable hash indices. Required CI uses
|
||
one duration-packed `--ci-plan`, 20 ordinary `--ci-run` shards plus a separate
|
||
exclusive-fixture shard, and a `--ci-verify` aggregate. CI shards still run on
|
||
independent machines without ordering unrelated jobs. The public
|
||
`TREE_MUTATING` map now classifies exclusive host-state fixtures; its sole
|
||
entry is `test/bootstrap-retention.test.ts`, whose same-UID nondumpable actors
|
||
affect host-wide procfs permission checks. Locally, this file runs only after
|
||
all parallel shards settle, and cancellation prevents that final phase from
|
||
starting. No selected files, retries, budgets, or receipt requirements are
|
||
removed. Former generator mutators still render into private output directories;
|
||
this serial phase protects process visibility, not in-place doc generation.
|
||
|
||
Full child output is retained in private files under `.context/free-test-logs/`,
|
||
outside each shard's temporary cleanup directory. The runner prints the path at
|
||
launch and completion. Losing the log fails the run even when the child exits
|
||
successfully. A redirected log directory is rejected before launching a child.
|
||
On failure, read that log first: the recovery message distinguishes incomplete
|
||
capture, unconfirmed cleanup, deadline expiry and a test/module failure. Fix the
|
||
demonstrated cause before rerunning. A focused `bun test` command is offered only
|
||
when every failure is attributable to existing selected files; it proves that
|
||
repair, not completion of the original selection. Preserve failed attempts when
|
||
sharing results, and inspect logs for private data before sharing them.
|
||
|
||
Before publication, classify new deterministic regressions for quick feedback.
|
||
Refresh the timing seed with the existing recorder on fixed inputs; do not edit
|
||
source while tests run. Critical boundary controls belong in `QUICK_CORE` when
|
||
their feedback cost is justified. Other measured files qualify at two seconds
|
||
or less; slow and unmeasured files remain outside quick, not outside full tests.
|
||
Report cold setup separately from warm execution, while retaining failed-attempt,
|
||
retry and cleanup time in the total cost.
|
||
|
||
**PTY fixture timing.** Plan-count sessions wake on terminal output or exit,
|
||
with at least 250ms between expensive observations and a 2s fallback for
|
||
transcript or hook changes that produce no terminal output. New output batches
|
||
settle for 250ms before observation so split terminal redraws cannot route input
|
||
from their first chunk. Input debounces,
|
||
permission guards, and the real CLI's 8s startup grace are unchanged. Synthetic
|
||
CLIs can pass `startupReadyMarker` to `runPlanSkillCounting` and emit that exact
|
||
marker after installing their input handlers; a missing marker fails before
|
||
any command is sent. The marker wait stays inside the existing startup and
|
||
total-run deadlines. `test/pty-output-wake.test.ts` covers output, silent waits,
|
||
exit, close, missing readiness, split redraws, and continuous redraws. Close and output waits
|
||
cancel their losing deadlines so completed workers can exit immediately.
|
||
|
||
The UI-positive design gate commits the supplied plan as `review-input.md`
|
||
before the first model turn. It requires an acknowledged Design focus/rating
|
||
question followed by an answered native finding about concrete UI behavior;
|
||
setup and outside-review choices cannot satisfy that sequence. Its declared
|
||
board actor submits feedback before acknowledging it. The final proof uses
|
||
the full native question, not the truncated diagnostic snippet, and proposal
|
||
text mentioning "no UI scope" is not treated as an exit verdict. Unknown-command
|
||
failures must name the invoked slash command; a child tool rejecting `--help`
|
||
is not a skill registration failure. Periodic seeded-finding classifiers
|
||
separately verify fixture-owned findings.
|
||
|
||
**Paid suite (sharded runner, local AND CI).** `scripts/test-paid-shards.ts`
|
||
is the single selection engine: 1 file per shard, `EVALS_JOBS` shard
|
||
processes × `EVALS_CONCURRENCY` within-shard, per-shard `GSTACK_EVAL_DIR`,
|
||
full-stream spooling to per-shard log files (path printed at START and on
|
||
failure), never-started/timed-out taxonomy, and parent-computed diff
|
||
selection propagated to children via `EVALS_SELECTION_JSON` (fail-open: a
|
||
child that can't parse it recomputes locally with one warning). Paid evals
|
||
never retry; each case's kind fixes its trials before the run (see "Eval verdict
|
||
policy" below). Files in `CASE_SHARDED_FILES` run one registered case per
|
||
process (`<file>#<case id>`, an exact `--test-name-pattern`, exactly one executed
|
||
case), so a long file of short cases spreads across runners and each case gets
|
||
its own SDK semaphore. `test/carve-section-loading.test.ts` is one of them: it registers
|
||
one periodic case per carved skill (`carve-section-loading-<skill>`, each with
|
||
its own touchfiles and history). Run one case with
|
||
`bun run scripts/test-paid-shards.ts --tier periodic --case carve-section-loading-<skill>`.
|
||
Trial telemetry rides the store: every recorded test carries its 1-based
|
||
`attempt` plus, on an isolated trial shard, its `case_id`, `kind`, `trial`,
|
||
`panel` and `policy_version`, and each lane's report uploads one
|
||
`trial-outcomes` JSONL line per trial. `bun run eval:pass-rates`
|
||
turns that history into per-case pass rates
|
||
(see "Pass-rate history" below; free-suite flakes are a separate record, see
|
||
[Flake ledger](#flake-ledger)). Census integrity is
|
||
enforced from the free suite: every `E2E_TOUCHFILES` / `LLM_JUDGE_TOUCHFILES`
|
||
key must name a living paid test (`test/touchfiles.test.ts`'s reverse
|
||
invariant), and `git show <sha>:path` fixtures are banned — vendor the bytes
|
||
instead (`test/git-ref-fixture-tripwire.test.ts`).
|
||
|
||
Functional QA and documentation acceptance require an explicit `EVALS_RUN_ID`;
|
||
`GSTACK_EVAL_DIR` alone does not satisfy their evidence-ownership guard. For each
|
||
local invocation, supply a fresh ID to the documented detached runner:
|
||
|
||
```bash
|
||
EVALS_RUN_ID="local-$(bun -e 'console.log(crypto.randomUUID())')" bun run eval:bg:pr
|
||
```
|
||
|
||
Neither package scripts nor `gstack-detach` invent this identity. CI's PR/manual
|
||
slices, periodic slices and weekly gate census supply an ID bound to the workflow
|
||
run, attempt, job and slice. Existing slice artifacts retain per-shard snapshots;
|
||
separate always-run `native-captures-<EVALS_RUN_ID>` artifacts retain project/legacy
|
||
`e2e-runs` and `evals/qa-callers` evidence for 90 days. These diagnostic artifacts
|
||
are not collector results and do not establish that an unfinished test passed.
|
||
|
||
**Fast PR profile and evidence reuse.** `test:pr` selects the changed cases in
|
||
`scripts/test-pr-profile.ts` plus every changed quality judge. `--profile full`
|
||
retains the broad census; no case IDs or tier assignments are removed. The plan
|
||
records both E2E and judge selections and lists deferred coverage. Executors
|
||
receive those selections separately and the report checks actual executed case
|
||
counts. Unknown source dependencies restore the broad gate (see
|
||
[PR paid lane fallback](#pr-paid-lane-fallback)); unmapped prompts
|
||
without registered coverage require full validation. Known broad-only prompt
|
||
changes are explicitly deferred, not counted as PR passes. Weekly/manual runs of
|
||
`evals-periodic.yml` execute both complete censuses fresh; manual `evals.yml`
|
||
runs the broad gate. This deliberately moves some defect detection later.
|
||
|
||
`scripts/eval-input-cache.ts` accepts only complete, clean, first-attempt passes
|
||
with matching before/after inputs. The audited workflow-judge adapter hashes the
|
||
actual expanded prompt, source/fixture/rubric/runner closure, installed SDK,
|
||
model parameters and runtime. Missing/unknown inputs force execution. Receipts
|
||
are scoped to the same repository and PR, expire after 24 hours, and contain
|
||
public scores and provenance rather than prompts or secrets. Of the 17 cases
|
||
using `runWorkflowJudge`, 16 are eligible; the cookie workflow's custom input
|
||
does not match the cache adapter and stays fresh, as do the other 11 quality cases.
|
||
CI supplies the scoped cache/runtime configuration; local runs are fresh by
|
||
default. Cached scores must
|
||
pass current assertions; reused records retain their original source and time
|
||
and cannot renew the receipt. `scripts/e2e-shard-reuse.ts` extends the same receipts
|
||
to PR-profile E2E shards (paid evals never retry, so a pass is structurally a
|
||
first attempt): the identity hashes the test's import closure, every tracked file
|
||
matched by the touchfiles of every case the file registers plus the global
|
||
touchfiles, the runner/workflow/setup actions, the child's environment pins, the
|
||
CI image and Claude CLI version, and the shard's case ids, pattern, wall and
|
||
concurrency. A computed registration, an unmatched touchfile pattern, a retrying
|
||
file, a preload option or a custom endpoint makes the shard ineligible. A reused
|
||
shard reports `reused` with its source run and writes `execution: "reused"`
|
||
collector records; the report rejects reused outcomes outside the fast PR profile.
|
||
`EVALS_FRESH=1`, periodic, marathon and release validation bypass both lookup and publishing.
|
||
|
||
**Free test timing and isolation.** `test:quick` is an explicitly partial measured
|
||
subset for edit feedback. `test` remains complete local acceptance with its
|
||
bounded worker pool. The CI planner inventories every free file and packs them
|
||
using `scripts/free-test-durations.json`; each machine runs its assigned shard
|
||
serially. Plans and receipts bind the source revision, complete inventory and
|
||
strict outcomes; missing, duplicate or mismatched receipts fail the required
|
||
aggregate. The existing maximum five-file flaky retry allowance applies across
|
||
the entire lane, not separately to every machine. Refresh the full timing list
|
||
with `bun run test:ubicloud --record-durations`. Profiling records failures faithfully
|
||
and is separate from final release acceptance.
|
||
|
||
**CI planner/executor/report.** `--emit-plan <path> --slice-budget S --jobs J`
|
||
(CI) or `--slices K` (local) computes selection + the slice plan ONCE (killing
|
||
per-slice selector divergence);
|
||
`--plan <path> --slice i` executors consume the manifest and write
|
||
slice-result artifacts; `--report <dir>` reconciles them FAIL-CLOSED (a slice
|
||
whose artifact never landed, or a planned shard nobody reported, is a
|
||
failure). Budget mode (`packBySliceBudget`) places shards longest-recorded-first
|
||
into the fullest slice whose estimated wall on J FIFO workers stays within S
|
||
seconds, else a new slice; a shard with no recorded wall weighs the whole budget
|
||
(its own runner), a shard longer than the budget runs alone, and overlays keep
|
||
one final one-at-a-time slice. The manifest's `plan` records each slice estimate
|
||
and its own CI job ceiling in `sliceCiTimeoutMinutes`: max(2 × slice budget, the
|
||
slice's longest shard supervised wall, the serialized overlay envelope) + 20
|
||
minutes setup (`CI_SETUP_ALLOWANCE_MINUTES`); `ciTimeoutMinutes` is the largest of
|
||
them. CI derives the matrix (`[range(1; .sliceCount + 1)]`) from the manifest and
|
||
indexes each slice's ceiling as its job timeout
|
||
(`fromJSON(needs.plan-slices.outputs.slice_timeouts)[matrix.slice]`). Executors
|
||
refuse an `EVALS_JOBS` other than the planned J and run their shards longest first.
|
||
|
||
Each executor's first step records its job start (`GSTACK_SLICE_JOB_STARTED_AT`).
|
||
The slice deadline is that start + the slice ceiling − a 5-minute upload reserve:
|
||
after it the executor starts no more shards. A shard that never started reports
|
||
`not_run` (INFRA, `never-started`); a shard still running is killed and reports
|
||
`hung` (TIMEOUT, `timed-out`). The executor checkpoints `slice-N.json` after every
|
||
shard start and finish, so a job killed before its final write reports from the
|
||
checkpoint (`slice N/M ended before its final result …: TIMEOUT`), never as a
|
||
missing slice. `--slices K` keeps the supervised round-robin
|
||
baseline re-packed by recorded times for local runs. Durations are recorded per
|
||
tier (a file's gate and periodic cases differ); refresh one tier from a
|
||
downloaded report directory with `--report <dir> --write-durations`. Under `EVALS_ALL` the hollow-shard guard marks exit-0 shards with
|
||
ZERO executed tests `passed-empty` (a failure) — census-health, not just
|
||
test runs. evals.yml runs the sliced gate lane per PR — the ONLY paid lane
|
||
since the legacy 17-row matrix (22.6 min/$21 per PR serialized ahead of the
|
||
slices) was deleted after demonstrated parity; its
|
||
`KNOWN_MATRIX_GAPS`/`KNOWN_TIER_UNSET` ratchets retired with it and
|
||
`test/evals-workflow-wiring.test.ts` pins the surviving wiring (slice-count
|
||
agreement, tier consistency, the shared register-skills composite with its
|
||
fail-fast verification loop). Tier `marathon` (complete start-to-finish flows)
|
||
is selected positively: a file enters the marathon plan only when it declares
|
||
`describeE2ETier('marathon')` or registers a marathon-tier case, and the gate and
|
||
periodic planners exclude marathon-only files; `evals-marathon.yml` runs them
|
||
weekly and on dispatch, fresh, one file per runner, with its own fail-closed
|
||
report and tracking issue, and nothing requires it. evals-periodic.yml runs ALL
|
||
periodic-tier files weekly (the coverage contract) minus the reasoned
|
||
exclusions in `test/helpers/periodic-exclude-data.ts` (reason + tracking
|
||
required per entry; removal re-activates the file), plus a weekly
|
||
`EVALS_ALL` gate census. A red census writes one report on every ref, to the
|
||
step summary and the `census-report-a<attempt>` artifact: the run's branch, sha
|
||
and event, both lanes' summaries, every pass-rate alarm line, the red ledger
|
||
and session headroom (`eval:pass-rates --reds` / `--headroom --runs 10 --branch
|
||
<ref>`), the all-green estimate and a link to the red-census guide, with
|
||
report-derived text passed through `scripts/lib/published-text.ts`. Only a run
|
||
on `refs/heads/main` comments on (or opens) the one tracking issue and closes it
|
||
on the next green run; the marathon lane does the same with its own issue and
|
||
`marathon-report-a<attempt>` artifact. `test/evals-tracking-issue.test.ts`
|
||
pins the main-only guard and runs both report scripts. The host-run Codex job
|
||
also carries the live Codex multi-block case (`codex-multiblock-live`: `./setup
|
||
--host codex` from the job's checkout into a fresh `CODEX_HOME`, the router in
|
||
`codex debug prompt-input`, and a later /learn block rooted by its own
|
||
prelude), and the periodic lane runs the design default-model smoke
|
||
(`design-model-smoke`), a visible SKIPPED with no coverage credit when
|
||
`OPENAI_API_KEY` is absent. The CI
|
||
image pins the claude CLI to an exact version (`.github/docker/Dockerfile.ci`,
|
||
enforced by `test/ci-image-cli-pin.test.ts` — bumps ride PRs that run the PTY
|
||
gate), and every eval-store run records `claude --version`, resolved once in
|
||
the runner parent and handed to shard children as `GSTACK_CLAUDE_CLI_VERSION`
|
||
(never spawned on a test thread), so a TUI-drift flake hunt is a grep, not
|
||
archaeology.
|
||
|
||
<a id="eval-verdict-policy"></a>
|
||
**Eval verdict policy** (`EVAL_POLICY` version 2 in
|
||
`test/helpers/periodic-exclude-data.ts`; version 1 pre-registered 2026-09-29,
|
||
version 2 approved 2026-10-04 with the decision memo in
|
||
[test-audit-2026-10.md](test-audit-2026-10.md)). Paid evals
|
||
never retry. Each live case has exactly one kind in `E2E_KINDS`
|
||
(`test/helpers/touchfiles-data.ts`; `test/eval-kinds.test.ts` enforces coverage),
|
||
and the kind fixes its trials before the run:
|
||
|
||
- `rule` (default): one trial; any failed assertion fails the verdict. For
|
||
cases where nothing stochastic decides the verdict, or where it checks a
|
||
contract the product must meet every run.
|
||
- `behavior`: a panel of `n = 3` independent trials, launched together as
|
||
isolated case shards on different slices (key `<file>#<id>~t<N>`). All three
|
||
always run: no early stop and no conditional extra trial. PASS when at least
|
||
`k = 2` pass and no trial violated a contract (`expectContract()` stamps
|
||
`failure_class: 'contract'`). Each behavior case names its tolerated deviation
|
||
in `BEHAVIOR_WHY` and must have a literal registration so it can run alone.
|
||
- `judge`: an LLM judge scoring a fixed input. `judgePanel()`
|
||
(`test/helpers/llm-judge.ts`) draws 3 samples of the same prompt concurrently
|
||
inside the unchanged `JUDGE_MS`; numeric dimensions gate on the per-dimension
|
||
median of exactly 3 samples, so at least 2 of 3 must meet the unchanged
|
||
threshold (`judgePanelMedian()`; no dimension compensates for another, and
|
||
any other sample count fails closed), booleans on a strict majority. Panel
|
||
logs show every sample and the mean for information; the median is the gate
|
||
(EVAL_POLICY v3, approved 2026-10-06). A sample that errors (refusal, truncation,
|
||
non-JSON, a malformed field) fails the panel and is never resampled; a
|
||
refusal counts as an unscored panel only when every sample refused.
|
||
`callJudge`'s 429 backoff happens before any model output and is transport,
|
||
not a verdict retry. The workflow-judge cache stores whole panels only.
|
||
The `rule` case auq-matrix uses the same panel inside its one execution: each
|
||
skill's single native capture has its recommendation substance scored by 3
|
||
judge samples, gated on their median against the unchanged minimum of 4, and a
|
||
failed sample fails the panel without resampling (approved 2026-10-04 for
|
||
censuses after the change).
|
||
|
||
`panelVerdict()` (`test/helpers/eval-store.ts`) is the single verdict
|
||
function the report, `collector-outcomes.json`, the PR comment and pass-rates
|
||
all use. A timed-out, crashed or infrastructure-failed trial is a failed trial
|
||
recorded with its class; a missing or duplicate trial record makes the verdict
|
||
INCOMPLETE, which fails the lane; a 2/3 PASS is shown as `PASS 2/3` with the
|
||
failed trial's cause. A manual re-run adds trials under a new run attempt and
|
||
never replaces the first attempt's verdict. A red census is never rerun on
|
||
unchanged inputs: each red is diagnosed as product, test/detector, harness or
|
||
infra and resolved by a concrete repair and a fresh census, or listed as a named
|
||
red. The one exception: a census whose every red verdict is machine-classified
|
||
INFRA or INCOMPLETE (missing slice artifact, runner loss, API error before the
|
||
first model turn) may be re-dispatched once as a new run, and both runs are
|
||
reported. Changing any `EVAL_POLICY` constant after seeing census results needs
|
||
Garry's re-approval, a `version` bump and a fresh census;
|
||
`test/periodic-exclude-policy.test.ts` pins the approved values.
|
||
|
||
<a id="failure-causes"></a>
|
||
**Failure causes and details** (diagnostic only; verdicts unchanged under v1).
|
||
Every failed trial record keeps `failure_class` (`assertion`, `contract`,
|
||
`timeout`, `infra`: the field verdicts, INFRA re-dispatch and pass rates read)
|
||
and its 300-character `error` exactly as before. `failureCauseOf()`
|
||
(`test/helpers/eval-store.ts`, called by both record builders, including the
|
||
JUnit census for PTY and JUnit-only cases) adds an optional `failure_cause`
|
||
with a one-line `failure_cause_evidence`. It never changes `failure_class`.
|
||
The highest-precedence cause with evidence wins:
|
||
|
||
| `failure_cause` | Recorded when | First step |
|
||
|---|---|---|
|
||
| `contract` | `expectContract()` stamped a contract violation | fix the product; a violation fails a behavior panel outright |
|
||
| `pre_turn_infra` | the trial failed before the first model turn (`failure_class: 'infra'`) | check the runner and API status; an all-INFRA census is re-dispatched once |
|
||
| `api_error` | a session ended on an API error (for PTY, the `API Error:` panel on an idle turn) or the runner's exit reason was `error_api` | read the evidence line; a provider outage is a named red |
|
||
| `refusal` | the structured stop reason was a refusal (phrases only as a last resort; quoted refusal text in a tool result does not count) | check whether the fixture prompt invites the refusal |
|
||
| `provider_stall` | a session that streamed partial messages saw no event of any kind, thinking deltas included, for `STALL_WINDOW_MS` (120 s) while a model request was in flight and no tool, permission prompt, hook or subagent was outstanding; sessions without partial messages are never stalls | read the session ledger row; still a failed trial under v1 |
|
||
| `session_timeout` | a runner's armed session timeout fired | `eval:pass-rates --headroom`; cut work, never raise the budget |
|
||
| `observer_timeout` | the test's observer gave up waiting for an outcome (`outcome=timeout`) | read the transcript tail: a missed detector or a product that never answered |
|
||
| `assertion` | a check failed after the session ran (`session completed; check failed` when it ended normally) | the Expected/Received values or judge dimensions |
|
||
| `unknown` | the trial failed with no evidence for any cause above | inspect the shard directory |
|
||
|
||
A detector, harness or product fault is a human diagnosis, never a cause.
|
||
Readers before this field accept the new records (a frozen v1 reader runs over
|
||
them in `test/eval-store.test.ts`); an unknown cause from a newer gstack is
|
||
rejected with `unknown failure_cause "<x>" (written by a newer gstack; update
|
||
this checkout to read it)`.
|
||
|
||
`failure_detail` carries the values `error` cannot hold: a failed Bun matcher's
|
||
`{expected, received}`, or for a judge one `{dimension, mean, threshold,
|
||
samples, rationale}` entry per failing dimension (since EVAL_POLICY v3 `mean`
|
||
holds the panel's gating median), each part capped at 200
|
||
characters. `sessions[]` (at most 32) summarizes the trial's session-ledger
|
||
rows. `cost_known: false` marks a record or trial whose harness captured no
|
||
billing: PTY and Codex sessions never bill, and an SDK session bills only with a
|
||
terminal `total_cost_usd`. An absent field means known. Census and marathon
|
||
cost lines print the known sum and `N of M trial(s) cost unknown`, never a bare
|
||
total over unknowns.
|
||
|
||
<a id="session-ledger"></a>
|
||
**Session ledger.** Every runner (session-runner, the Agent SDK runner
|
||
including `runSharedInteractive`, the PTY session and `runRecordedCodexEval`)
|
||
appends one best-effort line per armed session to
|
||
`$GSTACK_EVAL_DIR/session-ledger.jsonl` (`test/helpers/session-ledger.ts`):
|
||
a stable key `<runner>:<label>#n`, the exact `budget_ms` it armed, monotonic
|
||
`elapsed_ms`, the `end` reason, sanitized evidence, `billed`, and a compact
|
||
liveness summary (longest in-request silence, the last event kind, any tool open
|
||
at the end). `claude -p` sessions stream partial messages for this summary;
|
||
transcripts keep their shape and size (full stream diagnostics only with
|
||
`publicStreamDiagnostics`). A failed ledger write never fails a trial; a trial
|
||
without ledger rows has no `sessions` and its headroom is `unknown`, never
|
||
scored. The ledger rides in each slice artifact beside the shard results.
|
||
|
||
**Quarantine** (`CASE_QUARANTINE`, same file). An entry needs: a per-trial rate
|
||
below 95% over at least 10 post-policy trials of the case's current input
|
||
identity (pre-policy backfill may justify only an initial entry, labeled as
|
||
such); a written diagnosis in `reason` whose `failureClass` is `detector`,
|
||
`harness` or `model-latency` (a product defect is fixed or listed as a named
|
||
red, never quarantined); unchanged case touchfiles in the change that adds it;
|
||
and an owner, tracking pointer, `enteredAt` date and measurable `exit`. A
|
||
quarantined case still runs its full panel and reports in every lane but cannot
|
||
fail it, except on a hard break (0 of n) or a contract violation, and it never
|
||
counts as passing coverage. At most 10% of a blocking tier (gate, periodic) may
|
||
be quarantined. The weekly report fails when an entry passes its exit rule (at
|
||
least 97% over at least 10 trials) without being removed, when an entry is 8
|
||
weekly runs old, or when a tier is over its cap.
|
||
|
||
**Pass-rate history** (`bun run eval:pass-rates`, `scripts/eval-flake-rank.ts`).
|
||
It reads the `trial-outcomes` artifact of the last N completed weekly
|
||
`evals-periodic.yml` runs, meaning scheduled runs on `main` plus `main`
|
||
dispatches, plus completed branch census runs in the same window (flags:
|
||
`--case`, `--runs N`, `--branch` to inspect one branch, `--dir`, `--backfill`,
|
||
`--json`, `--gate`, and the views `--headroom`, `--reds`,
|
||
`--run <id>`; `--help` works offline, and an unknown flag or case id exits 2
|
||
before anything is fetched; every view prints its `scope:` line). A branch trial counts only toward a series `main` has also
|
||
run (same case-owned bytes, `HARNESS_VERSION`, model and CLI); a branch never
|
||
starts or becomes a case's current series, and weeks for quarantine expiry
|
||
count `main` runs only. It prints
|
||
per-case per-trial pass rates with 95% Wilson intervals. A series is one case
|
||
under one input identity ([Harness version](#harness-version)), per model,
|
||
Claude CLI version and policy version
|
||
([Pass-rate policy versions](#pass-rate-policy-versions)); a change starts a
|
||
new series and older ones stay visible. Labels: INCONCLUSIVE below 10 trials, BROKEN when the latest run is
|
||
0/n after a prior interval at or above 95%, FLAKY when failures leave the
|
||
interval straddling 95%, FAILING when the whole interval is below it, PASSING
|
||
otherwise. `--backfill` imports legacy slice artifacts as pre-policy trials
|
||
(first attempt only; a record that names no registry id is listed as
|
||
unattributed, never guessed); they are display-only. `--gate` (the weekly
|
||
report) fails with ACTION REQUIRED, on post-policy trials of the current series
|
||
only, when a non-quarantined blocking case meets the entry rule (proposing an
|
||
entry), when a `rule` case does (rule case behaving like behavior: fix or
|
||
reclassify), when a blocking case's current identity is significantly below its
|
||
previous one (one-sided Fisher exact, α = 0.05, at least 6 trials each side,
|
||
Holm-controlled across the cases tested), on the quarantine rules above, and
|
||
with a `[headroom]` alarm when a case's slowest session ran above
|
||
`HEADROOM_FAIL` (85%) of the budget it armed. History that cannot be fetched
|
||
fails the gate closed.
|
||
|
||
The views (`scripts/lib/eval-history.ts`): `--headroom` lists each case's
|
||
slowest armed session against its budget (warn above `HEADROOM_WARN`, 75%;
|
||
`insufficient` below 3 samples; timed-out samples marked censored; `unknown`
|
||
without a session ledger, with the case wall beside it as a labelled upper
|
||
bound) and the census critical path from the slice job timings. `--reds` lists
|
||
verdict reds per census lane by failure class and cause, pooled and shrunk
|
||
per-case red rates, and the all-green probability Π(1 − p_i) over the latest
|
||
census's cases with an interval, labelled an approximation because verdicts are
|
||
not proven independent. `--run <id>` is one census's triage: each red with its
|
||
values and history, and the transcript evidence it downloads from only the
|
||
slices its reds name (a slice artifact over 64 MB is reported, not fetched).
|
||
The three thresholds `HEADROOM_WARN`, `HEADROOM_FAIL` and `STALL_WINDOW_MS`
|
||
live in `test/helpers/eval-budgets.ts`, outside `EVAL_POLICY`; a slow case gets
|
||
less work, never a larger budget. The red-census walkthrough is
|
||
[docs/evals/census-red.md](evals/census-red.md).
|
||
|
||
**The arithmetic.** With per-trial pass rate p, the chance a single case goes
|
||
red (a false red while the product works, the catch rate once it has
|
||
regressed):
|
||
|
||
| p | 1 trial | 2-of-3 panel |
|
||
|---|---|---|
|
||
| 0.99 | 1.0% | 0.03% |
|
||
| 0.95 | 5.0% | 0.72% |
|
||
| 0.90 | 10.0% | 2.8% |
|
||
| 0.70 | 30.0% | 21.6% |
|
||
| 0.30 | 70.0% | 78.4% |
|
||
|
||
The panel removes most false reds at healthy rates, but it catches a 0.95 → 0.70
|
||
regression in one run only 21.6% of the time (a single trial 30%, retry-until-green
|
||
3%), so drift detection is the history rule's job, not the per-run verdict's.
|
||
The Fisher alarm is weak at the minimum sample (5.4% power for 0.95 → 0.70 at
|
||
6 trials a side), and ten straight passes still leave a 72% Wilson lower bound:
|
||
after this policy lands, every series starts INCONCLUSIVE.
|
||
|
||
A lane is all green with probability Π p_rule × Π P(≥2 of 3 | p_behavior) ×
|
||
Π p_judge. For the current registry (PR gate worst case: 107 rule cases and 24
|
||
judges; weekly census: 190 rule, 22 behavior and 25 judge verdicts), with rule
|
||
and judge verdicts at p_rule:
|
||
|
||
| p_rule | full PR gate | weekly, behavior p = 0.90 | 0.95 | 0.97 |
|
||
|---|---|---|---|---|
|
||
| 0.99 | 26.8% | 6.2% | 9.8% | 10.9% |
|
||
| 0.995 | 51.9% | 18.2% | 29.0% | 32.1% |
|
||
| 0.999 | 87.7% | 43.2% | 68.7% | 76.1% |
|
||
|
||
The rule term dominates: a green lane on a working product needs rule cases to
|
||
be near-deterministic (0.999), which is why failing detectors are converted to
|
||
outcome checks and product defects are fixed or named, and why each census
|
||
reports its all-green probability from the measured rates (`eval:pass-rates
|
||
--reds`, carried into the census report).
|
||
|
||
**Timeout policy.** Paid tests use the tiers in
|
||
`test/helpers/eval-budgets.ts` (JUDGE/CAPTURE/CAPTURE_LONG/PTY/PTY_LONG);
|
||
`test/eval-budgets-policy.test.ts` pins that every tier fits the shard wall
|
||
minus overhead and ratchets raw literals. Budget above the wall is fiction.
|
||
No paid test may exceed the ordinary tiers.
|
||
|
||
`FINDING_RETRY_BUDGETS` also registers the CEO split-overflow and Eng
|
||
multi-finding batching files. Each retains its 25-minute case deadline and runs
|
||
once (paid evals never retry) in a 27-minute shard wall including two minutes for
|
||
cleanup. No per-case budget grows. Overlay wrappers
|
||
have a 1,830-second minimum shard wall and run without Bun retries; see the
|
||
[overlay contract](OVERLAY_BENCHMARK_CONTRACT.md) for their unchanged work budget.
|
||
|
||
The quality file reserves its whole-file wall (3,170 seconds) for every case run
|
||
once, plus cleanup. Each still has 120 seconds of model work. Its 17 workflow
|
||
judges own their deadline and abort signal, with five seconds for terminal
|
||
recording inside a ten-second Bun grace; the other 11 retain their existing
|
||
120-second Bun timeout. Late responses cannot create records or cache passes.
|
||
|
||
The ship documentation file reserves 4,920 seconds for four 600-second cases and
|
||
eight 300-second fault cases, run once, plus cleanup; in CI each case runs as its
|
||
own shard. The standalone
|
||
documentation child retains its 600-second case. The five review/ship explorer
|
||
cases reserve 1,695 seconds, run once, including finalization grace.
|
||
These are whole-file supervision limits, not additional model work per case.
|
||
|
||
The shared-library path file reserves 1,920 seconds for its three serial
|
||
600-second cases, run once, plus 120 seconds for cleanup; in CI each case runs as
|
||
its own shard with a 720-second wall (a registered file's case shard supervises
|
||
`caseMs` times its allowed attempts plus the reserve). Its
|
||
registered budget keeps the file in its own shard and binds the expected wall
|
||
to both the saved plan and the execution receipt; missing or stale budget
|
||
records fail reconciliation. Case deadlines and model budgets do not grow.
|
||
|
||
`resolvePaidShardBudget(files, overrideMs?)` is the canonical per-job resolver.
|
||
Each registered finding file and each overlay wrapper requires its
|
||
own shard, even with `--files-per-shard` above one. Mixed or multi-file overlay
|
||
jobs are rejected. An explicit
|
||
CLI `--timeout`, `EVALS_SHARD_TIMEOUT_MS`, or API `timeoutMs` still wins for these
|
||
policies, including a lower cap; overlay overrides below their minimum are rejected.
|
||
Planner entries and execution results record the effective wall,
|
||
its source and policy identifier. Custom drivers must resolve each job instead
|
||
of passing their ordinary 1800-second default as an explicit cap;
|
||
their outer controller/detach wall must also cover the allocated work and cleanup.
|
||
The paid census counts are printed by `--list` for each tier.
|
||
`eval:bg:<pr|gate|periodic|release>` runs `scripts/eval-bg.ts`. On the local
|
||
backend its outer cap is ceil(1.5 × planned serial seconds / `EVALS_JOBS`) + 20
|
||
minutes, at most 4 hours, computed from `scripts/paid-test-durations.json` for
|
||
the lane's current plan (`--timeout SECS` overrides). On the dispatch backend the
|
||
CI job ceilings above bound the run, and the local follower stops after 4 hours.
|
||
`test/eval-detach-timeout-floor.test.ts` pins the cap formula, the 4-hour
|
||
ceiling, the backend choice, the sentinel on both backends, the conclusion
|
||
mapping and dispatch dedupe.
|
||
|
||
CI plans with `--slice-budget 420 --jobs 2` for the PR gate, the periodic census
|
||
and the weekly gate census (the gate census also `--skip-judges`), and
|
||
`--slice-budget 1 --jobs 1` (one file per runner) for marathon. The live plans
|
||
must fit their workflow's `max-parallel` so every slice starts at once, and every
|
||
per-slice ceiling must stay within 360 minutes; `test/evals-workflow-wiring.test.ts`
|
||
recomputes both from the complete census. Reconciliation rejects missing,
|
||
duplicated or misplaced registered work, absent budget records, case shards that
|
||
did not execute exactly their case, and reused results outside the PR profile.
|
||
Ordinary paid tiers and the default 1800-second shard wall remain unchanged; the
|
||
registered and overlay policies above supply exceptions, and unregistered
|
||
over-ceiling tests still fail policy checks.
|
||
|
||
Session timeouts are two-phase: a silent API dies at the startup grace (90s
|
||
local / 300s CI floor, distinct exit reason `timeout_startup`) and the work
|
||
budget arms on the first byte — the total wall never grows
|
||
(`test/session-runner-startup-grace.test.ts` pins the floor). A timed-out
|
||
session kills its whole detached process group (claude, codex, and gemini
|
||
runners alike — `test/session-runner-groupkill.test.ts`), so a stray
|
||
grandchild can't stretch a 600s budget past 1400s. And sync spawns can't
|
||
wedge a shard: every `spawnSync`/`execSync`/`execFileSync`/`Bun.spawnSync`
|
||
in the test trees must carry a `timeout`, enforced by
|
||
`test/spawnsync-timeout-tripwire.test.ts` with a shrink-only exemption
|
||
ratchet.
|
||
|
||
**Anchor-sliced `setup` harnesses.** `setup` is one large bash script, so the
|
||
free tests that pin its linker, cleanup, retired-skill prune, browser hint,
|
||
rebuild decision, and Chromium-bootstrap behavior never run the whole thing.
|
||
They slice the source by anchor (`extractFn(name)` takes
|
||
`name() {` through the next `\n}\n`; `test/setup-playwright-best-effort.test.ts`
|
||
slices the `# 2. Ensure Playwright's Chromium is available` block up to
|
||
`# 2b.`), join the extracted functions with stubbed collaborators, and execute
|
||
the REAL bash under a temp `HOME` with stubbed probes and installers. Two rules
|
||
keep the harness honest: renaming a function or anchor comment in `setup` fails
|
||
the test with `function not found` / `anchor not found` instead of silently
|
||
testing nothing, and `test/setup-link-ownership.test.ts` and
|
||
`test/setup-playwright-best-effort.test.ts` throw on any `command not found` on
|
||
stderr as harness drift (a helper the test forgot to extract) rather than
|
||
letting it degrade into a pass. Files: `test/setup-link-ownership.test.ts`,
|
||
`test/setup-cleanup-orphans.test.ts`, `test/setup-playwright-best-effort.test.ts`,
|
||
`test/setup-prune-stale-generated.test.ts` (`_prune_stale_generated` against a
|
||
temp render tree plus host dirs: host cleanup after the generator already
|
||
pruned, symlink targets survive, frontmatter-renamed skills, foreign links),
|
||
`test/setup-browser-hint.test.ts` (`_browser_hint` and the bootstrap summary
|
||
across Aside present/absent, bootstrap ok/failed/skipped, `GSTACK_SKIP_ASIDE`),
|
||
and `test/setup-needs-build.test.ts` (the `NEEDS_BUILD` block sliced between
|
||
two anchors: every binary and source set flips it, Windows `.exe` suffixes).
|
||
`test/relink.test.ts` shells out to a copy of the real `bin/gstack-relink`
|
||
against a temp `GSTACK_INSTALL_DIR` / `GSTACK_SKILLS_DIR`, and
|
||
`test/hook-scripts.test.ts` runs the real `careful/bin/check-careful.sh` and
|
||
`freeze/bin/check-freeze.sh` with JSON payloads on stdin (including the
|
||
`GSTACK_HOME` state-root parity against `bin/gstack-paths`).
|
||
|
||
### Pass-rate policy versions
|
||
|
||
Readers score only trials recorded under their own `EVAL_POLICY.version`.
|
||
Trials from an older policy are shown display-only. Trials from a newer policy
|
||
are ignored with a printed count ("ignored N trial(s) recorded under a policy
|
||
newer than vX"). When you see that line, run pass-rates from a checkout at or
|
||
after the commit that bumped the version. The supported rollback of a policy
|
||
change is reverting its writer commit; the reader-compatibility commit before it
|
||
stays.
|
||
|
||
### Harness version
|
||
|
||
Under `EVAL_POLICY` v2 a case's series identity is the bytes the case owns (its
|
||
paid test file, its fixtures and its skills' prompt files, including the
|
||
generated SKILL.md) plus `HARNESS_VERSION`, keyed with model, Claude CLI version
|
||
and policy version (`scripts/eval-trial-series.ts`). Each trial also records the
|
||
full consumed-input fingerprint as provenance. `scripts/harness-version.json`
|
||
pins every shared-harness file (`GLOBAL_TOUCHFILES` plus the session runners, the
|
||
PTY harness, the e2e gate and the LLM judge) by blob hash. When
|
||
`test/harness-version.test.ts` fails, run one of:
|
||
|
||
```bash
|
||
bun run scripts/bump-harness-version.ts --non-behavioral "<why no verdict can change>" # no series reset
|
||
bun run scripts/bump-harness-version.ts --bump "<what behavior changed>" # new series for every case
|
||
```
|
||
|
||
On a merge conflict in the manifest, take the higher version, then rerun the
|
||
script.
|
||
|
||
## Ubicloud VMs (`bun run test:ubicloud`)
|
||
|
||
`bun run test:ubicloud [test:free args]` runs the free suite on an ephemeral
|
||
Ubicloud VM instead of the local machine. It is the fast path from small dev
|
||
boxes, containers, and cloud sandboxes, and the way to record the duration seed
|
||
in the CI lane's environment. It needs `UBICLOUD_API_KEY` (a project token from
|
||
the Ubicloud console) plus `bash`, `curl`, `python3`, `ssh`, `ssh-keygen`, and
|
||
`tar` locally.
|
||
|
||
`scripts/ubicloud/ubi-runner.sh` creates the VM (`UBI_SIZE`, default
|
||
`standard-16`; `UBI_LOCATION`, default `eu-central-h1`) and streams the
|
||
checkout to it: tracked files, untracked files that are not ignored, and
|
||
`.git`, so uncommitted edits are tested. It then runs
|
||
`scripts/ubicloud/setup-free-suite.sh`, which mirrors the `free-suite` CI job
|
||
(same Bun pin, Playwright Chromium with its setuid sandbox helper, Xvfb,
|
||
poppler, emoji fonts, zsh for the bash+zsh portability arms (#2669), generated
|
||
host outputs, gate binaries, and the CSO helper), and runs `xvfb-run -a bun run test:free` with `GSTACK_EXPECT_BINARIES=1`
|
||
and `GSTACK_FREE_RETRY_FLAKY=1`. Shard logs are copied to
|
||
`.context/ubicloud/<timestamp>/`, and the VM is destroyed on every exit path.
|
||
The exit status is the suite's.
|
||
|
||
A stock Ubuntu 24.04 VM differs from a GitHub-hosted runner in three ways that
|
||
the scripts correct: the login umask is `002` (group-writable directories fail
|
||
the CSO private-state checks), AppArmor blocks the unprivileged user
|
||
namespaces Chromium's sandbox needs, and `clang` and `python3-venv` are absent
|
||
(required by the Dia readiness and Python runner tests).
|
||
|
||
VMs are named `ubirun-<epoch>-<hex>`. Every new VM first destroys `ubirun-*`
|
||
VMs older than `UBI_GC_HOURS` (default 12), so an interrupted client cannot
|
||
leak one for long. For other commands, use the runner directly:
|
||
`scripts/ubicloud/ubi-runner.sh run --setup <script> -- '<command>'`, or its
|
||
`up` / `ssh` / `sync` / `pull` / `down` steps (`--help` lists them).
|
||
|
||
## Cloud sandboxes (Vercel / Conductor cloud workspaces)
|
||
|
||
Syscall-supervised sandboxes need environment setup before `bun run test` can
|
||
run green: run `scripts/sandbox-doctor.sh` once per boot. It documents and
|
||
treats the full failure taxonomy (missing /dev/fd, 64M /dev/shm, spurious
|
||
access(2) EACCES from the seccomp supervisor under load, full-capability
|
||
processes defeating chmod-denial tests, no X server, no git identity, and
|
||
Conductor's git-shim exit-code laundering). The doctor seeds `TMPDIR`,
|
||
`DISPLAY`, and the runner knobs into `~/.bashrc`, so open a new shell (or
|
||
`source ~/.bashrc`) before running the suite. Then:
|
||
|
||
```bash
|
||
setpriv --ambient-caps=-all --bounding-set=-all bun run test
|
||
```
|
||
|
||
Two runner knobs exist for these environments (both no-ops unless set):
|
||
`GSTACK_FREE_JOBS` overrides the shard count in either direction (2 is the measured sweet spot — one
|
||
serial mega-shard and 6-way sharding both saturate the per-process syscall
|
||
supervisor), and `GSTACK_FREE_RETRY_FLAKY=1` re-runs attributed failures once
|
||
serially, downgrading a clean retry to a loud FLAKY-PASS (capped at 5 files so
|
||
a broken tree can't masquerade as flaky). The required CI free lane and the
|
||
Windows lane set the retry knob too, appending every flaky pass to the JSONL ledger it uploads
|
||
(`GSTACK_FLAKE_LEDGER`) — a flaky pass never reds the lane, but it never
|
||
disappears either ([Flake ledger](#flake-ledger)).
|
||
|
||
## Test selection and tiers
|
||
|
||
Moved verbatim from CLAUDE.md (#2096 size limit).
|
||
|
||
**Diff-based test selection:** the sharded paid runner (`test:pr`, `eval:bg:pr`,
|
||
`test:gate:sharded`) selects tests based on `git diff` against the base branch.
|
||
Each test declares its file dependencies in `test/helpers/touchfiles.ts`. Changes
|
||
to global touchfiles (session-runner, eval-store, touchfiles.ts itself) trigger
|
||
all tests. Use `EVALS_ALL=1` to force all tests. Run `eval:select` to preview
|
||
which tests would run; it applies the PR profile by default, and
|
||
`--profile full` shows the plain touchfile selection. Commands by task: [CONTRIBUTING.md](../CONTRIBUTING.md#which-command-do-i-run).
|
||
|
||
**Two-tier system:** Tests are classified as `gate` or `periodic` in `E2E_TIERS`
|
||
(in `test/helpers/touchfiles.ts` — a facade over `touchfiles-data.ts` +
|
||
`test-selection.ts`). CI runs the changed fast PR profile and selected judges
|
||
per PR via evals.yml's sliced lane
|
||
(planner manifest → executors → fail-closed report; engine =
|
||
scripts/test-paid-shards.ts, the same runner as local eval:bg:pr); the free
|
||
suite runs on every PR via `.github/workflows/free-tests.yml` (a REQUIRED
|
||
check, secretless — fork PRs get real signal); ALL periodic tests run weekly
|
||
via evals-periodic.yml (EVALS_ALL, minus the reasoned exclusions in
|
||
`test/helpers/periodic-exclude-data.ts` — reason + tracking required per
|
||
entry), plus a weekly EVALS_ALL gate census. Use `EVALS_TIER=gate` or
|
||
`EVALS_TIER=periodic` to filter locally. When adding new E2E tests, classify them:
|
||
1. Safety guardrail or deterministic functional test? -> `gate`
|
||
2. Quality benchmark, Opus model test, or non-deterministic? -> `periodic`
|
||
3. Requires external service (Codex, Gemini)? -> `periodic`
|
||
|
||
Tier declarations are enforced by `test/e2e-tier-alignment.test.ts` (free, runs
|
||
in `bun test`): a `skill-e2e-*` file named in a touchfiles dep list whose
|
||
`EVALS_TIER` self-gate disagrees with its declared tier in `E2E_TIERS` fails the
|
||
suite. Files not named in any dep list are reported, not enforced — keep both
|
||
in sync.
|
||
|
||
### PR paid lane fallback
|
||
|
||
PR selection (`scripts/test-pr-profile.ts`) classifies every changed file. A file
|
||
mapped by a paid case's touchfiles selects that case. These files are exempt and
|
||
select nothing: docs, any non-paid `*.test.ts(x)`, `FREE_ONLY_PR_FILES` (the
|
||
free and paid duration seeds, `scripts/ubicloud/**`, every workflow that runs no
|
||
paid evals, and free-only tools), and the fixtures in `FREE_FIXTURES`
|
||
(`test/helpers/free-fixtures-data.ts`, each fixture with its free consumers).
|
||
`PAID_WORKFLOW_FILES` (`evals.yml`, `evals-periodic.yml`, `evals-marathon.yml`)
|
||
and any other unknown file restore the full gate (`prCoverage.mode =
|
||
full-fallback`). The job summary and PR comment list each file that caused a
|
||
fallback with one of three labels:
|
||
|
||
- **needs touchfile entry**: a paid test, helper or fixture no case maps; add it
|
||
to the owning case in `E2E_TOUCHFILES` (`test/helpers/touchfiles-data.ts`).
|
||
- **add to FREE_ONLY_PR_FILES**: a file only free lanes read; add it to the list
|
||
in `scripts/test-pr-profile.ts` (or a fixture to `FREE_FIXTURES`).
|
||
- **real unknown dependency**: shared code (bin/, lib/, resolvers, hosts, setup)
|
||
whose dependents are not mapped; the full gate is the correct result.
|
||
|
||
`test/free-fixtures.test.ts` holds the inventory: each `test/fixtures/**` path
|
||
belongs to a paid touchfile or `FREE_FIXTURES`, and each workflow to the paid or
|
||
free-only list. Editing a paid test file runs its own gate cases on the PR when
|
||
their Bun test is named by the case id; the file's other cases stay deferred with
|
||
a reason that says to name the test by its case id.
|
||
|
||
### PR receipts, recovery and debounce
|
||
|
||
Passes and failures of single-trial shards are written as receipts at the
|
||
execution boundary, so a cancelled run's finished work survives. The
|
||
`recover-receipts` job runs `scripts/recover-receipts.ts` from the base ref with
|
||
`actions: read`: it merges the receipts of at most 5 completed, cancelled
|
||
`evals.yml` runs of the same PR (oldest first, negatives before passes, so a newer
|
||
FAIL blocks an older PASS) and hands the store to `plan-slices`, which keeps
|
||
`contents: read` only. Its `recovery.json` checkpoint never advances past an
|
||
unresolved run. `plan-slices` turns reuse off when recovery degraded, the
|
||
checkpoint is missing or a cancelled run is still unresolved; recovery itself
|
||
never fails the run, and the job summary names the reason (rate limit with its
|
||
reset time, `gh auth status`, the 60-second budget). The whole store is saved by
|
||
`slices-report`.
|
||
|
||
On a `synchronize` push, when another run for the same PR started in the last 15
|
||
minutes, the debounce job waits 90 seconds before planning; a run that outlives
|
||
the wait reports "superseded by <sha>". PR labels: `evals-no-debounce` skips the
|
||
wait and `evals-fresh` turns receipt reuse off. Labels apply from the next push,
|
||
because adding a label does not start `evals.yml`.
|
||
|
||
## Free suite runner, judge reuse and engine skips
|
||
|
||
Moved verbatim from CLAUDE.md (#2096 size limit).
|
||
|
||
`bun run test` routes through `scripts/test-free-shards.ts` (N concurrent
|
||
shard processes, serial within each, packed by recorded per-file durations
|
||
when `scripts/free-test-durations.json` exists — refresh it with
|
||
`bun run test:ubicloud --record-durations`; strict-output classification per
|
||
shard: a shard without bun's terminal summary line FAILS — silent truncation
|
||
cannot report green). `TREE_MUTATING` lists the files that still run in their
|
||
own trailing serial shard (today only `test/bootstrap-retention.test.ts`, for
|
||
host-wide procfs visibility); gen-skill-docs tests no longer need it (main()
|
||
guard, and `--out-dir` renders every host into mkdtemps — see
|
||
docs/TESTING_INTERNALS.md). Never type bare `bun test` for the suite: it
|
||
walks the whole repo, loading paid eval files and missing the strict
|
||
classifier.
|
||
It covers skill validation, gen-skill-docs quality checks, browse
|
||
integration tests, the Aside contract pins, and the render-wrapper pins.
|
||
`bun run test:pr` runs the selected short live behaviors and quality judges.
|
||
It reports deferred broad coverage; unknown dependencies restore the full gate,
|
||
and an unmapped prompt without registered coverage blocks planning. Full free
|
||
acceptance and required PR checks must pass before publishing. CI can reuse the
|
||
16 workflow-judge passes for 24 hours when their complete consumed inputs and
|
||
runtime match; records preserve original provenance. The cookie workflow's custom
|
||
input, the other 11 judge cases, dynamic agent tests, and local runs without
|
||
scoped cache configuration stay fresh.
|
||
Scheduled/manual full coverage and `test:release` always run fresh.
|
||
See [testing policy](CONTRIBUTING.md#test-tiers) for commands and measured targets.
|
||
Anything that needs Aside
|
||
itself (`test/skill-e2e-aside.test.ts`, the Aside qa/design E2E cases, the
|
||
live render in `test/aside-render.test.ts`) runs only on a Mac with the Aside
|
||
app open and self-skips elsewhere (`asideAvailable()`). make-pdf's render
|
||
gates and `test/skill-e2e-diagram.test.ts` run through whichever engine
|
||
resolves (`browserAvailable()` — Aside, or the browse binary CI builds with
|
||
`bun run build:gates`) and skip only when neither exists; the fallback
|
||
engine's own tests run everywhere.
|
||
|
||
### Real-home tripwire
|
||
|
||
No free test may write the developer's real home. `scripts/lib/free-home-guard.ts`
|
||
snapshots `~/.gstack`, `~/.claude`, `~/.codex`, `~/.agents` and `~/.config/gstack`
|
||
(live session logs excluded) and fails the run when an entry changes.
|
||
|
||
- A shard that runs alone (`--shard`, CI, the exclusive host-state shard, the
|
||
flaky retry) owns its window, so the failure names its files.
|
||
- Full-suite shards run concurrently on one HOME and cannot tell whose write a
|
||
change was. The runner guards that whole phase once and names no shard.
|
||
- `bun run scripts/test-free-shards.ts --attribute-home` names the writer: it
|
||
runs every file alone with a private HOME (browser cache and git identity
|
||
still come from the real home) and reports each file that wrote a watched
|
||
surface. The retained shard directory keeps the written files as evidence.
|
||
|
||
Fix a writer with `usePrivateStateRoot()` (`test/helpers/private-state-root.ts`)
|
||
or a child HOME/GSTACK_HOME, and resolve product state paths at write time,
|
||
never at import.
|
||
|
||
### Flake ledger
|
||
|
||
`GSTACK_FREE_RETRY_FLAKY=1` reruns a failing free test file once, serially. A
|
||
clean retry turns the shard green as a flaky pass and appends an entry to that
|
||
shard's flake ledger, uploaded as `flake-ledger-<shard>` (90-day retention). The
|
||
Monday "Weekly test health" workflow (`bun run test:health --enforce`) reads
|
||
main's ledgers through `scripts/lib/ci-history.ts` and fails when a file flakes
|
||
in more than 5% of main free-tests runs over a window of at least 20 runs; a
|
||
window thinner than 20 runs in the last 7 days widens to the newest 20 runs, and
|
||
fewer than 20 runs is report-only. `bun run test:health flake-summary <dir>`
|
||
prints a run's ledgers as a table. A flaky file is fixed at source; the retry
|
||
never masks it. `bun run eval:pass-rates` lists only the local ledger
|
||
(`flakeLedgerPath()`, overridden by `GSTACK_FLAKE_LEDGER`).
|
||
|
||
The aggregate job of `free-tests.yml` downloads every `flake-ledger-*` artifact
|
||
of the run and appends `bun run scripts/test-health-report.ts flake-summary <dir>`
|
||
to its job summary. The Windows lane uploads `flake-ledger-windows-<shard>`.
|
||
|
||
Free-suite flake rules:
|
||
|
||
- Bun gives a child `stdio: 'pipe'` a unix socketpair. A test that must hold a
|
||
write blocked uses a FIFO the test never reads (`test/qa-evidence.test.ts`,
|
||
`test/qa-deadline.test.ts`), not a paused child stream: socket capacity follows
|
||
`net.core.{w,r}mem_default` and the parent's reader.
|
||
- A test that rewrites CI provenance variables (`CI`, `GITHUB_*`, `CI_*`)
|
||
restores them. Free shards run many files in one process, and a later browse
|
||
daemon without `CI=true` launches Chromium sandboxed.
|
||
- Handshakes with a runner wait for the runner's own observable effect (its
|
||
progress line, a coalesced read count), not for a fixture side file or a timer.
|
||
|
||
### Free suite duration seed
|
||
|
||
`scripts/free-test-durations.json` drives shard packing; files missing from it
|
||
pack at the seed's 99th percentile. Acceptable seeds come from
|
||
`bun run test:ubicloud --record-durations` (each file timed in its own child on a
|
||
VM with the CI lane's environment) or a CI recording. A 4-core laptop or
|
||
small-sandbox recording is not acceptable: browser and display tests skip or slow
|
||
down there, so the seed misstates them.
|
||
|
||
- `--ci-plan` warns in the job summary, with the refresh command, when more than 5
|
||
files are unseeded; it never fails a PR. `--ci-verify` lists shards that ran
|
||
longer than 1.5× their prediction and at least 30 seconds over.
|
||
- The weekly test-health run fails its enforced `unseeded-free-files` check
|
||
("stale seed: N unseeded file(s) > 5") when more than 5 free test files are
|
||
missing from the seed, so contributors without Ubicloud access learn within a
|
||
week that it needs a refresh.
|
||
- `test/free-seed-ratchet.test.ts` (run with full history in `free-tests.yml`'s
|
||
`free-plan` job, `GSTACK_FREE_SEED_BASE=$(git merge-base HEAD origin/main)`)
|
||
fails when a seeded file over 60 seconds is missing from
|
||
`scripts/free-test-seed-allowlist.json`, when an allowlist entry is stale (gone,
|
||
or no longer over 60 seconds), or when an entry is added relative to the
|
||
merge-base copy without a `todo`. An annotated exception is
|
||
`{file, reason, todo}` and the test prints it. A merge-base without the
|
||
allowlist file counts as the first allowlist. Fix a failure by splitting the
|
||
file, then rerun `bun run test:ubicloud --record-durations`.
|
||
|
||
### Windows free lane
|
||
|
||
`windows-free-tests.yml` plans on Linux (`--windows-only --ci-plan --shards 6`),
|
||
runs one strict serial shard per `windows-latest` job
|
||
(`bun run test:windows --ci-run`), and verifies every shard receipt on Linux
|
||
(`--windows-only --ci-verify`). Packing uses Windows-measured durations from
|
||
`scripts/free-test-durations-windows.json`; refresh them with
|
||
`gh workflow run windows-free-tests.yml --ref <branch> -f record_durations=true`,
|
||
then download the `free-test-durations-windows` artifact and commit it.
|
||
|
||
Curation lives in `scripts/lib/windows-curation.ts`. Every Windows plan and
|
||
`--list` prints the curated count and the top exclusion reasons (also in the job
|
||
summary). Files a probe proved safe despite a `/tmp` literal are force-included
|
||
(`WINDOWS_PROBE_SAFE`). `test/windows-native-workflows.test.ts` holds
|
||
`WINDOWS_CURATED_FLOOR`; when Windows-safe tests are deleted on purpose, lower it
|
||
in the same PR with a reason.
|
||
|
||
Native qualification campaigns (Windows cookie extraction, Windows launch
|
||
diagnostics, Dia on macOS) run only on dispatch of `native-qualification.yml`:
|
||
|
||
```bash
|
||
gh workflow run native-qualification.yml --ref <branch> -f mode=<cookie-native|windows-native-diagnostics|dia-native|dia-launch-comparison|dia-gui-readiness>
|
||
```
|
||
|
||
### Real-setup install fixture
|
||
|
||
Tests that run the real `setup` use `test/helpers/install-fixture.ts`. Each test
|
||
file builds one read-only seed checkout and clones it per test with
|
||
copy-on-write file copies (plain copy fallback), never hard links. Writes go
|
||
through `put`, `setVersion` and the `fixture*Sync` helpers; files register
|
||
`afterEach(cleanupFixtures)` and `afterAll(cleanupSeed)`.
|
||
`test/install-fixture.test.ts` is the isolation tripwire: writes in one clone
|
||
leave the seed and sibling clones unchanged.
|
||
|
||
### Test-only timing knobs
|
||
|
||
Defaults are the product's; tests shrink them instead of waiting real time:
|
||
`GSTACK_RENDER_SLACK_MS` (`lib/aside-render.ts`, default 10000),
|
||
`GSTACK_MEMORABLE_LOCK_TRIES` (`bin/gstack-memorable`, default 50 tries of 0.1 s),
|
||
the `recordGraceMs` option of `test/helpers/office-hours-attempt.ts` (default
|
||
5000) and the `timeoutMs` argument of `clearCookieTargetStorage(page, origin,
|
||
timeoutMs)` (default 15000).
|
||
|
||
## Running evals as an agent: detach
|
||
|
||
Moved verbatim from CLAUDE.md (#2096 size limit). The short rule stays in
|
||
CLAUDE.md; this is the full mechanism.
|
||
|
||
When **you (an agent/harness)** launch a long eval/benchmark run, run it through
|
||
`bin/gstack-detach` — NEVER as a plain backgrounded Bash task. A plain background
|
||
task lives in the harness's process group, so a SIGTERM ("polite quit") on a turn
|
||
boundary, a stopped Monitor, or an interruption kills the run mid-flight (observed:
|
||
`script "test:gate" was terminated by signal SIGTERM` ~40 min into a run of the
|
||
since-retired single-process runner). On macOS
|
||
the run can also die to idle-sleep. `gstack-detach` fixes both: a fresh session
|
||
(escapes the group SIGTERM) wrapped in `caffeinate -i` (blocks idle-sleep).
|
||
|
||
- Use `bun run eval:bg:<pr|gate|periodic|release>` (`scripts/eval-bg.ts`). It
|
||
prints `[eval-bg] backend=<dispatch|local> …` and `gstack-detach LOG <path>` and
|
||
returns at once. Both backends run under `gstack-detach` with the machine-wide
|
||
`gstack-evals` lock (concurrent worktrees serialize instead of saturating the
|
||
shared model API) and a **run-scoped** log under `~/.gstack-dev/eval-runs/`
|
||
whose first line names the backend, the run and the tested revision.
|
||
- **Dispatch** (default when HEAD is clean and equal to its pushed branch on
|
||
`garrytan/gstack`, checked with `gh api`, and `gh` can dispatch): `pr` and
|
||
`gate` dispatch `evals.yml` (`evals_all=false` with `base_ref`/`base_sha` for
|
||
`pr`, `evals_all=true` for `gate`), `periodic` dispatches `evals-periodic.yml`,
|
||
`release` dispatches both. Every dispatch passes `expected_sha` (the workflow
|
||
fails fast when the checked-out revision differs) and a `nonce` that appears
|
||
in the run name (`E2E Evals [eval-bg <nonce>]`), which is how the log finds
|
||
and follows its run. A queued, running or green dispatch with the same
|
||
revision and inputs is followed instead of dispatched again. Dispatched runs
|
||
are validation runs: fresh and never writing PR receipts, except that a `pr`
|
||
dispatch on a branch with an open same-repo PR passes `pr_receipts=<PR>` and
|
||
reads that PR's receipts read-only.
|
||
- **Local** (dirty tree, unpushed commits, a fork, no `gh`, or `--local` /
|
||
`GSTACK_EVAL_BG_MODE=local`): the sharded paid runner
|
||
(`scripts/test-paid-shards.ts`) on this machine, capped at
|
||
ceil(1.5 × planned serial seconds / `EVALS_JOBS`) + 20 minutes, at most 4 hours
|
||
(`--timeout SECS` overrides). One Bun process per test file, an external
|
||
wall-clock timeout that kills the shard's process GROUP (stray
|
||
`claude`/`codex` grandchildren included), a per-shard
|
||
`GSTACK_EVAL_DIR=<evalDir>/shards/<slug>/` honored by the `EvalCollector`
|
||
constructor, and an aggregate that separates failed vs timed-out vs
|
||
never-started shards. `EVALS_JOBS` sets the shard process count (default 8,
|
||
2 for `pr`); `EVALS_CONCURRENCY` is bun's --max-concurrency WITHIN a shard
|
||
(default 2). Export `ANTHROPIC_API_KEY` first (never pass keys in argv).
|
||
- `--dispatch` refuses with the fix ("commit and push, or rerun with --local")
|
||
instead of falling back.
|
||
`eval:list` / `eval:compare` / `eval:summary` / `eval:pass-rates` read the shard
|
||
dirs too. For any other long agent job, call
|
||
`gstack-detach [--lock NAME] [--timeout SECS] [--label LBL] -- <cmd>` directly.
|
||
- Then **poll the printed logfile** with a death-aware watcher: break on the
|
||
guaranteed `### gstack-detach EXIT=<code> ###` sentinel (0 passed, 1 failed,
|
||
130 cancelled, 2 other on both backends; silence is never mistaken for success).
|
||
`bun run scripts/eval-bg.ts status <log-or-run-id>` reconnects and prints
|
||
running, passed, failed, cancelled or incomplete (died without a sentinel). The detached run survives
|
||
even if your watcher gets reaped, so re-checking the log always works. Keep
|
||
checking until the sentinel appears or the user tells you to stop; a long run is
|
||
expected, and a promise to check later is not a result. At each check, report
|
||
which tests passed, which are still running, and any failures so far.
|
||
- Why the lock: a shared dev box with several Conductor worktrees will rate-limit
|
||
the model API if two eval suites run at once (15-way concurrency each), which
|
||
mass-times-out E2E tests. The lock makes the second run WAIT, not collide.
|
||
- Humans running `bun run test:pr` foreground in their own terminal don't need
|
||
this — Ctrl-C is intended there. Detachment is for agent-launched runs only.
|