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

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 0.1.0-alpha.29 — 2026-11-03
+
+Editing documentation no longer makes sandboxed checks STALE, a fast check
+is skipped or recorded as it should be, and macOS test runs can no longer
+reach a service started outside them.
+
+- **Documentation is hidden too (`sandbox-v3`).** A sandboxed run now also
+  hides the project's documentation: files named `*.md`, `*.mdx`, `*.rst`,
+  `LICENSE*` or `CHANGELOG*` anywhere, and text, image and PDF files in the
+  root `docs/` folder (code there stays visible). The receipt names the
+  files the run hid, and a later edit to one of them leaves the result
+  CURRENT: editing the README no longer makes the tests STALE. A new
+  documentation file still counts. `init` tries this first, then the
+  git-ignored files only (`sandbox-v2`), then the whole checkout. A check
+  that reads documentation (a doctest over the README) keeps `sandbox-v2`.
+  Run `redue init` again to move an existing check to `sandbox-v3`.
+- **A fast check is no longer missed by the hook.** The hook waited half of
+  the check's last run for `redue status`, so a 0.2 s mypy got 0.1 s, the
+  status answer came too late, and the agent's run went unrecorded. The
+  wait is now at least 2 s. `REDUE_HOOK_LOG` (an absolute file path) makes
+  the hook write one line per Bash command with its decision and why.
+- **macOS test runs get no network.** Seatbelt cannot refuse only the ports
+  that were already listening (a per-port rule under a loopback allow is not
+  applied; an allow list of every other port does not compile), so a macOS
+  test run now gets Unix sockets in its own temporary directory only, as a
+  typecheck or lint does. A suite that needs loopback fails `init`'s trial
+  and runs without REDUE. Test checks set up by alpha.28 on macOS are not
+  CURRENT after the upgrade.
+- **`redue status` reconciles by default.** `redue status --cached` gives the
+  observer's last published answer; `--sync` is still accepted. Like
+  `--sync`, plain `status` exits 2 when it cannot reach the observer (after
+  `redue stop`, for example); `--cached` exits 0.
+- **`redue setup` says more and prints less.** It lists the checks it left
+  out and why (a kind it found nothing for, a proposed `tsc --noEmit` no
+  recipe takes), says what recording only means, and prints one line per
+  recorded run instead of the check's whole output.
+- `redue remove-state` waits for the observer to exit before removing its
+  state (a Windows ENOTEMPTY).
+- **Measured.** In the product census, repositories whose qualifying
+  sandboxed check keeps the documentation hidden, out of those with one:
+  TypeScript on Linux, typecheck 17 of 19, lint 20 of 20, tests 7 of 8; on
+  macOS 12 of 13, 14 of 16, 6 of 9. Python on Linux 15 of 15, 22 of 22, 12
+  of 17; on macOS 11 of 13, 17 of 17, 8 of 11. No network for macOS test
+  runs cost 1 TypeScript suite (it starts a server on 127.0.0.1) and 2
+  Python suites: test suites qualifying on macOS went from 12 to 11
+  (TypeScript) and 14 to 11 (Python; one checkout no longer installs). The
+  strace cross-check found no read outside the recorded inputs. In a Claude
+  Code follow-up on starlette and nestjs-api-gateway, a README edit made no
+  check STALE; the hook skipped mypy, pytest and the lint, and each skipped
+  command passed when run plainly.
+
 ## 0.1.0-alpha.28 — 2026-11-02
 
 Test suites can run in the sandbox, so REDUE can reuse a passing test run

package/README.md

@@ -26,13 +26,17 @@ redue setup claude
 stops before writing anything if the dependencies are not installed. It:
 
 - finds your typecheck, lint and test scripts and writes `redue.config.json`
-  (it never changes your scripts, source or dependencies). Checks REDUE can
-  only record, not reuse, are listed as recording-only;
+  (it never changes your scripts, source or dependencies). In a Python
+  project it finds these tools in `.venv/bin`, with the arguments your CI
+  workflows, Makefile, justfile, tox, nox or scripts give them: mypy,
+  pyright and ty (typecheck), ruff (lint) and pytest (test). It says which
+  checks it left out and why, and which it can only record, not reuse;
 - connects Claude Code: a short section in `CLAUDE.md`, a skill, and two hooks
   in `.claude/settings.local.json`;
 - starts REDUE's file observer, waits while it indexes the project (a minute
   or more in a large one), then runs each check that can qualify once, so
-  there is a first result to reuse;
+  there is a first result to reuse, and prints one line per run (the run's
+  own output only when it fails);
 - prints every file it writes. Running it again changes nothing.
 
 Then start a new Claude Code session in the project and work as usual. When
@@ -43,7 +47,7 @@ through REDUE so the new result is recorded.
 To look yourself:
 
 ```text
-$ redue status --sync
+$ redue status
 ✓ typecheck  CURRENT / PASS
 ✓ lint  CURRENT / PASS
 
@@ -54,10 +58,10 @@ src/main.ts changed
 Due again when verification is needed: redue run "typecheck"
 ```
 
-`--sync` checks the files and your environment before it answers; this is
-what the agent asks. Plain `redue status` is a fast cached answer and can say
-UNVERIFIED ("cannot confirm your execution context") where `--sync` would say
-CURRENT.
+`redue status` checks the files and your environment before it answers, as
+the agent's hook does. `redue status --cached` gives the last answer the
+observer published without checking; it can say UNVERIFIED ("cannot confirm
+your execution context") where `redue status` would say CURRENT.
 
 `redue stats` shows, per check, the reruns the hook skipped, the time saved,
 the recorded runs and the top reasons a check was UNVERIFIED, from a log kept
@@ -87,27 +91,30 @@ packages.
 ## What it covers today
 
 In a census of 120 active public TypeScript repositories (November 2026, REDUE
-at commit a2401cc, before 0.1.0-alpha.28), each installed as its users would,
+at commit 8cb32d6, before 0.1.0-alpha.29), each installed as its users would,
 with dependencies' install scripts on, 89 installed cleanly on a macOS runner.
 A check counts when two recorded runs on the same code both came out CURRENT
-on the same inputs. 38 repositories had at least one such check:
+on the same inputs. 34 repositories had at least one such check:
 
 | Check | Repositories | How |
 |---|---|---|
