@redue/cli 0.1.0-alpha.3 → 0.1.0-alpha.30

package/docs/user/sandbox.md

@@ -0,0 +1,312 @@
+# Sandboxed recipe (typecheck, lint and tests, any language)
+
+The sandboxed recipe runs a typecheck, lint or test command inside an operating
+system sandbox and reports later whether that result still applies to the
+files you have. The sandbox holds for every process the command starts, so it
+covers programs REDUE cannot record: TypeScript 7's native compiler, esbuild,
+oxlint and tsgolint, biome, turbo, and Python tools such as mypy, pyright, ty
+and ruff, and test runners such as pytest.
+
+**The claim.** A sandboxed result holds for a run that sees only the project's
+files that git doesn't ignore, except its documentation, its installed
+packages and the toolchain, the way CI does. It does not say that a run with
+your own configuration files, a service on your machine or the network would
+give the same result.
+
+A check that reads the documentation (a doctest over `README.md`) sees it
+too. A check that needs files git ignores (generated code, another package's
+built declarations) gets the whole checkout. See
+[hidden files](#files-git-ignores-and-documentation).
+
+## Where it applies
+
+- **Tests:** a root `test` script, and pytest in the project's `.venv`. See
+  [tests](#tests). For a Node test script, `init` tries the sandbox before the
+  [direct test recipe](tests-direct.md), which becomes the fallback, when
+  both would run the same script. In the
+  census, on the repos where both qualified, the direct recipe's results went
+  STALE when the project's build rewrote its output, and the sandboxed ones,
+  with ignored files hidden, stayed CURRENT.
+- **Node projects:** a root `typecheck` or `lint` script (npm, pnpm, or Yarn
+  with the `node-modules` linker). `init` tries the
+  [direct TypeScript recipe](direct-typescript.md) and the pnpm and Yarn
+  TypeScript recipes first; they stay first where they apply. Then the
+  sandboxed recipe, before the [general recipe](node-script.md), since it
+  also covers the native programs a script starts. Where init's trials show
+  a difference, or the sandbox cannot run, `init` writes the general recipe
+  as before. Where the sandbox cannot start at run time (inside Claude Code's
+  macOS sandbox), a script the general recipe takes is recorded as it records
+  it.
+- **Python projects:** mypy, pyright, ty and ruff installed in the project's
+  `.venv` (`uv sync` makes one; Poetry does with `virtualenvs.in-project`).
+  `init` uses the arguments your CI workflow, Makefile, tox, nox, justfile or
+  shell scripts in `scripts/` run the tool with, through `uv run`, `poetry run`,
+  `python -m` or `.venv/bin`. Without them it uses the tool's default:
+  `ruff check`, `ty check`, `pyright`, and `mypy` (with `.` when mypy's
+  configuration names no `files`).
+- **Platforms:** macOS (Seatbelt, `sandbox-exec`) and Linux 6.7 or later
+  (Landlock; the launcher needs Python 3).
+
+```sh
+redue init
+redue start
+redue run typecheck
+redue status --sync
+```
+
+A Python check in the config:
+
+```json
+{"name": "typecheck", "kind": "typecheck", "qualification": "sandbox-v3",
+ "command": [".venv/bin/mypy", "src"], "inputs": ["**", "..."], "installedInputs": [".venv/**", "..."]}
+```
+
+A Node check names its script, as the general recipe's do:
+`{"name": "lint", "script": "lint", "kind": "lint", "qualification": "sandbox-v3", ...}`.
+`sandbox-v3` hides the files git ignores and the documentation from the run,
+`sandbox-v2` only the files git ignores; `sandbox-v1` runs it on the whole
+checkout.
+
+With the Claude Code hook, `uv run mypy src`, `poetry run mypy src`,
+`python -m mypy src`, `.venv/bin/mypy src` and `mypy src` are recognized as
+that check. The last two count only when PATH finds the tool or Python in the
+project's `.venv/bin` first. When the hook runs the check through REDUE, it
+keeps `uv run` or `poetry run` in front, so the environment still syncs first.
+
+## Files git ignores and documentation
+
+`init` runs each check plainly, then sandboxed with the files git ignores and
+the documentation hidden. When both give the same result, it writes
+`sandbox-v3`. When the plain run passed and the sandboxed one failed only
+because it was refused a file it hid (no other refusal line, and not a line
+the plain run printed too), it writes `sandbox-v1` (the whole checkout)
+without running it again: without the hiding, a run can then only fail
+where a plain one passes, never pass where it fails. When the runs differ
+in another way, `init` runs the check once more with the whole checkout,
+reusing the plain run, and writes `sandbox-v1` only if that agrees. So a
+check runs two or three times at init, not four. `init` no longer writes
+`sandbox-v2`; a check already set up with it keeps it.
+
+With `sandbox-v3`, each run also hides the documentation: the files git
+lists (and does not ignore) named `*.md`, `*.mdx`, `*.rst`, `LICENSE*` or
+`CHANGELOG*` anywhere, and text, image and PDF files (`.txt`, `.adoc`,
+`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.pdf`) in the root `docs/`
+folder. Code in `docs/` (examples a typecheck includes) is not hidden, and
+folders stay listable. The receipt names the files the run hid. A later edit
+to one of them, or its deletion, leaves the result CURRENT: editing the
+README does not make the tests STALE. A new documentation file, a link named
+like one, or a change made while the run ran still counts. On macOS the
+files with those extensions are refused by name pattern, in any case and in
+`node_modules` too: `README.MD` or `Docs/logo.svg` is refused but not
+listed, so an edit to it counts, and a check that reads one gets
+`sandbox-v1` on macOS. `LICENSE*` and `CHANGELOG*` files are refused by the
+exact paths git lists, so `license-check.ts` stays readable. On Linux each
+listed file is hidden like a git-ignored one. In a checkout with more than
+100 `LICENSE*` and `CHANGELOG*` files (vendored packages), those files are
+not hidden on either platform and count as inputs.
+
+With `sandbox-v2`, each run hides what `git ls-files --others --ignored
+--exclude-standard --directory` lists, except `node_modules`, `.venv` and
+runner caches: build output (`dist/`, `.next/`), coverage files, `.env` files.
+Only the project's rules count: its `.gitignore` files and
+`.git/info/exclude`, not your global excludes file. Those files are not
+inputs, so a build or test run that writes them leaves the result CURRENT.
+
+When a `sandbox-v2` or `sandbox-v3` run fails with a refusal that names a
+hidden file (a missing file counts only when it names one, since Linux tools
+report an unreadable file as missing), REDUE runs the check again in the
+sandbox without hiding anything. That result is kept and compared on every
+file, git-ignored ones and documentation included. Run `redue init` again to
+write another recipe for a check that keeps needing them.
+
+## What the run sees
+
+It may read and execute only beneath:
+
+- the checkout, without the files git ignores for `sandbox-v2`, and without
+  its documentation too for `sandbox-v3`;
+- the toolchain: Node's installation and the package managers' (with
+  Corepack's downloads), or the Python installation the `.venv` was made from;
+- system directories (`/usr`, `/bin`, `/etc` and the like on Linux; `/usr`,
+  `/System`, `/Library`, `/opt/homebrew` and the like on macOS);
+- a private home directory and a fresh temporary directory, in REDUE's state.
+
+A typecheck or lint has no network: no TCP connection, loopback included
+(a test run on Linux gets loopback; see [tests](#tests)). On macOS its only
+Unix sockets are in its own temporary directory, which is new for each run.
+On Linux 6.12 and later it cannot reach an abstract Unix socket outside the
+run.
+
+What the check leaves running is stopped when it exits, as at the end of a
+CI job: its process group gets SIGTERM, and SIGKILL a second later. On Linux
+the launcher also stops daemons that started their own session. On macOS
+such a daemon outlives the run, but no later run can reach it: its socket
+was in a temporary directory that is gone. The run gets no terminal input.
+
+The checkout's `.git` is not an input. Tools still see it, as they do in a CI
+checkout (a linter that applies `.gitignore` only inside a repository does),
+but git commands find no repository: `GIT_DIR` points nowhere. A script that
+runs git (`git diff --exit-code`) gives a different result inside the
+sandbox, and `init` leaves it to the other recipes.
+
+It gets a controlled environment, not yours:
+
+- the variables the check declares (`TZ`, `LANG`, `CI`, `USER`, `LC_*`,
+  `DYLD_*`, `LD_*`, and `NODE_*`, `npm_config_*`, `PNPM_*`, `YARN_*`,
+  `COREPACK_*` for Node, or `PYTHON*`, `MYPY*`, `RUFF_*`, `PYRIGHT*`, `TY_*`
+  for Python), with your values;
+- your PATH, without the project's `.venv/bin`, which a Python check gets
+  first instead, so `uv run` and an activated environment give the same PATH;
+- `HOME`, `TMPDIR` and the XDG directories in its private directories;
+  `VIRTUAL_ENV` for a Python check; Corepack's home where Corepack keeps it.
+
+## Tests
+
+A test run gets what a typecheck or lint gets, and also:
+
+- **On Linux, loopback, and no remote host.** It may listen on any address
+  and accept connections, and connect only to the local host (`127.0.0.0/8`,
+  `::1`, `0.0.0.0`, `::`) and Unix sockets.
+  - Landlock cannot tell a loopback address from a remote one, so a
+    seccomp filter in the test's processes does instead. It refuses sockets
+    other than Unix, netlink and TCP when they are created (UDP included),
+    TCP Fast Open (`MSG_FASTOPEN`) and `io_uring`. It hands each `connect` to
+    REDUE's launcher. The launcher allows a local port no process listens on
+    (the test gets "connection refused") or one the run's own processes
+    listen on, and a Unix socket file in the checkout, the run's home or its
+    temporary directory. It refuses a service started outside the run (your
+    local database) and every remote host. Nothing else goes through the
+    launcher, so worker processes talk to each other as usual. If the
+    launcher's supervisor cannot start, or stops before the run ends, the
+    result is UNVERIFIED, never CURRENT.
+- **On macOS, no network.** No TCP or UDP, loopback included: only Unix
+  sockets in its own temporary directory (its home is beneath it), as a
+  typecheck or lint gets. Seatbelt cannot refuse a service started outside
+  the run while allowing the run's own servers: a rule that refuses one
+  loopback port under a loopback allow is not applied, and an allow list of
+  every other port does not compile. A suite that starts a server on
+  loopback, or reads a local database, fails init's trial: init leaves the
+  test check out, and the tests run without REDUE, as before. A test check
+  set up by alpha.28 on macOS is not CURRENT after the upgrade; if its runs
+  now fail inside the sandbox, run `redue init` again.
+- **A fresh home.** Its home directory is new and empty for each run, as on
+  CI: what a test leaves there is not observed, so it must not reach a later
+  run.
+- **A private `/tmp`.** Its `TMPDIR` is its own, new for each run, and it may
+  not write in `/tmp` or `/var/tmp` outside it. A test that writes to a fixed
+  path there is refused.
+
+`init` compares a test run's exit status and the counts its summary prints
+(passed, failed, skipped), not every line: test runners print in the order
+their workers finish. Git-ignored files are hidden from a test run when the
+trial agrees, as for typecheck and lint. A suite that reads back git-ignored
+files it writes in the same run (a coverage database, a build it starts
+itself) gets the whole checkout. Files a hidden run writes beneath hidden
+folders, or new files git ignores, are not changes to its inputs.
+
+## What REDUE claims
+
+CURRENT means the last sandboxed run's inputs are unchanged:
+
+- every file in the checkout git doesn't ignore but its documentation
+  (`sandbox-v3`), every file git doesn't ignore (`sandbox-v2`), or every file
+  in it, git-ignored files and git-ignored links to files in it included
+  (`sandbox-v1`), except `.git` and runner caches (the general recipe's, plus
+  `__pycache__`, `.mypy_cache`, `.ruff_cache` and `.pytest_cache`);
+- `node_modules` and `.venv`, observed as installed files, by identity;
+- the environment the run gets (without display variables such as `TERM`
+  and `COLUMNS`), and the places it may read;
+- Node's and the package managers' executables, or the interpreter the
+  `.venv` was made from, by file identity;
+- every directory on PATH, by identity: installing, removing or upgrading a
+  program in one makes the result STALE;
+- `.git/info/exclude` and `.git/config`, by content: ruff and biome read the
+  ignore rules there, and they decide what `sandbox-v2` hides. For a project
+  in a subdirectory of its repository, also the `.gitignore` files above it.
+
+## Telling a refusal from a real failure
+
+A run the sandbox refused something fails like any other. REDUE does not run
+every failure twice to find out:
+
+- `init` runs each proposed check plainly and sandboxed, and proposes it
+  when both give the same exit status and the same output, and a failure
+  shows no sign of a refusal. The output is compared without colors,
+  timings, the temporary and home directories, and lines about caches. The
+  one exception is a check that passed plainly and failed only because it
+  was refused a hidden file: it gets the whole checkout without another run
+  (see [files git ignores](#files-git-ignores-and-documentation)).
+  Otherwise `init` writes what it would have without this recipe and says why.
+  These are the only runs `init` makes.
+- When a `sandbox-v2` or `sandbox-v3` run fails with a refusal that names a hidden file, it
+  runs again in the sandbox without hiding (see
+  [files git ignores](#files-git-ignores-and-documentation)).
+- When a sandboxed run fails and its output has a line that looks like a
+  refusal ("Operation not permitted", "Permission denied", "Read-only file
+  system", a name lookup or a connection that failed), REDUE runs the check
+  again outside the sandbox. If that exits differently, the result is the
+  plain run's and UNVERIFIED: "the sandbox changed the result", with the
+  line. A failure without such a line is not run again.
+
+## The private home
+
+A typecheck or lint's home directory is kept between runs, per check, so caches tools
+build there (font caches, a type checker's cache) are not rebuilt every run.
+It starts empty: your configuration files are not in it. What a run leaves
+there can change a later run, and REDUE trusts it like a runner cache. Remove
+it with `redue remove-state`.
+
+## Limits
+
+- Inside Claude Code's own sandbox on macOS, `sandbox-exec` cannot start: the
+  run goes ahead unsandboxed and is UNVERIFIED ("the run was not sandboxed").
+  On Linux, Landlock works inside it.
+- Windows is not supported. The check stays recording-only there.
+- Linux before 6.7 (Landlock ABI below 4) cannot refuse TCP connections, so a
+  run there is UNVERIFIED. UDP is not refused on Linux.
+- System files (time zones, certificates, `/etc`) are not inputs: a change to
+  them does not make a result STALE.
+- A program that reads files in `.git` itself, without git (a commit hash for
+  a version string), reads something REDUE does not observe: a commit does
+  not make the result STALE.
+- Runner caches in the checkout are trusted as the general recipe trusts them.
+- On Linux, a run can still reach a daemon started outside it through a Unix
+  socket file (Landlock does not cover them), and what that daemon reads is
+  not seen. On macOS it cannot.
+- On Linux, uv hard-links `.venv` files to its cache. The cache is
+  toolchain: a file rewritten through the cache, not through the `.venv`, is
+  noticed only when the observer next reads the `.venv` (when it starts).
+- A `.venv` link that leads out of the checkout, other than the interpreter's,
+  keeps the check recording-only and names the link, and so does a `.venv`
+  that uses the system site-packages.
+- A git-ignored link to a directory, or out of the checkout, is not observed,
+  and neither is a `node_modules` directory outside the installed ones (a
+  nested example project's).
+- A script that changes files (`--fix`, `--write`) does not get this recipe:
+  `init` would run it twice.
+- With `sandbox-v2` or `sandbox-v3`, a run cannot read a hidden file, but it can still see
+  that one exists, its size and its times, and write beneath it. On Linux it
+  can also list a hidden folder; on macOS it cannot. A tool that acts on
+  whether a git-ignored file exists, without reading it, is not covered: a
+  new or removed one does not make the result STALE. In a census of 136
+  test suites with ignored files after their build, none did.
+- On Linux, a test run's UDP is refused, loopback included: the filter
+  decides when the socket is made, before its address is known. A test that
+  needs it fails its trial and keeps another recipe.
+- On Linux, the launcher decides a `connect` from the address it reads in
+  the process's memory, and the kernel reads it again after. A process that
+  changes the address in between, from another thread, could reach another
+  host. Honest test code does not.
+- On Linux, a typecheck or lint can still connect to a Unix socket file
+  outside it (a local database's).
+- On Linux, a file a `sandbox-v2` or `sandbox-v3` run creates in a folder that holds hidden
+  files (the checkout's root, when anything in it is hidden; with `sandbox-v3`,
+  any folder with a README) cannot be read
+  back in the same run. `init`'s trial and the rerun without hiding catch a
+  check that needs to.
+- A file whose git status changes without a change to its content (`git add
+  -f` of an ignored file, `git rm --cached` of a tracked one) is noticed only
+  when its content next changes. A change to `.gitignore` or
+  `.git/info/exclude` makes the result STALE.
+- A run that moves a hidden folder into a visible place can read it there.
+  That changes the checkout during the run, so the run is not reused.

package/docs/user/shell.md

@@ -11,9 +11,9 @@ REDUE UNVERIFIED
 ```
 
 It reads the cached snapshot, checks its expiry and observer liveness, and never
-synchronizes, traverses installed packages, or runs probes/checks. Like ordinary
-status, it can remain conservative when caller context or installed hardlinks
-need a synchronized read. Do not turn that uncertainty into a green badge.
+synchronizes, traverses installed packages, or runs probes/checks. Like
+`status --cached`, it can remain conservative when caller context or installed
+hardlinks need a synchronized read. Do not turn that uncertainty into a green badge.
 
 For an existing async/bounded prompt framework, use `redue status --short` from
 the project root as the segment command and display unavailable on errors or

package/docs/user/supported-projects.md

@@ -12,18 +12,37 @@ 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,
+for a root typecheck, lint or test script, the [sandboxed recipe](sandbox.md) on
+macOS and Linux (the script run inside an OS sandbox, with the files git
+ignores and the documentation hidden when it gives the same result that way,
+else with only the files git ignores hidden, else on the whole checkout; a
+test run also gets a private `/tmp`, and loopback-only network on Linux or no
+network on macOS),
+then, for typecheck and lint, the [general recipe](node-script.md): the script run
+through the package manager with every Node process recorded and the whole
+checkout as its input. Python projects get the sandboxed recipe for mypy,
+pyright, ty, ruff and pytest in their `.venv`. `--recipe typescript-direct`,
+`tests-direct`, `node-script` or `sandbox` 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 +55,48 @@ 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.
+A root test script gets the sandboxed recipe when its trial gives the same
+exit status and test counts as a plain run. Otherwise, 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 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
@@ -61,10 +107,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,143 @@
+# Direct test recipe (Vitest and Jest)
+
+`redue init --recipe tests-direct --check test` (or `redue init`, where the
+[sandboxed recipe](sandbox.md) cannot take the test script) 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. A process that replaces itself with
+  another program (`process.execve`) counts as starting it, and it must
+  become a recorded Node process. A shell is read by its command, as the
+  [general recipe](node-script.md#programs) reads it: one that runs another
+  program before it becomes Node counts too;
+- used one of Node's bindings with file, network or program access
+  (`process.binding('fs')`, `'spawn_sync'` and others), or ran Node with
+  `--expose-internals`: the recorder cannot follow those;
+- 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) or, without a pnpm store, links that are all installed
+  files the check observes (esbuild's install links its binary into its
+  platform package). The link count of each such file is checked again
+  before every answer, so a link added later is noticed. A change through a
+  link elsewhere, such as Yarn's hardlinks modes, is not seen. This applies
+  to the [general recipe](node-script.md) too.
+
+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.

package/package.json

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