Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #128

Outcome

A /codebook question about a test inside a workspace package runs that test the way the package's own vitest command would, unless the repository's root config already runs it:

• the working directory is the test's nearest directory with a Vitest or Vite config, normally the package;
• the config is that one;
• the Vitest is the one Node resolves from that directory (the package's own, or one hoisted to an ancestor inside the repository);
• a test that the root config's own listing already selects exactly once keeps running from the root exactly as today (the root claim). A test under a package config in a repository with no root config moves from the root's defaults to its package config, which is this cycle's purpose;
• the run's environment stays Codebook's fixed one (CI=true, NODE_ENV=test, no inherited credentials; buildNodeTestEnvironment.ts:27), not the package script's. Vite and Vitest still load the chosen config and read the Vitest root's .env* files for import.meta.env, as the package's own vitest would; Codebook isolates only the process environment it passes.

Environment variables and CLI options that a package's test script adds are not reproduced (out of scope). The run pauses at the declared stops, reads their facts, and saves a test replay, exactly as a root test does today.

This is a feature cycle. It follows bug-fix Cycle 0052 (#124), which closed with nothing carried. It is one increment toward PRODUCT_GOAL.md's final acceptance: the library-test rows of P02 (TanStack/query) and P05 (reduxjs/redux-toolkit), plus the package tests of P07 and P08 to the extent task 1 observes them (a repository task 1 records NOT RUN keeps that claim unproven).

• Learner. A question such as "/codebook explain how QueryCache.build decides to reuse a query, running its test" in TanStack/query now runs packages/query-core's test. Today it is refused, or it runs without the package's jsdom and conditions.
• Agent. codebook_status reports node-test ready when Vitest 4+ sits at the repository root or in a package up to two levels below it. A test in a deeper package still starts: the start checks that test's own Vitest, and vitestSearch tells the agent what the search found. A start resolves the package from the cited test file. A refusal names the package path and what is missing. The node-test run's manifest names the Vitest root it used (vitestRoot).
• Engineering. One resolver feeds the prerequisite check, the file listing and the launch. The root-only assumptions at the four call sites below go away.

Verified current state (main 83a07385, v0.2.42.0, read 2026-10-26):

• utils/readVitestPrerequisite.ts:55-70 reads only <root>/node_modules/vitest/package.json. When that file is missing it refuses with "node-test needs Vitest 4 or later at the repository root; … a Vitest inside a package is not supported yet."
• utils/requireOwnedVitest.ts:24-33 resolves the program only at <root>/node_modules/vitest/vitest.mjs (VITEST_PROGRAM_PATH).
• utils/listVitestTestFiles.ts:94 and utils/launchNodeTest.ts:63 spawn Vitest with cwd set to the opened root. utils/prepareNodeTestLaunch.ts:95-106 passes no --root or --config, so Vitest sees only a root config.
• environment.ts:279 drives codebook_status's profiles['node-test'].missing from the root check.
• Help (resources.ts:273), README (extension/README.md:107) and the refusal all say "at the repository root".

Gap audit (all 13 rows, baseline 83a07385)

Each row lists (a) implementation, (b) proof and (c) next action. Native evidence so far comes only from the macOS Space local:codebook-qa on nextjs-dashboard, in VS Code 1.142 (Copilot Chat, GPT-6 Luna) and Cursor 3.27.12 (Agent, Grok 4.6 High). It is development evidence and fills no final row.

Execution forms of the nine projects. Layouts were read on 2026-10-26 from each repository's public default branch. P01 is private and was not inspected. Nothing here was executed.

Largest gaps, ranked.

1. Execution-form coverage (AC-REAL-PROJECTS, AC-LIVE). At least seven projects have a form that cannot run.
2. Stale Wiki proof (AC-WIKI, AC-WIKI-UPDATE, AC-SOURCE-LINKS).
3. Per-system and install evidence (AC-DESKTOP, AC-SKILL).

Selected increment (Working loop, step 2)

• AC IDs. Primary: AC-REAL-PROJECTS (P02 and P05 library tests, package tests of P07 and P08). Dependencies: AC-LIVE and AC-SKILL (help and README tell the rule). Regressions: AC-SAVE, AC-REPLAY, AC-GAPS, AC-LEARNING and root-mode runs on nextjs-dashboard.
• Why now. Of the gap-1 forms, this is the only one with a known mechanism on top of the proven node-test path. It tests, headless, whether package sources bind under Codebook's js-debug attach path (task 1, observation 7); native binding stays NOT RUN until Stage 1 (O4). Every other form needs new debugger and runtime work. Rows it can unlock at final acceptance: the library-test rows of P02 and P05 in both hosts (4 project-host rows), and the package-test rows of P07 and P08 (up to 4) if task 1 confirms them; their Example rows still need later profiles. A Node server profile reuses this cycle's resolver for apps/api-style roots and the same pwa-node attach to a Node process, so its main unknown is operating the server, not binding.
• Starting action. Run a bounded spike before any product code moves (task 1). Use pinned clones of TanStack/query, redux-toolkit, nsx and switch-time, outside the editors, with the real Vitest. Run vitest list --filesOnly from the package with its config. Then start one package test with --inspect-brk --no-file-parallelism, set a CDP breakpoint in package source and observe it bind.
• Expected result. The package config selects the cited file once, and the breakpoint binds in the package source.
• Falsifying observation (any of these). The cited file is selected under more than one project. The run still lacks the package config. The breakpoint never binds after the cwd change. The package Vitest resolves outside the repository. The package module's script URL or source map differs in form from a root-mode run's (observation 5). The root claim picks a mode under which the test does not pass while the other mode passes (observation 6). js-debug does not stop at the package source line through Codebook's attach arguments (observation 7). A TanStack/query or redux-toolkit package test needs a build of sibling packages first (observation 8). If one occurs, the cycle re-plans in this Issue (for example a --root or --project mode) before product code moves.

Proposed change

Resolution rule (one new utility, utils/resolveNodeTestVitestRoot.ts):

1. Walk from the cited test file's directory up to the opened root, both included. The first directory that holds a config file is the Vitest root. Any ancestor counts, not only package folders. Nothing above the opened root is consulted, even when the opened folder sits inside a larger repository. Vitest 4 has no vitest.workspace file (Vitest 5.0.2's code looks none up); a projects list lives in a config file, which this rule finds like any other.
   • A config file is a regular file named vitest.config.{ts,mts,cts,js,mjs,cjs} or vite.config.{ts,mts,cts,js,mjs,cjs}, whose realpath is inside the repository.
   • A directory with such a name, or a link that leaves the repository, is not a config file, and the walk goes on past a directory that holds only such entries. When the chosen Vitest root itself holds such an entry, or the root fallback (no config up to the root) leaves one at the opened root, the start is refused before the history, since Vitest's own config search could load it: node-test does not start Vitest in <relative Vitest root> for <relative test file>: <name> there is a folder or a link that leaves the repository, and Vitest could load it as its config. Ask the learner to remove or replace it, then start the test again. (PREREQUISITE_MISSING). This also refuses a root-mode layout that today would load such a link: the one intended root-mode change, named in the CHANGELOG.
   • When one directory holds several config files, it is the Vitest root either way; Vitest picks its own file from them.
   • When no directory up to the root has one, the opened root is the Vitest root.
   • Root claim. When the walk stops below the opened root, the opened root also holds a config file, and a usable Vitest resolves at the root (step 2 applied to the root), Codebook first lists the cited file from the root as today (vitest list --filesOnly <repository-relative path>, cwd = root). If that listing selects the file exactly once, the opened root is the Vitest root, so the run works as it does today. If it selects the file zero times or under several projects, or the listing fails, the walk's directory stays the Vitest root; the claim's result, a clean listing failure included, is recorded in the run journal when the run starts (node-test.started carries rootClaim). The claim's listing runs in the pre-history check (rule 7), within VITEST_FILE_LIST_TIMEOUT_MS and the start's preparation deadline, so the owned run's 45 s attach budget (NODE_TEST_ATTACH_TIMEOUT_MS, ownedNodeTestRun.ts:209) still covers only today's one listing; a start whose claim applies pays one extra listing in either mode, a start without a nearer config pays none. Only a clean failure falls back to package mode: the root listing ended by Vitest itself (an error exit or an unreadable list) with its process group confirmed ended, the start not cancelled and its deadline not passed. A cancellation, the deadline, or a process group that could not be confirmed ended refuses the start as today's listing does (listVitestTestFiles.ts:177), and neither the package listing nor the launch runs. The decision is a small pure function, decideNodeTestRootClaim (selected once, zero, several projects, failed cleanly, or a refusal for a cancelled, timed-out or unconfirmed listing), unit-tested on those inputs.
   • Root mode is the case where the Vitest root is the opened root: with a root config, with none, or by root claim. It behaves exactly as today (AC 3). Package mode is every other case.
2. Resolve the Vitest package by walking from the Vitest root up to the opened root. The first directory whose node_modules/vitest exists (any entry: a folder, a link, or one with a broken or unreadable package.json) holds the Vitest; the walk does not go past it, as Node's resolution would not.
   • It is read through realpath containment (resolveOwnedRepositoryFile).
   • A node_modules/vitest or vitest.mjs whose realpath leaves the repository gets the links-outside refusal.
   • A version below 4 gets the too-old refusal; an unreadable or unparsable package.json gets the unreadable-version refusal.
   • A missing vitest.mjs gets the program-missing refusal.
   • The walk never falls back to another Vitest above it.
   • Both walks use canonical paths: the cited file's realpath, which checkNodeTestFiles already checks to be inside the repository, and its ancestors. The opened root is canonical too (realpath, as checkNodeTestFiles returns it), and every step stays inside it; a walk that reaches the filesystem root without meeting it refuses the start (defensive; unit-tested with a symlinked opened root).
3. The version is printed as today (PRINTABLE_VITEST_VERSION). Paths in sentences are POSIX-style and relative to the opened root, and the root itself is written ..
4. The listing (listVitestTestFiles) and the launch (launchNodeTest) run with cwd = <vitestRoot>. The test filter is the cited path relative to the Vitest root, in POSIX form (/ separators on every system). Vitest matches a filter as a substring of file paths, so a package-relative filter can select other files whose paths contain it; the existing exclude step removes them (observation 1 checks it). The working directory is the Vitest root, not --root from the repository root, because a package's own script runs with the package as its working directory (pnpm, npm and yarn workspaces), so paths relative to the working directory resolve as they do there. A Vitest-root-relative filter that starts with - is refused before the history: node-test cannot pass <relative test file> to Vitest from <relative Vitest root>: its path there starts with "-", which Vitest would read as an option. Ask the learner to rename that file or folder, then start the test again. (INVALID_CONFIGURATION); the listing and the launch take the filter from the one plan (rule 7). The --exclude globs are the absolute paths they are today. The "belongs to N projects" and "still selects other files" refusals stay.
5. PreparedNodeTestLaunch gains vitestRoot (absolute, canonical). workspace stays the opened root, so source checks, citations, history and replay are unchanged. The node-test.started journal event already records cwd and now records the Vitest root.
6. The run's manifest resource (resources.ts:358-373, profile: node-test) gains vitestRoot: the Vitest root relative to the opened root, POSIX form, . in root mode. It also gains vitestRootReason (no-config: no config up to the root; root-config: the root holds the nearest config; root-claim: the root claim kept root mode; nearest-config: package mode), rootClaim (not-applicable, selected-once, not-selected, several-projects or listing-failed), vitestConfigFiles (the config file names in the Vitest root, [] when none) and skippedConfigFiles (config-named entries the walk passed over in directories between the test and the Vitest root, as in-repository relative POSIX paths, never link targets, usually []). It is read from the in-memory prepared run (service.ts:230), so it appears wherever the node-test manifest appears today and no stored format changes; a saved replay does not carry it (X9, later). configurationHash hashes the agent's configuration, not argv or cwd, so it stays as it is. One owned node-test run per opened repository, as today; the Vitest root adds no lock.
7. Execution plan. The pre-history check (environment.checkNodeTestFiles, environment.ts:376-388, called at service.ts:3254 before the history starts) computes the whole plan once: the walk, the root claim with its listing, the Vitest resolution for the chosen root (version and program), the Vitest-root-relative filter and the manifest fields. It returns the plan to the service, which stores it in record.nodePrepared (the manifest reads it) and passes it to createNodeTestRun; prepareNodeTestLaunch re-verifies its identity just before listing (the same Vitest root from the walk, the same Vitest realpath and version, the same config file names) and refuses a changed plan: node-test's plan for <relative test file> changed while the run was preparing (<what changed>); start the test again. (INVALID_CONFIGURATION). So every refusal of this plan's Vitest rules comes before the history; the existing listing refusals keep today's timing and handling (after the history starts).

Readiness (codebook_status, environment.ts:279):

• node-test is ready when a usable Vitest (4 or later, inside the repository) is found in node_modules/vitest at the root, or in a directory one or two levels below it.
• Directories named node_modules or starting with ., symbolic links to directories, and directories that cannot be read are skipped (lstat, no link following, so no cycle).
• The search lists at most NODE_TEST_READINESS_DIRECTORY_LIMIT (256) directories per codebook_status call, the root first, then breadth first. When the limit ends the search before a usable Vitest is found, missing reads instead node-test found no usable Vitest in the first 256 folders it looked at (the repository root and up to two levels below it) and did not look further. A start still checks the cited test's own package.; it asks for no install, since the search was incomplete.
• Sorted path order is the code-unit order of the relative POSIX paths (JavaScript's default string sort), not a locale order.
• Ready as soon as one candidate is usable, whatever the others are.
• With none usable and none found, missing reads: node-test needs Vitest 4 or later at the repository root or in a package one or two levels below it; none was found. Ask the learner to install Vitest, then call codebook_status again. A test in a deeper package can still start: the start checks that test's own package.
• A candidate is found when its node_modules/vitest exists as any entry (a folder, a link, or one whose package.json is missing or unreadable). With none usable but some found, missing names the first one found in search order (breadth first: the root, then the directories one level below it in sorted path order, then those two levels below it in sorted path order), in one of three exact forms, where <path> is its directory relative to the opened root (. for the root):
  • node-test needs Vitest 4 or later at the repository root or in a package one or two levels below it; the first one found, <path>/node_modules/vitest, is <version>. Ask the learner to install or upgrade it, then call codebook_status again. A test in a deeper package can still start: the start checks that test's own package.
  • the same sentence with is an unreadable version in place of is <version>;
  • the same sentence with links outside the repository in place of is <version>;
  • the same sentence with is missing its program vitest.mjs in place of is <version>. A candidate is usable only with a version of 4 or later and its vitest.mjs present.
• The start-time check (step 2) stays authoritative for the cited file. A start no longer waits on the readiness search: for node-test, the start gate at service.ts:3233 awaits a separate start-time prerequisite check (Node, the debugger and the other node-test prerequisites, without the repository search, so neither the search's time nor its result reaches the start), while codebook_status keeps the full search; the cited file's own resolution in the pre-history check (rule 7) takes the search's place. So a test whose package lies deeper than two levels, or past the 256-directory limit, starts when its own Vitest is usable.
• codebook_status adds profiles['node-test'].vitestSearch: usable (a usable Vitest was found), none (none found), unusable (the first one found is too old, unreadable, links outside or lacks its program) or incomplete (the 256-directory limit ended the search). ready is true only with usable and the other prerequisites met; with the other three, missing holds the sentence and the walkthrough (resources.ts:239) tells the agent it may still start a test whose own package has Vitest.

Refusal sentences (exact text):

• No Vitest for the file: node-test needs Vitest 4 or later for <relative test file>; none was found in <relative Vitest root>/node_modules/vitest or above it inside the repository. Ask the learner to install Vitest in that package or at the repository root, then start the test again.
• Too old: node-test needs Vitest 4 or later for <relative test file>; <relative path>/node_modules/vitest is <version>. Ask the learner to upgrade it, then start the test again.
• Unreadable version: node-test cannot read the version of <relative path>/node_modules/vitest for <relative test file>: its package.json is missing, unreadable or not a Vitest package file. Ask the learner to reinstall the dependencies, then start the test again.
• Program missing: node-test needs the Vitest program <relative path>/node_modules/vitest/vitest.mjs for <relative test file>; reinstall Vitest there, then start the test again.
• Links outside: node-test needs Vitest 4 or later inside the repository for <relative test file>; <relative path>/node_modules/vitest links outside it (for example to a package store outside the repository), which Codebook does not run. Ask the learner to install the dependencies so that Vitest lies inside the repository, then start the test again.
• Channel: codebook_start returns its receipt at once, as today (service.ts:1190); each refusal then appears in the run resource's error (code PREREQUISITE_MISSING or INVALID_CONFIGURATION, message = the sentence, its cause, and the code's fixed recovery), never as an MCP tool error and never as success; codebook_status's missing is data. These refusals come before the run's history exists, so starting again is safe. A host test reads one refusal through the MCP run resource (H10).
• The listing refusals at prepareNodeTestLaunch.ts:156-182 ("Vitest does not select the cited test file under this repository's Vitest configuration.", "…belongs to N Vitest projects…", "Vitest's file filter also selects N other test files…", "Vitest still selects other test files after Codebook excluded them…") stay verbatim in both modes, and their existing tests stay unchanged. In both modes their error cause (reachable through the run resource's error, service.ts:2776) carries the diagnosis: the test path, the Vitest root, the root-claim result and the filter, all relative POSIX paths, and notes that the config's own root, dir or include may exclude the file. A listing timeout keeps today's refusal and timing (after the history starts); the learner may start again.

MCP. The API stays 1.8: no input changes; the manifest's vitestRoot, vitestRootReason, rootClaim, vitestConfigFiles and skippedConfigFiles and codebook_status's vitestSearch are additive output fields, as applicationOrigin and applicationPortSource were (CHANGELOG.md:136). The rule is deterministic from the cited file and the repository's configs. The start contract changes in one way: a node-test start no longer needs ready from the Vitest search (help, README and CHANGELOG say so).

Tasks

1. Spike (bounded experiment, time box 9 h). Evidence: all observations PASS on all four repositories, no re-plan (task 1 comment); the post-task-3 rerun PASS through Codebook's own wiring (tasks 2–6 comment).
   • Clone TanStack/query, reduxjs/redux-toolkit, laststance/nsx and laststance/switch-time at their default branches' current commits (recorded as the pinned commits) into a temporary folder outside the editors and the repository. Install each with its own documented install command.
   • Before choosing, write one natural learning question each for TanStack/query and redux-toolkit in this Issue (different code paths, not asked in earlier cycles), and pick the package test whose run exercises the code that answers it: under a TanStack/query package (packages/query-core/src/ or packages/react-query/src/) and under packages/toolkit/src/. For nsx (browser-extension/) and switch-time (apps/api/), pick one test each chosen by vitest list --filesOnly from that package and recorded.
   • Observations:
     • (0) The Vitest version Node resolves from the package (node_modules/vitest/package.json). Below 4 = NOT RUN for that repository, recorded.
     • (1) vitest list --filesOnly <file> run from the package (cwd = package) selects the file exactly once (pass condition). Only when the same filter also selects another test file: adding --exclude=<that file's absolute path> must drop it from the listing; otherwise record the exclude check as not applicable.
     • (2) vitest run <file> from the package passes (record its exit code, wall time, and whether the package config's typecheck ran for it; a typecheck failure Vitest reports is the run's result as Vitest reports it). Contrast: the same file run from the opened root with the same Vitest program (node <the package's resolved vitest.mjs> run <repository-relative file>, cwd = root) fails, which shows the package config is in effect. If it passes from the root too, try up to two more files of the same repository that need their package config (a .test.tsx under jsdom, or one importing through resolve.conditions); after three files without a contrast, record "contrast not shown" (not falsifying).
     • (3) vitest run <file> --inspect-brk --no-file-parallelism from the package. Through CDP, set a breakpoint by URL regex on an executable line of a package source module the test calls (not the test file; for example packages/query-core/src/queryCache.ts or packages/toolkit/src/createSlice.ts), then resume. Within 60 s the process must pause there, and Runtime.getProperties on that frame's local scope must return at least one variable.
     • (4) Each package's node_modules/vitest realpath stays inside the clone.
     • (5) Source-map form equivalence (raw CDP: it shows the package module looks to a debugger as a root-mode module does, not that js-debug binds it; native js-debug binding of package mode stays NOT RUN until Stage 1, O4). In (3)'s run, record the Debugger.scriptParsed event of the package source module (the event whose url, read as a file path when it is a file:// URL, or whose source map's resolved sources entry equals the module's realpath): its url scheme (file:// URL, bare absolute path, or other), whether it has a sourceMapURL, and whether one entry of the decoded source map's sources, resolved against sourceRoot and the script URL, equals the module's absolute realpath. Record the same three facts once for app/lib/utils.test.ts of nextjs-dashboard at 1936e41 (module app/lib/utils.ts; a root-mode Vitest run, the path that binds natively in N52, so both sides are Vitest runs). Pass = the same scheme, a source map in both, and in both a sources entry resolving to the module's realpath (for example sources: ["utils.ts"] under the script URL file:///…/app/lib/utils.ts resolves to /…/app/lib/utils.ts; a webpack://, /@fs/ or other non-file entry does not count). A different scheme is falsifying even when the source map resolves, since the native proof covers only the baseline's scheme.
     • (6) Root claim. For nsx and switch-time (each with a root config): list the chosen package test from the root with the root Vitest (vitest list --filesOnly <repository-relative file>, cwd = root) and record whether it is selected exactly once; run it from the root and from the package and record each result. Pass = the mode the root claim picks is one under which the test passes, or neither mode passes. For TanStack/query and redux-toolkit, record whether the root holds a config file.
     • (7) js-debug binding (TanStack/query and redux-toolkit; headless, mechanism level). Obtain and verify the release artifact before the spike's clock starts, then run the standalone js-debug DAP server from the microsoft/vscode-js-debug release matching the VS Code-bundled js-debug (1.140.0 on this Mac; record the version used) and attach to (3)'s paused process with Codebook's attach arguments (ownedNodeTestRun.ts:258-270: type: pwa-node, request: attach, websocketAddress, cwd = the opened root, sourceMaps: true). Send setBreakpoints for (3)'s package source line by file path, continue, and require a stopped event at that file and line within 60 s and a nonempty variables reply for its first scope. This is the product's DAP path without the editor; it is still no native evidence (O4).
     • (8) Official command (all four). Record the package's test script and run the repository's documented test command for the chosen file once (for example pnpm --filter <package> test -- <file>); record its result, the config it used and the environment variables it sets, beside (2)'s direct run. Record whether (2)'s package run needed a build of sibling packages first; on TanStack/query or redux-toolkit that need is falsifying (Codebook runs no build).
   • Time boxes: TanStack/query and redux-toolkit 3.5 h each, nsx and switch-time 1 h each, every observation in each. A repository not installable in its box is recorded NOT RUN with the reason.
   • Stop condition: a failure or NOT RUN of (0)–(5), (7) or (8)'s sibling-build check on TanStack/query or redux-toolkit (a Vitest below 4, not installable, or a time box that ends first), or a failure of (5) or (6) on any repository, stops the spike and re-plans this Issue before task 2. Other failures on nsx or switch-time drop that repository's P07/P08 claim, recorded. Record commits, commands, outputs and verdicts in a comment of this Issue, with repository-relative paths and environment variable names only, never their values (the Issue is public); raw logs stay in the ignored artifacts/cycle-0053/spike/. Task 1, observation (1) included, runs before any code of task 2 or 3.
   • After tasks 2 and 3, repeat (1)–(3) and (5)–(7) once with the argv and cwd that Codebook's own prepareNodeTestLaunch produces, the environment buildNodeTestEnvironment builds (CI=true, NODE_ENV=test) and the attach arguments ownedNodeTestRun sends, for the same files on the same clones (a headless script), so the shipped wiring, not only the plan, meets the real packages. Record the result beside the spike's. A rerun failure is a defect of tasks 2–3, fixed before the PR; it does not re-plan.
2. Resolver (fixed in e76a705e, review fixes through c0198a68; PR v0.2.43.0 feat: Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #129) resolveNodeTestVitestRoot, with unit tests:
   • the nearest config wins; root fallback with a root config and with none;
   • a hoisted Vitest, and a package-only Vitest;
   • the nearest Vitest is older, with a good one above it: refused, no fallback;
   • a Vitest link that leaves the repository;
   • a config name that is a directory, and a config link that leaves the repository: skipped.
   • decideNodeTestRootClaim: the root listing selects the file once (root mode), zero times, under two projects, or fails cleanly (package mode); a cancelled, timed-out or unconfirmed listing is a refusal, not a fallback.
   • an unusable root Vitest skips the root claim (package mode); a dangling or unreadable config link is skipped; an unreadable ancestor (EACCES) refuses; a symlinked opened root still bounds the walk; a chosen root holding a config-named folder or an outside link is refused; a Vitest-root-relative filter starting with - is refused.
3. Execution plan, launch and listing (fixed in e76a705e; worker binding 59f83737; PR v0.2.43.0 feat: Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #129) use the Vitest root (environment.checkNodeTestFiles for the pre-history plan, the start gate at service.ts:3233, prepareNodeTestLaunch, requireOwnedVitest, listVitestTestFiles, launchNodeTest, ownedNodeTestRun). Host tests:
   • A package-mode test runs with cwd = package and its filter relative to the package; the excludes are unchanged.
   • A package-mode run goes through preparation, a captured stop with its facts, completion and the history's seal with the existing harness (nodeRunHarness, nodeTestService tests). Its history and replay paths are the same as for a root run.
   • A root-mode test runs exactly as today, with the same argv, cwd, excludes, configurationHash and journal cwd as at 83a07385.
   • Root claim: with a root config whose listing selects the cited package test exactly once, the run is in root mode; with a root listing that selects it zero times or under two projects, or a root listing that fails cleanly (journaled), it is in package mode.
   • The manifest resource reads vitestRoot: "." for a root-mode run and vitestRoot: "packages/<name>" for a package-mode run.
   • The host tests: (H1) package-mode listing cwd, filter and excludes; (H2) package-mode launch cwd and argv; (H3) package-mode seal complete and replay open; (H4) root-mode argv, cwd, excludes, hash and journal cwd equal to 83a07385; (H5) the root claim's root-mode case, its three package-mode cases (zero selections, two projects, a clean failed root listing, which also writes its journal record), and its three refusals (a cancellation, the deadline, an unconfirmed process-group end), where neither the package listing nor the launch runs; (H6) the manifest fields in both modes; (H7) a Vitest only three levels below the root: codebook_status reports vitestSearch: none and a start of a test there runs in package mode, the same with the search ended by the 256-directory limit (incomplete), and a start that proceeds while the search is slow or failing, while a Node or debugger prerequisite still refuses it; (H8) each listing refusal's cause names the Vitest root, the root-claim result and the filter; (H9) a start refused for an unreadable version, then for a link outside, runs once the learner's repair is in place; (H10) one refusal read through the MCP run resource's error; (H11) a plan changed between the pre-history check and the launch (a new nearer config) is refused with its sentence.
4. Readiness (fixed in e76a705e, bounded in fcc16cc6/c0198a68; PR v0.2.43.0 feat: Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #129) in codebook_status and the start gate (service.ts:3233), with unit and environment tests: (R1) a package-only Vitest two levels below the root is ready; (R2) none found gives the first missing sentence; (R3)–(R5) the first found is too old, unreadable, or links outside, each with its exact form, and one with a good version but no vitest.mjs before a later usable one (ready); (R6) node_modules, dot-directories and symbolic links to directories are not entered; (R7) the directory limit ends the search and the sentence says so; (R8) vitestSearch reads usable, none, unusable and incomplete in those cases.
5. Refusal sentences (fixed in e76a705e; help code fixed in e825b04a; PR v0.2.43.0 feat: Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #129) as specified, with tests that pin each one.
6. Docs. (e76a705e, acc56c30, CHANGELOG 297c8cf4; PR v0.2.43.0 feat: Cycle 0053: a test inside a workspace package runs with that package's Vitest and config #129)
   • Help (resources.ts:239 walkthrough and :273) and README (extension/README.md:107 and the node-test section) tell the rule in one line (the nearest Vitest or Vite config above the test wins, unless the root config already selects the test once), the readiness depth and limit, that the start check decides for the cited test, and that the run uses Codebook's fixed environment, not the package script's. The bundled skill names no Vitest location (skills/codebook/SKILL.md, 1.0.47) and stays unchanged.
   • README adds a short package-test quickstart reachable from its Quick start: the prerequisite (Vitest 4+ in the package or above it), which folder to open, the shape of a natural question about a package's test, how success shows (the run manifest's vitestRoot), and what differs from the package's own test script.
   • README adds a troubleshooting table: each refusal and missing form, its code (PREREQUISITE_MISSING, INVALID_CONFIGURATION), its cause and its fix, with rows for a root listing that selects the test under several projects (package mode, rootClaim: several-projects) and for a package store outside the repository (pnpm's global virtual store or a shared store). README also says the chosen config and its .env* files load as the package's own vitest would, and that Yarn Plug'n'Play is not supported.
   • User-facing text says "Vitest root" for the folder whose config the run uses and "package" only for a package folder; the PreparedNodeTestLaunch docstring tells workspace (the opened root) from vitestRoot.
   • Also correct extension/README.md:13's "exact bytes" claim for the Cursor copy (AC-SKILL).
   • Add a CHANGELOG entry with an upgrade note: in a repository with no root config, a test under a package config now runs with that package's config and Vitest (the run manifest's vitestRoot shows it); runs the root config claims are unchanged; the package script's environment and options are not reproduced; a start no longer waits on the readiness search. The README:13 correction gets its own CHANGELOG line. A README sentence covers each behavior the entry names.
7. N53, native, both hosts (evidence: PASS both hosts on 297c8cf4, N53 results; found N53-F1, carried), on nextjs-dashboard at 1936e41 in the Space, on the PR's candidate:
   • (a) A new natural /codebook test 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 or Cycle 0052: replays leave, move and open without stale frames, and every Cycle 0051 carried defect is closed #124) runs in root mode: stops, facts, replay save and open. Record the time from the question's submission to the first stop (root-mode time-to-first-stop in a prepared repository).
   • (b) Package mode is NOT RUN natively, under the development-target rule (O4); task 1 and the host tests are its proof at their stated level.

Acceptance criteria

1. Task 1's comment records, for each repository, the pinned commit, observations (0)–(8), the two learning questions and a verdict; a repository not installable in its time box, or with a Vitest below 4, is NOT RUN with the reason; NOT RUN on TanStack/query or redux-toolkit re-plans this Issue. A falsifying result re-plans this Issue before task 2.

2. A cited test file under a directory with its own Vitest or Vite config, which the root claim does not keep at the root, runs with cwd set to that directory, its filter relative to it, and the Vitest resolved from it or the nearest ancestor inside the repository; a test the root claim keeps runs in root mode (host tests H1–H3, H5).

3. A cited test file whose Vitest root is the opened root (a root config, no config at all, or the root claim) runs exactly as at 83a07385: same argv, cwd, excludes, configurationHash and journal cwd (host test H4). The one intended root-mode change: a root holding a config-named folder or a link that leaves the repository is now refused.

4. A package-mode run seals its history complete and its replay opens, through the existing service and run harnesses (host tests).

5. codebook_status reports node-test ready for a repository whose only Vitest 4+ is in packages/<name>/node_modules/vitest. It reports the search in missing and vitestSearch when there is none. No directory named node_modules or starting with . is entered (unit tests).

6. Each of the eight refusal sentences (five Vitest, the chosen-root config entry, the - filter, the changed plan) is returned exactly in its case (tests pin the literals).

7. N53 (a) passes in both hosts. The VS Code chat is Copilot Chat with GPT-6 Luna and the Cursor chat is Agent with Grok 4.6 High (fallback: the Codex Extension after observed credit exhaustion). Each take's SHA-256 is recorded here.

8. The 15-check exact-tree gate passes on the PR's final tree:

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

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

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

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

11. The node-test manifest resource names vitestRoot: . for a root-mode run, packages/<name> for a package-mode run, with vitestRootReason, rootClaim, vitestConfigFiles and skippedConfigFiles (host test H6).

12. A node-test start of a test whose own package has a usable Vitest succeeds while codebook_status reports node-test not ready only because of the Vitest search (vitestSearch none or incomplete); any other unmet node-test prerequisite still refuses the start (host test H7).

13. Each listing refusal keeps its message and carries a cause naming the test path, Vitest root, root-claim result and filter (H8); a refused start whose prerequisite the learner repaired starts on the next attempt (H9).

14. Every refusal of this plan's Vitest rules comes before the history (rule 7); a refusal reads through the MCP run resource's error (H10); a plan changed between the pre-history check and the launch is refused (H11); a root listing cancelled, past the deadline or with an unconfirmed process-group end refuses without the package listing or the launch (H5).

Testing plan

Where the implementer finds the context.

• The cycle procedures (gate, native round, Owner decisions) are in AGENTS.md (Working loop, Delivery, Native QA).
• The 83a07385 baseline: run today's root-mode launch host test once in a worktree at 83a07385 and write the argv, cwd and excludes it produces into H4 as hard-coded literals (with the fixture paths it uses); H4 then compares the new code against those literals.
• /autoplan's review of this plan is recorded in a comment of this Issue before task 1 starts. Its accepted changes amend this body.
• The bundled skill needs no change (it names no Vitest location); task 6's help and README sentences were reviewed in this /autoplan's DX phase and are re-checked in Eng.
• The body is authoritative; the amendment lists at the end name what each review changed.

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. No stored format and no MCP input change (the additive manifest and codebook_status fields go with the revert, and a start again waits on the readiness search). Root-mode runs keep their argv, cwd, excludes and hash (AC 3); the readiness and refusal wording changes for every repository (tasks 4 and 5) and reverts with the PR.

Effort

Total: about 4.5 days for a human team; for CC, about 2.5 working days plus the native round and the gate.

Files

Out of scope

• New run profiles: Node server (Express, Hono), Chrome MV3, Vite or Expo web, Pages Router, and library Examples.
• Jest, Mocha and node:test.
• Environment variables and CLI options a package's test script adds.
• A vitestRoot input field (no MCP input change).
• Detecting a nearest config that does not hold its tests' settings (a build-only vite.config.*) when the root claim does not apply: it cannot be told without running the config. The manifest's vitestRoot shows which root ran, and task 1's observation (6) checks the two repositories with a root config.
• Native Windows use (goal v10's per-system cycle). On macOS and Linux the walk compares the canonical paths checkNodeTestFiles already produces.
• Recording the Vitest root and version in the saved replay (X9): a stored-format change with its own compatibility work; the live manifest carries vitestRoot now.
• Reproducing a package script's own environment variables and CLI options; task 1's observation (8) records how the official command differs.
• Native package-mode trials on the nine projects (O4).
• The Wiki trial (W1), per-step understanding (E8) and the Windows and Ubuntu cycle.

Owner decisions

• Standing:
  • The owner's goal of 2026-10-24 and the direction of 2026-10-22: every resource goes to the product; never spend money or break the law.
  • The owner cannot answer, so each decision takes the recommended option, named here.
• O1 (recommended): this cycle's increment is node-test in workspace packages.
  • Why: it is the largest gap with a known mechanism, it is 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 O1's next candidate, and it tests the package-binding unknown headless (task 1, observation 7) before the server and extension profiles; native binding stays for Stage 1.
  • Considered: the Wiki fidelity trial (W1), a Node server profile and a Chrome MV3 profile. They stay later candidates.
• O2 (recommended): the Vitest root is the nearest ancestor of the cited file, up to the opened root, that holds a Vitest or Vite config.
  • Vitest resolves from there or the nearest ancestor inside the repository. There is no new input field, and MCP stays at 1.8 (additive output fields only). A test the root config's own listing selects exactly once keeps root mode (the root claim, CEO review), so a test the root config runs today keeps running that way.
  • Considered: an agent-supplied vitestRoot field (an API change that needs its own DX review), and always using the root (P02 loses its config).
• O3 (recommended): readiness searches the root and directories up to two levels below it, never entering node_modules or dot-directories. The start-time check stays authoritative.
  • Considered: reading workspace globs (pnpm-workspace.yaml, workspaces), which adds parsing for three package managers; and dropping the readiness check, which would claim ready for repositories without Vitest.
• O4 (recommended): native trials stay on nextjs-dashboard (AGENTS.md, Development target). Package mode is proven by the headless real-Vitest spike on pinned public clones (development evidence, no final-row credit) and by host tests. Its native proof comes at final acceptance Stage 1 (P02 and P05 rows).
• O5 (recommended): the gstack upgrade offered at this /spec waits ("Not now"), so the instructions stay stable during the cycle.
• O6 (recommended): one PR, unless the spike re-plans the cycle (up to three PRs are allowed).
• O7 (recommended, 2026-10-26): /autoplan reviewed this plan (CEO, DX and Eng with Claude and Codex voices each; Design skipped, no UI). The owner cannot answer, so its final gate took every recommendation (rec, the owner's standing instruction): d1 keep the root claim; d2 add the manifest fields; d3 defer the fixture real-Vitest test; d4 keep O1; d5 defer the root in saved replays; d6 defer an agent-selected Vitest root input; d7 defer refusal sub-codes; d8 refuse a chosen root holding a config-named folder or outside link; plan approved as amended. The review record is summarized in this Issue's /autoplan comment.
• O8 (recommended): the /office-hours offer at /autoplan's start was skipped; /spec had already written the problem, premises and alternatives here.
• O9 (recommended): cheap, mechanical informational review findings were fixed in the same fixing pass instead of being carried (owner, 2026-10-22: every resource to the product).
• O10 (recommended): the ship review limit was reached (three fixing cycles); every last-round finding was fixed in c0198a68 without another round, no Critical/Major stayed open (no Issue recorded), and the PR reports converged:false (owner, 2026-10-23).
• O11 (recommended): release 0.2.43.0 (patch, the project's per-cycle convention).

Later candidates (a short list; no carried defect):

• W1: native Wiki fidelity, update and source-link trial in both hosts.
• The next execution form after this one: a Node server profile (P07 Express, P08 Hono) or Chrome MV3 (P06, P07).
• E8 (per-step understanding) and C1, C5, C8 to C12 of 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.
• From this cycle's DX review: refusal sub-codes beyond PREREQUISITE_MISSING (an MCP code-set change); an agent-selected Vitest root input, triggered by a package-mode failure whose rootClaim shows the root would select the file.
• From this cycle's CEO review: codebook_status listing the packages with a usable Vitest (X5); a committed real-Vitest test on a fixture monorepo (X6); the replay summary naming the Vitest root (X9).

Next action

PR #129: required CI and hosted CodeRabbit approval on the exact head, the 15-check exact-HEAD gate, then merge with --match-head-commit; then close this Issue naming N53-F1 as carried, and /spec a bug-fix cycle for it.

• CEO review amendments (2026-10-26, autoplan auto-decisions; the owner cannot answer, so each is the recommended option). They are folded into the body above; this list names them:

  • Root claim (taste, from spec review 2): when the walk stops below the opened root, a root config exists and a usable root Vitest resolves, a root listing that selects the cited file exactly once keeps root mode, so a test the root config runs today keeps running that way; zero selections, several projects or a failed listing keep package mode. Host test H5; observation (6) on nsx and switch-time.
  • Task 1 runs on four repositories (TanStack/query, redux-toolkit, nsx, switch-time) with observations (0)–(8), time box 9 h plus a 1 h rerun with Codebook's argv; a failure or NOT RUN of (0)–(5), (7) or (8)'s sibling-build check on TanStack/query or redux-toolkit, or a failure of (5) or (6) anywhere, re-plans; other nsx/switch-time failures drop that repository's claim, and NOT RUN there is recorded with the reason.
  • Observation (5) is source-map form equivalence by raw CDP (relabelled from "js-debug equivalence": it narrows premise 11, it does not close it) against nextjs-dashboard app/lib/utils.test.ts at 1936e41; native js-debug binding of package mode stays NOT RUN until Stage 1 (O4).
  • The rule's limits are stated: any ancestor counts, nothing above the opened root is consulted, Vitest 4 has no workspace file, the filter is POSIX, one owned run per repository, native Windows out of scope.
  • Proposed change 6 and AC 11: the node-test manifest resource gains vitestRoot (POSIX, relative, . for root), from the in-memory prepared run, absent from saved replays; the API stays 1.8 as an additive output field (precedent CHANGELOG.md:136).
  • Spec review 3 (cap reached, fixes applied without a fourth review): vitestRoot carried PreparedNodeTestLaunch → nodePrepared (service.ts:230, :3219) → manifest, outside configuration; readiness lists at most 256 directories (NODE_TEST_READINESS_DIRECTORY_LIMIT) and says so when the limit ends the search; code-unit sort order; the existing listing refusals stay verbatim; the root-claim listing is reused as the first listing and decided by the unit-tested decideNodeTestRootClaim; NOT RUN on P02/P05 re-plans; (5) matching rule and scheme rule; Vitest's substring filter named; rerun failures are task 2–3 defects; H4 compares hard-coded literals captured at 83a07385; readiness tests R1–R7; unit count +24.
  • CEO dual voices (Claude subagent and Codex gpt-6-astra, 2026-10-26): observation (7) js-debug DAP binding through Codebook's attach arguments (headless, mechanism level); observation (8) the official test command and no sibling build; P02/P05 tests chosen from a natural learning question written in the Issue first; time box 9 h; the outcome states the fixed environment and corrects the regression guarantee (a test under a package config with no root config moves to its package config); --root dismissed in favor of cwd with the reason; a truncated readiness search asks for no install; rows unlocked stated in Why now; recording the root in saved replays stays X9.
  • CEO review sections: H5 adds the failed-root-listing case and asserts its journal record.
  • Readiness: a candidate is found when node_modules/vitest exists as any entry; breadth-first order; three exact missing forms; both missing sentences say a deeper package can still start.
  • AC 2, AC 3 and task 3 name H1–H6, including configurationHash and journal cwd against 83a07385; Rollback names the wording change; Files adds prepareNodeTestLaunch.ts:67-183 and the read-only checkNodeTestFiles.ts.
  • Out of scope adds the undetectable build-only nearest config outside the root claim and native Windows; Later candidates add X5, X6 and X9; the AC-SKILL path is extension/README.md:13 (original task 6 scope); Effort and the Testing plan are re-estimated.

• DX review amendments (2026-10-26, autoplan auto-decisions; the owner cannot answer, so each is the recommended option). Folded into the body above; this list names them:

  • Start gate: a node-test start no longer waits on the repository-level Vitest search (service.ts:3233); every other node-test prerequisite still gates it; codebook_status adds vitestSearch (usable, none, unusable, incomplete) and the walkthrough at resources.ts:239 says a test whose own package has Vitest may still start (AC 12, H7, R8).
  • Five refusal sentences: too old and unreadable are split, the link-outside fix names a package store outside the repository, and each file-level refusal ends with "then start the test again"; the channel is the start's PREREQUISITE_MISSING error; refusals come before history (AC 6, H9).
  • The listing refusals keep their messages and carry a cause with the test path, Vitest root, root-claim result and filter (AC 13, H8); a listing timeout keeps today's refusal, with no side effects.
  • The manifest adds vitestRootReason, rootClaim, vitestConfigFiles and skippedConfigFiles beside vitestRoot (AC 11, H6); all additive, API stays 1.8.
  • The attach cwd stays the opened root (ownedNodeTestRun.ts:264 unchanged); the spike's rerun uses Codebook's own argv, environment and attach arguments; the spike's public Issue comment uses relative paths and environment variable names only.
  • Docs: one-line rule, readiness depth, start authority and fixed environment in help and README; a package-test quickstart; a troubleshooting table; "Vitest root" vocabulary; the CHANGELOG upgrade note and a separate README:13 line; the bundled skill stays 1.0.47.
  • N53 records root-mode time-to-first-stop. Later candidates add refusal sub-codes and an agent-selected Vitest root input.

• Eng review amendments (2026-10-26, autoplan auto-decisions; the owner cannot answer, so each is the recommended option). Folded into the body above; this list names them:

  • Rule 7, the pre-history execution plan: environment.checkNodeTestFiles computes the walk, the root claim with its listing, the Vitest resolution, the filter and the manifest fields once, before the history; the service stores it in nodePrepared and passes it to the run; prepareNodeTestLaunch re-verifies it and refuses a changed plan (H11, AC 14).
  • The root claim falls back to package mode only on a clean listing failure; a cancellation, the deadline or an unconfirmed process-group end refuses without the package listing or the launch (H5); its listing uses the preparation deadline, so the 45 s attach budget is unchanged.
  • The start gate awaits a separate start-time prerequisite check without the repository search (H7).
  • New refusals: a chosen root holding a config-named folder or outside link (also the one intended root-mode change, AC 3), a Vitest-root-relative filter starting with -, and a changed plan; eight sentences in all (AC 6).
  • The refusal channel is corrected: the start returns its receipt, and refusals appear in the run resource's error (H10).
  • Readiness: usable needs version 4+ and vitest.mjs; a fourth missing form for a missing program; the readiness search moves to utils/searchRepositoryVitest.ts.
  • The opened root is canonical and bounds the walk; skippedConfigFiles lists in-repository paths only; spike (2) records exit code, wall time and typecheck; (5) rejects /@fs/ sources; (7) verifies the js-debug artifact before the clock.
  • Docs: config and .env* loading, Yarn PnP unsupported, troubleshooting rows for several projects and a store outside the repository.
  • Effort and test counts re-estimated (unit +35, host +11); the body is authoritative over the CEO and DX lists' earlier counts.