@redue/cli 0.1.0-alpha.22 → 0.1.0-alpha.23

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.1.0-alpha.23 — 2026-10-26
+
+One command to set up REDUE with Claude Code, and one to undo it.
+
+- **`redue setup claude`** runs `init` (when there is no
+  `redue.config.json`), connects Claude Code, starts the observer, waits for
+  it to index the project, and records each check that can qualify once. It
+  asks once (`--yes` for no prompts), prints every file it writes, and a
+  second run changes nothing. It stops before writing when dependencies are
+  not installed or nothing can be set up.
+- **`redue remove`** undoes exactly what setup created: the integration (or
+  only this machine's hooks), the observer state, the local ignore line, and
+  the config if it is unchanged since setup wrote it. Anything that existed
+  before setup stays. Setup notes what it created in the clone's Git
+  directory, never in a committed file.
+- **Hooks find REDUE.** The Claude Code hooks name plain `redue` only when
+  the `redue` that your shell and a login shell find is this install;
+  otherwise they name this install's Node and entry by absolute path, so a
+  Claude Code started from an IDE or with a shorter PATH still runs it.
+  Checks the hook runs for the agent follow the same rule.
+- `init` keeps a typecheck that runs TypeScript 7's `tsc` (or `tsgo` from
+  `@typescript/native-preview`) recording-only and says why. The pnpm and
+  Yarn TypeScript recipes refuse TypeScript 7 with a clear reason instead
+  of an error from inside the compiler API.
+- The README is rewritten around a 5-minute quickstart, what REDUE covers
+  today (census qualifiers) and what it won't do.
+- Known limits, found by the stranger test: a Vitest run writes under
+  `node_modules/.vite`, which makes a direct TypeScript typecheck STALE until
+  it runs again; an installed file with a second hard link (esbuild's install
+  makes one) keeps the test check UNVERIFIED.
+
+- Contributors: the census can run every recipe (`--all-recipes`) and
+  counts direct TypeScript checks; its unrecorded-program check no longer
+  flags Yarn's temporary `node` wrapper; `eval/stranger.mjs` runs fresh
+  Claude Code sessions that set REDUE up from the README alone.
+
 ## 0.1.0-alpha.22 — 2026-10-25
 
 A correctness fix for recorded runs. Earlier alphas could report CURRENT for

package/README.md

@@ -1,229 +1,146 @@
 # REDUE
 
-Maintainer notice: alpha.4 withdraws automatic npm-launcher applicability.
-Npm commands still execute and record historical outcomes, but remain UNVERIFIED.
-[Why this changed and how to upgrade without deleting receipts](docs/user/npm-launcher-notice.md).
-Alpha.2 users should also review the [receipt correction](docs/user/receipt-selection-notice.md).
+**Know which checks still hold. Redo what's due.**
 
-**Know what still holds. Redo what's due.**
+You or your coding agent ran the typecheck, the linter or the tests. Then the
+code changed, or a new agent session started with no memory of it. REDUE
+records each check's result with the exact inputs it ran on, and tells you and
+your agent whether that result still applies to the code you have now, so a
+check that still holds is not run again and one that is stale is.
 
-You ran the checks. Then the code changed—or a new coding agent started with no
-conversation history. Which results can you still use?
+## Quickstart (about 5 minutes)
 
-REDUE keeps persistent verification state for your codebase so developers and
-coding agents can see which previous checks still apply to the code they have now.
-It records evidence, not proofs of correctness.
-
-For a qualified direct-compiler or supported Yarn/pnpm check (ordinary npm scripts are recording-only):
-
-```text
-$ redue status --sync
-✓ typecheck  CURRENT / PASS
-? test  UNVERIFIED / PASS
-  Recording-only: test runtime, transforms and cache inputs need review
-
-# Later, after a relevant edit:
-$ redue explain typecheck
-typecheck: STALE / PASS
-src/main.ts changed
-Relevant inputs changed:
-  src/main.ts
-Due again when verification is needed: redue run "typecheck"
-```
-
-Agent A verifies and exits. Agent B starts fresh. The receipt is still there;
-REDUE checks whether it still applies. Unrelated documentation edits can preserve
-it; relevant source edits make it stale. [Run the reproducible demo](docs/contributor/demo.md).
-
-## Install the alpha
-
-The opt-in pilot uses **0.1.0-alpha.18**. 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.
-
-
-REDUE is published on npm as `@redue/cli`. The installed command is `redue`.
+You need macOS or Linux, Node 22 or 24, Git, Claude Code, and a JavaScript or
+TypeScript project with its dependencies installed (`npm install`,
+`pnpm install` or `yarn`). On Linux, also Python 3.
 
 ```sh
 npm install --global @redue/cli@alpha
+cd your-project
+redue setup claude
 ```
 
-To test a source candidate, run `npm ci` and `npm pack --json`, then install the
-reported tarball filename with `npm install --global ./<filename>`.
-
-Use a Node installation you own; REDUE does not need administrator privileges.
-If a global prefix is not writable, use a user-owned `--prefix` or run the
-installed CLI with Node. [Installation and removal](docs/user/getting-started.md)
-includes PowerShell and isolated-prefix instructions.
-
-Inside an existing, trusted Git project with dependencies already installed:
-
-```sh
-cd my-project
-redue init
-redue start
-redue run typecheck  # use a check name printed by init
-redue status
-```
+`setup` shows what it will do and asks once (`--yes` skips the question). It
+stops before writing anything if the dependencies are not installed. It:
 
-`init` discovers existing scripts, explains which can qualify and which are
-recording-only, and writes a small `redue.config.json`. It never runs your checks
-or changes your package manager, source, scripts, or dependencies. Commit the
-reviewed project config; local evidence stays outside the checkout.
+- finds your typecheck, lint and test scripts and writes `redue.config.json`
+  (it never changes your scripts, source or dependencies). Checks REDUE can
+  only record, not reuse, are listed as recording-only;
+- connects Claude Code: a short section in `CLAUDE.md`, a skill, and two hooks
+  in `.claude/settings.local.json`;
+- starts REDUE's file observer, waits while it indexes the project (a minute
+  or more in a large one), then runs each check that can qualify once, so
+  there is a first result to reuse;
+- prints every file it writes. Running it again changes nothing.
 
-Start with ordinary `status`. When it cannot establish caller context, use
-`redue status --sync` if that is worthwhile—or just rerun an inexpensive check.
-**Synchronization can cost more than rerunning a cheap check, particularly on
-Windows.** REDUE does not choose or execute that tradeoff for you.
+Then start a new Claude Code session in the project and work as usual. When
+the agent is about to rerun a check whose last pass still applies, the hook
+skips it and tells the agent why. After an edit, the hook runs the check
+through REDUE so the new result is recorded.
 
-`init` tries the strict recipes first: the [direct compiler recipe](docs/user/direct-typescript.md)
-for npm typechecks, the pnpm and Yarn TypeScript recipes, and the
-[direct test recipe](docs/user/tests-direct.md). A root typecheck or lint
-script none of them takes can use the [general recipe](docs/user/node-script.md),
-which runs the script through the package manager and records every Node
-process; a script that starts another program (git, esbuild, turbo) stays
-UNVERIFIED and the reason names it. Test scripts use the direct test recipe
-(Vitest, Jest); other test scripts stay recording-only.
+To look yourself:
 
