@redue/cli 0.1.0-alpha.27 → 0.1.0-alpha.29

package/docs/user/sandbox.md

@@ -1,24 +1,27 @@
-# Sandboxed recipe (typecheck and lint, any language)
+# Sandboxed recipe (typecheck, lint and tests, any language)
 
-The sandboxed recipe runs a typecheck or lint command inside an operating
+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 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, 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.
+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 needs files git ignores (generated code, another package's
-built declarations) gets the whole checkout instead: its result holds for a
-run that sees the project, git-ignored files included, its installed packages
-and the toolchain. See [files git ignores](#files-git-ignores).
+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 the [direct test recipe](tests-direct.md)
+  does not take, and pytest in the project's `.venv`. See [tests](#tests).
 - **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
@@ -49,14 +52,15 @@ redue status --sync
 A Python check in the config:
 
 ```json
-{"name": "typecheck", "kind": "typecheck", "qualification": "sandbox-v2",
+{"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-v2", ...}`.
-`sandbox-v2` hides the files git ignores from the run; `sandbox-v1` runs it on
-the whole checkout.
+`{"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
@@ -64,12 +68,31 @@ 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
-
-`init` runs each check three ways at most: plainly, sandboxed with the files
-git ignores hidden, and, when those two differ, sandboxed with the whole
-checkout (reusing the plain run). The first sandboxed way that gives the same
-result is written: `sandbox-v2` or `sandbox-v1`.
+## Files git ignores and documentation
+
+`init` runs each check four ways at most: plainly, then sandboxed with the
+files git ignores and the documentation hidden, with only the files git
+ignores hidden, and with the whole checkout (reusing the plain run). The first
+sandboxed way that gives the same result is written: `sandbox-v3`,
+`sandbox-v2` or `sandbox-v1`.
+
+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-v2` 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
@@ -78,25 +101,27 @@ 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` 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 included. Run `redue init` again to write `sandbox-v1` for a
-check that keeps needing them.
+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`;
+- 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.
 
-It has no network: no TCP connection, loopback included. On macOS its only
+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.
@@ -124,11 +149,56 @@ It gets a controlled environment, not yours:
 - `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 (`sandbox-v2`), or every file
+- 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`);
@@ -154,9 +224,9 @@ every failure twice to find out:
   timings, the temporary and home directories, and lines about caches.
   Otherwise `init` writes what it would have without this recipe and says why.
   These are the only runs `init` makes.
