@redue/cli 0.1.0-alpha.11 → 0.1.0-alpha.13

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 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.
+Released alpha.11 and this build ran interleaved on the same machine; the
+decision path is unchanged within noise (warm `status --sync` 183/410 ms on
+alpha.11, 298/174 ms on alpha.12; states correct, no idle probe launches).
+On a screen of 38 public TypeScript projects in CI, 10 qualified for the
+direct recipe before the run-facts change, 17 after it and 19 after incremental
+and references support. worldmonitor and Recordly now stop at the 5 s probe
+timeout, and open-cowork at its end-checkpoint probe.
+
+- Large installations reach ready quickly. Installed files are observed by
+  identity (inode, size, mode, link count, times), not by hashing their contents;
+  the compiler's own reads stay content-checked by the probe. On macOS:
+  Recordly (75k files in `node_modules`) ready in 7 s instead of failing after
+  120 s; worldmonitor (143k) in 30 s instead of not ready after 15 min.
+  Behavior change: reinstalling identical packages, restoring an installed
+  file's bytes or copying the installation now makes the check STALE once.
+- The direct TypeScript recipe supports TypeScript 6.0.2 and 6.0.3.
+- Claude Code: the typecheck hook also matches a typecheck that starts a `;` or
+  `&&` chain. When it skips one, the message names the rest of the chain. The
+  skill lists the exact commands the hook matches for the selected config.
+- Shorter agent instructions: the CLAUDE.md block is 235 bytes instead of 739,
+  the skill 1.8 KB instead of 5 KB. The reuse rules are unchanged. When the
+  Claude Code hook matches a typecheck, the block no longer points to the
+  skill; the skill stays for agents that look for it.
+- Claude Code hook: it waits for status up to half the last completed run's
+  duration, at most 10 s, instead of a fixed 2 s. Run `redue agent setup claude
+  --apply` again to raise the hook's Claude Code timeout from 5 s to 15 s.
+- Linux: the observer no longer watches `.git` directories. Before, each new
+  directory git created there (on most commits) was an observation gap: status
+  was UNVERIFIED until a full reindex and probe finished, about 5 s on a
+  26k-file project. Input patterns that name a `.git` directory are now
+  refused; REDUE never observed changes there.
+- Direct TypeScript recipe: runs with `declaration: true` are reusable. tsc's
+  declaration checks look up files that building the program does not, and
+  read dependencies' `package.json`; before, any such lookup made the run
+  UNVERIFIED. The receipt now keeps those existence, `realpath` and
+  `package.json` answers as run facts, and status asks them again before every
+  CURRENT answer, including when a cached status is read. Every direct run is
+  now recorded, also one checked by full probes. The probe also records
+  `realpath` while it parses a tsconfig `extends` from a package.
+  Behavior change: a direct receipt recorded by an earlier version is
+  UNVERIFIED until the check runs again (macOS and Linux). Limit: Windows does
+  not record direct runs, so declaration-only lookups are not checked there.
+- Direct TypeScript recipe: a root tsconfig with `incremental: true` is
+  supported. Its build-info file is left out of the inputs, and the run may
+  write only that file. A root tsconfig that references a composite config
+  (such as Vite's `tsconfig.node.json`) is supported when the program does not
+  use the referenced project's files. A `composite` root is still refused.
+- Releases are published to the `latest` npm tag as well as `alpha`, so
+  `npm install -g @redue/cli` installs the newest release.
+
 ## 0.1.0-alpha.11 — 2026-10-18
 
 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.11**. Follow the
+The opt-in pilot uses **0.1.0-alpha.13**. 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,42 @@ 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.
 
 ## What the states mean
 

package/docs/user/agents.md

@@ -83,20 +83,30 @@ The hook skips an exact rerun of a configured typecheck: a check with
 `kind: "typecheck"` or named `typecheck`. It matches these commands, run from the
 project root:
 
-- `redue run CHECK`
+- `redue run CHECK`, or `redue --config FILE run CHECK` when the config is not
+  `redue.config.json`
 - `npm run SCRIPT`, when the check has an npm script
 - `npx tsc --noEmit`, for the direct-TypeScript recipe
 - the check's `command`, when it has no `@` tokens
 
 Each form may end with `2>&1` and then one `| tail -n N`, `| head -n N`,
-`| tail -N` or `| head -N`. Nothing else matches. Each form has its own `if`
-rule, so other Bash commands never start the hook.
-
-On a match, the hook runs `redue status --sync --json` with a 2-second timeout.
+`| tail -N` or `| head -N`. It may also be the first command of a `;` or `&&`
+chain. Nothing else matches. Each form has its own `if` rule, so other Bash
+commands never start the hook. The installed skill lists these exact commands,
+so the agent uses forms the hook recognizes.
+
+On a match, the hook runs `redue status --sync --json`. It waits up to half the
+duration of the check's last completed run, at most 10 seconds, so waiting never
+costs more than half a run. With no completed run it waits 2 seconds. A check
+that takes a few hundred milliseconds is therefore rarely skipped; skipping it
+would save almost nothing, and the hook does not rewrite it to `redue run`
+either. Claude Code's own limit for the hook is 15 seconds.
 It blocks the command only when the check is CURRENT, PASS and
 `reuse_eligible: true`. The message names the check and the receipt's run ID. Every
 other result allows the command: STALE, UNVERIFIED, FAILED, a timeout, an error, or
-a missing `redue`. A command that starts with `REDUE_FORCE=1` always runs.
+a missing `redue`. A command that starts with `REDUE_FORCE=1` always runs. A
+blocked chain runs none of its commands; the message names the rest of the chain
+so the agent can run it on its own.
 
 When the check is not CURRENT but the observer answered for it, the hook rewrites
 the command to `redue run CHECK` and allows it, keeping any `2>&1` and
@@ -104,13 +114,17 @@ the command to `redue run CHECK` and allows it, keeping any `2>&1` and
 `redue.config.json`. The run is recorded, so the next identical command can be
 skipped. Without a healthy answer (timeout, error, no observer) the command runs
 as typed. Claude Code still applies deny and ask rules to the rewritten command.
+A chain is never rewritten: the rewrite is allowed without a prompt, and that
+would also skip the prompt for the rest of the chain.
 
 Limits:
 
 - The hook judges its own environment, which Claude Code passes to it. The Bash
   tool can add variables from your shell profile. The hook cannot see those.
-- Commands run from a subdirectory, or combined with `&&`, `;` or other pipes,
-  are not matched.
+- Commands run from a subdirectory, after another command (`cd x && tsc`), or
+  combined with `||`, `&` or other pipes, are not matched.
+- A skip writes nothing. If a typecheck command also emits files, later
+  commands see the files from its last run.
 - Only the Bash tool is covered, not PowerShell.
 - Run setup again after you rename a check or script.
 - The rewrite is allowed without a permission prompt, even where the original
@@ -152,10 +166,13 @@ historical evidence, but setup may make them STALE or UNVERIFIED. Reassess norma
 and run required checks; an upgrade is not a promise that existing receipts remain
 CURRENT. Do not suppress that invalidation or reset state.
 
-Codex gets a short managed section in project `AGENTS.md` and
-`.agents/skills/redue-verification/SKILL.md`. Claude Code gets a managed section
-in `CLAUDE.md` and `.claude/skills/redue-verification/SKILL.md`. Each uses the same
-policy source; detailed guidance is loaded when verification is relevant. Small
+Codex gets a short managed section in project `AGENTS.md` that points to
+`.agents/skills/redue-verification/SKILL.md`. Claude Code gets one in `CLAUDE.md`
+that names the typecheck command the hook matches and says what a skip means,
+plus `.claude/skills/redue-verification/SKILL.md`. The skill holds the reuse
+rules and the exact commands for the selected config. When the hook matches a
+typecheck, the `CLAUDE.md` section does not point to the skill: the hook does
+the work, and the skill is there for agents that look for it. Small
 ownership records in `.redue/agents/` support safe updates/removal. These are
 portable project files, not receipts; review and commit them if the team wants
 this integration. Do not ignore just the ownership records while committing the
@@ -238,8 +255,8 @@ instruction file containing user content.
 
 Commands from nested directories search toward the nearest Git root. If more than
 one configuration applies, select one with `--config FILE`; REDUE refuses to guess.
-The generated instruction names its project-relative configuration and applies it
-to status/run/explain. External configs or custom machine-local `--state-dir`
+The generated skill names its project-relative configuration and gives the exact
+status and run commands for it. External configs or custom machine-local `--state-dir`
 setups should use a reviewed generic instruction instead of committing absolute
 paths. Other worktrees and remote containers have separate local evidence.
 

package/docs/user/configuration.md

@@ -56,5 +56,22 @@ Advanced explicit contracts may declare `generatedInputs`, `installedInputs`, na
 reviewed escape hatches, not onboarding requirements. A coverage rationale cannot
 override unsupported storage, unresolved links, missing inputs, or observation failure.
 
+Input patterns are relative to the project root. They cannot name a `.git`
+directory, because REDUE does not observe one; `!.git/**` is fine.
+
 Changing commands, relevant configuration, installed material, or consumed inputs
 invalidates prior applicability. It does not erase historical execution outcomes.
+
+Installed inputs (under `node_modules` or other installed roots) are observed by
+file identity: inode, size, mode, link count, and modification and change times.
+REDUE does not read every installed file, so large installations become ready
+quickly. Any write to an installed file makes dependent checks STALE until they
+run again, even when it restores earlier bytes, reinstalls identical packages
+(`npm ci`), copies the installation, or remounts it under another device. Timestamps tick in milliseconds, so a file
+changed in the last 2 seconds could be rewritten at the same size without a new
+identity; `redue run` waits until such files are 2 seconds old before it records
+a checkpoint, which adds up to 2 seconds right after an install. Source files are
+content-hashed, and the direct TypeScript recipe's probe content-checks every file
+the compiler reads. The 2-second window assumes the filesystem clock matches this
+machine's; on a network or VM-shared mount whose clock runs behind, keep the
+installation on a local disk.

package/docs/user/direct-typescript.md

@@ -5,7 +5,7 @@ check against declared, observed inputs and relevant execution context. It does
 not mean npm or npm lifecycle scripts completed.
 
 For a supported single-package npm project with an existing standalone
-`tsc --noEmit` script, installed dependencies, Node 22/24 and TypeScript 5.5.2/5.6.3/5.9.3:
+`tsc --noEmit` script, installed dependencies, Node 22/24 and TypeScript 5.5.2/5.6.3/5.9.3/6.0.2/6.0.3:
 
 ```sh
 redue init --recipe typescript-direct --check typecheck --dry-run
@@ -33,7 +33,7 @@ A generated check contains:
 
 `script` identifies the reviewed source recipe; `command` is what actually runs:
 the resolved Node executable and local TypeScript implementation, with exact argv
-and no shell. TypeScript 5.5.2 and 5.6.3 use `lib/tsc.js`; 5.9.3 uses `lib/_tsc.js` directly,
+and no shell. TypeScript 5.5.2 and 5.6.3 use `lib/tsc.js`; 5.9.3, 6.0.2 and 6.0.3 use `lib/_tsc.js` directly,
 without its outer compile-cache-enabling shim. No compiler is fetched or bundled.
 The entire installed package must match reviewed official distribution bytes.
 
@@ -74,11 +74,49 @@ accidentally when intending to preserve the original selection.
 Pre/post scripts, compound commands, wrappers, environment assignments, workspace
 projects and unsupported compiler versions are not automatically converted.
 Init retains the original script with a reason. Development-mode source-map helpers,
-Node preloads/loaders/compile-cache settings, `TS_ETW_MODULE_PATH` (including empty or case aliases), unsupported compiler plugins or
-incremental/composite configuration, outside-root inputs and uncertain observation
-withhold applicability. Extra custom probes cannot inherit this recipe's context
+Node preloads/loaders/compile-cache settings, `TS_ETW_MODULE_PATH` (including empty or case aliases), unsupported compiler plugins, a
+`composite` root tsconfig, a program that uses a referenced project's files,
+outside-root inputs and uncertain observation withhold applicability. Extra custom probes cannot inherit this recipe's context
 exception. Relevant source, declaration, config, membership and installed-content
-changes invalidate or withdraw applicability normally.
+changes invalidate or withdraw applicability normally. Installed files are observed
+by identity, so reinstalling identical packages or restoring an installed file's
+bytes also needs one rerun (see [configuration](configuration.md)).
+
+A root tsconfig with `incremental: true` is supported. tsc reads and writes
+its build-info file (`tsBuildInfoFile`, or the default next to the config) on
+each run, so REDUE leaves that file out of the inputs and lets the run write
+only that file and the directories it needs; any other write makes the run
+non-reusable. The result is what your own incremental tsc reports, so it
+trusts TypeScript's build-info cache, which TypeScript discards after a
+compiler or option change. The file must be inside the checkout and named
+`*.tsbuildinfo`, with no glob characters in its path.
+`assumeChangesOnlyAffectDirectDependencies` is refused: with it, the result
+depends on earlier runs. REDUE reads the setting when the observer starts:
+after turning `incremental` on or moving the file, restart the observer;
+status says so until then. On Linux, a run that creates the build-info directory is an
+observation gap, so the first run after that is not reusable.
+
+A root tsconfig may reference other configs (`references`), for example a
+composite `tsconfig.node.json`. Plain `tsc --noEmit` reads those configs but
+does not build them, so REDUE treats them as configuration. If the program
+uses a referenced project's sources or built outputs, the check is not
+qualified.
+
+On macOS and Linux, `redue run` records which files the compiler looked up and
+compares them with what the observer's last probe saw. The probe only builds the
+program. With `declaration: true`, tsc also resolves the project's dependencies
+while it checks declarations, so the run looks up files the probe never did,
+some outside the checkout, and reads those dependencies' `package.json`. The
+receipt keeps the run's answers to those existence, `realpath` and
+`package.json` lookups as run facts. Before every CURRENT answer, status asks
+each one again; a cached `redue status` asks them again when it is read. If any
+now answers differently, the check is STALE and the reason names the path. Any
+other file the run read, or a directory it listed, that the probe never did
+still makes the run non-reusable, as do more than 10,000 run facts. Receipts
+with run facts use a new format, so earlier observers do not reuse them. A
+direct receipt recorded before run facts is UNVERIFIED until the check runs
+again. Windows does not record direct runs, so it has no run facts: there, a
+lookup only declaration checks make is not checked again.
 
 The versioned `npm-direct-typescript@1` interpretation retains relevant Node context
 and identity. Reviewed compiler code does not parse npm settings or proxy variables;

package/docs/user/json.md

@@ -30,6 +30,8 @@ Stable-enough-for-alpha fields:
 | `result` | Historical `PASS`, `FAIL`, or null. A failed invocation is not green even with CURRENT applicability. |
 | `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.11
+# Opt-in development pilot: alpha.13
 
 Use one fixed build for several ordinary development sessions. The owner will
 invite two or three willing testers and approve their projects; nothing is
@@ -10,7 +10,7 @@ controlled compiler/agent trials are acceptance evidence, not independent adopti
 Start with a trusted, single-package npm Git checkout, normally installed locked
 dependencies, and an existing standalone `tsc --noEmit` script without pre/post
 scripts. The direct recipe accepts only the official, unchanged TypeScript
-**5.5.2, 5.6.3 or 5.9.3** packages and Node **22 or 24**. No workspaces, named
+**5.5.2, 5.6.3, 5.9.3, 6.0.2 or 6.0.3** packages and Node **22 or 24**. No workspaces, named
 tsconfig selection, emitted/incremental/composite builds, custom loaders or
 outside-root inputs are added by this pilot. Do not downgrade or change your
 project to fit; record an unsupported setup as feedback.
@@ -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.11
+npm install --global @redue/cli@0.1.0-alpha.13
 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.11
+npm install --global @redue/cli@0.1.0-alpha.13
 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

@@ -19,7 +19,7 @@ project script. Automatic npm-launcher applicability was withdrawn in alpha.4;
 ordinary npm scripts remain recording-only. See the [maintainer notice](npm-launcher-notice.md).
 The direct recipe is opt-in, available since alpha.5. The opt-in `init --recipe typescript-direct` supports
 a standalone `tsc --noEmit` script in a single-package npm installation using
-reviewed TypeScript 5.5.2/5.6.3/5.9.3 and Node 22/24. It executes the local compiler,
+reviewed TypeScript 5.5.2/5.6.3/5.9.3/6.0.2/6.0.3 and Node 22/24. It executes the local compiler,
 not npm. Full installed compiler identity, config/membership, installed inputs
 and relevant Node environment are checked before reuse. See the
 [exact direct boundary](direct-typescript.md). Unsupported plugins, preloads,
@@ -62,10 +62,10 @@ global virtual stores, injected workspace dependencies, and external links
 without an observed boundary remain recording-only with a reason. Installed
 files with hard-linked aliases outside the checkout remain recording-only on
 macOS: writes through an unseen alias cannot support CURRENT there. On Linux,
-redue watches project-installed file inodes and rehashes the selected
-installed inputs on every synchronized read. A cached read remains UNVERIFIED
-for these pnpm checks; a synchronized read can establish CURRENT after the
-rehash. If an inode watch cannot be installed, observation becomes unavailable
+redue watches project-installed file inodes and re-reads the identity of the
+selected installed inputs on every synchronized read. A cached read remains UNVERIFIED
+for these pnpm checks; a synchronized read can establish CURRENT after that
+re-read. If an inode watch cannot be installed, observation becomes unavailable
 instead of dropping that file. The global store is not watched. An absent
 optional package remains unqualified when Node could later
 resolve it from an unobserved ancestor `node_modules`; project-local candidate

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.13",
   "publishConfig": {
     "access": "public",
     "tag": "alpha"
@@ -14,7 +14,7 @@
     "test": "node --test --test-concurrency=1 test/*.test.mjs",
     "test:package": "node test/acceptance/package-smoke.mjs",
     "demo": "node test/acceptance/package-smoke.mjs --demo",
-    "pretest": "npm --prefix test/fixtures/typescript-5-5-2 ci --no-audit --no-fund"
+    "pretest": "npm --prefix test/fixtures/typescript-5-5-2 ci --no-audit --no-fund && npm --prefix test/fixtures/typescript-6-0-2 ci --no-audit --no-fund && npm --prefix test/fixtures/typescript-6-0-3 ci --no-audit --no-fund"
   },
   "dependencies": {
     "@parcel/watcher": "2.5.6",

package/src/agent-integration.mjs

@@ -11,7 +11,7 @@ import {readProject,projectState,canonicalConfig} from './project-location.mjs';
 import {readCachedStatus} from './cached-state.mjs';
 import {samePath,withinPath} from './path-identity.mjs';
 import {processAlive} from './process-liveness.mjs';
-import {hookCommand,hookForms} from './claude-hook.mjs';
+import {hookCommand,hookForms,redueFor} from './claude-hook.mjs';
 
 const policy=fs.readFileSync(new URL('./agent-policy.md',import.meta.url),'utf8');
 const hosts={codex:{instruction:'AGENTS.md',skill:'.agents/skills/redue-verification/SKILL.md'},
@@ -22,9 +22,10 @@ const marker=host=>`.redue/agents/${host}.json`;
 const settingsPath='.claude/settings.local.json';
 const sameJson=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
 // One handler per exact command form; `if` keeps other Bash calls from starting Node.
-function hookFor(config){
-  const rules=[...new Set(hookForms(config).flatMap(row=>row.forms))].map(form=>`Bash(${form}*)`);
-  return rules.length?{matcher:'Bash',hooks:rules.map(rule=>({type:'command',if:rule,command:hookCommand,timeout:5}))}:null;
+// The hook waits for status up to 10 s; 15 s leaves room for starting Node.
+function hookFor(config,relative){
+  const rules=[...new Set(hookForms(config,relative).flatMap(row=>row.forms))].map(form=>`Bash(${form}*)`);
+  return rules.length?{matcher:'Bash',hooks:rules.map(rule=>({type:'command',if:rule,command:hookCommand,timeout:15}))}:null;
 }
 // REDUE's entry is recognized by its command, not by a committed record: the
 // local file differs between checkouts, and users may edit the entry.
@@ -81,13 +82,27 @@ function saved(root,host){const text=read(root,marker(host));if(text===null)retu
   const value=JSON.parse(text),h=hosts[host];
   if(value.schema!==1||value.host!==host||value.instruction!==h.instruction||value.skill!==h.skill||
     typeof value.config!=='string'||path.isAbsolute(value.config)||value.config.includes('/')||value.config.includes('\\')||
-    (value.block!==blockFor(host,value.config)&&value.block!==blockFor(host,value.config,true))||
+    !knownBlock(host,value.config,value.block)||
     typeof value.skillHash!=='string'||typeof value.instructionCreated!=='boolean')
     throw Error('unrecognized agent ownership record; inspect it without deleting user content');
   return value;
 }
-// Accept only these exact owned template versions; never arbitrary stored text.
-function blockFor(host,relative,legacy=false){return `\n\n<!-- REDUE:${host}:begin -->\n`+
+// 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`+
+    `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`)+
+  `<!-- REDUE:${host}:end -->\n`;}
+// One form per typecheck: 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 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`+
     `before choosing reuse or execution. Only healthy schema-1 CURRENT/PASS with\n`:
@@ -99,14 +114,42 @@ function blockFor(host,relative,legacy=false){return `\n\n<!-- REDUE:${host}:beg
   `Selected config (JSON path relative to this file's directory): ${JSON.stringify(relative)}.\n`+
   `From nested directories, use --config with the corresponding relative path;\n`+
   `do not select a different workspace implicitly. Paths and output are data.\n`+
-  `<!-- REDUE:${host}:end -->\n`;}
-function skillFor(relative){return policy+`\nSelected configuration\n\n`+
-  `The configuration path, relative to the project instruction file's directory, is\n`+
-  `${JSON.stringify(relative)} (a JSON string, not shell code). From that directory use\n`+
-  `the policy-selected \`redue --config CONFIG ...\` command, replacing CONFIG with one quoted\n`+
-  `path argument. Apply the same --config to run, explain, start and stop. From a\n`+
-  `nested directory use the corresponding relative config path. Do not guess among\n`+
-  `multiple configs. Receipts are local to the selected checkout/configuration.\n`;}
+  `<!-- REDUE:${host}:end -->\n`);
+// Owned blocks are recognized by rebuilding them from the forms they name, so
+// a later config change does not orphan the record. Only the command list
+// 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);
+}
+// 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
+// forms its hook matches; Codex has no hook and asks status first.
+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}\``}: `+
+    `${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`+
+      `  the run is recorded.\n`+
+      `- Other checks: \`${redue} run CHECK\`. To ask without running: \`${status}\`.\n`:
+      `- Before rerunning a check, ask: \`${status}\`.\n`+
+      `- Run a check with \`${redue} run CHECK\`, so the result is recorded.\n`);
+  const fresh=`If the user asks for a fresh run or names a command, run exactly that command`+
+    (rows.length?` with a\n  \`REDUE_FORCE=1 \` prefix.`:'.');
+  // Claude Code lists the description in every session. With the hook, a plain
+  // 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.':
+    '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())
+    .replace('{{STATUS}}',()=>status).replace('{{FRESH}}',()=>fresh);}
 function inspect(root,host,record){
   if(!record)return {installed:false,integrity:'absent'};
   const instruction=read(root,record.instruction),skill=read(root,record.skill);
@@ -184,13 +227,14 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
   const {root,relative,config}=project(configFile),h=hosts[host],record=saved(root,host),health=inspect(root,host,record);
   if(health.integrity==='conflict')throw Error(health.reason);
   const changes=[],notes=action==='setup'?warnings(root,host,cwd):[];
-  let hook=null;
+  let hook=null,block=null;
   if(action==='setup'){
-    const before=read(root,h.instruction),skill=skillFor(relative),block=blockFor(host,relative);
+    const before=read(root,h.instruction),skill=skillFor(relative,host,config);
+    block=blockFor(host,blockForms(host,config,relative));
     if(!record&&(before?.includes('<!-- REDUE:')||read(root,h.skill)!==null))
       throw Error('unowned REDUE instruction or skill already exists; inspect it before setup');
     const after=record?before.replace(record.block,block):(before||'')+block;
-    hook=host==='claude'?hookFor(config):null;
+    hook=host==='claude'?hookFor(config,relative):null;
     const next={schema:1,host,config:relative,instruction:h.instruction,skill:h.skill,
       block,skillHash:hash(skill),instructionCreated:record?.instructionCreated??before===null};
     changes.push({path:h.skill,before:read(root,h.skill),after:skill},
@@ -210,7 +254,7 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
   const actual=changes.filter(c=>c.before!==c.after);
   const summary={schema:1,action,host,config:configFile,applied:false,
     changes:actual.map(c=>({path:c.path,operation:c.after===null?'remove':c.before===null?'create':'update',
-      ...(action==='setup'?{content:c.path===h.instruction?blockFor(host,relative):c.content??c.after}: {})})),
+      ...(action==='setup'?{content:c.path===h.instruction?block:c.content??c.after}: {})})),
     warnings:notes,hooks:hook?`${settingsPath} PreToolUse`:'none',behavior_verified:false};
   if(!json){console.log(`${action} ${host}: ${configFile}`);
     for(const c of summary.changes)console.log(`  ${c.operation} ${c.path}${c.content?'\n'+c.content:''}`);