@redue/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## 0.1.0-alpha.19 — 2026-10-24
+
+A general recipe for typecheck and lint scripts that the strict recipes do not
+take. Test scripts stay on the direct test recipe (Vitest, Jest).
+
+- `redue init` tries the strict recipes first, then writes a general check
+  (`"qualification": "node-script-v1"`) for a root typecheck or lint script.
+  `redue run` runs the script through the project's package manager (npm,
+  pnpm 9-12 or Yarn with the `node-modules` linker) with REDUE's recorder in
+  every Node process, on macOS and Linux. The input is the whole checkout but
+  `.git`, `node_modules` and runner caches, plus every workspace
+  `node_modules` observed as installed files, the package manager and its
+  version, and the environment. See docs/user/node-script.md.
+- pnpm's launchers are trusted only when their text matches a template a pnpm
+  release writes (pnpm 8.0 to 12.14). The pnpm executable, Corepack's
+  pnpm-native included, is toolchain; its configuration files are kept by
+  content.
+- A run that starts a program REDUE does not record is UNVERIFIED and the
+  reason names it: native programs from installed packages (esbuild, turbo,
+  tsgolint, biome), git, find, and shells that read startup files.
+- `status` and the hook's skip message name the recipe that made the receipt
+  ("general recipe"). The Claude Code hook recognizes lint commands as it does
+  typecheck and test commands: `npm run lint`, `pnpm lint`, and for a script
+  that is one plain command, that command and its `npx` form.
+- In the census of 108 public TypeScript repos, the general recipe qualifies
+  23 typecheck and 21 lint scripts (both recorded runs clean, CURRENT after
+  the second). Of the scripts whose runs start only Node and the package
+  manager's own launchers (35 typecheck, 37 lint, measured with strace), init
+  proposes and observes about 21 and 22, and 18 of each qualify. The rest:
+  init does not pick script names such as `tsc:build`, fails in monorepos
+  over 50 packages, or refuses source directory links and custom install
+  setups; plans with submodules or dangling links are unavailable.
+- Known limits: on macOS, pnpm 12's temporary files in the project root can
+  arrive as an event on the root and make a run UNVERIFIED. Writes into
+  `node_modules` during a run make it UNVERIFIED, except pnpm's workspace
+  state and vue-tsc's global types, which stay inputs and are kept as the run
+  left them. A workspace's recording checks now leave out nested
+  `node_modules`, so `redue init` rewrites them once.
+
+- Contributors: `census.mjs --product` applies the product's own rule and
+  lists the files an unstable run touched; the eval kills a timed-out
+  command's whole process group; the agent eval has lint tasks.
+
+## 0.1.0-alpha.18 — 2026-10-23
+
+Typecheck in more project shapes, and pnpm test reuse on Linux. In the census
+of 108 public TypeScript repos, the ones `init` makes ready went from 8 to 11
+for typecheck (the census clones each repo's current head, so one or two
+repos move between runs) and stayed at 22 for tests.
+
+- pnpm test checks are reused on Linux. A recorded run accepts an installed
+  file hard-linked into the pnpm store the install recorded, when the store
+  holds it at its content address (pnpm names store files by their sha512).
+  Links anywhere else stay UNVERIFIED. Each file is hashed once; REDUE keeps
+  its identity and store path in its state and hashes it again only when the
+  identity changes. A 46 MB install takes about 160 ms to check the first
+  time. Limit: an in-place edit of an installed file in another project that
+  shares the store file is not seen until the next recorded run.
+
+- Typecheck scripts in more shapes. A script of `tsc --noEmit` runs with
+  `-p`/`--project`, `--skipLibCheck` or `--pretty`, in any argument order,
+  qualifies for the direct npm recipe and the pnpm contract. A chain of such
+  runs joined by `&&` becomes one check per run (`typecheck.1`,
+  `typecheck.2`); the hook skips the script only when every run is CURRENT
+  and otherwise runs the stale ones through `redue run`. `check-types` joins
+  the recognized script names.
+- The hook acts on a typecheck script's form only while the script in
+  package.json still has exactly the configured `tsc` runs. Before, a script
+  changed to `tsc --noEmit && eslint .` was rewritten to `redue run
+  typecheck`, which ran tsc alone.
+- Without a typecheck script, `init` proposes a `tsc --noEmit` check for a
+  root `tsconfig.json` (direct npm recipe, pnpm) and for each pnpm workspace
+  package with one, unless a script runs a TypeScript checker in another form
+  (`tsc -b`, `vue-tsc`, ...). package.json is not changed; the check is
+  written only when the contract holds.
+- The pnpm contract no longer needs `include: ["src"]`. Its source inputs are
+  the directories the config's `include` covers, as TypeScript computes them
+  for new files, minus `node_modules`. `exclude` entries stay inputs, since an
+  import can still reach an excluded file. A config extended from an installed
+  package is an installed input.
+- Fixed: a config with three or more pnpm or test checks never got a
+  synchronized answer. The observer dropped control requests over 4 KB, and a
+  sync request carries about 1.5 KB of context digests per check; status
+  showed "Unexpected end of JSON input" for every check. The limit is 1 MiB.
+
+- The direct npm TypeScript recipe takes any TypeScript 5.x or 6.0, not only
+  the five reviewed releases. Another release qualifies when package-lock.json
+  records the registry's `typescript` at that version with an integrity
+  (sha512, or sha1 from registries that record only sha1), npm's cache holds
+  the tarball under it, and the installed package is exactly the tarball's
+  files. Nothing is downloaded; a missing tarball
+  keeps the check recording-only with `npm-tarball-uncached`. The check takes
+  about 100 ms per full probe (TypeScript 5.x and 6.0 tarballs, 120-140 files).
+  CI runs the direct contract suite against 5.0.4, 5.1.6, 5.2.2, 5.3.3, 5.4.5,
+  5.5.4, 5.7.3 and 5.8.3.
+
+- Contributors: `npm test` runs up to four test files at a time, keeping two
+  cores free (a 3-core CI macOS runner runs one at a time), and takes about
+  6 minutes on the owner's Mac (was 19.6). The two TypeScript 6 fixture
+  suites are separate files so they run side by side.
+
 ## 0.1.0-alpha.17 — 2026-10-22
 
 Workspaces and package managers beyond npm. In the census of 108 public

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.17**. Follow the
+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.
 