-| Typecheck | 20 | 14 by running the project's script in an OS sandbox ([sandboxed recipe](docs/user/sandbox.md)), 13 of them with the files git ignores hidden; 5 by running the local `tsc` directly ([direct recipe](docs/user/direct-typescript.md)); 1 by running the script with every Node process recorded ([general recipe](docs/user/node-script.md)) |
-| Lint | 22 | 19 sandboxed recipe (18 with ignored files hidden), 3 general recipe |
-| Tests | 12 | 10 sandboxed recipe, with ignored files hidden and loopback-only network; 2 Vitest run directly ([direct test recipe](docs/user/tests-direct.md)) |
+| Typecheck | 20 | 13 by running the project's script in an OS sandbox ([sandboxed recipe](docs/user/sandbox.md)), 12 of them with the files git ignores and the documentation hidden; 5 by running the local `tsc` directly ([direct recipe](docs/user/direct-typescript.md)); 2 by running the script with every Node process recorded ([general recipe](docs/user/node-script.md)) |
+| Lint | 20 | 16 sandboxed recipe (14 with ignored files and documentation hidden, 1 with ignored files hidden), 4 general recipe |
+| Tests | 11 | 9 sandboxed recipe with no network (6 with ignored files and documentation hidden, 3 with ignored files hidden); 2 Vitest run directly ([direct test recipe](docs/user/tests-direct.md)) |
 
-In alpha.27 the same census found 2 repositories with a qualifying test check
-on macOS and on Linux; now 12 on macOS and 11 on Linux.
+alpha.28 found 38 repositories on macOS. Test runs there no longer get
+loopback, which cost 1 test suite (it starts a server on 127.0.0.1). Of the
+other 3, one lint check was lost to a documentation-hiding bug fixed before
+this release, one checkout now installs with pnpm in a way REDUE does not
+take, and one `init` did not answer within the census's 10 minutes. On
+Linux, where tests keep loopback, 10 test suites qualified.
 
 In a census of 120 Python repositories, 74 installed on a Linux runner
 and 31 had a qualifying check: typecheck (mypy, pyright, ty) 15, lint (ruff)
-22, tests (pytest) 17, all through the sandboxed recipe (14 of the test
-suites with ignored files hidden, 3 with the whole checkout). In alpha.27, no
-Python test suite qualified. On Linux, every sandboxed run was traced
-with strace: each file it read in the checkout was a recorded input, a cache
-or its own output.
+22, tests (pytest) 17, all through the sandboxed recipe (15, 22 and 12 of
+them with ignored files and documentation hidden). On Linux, every sandboxed
+run was traced with strace: each file it read in the checkout was a recorded
+input, a cache or its own output.
 
 Everything else stays UNVERIFIED, with a reason you can read in
 `redue explain`. The usual ones: a script starts a program REDUE cannot see
@@ -163,7 +170,7 @@ harness, tasks and raw results are in [`eval/`](eval/README.md).
 redue init          # write redue.config.json from your scripts
 redue start         # start the file observer
 redue run typecheck # run a check through REDUE and record the result