-## Connect your agent (experimental)
+```text
+$ redue status --sync
+✓ typecheck  CURRENT / PASS
+✓ lint  CURRENT / PASS
 
-```sh
-redue agent setup codex --dry-run
-redue agent setup codex --apply  # or claude
-redue agent doctor
+# after editing src/main.ts
+$ redue explain typecheck
+typecheck: STALE / PASS
+src/main.ts changed
+Due again when verification is needed: redue run "typecheck"
 ```
 
-Start a fresh agent session and give it an ordinary task. Project-local guidance
-teaches it to inspect evidence before deciding whether verification needs repeating.
-Setup is explicit, reversible, and does not change tool permissions or run checks.
-[Activation, removal, and generic-agent guidance](docs/user/agents.md).
-
-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 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. Since alpha.15 the agent instructions ask agents to run
-  the check and leave skipping to REDUE; in a 12-session rerun of that task,
-  no agent left it out. Cost was the same ($0.54 without, $0.56 with).
+`--sync` checks the files and your environment before it answers; this is
+what the agent asks. Plain `redue status` is a fast cached answer and can say
+UNVERIFIED ("cannot confirm your execution context") where `--sync` would say
+CURRENT.
+
+To undo everything setup did: `redue remove`.
+
+## What it covers today
+
+In a census of 120 active public TypeScript repositories (October 2026, REDUE
+at commit c9034e5, just after 0.1.0-alpha.22), 89 installed cleanly. A check
+counts when two recorded runs on the same code both came out CURRENT on the
+same inputs. 31 repositories had at least one such check:
+
+| Check | Repositories | How |
+|---|---|---|
+| Typecheck | 22 | 16 by running the project's script with every Node process recorded ([general recipe](docs/user/node-script.md)); 6 by running the local `tsc` directly ([direct recipe](docs/user/direct-typescript.md)) |
+| Lint | 18 | general recipe |
+| Tests | 2 | Vitest run directly ([direct test recipe](docs/user/tests-direct.md)) |
+
+Everything else stays UNVERIFIED, with a reason you can read in
+`redue explain`. The usual ones: a script starts a program REDUE cannot see
+into (esbuild, turbo, nx, oxlint's tsgolint, TypeScript 7's native compiler),
+the project uses Bun, or a test suite writes into its own inputs. Two you may
+meet right after setup: a Vitest run writes its results under
+`node_modules/.vite`, which the direct TypeScript recipe counts as an
+installed input, so the typecheck turns STALE until it runs again; and an
+installed file with a second hard link (esbuild's install makes one) keeps
+the test check UNVERIFIED.
+[Supported projects](docs/user/supported-projects.md) has the details.
+
+## Measured with Claude Code
+
+Headless Claude Code sessions (Sonnet 5.5, CI Linux runner) on the same tasks
+with and without REDUE, three sessions per task. Session time, medians per
+task summed over the projects:
+
+- **Typecheck** (twilio-node, semiotic, Ultra-Card, SwitchHosts; four tasks;
+  96 sessions; 0.1.0-alpha.12 code): 464 s without, 330 s with. REDUE skipped
+  33 typechecks. Each was checked afterwards with plain `tsc` on the exact tree
+  it was skipped on, and all 33 agreed.
+- **Unit tests** (cheerio with Vitest 4, SwitchHosts with Vitest 5, twilio-node
+  with Jest 29; four tasks; 72 sessions; 0.1.0-alpha.14 code): 515 s without,
+  295 s with. REDUE skipped 21 test runs. Each was rerun plainly three times on
+  the exact tree, and all passed every time.
+
+API cost was the same in both arms. The savings come only when an earlier
+pass still applies: a task that changes source code saves nothing. A handful
+of projects and three runs per task show direction, not a general rate. The
+harness, tasks and raw results are in [`eval/`](eval/README.md).
+
+## What REDUE won't do
+
+- **Prove your code is correct.** CURRENT means the inputs of the recorded
+  run are unchanged, not that the code works. A failure stays a failure.
+- **Run checks for you.** Nothing runs in the background; checks run when you
+  or the agent run them.
+- **Trust what it cannot see.** A program it cannot account for, a file it
+  does not observe, or a gap in observation makes the result UNVERIFIED and
+  says why. It never turns that into CURRENT by guessing.
+- **Support yet:** TypeScript 7's native compiler, Bun, per-package checks in
+  large monorepos, results shared across machines, and the general recipe on
+  Windows (Windows has the strict recipes only).
 
 ## What the states mean
 
-| State | Meaning | Normal next step |
+| State | Meaning | Next step |
 | --- | --- | --- |
-| CURRENT | The recorded result applies to the declared inputs. | Reuse a passing result; do not rerun merely for freshness. |
-| STALE | Relevant inputs changed since the recorded result. | Rerun when verification is needed. |
-| UNVERIFIED | Applicability is unknown: no receipt, incomplete coverage, pending observation, or missing context. | Read the reason; synchronize if worthwhile, or run the check. |
-| FAILED | The invocation failed. Its applicability is tracked separately. | Keep the failure visible; it is not green evidence. |
-
-A historical PASS remains PASS when stale or unverified. A historical failure
-never becomes a successful check. CURRENT does not mean every product behavior
-has been verified.
-
-## Supported alpha path
-
-- macOS, Linux, and Windows on supported local filesystems; Node 22+.
-- Linux also requires Python 3 for observation. No WSL or Git Bash needed on Windows.
-- npm, pinned Yarn `node-modules`, and pinned pnpm 12 isolated/hoisted layouts.
-- Automatic qualification for supported Yarn/pnpm TypeScript invocations; ordinary npm
-  launcher checks remain recording-only. Explicitly select the
-  [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.
-- 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
-narrow. A script named `test` is not automatically a complete test contract.
-
-## Alpha limitations
-
-- REDUE records evidence; it does not prove correctness.
-- Direct commands outside `redue run` do not create receipts.
-- Some tests, lints, and builds remain UNVERIFIED/PASS because their input contract is incomplete.
-- Synchronized applicability has nontrivial cost and can lose to an inexpensive rerun.
-- Unsupported/exotic install layouts and filesystems remain conservative; they do not become green through guesses.
-- No cloud/team synchronization, IDE extension, or automatic background check execution.
-- Alpha configuration and APIs may evolve. Neither cached nor synchronized status is an atomic snapshot against concurrent edits.
-
-## Humans, shells, and agents
+| CURRENT | The recorded result applies to the code as it is now. | Reuse a pass; no need to rerun. |
+| STALE | An input changed since the recorded result. | Rerun when you need the answer. |
+| UNVERIFIED | REDUE cannot tell: no result yet, an input it cannot see, or observation not ready. | Read the reason; rerun if it matters. |
+| FAILED | The last run failed: the check ran and reported a failure, or could not run. | Fix and rerun. |
+
+## Without Claude Code, or step by step
 
 ```sh