@@ -76,10 +76,14 @@ Start with ordinary `status`. When it cannot establish caller context, use
 **Synchronization can cost more than rerunning a cheap check, particularly on
 Windows.** REDUE does not choose or execute that tradeoff for you.
 
-Since alpha.4, ordinary npm scripts are recording-only after
-[an npm launcher applicability gap](docs/acceptance/npm-launcher-boundary.md).
-A separate explicit [direct compiler recipe](docs/user/direct-typescript.md) can
-qualify supported npm typechecks. It does not claim that npm/lifecycle scripts ran.
+`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.
 
 ## Connect your agent (experimental)
 

package/bin/redue.mjs

@@ -4,7 +4,9 @@ import {mark,traceBase,traceContext,traceEnvironment,traceId} from '../src/decis
 traceBase({...traceContext(),request:traceId(),work:'client'});
 mark('client.loaded');
 import {directCompiler,directQualification,directEnvironment,directInterpretation} from '../src/direct-typescript.mjs';
+import {runArgv,tscRun} from '../src/typescript-invocation.mjs';
 import {testEnvironment,testRunnerAt,testsInterpretation,testsQualification} from '../src/test-direct.mjs';
+import {scriptEnvironment,scriptInterpretation,scriptKinds,scriptQualification} from '../src/node-script.mjs';
 import os from 'node:os';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
@@ -26,7 +28,7 @@ const help=`REDUE ${version}
 Usage: redue [--config FILE] [--state-dir DIR] COMMAND [OPTIONS]
 
 Commands:
-  init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct]
+  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]
   agent doctor [codex|claude] [--json]