-redue status --sync # what still holds
+redue status        # what still holds
 ```
 
 Codex is supported too (`redue agent setup codex --apply`); see

package/bin/redue.mjs

@@ -7,7 +7,7 @@ import {directCompiler,directQualification,directEnvironment,directInstalledInpu
 import {runArgv,tscRun} from '../src/typescript-invocation.mjs';
 import {testEnvironment,testRunnerAt,testsInterpretation,testsQualification} from '../src/test-direct.mjs';
 import {scriptEnvironment,scriptInterpretation,scriptKinds,scriptQualification} from '../src/node-script.mjs';
-import {hiddenListIssue,hiddenQualification,isSandboxed,pythonTool,sandboxEnvironment,sandboxInterpretationOf,sandboxKinds,sandboxQualification} from '../src/sandbox.mjs';
+import {docsQualification,hiddenDocsIssue,hiddenListIssue,hiddenQualification,isSandboxed,pythonTool,sandboxEnvironment,sandboxInterpretationOf,sandboxKinds,sandboxQualification} from '../src/sandbox.mjs';
 import os from 'node:os';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
@@ -40,8 +40,8 @@ Commands:
                        Connect project instructions; explicit setup only
   start                Start the local observer
   stop                 Stop this observer
-  status [--json|--short] Read conservative cached status
-  status --sync        Reconcile inputs and caller context before answering
+  status [--json]      Reconcile inputs and caller context, then answer (--sync is the same)
+  status --cached [--json] | --short  The last answer the observer published, without reconciling
   explain [CHECK] [--json] Explain applicability (synchronized; may cost more than a rerun)
   detail [CHECK] [--json]  Alias for explain
   run CHECK [--if-due] Execute one configured check and record its outcome; with --if-due,
@@ -102,9 +102,12 @@ const json=args.includes('--json');
 // run --if-due: run the check only when its last pass does not apply now.
 const ifDue=command==='run'&&args.includes('--if-due');
 if(ifDue)args.splice(args.indexOf('--if-due'),1);
-const sync=args.includes('--sync');
+// status syncs by default (warm, it costs well under 100 ms more than the
+// cached answer); --cached and --short read the cached answer.
+const cachedOnly=args.includes('--cached');
 const dryRun=args.includes('--dry-run');
 const short=args.includes('--short');
+const sync=args.includes('--sync')||command==='status'&&!cachedOnly&&!short;
 let workspaceSelection=null,checkSelection=null,recipeSelection=null;
 if(command==='init')for(let i=0;i<args.length;){
   if(args[i]==='--workspace'||args[i]==='--check'||args[i]==='--recipe'){
@@ -115,9 +118,10 @@ if(command==='init')for(let i=0;i<args.length;){
 }
 const check=['run','detail','explain'].includes(command)&&args[0]&&!args[0].startsWith('--')?args.shift():null;
 if(command==='run'&&!check)error('run requires a check name');
-if(args.some(value=>!['--json','--sync','--dry-run','--short'].includes(value)))error('unknown option; use --help');
+if(args.some(value=>!['--json','--sync','--cached','--dry-run','--short'].includes(value)))error('unknown option; use --help');
 if(sync&&!['status','detail','explain'].includes(command))error('--sync is for status or detail');
-if(short&&(command!=='status'||json||sync))error('--short is a cached status option; do not combine it with --sync or --json');
+if(cachedOnly&&(command!=='status'||args.includes('--sync')))error('--cached is a status option; do not combine it with --sync');
+if(short&&(command!=='status'||json||args.includes('--sync')))error('--short is a cached status option; do not combine it with --sync or --json');
 if(dryRun&&command!=='init')error('--dry-run is for init');
 
 if(command==='init'){
@@ -153,6 +157,7 @@ if(command==='init'){
   }
   // A sandboxed check is proposed only when it gives the same exit status and
   // output inside the sandbox as outside it: first with the checkout's
+  // git-ignored files and documentation hidden (sandbox-v3), then with the
   // git-ignored files hidden (sandbox-v2), else with the whole checkout
   // (sandbox-v1), reusing the plain run. Otherwise init writes what it would
   // have without the sandboxed recipe, with the reason.
@@ -165,11 +170,18 @@ if(command==='init'){
   for(const [at,row] of [...discovery.checks.entries()]){
     if(row.qualification!==sandboxQualification||row.level!=='ready')continue;
     if(!json)console.error(`Running ${row.config.name} inside and outside the sandbox to confirm it...`);
-    const hidden=await sandboxTrial(discovery.root,row.config,{hide:true});
-    if(!hidden.issue)trials++;
+    const docs=await sandboxTrial(discovery.root,row.config,{hide:'docs'});
+    if(!docs.issue)trials++;
+    if(!docs.issue&&docs.same){
+      row.config={...row.config,qualification:docsQualification};row.qualification=docsQualification;
+      row.reason=row.reason.replace('the whole checkout is its input',"the checkout's files git doesn't ignore, except its documentation, are its input")+`; ran both ways at init, exit ${docs.plain}`;continue;}
+    // Without a list of the documentation, the git-ignored files are still tried.
+    const hidden=docs.plainRun?await sandboxTrial(discovery.root,row.config,{hide:true,plain:docs.plainRun}):
+      docs.issue===hiddenDocsIssue?await sandboxTrial(discovery.root,row.config,{hide:true}):docs;
     if(!hidden.issue&&hidden.same){
       row.config={...row.config,qualification:hiddenQualification};row.qualification=hiddenQualification;
-      row.reason=row.reason.replace('the whole checkout is its input',"the checkout's files git doesn't ignore are its input")+`; ran both ways at init, exit ${hidden.plain}`;continue;}
+      row.reason=row.reason.replace('the whole checkout is its input',"the checkout's files git doesn't ignore are its input")+
+        `; ran both ways at init, exit ${hidden.plain}; it needs the documentation (${trialIssue(docs)})`;continue;}
     // Without git, nothing is hidden: the whole checkout is tried on its own.
     const trial=hidden.plainRun?await sandboxTrial(discovery.root,row.config,{plain:hidden.plainRun}):
       hidden.issue===hiddenListIssue?await sandboxTrial(discovery.root,row.config):hidden;
@@ -222,7 +234,7 @@ if(command==='init'){
       console.log('Ready to qualify means the supported contract will be validated; it is not verification evidence.');
       console.log(`Next: review the config, then redue start and redue run ${JSON.stringify(discovery.checks[0].config.name)}.`);
       console.log('Connect your agent: redue agent setup codex (or claude). Preview with --dry-run.');
-      console.log('Use redue status first. --sync can establish applicability, but may cost more than rerunning a cheap check.');}
+      console.log('Then redue status says whether each result applies to the files as they are now.');}
   } else if(unsupported&&!json)console.log(`No config written: ${summary.issue||'unsupported discovery boundary'}.`);
   if(json)console.log(JSON.stringify({...summary,proposed_config:discovery.config}));
   await exit(0);
@@ -408,7 +420,7 @@ const checks=publicConfig.checks.map(check=>{
     ...(npmDirect?{qualificationInterpretation:directInterpretation}:{}),
     ...(testsDirect?{qualificationInterpretation:testsInterpretation}:{}),
     ...(generalScript?{qualificationInterpretation:scriptInterpretation}:{}),
-    ...(sandboxed?{qualificationInterpretation:sandboxInterpretationOf(check.qualification)}:{}),
+    ...(sandboxed?{qualificationInterpretation:sandboxInterpretationOf(check.qualification,check.kind)}:{}),
     workspace:check.workspace||null,kind:check.kind||null};
 });
 const runtime={schema:1,provider:'declared-project@1',root,state,checks};

package/docs/user/agents.md

@@ -12,8 +12,8 @@ generic agent's instructions with the project owner's permission.
    `redue --config CONFIG status --sync --json`. Do not infer a recipe from its name.
    Cached status cannot establish its caller context. In mixed configurations,
    assess each check's contract separately; this is not a global sync-first policy.
-3. For other/unknown recipes, query ordinary `status --json` first and decide whether
-   synchronization is worthwhile. Ordinary status and `--short` remain cheap inspection.
+3. For other/unknown recipes, `status --json` synchronizes too (`--sync` is the
+   same); `status --cached --json` and `--short` remain cheap inspection.
 4. Reuse only schema 1, healthy observation and the selected check's CURRENT/PASS
    with `reuse_eligible: true`. Missing eligibility means false. A historical FAIL
    is never green evidence. Do not rerun eligible evidence merely for freshness.
@@ -167,11 +167,18 @@ commands never start the hook. The installed skill lists these exact commands,
 so the agent uses forms the hook recognizes.
 
 On a match, the hook runs `redue status --sync --json`. It waits up to half the
-duration of the check's last completed run, at most 10 seconds, so waiting never
-costs more than half a run. With no completed run it waits 2 seconds. A check
-that takes a few hundred milliseconds is therefore rarely skipped; skipping it
-would save almost nothing, and the hook does not rewrite it to `redue run`
-either. Claude Code's own limit for the hook is 15 seconds.
+duration of the check's last completed run, at least 2 seconds and at most 10
+seconds. A status call usually takes 70-250 ms, so a fast check (mypy in 0.2 s)
+is still skipped when CURRENT, or run through `redue run` and recorded when not.
+When the observer is slow or stuck, a matching command can wait the full 2
+seconds before it runs as written. Claude Code's own limit for the hook is 15
+seconds.
+
+To see why the hook decided what it did, set `REDUE_HOOK_LOG` to an absolute
+file path in the environment Claude Code starts with. The hook appends one JSON
+line per Bash command: the command, the decision (`deny`, `rewrite` or
+`allow`) and why, such as `no check matches the command` or `status did not
+answer within 2000 ms`.
 It blocks the command only when the check is CURRENT, PASS and
 `reuse_eligible: true`. The message names the check and the receipt's run ID. Every
 other result allows the command: STALE, UNVERIFIED, FAILED, a timeout, an error, or

package/docs/user/getting-started.md

@@ -117,9 +117,10 @@ compiler invocation it selects, and for npm the
 run through the package manager. No existing configuration is silently migrated.
 Only use configs and probes from trusted repositories: these execute local code.
 
-`status` is cached and conservative. `status --sync` and `explain` revalidate caller
-context and may execute read-only probes. Synchronization can be slower than a cheap
-check, especially on Windows. Choose deliberately. A timeout is UNVERIFIED, not green.
+`status` and `explain` revalidate caller context and may execute read-only probes
+(`status --sync` is the same as `status`). `status --cached` is the cached,
+conservative answer, without revalidating. Synchronization can be slower than a
+cheap check, especially on Windows. A timeout is UNVERIFIED, not green.
 
 ## Lifecycle and removal
 

package/docs/user/json.md

@@ -1,7 +1,7 @@
 # Alpha JSON interface (schema 1)
 
-Use `status --json` for cached state, `status --sync --json` for caller-aware
-applicability, and `explain CHECK --json` for selected synchronized detail.
+Use `status --json` (or `status --sync --json`) for caller-aware applicability,
+`status --cached --json` for cached state, and `explain CHECK --json` for selected synchronized detail.
 `detail` remains an alias. Successful reads emit one JSON object, no human prose.
 
 ```json