-- When a `sandbox-v2` run fails with a refusal that names a hidden file, it
+- 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)).
+  [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
@@ -166,7 +236,7 @@ every failure twice to find out:
 
 ## The private home
 
-The run's home directory is kept between runs, per check, so caches tools
+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
@@ -200,17 +270,24 @@ it with `redue remove-state`.
   nested example project's).
 - A script that changes files (`--fix`, `--write`) does not get this recipe:
   `init` would run it twice.
-- With `sandbox-v2`, a run cannot read a hidden file, but it can still see
-  that one exists. On macOS it sees the names of hidden files and folders at
-  the level where they start (`dist` in the checkout's root). On Linux it can
-  also list a hidden folder and see its files' sizes and times: Landlock
-  restricts neither beneath a folder the run may list. A tool that acts on
+- 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. Typecheckers and
-  linters read what they act on; a test that skips itself when a built file
-  is missing does not, which is why hidden files are not used for tests yet.
-- On Linux, a file a `sandbox-v2` run creates in a folder that holds hidden
-  files (the checkout's root, when anything in it is hidden) cannot be read
+  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

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

@@ -19,13 +19,16 @@ build scripts. It prefers familiar script names (for typecheck: `typecheck`,
 `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. Without `--recipe`, `init` tries the strict recipes below first, then,
-for a root typecheck or lint script, the [sandboxed recipe](sandbox.md) on
+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 hidden when it gives the same result that way, else on the whole
-checkout), then the [general recipe](node-script.md): the script run
+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 and ruff in their `.venv`. `--recipe typescript-direct`,
+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
@@ -56,7 +59,9 @@ 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).
+its inputs; see [direct tests](tests-direct.md). Other root test scripts get
+the sandboxed recipe when its trial gives the same exit status and test counts
+as a plain run.
 In particular, test caches and build-generated inputs are not excluded to
 make evidence green.
 

package/package.json

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

package/src/claude-hook.mjs

@@ -27,7 +27,7 @@ const general=check=>(check?.qualification==='node-script-v1'&&['typecheck','tes
   sandboxed(check))&&typeof check.script==='string';
 // A sandboxed check: a root package script, or a tool from the project's .venv.
 // sandbox.mjs's isSandboxed, written out: the hook does not load the sandbox module.
-const sandboxed=check=>['sandbox-v1','sandbox-v2'].includes(check?.qualification)&&['typecheck','lint'].includes(check.kind);
+const sandboxed=check=>['sandbox-v1','sandbox-v2','sandbox-v3'].includes(check?.qualification)&&['typecheck','lint','test'].includes(check.kind);
 const python=check=>sandboxed(check)&&Array.isArray(check.command)&&/^\.venv\/bin\/[A-Za-z0-9_.-]+$/.test(check.command[0]||'')&&
   check.command.every(word=>typeof word==='string'&&safe.test(word));
 const eligibleCheck=check=>typecheck(check)||tests(check)||general(check)||python(check);
@@ -446,7 +446,7 @@ function synchronizedStatus(entry,config,root,timeout,sync=true){
     // Claude Code ends a hook that outlives its own timeout; end the status call with it.
     const stop=()=>finish(null);process.once('SIGTERM',stop);
     // Its own process group on POSIX, so a timeout also ends the engine it starts.
-    try{child=spawn(process.execPath,[entry,'--config',config,'status',...(sync?['--sync']:[]),'--json'],
+    try{child=spawn(process.execPath,[entry,'--config',config,'status',sync?'--sync':'--cached','--json'],
       {cwd:root,stdio:['ignore','pipe','ignore'],env:process.env,windowsHide:true,detached:process.platform!=='win32'});}
     catch{return finish(null);}
     child.on('error',()=>finish(null));
@@ -456,12 +456,14 @@ function synchronizedStatus(entry,config,root,timeout,sync=true){
   });
 }
 
-// Waiting for status never costs more than half the check: half the last
-// completed run's duration, at most 10 s. With no completed run, 2 s.
+// Half the last completed run's duration, at least 2 s and at most 10 s; with
+// no completed run, 2 s. A shorter wait misses a status call (70-250 ms here,
+// over 1.5 s on a loaded CI or Windows runner) for a fast check, and the
+// agent's run would go unrecorded.
 export function statusTimeout(status,name){
   const run=Array.isArray(status?.checks)?status.checks.find(row=>row?.name===name)?.invocation:null;
   return run?.status==='exited'&&Number.isFinite(run.durationMs)&&run.durationMs>=0?
-    Math.min(run.durationMs/2,10000):2000;
+    Math.min(Math.max(run.durationMs/2,2000),10000):2000;
 }
 // From the observer's last published status, which is small, not the receipts.
 // The longest wait among `names`, read once.
@@ -500,18 +502,29 @@ export function sessionStart(input,{entry}){
 }
 
 // Returns the hook's stdout object, or null to allow the command.
-export async function claudeHook(input,{entry,timeout,invoke=null}){
-  if(input?.tool_name!=='Bash')return null;
+// `explain(text)` hears why, also when the command is left as it is.
+export async function claudeHook(input,{entry,timeout,invoke=null,explain=null}){
+  // A failing explain never changes the decision.
+  const why=(text,value=null)=>{try{explain?.(text);}catch{}return value;};
+  if(input?.tool_name!=='Bash')return why('not a Bash command');
   const command=input.tool_input?.command,root=input.cwd;
-  if(typeof command!=='string'||/^\s*REDUE_FORCE=1(?:\s|$)/.test(command))return null;
-  const project=hookProject(root);
-  if(!project)return null;
+  if(typeof command!=='string')return why('no command');
+  if(/^\s*REDUE_FORCE=1(?:\s|$)/.test(command))return why('REDUE_FORCE=1');
+  let project;
+  try{project=hookProject(root);}catch(error){return why(`no readable setup record in this directory (${error.code??error.message})`);}
+  if(!project)return why('REDUE is not set up for Claude Code in this directory');
+  // What a status answer said about `names`, when the hook does not skip.
+  const said=(status,names,waited)=>!status?`status did not answer within ${waited} ms`:
+    status.observation?.healthy!==true?'the observer is not healthy':
+    names.map(name=>{const row=Array.isArray(status.checks)?status.checks.find(item=>item?.name===name):null;
+      return !row?`${name} not in status`:`${name} ${row.freshness}/${row.result??'-'}${row.freshness==='CURRENT'&&row.result==='PASS'?
+        ` but not reusable (reuse_eligible ${row.reuse_eligible}, run ${row.invocation?.runId??'none'})`:row.reason?` (${row.reason})`:''}`;}).join('; ');
   const {record,config,parsed}=project;
   // For `redue stats`: the checks a decision skipped, or the ones that were due.
   const tally=(status,names,skipped)=>{let state;try{state=projectState(project.projectRoot,config);}catch{return;}
     for(const name of names){const entry=skipped?skipNote(status,name,'hook'):dueNote(status,name);if(entry)note(state,entry);}};
   const entered=enteredDir(command,root,project.projectRoot);
-  if(!entered)return null;
+  if(!entered)return why('the command enters a directory outside the project');
   let scripts={};
   if(entered.dir==='.')try{scripts=JSON.parse(fs.readFileSync(path.join(project.projectRoot,'package.json'),'utf8')).scripts||{};}catch{}
   // The configured config path as the command's directory sees it.
@@ -527,23 +540,25 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
   // The observer's cached health is enough here: each check asks again when it runs.
   const chained=chainCommand(entered.command,parsed,record.config,entered.dir,scripts,invoke??redueInvocation(entry),configPath,project.projectRoot);
   if(chained){
-    const cached=await synchronizedStatus(entry,config,root,timeout??5000,false);
+    const wait=timeout??5000,cached=await synchronizedStatus(entry,config,root,wait,false);
     return cached?.observation?.healthy===true&&chained.names.every(name=>cached.checks?.some(row=>row?.name===name))?
-      {hookSpecificOutput:{hookEventName:'PreToolUse',updatedInput:{...input.tool_input,command:entered.prefix+chained.command}}}:null;
+      why(`a chain: ${chained.names.join(', ')} through redue run`,{hookSpecificOutput:{hookEventName:'PreToolUse',updatedInput:{...input.tool_input,command:entered.prefix+chained.command}}}):
+      why(`a chain left as written: ${said(cached,chained.names,wait)}`);
   }
   const match=matched(entered.command,parsed,record.config,entered.dir,scripts,project.projectRoot);
-  if(!match)return null;
+  if(!match)return why('no check matches the command');
   // A check followed by more than a simple chain runs untouched.
-  if(match.rest!==null&&!match.fanout)return null;
+  if(match.rest!==null&&!match.fanout)return why('more commands follow the check');
   // turbo, nx and `pnpm -r` cache their own results: skip only when every
   // check the command runs is CURRENT, and otherwise leave it alone.
   if(match.fanout){
     const names=await fanoutChecks(match.fanout,parsed,project.projectRoot);
-    if(!names)return null;
-    const status=await synchronizedStatus(entry,config,root,timeout??lastRunTimeout(config,parsed,...names)),
+    if(!names)return why('a fan-out whose checks are not all configured');
+    const wait=timeout??lastRunTimeout(config,parsed,...names),status=await synchronizedStatus(entry,config,root,wait),
       reason=fanoutVerdict(status,names,match.rest);
     tally(status,names,Boolean(reason));
-    return reason?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}:null;
+    return reason?why('every check CURRENT/PASS',{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}):
+      why(`a fan-out left to run: ${said(status,names,wait)}`);
   }
   // A compiler script: its checks in the order of its runs, or nothing when
   // they no longer correspond. One run is an ordinary check. A chain is
@@ -551,26 +566,26 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
   // redue run, in order.
   if(match.row){
     const names=scriptChecks(match.row,parsed,project.projectRoot);
-    if(!names)return null;
+    if(!names)return why('the script no longer runs its configured checks');
     if(names.length===1)match.check=names[0];
     else{
-      const status=await synchronizedStatus(entry,config,root,timeout??lastRunTimeout(config,parsed,...names)),
+      const wait=timeout??lastRunTimeout(config,parsed,...names),status=await synchronizedStatus(entry,config,root,wait),
         reason=fanoutVerdict(status,names,match.rest);
       tally(status,names,Boolean(reason));
-      if(reason)return {hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}};
+      if(reason)return why('every check CURRENT/PASS',{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}});
       const pending=names.filter(name=>!verdict(status,name));
       const rewritten=status?.schema===1&&status.observation?.healthy===true&&Array.isArray(status.checks)&&
         names.every(name=>status.checks.some(item=>item?.name===name))?recordedCommand(entered.command,pending,configPath,invoke??redueInvocation(entry)):null;
-      return rewritten?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow',
+      return why(`${rewritten?'through redue run':'left as written'}: ${said(status,names,wait)}`,rewritten?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow',
         permissionDecisionReason:`REDUE: ${pending.map(name=>JSON.stringify(name)).join(', ')} of this script's checks ${pending.length===1?'is':'are'} not CURRENT; running ${pending.length===1?'it':'them'} through redue run so the result is recorded.`,
-        updatedInput:{...input.tool_input,command:entered.prefix+rewritten}}}:null;
+        updatedInput:{...input.tool_input,command:entered.prefix+rewritten}}}:null);
     }
   }
