@redue/cli 0.1.0-alpha.2 → 0.1.0-alpha.21

package/docs/user/node-script.md

@@ -0,0 +1,154 @@
+# 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 rewrites
+`node_modules/.pnpm-workspace-state-v1.json` at the first run after an
+install, through a temporary `node_modules/.tmpXXXXXX` file. vue-tsc writes
+`node_modules/.vue-global-types/*.d.ts` before it reads them. These files stay
+inputs. When they are the only files a run changed, and the run wrote them,
+the result is kept with the files as the run left them. A recorded process
+counts as writing a file it wrote; for pnpm's files, the pnpm executable must
+have run. A later change to them makes the result 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/npm-launcher-notice.md

@@ -0,0 +1,42 @@
+# npm launcher applicability correction — alpha.4
+
+Alpha.4 withdraws automatic applicability for npm-backed TypeScript checks using
+`typescript-noemit-v1`. Alpha.3 was demonstrated to admit an npm invocation whose
+update notification consumes unobserved remote responses, cache and time. Those
+inputs can change the outer npm result without changing the tracked project or
+caller identity. The controlled reproduction does not establish a public registry
+malfunction, affected-user count, or compiler completion in the failing npm case.
+
+Npm commands still execute exactly as configured through `redue run CHECK`.
+They still record PASS/FAIL. Previous PASS remains historical PASS; applicability
+is now UNVERIFIED, including after synchronization or a successful new npm run.
+This is a correction to the claimed boundary, not evidence that the code failed.
+Supported Yarn/pnpm and independently reviewed explicit contracts are unchanged.
+
+Until upgraded, do not rely solely on automatic npm CURRENT to skip the npm
+invocation. A different verification recipe requires explicit selection and fresh
+evidence; it cannot reinterpret an old npm receipt. Alpha.4 does not ship the
+experimental npm direct-compiler recipe or agent activation.
+
+## Upgrade without losing history
+
+First stop **every observer using this installation**, using each original config
+and any explicit state directory. Then upgrade that same installation and restart
+each observer with the same selections:
+
+```sh
+redue --config /path/to/project/redue.config.json stop
+npm install --global @redue/cli@0.1.0-alpha.4
+redue --config /path/to/project/redue.config.json start
+redue --config /path/to/project/redue.config.json status --sync
+```
+
+Repeat the stop/start commands for each project. If you originally used
+`--state-dir`, supply the identical directory on every REDUE command. If installed
+with a custom npm `--prefix`, supply the same prefix during installation. On Windows
+use `npm.cmd`/`redue.cmd` if required by existing PowerShell policy; do not change it.
+
+**Do not delete receipts or use `remove-state` as an upgrade step.** An upgraded
+client refuses an obsolete running observer interpretation and asks for stop/start.
+Restart reconciles existing state and preserves immutable historical runs. This
+correction does not silently change your project config or configured command.

package/docs/user/pilot.md

