@redue/cli 0.1.0-alpha.12 → 0.1.0-alpha.14

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 0.1.0-alpha.14 — 2026-10-21
+
+Bench numbers below are from one 800-file project on macOS arm64, Node 22.13.0.
+Released alpha.13 and this build ran interleaved on the same machine; the
+typecheck decision path is unchanged within noise (warm `status --sync` 162/157
+ms on alpha.13, 169/166/289 ms on alpha.14; `redue run` overhead 12/14% and
+12/7/18%; states correct, no idle probe launches).
+
+- New opt-in recipe for unit tests: `redue init --recipe tests-direct --check
+  test` records a single-package npm project's Vitest 4/5 or Jest 29 run on
+  macOS and Linux. The check's inputs are the whole checkout (minus `*.md`,
+  `*.mdx` and, with `--coverage`, `coverage/`), the installed files, the Node
+  binary, the exact command, and every environment variable the run's
+  JavaScript reads directly, compared by value. A recorder loaded into every
+  Node process and worker thread of the run guards the rest: reading an
+  excluded or git-ignored file, a directory listing or large file outside the
+  checkout, network use other than loopback, or a process that escaped the
+  recorder makes the result UNVERIFIED with the reason. Lookups outside the
+  checkout become run facts that status checks again. Two runs on the same
+  inputs with different results make the check UNVERIFIED until the inputs
+  change. See [direct tests](docs/user/tests-direct.md) for the claim and its
+  limits.
+- Claude Code: the hook skips or records a direct test check's runs (`npm run
+  <script>`, `npm test`, the script's own command) like the typecheck's.
+- Linux: a directory created or deleted in the checkout is now an event, not
+  an observation gap. Before, every new directory forced a full reconciliation,
+  and a second one during it left the observer UNVERIFIED (`plan_gap`).
+- An excluded installed path appearing (a runner cache, a TypeScript build-info
+  file) no longer changes the input plan. Checks with such an exclusion are
+  STALE with "input plan changed" once after the upgrade, until their next run.
+- Measured with Claude Code on three public projects (Sonnet 5.5, CI Linux,
+  72 sessions): agents skipped 21 test runs, every skip confirmed by three
+  plain reruns on its tree, and session time fell from 515 to 295 s summed over
+  the task medians. In two sessions the agent itself left out its final test
+  run after a README-only edit, without asking REDUE; both said so, and the
+  final trees passed.
+
+## 0.1.0-alpha.13 — 2026-10-19
+
+Bench numbers below are from one 800-file project on macOS arm64, Node 22.13.0.
+Released alpha.12 and this build ran interleaved on the same machine; the
+decision path is unchanged within noise (warm `status --sync` 192/197 ms on
+alpha.12, 174/198 ms on alpha.13; states correct, no idle probe launches).
+On the CI screen of 38 public TypeScript projects, 22 qualify for the direct
+recipe, up from 19 at alpha.12: worldmonitor, Recordly and open-cowork, which
+the fixed 5 s probe deadline blocked.
+
+- A full state probe may run longer on large projects. Its deadline was a
+  fixed 5 s (10 s on Windows and for pnpm); now it is the larger of twice the
+  last successful probe and the last completed run, at least that floor and at
+  most 60 s, doubling after a timeout. A probe that never finishes is still
+  killed at its deadline and the check stays UNVERIFIED. `redue status --sync`
+  and `redue run` wait for the observer up to the sum of its checks' probe
+  deadlines plus 10 s (`probe_deadline_ms` in status JSON), never less than
+  before. While a full probe runs the observer does not answer, so with a hung
+  probe a decision can wait up to 60 s per check before it is UNVERIFIED.
+
 ## 0.1.0-alpha.12 — 2026-10-19
 
 Bench numbers below are from one 800-file project on macOS arm64, Node 22.13.0.

package/README.md

@@ -37,7 +37,7 @@ it; relevant source edits make it stale. [Run the reproducible demo](docs/contri
 
 ## Install the alpha
 
-The opt-in pilot uses **0.1.0-alpha.12**. Follow the
+The opt-in pilot uses **0.1.0-alpha.14**. Follow the
 [fixed-version pilot guide](docs/user/pilot.md) for supported projects, setup,
 updates and voluntary feedback. No external usage results are claimed yet.
 
@@ -96,9 +96,67 @@ Setup is explicit, reversible, and does not change tool permissions or run check
 
 The experimental claim is **opt-in project-local agent activation and direct TypeScript
 evidence, with fresh-session reuse demonstrated in the tested Codex/macOS
-configuration**. Claude setup/removal mechanics are tested; Claude behavior and
-cross-host reuse are not. This is experimental guidance, not guaranteed agent
-compliance, general sandbox compatibility, or a promise of time savings.
+configuration and measured for Claude Code below**. Cross-host reuse is not
+tested. This is experimental guidance, not guaranteed agent compliance, general
+sandbox compatibility, or a promise of time savings.
+
+### Measured with Claude Code
+
+Four public TypeScript projects, four tasks each, three sessions per task with
+and without REDUE: 96 headless Claude Code sessions (Sonnet 5.5, CI Linux
+runner, alpha.12 code, October 2026). Plain `tsc --noEmit` takes 10–19 s on
+these projects. Medians per task, summed over the four projects:
+
+| Task | Session time, without → with REDUE | Input tokens | Typechecks skipped |
+|---|---|---|---|
+| Docs edit, then "make sure it still typechecks" | 97 → 45 s | 169k → 162k | 12 of 12 |
+| "Does it still typecheck?" after a pull | 74 → 22 s | 117k → 89k | 12 of 12 |
+| Source change, typecheck, then a docs edit | 141 → 112 s | 210k → 200k | 9 of 12 |
+| Source change with tests | 152 → 151 s | 269k → 234k | 0 of 12 |
+| **All tasks** | **464 → 330 s** | **765k → 685k** | 33 |
+
+- **Correctness:** every typecheck REDUE skipped was checked afterwards with
+  plain tsc on the exact tree it was skipped on. All 33 agreed, and all 96
+  final trees passed plain tsc and the task checks in both arms.
+- **Cost:** API cost was the same ($0.65 without, $0.66 with). One-time setup
+  per checkout was 3–5 s, plus one recorded typecheck; the CLAUDE.md section
+  REDUE adds is about 60 tokens.
+- **How:** each session gets a fresh clone at a pinned commit; the REDUE arm
+  first runs `redue init`, `agent setup claude`, `start` and one
+  `redue run typecheck`, standing for an earlier session's passing check.
+  The harness, tasks and raw results are in [`eval/`](eval/README.md).
+- **Limits:** four projects and three runs per cell show direction, not a
+  general rate. Savings come only when an earlier pass still applies: tasks
+  that change source code save nothing, and on one project the docs edit came
+  after source edits that made the result STALE, so nothing was skipped. The
+  projects were chosen because they qualify for the direct TypeScript recipe;
+  of 38 screened projects, 19 qualified at alpha.12 and 22 at alpha.13. Times are agent session
+  time only, on one runner type.
+
+### Unit tests, measured with Claude Code
+
+Three public projects (cheerio with Vitest 4, SwitchHosts with Vitest 5, twilio
+with Jest 29), four tasks each, three sessions per task with and without REDUE:
+72 headless Claude Code sessions (Sonnet 5.5, CI Linux runner, alpha.14 code,
+October 2026), using the opt-in [direct test recipe](docs/user/tests-direct.md).
+Medians per task, summed over the three projects:
+
+| Task | Session time, without → with REDUE | Input tokens | Test runs skipped |
+|---|---|---|---|
+| Docs edit, then "make sure the unit tests still pass" | 95 → 41 s | 131k → 121k | 9 of 9 |
+| "Do the unit tests still pass?" after a pull | 80 → 22 s | 62k → 63k | 9 of 9 |
+| Source change, tests, then a docs edit | 171 → 111 s | 224k → 213k | 3 of 9 |
+| Source change with tests | 169 → 120 s | 172k → 164k | 0 of 9 |
+| **All tasks** | **515 → 295 s** | **589k → 559k** | 21 |
+
+- **Correctness:** every skipped test run was rerun plainly three times on the
+  exact tree it was skipped on; all 21 passed every time. All 72 final trees
+  passed the tests and the task checks in both arms.
+- **Limits:** one run of three projects shows direction, not a rate. The
+  source-change task skipped nothing; its time difference is session variance.
+  In two mixed-task sessions the agent left out its final test run on its own
+  after a README-only edit, without asking REDUE, and said so; the eval report
+  lists such sessions. Cost was the same ($0.54 without, $0.56 with).
 
 ## What the states mean
 
@@ -123,7 +181,9 @@ has been verified.
   [direct local compiler recipe](docs/user/direct-typescript.md) for the reviewed
   npm/TypeScript boundary. Workspace
   boundaries follow the files actually consumed, including built declarations.
-- Existing test/lint/build and arbitrary commands can record results while
+- Opt-in [direct test recipe](docs/user/tests-direct.md) for Vitest 4/5 and
+  Jest 29 in single-package npm projects on macOS and Linux.
+- Other test/lint/build and arbitrary commands can record results while
   their applicability remains unqualified.
 
 The [supported-project boundary](docs/user/supported-projects.md) is deliberately

package/bin/redue.mjs

@@ -4,6 +4,7 @@ import {mark,traceBase,traceContext,traceEnvironment,traceId} from '../src/decis
 traceBase({...traceContext(),request:traceId(),work:'client'});
 mark('client.loaded');
 import {directCompiler,directQualification,directEnvironment,directInterpretation} from '../src/direct-typescript.mjs';
+import {testEnvironment,testRunnerEntry,testsInterpretation,testsQualification} from '../src/test-direct.mjs';
 import os from 'node:os';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
@@ -25,7 +26,7 @@ const help=`REDUE ${version}
 Usage: redue [--config FILE] [--state-dir DIR] COMMAND [OPTIONS]
 
 Commands:
-  init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct]
+  init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct]
                        Discover existing scripts; optionally select one workspace/check
   agent setup codex|claude [--dry-run|--apply] [--json]
   agent doctor [codex|claude] [--json]
@@ -128,7 +129,8 @@ if(command==='init'){
       console.log(`  ${row.name} (${row.script||row.command?.join(' ')}) — `+
         `${{ready:'ready to qualify',recording:'recording-only',unsupported:'unsupported'}[row.level]||row.level}: ${row.reason}`);
       if(row.script&&row.command)console.log(`    Recorded invocation: ${row.command.map(value=>
-        value==='@node'?'node':value==='@typescript-compiler:.'?'[reviewed local TypeScript compiler implementation]':value.startsWith('@typescript-bin:')?
+        value==='@node'?'node':value==='@typescript-compiler:.'?'[reviewed local TypeScript compiler implementation]':
+          value.startsWith('@test-runner:')?`[local ${value.slice('@test-runner:'.length)}]`:value.startsWith('@typescript-bin:')?
           `[installed TypeScript in ${value.slice('@typescript-bin:'.length)}]`:value).join(' ')}`);
     }
     for(const row of summary.ambiguous)
@@ -198,6 +200,11 @@ function token(value){
   if(value==='@typescript-compiler:.'){
     try{return directCompiler(root,{verify:false}).entry;}catch(e){error(`direct compiler unavailable: ${e.code||e.message}`);}
   }
+  if(value.startsWith('@test-runner:')){
+    // Qualification reports a missing runner; status and stop still work.
+    try{return testRunnerEntry(root,value.slice('@test-runner:'.length));}
+    catch{return path.join(root,'node_modules',value.slice('@test-runner:'.length),'<unavailable>');}
+  }
   if(value==='@vstate/direct-typescript-probe')return path.join(productRoot,'src','direct-typescript-probe.mjs');
   if(value.startsWith('@typescript-bin:')){
     const dir=value.slice('@typescript-bin:'.length);
@@ -237,7 +244,8 @@ const checks=publicConfig.checks.map(check=>{
     error(`${check.name}: reviewed coverage ${category} needs a rationale`);
   const npmDirect=check.qualification===directQualification;
   const pnpmTypecheck=check.qualification==='pnpm-tsc-v1';
-  if(check.script&&check.command&&!pnpmTypecheck&&!npmDirect)
+  const testsDirect=check.qualification===testsQualification;
+  if(check.script&&check.command&&!pnpmTypecheck&&!npmDirect&&!testsDirect)
     error(`${check.name}: choose script or command, not both`);
   const manager=publicConfig.packageManager;
   if(check.script&&!['npm','yarn','pnpm'].includes(manager))
@@ -246,11 +254,15 @@ const checks=publicConfig.checks.map(check=>{
     [`@which:${manager}`,'run',check.script]:null;
   const npmAutomatic=check.qualification==='typescript-noemit-v1';
   const yarnWorkspace=check.qualification==='yarn-workspace-tsc-v1';
-  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck)
+  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck&&!testsDirect)
     error(`${check.name}: unknown qualification contract`);
   if(npmDirect&&(manager!=='npm'||!check.script||check.cwd&&check.cwd!=='.'||
     JSON.stringify(check.command)!==JSON.stringify(['@node','@typescript-compiler:.','--noEmit'])))
     error(`${check.name}: direct recipe requires its explicit local compiler command`);
+  // The script's own arguments follow the runner; qualification compares them with the script.
+  if(testsDirect&&(manager!=='npm'||!check.script||check.cwd&&check.cwd!=='.'||!Array.isArray(check.command)||
+    check.command[0]!=='@node'||!/^@test-runner:(?:vitest|jest)$/.test(check.command[1]||'')))
+    error(`${check.name}: test recipe requires its explicit local test runner command`);
   if(npmAutomatic&&(manager!=='npm'||check.cwd&&check.cwd!=='.'))
     error(`${check.name}: automatic TypeScript qualification currently needs root npm script`);
   if(yarnWorkspace&&(manager!=='yarn'||!check.workspace||check.cwd&&check.cwd!=='.'||
@@ -276,7 +288,7 @@ const checks=publicConfig.checks.map(check=>{
       check.workspace||'.',check.script]]:[];
   const windowsContext=process.platform==='win32'?
     ['ComSpec','COMSPEC','PATHEXT','USERPROFILE']:[];
-  const autoEnvironment=npmDirect?directEnvironment:npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
+  const autoEnvironment=npmDirect?directEnvironment:testsDirect?testEnvironment:npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
     'NODE_ENV','BASH_ENV','ENV',...windowsContext],prefixes:['npm_config_','DYLD_','TSGO_'],
     pathExecutables:['node','npm'],executableIdentity:true}:yarnWorkspace?
     {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
@@ -288,7 +300,7 @@ const checks=publicConfig.checks.map(check=>{
   return {name:check.name,command:argv(scriptCommand||check.command,`${check.name}.command`),
     cwd:check.cwd,inputs:check.inputs||[],generatedInputs:check.generatedInputs||[],
     installedInputs:check.installedInputs||(
-      npmAutomatic||npmDirect?['node_modules/**']:[]),
+      npmAutomatic||npmDirect||testsDirect?['node_modules/**']:[]),
     allowedExternalRoots:check.allowedExternalRoots||[],
     probes:[...(check.probes||[]),...autoProbes]
       .map((p,i)=>argv(p,`${check.name}.probes[${i}]`)),
@@ -299,6 +311,7 @@ const checks=publicConfig.checks.map(check=>{
     qualification:check.qualification||null,script:check.script||null,
     ...(npmAutomatic?{qualificationInterpretation:'npm-launcher-withheld@1'}:{}),
     ...(npmDirect?{qualificationInterpretation:directInterpretation}:{}),
+    ...(testsDirect?{qualificationInterpretation:testsInterpretation}:{}),
     workspace:check.workspace||null,kind:check.kind||null};
 });
 const runtime={schema:1,provider:'declared-project@1',root,state,checks};

package/docs/user/json.md

@@ -31,6 +31,7 @@ Stable-enough-for-alpha fields:
 | `freshness` | `CURRENT`, `STALE`, or `UNVERIFIED`, independent of result. |
 | `reuse_eligible` | True only for qualified, applicable passing evidence. Never derive permission to reuse from outcome alone. Missing means false. |
 | `run_facts` | Number of lookups outside the discovery certificate that the receipt's run made (direct TypeScript recipe). Status asks each again before answering CURRENT. Absent when there are none. |
+| `probe_deadline_ms` | Top level. How long the full state probes of one decision may take in total: each check's deadline (5 s to 60 s, from earlier probes and runs) times its probe count, summed. Callers wait at least this long plus 10 s for a synchronized answer. |
 | `reason` | Human explanation; not a stable machine enum. Do not parse it to authorize reuse. |
 | `changed_inputs` | Known changed relevant paths when available, possibly only the first difference; empty/missing is not proof of no changes. |
 | `invocation` | Null without a receipt; otherwise run ID, completion `status`, duration, exit code/signal when known. Status distinguishes exited, interrupted, and start/capture failure. |

package/docs/user/pilot.md

@@ -1,4 +1,4 @@
-# Opt-in development pilot: alpha.12
+# Opt-in development pilot: alpha.14
 
 Use one fixed build for several ordinary development sessions. The owner will
 invite two or three willing testers and approve their projects; nothing is
@@ -35,7 +35,7 @@ are **NOT RUN**. The recording shortcut is macOS/direct-recipe only.
 For a new default npm installation:
 
 ```sh
-npm install --global @redue/cli@0.1.0-alpha.12
+npm install --global @redue/cli@0.1.0-alpha.14
 redue --version
 cd my-project
 redue --config redue.config.json init --recipe typescript-direct --check typecheck --dry-run
@@ -89,7 +89,7 @@ using it; keep the same npm prefix, config and any explicit state selection.
 
 ```sh
 redue --config redue.config.json stop
-npm install --global @redue/cli@0.1.0-alpha.12
+npm install --global @redue/cli@0.1.0-alpha.14
 redue --config redue.config.json agent setup codex --dry-run
 redue --config redue.config.json agent setup codex --apply
 redue --config redue.config.json start

package/docs/user/supported-projects.md

@@ -38,7 +38,10 @@ only its source does not stale the selected check until the consumed output
 changes. Unsupported custom resolution, project references, outside-root
 source links, and installation modes remain recording-only. Other Yarn
 typechecks, Vitest/Jest, ESLint, and builds start recording-only unless a
-separately justified explicit contract is provided.
+separately justified explicit contract is provided. For a single-package npm
+project whose test script runs Vitest 4/5 or Jest 29 directly, the opt-in
+`init --recipe tests-direct` records the run and guards its inputs; see
+[direct tests](tests-direct.md).
 In particular, test caches and build-generated inputs are not excluded to
 make evidence green.
 

package/docs/user/tests-direct.md

@@ -0,0 +1,106 @@
+# Direct test recipe (Vitest and Jest)
+
+`redue init --recipe tests-direct --check test` records a project's unit test
+run and reports later whether that result still applies to the files you have.
+It supports a single-package npm project whose test script runs Vitest 4 or 5,
+or Jest 29, directly. It runs on macOS and Linux with Node 22 or 24.
+
+## Setup
+
+```sh
+redue init --recipe tests-direct --check test
+redue start
+redue run test
+redue status --sync
+```
+
+`init` picks the `test`, `test:unit` or `test:check` script when it runs a
+runner directly, otherwise the only script that does. The script must be one
+runner invocation: no `&&`, quotes, globs or variable assignments. Watch mode,
+`--changed`, `related`, snapshot updates (`-u`), shuffling, sharding and
+Jest's `--onlyChanged` are refused. Vitest needs `run`, `--run` or
+`--watch=false`. Other scripts stay recording-only.
+
+REDUE runs the local runner with Node directly. npm, its lifecycle scripts and
+`package.json` are not changed or executed.
+
+## What REDUE claims
+
+CURRENT means the last run's inputs are unchanged: every file in the checkout
+outside `node_modules`, the installed files in `node_modules`, the Node binary,
+the exact command, and the environment. Every environment variable the run's
+JavaScript read directly must have the same value, or still be unset. Node and
+libc read some variables natively, and Vite lists the environment for its own,
+so these are always compared: `TZ`, `LANG` and every `NODE_*`, `LC_*`,
+`VITE_*`, `DYLD_*` and `LD_*` variable. Display-only variables are not
+compared: `_`, `TERM`, `TERM_PROGRAM`, `COLORTERM`, `FORCE_COLOR`, `NO_COLOR`,
+`FORCE_TTY`, `COLUMNS`, `LINES` and `AI_AGENT`.
+It does not mean a rerun would give the same result. A test that depends on the
+time of day or on randomness can pass now and fail later on the same inputs.
+
+The default config excludes `**/*.md`, `**/*.mdx` and, with `--coverage`,
+`coverage/**`. Editing those files keeps a result CURRENT unless the run read
+them. A run may create git-ignored files (for example under `test/tmp`) and
+read back what it wrote, in the same process or inside a directory it created:
+when every change during the run is such an output, the result keeps the files
+as the run left them.
+
+## The guard
+
+Every Node process and worker thread of the run loads a recorder
+(`src/test-recorder.cjs`). After the run REDUE checks the record. The result is
+kept but marked UNVERIFIED, with the reason, when the run:
+
+- read a file that the config excludes, or a git-ignored file REDUE does not
+  observe, that the run did not create first;
+- changed an input during the run, or read a git-ignored output an earlier
+  run left before writing it again: the result depends on that leftover;
+- listed a directory, or read a file over 1 MB, outside the checkout, other
+  than files and directories the run created, Jest's cache directory and the
+  runners' data directories (Vitest's `vitest` folder in the user data
+  directory);
+- connected to anything other than loopback or a local socket, or asked DNS
+  about a name other than localhost;
+- started a process that did not load the recorder: a shell, a binary, or a
+  Node process with its own environment;
+
+Lookups that can be asked again become run facts, checked before every CURRENT
+answer: whether a path outside the checkout exists, where a link resolves, the
+content of each smaller file read outside it (Linux native bindings read
+`/proc/version` and `/usr/bin/ldd` to pick their C library), and
+the existence and listings of excluded or ignored files in the checkout.
+
+When two runs on the same inputs and environment give different results, the
+check is UNVERIFIED until the inputs change.
+
+A `--coverage` run may read back the default `coverage/` report: Jest reads
+every JavaScript file under its roots, an earlier report's included, only to
+map dependencies, and that does not decide pass or fail. This is not allowed
+when the configuration names coverage thresholds, which make the report decide
+the result, or another report directory. Configuration can be code, so REDUE
+looks for `coverageThreshold`, `thresholds`, `coverageDirectory` and
+`reportsDirectory` in `package.json`'s `jest` field and the runner's config
+files; when one appears, reading an old report is UNVERIFIED.
+
+## Known causes of UNVERIFIED
+
+Tests that write files git does not ignore change the run's inputs.
+
+## Limits
+
+- Runner caches and data are trusted: `node_modules/.vite`,
+  `node_modules/.vite-temp`, `node_modules/.vitest`, Vitest's typecheck build
+  info in `node_modules/vitest/dist`, Jest's cache directory and Vitest's user
+  data directory are not inputs.
+- Code that copies the environment and reads the copy, and native code that
+  reads files, environment variables or the network, is not seen.
+- Metadata of excluded files (size, times) is not compared, only their
+  existence.
+- A file the run creates and another process reads is the run's output only
+  when it is inside a directory the run created.
+- Outputs a run keeps are part of the result's inputs afterwards. Deleting
+  them, or an observer restart that reindexes without them (git-ignored files
+  are not indexed at start), makes the result STALE.
+- A config written by an earlier build of this recipe is UNVERIFIED with "run
+  redue init again"; move `redue.config.json` aside and run init.
+- Windows is not supported; the check stays recording-only there.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.14",
   "publishConfig": {
     "access": "public",
     "tag": "alpha"

package/src/agent-integration.mjs

@@ -88,20 +88,27 @@ function saved(root,host){const text=read(root,marker(host));if(text===null)retu
   return value;
 }
 // The managed block is always in the agent's context, so it stays short. For
-// Claude Code it names the typecheck command the hook matches and what a skip
-// means. The hook does the rest, so the block does not point to the skill;
-// the skill stays for agents that look for it.
-function blockFor(host,forms=[]){return `\n\n<!-- REDUE:${host}:begin -->\n`+
-  (forms.length?`Typecheck with ${forms.map(form=>`\`${form}\``).join(' and ')}. If its last pass still applies to\n`+
+// Claude Code it names the typecheck and test commands the hook matches and
+// what a skip means. The hook does the rest, so the block does not point to
+// the skill; the skill stays for agents that look for it. A typecheck-only
+// block keeps its earlier wording.
+const quoted=forms=>forms.map(form=>`\`${form}\``).join(' and ');
+function blockFor(host,rows=[]){
+  const typechecks=rows.filter(row=>row.kind!=='test').map(row=>row.form),tests=rows.filter(row=>row.kind==='test').map(row=>row.form);
+  return `\n\n<!-- REDUE:${host}:begin -->\n`+
+  (!rows.length?`Before you run, skip or report a typecheck or other configured check, read\n`+
+    `${hosts[host].skill}.\n`:!tests.length?`Typecheck with ${quoted(typechecks)}. If its last pass still applies to\n`+
     `these exact files, a REDUE hook skips the run and says so. The skip counts as\n`+
     `a pass; don't check it again.\n`:
-    `Before you run, skip or report a typecheck or other configured check, read\n`+
-    `${hosts[host].skill}.\n`)+
+    (typechecks.length?`Typecheck with ${quoted(typechecks)}.\n`:'')+
+    `Run the unit tests with ${quoted(tests)}.\n`+
+    `If a check's last pass still applies to these exact files, a REDUE hook skips\n`+
+    `the run and says so. The skip counts as a pass; don't check it again.\n`)+
   `<!-- REDUE:${host}:end -->\n`;}
-// One form per typecheck: the npm script when there is one, since that is what
+// One form per check: the npm script when there is one, since that is what
 // the project's own instructions usually name.
-const blockForms=(host,config,relative)=>host!=='claude'?[]:hookForms(config,relative).map(row=>
-  row.forms.find(form=>form.startsWith('npm run '))??row.forms.find(form=>!form.startsWith('redue '))??row.forms[0]);
+const blockForms=(host,config,relative)=>host!=='claude'?[]:hookForms(config,relative).map(row=>({kind:row.kind,
+  form:row.forms.find(form=>form.startsWith('npm run '))??row.forms.find(form=>!form.startsWith('redue '))??row.forms[0]}));
 const priorBlocks=(host,relative)=>[false,true].map(legacy=>`\n\n<!-- REDUE:${host}:begin -->\n`+
   `Before deciding whether configured verification needs repeating, use REDUE.\n`+
   (legacy?`Read ${hosts[host].skill} for the decision policy, then query ordinary status\n`+
@@ -120,9 +127,11 @@ const priorBlocks=(host,relative)=>[false,true].map(legacy=>`\n\n<!-- REDUE:${ho
 // varies, and only in the safe character set. Earlier owned versions are
 // recognized so setup can replace them; other stored text never is.
 function knownBlock(host,relative,block){
-  const named=/^\n\n<!-- REDUE:[a-z]+:begin -->\nTypecheck with ((?:`[A-Za-z0-9_./:=,+ -]+`(?: and )?)+)\. /.exec(block);
-  const forms=named?[...named[1].matchAll(/`([^`]+)`/g)].map(m=>m[1]):[];
-  return block===blockFor(host,forms)||priorBlocks(host,relative).includes(block);
+  const list='((?:`[A-Za-z0-9_./:=,+ -]+`(?: and )?)+)';
+  const forms=pattern=>{const named=new RegExp(pattern).exec(block);return named?[...named[1].matchAll(/`([^`]+)`/g)].map(m=>m[1]):[];};
+  const rows=[...forms(`^\\n\\n<!-- REDUE:[a-z]+:begin -->\\nTypecheck with ${list}\\.`).map(form=>({kind:'typecheck',form})),
+    ...forms(`Run the unit tests with ${list}\\.\\n`).map(form=>({kind:'test',form}))];
+  return block===blockFor(host,rows)||priorBlocks(host,relative).includes(block);
 }
 // The policy with the exact commands for this config, so an agent never builds
 // a --config form the hook would not recognize. Claude Code gets the typecheck
@@ -131,7 +140,9 @@ function skillFor(relative,host,config){
   // Double quotes work in POSIX shells, cmd and PowerShell for ordinary names.
   const redue=redueFor(relative)??`redue --config ${JSON.stringify(relative)}`,status=`${redue} status --sync --json`;
   const rows=host==='claude'?hookForms(config,relative):[];
-  const commands=rows.map(row=>`- ${row.check==='typecheck'?'Typecheck':`Typecheck \`${row.check}\``}: `+
+  const label=row=>row.kind==='test'?(row.check==='test'?'Unit tests':`Unit tests \`${row.check}\``):
+    row.check==='typecheck'?'Typecheck':`Typecheck \`${row.check}\``;
+  const commands=rows.map(row=>`- ${label(row)}: `+
     `${row.forms.map(form=>`\`${form}\``).join(' or ')}.\n`).join('')+
     (rows.length?`  If the last pass still applies to these exact files, a hook skips the run\n`+
       `  and says so. That counts as a pass; don't confirm it with status. Otherwise\n`+
@@ -145,7 +156,7 @@ function skillFor(relative,host,config){
   // typecheck needs only the CLAUDE.md block, so the description must not
   // send the agent here for one.
   const description=rows.length?'Rules and exact commands for redue status, redue run and other redue commands. '+
-    'A plain typecheck needs only the REDUE section of CLAUDE.md.':
+    `A plain ${rows.some(row=>row.kind==='test')?'typecheck or test run':'typecheck'} needs only the REDUE section of CLAUDE.md.`:
     'Use before running, skipping or reporting a typecheck or other configured check.';
   // Replacer functions, so `$` in a config name is never a replacement pattern.
   return policy.replace('{{DESCRIPTION}}',()=>description).replace('{{CONFIG}}',()=>JSON.stringify(relative)).replace('{{COMMANDS}}',()=>commands.trimEnd())
@@ -241,7 +252,7 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
       {path:h.instruction,before,after});
     if(host==='claude'){const settings=read(root,settingsPath);
       changes.push({path:settingsPath,before:settings,after:settingsWith(settings,hook),
-        content:hook?JSON.stringify(hook,null,2):'remove the REDUE PreToolUse hook (no typecheck check to match)'});}
+        content:hook?JSON.stringify(hook,null,2):'remove the REDUE PreToolUse hook (no typecheck or test check to match)'});}
     changes.push({path:marker(host),before:read(root,marker(host)),after:JSON.stringify(next,null,2)+'\n'});
   }else if(record){
     const before=read(root,h.instruction),after=before.replace(record.block,'');

package/src/claude-hook.mjs

@@ -1,5 +1,5 @@
-// Claude Code PreToolUse hook: skip an exact typecheck rerun when REDUE reports
-// CURRENT/PASS with reuse_eligible on the current inputs. When the check is not
+// Claude Code PreToolUse hook: skip an exact typecheck or test rerun when REDUE
+// reports CURRENT/PASS with reuse_eligible on the current inputs. When the check is not
 // CURRENT, the command becomes `redue run <check>` so the run is recorded. Every
 // other outcome, including errors and timeouts, allows the command unchanged.
 // Never exit 2: Claude Code treats exit 2 as a block.
@@ -12,28 +12,38 @@ import {realObservedPath} from './path-identity.mjs';
 export const hookCommand='redue agent hook claude';
 const safe=/^[A-Za-z0-9_./:=,+-]+$/;
 const typecheck=check=>check?.kind==='typecheck'||check?.name==='typecheck';
+// A direct test check: its command is the runner and the script's arguments.
+const tests=check=>check?.qualification==='npm-tests-direct-v1'&&Array.isArray(check.command)&&
+  /^@test-runner:(?:vitest|jest)$/.test(check.command[1]||'');
+export const checkKind=check=>tests(check)?'test':'typecheck';
 
 export const defaultConfig='redue.config.json';
 // The `redue` prefix for a config beside the project root; null when the name
 // would need shell quoting.
 export const redueFor=(configFile=defaultConfig)=>configFile===defaultConfig?'redue':
   safe.test(configFile)?`redue --config ${configFile}`:null;
-// Exact commands that rerun each configured typecheck. Names that would need
-// shell quoting get no form, so the hook never fires for them.
+// Exact commands that rerun each configured typecheck or direct test check.
+// Names that would need shell quoting get no form, so the hook never fires for them.
 export function hookForms(config,configFile=defaultConfig){
   const rows=[],redue=redueFor(configFile);
   for(const check of config?.checks||[]){
-    if(!typecheck(check)||typeof check.name!=='string'||!safe.test(check.name))continue;
+    if(!(typecheck(check)||tests(check))||typeof check.name!=='string'||!safe.test(check.name))continue;
     const forms=redue?[`${redue} run ${check.name}`]:[];
     // Other forms run from the project root, so they match only a root check.
     if(check.cwd!==undefined&&check.cwd!=='.'){if(forms.length)rows.push({check:check.name,forms});continue;}
     if(config.packageManager==='npm'&&typeof check.script==='string'&&safe.test(check.script))
       forms.push(`npm run ${check.script}`);
     if(check.qualification==='npm-typescript-direct-v1')forms.push('npx tsc --noEmit');
-    if(Array.isArray(check.command)&&check.command.length&&
+    if(!tests(check)&&Array.isArray(check.command)&&check.command.length&&
       check.command.every(v=>typeof v==='string'&&safe.test(v)&&!v.startsWith('@')))
       forms.push(check.command.join(' '));
-    if(forms.length)rows.push({check:check.name,forms:[...new Set(forms)]});
+    // The script's own text, which runs the same runner with the same arguments.
+    if(tests(check)){
+      if(check.script==='test'&&config.packageManager==='npm')forms.push('npm test');
+      const text=[check.command[1].slice('@test-runner:'.length),...check.command.slice(2)];
+      if(text.every(v=>typeof v==='string'&&safe.test(v)))forms.push(text.join(' '),`npx ${text.join(' ')}`);
+    }
+    if(forms.length)rows.push({check:check.name,kind:checkKind(check),forms:[...new Set(forms)]});
   }
   return rows;
 }