-  const name=match.check,status=await synchronizedStatus(entry,config,root,timeout??lastRunTimeout(config,parsed,name)),
+  const name=match.check,wait=timeout??lastRunTimeout(config,parsed,name),status=await synchronizedStatus(entry,config,root,wait),
     reason=verdict(status,name,match.rest);
   tally(status,[name],Boolean(reason));
-  if(reason)return {hookSpecificOutput:{hookEventName:'PreToolUse',
-    permissionDecision:'deny',permissionDecisionReason:reason}};
+  if(reason)return why(`${name} CURRENT/PASS`,{hookSpecificOutput:{hookEventName:'PreToolUse',
+    permissionDecision:'deny',permissionDecisionReason:reason}});
   // Rewrite only on a healthy answer for this check: without an observer,
   // `redue run` cannot record, so the command stays as Claude sent it. A chain
   // stays too: the rewrite returns "allow", which would also skip the prompt
@@ -579,9 +594,9 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
     status.checks.some(item=>item?.name===name)?recordedCommand(entered.command,name,configPath,invoke??redueInvocation(entry),match.wrapper):null;
   // updatedInput replaces the whole tool input. Deny and ask rules still apply
   // to the rewritten command; "allow" skips only the prompt.
-  return rewritten?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow',
+  return why(`${rewritten?'through redue run':'left as written'}: ${said(status,[name],wait)}`,rewritten?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow',
     permissionDecisionReason:`REDUE: check ${JSON.stringify(name)} is not CURRENT; running it through redue run so the result is recorded.`,
-    updatedInput:{...input.tool_input,command:entered.prefix+rewritten}}}:null;
+    updatedInput:{...input.tool_input,command:entered.prefix+rewritten}}}:null);
 }
 
 export async function runClaudeHook(entry){
@@ -590,7 +605,12 @@ export async function runClaudeHook(entry){
     for await(const chunk of process.stdin){text+=chunk;if(text.length>1024*1024)return;}
     const input=JSON.parse(text);
     if(input?.hook_event_name==='SessionStart'){sessionStart(input,{entry});return;}
-    const output=await claudeHook(input,{entry});
+    // REDUE_HOOK_LOG (an absolute file): one JSON line per decision, with why.
+    const log=process.env.REDUE_HOOK_LOG,started=Date.now();let why=null;
+    const output=await claudeHook(input,{entry,explain:text=>{why=text;}});
     if(output)await new Promise(resolve=>process.stdout.write(JSON.stringify(output)+'\n',resolve));
+    if(log&&path.isAbsolute(log))try{fs.appendFileSync(log,JSON.stringify({at:started,ms:Date.now()-started,cwd:input?.cwd??null,
+      command:input?.tool_input?.command??null,decision:!output?'allow':output.hookSpecificOutput?.updatedInput?'rewrite':output.hookSpecificOutput?.permissionDecision??'allow',
+      why})+'\n');}catch{}
   }catch{}
 }