package/docs/user/sandbox.md

@@ -8,14 +8,15 @@ 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, 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
 
@@ -51,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
@@ -66,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
@@ -80,18 +101,19 @@ 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`,
@@ -99,7 +121,7 @@ It may read and execute only beneath:
 - 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 gets loopback; see [tests](#tests)). On macOS its only
+(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.
@@ -131,11 +153,10 @@ It gets a controlled environment, not yours:
 
 A test run gets what a typecheck or lint gets, and also:
 
-- **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.
-  - On macOS, Seatbelt enforces that.
-  - On Linux, Landlock cannot tell a loopback address from a remote one, so a
+- **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
@@ -147,6 +168,16 @@ A test run gets what a typecheck or lint gets, and also:
     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.
@@ -166,7 +197,8 @@ folders, or new files git ignores, are not changes to its inputs.
 
 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`);
@@ -192,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
@@ -238,28 +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
+- 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. On macOS UDP
-  to loopback works. A test that needs it fails its trial and keeps another
-  recipe.
-- On macOS, a test run can connect to a service on loopback that it did not
-  start (a local database on `127.0.0.1:5432`), and that service's state is
-  not observed: a change to it does not make the result STALE. On Linux the
-  launcher refuses it.
+  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` run creates in a folder that holds hidden
-  files (the checkout's root, when anything in it is hidden) cannot be read
+- 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

@@ -21,8 +21,10 @@ 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, 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; a test run also gets loopback-only network and a private `/tmp`),
+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,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.28",
+  "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','test'].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,supervisorIssue,visibleChange,testRun as sandboxTestRun,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,21 +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, supervised on Linux (the launcher
+        // 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-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?{network:'loopback',writes:[root,dirs.home,dirs.tmp],
+          ...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,options,stats,
-          argv:sandboxArgv(support.mode,command,{...options,hidden:(hidden||[]).map(rel=>path.join(root,rel.replace(/\/$/,'')))}),
+        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})};
       }
     }
@@ -498,7 +501,8 @@ async function execute() {
       (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});
+      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.
@@ -546,10 +550,10 @@ async function execute() {
     // 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`);
+        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;
@@ -576,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;
         }
       }
     }
@@ -601,7 +605,8 @@ 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;
         }
       }
@@ -630,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}:{})}:{}),
@@ -645,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};
@@ -740,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});

package/src/daemon.mjs

@@ -348,14 +348,16 @@ function describeChangedInput(plan,file) {
     .map(mapping=>mapping.logical).slice(0,2);
   return file+' changed'+(matches.length?` (installed via ${matches.join(', ')})`:'');
 }
-// A run that hid the checkout's git-ignored entries (sandbox@2): the first
+// A run that hid the checkout's git-ignored entries (sandbox@2), and maybe
+// documentation files (sandbox@3, the receipt's sandbox.docs): the first
 // changed input it could see (sandbox.mjs's visibleChange), or null; once
 // per receipt and pair of fingerprints.
 const hiddenRun=r=>Array.isArray(r?.sandbox?.hidden)&&Boolean(r.files);
 function visibleChange(row,r,name) {
   const key=(r.invocation?.runId||'')+'\0'+r.fingerprint+'\0'+combinedSummary(name).fingerprint;
   if(row.visibleKey!==key){const current=combinedFiles(name);
-    row.visibleKey=key;row.visibleChange=sandboxVisibleChange(root,r.sandbox.hidden,r.files,current,[...Object.keys(r.files),...Object.keys(current)]);}
+    row.visibleKey=key;row.visibleChange=sandboxVisibleChange(root,r.sandbox.hidden,r.files,current,[...Object.keys(r.files),...Object.keys(current)],
+      {docs:Array.isArray(r.sandbox.docs)?r.sandbox.docs:null});}
   return row.visibleChange;
 }
 function rows(contextHashes,synchronizedInstalled=false,synchronizedFilesystem=false) {

package/src/node-onboarding.mjs

@@ -323,7 +323,9 @@ export function discoverNodeProject(root,{recipe=null}={}) {
       }catch(e){classification={...classification,reason:`Sandboxed recipe unavailable (${e.code?.replace(/^test-/,'')||e.message}); ${classification.reason}`};}
     }
     if(generalRow){checks.push(generalRow);continue;}