@@ -0,0 +1,146 @@
+# 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
+collected or uploaded automatically. External usage has **not started**. Earlier
+controlled compiler/agent trials are acceptance evidence, not independent adoption.
+
+## Check the boundary first
+
+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 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.
+
+Development-mode source-map support, Node preloads/inspectors/compile-cache
+overrides and `TS_ETW_MODULE_PATH` are unsupported. A few inert Node settings
+are accepted; see [Node settings](direct-typescript.md#node-settings). The injected
+`NODE_USE_ENV_PROXY=1` context is reviewed only on Node **22.13.0**; leave the
+environment and security controls intact. See the [full recipe boundary](direct-typescript.md).
+
+CLI/package mechanics are tested on macOS/APFS, native Linux and Windows/NTFS;
+Linux also needs Python 3 and [supported native storage](getting-started.md).
+Actual fresh-session behavior was tested with Codex **0.162.0 on macOS**, Node
+22.13.0 and the approved exact checkout/state/socket access. This is not general
+sandbox compatibility. Claude mechanics are tested, and the
+[Claude Code typecheck hook](agents.md#claude-code-typecheck-hook) was exercised in
+Claude Code 2.1.302 (`claude -p`). Broader Claude behavior and cross-host handoff
+are **NOT RUN**. The recording shortcut is macOS/direct-recipe only.
+
+## Install and connect explicitly
+
+For a new default npm installation:
+
+```sh
+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
+redue --config redue.config.json init --recipe typescript-direct --check typecheck
+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
+redue --config redue.config.json agent doctor codex --json
+```
+
+Use the discovered check name. Review both previews before applying. The recorded
+invocation is the resolved local Node/compiler with `--noEmit`, **not npm or its
+lifecycle scripts**. Neither init nor setup executes verification. An existing
+config is never overwritten; use the [deliberate check replacement procedure](direct-typescript.md#existing-npm-configuration-deliberate-replacement)
+without losing other checks or changing config/state identity. For an owned custom
+installation prefix or Windows command shims, use the [installation instructions](getting-started.md).
+
+Run doctor inside the agent's actual command boundary too. A healthy outside-shell
+result does not prove access. The owner must grant only the intended checkout,
+owned state directory and exact observer endpoint through supported host controls.
+The observer can write its index, run trusted configured probes in its own process
+context, reload receipts and stop; endpoint access is more than a file read.
+Do not disable sandboxing, bypass the proxy, or allow all sockets. If access is
+unavailable, record the limitation; an installed skill is not behavioral acceptance.
+See [access and diagnostics](agents.md). Doctor does not run verification or sync.
+
+Complete setup before the first real verification obligation. When that obligation
+arises, record the configured compiler check in the intended execution context:
+
+```sh
+redue --config redue.config.json run typecheck
+redue --config redue.config.json status --sync --json
+```
+
+A successful run may remain **UNVERIFIED**. Reuse needs understood schema, healthy
+observation, CURRENT, PASS and `reuse_eligible: true`; a receipt or exit code alone
+is insufficient. Recovery cannot repair a run's missing start observation. A later
+fully observed run can create new eligible evidence. Do not erase receipts to get green.
+
+Start a fresh agent session after connecting, then work normally. Keep ordinary
+task requests and explicit fresh-verification obligations; an explicit npm-script
+request still requires npm. Let later sessions occur naturally—do not manufacture
+edits, restarts or repeated queries to inflate reuse. Configured compiler evidence
+does not verify tests, npm lifecycle behavior or application correctness.
+
+## Update or leave without losing evidence
+
+Keep the pilot version fixed unless a real defect requires a reviewed update.
+Record any build boundary. Before replacing an installation, stop every observer
+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.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
+redue --config redue.config.json status --sync --json
+```
+
+Package installation alone does not update project instructions. Setup updates
+intact owned content, preserves unrelated text and refuses edited managed content.
+Review conflicts; do not delete ownership records to force an update. Setup metadata
+can invalidate prior applicability; reassess normally and start a fresh agent session.
+Historical receipts remain. See [the complete update procedure](agents.md#update-an-existing-connection).
+
+To disconnect and uninstall, using the same installation prefix when applicable:
+
+```sh
+redue --config redue.config.json agent remove codex --dry-run
+redue --config redue.config.json agent remove codex --apply
+redue --config redue.config.json stop
+npm uninstall --global @redue/cli
+```
+
+This preserves project config and receipts. Do not use `remove-state` for an upgrade
+or pilot exit. Edited managed content is left intact with a conflict for review.
+
+## Voluntary notes, reviewed before sharing
+
+Keep a small local note per real verification obligation, including setup failures
+and abandoned attempts. Use existing local receipts/tool history only when you
+choose; do not enable automatic transcript capture. Suggested fields:
+
+| Field | Record |
+| --- | --- |
+| Context | Build, OS/Node/compiler/host versions, anonymous project/session label |
+| Obligation | What actually needed verification; explicit fresh execution if requested |
+| Decision | Consulted? Agent-visible CURRENT/PASS/eligible, STALE, unsupported or unavailable? |
+| Outcome | Actual reuse with no equivalent execution; wrapped run; execution outside REDUE; or unresolved |
+| Evidence | Local before/after receipt IDs and actual commands, reviewed locally |
+| Cost | Measured setup/restart/query/recording/execution durations, if available |
+| Friction | What failed or confused; why you continued or stopped using REDUE |
+
+A CURRENT query is not automatically a saved run; an inspection needing no
+verification is not an avoided check. Do not infer a counterfactual from a receipt.
+Label estimated avoided compiler cost and its assumptions separately from measured
+time. Include recording, restarts and required reruns. Whole-task time alone does
+not establish causal speedup. The question is whether natural later reuse repays
+the cost of creating and maintaining evidence.
+
+Share only a voluntary owner-reviewed, redacted summary through the
+[existing issue tracker](https://github.com/msiric/redue/issues). Keep private source,
+paths, configuration bodies, credentials, receipts and raw transcripts out of public
+issues. Sensitive correctness/security reports use the repository's private security
+reporting channel. Maintain one short friction list, prioritize correctness first,
+and choose the next development task from observed usage rather than a benchmark target.

package/docs/user/receipt-selection-notice.md

@@ -0,0 +1,60 @@
+# Receipt selection correction in alpha.3
+
+**Known affected release: `@redue/cli@0.1.0-alpha.2`. Fixed in
+`@redue/cli@0.1.0-alpha.3`.** No exploit or affected-user count is established.
+REDUE remains an alpha.
+
+If a wrapper persisted a newer outcome but its observer reload notification
+failed, the observer could continue selecting an older passing receipt. Cached
+and synchronized status could then present that older result as CURRENT and
+eligible for reuse. A separate reproduced write-failure window left a new
+immutable outcome recorded while replacing the selected receipt failed.
+
+Until upgraded, do not rely solely on affected CURRENT output to skip checks.
+Run verification when needed and inspect its actual outcome; a successful status
+command is not proof that the latest execution passed.
+
+## What changes
+
+The observer refreshes REDUE-owned receipt selection before publishing status.
+Clients check that a response represents the current readable selection. Missing,
+unreadable, malformed, incompatible, or replaced selection cannot authorize
+reuse. A new client connecting to an alpha.2 observer returns UNVERIFIED and
+asks for a restart, even when the old response says CURRENT.
+
+A small owned pending-update record also withholds applicability after an
+incomplete receipt write. Successful recording clears only that check's pending
+entry. It does not discard another check's incomplete outcome or automatically
+promote an orphaned journal entry. Inspect the failed run and storage error, fix
+the storage problem, then record that check again. An unreadable/malformed pending
+record requires operator inspection; do not delete receipts to obtain green status.
+
+Historical PASS/FAIL and immutable `runs-v1` files remain intact. Stable applicable
+FAIL remains a failure and is never reuse-eligible. This guard tracks owned
+receipt replacement; it does not replace input-content validation or promise an
+atomic decision against concurrent edits/writes.
+
+## Upgrade and restart
+
+From each initialized project, stop its observer before replacing the installation.
+After all observers for that installation have stopped, upgrade it once, then
+restart each observer with its existing configuration and state selection:
+
+```sh
+redue stop
+npm install --global @redue/cli@0.1.0-alpha.3
+redue --version
+redue start
+redue status --sync --json
+```
+
+Use the same npm `--prefix`, project `--config`, and `--state-dir` you already use,
+if customized. On Windows use `npm.cmd`/`redue.cmd` where required by the existing
+shell policy. Stop all observers belonging to the installation before replacing
+it, then start each with the upgraded binary. For an independently installed
+candidate, its `stop` command can stop the older observer in the same explicitly
+selected owned state. Do not run `remove-state`; receipts need not be deleted.
+
+Restart preserves historical receipts and reconciles inputs. It does not promise
+CURRENT: a newer failure, unstable execution, incomplete contract, changed input,
+or observation uncertainty remains visible under the normal rules.

package/docs/user/supported-projects.md

@@ -12,18 +12,30 @@ is known. When npm is not pinned in `package.json`,
 leaves the version unknown rather than guessing if that inspection fails.
 
 At the repository root, `init` looks for existing typecheck, test, lint, and
-build scripts. It prefers familiar script names, then unique recognizable
+build scripts. It prefers familiar script names (for typecheck: `typecheck`,
+`type-check`, `check-types`, `check:types`, `types:check`, `tsc`, `types`,
+`lint:types`), then for typecheck one script named under such a name
+(`typecheck:test`, `tsc:build`; not a watch script), 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. It recognizes canonical
-`tsc --noEmit` on local npm installations as a candidate for automatic
-qualification. Before CURRENT is possible, a read-only probe checks the
-TypeScript configuration and effective file list, local compiler, installed
-contents, npm/Node identity, and relevant caller context. Unsupported plugins,
-preloads, config graphs, or outside-root inputs leave the check UNVERIFIED with
-an explanation. A discovered script can still be run and recorded in that
-state. Root and package-level npm/Yarn workspace scripts are discovered from
-`package.json` workspace declarations. Pinned Yarn 4 `node-modules`/classic
+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,
+configuration or outside-root inputs remain UNVERIFIED. Root and package-level npm/Yarn workspace scripts are discovered from
+`package.json` workspace declarations. In a workspace of more than 50
+packages, `init` proposes the root's checks only and names what it skipped;
+add package checks to the config yourself. Up to 1000 packages are read. Pinned Yarn 4 `node-modules`/classic
 workspaces with a standalone `tsc -p .` script, local TypeScript, a conventional
 `src` include, and Node module resolution can qualify automatically. For one
 workspace, use `redue init --workspace NAME --check typecheck`; it writes only
@@ -36,21 +48,42 @@ 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.
+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.
 
-Pinned pnpm 12 projects are read from `packageManager`, `pnpm-workspace.yaml`,
-the lockfile, and the installed `node_modules/.modules.yaml` metadata. The
+pnpm 9-12 projects are read from `packageManager`, `pnpm-workspace.yaml`,
+`.npmrc`, the lockfile, and the installed `node_modules/.modules.yaml`
+metadata. The installed metadata names the pnpm version; a `packageManager`
+pin is optional, and when present (with or without Corepack's `+sha512` hash)
+it must name the installed version. Settings that only change what gets
+installed are accepted, because the installed files are what REDUE observes.
+Settings that move or copy installed files, or run code during install, are
+not: custom `modulesDir`, `virtualStoreDir` or `lockfileDir`, the global
+virtual store, injected workspace packages, separate workspace lockfiles,
+pnpmfile hooks and `configDependencies`. They are refused when either
+`pnpm-workspace.yaml` or `.npmrc` sets them. The linker is read from the file
+the installed major reads (`.npmrc` for pnpm 9, `pnpm-workspace.yaml` then
+`.npmrc` for pnpm 10, `pnpm-workspace.yaml` for pnpm 11 and 12) and must match
+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 12'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
@@ -61,10 +94,10 @@ global virtual stores, injected workspace dependencies, and external links
 without an observed boundary remain recording-only with a reason. Installed
 files with hard-linked aliases outside the checkout remain recording-only on
 macOS: writes through an unseen alias cannot support CURRENT there. On Linux,
-redue watches project-installed file inodes and rehashes the selected
-installed inputs on every synchronized read. A cached read remains UNVERIFIED
-for these pnpm checks; a synchronized read can establish CURRENT after the
-rehash. If an inode watch cannot be installed, observation becomes unavailable
+redue watches project-installed file inodes and re-reads the identity of the
+selected installed inputs on every synchronized read. A cached read remains UNVERIFIED
+for these pnpm checks; a synchronized read can establish CURRENT after that
+re-read. If an inode watch cannot be installed, observation becomes unavailable
 instead of dropping that file. The global store is not watched. An absent
 optional package remains unqualified when Node could later
 resolve it from an unobserved ancestor `node_modules`; project-local candidate

package/docs/user/tests-direct.md

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