Cycle 0054: an unreached declared stop explains itself, a launch re-asks a changed root claim, and the native trial keeps unreleased listings #130

Outcome

Three test-run defects that Cycle 0053 carried (#128 closing comment) are closed, each by a fix and a test that fails without it:

1. A test whose next declared stop is never reached explains itself: the continuation names the exit and the stop it did not reach, and the node-test help tells the agent that stops are reached only in the order the test executes them.
2. A package-mode launch whose root claim would now be decided differently is refused before the test runs.
3. The native-trial bootstrap never drops a root listing it could not release.

This is a bug-fix cycle. It adds no increment, and nothing in it is selected, dropped or reduced. It follows feature Cycle 0053 (#128, PR #129, 1b2dcfa7, v0.2.43.0). Defects found while this cycle runs are fixed in it; the ship review limit is the only exception (AGENTS.md, Cycle rule).

Gap audit (baseline 1b2dcfa7)

Changed since #128's audit (83a07385). Only Cycle 0053's node-test Vitest-root work: the resolver, the plan, readiness, refusals, the listing release and the docs. Rows it touches:

• AC-REAL-PROJECTS: match improved. Package tests of P02/P05/P07/P08 run headless through Codebook's wiring. Native Stage 1 is still owed (O4 of Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #128).
• AC-LIVE: root mode re-proven natively in both hosts (N53, Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #128).
• AC-SKILL: README line corrected.

Unchanged since #128's audit. AC-SAVE, AC-REPLAY, AC-GAPS, AC-LEARNING, AC-WIKI, AC-WIKI-UPDATE, AC-SOURCE-LINKS, AC-ENTRY, AC-DESKTOP and AC-SHORTCUTS keep #128's implementation, proof and next action: Cycle 0053 changed no code they read.

This cycle's three defects. All are in AC-LIVE (node-test) and AC-REAL-PROJECTS (package mode). Each closes by its task below.

Tasks

1. N53-F1. Source: Cycle 0053, native trial N53, VS Code. The behavior already exists at 83a07385. Code fixed in 558562d4 (the sentence, the walkthrough and testSelection help, the README; owned-run and help tests red without the fix); help wording corrected in 95b155d8 (task 4). Evidence: N54 PASS in both hosts.

   • Defect. When a continuation's test ends before the next declared stop, codebook_continue answers RUNTIME_FAILED with a message that says only that the owned debug session ended, and the run seals partial with that reason. The cause: captureStop (extension/src/ownedNodeTestRun.ts, under waitUntil) calls assertActive. explainEarlyExit (extension/src/ownedNodeTestRun.ts:918) words the exit only for stop 1, and only from prepare. In N53 the agent declared stop 2 at app/lib/data.test.ts:210, a line the test runs before stop 1 (app/lib/data.ts:190), and could not tell from the answer what went wrong.

   • Fix: explainEarlyExit. It takes the declared stop's number and is also called from advance's failure path, after the session ends while the owned process has exited. The message is exactly: Owned Node test exited with ${code or signal} before declared stop ${n}. A declared stop is reached only when the test runs its line after the previous stop; its output is in the Codebook test output. If Vitest skipped the cited test, check that testTitles names it exactly; see codebook://help/node-test. (For stop 1 the second sentence still holds.)

   • Fix: help. The node-test help (extension/src/resources.ts, the walkthrough's "choose the stop lines" step and testSelection) gains one sentence: each additional stop is a line the test runs after the previous stop; a line the test ran before it is reached only if the test runs it again, and a stop whose line does not run after the previous stop is never reached, so the run ends at the test's exit. (CHANGED in 95b155d8, same goal: the first wording said a line that ran before is never reached, which a loop disproves.)

   • Fix: README. extension/README.md says the same in its node-test section.

   • The bundled skill stays 1.0.47 for this task. It defers to the help. (Task 4 later moved it to 1.0.48 for an unrelated sentence.)

   • Test (fails without the fix). An owned-run test where the test process exits after stop 1 while stop 2 is still pending. advance rejects with the exact sentence for stop 2, and with the exit code.

   • Help test. It pins the help sentence.

   • Native check N54 in both hosts. Space local:codebook-qa, nextjs-dashboard 1936e41. VS Code uses Copilot Chat with GPT-6 Luna; Cursor uses Agent with Grok 4.6 High (Fast allowed; fallback is the Codex Extension after observed credit exhaustion). Each host gets a new natural /codebook question, not asked in Cycle 0049: a Vitest test run the editor chat explained is saved and replayed as a learning replay in both editors #107, Cycle 0050: every defect Cycle 0049 carried is fixed or closed with evidence #118, Cycle 0051: a test replay opens in the region-2 composition, with the Learning summary in the chat's place, one transport and 5A #122, Cycle 0052: replays leave, move and open without stale frames, and every Cycle 0051 carried defect is closed #124 or Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #128, that needs at least two stops. Record:

     • whether the agent declared the stops in execution order;
     • every stop reached, with the run sealed complete;
     • the replay saved and opened.

     The early-exit sentence itself cannot be forced through a natural chat. Its native proof is NOT RUN, and the host test is its proof at that level.

   • N54 rules.

     • Acceptance judges Codebook's behavior. An agent mistake that Codebook reports truthfully (for example a stop order that ignores the help) is recorded, not failed. That host's take may continue with one natural learner follow-up, as N52 did, or a new natural question.
     • Every Codebook defect a take exposes becomes a task here and is fixed in this cycle.
2. CR-OD1. Source: Cycle 0053, hosted CodeRabbit outside-diff finding on e825b04a (Minor). Fixed in 558562d4. Four new launch tests and one owned-run forwarding test fail without the fix; three existing launch tests now record the root listing at launch. nsx measurement: 247, 146 and 142 ms, median 146 ms (cited file selected 0 times, not-selected, Node 24.21.0).
   • Defect. verifyExecutionPlan (extension/src/utils/prepareNodeTestLaunch.ts) re-checks the root claim only through rootClaimBasis: the root config names and bytes, the refused entries and the root Vitest. The root listing's answer can change without any of those changing, for example when a config that the root's projects selects is added, removed or edited. A package-mode run decided as not-selected, several-projects or listing-failed then launches in its package, although the root would now select the test once.
   • Fix: re-ask the root at launch. When the plan's summary.rootClaim is not-selected, several-projects or listing-failed, prepareNodeTestLaunch lists the cited test from the opened root with the root's Vitest. It uses the declared path, the owned run's listVitestTestFiles and the attach signal, and runs before its package listing. It decides the claim again with decideNodeTestRootClaim.
   • Refusal wording. A different rootClaim refuses with the changed-plan sentence: node-test's plan for <test> changed while the run was preparing (the repository root's Vitest now answers rootClaim <new>, not <old>); start the test again. A refused or unconfirmed root listing refuses as the launch's own listing refusals do today.
   • Root mode needs no extra listing. A selected-once plan (root mode) already lists from the root at launch, and a cited count other than 1 is refused there; a test pins it. not-applicable (no claim) also needs none.
   • Cost. One extra Vitest listing at launch, only for package runs whose plan made a root claim.
   • Measurement. Measure the added root listing alone, as the wall time of the listVitestTestFiles call from the root, on laststance/nsx at 0897231007dec21904b61bac46c62a40d42ca7ba (Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #128 task 1: test browser-extension/tests/unit/entrypoints/popup/App.test.tsx, rootClaim not-selected, Node 24.21.0). Use three runs through the built extension/dist, and record each time and the median here.
   • Outcome per planned rootClaim, decided at launch.
     • The same decision (not-selected again, several-projects again, or a clean listing-failed again): the launch goes on to its package listing.
     • A different decision, for example listing-failed that now selects once, or not-selected that now lists under several projects: refused with the changed-plan sentence.
     • A root listing at launch that is cancelled, passes the attach deadline, cannot confirm its process group ended, or cannot run at all: refused with the listing's own error, as the launch's package listings refuse today. Never a fallback.
   • Tests (fail without the fix). Each case is decided at launch:
     • a plan decided not-selected meets a root listing that now selects the test once: refused with the exact sentence, and no package listing runs;
     • the same root listing still selects it zero times: the launch goes on, and the package listing runs;
     • a plan decided several-projects meets the same answer: the launch goes on;
     • a plan decided listing-failed meets a root listing that now selects once: refused;
     • a plan decided selected-once meets a root listing that now selects it twice: refused (the existing launch refusal pins it).
   • README. The changed-plan troubleshooting row names the re-asked root claim.
3. CR-OD2. Source: Cycle 0053, hosted CodeRabbit outside-diff finding on e825b04a (Minor). Fixed in 558562d4. Five new bootstrap tests fail at 1b2dcfa7.
   • Defect. extension/src/nativeNodeTestBootstrap.ts (lines 42–65) collects the retries of unreleased root listings and runs them once, in planNodeTestExecution's finally. When that release fails, run() throws before OwnedNodeTestRun exists: the retries are dropped and no trial report is written. The bootstrap creates no StudyRecord, so nothing retries them later.
   • Fix. The bootstrap keeps the retries for the whole trial. It runs them after planning, and again in its outermost finally, after run.stop() when a run exists. It always writes the private trial report (CODEBOOK_NODE_TEST_REPORT_PATH), also when planning fails, with error and unreleasedListings: [{ processGroup, directory }] for any listing still not confirmed as ended.
   • Order and precedence.
     • Each cleanup step runs in its own try: run.stop(), then the listing retries, then the report write. A failing step never skips the next.
     • The trial rejects with the first error in this order: the planning or run error, then the stop error, then a listing still unreleased after the last retry, then the report write error.
     • A release that a later retry recovers is not an error by itself.
   • Tests (fail without the fix), loading the module with stand-ins as Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #128's bootstrap test does:
     • a planning failure whose release fails once and then succeeds: the second try runs, and the report records no unreleased listing;
     • a release that keeps failing: the report names its group and folder;
     • planning that fails: a report is written;
     • a failing run.stop(): the retries and the report still run, and the trial rejects with the run's own error first.
4. CR-131. Source: this cycle, hosted CodeRabbit on PR v0.2.44.0 fix: Cycle 0054: an unreached declared stop explains itself, a launch re-asks a changed root claim, and the native trial keeps unreleased listings #131. Each finding below is closed by a fix and a test that fails without it.
   • On 82753fcf (two inline Minor findings). Fixed in 0aac7c8d:
     • The README now quotes the early-exit sentence with its signal form.
     • New test: a signal that ends the test before stop 2 is named in the sentence. It is red without the fix.
   • On 0aac7c8d (one inline and one outside-diff Minor finding). Fixed in 95b155d8:
     • The help, the README, the CHANGELOG and two doc comments no longer claim that a stop on a line which ran before the previous stop is never reached. Such a stop is reached when the test runs that line again.
     • The help test fails on the old sentences.
   • On 95b155d8 (one inline and one outside-diff Minor finding). Fixed in 98d70e3e:
     • The early-exit sentence for stop 1 now says that the first declared stop is reached only when the test runs its line. Stop 1 has no previous stop to run after.
     • The help's testSelection names the exit code or signal, as the run's error does.
     • README and CHANGELOG are updated.
     • Two new tests fail without the fix: the owned-run stop-1 sentence and the help's signal wording.
   • On 98d70e3e (one inline Minor finding). Fixed in 5aa799fc:
     • The help, the bundled skill and the README no longer say that a run ending with an error before its first stop did not run its test. Such a run reached no stop and explains nothing: a refusal before the launch ran no test, and a test that exited first names its exit code or signal.
     • The skill moves to 1.0.48 for this one sentence.
     • The help and skill tests fail on the old sentence.
     • N54's candidate had skill 1.0.47. Its evidence carries forward because neither N54 run ended with an error before its first stop.
   • Outcome. CodeRabbit APPROVED 5aa799fc; its body has no outside-diff finding.
   • On 5e998ae2 (APPROVED, plus a COMMENTED review with one outside-diff Minor finding). Fixed in be9637f7:
     • Each unreleasedListings entry of the native trial's private report now keeps its listing's own release error (reason). listingError keeps only the last retry's.
     • The bootstrap test fails without the fix.
5. GATE-H1. Source: this cycle, the exact-HEAD gate's pnpm health on 5aa799fc (its coverage run of the suite).
   • Defect. The run failed once: a recorded run whose saves cannot look at its recording folder keeps its study, tells "History not saved: …", … read history: 'saved' and no error line. All other checks passed: pnpm test (6,946 pass) and the earlier pnpm health run on 98d70e3e.
   • Root cause: the test's seam, not the product.
     • The stand-in kept one shared variable, set at each saveStudy call and cleared in that call's finally.
     • The mock sits on LearningLibrary.prototype, so any other save that ended lifted the refusal before this save looked. Another library's save counts too.
     • saveStudy looks at the folder only after it acquires the library's lock.
   • Fixed in 5e998ae2. The seam counts the saves running per recording folder, and refuses a look while the test says so and a save of that folder is running.
   • Evidence.
     • An unrelated save, injected while the refused look is pending, reproduces the gate's exact failure with the old seam and passes with the new one.
     • The test passed 10 of 10 isolated runs, and the whole file passed (204 tests).
     • The other saveStudy stand-ins decide each call by itself.

Acceptance criteria

1. Task 1's owned-run test rejects advance with Owned Node test exited with code 0 before declared stop 2. A declared stop is reached only when the test runs its line after the previous stop; … when the test exits with stop 2 pending, and fails at 1b2dcfa7. The help test pins the help sentence. extension/README.md carries it.

2. N54 runs in both hosts, recorded here before and after submission:

   • each host's natural multi-stop question;
   • whether the agent declared the stops in execution order;
   • every stop reached, the run sealed complete, and its replay saved and opened;
   • each take's SHA-256;
   • sourceBuild naming the candidate.

3. Task 2's three launch tests pass and fail at 1b2dcfa7 where stated. The extra listing's time on nsx is recorded.

4. Task 3's bootstrap tests pass and fail at 1b2dcfa7 where stated.

5. Each new or changed test states protects=…; fails_when=…; no_claim=…. Changes to existing tests are reported with their reason in the PR.

6. The 15-check exact-tree gate passes on the PR's final tree, in this order:

   • from extension/: pnpm format:check, pnpm typecheck, pnpm lint, pnpm health:static, pnpm dupes, pnpm dead-code, pnpm test;
   • from the repository root, after that build, with .github/reader-dom/node_modules/.bin on PATH: node extension/scripts/<check>-qa.mjs verify <new empty folder> for each of study-bootstrap, wiki-reader-dom, study-reading-pose, understanding-focus and repository-return;
   • from extension/: pnpm test:package, then pnpm health;
   • from the repository root: node --test .codex/restore-product-context.test.mjs.

   Required CI passes on the exact head, and hosted CodeRabbit approves that head.

7. Every user-visible change has a CHANGELOG entry and its sentence in extension/README.md.

8. Every defect found during this cycle is a task here and is closed before merge, except as the ship review limit allows.

Testing plan

Rules for the implementing agent

1. Acceptance criteria are each test's protects / fails_when / no_claim. Never "make the tests pass".
2. Real code and real tests land together.
3. Any change to a test, validator, CI step, timeout, tolerance, threshold, snapshot or suppression is reported on its own line with its reason.
4. A reported command names the command and its observed result.
5. A report is a claim until the driving agent re-executes it.

Rollback

Revert the PR. Nothing changes in a stored format, the MCP input or the API (it stays 1.8). Task 1 changes one error sentence and one help sentence. Task 2 adds one root listing at launch for claim-decided package runs. Task 3 changes only the native-trial bootstrap, which is not part of the packaged runtime's chat path.

Effort

Files

Out of scope

• Any increment, including the next execution form (Node server, Chrome MV3), W1, E8 and per-system work.
• Checking stop order before the run. Execution order is not known statically.
• Package-mode native proof: a deferred proof gap, not a carried defect. It is owed at final-acceptance Stage 1 in the P02/P05 library-test rows (O4 of Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #128).
• Inspection paths beyond four segments: an accepted limitation, recorded in Cycle 0052: replays leave, move and open without stale frames, and every Cycle 0051 carried defect is closed #124 among the observations that are not defects (N52 pt3). The agent recovered in one retry. Not a carried defect.

Owner decisions

• Standing: the owner's goal of 2026-10-24 and direction of 2026-10-22 hold. The owner cannot answer, so every decision takes the recommended option, named here.
• O1 (recommended). N53-F1 is fixed in the error sentence and the help, not in the bundled skill. The skill defers to the help, and a skill change would bump its version for one sentence.
  • Considered: a pre-run order check. It is impossible, since execution order is not known statically.
• O2 (recommended). CR-OD1 is fixed by re-asking the root at launch, only for package runs whose plan made a root claim. Root mode already re-asks the root at launch.
  • Considered: hashing more files (incomplete, since a root projects glob can select any config); documenting the limit (leaves the defect).
• O3 (recommended). CR-OD2 keeps the retries for the whole trial and always writes the private report, so an unreleased group is named even when it cannot be ended.
• O4 (recommended). One PR.

Next action

Closed: PR #131 merged as 601f3827 (v0.2.44.0), and nothing is carried. Next: /spec writes the Cycle 0055 feature Issue.