package/src/cli.mjs

@@ -8,7 +8,7 @@ import {patternMatcher} from './glob.mjs';
 import {observedBy} from './installed-observation.mjs';
 import {changedFiles,coverageReadable,gitIgnored,recordedEnvironment,testEnvironmentIssue,testGuardConfig,testRunGuard,testRunFacts,sharedInstalledFile,testsInterpretation,testsQualification} from './test-direct.mjs';
 import {childProgram,generalIssue,lookup,pnpmConfigFiles,scriptCaches,scriptInstalledPaths,scriptInterpretation,scriptQualification,scriptRunFacts,pnpmNameless,toolOutput,toolchainDirs} from './node-script.mjs';
-import {denialLine,endWithChild,hiddenEntries,hiddenQualification,hiddenRefusal,isSandboxed,runToEnd,sandboxArgv,sandboxContext,sandboxDirs,sandboxEnv,
+import {denialLine,docsQualification,endWithChild,hiddenDocs,hiddenEntries,hiddenQualification,hiddenRefusal,hidesIgnored,isSandboxed,runToEnd,supervisorIssue,visibleChange,testRun as sandboxTestRun,sandboxArgv,sandboxContext,sandboxDirs,sandboxEnv,
   sandboxInterpretation,sandboxInterpretationOf,sandboxPlaces,sandboxQualification,sandboxSupport,systemPlaces} from './sandbox.mjs';
 import path from 'node:path';
 import net from 'node:net';
@@ -331,12 +331,24 @@ async function execute() {
       if(support.issue)captureIssues.push(`the run was not sandboxed: ${support.issue}`);
       else{
         const dirs=sandboxDirs(state,name);
+        // A test run: loopback networking on Linux, supervised (the launcher
+        // reports in REDUE's state, outside what the test may touch), a
+        // private /tmp, and a fresh home each run: what a test leaves in its
+        // home is not observed, so it must not reach a later run.
+        const tests=sandboxTestRun(selected),stats=tests&&support.mode==='landlock'?path.join(state,`launcher-${runId}.json`):null;
+        if(tests){dirs.home=path.join(dirs.tmp,'home');fs.mkdirSync(dirs.home,{mode:0o700});}
         const reads=[root,dirs.home,dirs.tmp,...sandboxPlaces(selected,process.env,root),...systemPlaces];
-        // sandbox-v2 hides the checkout's git-ignored entries. Where git
-        // cannot list them, nothing is hidden, and the receipt compares every file.
-        const hidden=selected.qualification===hiddenQualification?hiddenEntries(root):null;
-        sandbox={mode:support.mode,dirs,reads,hidden,argv:sandboxArgv(support.mode,command,{reads,tmp:dirs.tmp,python:support.python,
-          hidden:(hidden||[]).map(rel=>path.join(root,rel.replace(/\/$/,'')))}),
+        // sandbox-v2 hides the checkout's git-ignored entries, and sandbox-v3
+        // its documentation too. Where git cannot list them, nothing is
+        // hidden, and the receipt compares every file.
+        const hidden=hidesIgnored(selected.qualification)?hiddenEntries(root):null;
+        const docs=hidden&&selected.qualification===docsQualification?hiddenDocs(root):null;
+        const options={reads,tmp:dirs.tmp,python:support.python,stats,
+          ...tests?{...support.mode==='landlock'?{network:'loopback'}:{},writes:[root,dirs.home,dirs.tmp],
+            fault:process.env.VSTATE_TEST_FAULTS==='1'?process.env.VSTATE_TEST_SUPERVISOR||null:null}:{}};
+        sandbox={mode:support.mode,dirs,reads,hidden,docs,options,stats,
+          argv:sandboxArgv(support.mode,command,{...options,hidden:(hidden||[]).map(rel=>path.join(root,rel.replace(/\/$/,''))),
+            ...docs?{docs:{root,entries:docs}}:{}}),
           env:sandboxEnv(selected,process.env,{root,...dirs})};
       }
     }
@@ -481,6 +493,18 @@ async function execute() {
       unexplained=touched.filter(file=>!ignored.has(file));
       if(!unexplained.length){eventsExplained=true;if(changed.length)outputs=changed;}
     }
+    // A run that hid git-ignored files: what it wrote beneath them (test
+    // output, coverage data) is not a change to its inputs (visibleChange);
+    // anything else is named.
+    let hiddenOnly=false;
+    if(sandbox?.hidden&&snap&&end&&snap.planId===end.planId&&snap.observationHealthy&&end.observationHealthy&&
+      (snap.inputEventSerial===end.inputEventSerial||end.inputEventPathsComplete===true)){
+      const before=snap.files||{},after=end.files||{},events=end.inputEventPaths||[];
+      // During the run a new file outside the hidden entries was readable: it counts.
+      const found=visibleChange(root,sandbox.hidden,before,after,[...Object.keys(before),...Object.keys(after),...events],
+        {during:true,docs:sandbox.docs});
+      if(found===null){eventsExplained=true;hiddenOnly=true;}else unexplained=[found];
+    }
     // The end certificate, recorded or probed, must cover what this compile received.
     // With no input event, gap or content change in between, it also holds at the start.
     // A run checked by full probes is compared with it too, for its run facts.
@@ -519,18 +543,18 @@ async function execute() {
         `: ${named.slice(0,5).join(', ')}${more>0?` and ${more} more`:''}`:'')+unrecorded);
     }
     // A recorded certificate changes only the probe part of the fingerprint.