-redue explain typecheck          # synchronized explanation; may run read-only probes
-redue status --json              # conservative cached data
-redue status --sync --json       # caller-aware decision
-redue status --short             # small cached indicator; never synchronizes
-redue stop                      # retains historical receipts
-redue remove-state              # removes only this config's owned local state
+redue init          # write redue.config.json from your scripts
+redue start         # start the file observer
+redue run typecheck # run a check through REDUE and record the result
+redue status --sync # what still holds
 ```
 
-Agents should use [the documented JSON interface](docs/user/json.md), not parse
-terminal prose. [The canonical agent loop](docs/user/agents.md) keeps the
-sync-versus-rerun choice explicit. [Shell usage](docs/user/shell.md) does not put
-synchronized work in a prompt.
+Codex is supported too (`redue agent setup codex --apply`); see
+[agents](docs/user/agents.md). Agents should read
+[the JSON interface](docs/user/json.md), not the terminal text.
 
-[User docs](docs/README.md) · [Contributing](CONTRIBUTING.md) ·
-[Architecture](docs/contributor/architecture.md) · [Acceptance evidence](docs/acceptance/README.md)
+[Getting started](docs/user/getting-started.md) · [User docs](docs/README.md) ·
+[Contributing](CONTRIBUTING.md) · [Architecture](docs/contributor/architecture.md)
 
 ## License
 
-REDUE is licensed under [Apache-2.0](LICENSE). Dependencies retain their own licenses.
+REDUE is licensed under [Apache-2.0](LICENSE). Dependencies keep their own licenses.

package/bin/redue.mjs

@@ -28,6 +28,9 @@ const help=`REDUE ${version}
 Usage: redue [--config FILE] [--state-dir DIR] COMMAND [OPTIONS]
 
 Commands:
+  setup claude [--yes] Set up REDUE and Claude Code in this project in one step:
+                       init, agent setup claude, start, one recorded run per check
+  remove [--yes]       Undo setup: integration, observer state, and the config setup created
   init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct|node-script]
                        Discover existing scripts; optionally select one workspace/check
   agent setup codex|claude [--dry-run|--apply] [--json]
@@ -58,7 +61,18 @@ if(args.length===3&&args[0]==='agent'&&args[1]==='hook'&&args[2]==='claude'){
   await runClaudeHook(fileURLToPath(import.meta.url));process.exit(0);
 }
 if(args.length===1&&args[0]==='--version'){console.log(version);process.exit(0);}
+// Internal: the entry this command runs, so setup and the hook can tell
+// whether the `redue` on PATH (a link, a package manager's shim, a wrapper)
+// is this install.
+if(args.length===1&&args[0]==='--entry'){console.log(fs.realpathSync(fileURLToPath(import.meta.url)));process.exit(0);}
 if(args.includes('--help')||args.includes('-h')||!args.length){console.log(help);await exit(0);}