-    if(!script&&classification.level!=='ready')continue;
+    // A proposed `tsc --noEmit` that no recipe takes is left out, with why.
+    if(!script&&classification.level!=='ready'){
+      skipped.push({kind,reason:`${kind}: no typecheck script, and a proposed tsc --noEmit was not taken (${classification.reason})`});continue;}
     if(parts&&classification.level==='ready'){
       for(const part of parts)checks.push({config:{...check,...part,qualification:classification.qualification},...classification});
       continue;

package/src/presentation.mjs

@@ -3,7 +3,7 @@
 const recipes={'npm-typescript-direct-v1':'direct TypeScript recipe','npm-tests-direct-v1':'direct test recipe',
   'node-script-v1':'general recipe','pnpm-tsc-v1':'pnpm TypeScript recipe','yarn-workspace-tsc-v1':'Yarn workspace TypeScript recipe',
   'typescript-noemit-v1':'npm TypeScript recipe','sandbox-v1':'sandboxed recipe',
-  'sandbox-v2':'sandboxed recipe, git-ignored files hidden'};
+  'sandbox-v2':'sandboxed recipe, git-ignored files hidden','sandbox-v3':'sandboxed recipe, git-ignored files and docs hidden'};
 export const recipeLabel=recipe=>recipes[recipe]??null;
 export function checkLabel(row) {
   return row.result==='FAIL'?'FAILED':row.freshness;
@@ -12,8 +12,8 @@ export function explanation(row) {
   const reason=row.reason||'No verification evidence is available.';
   if(reason==='no receipt')return 'No execution has been recorded. Run this check when verification is needed.';
   if(reason==='declared inputs match')return 'Recorded evidence still applies to the declared inputs.';
-  if(reason==='execution environment context not supplied')return 'Cached status cannot confirm your execution context. Use --sync if worthwhile, or rerun the check.';
-  if(/requires? a synchronized content read/.test(reason))return 'Cached status cannot establish applicability here. Use --sync if worthwhile, or rerun the check.';
+  if(reason==='execution environment context not supplied')return 'Cached status cannot confirm your execution context. Run redue status without --cached, or rerun the check.';
+  if(/requires? a synchronized content read/.test(reason))return 'Cached status cannot establish applicability here. Run redue status without --cached, or rerun the check.';
   if(reason.startsWith('input coverage unresolved: '))return 'Recording-only: '+reason.slice(27);
   if(/input plan (rebuilding|indexing)|observer initialization|input observation reconciliation pending/.test(reason))
     return 'Checking inputs after startup or changes. Wait for observation to finish, then query again.';
@@ -56,6 +56,6 @@ export function renderRun(value) {
   if(value.invocation!=='exited')lines.push(`Invocation ${value.invocation}; no reusable passing evidence.`);
   else if(!value.coverage_qualified)lines.push('Applicability remains UNVERIFIED: input coverage is incomplete.');
   else if(!value.stable)lines.push('Applicability remains UNVERIFIED: inputs changed or observation was unavailable during execution.');
-  else lines.push('Inspect redue status before reusing this evidence. Cached status may require --sync to establish applicability.');
+  else lines.push('Check redue status before reusing this evidence.');
   return lines.join('\n');
 }

package/src/sandbox.mjs

@@ -29,11 +29,36 @@ export const sandboxInterpretation='sandbox@1';
 export const hiddenQualification='sandbox-v2';
 export const hiddenInterpretation='sandbox@2';
 export const hiddenListIssue='git cannot list the ignored files';
-export const isSandboxed=qualification=>qualification===sandboxQualification||qualification===hiddenQualification;
-export const sandboxInterpretationOf=qualification=>qualification===hiddenQualification?hiddenInterpretation:sandboxInterpretation;
+// And the project's documentation hidden too (docPatterns): an agent edits it
+// often, and a typecheck, lint or test suite seldom reads it.
+export const docsQualification='sandbox-v3';
+export const docsInterpretation='sandbox@3';
+// Under docs/, only documentation files: code there (examples a typecheck
+// includes) stays visible.
+const docsFolderTypes=['txt','adoc','png','jpg','jpeg','gif','svg','webp','pdf'];
+export const docPatterns=['**/*.md','**/*.mdx','**/*.rst','**/LICENSE*','**/CHANGELOG*',...docsFolderTypes.map(type=>`docs/**/*.${type}`)];
+export const hiddenDocsIssue='git cannot list the documentation';
+// What macOS refuses by path pattern: the extensions, in any case (Seatbelt
+// matches regexes without regard to case). Every other listed file
+// (LICENSE*, CHANGELOG*) it refuses by its path; a pattern would refuse
+// license-check.ts too.
+const docsByPattern=rel=>/^(.+\/)?[^/]*\.(md|mdx|rst)$/i.test(rel)||new RegExp(`^docs/(.+/)?[^/]*\\.(${docsFolderTypes.join('|')})$`,'i').test(rel);
+// One path each makes the profile larger and slower to compile (1,000 add
+// about 190 ms to a run; a few thousand do not compile). Past this many,
+// those files stay visible and count as inputs, on every platform.
+export const namedDocsLimit=100;
+export const isSandboxed=qualification=>[sandboxQualification,hiddenQualification,docsQualification].includes(qualification);
+// Whether the recipe hides the checkout's git-ignored entries (v2 and v3).
+export const hidesIgnored=qualification=>qualification===hiddenQualification||qualification===docsQualification;
+// A macOS test run has had no TCP since alpha.29: its own interpretation, so a
+// result recorded with loopback is not the same plan.
+export const sandboxInterpretationOf=(qualification,kind=null,platform=process.platform)=>
+  (qualification===docsQualification?docsInterpretation:qualification===hiddenQualification?hiddenInterpretation:sandboxInterpretation)+
+  (kind==='test'&&platform==='darwin'?'+no-tcp':'');
 export const sandboxKinds=['typecheck','lint','test'];
-// A test run gets loopback networking and a private /tmp (sandboxArgv's
-// `network` and `writes`); a typecheck or lint gets no network.
+// A test run gets a private /tmp (sandboxArgv's `writes`) and, on Linux,
+// supervised loopback networking (`network`); a typecheck or lint, and a
+// test run on macOS, get no network but Unix sockets.
 export const testRun=check=>check?.kind==='test';
 const fail=code=>{throw Object.assign(Error(code),{code});};
 const digest=value=>createHash('sha256').update(value).digest('hex');
@@ -252,6 +277,24 @@ export function hiddenEntries(root){
     !runnerCache(rel)&&!runnerCache(rel.replace(/\/$/,'')+'/x'));
 }
 
+// The documentation files docPatterns names among the files git lists and
+// does not ignore (git-ignored ones are hidden as such), as regular files:
+// a link is not hidden. Files, never folders, so a folder stays listable.
+// Relative; null when git cannot tell. git filters by pathspec, so a large
+// checkout is not listed whole.
+const docMatch=picomatch(docPatterns,{dot:true});
+export function hiddenDocs(root){
+  const r=spawnSync('git',[...projectGit,'ls-files','-z','--cached','--others','--exclude-standard','--',...docPatterns.map(pattern=>`:(glob)${pattern}`)],
+    {cwd:root,encoding:'utf8',maxBuffer:256*1024*1024,timeout:60000,stdio:['ignore','pipe','ignore'],env:gitEnv()});
+  if(r.status!==0)return null;
+  const out=new Set();
+  for(const rel of r.stdout.split('\0'))if(rel&&!out.has(rel)&&docMatch(rel))
+    try{if(fs.lstatSync(path.join(root,rel)).isFile())out.add(rel);}catch{}
+  const named=[...out].filter(rel=>!docsByPattern(rel));
+  if(named.length>namedDocsLimit)for(const rel of named)out.delete(rel);
+  return [...out].sort();
+}
+
 // What git lists now as ignored at or beneath `paths` (relative files, or
 // directories ending in /), as hiddenEntries would: nested repositories are
 // not entered, and an entry that is an installed tree is not ignored (one
@@ -286,10 +329,15 @@ export function trackedBeneath(root,entries){
 // cannot tell, every change counts. `external:` paths always count. With
 // `during` (changes while the run ran), a new file outside the hidden
 // entries counts too: the run could read it.
-export function visibleChange(root,hidden,before,current,paths,{during=false}={}){
+// With `docs` (sandbox@3: the documentation files the run hid, relative), a
+// later change to one of those files does not count. A new documentation
+// file does, and so does any change while the run ran: the run is not shown
+// to have been kept from it.
+export function visibleChange(root,hidden,before,current,paths,{during=false,docs=null}={}){
   const entries=hidden.map(entry=>entry.replace(/\/$/,''));
   const beneath=file=>entries.some(entry=>file===entry||file.startsWith(entry+'/'));
-  const changed=[...new Set(paths)].filter(file=>before[file]!==current[file]).sort();
+  const hiddenDoc=new Set(during?[]:docs||[]);
+  const changed=[...new Set(paths)].filter(file=>before[file]!==current[file]&&!hiddenDoc.has(file)).sort();
   const seen=changed.filter(file=>file in before&&!beneath(file));
   if(seen.length)return seen[0];
   const covered=changed.filter(beneath),fresh=changed.filter(file=>!(file in before)&&!beneath(file));
@@ -322,11 +370,20 @@ const ancestors=list=>[...new Set(list.flatMap(dir=>{const out=[];for(let at=pat
 // the run's own temporary directory (`own`), which is new for each run: a
 // daemon an earlier run left behind cannot answer a later one. `hidden`:
 // absolute paths whose contents it may not read or execute.
-// A test run (`network` "loopback") may bind and accept anywhere and
-// connect to loopback only; with `writes`, it writes nothing beneath /tmp
-// and /var/tmp but beneath those places (its checkout, home and own
-// temporary directory).
-export function seatbeltProfile(reads,own=null,hidden=[],{network='none',writes=null}={}){
+// A test run gets no TCP either: Seatbelt cannot refuse one loopback port
+// while allowing the others (a per-port deny under a loopback allow is not
+// applied; an allow list of 65,000 ports does not compile), so a suite could
+// reach a database started outside the run. A suite that needs loopback
+// fails init's trial and runs plainly. With `writes`, a test run writes
+// nothing beneath /tmp and /var/tmp but beneath those places (its checkout,
+// home and own temporary directory).
+// `docs` ({root, entries}): the checkout's documentation it may not read,
+// regular files only, so folders stay listable. Extensions go by path
+// pattern, so the profile stays small however many files match: every file
+// hiddenDocs lists, and more (one in node_modules, README.MD). Seatbelt
+// matches a regex without regard to case, so LICENSE* and CHANGELOG* go by
+// the files hiddenDocs listed: a pattern would hide license-check.ts too.
+export function seatbeltProfile(reads,own=null,hidden=[],{writes=null,docs=null}={}){
   const quote=value=>JSON.stringify(value);
   const both=list=>[...new Set(list.flatMap(dir=>[dir,real(dir)]).filter(Boolean))];
   const all=[...new Set(reads.flatMap(dir=>[dir,real(dir)]).filter(Boolean))];
@@ -337,20 +394,30 @@ export function seatbeltProfile(reads,own=null,hidden=[],{network='none',writes=
     // Its contents only, as on Linux: a run may still see that it exists, and write beneath it.
     ...hidden.length?[`(deny file-read-data process-exec* ${[...new Set(hidden.flatMap(file=>[file,path.join(real(path.dirname(file))??path.dirname(file),path.basename(file))]))]
       .map(file=>`(subpath ${quote(file)})`).join(' ')})`]:[],
+    ...docs?[docsRule(docs,both([docs.root]))]:[],
     '(deny network*)',...own?[`(allow network* ${[own,real(own)].filter(Boolean).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[],
-    ...network==='loopback'?['(allow network-bind)','(allow network-inbound)','(allow network-outbound (remote ip "localhost:*"))']:[],
     ...writes?['(deny file-write* (subpath "/tmp") (subpath "/private/tmp") (subpath "/var/tmp") (subpath "/private/var/tmp"))',
       `(allow file-write* ${both(writes).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[]].join('\n');
 }
+// docsByPattern's patterns for each root, and each listed file they do not cover by its path.
+function docsRule(docs,roots){
+  const named=docs.entries.filter(rel=>!docsByPattern(rel));
+  const patterns=roots.map(dir=>escape(dir)).flatMap(dir=>[`^${dir}/(.+/)?[^/]*\\.(md|mdx|rst)$`,`^${dir}/docs/(.+/)?[^/]*\\.(${docsFolderTypes.join('|')})$`])
+    .map(pattern=>`(regex #"${pattern.replace(/"/g,'\\"')}")`);
+  const files=roots.flatMap(dir=>named.map(rel=>`(literal ${JSON.stringify(path.join(dir,rel))})`));
+  return `(deny file-read-data process-exec* (require-all (vnode-type REGULAR-FILE) (require-any ${[...patterns,...files].join(' ')})))`;
+}
 // The argv that runs `argv` sandboxed: reads beneath `reads`, no network but
 // Unix sockets beneath `tmp` on macOS, nothing beneath `hidden` (absolute).
 // On Linux a hidden directory can still be listed and its entries stat'ed:
 // Landlock restricts neither beneath a listable parent.
-// `network` "loopback" and `writes`: a test run's (seatbeltProfile). On Linux
-// its network is supervised: `stats` then says whether the supervisor served
-// the whole run (supervisorIssue).
-export function sandboxArgv(mode,argv,{reads,tmp=null,python,hidden=[],stats=null,network='none',writes=null,fault=null}){
-  if(mode==='seatbelt')return ['/usr/bin/sandbox-exec','-p',seatbeltProfile(reads,tmp,hidden,{network,writes}),...argv];
+// `network` "loopback" and `writes`: a test run's. Only Linux gives it a
+// network (seatbeltProfile says why macOS does not), supervised: `stats`
+// then says whether the supervisor served the whole run (supervisorIssue).
+// `docs` ({root, entries}): the checkout's documentation, hidden too.
+export function sandboxArgv(mode,argv,{reads,tmp=null,python,hidden=[],stats=null,network='none',writes=null,fault=null,docs=null}){
+  if(mode==='seatbelt')return ['/usr/bin/sandbox-exec','-p',seatbeltProfile(reads,tmp,hidden,{writes,docs}),...argv];
+  if(docs)hidden=[...hidden,...docs.entries.map(rel=>path.join(docs.root,rel.replace(/\/$/,'')))];
   // The launcher's own warnings would become the check's output.
   if(mode==='landlock')return [python,'-I','-W','ignore',landlockScript,...reads.flatMap(dir=>['--read',dir]),
     ...hidden.flatMap(file=>['--hide',file]),...stats?['--stats',stats]:[],
@@ -517,6 +584,7 @@ export function runToEnd(argv,{cwd,env,timeout=0,echo=false,started=null}){
   });
 }
 // {same, plain, sandboxed, line} or {issue} when the sandbox cannot run here.
+// With `hide` 'docs', the documentation (hiddenDocs) is hidden too.
 // With `hide`, the git-ignored entries hiddenEntries lists are kept from the
 // sandboxed run, and it also returns them, their count, the run times and, on
 // Linux, the launcher's rule count and setup time.
@@ -528,18 +596,23 @@ export async function sandboxTrial(root,check,{timeout=300000,hide=false,plain:e
   const command=python?check.command:[lookup(scriptProject(root,check.script).manager,process.env.PATH,root)||'npm','run',check.script];
   const selected={...check,command,environment:sandboxEnvironment(python,python?null:scriptProject(root,check.script).manager,check.kind)};
   const tests=testRun(check);
-  const scratch=fs.mkdtempSync(path.join(os.tmpdir(),'redue-trial-')),home=path.join(scratch,'home'),tmp=path.join(scratch,'tmp');
-  fs.mkdirSync(home);fs.mkdirSync(tmp);
+  // A test run's home is beneath its temporary directory, as in cli.mjs: on
+  // macOS that is where its Unix sockets may be.
+  const scratch=fs.mkdtempSync(path.join(os.tmpdir(),'redue-trial-')),tmp=path.join(scratch,'tmp'),home=tests?path.join(tmp,'home'):path.join(scratch,'home');
+  fs.mkdirSync(tmp);fs.mkdirSync(home);
   try{
-    const entries=hide?hiddenEntries(root):[];
-    if(!entries)return {issue:hiddenListIssue};
-    const hidden=entries.map(rel=>path.join(root,rel.replace(/\/$/,""))),stats=(hide||tests)&&supported.mode==='landlock'?path.join(scratch,'stats.json'):null;
+    const ignored=hide?hiddenEntries(root):[],docEntries=hide==='docs'?hiddenDocs(root):[];
+    if(!ignored)return {issue:hiddenListIssue};
+    if(!docEntries)return {issue:hiddenDocsIssue};
+    const entries=[...ignored,...docEntries];
+    const hidden=ignored.map(rel=>path.join(root,rel.replace(/\/$/,""))),stats=(hide||tests)&&supported.mode==='landlock'?path.join(scratch,'stats.json'):null;
     const run=async(argv,env)=>{const started=Date.now(),r=await runToEnd(argv,{cwd:root,env,timeout});
       return {status:r.timedOut?'timeout':r.status??r.signal??r.error?.code,output:`${r.stdout}\n${r.stderr}`,ms:Date.now()-started};};
     const plain=earlier??await run(command,{...process.env,...python?{}:{npm_config_update_notifier:'false'}});
     const reads=[root,home,tmp,...sandboxPlaces(selected,process.env,root),...systemPlaces];
     const sandboxed=await run(sandboxArgv(supported.mode,command,{reads,tmp,python:supported.python,hidden,stats,
-      ...tests?{network:'loopback',writes:[root,home,tmp]}:{}}),sandboxEnv(selected,process.env,{root,home,tmp}));
+      ...hide==='docs'?{docs:{root,entries:docEntries}}:{},
+      ...tests?{...supported.mode==='landlock'?{network:'loopback'}:{},writes:[root,home,tmp]}:{}}),sandboxEnv(selected,process.env,{root,home,tmp}));
     // A test run's network was supervised throughout, on Linux.
     const supervisor=tests&&stats?supervisorIssue(stats):null;
     // A failure both ways counts as the same only without a sign of a refusal.
@@ -561,6 +634,6 @@ export async function sandboxTrial(root,check,{timeout=300000,hide=false,plain:e
     const differs=tests&&read?(JSON.stringify(counts[0])===JSON.stringify(counts[1])?null:{plain:JSON.stringify(counts[0]),sandboxed:JSON.stringify(counts[1])}):output;
     return {same:plain.status===sandboxed.status&&!denied&&!differs&&!supervisor,plain:plain.status,sandboxed:sandboxed.status,output:differs,plainRun:plain,
       line:supervisor||denied||(plain.status===sandboxed.status?null:sandboxed.output.trim().split('\n').at(-1)?.slice(0,200)||null),
-      ...hide?{hidden:entries.length,entries,plainMs:plain.ms,sandboxedMs:sandboxed.ms,...launcher?{rules:launcher.rules,setupMs:launcher.ms}:{}}:{}};
+      ...hide?{hidden:entries.length,entries,docs:docEntries.length,plainMs:plain.ms,sandboxedMs:sandboxed.ms,...launcher?{rules:launcher.rules,setupMs:launcher.ms}:{}}:{}};
   }finally{fs.rmSync(scratch,{recursive:true,force:true});}
 }

package/src/setup.mjs

@@ -12,6 +12,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {spawnSync} from 'node:child_process';
+import {testCounts} from './sandbox.mjs';
 import {createInterface} from 'node:readline/promises';
 import {projectState} from './project-location.mjs';
 import {claudeHooksInstalled,removeClaudeHooks,removeIntegration} from './agent-integration.mjs';
@@ -80,7 +81,19 @@ async function setup({root,redue,yes,record:previous,recordFile,exclude,save}){
   const names=configExisted?JSON.parse(readText(configPath)).checks.map(check=>check.name):found.checks.map(check=>check.name);
   const ready=names.filter(name=>levels.get(name)==='ready');
   console.log(`Setting up REDUE for Claude Code in ${root}`);
-  console.log(configExisted?`  keep ${configName} (exists)`:`  create ${configName}: ${names.map(name=>`${name} (${levels.get(name)==='ready'?'can qualify':'recording-only'})`).join(', ')}`);
+  console.log(configExisted?`  keep ${configName} (exists)`:`  create ${configName}: ${names.map(name=>`${name} (${levels.get(name)==='ready'?'can qualify':'recording only'})`).join(', ')}`);
+  // What the checks setup does not make reusable are, and why.
+  if(!configExisted){
+    const recording=found.checks.filter(check=>check.level!=='ready');
+    if(recording.length)console.log('  recording only: REDUE records these runs but never reports one CURRENT, because it cannot tell what the result depends on:');
+    for(const check of recording)console.log(`    ${check.name}: ${check.reason}`);
+    const out=[...found.skipped||[]].filter(row=>row.reason);
+    const kinds=new Set([...found.checks.map(check=>check.kind??check.name.split(':')[0]),...out.map(row=>String(row.kind).split(':')[0])]);
+    for(const kind of ['typecheck','lint','test'])if(!kinds.has(kind)&&!found.checks.some(check=>check.name===kind))
+      out.push({kind,reason:`${kind}: none found (no script or tool REDUE recognizes)`});
+    if(out.length)console.log('  left out:');
+    for(const row of out)console.log(`    ${row.reason.startsWith(String(row.kind))?row.reason:`${row.kind}: ${row.reason}`}`);
+  }
   console.log(`  write the Claude Code integration: CLAUDE.md section, .claude/skills/redue-verification/SKILL.md, ${localSettings} hooks, ${agentRecord}`);
   console.log(`  start the observer and record ${ready.length?ready.join(', '):'no check'} once, unless already CURRENT`);
   if(!await confirm('Proceed?',yes,{defaultYes:true})){console.log('Nothing written.');return {applied:false};}
@@ -121,7 +134,7 @@ async function setup({root,redue,yes,record:previous,recordFile,exclude,save}){
   // recorded as reusable. Wait while it plans and indexes; once its plan is
   // ready, an observer that is still unhealthy says why in the status below.
   // Nothing to wait for when no check can qualify.
-  const observation=()=>{const out=redue(['status','--json'],{capture:true});try{return JSON.parse(out.stdout).observation??null;}catch{return null;}};
+  const observation=()=>{const out=redue(['status','--cached','--json'],{capture:true});try{return JSON.parse(out.stdout).observation??null;}catch{return null;}};
   // An answer without a phase (a stopped observer) for 10 s in a row ends the
   // wait too.
   const begun=Date.now();let told=-1,unread=0,phaseless=0;
@@ -136,9 +149,18 @@ async function setup({root,redue,yes,record:previous,recordFile,exclude,save}){
   // One recorded run of each check that can qualify and is not CURRENT.
   const statusOf=()=>{const out=redue(['status','--sync','--json'],{capture:true,timeout:600_000});try{return JSON.parse(out.stdout).checks;}catch{return [];}};
   const rows=statusOf(),due=ready.filter(name=>rows.find(row=>row.name===name)?.freshness!=='CURRENT');
-  for(const name of due){console.log(`Recording ${name} once:`);redue(['run',name]);}
+  // One line per check; the run's own output only when it fails.
+  for(const name of due){
+    console.log(`Recording ${name} once (running it)...`);
+    const started=Date.now(),run=redue(['run',name],{capture:true});
+    const output=`${run.stdout??''}\n${run.stderr??''}`,counts=testCounts(output),seconds=((Date.now()-started)/1000).toFixed(1);
+    const tally=Object.entries(counts).filter(([,value])=>value!==null).map(([key,value])=>`${value} ${key}`).join(', ');
+    console.log(`  ${name}: ${run.status===0?'PASS':`FAIL (exit ${run.status??run.signal})`} in ${seconds} s${tally?`, ${tally}`:''}`);
+    if(run.status!==0)console.log(output.trim().split('\n').slice(-15).map(line=>`    ${line}`).join('\n'));
+  }
   if(ready.length&&!due.length)console.log(`Already CURRENT: ${ready.join(', ')}.`);
-  for(const row of statusOf())console.log(`  ${row.name}: ${row.freshness}${row.result?' / '+row.result:''}${row.freshness==='CURRENT'?'':' — '+row.reason}`);
+  for(const row of statusOf())console.log(`  ${row.name}: ${row.freshness}${row.result?' / '+row.result:''}${row.freshness==='CURRENT'?'':
+    levels.get(row.name)!=='ready'?' — recording only':' — '+row.reason}`);
   console.log('Done. Start a new Claude Code session in this project. Undo with redue remove.');
   return {applied:true};
 }