-    if(!outputs&&(!snap||!end||snap.planId!==end.planId||(recording?snap.inputKey!==end.inputKey:snap.fingerprint!==end.fingerprint)||
+    if(!outputs&&!hiddenOnly&&(!snap||!end||snap.planId!==end.planId||(recording?snap.inputKey!==end.inputKey:snap.fingerprint!==end.fingerprint)||
       snap.revision!==end.revision))captureIssues.push('declared inputs changed or were not observed');
     // A run that hid git-ignored files and failed with a refusal that names
     // one runs again in the sandbox without hiding them: the check needs
     // them. That run's result is kept, compared on every file, when the
     // inputs held through it too. Its own refusal is handled as below.
     let hiddenRerun=null;
-    if(sandbox?.hidden?.length&&result==='FAIL'&&!requestedSignal){
-      const line=hiddenRefusal(output.head+'\n'+output.tail,sandbox.hidden);
+    if((sandbox?.hidden?.length||sandbox?.docs?.length)&&result==='FAIL'&&!requestedSignal){
+      const line=hiddenRefusal(output.head+'\n'+output.tail,[...sandbox.hidden||[],...sandbox.docs||[]]);
       if(line){
-        console.error(`redue: the sandboxed run failed with what looks like a refusal of a file git ignores (${line}); running it again in the sandbox without hiding them`);
-        const again=await runToEnd(sandboxArgv(sandbox.mode,command,{reads:sandbox.reads,tmp:sandbox.dirs.tmp,python:support.python}),
+        console.error(`redue: the sandboxed run failed with what looks like a refusal of a hidden file (${line}); running it again in the sandbox without hiding files`);
+        const again=await runToEnd(sandboxArgv(sandbox.mode,command,sandbox.options),
           {cwd:plan.cwd,env:sandbox.env,echo:true,started:child=>{activeChild=child;}});
         activeChild=null;
         hiddenRerun={line,exitCode:again.status,signal:again.signal||null,...again.error?{errorCode:again.error.code||again.error.name}:{}};
@@ -556,7 +580,7 @@ async function execute() {
           invocation.hiddenExitCode=invocation.exitCode;invocation.exitCode=again.status;
           result=again.status===0?'PASS':'FAIL';
           output.head=`${again.stdout}\n${again.stderr}`.slice(0,65536);output.tail='';
-          sandbox.hidden=null;
+          sandbox.hidden=null;sandbox.docs=null;
         }
       }
     }
@@ -581,11 +605,14 @@ async function execute() {
         else if(plain.error||plain.status===null)
           captureIssues.push(`the run outside the sandbox did not finish (${plain.error?.code||plain.signal}), so a refusal by the sandbox is not ruled out (${line})`);
         else if(plain.status!==invocation.exitCode){
-          captureIssues.push(`the sandbox changed the result: exit ${invocation.exitCode} inside it, ${plain.status??plain.signal} outside it (${line})`);
+          captureIssues.push(`the sandbox changed the result: exit ${invocation.exitCode} inside it, ${plain.status??plain.signal} outside it (${line}); `+
+            'if this repeats, run redue init again to choose a recipe for this check');
           invocation.sandboxedExitCode=invocation.exitCode;invocation.exitCode=plain.status;
         }
       }
     }
+    // A test run whose network was not supervised throughout is not reused.
+    if(sandbox?.stats){const issue=supervisorIssue(sandbox.stats);if(issue)captureIssues.push(issue);fs.rmSync(sandbox.stats,{force:true});}
     if(sandbox)fs.rmSync(sandbox.dirs.tmp,{recursive:true,force:true});
     const stable=captureIssues.length===0;
     // Two runs on the same inputs, environment and plan that disagree make the
@@ -608,7 +635,7 @@ async function execute() {
     // The recipe that made the receipt, which status and the hook name.
     // A sandboxed receipt names what the run did: hid the git-ignored files or not.
     const receipt={result,invocation,target,stable,fingerprintVersion:recorded||testRun?2:1,
-      recipe:(fallback?scriptQualification:own?(sandbox?.hidden?hiddenQualification:sandboxQualification):selected.qualification)||null,
+      recipe:(fallback?scriptQualification:own?(sandbox?.docs?docsQualification:sandbox?.hidden?hiddenQualification:sandboxQualification):selected.qualification)||null,
       ...(recorded||testRun?{runFacts}:{}),
       ...(testRun?{verificationRecipe:general?scriptInterpretation:testsInterpretation,guardIssues:guard?.issues||['the run record is unavailable'],
         environmentReads:guard?.environmentReads||{},...(nondeterministic?{nondeterministic}:{})}:{}),
@@ -623,8 +650,8 @@ async function execute() {
       provider:plan.provider,environmentHashes:environmentBefore,
       ...(observedContext?{observedContext,verificationRecipe:directInterpretation}:{}),
       // `hidden`: the git-ignored entries the run did not see, which the observer does not compare.
-      ...(own?{verificationRecipe:sandbox?.hidden?sandboxInterpretationOf(hiddenQualification):sandboxInterpretation,
-        sandbox:{mode:sandbox?.mode??null,hidden:sandbox?.hidden??null,...hiddenRerun?{hiddenRerun}:{},...sandboxRerun?{rerun:sandboxRerun}:{}}}:{}),
+      ...(own?{verificationRecipe:sandboxInterpretationOf(sandbox?.docs?docsQualification:sandbox?.hidden?hiddenQualification:sandboxQualification,selected.kind),
+        sandbox:{mode:sandbox?.mode??null,hidden:sandbox?.hidden??null,...sandbox?.docs?{docs:sandbox.docs}:{},...hiddenRerun?{hiddenRerun}:{},...sandboxRerun?{rerun:sandboxRerun}:{}}}:{}),
       ...(fallback?{sandbox:{mode:null,fallback:'node-script',issue:support.issue}}:{}),
       files:(outputs?end:snap)?.files??null,observerGeneration:before?.observation?.generation??null,
       startRevision:snap?.revision??null,endRevision:end?.revision??null};
@@ -718,7 +745,11 @@ async function main(){
       if(processAlive(pid)){await call({action:'stop'});
         for(let i=0;i<100&&fs.existsSync(path.join(state,'observer.lock'));i++)
           await new Promise(r=>setTimeout(r,100));
-        if(fs.existsSync(path.join(state,'observer.lock')))throw Error('observer did not stop');}
+        if(fs.existsSync(path.join(state,'observer.lock')))throw Error('observer did not stop');
+        // It releases the lock before it exits. On Windows a file it still
+        // holds open stays listed after deletion, and removing the
+        // directory fails with ENOTEMPTY until the process is gone.
+        for(let i=0;i<100&&processAlive(pid);i++)await new Promise(r=>setTimeout(r,100));}
     }
     // A stopping observer can still be closing its files (Windows: ENOTEMPTY, EBUSY).
     fs.rmSync(state,{recursive:true,force:true,maxRetries:10,retryDelay:200});