+if(args[0]==='setup'||args[0]==='remove'){
+  // Loaded on demand; setup works before a config exists.
+  const {setupCommand}=await import('../src/setup.mjs');
+  try{await setupCommand(args,{entry:fileURLToPath(import.meta.url)});}
+  catch(e){error(e.message);}
+  await exit(0);
+}
 let configFile=null,stateOverride=null;
 for(let i=0;i<args.length;){
   if(args[i]==='--config'||args[i]==='--state-dir'){
@@ -124,7 +138,7 @@ if(command==='init'){
     checks:discovery.checks.map(({config:check,level,reason})=>({name:check.name,
       script:check.script||null,command:check.command||null,
       workspace:check.workspace||null,level,reason})),config:configFile,
-    written:willWrite,existing:configured};
+    written:willWrite,existing:configured,writable:!configured&&!unsupported&&discovery.checks.length>0};
   if(!json) {
     console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
       `${summary.version?' '+summary.version:''}; ${summary.installation_layout} installation.`);

package/docs/user/agents.md

@@ -74,10 +74,18 @@ observer when a session starts (below); otherwise use `redue start`.
 
 ## Claude Code typecheck hook
 
-`redue agent setup claude --apply` also adds a PreToolUse hook and a
-SessionStart hook to `.claude/settings.local.json`. Both run
-`redue agent hook claude`, which needs a local REDUE install, so they are
-per-developer; keep that file out of commits. Other settings in the file are kept,
+`redue agent setup claude --apply` (and `redue setup claude`) also adds a
+PreToolUse hook and a SessionStart hook to `.claude/settings.local.json`.
+Both run `redue agent hook claude`, which needs a local REDUE install, so
+they are per-developer; keep that file out of commits. Setup names REDUE
+plainly only when the `redue` that both your shell and a login shell find on
+PATH is the install running setup. Otherwise the hooks name this install's
+Node and entry by absolute path, so a Claude Code started from an IDE, a
+desktop app or another shell still runs the right REDUE; run setup again
+after moving or upgrading Node. `redue agent doctor` reports a hook whose
+paths no longer exist. When the hook runs a check through REDUE for the
+agent, it likewise writes plain `redue run` only if its own PATH finds this
+install, else the absolute form. Other settings in the file are kept,
 but the file is rewritten as 2-space JSON. `.claude/settings.json` is not touched.
 `redue agent remove claude --apply` removes only the entries REDUE added.
 

package/docs/user/direct-typescript.md

@@ -7,7 +7,9 @@ not mean npm or npm lifecycle scripts completed.
 For a supported single-package npm project with a typecheck script of `tsc`
 runs (see [script forms](#script-forms)) or no typecheck script and a root
 `tsconfig.json`, installed dependencies, Node 22/24 and TypeScript 5.x or 6.0
-(see [compiler identity](#compiler-identity)):
+(see [compiler identity](#compiler-identity)). TypeScript 7 is a native
+compiler this recipe cannot run: `init` refuses it
+(`direct-typescript-version-unsupported`):
 
 ```sh
 redue init --recipe typescript-direct --check typecheck --dry-run

package/docs/user/getting-started.md

@@ -67,7 +67,26 @@ the package alone does not update project instructions.
 
 ## First project
 
-From the project root:
+With Claude Code, one command does the steps below and connects the agent:
+
+```sh
+redue setup claude          # asks once; --yes for no prompts
+```
+
+It runs `init` when the project has no `redue.config.json`, `agent setup
+claude`, and `start`, then records each check that can qualify once, unless
+it is already CURRENT. It prints every file it writes, and running it again
+changes nothing that is already set up. When `.claude/settings.local.json`
+is not ignored by Git, it adds it to `.git/info/exclude`; it refuses when
+that file is committed. What setup created is noted in the clone's Git
+directory (`.git/redue-setup-<id>.json`, never committed). `redue remove`
+undoes exactly that: the integration (or only this machine's hooks, when the
+integration was already in the project), the observer and its state
+(receipts included), the local ignore line, and the config if setup wrote it
+and it has not been edited since. A config or observer state that existed
+before setup stays. `remove` asks before it deletes; Enter means no.
+
+Step by step, from the project root:
 
 ```sh
 redue init --dry-run

package/docs/user/node-script.md

@@ -113,7 +113,10 @@ one REDUE can account for:
 
 A process that replaces itself with another program through
 `process.execve` (TypeScript 7's `tsc` does this to start its native
-compiler) is judged the same way as a program it starts.
+compiler) is judged the same way as a program it starts. `init` reads
+TypeScript 7's launchers (`tsc` from `typescript@7`, `tsgo` from
+`@typescript/native-preview`) as that native compiler and keeps such a script
+recording-only.
 
 Anything else makes the result UNVERIFIED and names the program: `git`,
 `sleep`, `find`, and native programs from installed packages such as esbuild,

package/docs/user/supported-projects.md

@@ -83,7 +83,11 @@ entries stay inputs: an import can still reach an excluded file); a file the
 program reads outside them keeps the check recording-only. This avoids pnpm's task-run bookkeeping
 writes during `pnpm run`; it does not alter the project's script. Test, lint,
 build, and ambiguous TypeScript scripts still execute through `pnpm run`; root
-typecheck and lint ones can use the [general recipe](node-script.md). The generated `@typescript-bin:WORKSPACE` token resolves
+typecheck and lint ones can use the [general recipe](node-script.md). The pnpm
+and Yarn TypeScript recipes read TypeScript's compiler API, which TypeScript 7
+does not ship: with TypeScript 7 installed they refuse and say so. The
+general recipe runs such a script, but TypeScript 7's native compiler is a
+program REDUE does not record, so the result is UNVERIFIED. The generated `@typescript-bin:WORKSPACE` token resolves
 the local compiler when the check runs; it is not an absolute machine path.
 
 The pnpm contract indexes consumed installed package contents inside the

package/package.json

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

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 {fanoutRules,hookCommand,hookForms,redueFor} from './claude-hook.mjs';
+import {fanoutRules,hookCommand,hookForms,redueFor,runsEntry,shellQuote as quote} 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'},
@@ -25,17 +25,53 @@ const sameJson=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
 // The hook waits for status up to 10 s; 15 s leaves room for starting Node.
 // Fan-out commands (turbo, nx, `pnpm -r`) and root scripts that run one get
 // prefix rules; the hook decides from the full command.
-function hookFor(config,relative,scripts){
+function hookFor(config,relative,scripts,command=hookCommand){
   const rules=[...new Set([...hookForms(config,relative,scripts).flatMap(row=>[...row.forms,...row.local]),
     ...fanoutRules(config,scripts)])].map(form=>`Bash(${form}*)`);
-  return rules.length?{matcher:'Bash',hooks:rules.map(rule=>({type:'command',if:rule,command:hookCommand,timeout:15}))}:null;
+  return rules.length?{matcher:'Bash',hooks:rules.map(rule=>({type:'command',if:rule,command,timeout:15}))}:null;
 }
 // The same command on SessionStart starts the observer; it needs no check to match.
-const sessionHook={hooks:[{type:'command',command:hookCommand,timeout:10}]};
+const sessionHookFor=(command=hookCommand)=>({hooks:[{type:'command',command,timeout:10}]});
 const events=['PreToolUse','SessionStart'];
+// The absolute form: Node and REDUE's entry (redue.mjs), each quoted as quote()
+// writes it. [node, entry] or null.
+function absoluteHook(command){
+  const word="'((?:[^']|'\\\\'')*)'";
+  const match=new RegExp(`^${word} ${word} agent hook claude$`).exec(command??'');
+  if(!match)return null;
+  const [node,entry]=[match[1],match[2]].map(value=>value.replaceAll("'\\''","'"));
+  // REDUE's entry file, or the bin link npm installs for it.
+  return /^redue(\.mjs)?$/.test(path.basename(entry))?[node,entry]:null;
+}
+export const isHookCommand=command=>command===hookCommand||Boolean(absoluteHook(command));
+// The command Claude Code runs for the hook. Plain `redue` when this install
+// is the one both this shell and a login shell find on PATH. Otherwise this
+// install's Node and entry by absolute path, so a Claude Code started from
+// another shell, an IDE or with a shorter PATH still runs it, and an older
+// install on PATH does not answer for this one. The settings file is
+// per-developer, so a machine path is fine there.
+export function hookInvocation(entry,{env=process.env,platform=process.platform}={}){
+  if(platform==='win32')return {command:hookCommand,reason:'Windows: plain redue on PATH'};
+  let target;try{target=fs.realpathSync(entry);}catch{target=entry;}
+  // Paths that survive upgrades where they can: the entry as invoked (a
+  // global bin link, not the versioned file behind it) and the node on PATH
+  // (Homebrew's link, not its versioned cellar).
+  const real=file=>{try{return fs.realpathSync(file);}catch{return null;}};
+  const invoked=typeof process.argv[1]==='string'&&path.isAbsolute(process.argv[1])&&real(process.argv[1])===target?process.argv[1]:target;
+  const execReal=real(process.execPath);
+  const node=(env.PATH||'').split(path.delimiter).map(dir=>path.join(dir||'.','node')).find(file=>real(file)===execReal)??process.execPath;
+  const same=file=>runsEntry(file,target,env);
+  const here=findExecutable('redue',{env});
+  const login=spawnSync(env.SHELL||'/bin/sh',['-lc','command -v redue'],{env,encoding:'utf8',timeout:5000,stdio:['ignore','pipe','ignore']});
+  const loginPath=login.status===0?login.stdout.trim().split('\n').pop():null;
+  if(same(here)&&same(loginPath))return {command:hookCommand,reason:`redue on PATH is this install (${here})`};
+  return {command:`${quote(node)} ${quote(invoked)} agent hook claude`,
+    reason:!here&&!loginPath?'redue is not on PATH; the hook names this install by its absolute path':
+      `redue on PATH is ${here||loginPath||'missing'} in ${same(here)?'a login shell':'this shell'}, not this install; the hook names this install by its absolute path`};
+}
 // 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.
-const ownedHook=entry=>Array.isArray(entry?.hooks)&&entry.hooks.length>0&&entry.hooks.every(h=>h?.command===hookCommand);
+const ownedHook=entry=>Array.isArray(entry?.hooks)&&entry.hooks.length>0&&entry.hooks.every(h=>isHookCommand(h?.command));
 function parseSettings(text){
   if(text===null)return {};
   let value;try{value=JSON.parse(text);}catch{throw Error(`${settingsPath} is not valid JSON; fix it before agent setup or removal`);}
@@ -65,6 +101,45 @@ function hookInstalled(root,event='PreToolUse'){
   try{return (parseSettings(read(root,settingsPath)).hooks?.[event]||[]).some(ownedHook);}
   catch{return false;}
 }
+// What removing a host's integration changes, from its setup record: the
+// managed block, the skill, the hooks and the record.
+function removalChanges(root,host,record){
+  const h=hosts[host],before=read(root,h.instruction),after=before===null?null:before.replace(record.block,'');
+  const changes=[{path:h.instruction,before,after:record.instructionCreated&&after===''?null:after},
+    {path:h.skill,before:read(root,h.skill),after:null}];
+  if(host==='claude'){const settings=read(root,settingsPath);
+    changes.push({path:settingsPath,before:settings,after:settingsWith(settings,null)});}
+  changes.push({path:marker(host),before:read(root,marker(host)),after:null});
+  return changes;
+}
+// Removes a host's integration without needing the project config (redue
+// remove after the config is gone): the changed paths, each with its operation.
+export function removeIntegration(root,host='claude'){
+  const record=saved(root,host);if(!record)return [];
+  const health=inspect(root,host,record);if(health.integrity==='conflict')throw Error(health.reason);
+  const changes=removalChanges(root,host,record).filter(c=>c.before!==c.after);
+  apply(root,changes);
+  return changes.map(c=>`${c.after===null?'remove':'update'} ${c.path}`);
+}
+// Whether REDUE's Claude Code hooks are in the local settings.
+export const claudeHooksInstalled=root=>hookInstalled(root,'SessionStart')||hookInstalled(root);
+// Removes REDUE's Claude Code hooks from the local settings and keeps the
+// rest; the file's path when it changed, else null.
+export function removeClaudeHooks(root){
+  const before=read(root,settingsPath);if(before===null)return null;
+  const after=settingsWith(before,null);if(after===before)return null;
+  apply(root,[{path:settingsPath,before,after}]);return settingsPath;
+}
+// Whether the installed hook's command can start: an absolute one by its
+// files, plain redue by PATH.
+function hookRunnable(root){
+  let command=null;
+  try{command=(parseSettings(read(root,settingsPath)).hooks?.SessionStart||[]).find(ownedHook)?.hooks[0]?.command??null;}catch{}
+  const absolute=absoluteHook(command);
+  if(absolute)return fs.existsSync(absolute[0])&&fs.existsSync(absolute[1])?'installed (absolute path)':
+    'installed, but its Node or REDUE path no longer exists; run redue agent setup claude again';
+  return findExecutable('redue')?'installed':'installed, but redue is not on PATH, so it never runs';
+}
 function safeFile(root,relative){
   if(path.isAbsolute(relative)||relative.split(/[\\/]/).some(p=>p==='..'||p===''))throw Error('unsafe integration path');
   const file=path.resolve(root,relative);
@@ -273,7 +348,7 @@ 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,block=null;
+  let hook=null,sessionHook=null,block=null;
   if(action==='setup'){
     const before=read(root,h.instruction),skill=skillFor(relative,host,config);
     block=blockFor(host,blockForms(host,config,relative));
@@ -281,7 +356,12 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
       throw Error('unowned REDUE instruction or skill already exists; inspect it before setup');
     const after=record?before.replace(record.block,block):(before||'')+block;
     let scripts={};try{scripts=JSON.parse(read(root,'package.json')??'{}').scripts||{};}catch{}
-    hook=host==='claude'?hookFor(config,relative,scripts):null;
+    const invocation=host==='claude'?hookInvocation(entry):null;
+    if(invocation)notes.push(`Hook command: ${invocation.command} (${invocation.reason})`);
+    if(invocation&&invocation.command!==hookCommand)
+      notes.push('The agent instructions say `redue ...`: put this install on PATH (npm install --global @redue/cli@alpha) so the agent\'s shell can run them. The hook runs the checks it rewrites through this install either way.');
+    hook=host==='claude'?hookFor(config,relative,scripts,invocation.command):null;
+    sessionHook=host==='claude'?sessionHookFor(invocation.command):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},
@@ -291,14 +371,7 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
         content:JSON.stringify(hook?next:{SessionStart:sessionHook},null,2)+
           (hook?'':'\nno 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,'');
-    changes.push({path:h.instruction,before,after:record.instructionCreated&&after===''?null:after},
-      {path:h.skill,before:read(root,h.skill),after:null});
-    if(host==='claude'){const settings=read(root,settingsPath);
-      changes.push({path:settingsPath,before:settings,after:settingsWith(settings,null)});}
-    changes.push({path:marker(host),before:read(root,marker(host)),after:null});
-  }
+  }else if(record)changes.push(...removalChanges(root,host,record));
   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',
@@ -355,7 +428,7 @@ export async function doctor({configFile,stateOverride,entry,cwd,host}){
       const out=spawnSync(launch.file,launch.args,{...launch.options,encoding:'utf8',timeout:2000,maxBuffer:4096,stdio:['ignore','pipe','pipe']});
       if(out.status===0)version=out.stdout.trim();}
     let integration={installed:false,integrity:'unknown'},hook=name==='claude'?'absent':'none',sessionHook=hook;
-    const installed=()=>value.command.path?'installed':'installed, but redue is not on PATH, so it never runs';
+    const installed=()=>hookRunnable(p.root);
     if(p)try{const record=saved(p.root,name);integration=inspect(p.root,name,record);
       if(name==='claude'&&hookInstalled(p.root))hook=installed();
       if(name==='claude'&&hookInstalled(p.root,'SessionStart'))sessionHook=installed();

package/src/claude-hook.mjs

@@ -6,12 +6,13 @@
 // Never exit 2: Claude Code treats exit 2 as a block.
 import fs from 'node:fs';
 import path from 'node:path';
-import {spawn} from 'node:child_process';
+import {spawn,spawnSync} from 'node:child_process';
 import {projectState} from './project-location.mjs';
 import {realObservedPath} from './path-identity.mjs';
 import {processAlive} from './process-liveness.mjs';
 import {scriptRunChecks} from './typescript-invocation.mjs';
 import {recipeLabel} from './presentation.mjs';
+import {findExecutable} from './executable-lookup.mjs';
 
 export const hookCommand='redue agent hook claude';
 // No shell metacharacters; `@` starts scoped package names.
@@ -31,6 +32,22 @@ export const defaultConfig='redue.config.json';
 // would need shell quoting.
 export const redueFor=(configFile=defaultConfig)=>configFile===defaultConfig?'redue':
   safe.test(configFile)?`redue --config ${configFile}`:null;
+export const shellQuote=value=>`'${String(value).replaceAll("'","'\\''")}'`;
+// How a rewritten command starts REDUE: plain `redue` when the hook's PATH
+// finds this install, else this install by absolute path. An agent shell
+// without redue on PATH cannot run the plain form.
+export function redueInvocation(entry,{env=process.env,platform=process.platform}={}){
+  if(platform==='win32'||runsEntry(findExecutable('redue',{env}),entry,env))return 'redue';
+  return `${shellQuote(process.execPath)} ${shellQuote(entry)}`;
+}
+// Whether the command at `file` runs this install's entry: the same file, or
+// a shim or wrapper that reports it (redue --entry).
+export function runsEntry(file,entry,env=process.env){
+  if(!file)return false;
+  try{const target=fs.realpathSync(entry);if(fs.realpathSync(file)===target)return true;
+    const out=spawnSync(file,['--entry'],{env,encoding:'utf8',timeout:5000,stdio:['ignore','pipe','ignore']});
+    return out.status===0&&fs.realpathSync(out.stdout.trim())===target;}catch{return false;}
+}
 
 // Package-manager commands that a script of the same name would not reach.
 const builtins={pnpm:new Set(['add','audit','bin','config','create','dedupe','deploy','dlx','doctor','env','exec','fetch',
@@ -265,9 +282,9 @@ export function matchCheck(command,config,configFile,dir,scripts){
 }
 // The same check (or checks, in order) through REDUE, keeping the output
 // suffix; null if it already is, or if more commands follow it.
-export function recordedCommand(command,name,configFile=defaultConfig){
+export function recordedCommand(command,name,configFile=defaultConfig,invoke='redue'){
   const names=Array.isArray(name)?name:[name];
-  const parts=split(command),redue=redueFor(configFile);
+  const parts=split(command),redue=redueFor(configFile)?.replace(/^redue/,()=>invoke);
   if(!parts||parts.rest!==null||!names.length||!names.every(value=>safe.test(value))||!redue)return null;
   const run=names.map(value=>`${redue} run ${value}`).join(' && ');
   return parts.base===run?null:names.length>1&&parts.suffix?`(${run})${parts.suffix}`:run+parts.suffix;
@@ -374,7 +391,7 @@ export function sessionStart(input,{entry}){
 }
 
 // Returns the hook's stdout object, or null to allow the command.
-export async function claudeHook(input,{entry,timeout}){
+export async function claudeHook(input,{entry,timeout,invoke=null}){
   if(input?.tool_name!=='Bash')return null;
   const command=input.tool_input?.command,root=input.cwd;
   if(typeof command!=='string'||/^\s*REDUE_FORCE=1(?:\s|$)/.test(command))return null;
@@ -414,7 +431,7 @@ export async function claudeHook(input,{entry,timeout}){
       if(reason)return {hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}};
       const pending=names.filter(name=>!verdict(status,name));
       const rewritten=status?.schema===1&&status.observation?.healthy===true&&Array.isArray(status.checks)&&
-        names.every(name=>status.checks.some(item=>item?.name===name))?recordedCommand(entered.command,pending,configPath):null;
+        names.every(name=>status.checks.some(item=>item?.name===name))?recordedCommand(entered.command,pending,configPath,invoke??redueInvocation(entry)):null;
       return rewritten?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow',
         permissionDecisionReason:`REDUE: ${pending.map(name=>JSON.stringify(name)).join(', ')} of this script's checks ${pending.length===1?'is':'are'} not CURRENT; running ${pending.length===1?'it':'them'} through redue run so the result is recorded.`,
         updatedInput:{...input.tool_input,command:entered.prefix+rewritten}}}:null;
@@ -429,7 +446,7 @@ export async function claudeHook(input,{entry,timeout}){
   // stays too: the rewrite returns "allow", which would also skip the prompt
   // for the rest of the chain.
   const rewritten=status?.schema===1&&status.observation?.healthy===true&&Array.isArray(status.checks)&&
-    status.checks.some(item=>item?.name===name)?recordedCommand(entered.command,name,configPath):null;
+    status.checks.some(item=>item?.name===name)?recordedCommand(entered.command,name,configPath,invoke??redueInvocation(entry)):null;
   // updatedInput replaces the whole tool input. Deny and ask rules still apply
   // to the rewritten command; "allow" skips only the prompt.
   return rewritten?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow',

package/src/node-script.mjs

@@ -236,6 +236,19 @@ export const scriptPath=(dir,callerPath)=>{
 // Why a shell command line could start a program REDUE does not record, or
 // null. Names are looked up along `searchPath` from `cwd`. A script the pnpm
 // executable runs is read the same way, since the recorder cannot see it.
+// TypeScript 7's Node launchers (tsc in typescript@7, tsgo in
+// @typescript/native-preview) replace themselves with a native compiler REDUE
+// does not record: the package and version, or null.
+export function nativeTypeScriptLauncher(file){
+  let dir;try{dir=path.dirname(fs.realpathSync(file));}catch{return null;}
+  for(let n=0;n<3;n++,dir=path.dirname(dir)){
+    let pkg;try{pkg=JSON.parse(fs.readFileSync(path.join(dir,'package.json'),'utf8'));}catch{continue;}
+    if(pkg.name==='typescript'&&Number(String(pkg.version).split('.')[0])>=7||pkg.name==='@typescript/native-preview')
+      return `${pkg.name} ${pkg.version}`;
+    return null;
+  }
+  return null;
+}
 export function commandLineIssue(text,{cwd,searchPath,depth=0}={}){
   if(depth>8)return 'the scripts run each other too deeply for REDUE to read';
   const parsed=parseCommandLine(text);
@@ -270,6 +283,8 @@ export function commandLineIssue(text,{cwd,searchPath,depth=0}={}){
       if(kind==='node'){
         const flag=['node','nodejs'].includes(path.basename(file))&&args.find(arg=>nativeReads.test(arg.text));
         if(flag)return `runs node ${flag.text.split('=')[0]}, which reads a file REDUE cannot see`;
+        const native=nativeTypeScriptLauncher(file);
+        if(native)return `runs ${path.basename(name)} from ${native}, a native compiler REDUE does not record`;
         break;
       }
       if(kind==='pnpm'){const issue=pnpmRunIssue(args.map(arg=>arg.text),{cwd:dir,searchPath,depth});if(issue)return issue;break;}

package/src/pnpm-inputs.mjs

@@ -2,7 +2,7 @@
 // repository-relative input sets and resolution relationships, never pnpm
 // virtual-store names as semantic identities.
 import {probeTimeLeft} from './probe-deadline.mjs';
-import {compilerFiles} from './typescript-list.mjs';
+import {compilerApiIssue,compilerFiles} from './typescript-list.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import {createRequire} from 'node:module';
@@ -298,7 +298,9 @@ export function pnpmTypecheckInputs(root,workspace,run,{captureQueries=false}={}
   let tsPackage;try{tsPackage=realObservedPath(lookup.resolve('typescript/package.json'));}
   catch{throw Error('installed TypeScript compiler cannot be resolved');}
   if(!within(tsPackage,root))throw Error('TypeScript compiler is outside the observed checkout');
-  const tsRoot=path.dirname(tsPackage),ts=lookup('typescript');
+  const tsRoot=path.dirname(tsPackage),apiIssue=compilerApiIssue(tsRoot);
+  if(apiIssue)throw Error(apiIssue);
+  const ts=lookup('typescript');
   const tsc=path.join(tsRoot,'bin','tsc');
   if(!exists(tsc))throw Error('installed TypeScript executable is missing');
   const configStarted=performance.now();

package/src/setup.mjs

@@ -0,0 +1,178 @@
+// `redue setup claude` and `redue remove`: one command from a project with
+// installed dependencies to a working Claude Code integration, and one to
+// undo it. Setup runs init when the project has no config, agent setup
+// claude, start, and one recorded run of each check init can qualify that is
+// not CURRENT. It prints every file it writes. What it created is kept in a
+// record in the clone's Git directory (never committed); a later setup adds
+// to that account and never forgets it. Remove undoes exactly what the record
+// says setup created: the agent files or just this machine's hooks, the
+// observer state, the local ignore line, and the config if it is unchanged
+// since setup wrote it.
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {createInterface} from 'node:readline/promises';
+import {projectState} from './project-location.mjs';
+import {claudeHooksInstalled,removeClaudeHooks,removeIntegration} from './agent-integration.mjs';
+
+const configName='redue.config.json',localSettings='.claude/settings.local.json',agentRecord='.redue/agents/claude.json';
+const hash=text=>createHash('sha256').update(text).digest('hex');
+const readText=file=>{try{return fs.readFileSync(file,'utf8');}catch{return null;}};
+const git=(root,...args)=>spawnSync('git',args,{cwd:root,encoding:'utf8',stdio:['ignore','pipe','ignore']});
+const ignoreLine=`/${localSettings}`;
+
+async function confirm(question,yes,{defaultYes}){
+  if(yes)return true;
+  if(!process.stdin.isTTY||!process.stdout.isTTY)throw Error('not a terminal; run again with --yes to proceed without prompts');
+  const prompt=createInterface({input:process.stdin,output:process.stdout});
+  try{const answer=(await prompt.question(`${question} ${defaultYes?'[Y/n]':'[y/N]'} `)).trim();
+    return defaultYes?!/^n/i.test(answer):/^y/i.test(answer);}finally{prompt.close();}
+}
+
+export async function setupCommand(args,{entry,cwd=process.cwd()}){
+  const action=args.shift();
+  const yes=args.includes('--yes'),rest=args.filter(arg=>arg!=='--yes');
+  if(action==='setup'&&(rest.length!==1||rest[0]!=='claude'))throw Error('use redue setup claude [--yes]');
+  if(action==='remove'&&rest.length)throw Error('use redue remove [--yes]');
+  const top=git(cwd,'rev-parse','--show-toplevel');
+  if(top.status!==0)throw Error('run this inside a Git checkout');
+  const root=fs.realpathSync(top.stdout.trim());
+  if(!fs.existsSync(path.join(root,'package.json')))throw Error(`no package.json at the repository root (${root})`);
+  // The entry as invoked, so a hook written by a child names the install's
+  // stable bin link rather than the versioned file behind it.
+  const invoked=typeof process.argv[1]==='string'&&path.isAbsolute(process.argv[1])&&
+    (()=>{try{return fs.realpathSync(process.argv[1])===fs.realpathSync(entry);}catch{return false;}})()?process.argv[1]:entry;
+  // Every step is the ordinary command, so its own output says what it did.
+  const redue=(argv,options={})=>spawnSync(process.execPath,[invoked,...argv],{cwd:root,encoding:'utf8',
+    stdio:options.capture?['ignore','pipe','pipe']:'inherit',timeout:options.timeout});
+  // One record per checkout, beside the others in the shared Git directory:
+  // linked worktrees share .git/info/exclude.
+  const common=path.resolve(root,git(root,'rev-parse','--git-common-dir').stdout.trim());
+  const recordFile=path.join(common,`redue-setup-${hash(root).slice(0,16)}.json`);
+  // Other checkouts' records, for checkouts that still exist.
+  const others=()=>{try{return fs.readdirSync(common).filter(name=>/^redue-setup-[0-9a-f]{16}\.json$/.test(name)&&path.join(common,name)!==recordFile)
+    .map(name=>JSON.parse(readText(path.join(common,name))??'null')).filter(other=>other&&fs.existsSync(other.root));}catch{return [];}};
+  const context={root,redue,yes,record:JSON.parse(readText(recordFile)??'null'),recordFile,
+    exclude:path.join(common,'info','exclude'),others,save:next=>fs.writeFileSync(recordFile,JSON.stringify(next,null,2)+'\n')};
+  return action==='setup'?setup(context):remove(context);
+}
+
+async function setup({root,redue,yes,record:previous,recordFile,exclude,save}){
+  if(!fs.existsSync(path.join(root,'node_modules')))
+    throw Error('dependencies are not installed: run your package manager\'s install (npm install, pnpm install, yarn) first');
+  if(fs.existsSync(path.join(root,'vstate.config.json'))&&!fs.existsSync(path.join(root,configName)))
+    throw Error('a legacy vstate.config.json exists; rename it to redue.config.json or remove it first');
+  if(git(root,'ls-files','--error-unmatch',localSettings).status===0)
+    throw Error(`${localSettings} is committed; the hooks REDUE adds there name this machine's paths. Untrack it (git rm --cached) first`);
+  const configPath=path.join(root,configName),configExisted=fs.existsSync(configPath);
+  // init's account of the checks: which can qualify, also with a config.
+  const preview=redue(['init','--dry-run','--json'],{capture:true});
+  if(preview.status!==0)throw Error(preview.stderr.trim().replace(/^redue: /,'')||'init failed');
+  const found=JSON.parse(preview.stdout);
+  if(!configExisted&&!found.writable)throw Error(`nothing to set up: ${found.issue||(found.checks.length?found.checks.map(check=>`${check.name}: ${check.reason}`).join('; '):'no typecheck, lint or test script REDUE can use')}`);
+  const levels=new Map(found.checks.map(check=>[check.name,check.level]));
+  const names=configExisted?JSON.parse(readText(configPath)).checks.map(check=>check.name):found.checks.map(check=>check.name);
+  const ready=names.filter(name=>levels.get(name)==='ready');
+  console.log(`Setting up REDUE for Claude Code in ${root}`);
+  console.log(configExisted?`  keep ${configName} (exists)`:`  create ${configName}: ${names.map(name=>`${name} (${levels.get(name)==='ready'?'can qualify':'recording-only'})`).join(', ')}`);
+  console.log(`  write the Claude Code integration: CLAUDE.md section, .claude/skills/redue-verification/SKILL.md, ${localSettings} hooks, ${agentRecord}`);
+  console.log(`  start the observer and record ${ready.length?ready.join(', '):'no check'} once, unless already CURRENT`);
+  if(!await confirm('Proceed?',yes,{defaultYes:true})){console.log('Nothing written.');return {applied:false};}
+  // What this run creates is added to what earlier runs created.
+  const state=projectState(root,configPath);
+  const own={schema:1,host:'claude',root,config:configName,state,
+    configCreated:Boolean(previous?.configCreated),configHash:previous?.configHash??null,
+    agentCreated:Boolean(previous?.agentCreated)||!fs.existsSync(path.join(root,agentRecord)),
+    hooksAdded:Boolean(previous?.hooksAdded)||!claudeHooksInstalled(root),
+    stateCreated:Boolean(previous?.stateCreated)||!fs.existsSync(state),
+    excludeAdded:Boolean(previous?.excludeAdded)};
+  if(!configExisted){
+    const init=redue(['init']);
+    if(init.status!==0||!fs.existsSync(configPath))throw Error(`init did not write ${configName}; nothing else was written`);
+    Object.assign(own,{configCreated:true,configHash:hash(readText(configPath))});
+  }
+  save(own);
+  console.log(`${previous?'update':'create'} ${recordFile}: what setup created, for redue remove`);
+  const agent=redue(['agent','setup','claude','--apply']);
+  if(agent.status!==0)throw Error('agent setup failed; see above. redue remove undoes what setup wrote');
+  // The hooks' settings hold machine paths: keep them out of commits in this
+  // clone when Git does not ignore them.
+  if(git(root,'check-ignore','-q',localSettings).status===1){
+    fs.mkdirSync(path.dirname(exclude),{recursive:true});
+    const text=readText(exclude)??'';
+    fs.writeFileSync(exclude,`${text}${text&&!text.endsWith('\n')?'\n':''}${ignoreLine}\n`);
+    console.log(`update ${exclude}: ignore ${ignoreLine} in this clone`);
+    own.excludeAdded=true;save(own);
+  }
+  // An observer that is already running is what start would give.
+  const started=redue(['start'],{capture:true});
+  process.stdout.write(started.stdout);
+  if(started.status!==0){
+    if(!/already running/.test(started.stderr))throw Error(`the observer did not start: ${started.stderr.trim().replace(/^redue: /,'')}`);
+    console.log('Observer already running.');
+  }
+  // The observer indexes the project first; a run before that cannot be
+  // recorded as reusable. Wait while it plans and indexes; once its plan is
+  // ready, an observer that is still unhealthy says why in the status below.
+  // Nothing to wait for when no check can qualify.
+  const observation=()=>{const out=redue(['status','--json'],{capture:true});try{return JSON.parse(out.stdout).observation??null;}catch{return null;}};
+  // An answer without a phase (a stopped observer) for 10 s in a row ends the
+  // wait too.
+  const begun=Date.now();let told=-1,unread=0,phaseless=0;
+  for(let state=observation();ready.length&&!(state?.phase==='ready'||state?.phase==='unavailable')&&phaseless<10;state=observation()){
+    const seconds=Math.round((Date.now()-begun)/1000);
+    unread=state===null?unread+1:0;phaseless=state&&!state.phase?phaseless+1:0;
+    if(unread>=30)throw Error('the observer\'s status cannot be read; run redue status to see why');
+    if(seconds>15*60)throw Error(`the observer is not ready after 15 minutes (${state?.reason||state?.phase||'unknown'}); run redue status, then redue setup claude again`);
+    if(Math.floor(seconds/15)>told){told=Math.floor(seconds/15);console.log(seconds?`Still indexing (${seconds} s)...`:'Waiting for the observer to index the project...');}
+    await new Promise(resolve=>setTimeout(resolve,1000));
+  }
+  // One recorded run of each check that can qualify and is not CURRENT.
+  const statusOf=()=>{const out=redue(['status','--sync','--json'],{capture:true,timeout:600_000});try{return JSON.parse(out.stdout).checks;}catch{return [];}};
+  const rows=statusOf(),due=ready.filter(name=>rows.find(row=>row.name===name)?.freshness!=='CURRENT');
+  for(const name of due){console.log(`Recording ${name} once:`);redue(['run',name]);}
+  if(ready.length&&!due.length)console.log(`Already CURRENT: ${ready.join(', ')}.`);
+  for(const row of statusOf())console.log(`  ${row.name}: ${row.freshness}${row.result?' / '+row.result:''}${row.freshness==='CURRENT'?'':' — '+row.reason}`);
+  console.log('Done. Start a new Claude Code session in this project. Undo with redue remove.');
+  return {applied:true};
+}
+
+async function remove({root,redue,yes,record:own,recordFile,exclude,others}){
+  if(!own){console.log('No setup record for this checkout: nothing redue setup created to remove.');
+    console.log('To undo a setup made step by step: redue agent remove claude --apply, then redue remove-state.');return {removed:false};}
+  const configPath=path.join(root,configName),configText=readText(configPath);
+  const removeAgent=own.agentCreated&&fs.existsSync(path.join(root,agentRecord));
+  const removeHooks=!removeAgent&&own.hooksAdded&&claudeHooksInstalled(root);
+  const removeState=own.stateCreated&&fs.existsSync(own.state);
+  const deleteConfig=own.configCreated&&configText!==null&&hash(configText)===own.configHash;
+  // The ignore line goes only when no other checkout of this repository is
+  // set up: those rely on it too, whichever added it.
+  const removeIgnore=own.excludeAdded&&!others().length;
+  console.log(`Removing what redue setup created in ${root}`);
+  if(removeAgent)console.log('  remove the Claude Code integration');
+  if(removeHooks)console.log(`  remove REDUE's hooks from ${localSettings} (the integration predates setup)`);
+  if(removeState)console.log('  stop the observer and remove its local state (receipts included)');
+  else if(!own.stateCreated)console.log('  keep the observer state (it predates setup)');
+  if(own.configCreated&&configText!==null)console.log(deleteConfig?`  delete ${configName}`:`  keep ${configName} (edited since setup)`);
+  if(removeIgnore)console.log(`  remove ${ignoreLine} from ${exclude}`);
+  console.log(`  delete ${recordFile}`);
+  if(!await confirm('Proceed?',yes,{defaultYes:false})){console.log('Nothing removed.');return {removed:false};}
+  if(removeAgent)for(const line of removeIntegration(root))console.log(line);
+  if(removeHooks){const changed=removeClaudeHooks(root);if(changed)console.log(`update ${changed}`);}
+  if(removeState&&redue(['--state-dir',own.state,'remove-state']).status!==0)
+    throw Error('the observer state was not removed; see above. The config and setup record are kept so you can retry');
+  if(deleteConfig){fs.unlinkSync(configPath);console.log(`remove ${configName}`);}
+  if(removeIgnore){
+    const text=readText(exclude);
+    if(text!==null&&text.split('\n').includes(ignoreLine)){
+      fs.writeFileSync(exclude,text.split('\n').filter(line=>line!==ignoreLine).join('\n'));
+      console.log(`update ${exclude}`);}
+  }
+  fs.unlinkSync(recordFile);console.log(`remove ${recordFile}`);
+  // Folders the integration lived in, when nothing else is left in them.
+  for(const dir of ['.redue/agents','.redue','.claude/skills/redue-verification','.claude/skills','.claude'])
+    try{fs.rmdirSync(path.join(root,dir));console.log(`remove ${dir}/`);}catch{}
+  console.log('Done.');
+  return {removed:true};
+}

package/src/typescript-list.mjs

@@ -63,6 +63,14 @@ export function queriesMatch(queries) {
   return queries.every(([kind,file,answer,options])=>
     JSON.stringify(queryAnswer(kind,file,options))===JSON.stringify(answer));
 }
+// Why a recipe built on TypeScript's compiler API cannot use the TypeScript
+// installed at `tsRoot`, or null: TypeScript 7 is a native compiler and
+// ships no such API.
+export function compilerApiIssue(tsRoot) {
+  let version=null;try{version=JSON.parse(fs.readFileSync(path.join(tsRoot,'package.json'),'utf8')).version;}catch{}
+  return Number(String(version).split('.')[0])>=7?
+    `TypeScript ${version} is a native compiler without the compiler API this recipe reads; REDUE does not support TypeScript 7 yet`:null;
+}
 export function compilerFiles(tsRoot,cwd,config='tsconfig.json') {
   const require=createRequire(import.meta.url),ts=require(tsRoot);
   if(typeof ts.createProgram!=='function'||typeof ts.createCompilerHost!=='function')return null;

package/src/yarn-workspace-inputs.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {execFileSync} from 'node:child_process';
 import {createRequire} from 'node:module';
+import {compilerApiIssue} from './typescript-list.mjs';
 import micromatch from './glob.mjs';
 import {withinPath as within,realObservedPath} from './path-identity.mjs';
 
@@ -58,6 +59,8 @@ export function yarnWorkspacePackages(root){
 }
 
 function parsedTypeScript(root,dir){
+  const apiIssue=compilerApiIssue(path.join(root,'node_modules','typescript'));
+  if(apiIssue)throw Error(apiIssue);
   const require=createRequire(path.join(root,'package.json'));
   const ts=require(path.join(root,'node_modules','typescript'));
   const config=path.join(root,dir,'tsconfig.json'),reads=new Set();