@@ -245,6 +247,7 @@ const checks=publicConfig.checks.map(check=>{
   const npmDirect=check.qualification===directQualification;
   const pnpmTypecheck=check.qualification==='pnpm-tsc-v1';
   const testsDirect=check.qualification===testsQualification;
+  const generalScript=check.qualification===scriptQualification;
   if(check.script&&check.command&&!pnpmTypecheck&&!npmDirect&&!testsDirect)
     error(`${check.name}: choose script or command, not both`);
   const manager=publicConfig.packageManager;
@@ -254,10 +257,15 @@ const checks=publicConfig.checks.map(check=>{
     [`@which:${manager}`,'run',check.script]:null;
   const npmAutomatic=check.qualification==='typescript-noemit-v1';
   const yarnWorkspace=check.qualification==='yarn-workspace-tsc-v1';
-  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck&&!testsDirect)
+  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck&&!testsDirect&&!generalScript)
     error(`${check.name}: unknown qualification contract`);
-  if(npmDirect&&(manager!=='npm'||!check.script||check.cwd&&check.cwd!=='.'||
-    JSON.stringify(check.command)!==JSON.stringify(['@node','@typescript-compiler:.','--noEmit'])))
+  // The general recipe runs the root package script through the package manager.
+  if(generalScript&&(!['npm','pnpm','yarn'].includes(manager)||!check.script||check.command||check.cwd&&check.cwd!=='.'||
+    check.workspace||!scriptKinds.includes(check.kind)))
+    error(`${check.name}: the general recipe needs a root typecheck, test or lint script, without command or cwd`);
+  if(npmDirect&&(manager!=='npm'||check.cwd&&check.cwd!=='.'||!Array.isArray(check.command)||
+    check.command[0]!=='@node'||check.command[1]!=='@typescript-compiler:.'||
+    !tscRun({},{script:null,args:check.command.slice(2)}).run?.noEmit))
     error(`${check.name}: direct recipe requires its explicit local compiler command`);
   // The script's own arguments follow the runner; qualification compares them with the script.
   if(testsDirect&&(!['npm','pnpm','yarn'].includes(manager)||!check.script||check.cwd&&check.cwd!=='.'&&!check.workspace||!Array.isArray(check.command)||
@@ -270,25 +278,32 @@ const checks=publicConfig.checks.map(check=>{
     check.command[1]!=='workspace'||check.command[2]!==check.workspace||
     check.command[3]!=='run'))
     error(`${check.name}: Yarn workspace qualification needs its discovered workspace command`);
-  if(pnpmTypecheck&&(manager!=='pnpm'||!check.script||!check.command||
+  if(pnpmTypecheck&&(manager!=='pnpm'||!Array.isArray(check.command)||
     check.command[0]!=='@node'||
     check.command[1]!==`@typescript-bin:${check.cwd||'.'}`||
     check.workspace&&check.cwd==='.'||
-    !check.command.slice(2).every(value=>typeof value==='string'&&value)))
+    !tscRun({},{script:null,args:check.command.slice(2)}).run))
     error(`${check.name}: pnpm qualification needs its discovered standalone TypeScript command`);
   const reason=check.kind==='test'?'test runtime, transforms and cache inputs need review':
     check.kind==='lint'?'lint plugins, config and resolver inputs need review':
     check.kind==='build'?'build environment and generated inputs need review':
     'check inputs need review';
-  const autoProbes=npmDirect?[['@node','@vstate/direct-typescript-probe','@project',check.script]]:npmAutomatic?[['@node','@vstate/typescript-contract-probe',
+  // A chained script has one check per tsc run: each check's run counts them,
+  // so a run added to or removed from the script invalidates them all.
+  const runCount=(npmDirect||pnpmTypecheck)&&check.script?publicConfig.checks.filter(other=>
+    other.qualification===check.qualification&&other.script===check.script&&
+    (other.cwd||'.')===(check.cwd||'.')&&(other.workspace||null)===(check.workspace||null)).length:1;
+  if(runCount>16)error(`${check.name}: more than 16 checks for script ${check.script}`);
+  const run=npmDirect||pnpmTypecheck?runArgv({script:check.script??null,args:check.command.slice(2),count:runCount}):null;
+  const autoProbes=npmDirect?[['@node','@vstate/direct-typescript-probe','@project',...run]]:npmAutomatic?[['@node','@vstate/typescript-contract-probe',
     '@project',check.script,'@which:npm']]:yarnWorkspace?
     [['@node','@vstate/yarn-workspace-typecheck-probe','@project',
       check.workspace,check.command[4],'@which:yarn']]:pnpmTypecheck?
     [['@node','@vstate/pnpm-typecheck-probe','@project',
-      check.workspace||'.',check.script]]:[];
+      check.workspace||'.',...run]]:[];
   const windowsContext=process.platform==='win32'?
     ['ComSpec','COMSPEC','PATHEXT','USERPROFILE']:[];
-  const autoEnvironment=npmDirect?directEnvironment:testsDirect?testEnvironment:npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
+  const autoEnvironment=npmDirect?directEnvironment:testsDirect?testEnvironment:generalScript?scriptEnvironment(manager):npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
     'NODE_ENV','BASH_ENV','ENV',...windowsContext],prefixes:['npm_config_','DYLD_','TSGO_'],
     pathExecutables:['node','npm'],executableIdentity:true}:yarnWorkspace?
     {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
@@ -310,9 +325,11 @@ const checks=publicConfig.checks.map(check=>{
     coverageReasons:check.coverageReasons||Object.fromEntries(
       categories.map(category=>[category,reason])),
     qualification:check.qualification||null,script:check.script||null,
+    ...(runCount>1?{runCount}:{}),
     ...(npmAutomatic?{qualificationInterpretation:'npm-launcher-withheld@1'}:{}),
     ...(npmDirect?{qualificationInterpretation:directInterpretation}:{}),
     ...(testsDirect?{qualificationInterpretation:testsInterpretation}:{}),
+    ...(generalScript?{qualificationInterpretation:scriptInterpretation}:{}),
     workspace:check.workspace||null,kind:check.kind||null};
 });
 const runtime={schema:1,provider:'declared-project@1',root,state,checks};

package/docs/user/agents.md

@@ -122,6 +122,17 @@ post-scripts. In every other case the command runs as typed: turbo caches its
 own results, so the hook never rewrites it. Filters (`--filter`) and nx are not
 matched.
 
+For a typecheck check that runs the compiler, the script's forms act only when
+the script in package.json still has exactly the configured runs: one `tsc`
+run per check with the same arguments, and no pre- or post-script. Otherwise
+the command runs as typed. A script that chains `tsc` runs with `&&` has one
+check per run, `typecheck.1`, `typecheck.2` and so on (see
+[direct TypeScript](direct-typescript.md#script-forms)); each run's own
+`npx tsc ...` form matches its check. The hook skips the script when all its
+runs are CURRENT, PASS and `reuse_eligible`, and otherwise rewrites it to
+`redue run` of the runs that are not, in the script's order, joined by `&&`.
+In a turbo or `pnpm -r` fan-out, a package's script counts only the same way.
+
 Each form may end with `2>&1` and then one `| tail -n N`, `| head -n N`,
 `| 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

package/docs/user/configuration.md

@@ -30,6 +30,8 @@ out of version-controlled configuration.
 
 For the explicit direct compiler choice and generated exact argv, see
 [direct TypeScript](direct-typescript.md). Existing script receipts cannot satisfy it.
+A general check (`"qualification": "node-script-v1"`) has a `script` and no
+`command`; see the [general recipe](node-script.md).
 
 ## Arbitrary commands
 
@@ -56,6 +58,10 @@ 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.
 
+A chained typecheck script gets one generated check per `tsc` run, all with
+the script's name (see [script forms](direct-typescript.md#script-forms)). A
+proposed check for a project without a typecheck script has no `script`.
+
 Input patterns are relative to the project root. They cannot name a `.git`
 directory, because REDUE does not observe one; `!.git/**` is fine.
 

package/docs/user/direct-typescript.md

@@ -4,8 +4,10 @@ This check means: the reviewed local TypeScript compiler completed the configure
 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/6.0.2/6.0.3:
+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)):
 
 ```sh
 redue init --recipe typescript-direct --check typecheck --dry-run
@@ -33,9 +35,64 @@ 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, 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.
+and no shell. The entry is `lib/_tsc.js` where the package has one (5.7 and
+later), without its outer compile-cache-enabling shim, and `lib/tsc.js`
+otherwise. No compiler is fetched or bundled.
+
+## Compiler identity
+
+The entire installed `node_modules/typescript` must be an official package,
+byte for byte, in one of two ways:
+
+- TypeScript 5.5.2, 5.6.3, 5.9.3, 6.0.2 or 6.0.3: its files match the digest
+  REDUE ships for that release.
+- Any other TypeScript 5.x or 6.0 release: package-lock.json records the
+  registry's `typescript` package at the installed version (no alias, an
+  `https` tarball URL, not a file or git source) with an integrity (sha512,
+  or sha1 where a registry records only sha1), npm's cache holds the tarball
+  under that integrity, and the installed files are exactly the tarball's
+  files. REDUE reads the cache only; it never downloads. The cache is the one
+  npm uses: `npm_config_cache`, else `cache` in the project's `.npmrc`, then
+  the user's, else `~/.npm` (`%LocalAppData%\npm-cache` on Windows); the
+  global npmrc is not read. `npm-shrinkwrap.json` is not read on this path.
+  `npm ci` fills the cache. When the tarball is missing the check stays
+  recording-only with the reason `npm-tarball-uncached`; `npm cache add
+  typescript@VERSION` adds it. The check's compiler identity is then the
+  lockfile integrity, so a lockfile change re-probes.
+
+CI runs the same contract suite against the last release of each minor from
+5.0 to 5.8 that the reviewed releases do not cover. Later minors (6.1 and up)
+wait until CI covers them. TypeScript 7 (the native compiler) is not
+supported.
+
+## Script forms
+
+A typecheck script qualifies when it is one or more `tsc` runs joined by `&&`,
+each with `--noEmit` and only these arguments, in any order: `-p`/`--project`
+with a config file or directory inside the project, `--skipLibCheck`, and
+`--pretty` (optionally `true` or `false`). For example
+`tsc -p tsconfig.app.json --noEmit` or
+`tsc --noEmit && tsc --noEmit -p tsconfig.node.json`. `tsc -b`, `--watch`,
+other options, quotes, variables and other commands keep the script
+recording-only.
+
+A chain gets one check per run, named `typecheck.1`, `typecheck.2` and so on,
+each with the script's name and that run's arguments in its command. Each run
+is checked as its own program against its own config, and is reused only while
+the script still has as many runs as the config has checks for it, one of them
+with exactly those arguments. Adding or removing a run, or a pre- or
+post-script, makes every check of the script not reusable until `init` runs
+again. The script as a whole
+(`npm run typecheck`) is skipped only when its current runs and the configured
+checks correspond one to one and all are CURRENT (see [agents](agents.md)).
+
+With no typecheck script and a root `tsconfig.json`, init proposes a
+`tsc --noEmit` check with no `script` field, unless a script already runs a
+TypeScript checker in another form (`tsc -b`, `vue-tsc`, `svelte-check`,
+`tsgo`, `astro check`, `nuxi typecheck`). package.json is not changed. The
+check is written only when the contract holds; otherwise no typecheck check is
+added. The pnpm contract does the same for each workspace package with a
+`tsconfig.json` and no typecheck script.
 
 Existing configs are never overwritten. To compare choices, use a new project-local
 `--config redue.direct.config.json` with init; this explicitly selects separate

package/docs/user/getting-started.md

@@ -82,9 +82,10 @@ Use a check actually printed by `init`. For a workspace:
 `redue init --workspace @example/package --check typecheck`.
 Initialization previews detected commands and qualification confidence before writing
 `redue.config.json`. An existing config is never overwritten. No checks are run and
-no dependencies installed. A missing/unsupported boundary is explained. Npm-launcher typechecks are
-recording-only in alpha.4; a passed execution is historical PASS with UNVERIFIED
-applicability, not reusable CURRENT.
+no dependencies installed. A missing/unsupported boundary is explained. `init` tries
+the strict recipes first and uses the [general recipe](node-script.md) for a root
+typecheck or lint script none of them takes. Test scripts use the
+[direct test recipe](tests-direct.md).
 
 “Ready to qualify” means REDUE has a supported recipe whose prerequisites will be
 validated. It is not a receipt. “Recording-only” can record PASS/FAIL without claiming
@@ -92,10 +93,9 @@ reusability. Qualification can change when configuration or installation changes
 
 `run` streams normal output and preserves execution environment and cancellation.
 For the narrow pnpm TypeScript contract, `init` explicitly shows the direct installed
-compiler invocation it selects. Npm scripts remain recording-only;
-use `redue init --recipe typescript-direct --dry-run` to preview a distinct,
-explicit [local compiler recipe](direct-typescript.md). Other scripts run through
-the package manager. No existing configuration is silently migrated.
+compiler invocation it selects, and for npm the
+[local compiler recipe](direct-typescript.md). General checks and other scripts
+run through the package manager. No existing configuration is silently migrated.
 Only use configs and probes from trusted repositories: these execute local code.
 
 `status` is cached and conservative. `status --sync` and `explain` revalidate caller

package/docs/user/node-script.md

@@ -0,0 +1,153 @@
+# General recipe (typecheck and lint scripts)
+
+The general recipe records a project's own typecheck or lint script, run
+through its package manager, and reports later whether that result still
+applies to the files you have. It is a lower tier than the strict recipes:
+`redue init` tries the [direct TypeScript recipe](direct-typescript.md), the
+pnpm and Yarn TypeScript recipes and the [direct test recipe](tests-direct.md)
+first, and uses the general recipe for a root typecheck or lint script none of
+them takes. Test scripts use the direct test recipe; `init` does not propose
+the general recipe for them.
+
+It supports a project installed by npm, pnpm 9-12 (isolated or hoisted
+`node_modules`) or Yarn with the `node-modules` linker, with one lockfile kind
+matching any `packageManager` declaration, on macOS and Linux with Node 22 or
+24. Workspaces are supported for root scripts. `init --recipe node-script`
+writes general checks only.
+
+## Setup
+
+```sh
+redue init
+redue start
+redue run lint
+redue status --sync
+```
+
+The config gets one field for the recipe, written by `init`:
+
+```json
+{"name": "lint", "script": "lint", "kind": "lint", "qualification": "node-script-v1", "inputs": ["**", "..."]}
+```
+
+`redue run lint` runs `npm run lint` (or `pnpm run lint`, `yarn run lint`) with
+REDUE's recorder loaded in every Node process, and npm's and pnpm's update
+checks turned off. With the Claude Code hook, `npm run lint`, `pnpm lint` and,
+for a script that is one plain command such as `eslint .`, that command itself
+and `npx eslint .` are recognized like typecheck and test commands.
+`status` and the hook's skip message name the recipe that made the receipt.
+
+## What REDUE claims
+
+CURRENT means the last run's inputs are unchanged:
+
+- every file in the checkout, except `.git`, every `node_modules`, the runner
+  caches listed below and the files the run itself wrote;
+- the installed files in the root's and every workspace package's
+  `node_modules`, and Yarn's install state, by file identity;
+- the lockfile and `package.json`, as files of the checkout;
+- the package manager's executable and Node, by file identity, and the exact
+  script;
+- every environment variable the run's JavaScript read directly, and always
+  `TZ`, `LANG`, `PATH`, `HOME`, `CI`, `XDG_CONFIG_HOME` and every `NODE_*`,
+  `LC_*`, `VITE_*`, `DYLD_*`, `LD_*`, `npm_config_*`, `pnpm_config_*`,
+  `PNPM_*`, `COREPACK_*` and `YARN_*` variable;
+- the executables of npm, pnpm, Yarn and Corepack on PATH, by file identity,
+  since a script may run another package manager;
+- small files read outside the checkout (up to 1 MB), by content, and lookups
+  outside it, asked again before each answer.
+
+Runner caches are not inputs, and a run may read and write them: `.cache`,
+`.vite`, `.vitest`, `.turbo`, `.nx`, `.swc`, `.jest-cache`, `.parcel-cache`,
+`.angular/cache`, `.next/cache` and `.tmp` directories, `*.tsbuildinfo`,
+`.eslintcache`, `.stylelintcache`, `.prettiercache`, and the
+`_tmp_<pid>_<hex>` files pnpm writes and removes at every run. A file with
+such a path that git does not ignore is source: reading it makes the run
+UNVERIFIED. At the top of each `node_modules`, only `.cache`, `.vite`,
+`.vite-temp`, `.vitest` and `.vitest-cache` are left out, and `*.tsbuildinfo`
+anywhere in it.
+
+Two installed files are rewritten by tools during a run: pnpm's
+`node_modules/.pnpm-workspace-state-v1.json` at the first run after an
+install, and the `node_modules/.vue-global-types/*.d.ts` files vue-tsc writes
+before it reads them. They stay inputs. When they are the only files a run
+changed, and the run wrote them (a recorded process wrote the file, or the
+pnpm executable ran, for its state), the result is kept with the files as the
+run left them, and a later change to them makes it STALE.
+
+It does not mean a rerun would give the same result: a test that depends on
+the time or on randomness can pass now and fail later on the same inputs.
+
+## Programs
+
+The recorder sees only Node processes. Every other program a run starts must be
+one REDUE can account for:
+
+- `sh` or `dash`, or `bash` without `BASH_ENV`, running a command that, read
+  as text, starts only Node programs, package managers and shell builtins
+  (`cd`, `echo`, `true`, `export`, `exec` and a few more). Words are looked up
+  on the PATH the shell got. A Node program is the Node executable, a file
+  whose `#!` line runs Node, or a pnpm launcher. A version manager's `node`
+  shim (asdf, nodenv) is a script and does not count. Other shells read
+  startup files and are refused. The shell must still have REDUE's recorder in
+  `NODE_OPTIONS`: npm's and pnpm's `node-options` setting replaces it, and a
+  run under such a setting is UNVERIFIED;
+- a pnpm launcher in `node_modules/.bin`: the `#!/bin/sh` script pnpm writes,
+  which runs `sed`, `dirname`, `uname` or `readlink` before it starts Node. It
+  is trusted only when its text is exactly one of the templates pnpm 8.0 to
+  12.14 write (`src/pnpm-shim-templates.json`), with only the bin file and
+  `NODE_PATH` filled in;
+- the pnpm executable (pnpm 12, also the copy Corepack downloads): REDUE cannot
+  see what it does, so the scripts it runs are read as text the same way,
+  their `pre` and `post` scripts included. Filters and recursive runs
+  (`--filter`, `-r`) are refused. At least one Node process it starts must
+  have loaded the recorder, and its configuration files outside the checkout
+  (`pnpm/rc`, `pnpm/config.yaml`, `~/.npmrc`, the global `npmrc`) are kept by
+  content;
+- `ps -A -o ppid,pid`, which pnpm loaded into Corepack runs.
+
+Anything else makes the result UNVERIFIED and names the program: `git`,
+`sleep`, `find`, and native programs from installed packages such as esbuild,
+turbo, tsgo, tsgolint and biome, whose reads, writes and network use REDUE
+cannot see. `init` reads the script the same way and keeps a script that
+starts such a program recording-only, with the program in the reason.
+
+A command line may use `&&`, `||`, `;`, `|`, quotes without expansions,
+globs in arguments and redirection to `/dev/null`. Variables, command
+substitution, input redirection, subshells, here-documents and `command -p`
+are refused. Setting or clearing `NODE_OPTIONS`, `PATH`, `REDUE_RUN_RECORD`,
+`BASH_ENV`, `ENV`, or npm's or pnpm's `node-options` or `script-shell` is
+refused, since it could stop a Node process from loading the recorder.
+`node --env-file` and Node's config-file options are refused: Node reads those
+files natively. `process.loadEnvFile` is recorded as a read.
+
+## The guard
+
+As in the [direct test recipe](tests-direct.md#the-guard), the result is kept
+but marked UNVERIFIED, with the reason, when the run read a git-ignored file
+REDUE does not observe and did not create first, changed an input during the
+run (a formatter's `--write`, a generated `version.ts`), listed a directory or
+read a large file outside the checkout, used the network, or started a program
+REDUE does not account for. Reads through a workspace package's link in
+`node_modules` count where the link leads.
+
+The package managers' own installations, Corepack's downloads and npm's log
+directory are toolchain, identified by the package manager's executable, not
+inputs.
+
+## Limits
+
+- On macOS, a file created and removed directly in the project root during a
+  run (pnpm 12 does this) can be reported by the file watcher as an event on
+  the root itself, an observation gap that makes the run UNVERIFIED. Linux
+  reports the file, which is not an input.
+- The pnpm executable and the pnpm launchers' helpers are trusted as
+  toolchain: what they read is not checked.
+- Code that copies the environment and reads the copy, and native code that
+  reads files or variables (native addons such as Rust-based resolvers), is
+  not seen.
+- A project whose `.npmrc` sets `node-options` stays UNVERIFIED: npm replaces
+  `NODE_OPTIONS` with it, which drops REDUE's recorder.
+- A script that runs a build first (`npm run build && tsc --noEmit`) usually
+  starts esbuild or another native bundler and stays UNVERIFIED.
+- Windows is not supported; the check stays recording-only there.

package/docs/user/pilot.md

@@ -1,4 +1,4 @@
-# Opt-in development pilot: alpha.17
+# Opt-in development pilot: alpha.18
 
 Use one fixed build for several ordinary development sessions. The owner will
 invite two or three willing testers and approve their projects; nothing is
@@ -9,8 +9,9 @@ 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, 5.9.3, 6.0.2 or 6.0.3** packages and Node **22 or 24**. No workspaces, named
+scripts. The direct recipe accepts only an official, unchanged TypeScript **5.x or
+6.0** package (a reviewed release, or one matching the tarball package-lock.json
+names in npm's cache) 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 +36,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.17
+npm install --global @redue/cli@0.1.0-alpha.18
 redue --version
 cd my-project
 redue --config redue.config.json init --recipe typescript-direct --check typecheck --dry-run
@@ -89,7 +90,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.17
+npm install --global @redue/cli@0.1.0-alpha.18
 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

@@ -15,11 +15,17 @@ At the repository root, `init` looks for existing typecheck, test, lint, and
 build scripts. It prefers familiar script names, then unique recognizable
 `tsc`, Vitest/Jest, ESLint, or Vite commands under other names. Multiple
 matches are reported as ambiguous rather than guessed. It never creates a new
-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/6.0.2/6.0.3 and Node 22/24. It executes the local compiler,
+project script. Without `--recipe`, `init` tries the strict recipes below first,
+then the [general recipe](node-script.md) for a root typecheck or lint
+script: the script run through the package manager with every Node process
+recorded and the whole checkout as its input. `--recipe typescript-direct`,
+`tests-direct` or `node-script` selects one recipe alone. The direct TypeScript recipe supports
+a typecheck script of `tsc --noEmit` runs in any argument order, chained runs,
+or no typecheck script at all (a proposed `tsc --noEmit`; see
+[script forms](direct-typescript.md#script-forms)), in a single-package npm installation using
+TypeScript 5.x or 6.0 (a reviewed release, or one whose installed files match the
+tarball package-lock.json names in npm's cache; see
+[compiler identity](direct-typescript.md#compiler-identity)) 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,
@@ -37,11 +43,11 @@ When an internal dependency is consumed through built declarations, changing
 only its source does not stale the selected check until the consumed output
 changes. Unsupported custom resolution, project references, outside-root
 source links, and installation modes remain recording-only. Other Yarn
-typechecks, Vitest/Jest, ESLint, and builds start recording-only unless a
-separately justified explicit contract is provided. For a single-package npm
-project whose test script runs Vitest 4/5 or Jest 29 directly, the opt-in
-`init --recipe tests-direct` records the run and guards its inputs; see
-[direct tests](tests-direct.md).
+typechecks, Vitest/Jest, ESLint, and builds in workspace packages start
+recording-only unless a separately justified explicit contract is provided.
+For a single-package project whose test script runs Vitest 4/5 or Jest 29
+directly, `init` uses the direct test recipe, which records the run and guards
+its inputs; see [direct tests](tests-direct.md).
 In particular, test caches and build-generated inputs are not excluded to
 make evidence green.
 
@@ -62,12 +68,17 @@ the installed one. Only the project's files are read: settings from a user or
 global rc file, or `npm_config_*` variables during install, are not. The
 supported local layouts are pnpm's standard isolated and hoisted
 `node_modules` with a project-local `.pnpm` virtual store. `init` can discover
-root and workspace scripts. For a standalone `tsc --noEmit` or `tsc -p ...`
-script in the narrow TypeScript contract, it records the exact installed
-compiler invocation directly. This avoids pnpm's task-run bookkeeping
+root and workspace scripts. For a typecheck script of `tsc` runs
+([script forms](direct-typescript.md#script-forms); `tsc -p .` without
+`--noEmit` is also accepted), or a package with a `tsconfig.json` and no
+typecheck script, it records the exact installed compiler invocation directly.
+The source inputs are the directories the config's `include` covers, as
+TypeScript itself computes them for new files, minus `node_modules` (`exclude`
+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` and
-start recording-only. The generated `@typescript-bin:WORKSPACE` token resolves
+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
 the local compiler when the check runs; it is not an absolute machine path.
 
 The pnpm contract indexes consumed installed package contents inside the