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

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.1.0-alpha.27 — 2026-11-01
+
+A build or test run no longer makes a sandboxed typecheck or lint STALE,
+and `redue stats` shows what REDUE saved you.
+
+- **Files git ignores are hidden from sandboxed runs.** A sandboxed
+  typecheck or lint now runs without the files git ignores (`dist/`,
+  `.next/`, coverage files, `.env`), except `node_modules`, `.venv` and
+  runner caches. Those files are not its inputs, so a build or test run that
+  writes them leaves the result CURRENT. The claim: the result holds for a
+  run that sees only the project's files that git doesn't ignore, its
+  installed packages and the toolchain. Only the project's `.gitignore`
+  files and `.git/info/exclude` count, not your global excludes file.
+- **Checks that need ignored files keep working.** `init` tries the
+  sandbox with ignored files hidden first (`sandbox-v2`), then with the
+  whole checkout (`sandbox-v1`), then the general recipe. A hidden run that
+  fails on a hidden file runs again in the sandbox without hiding, and that
+  result is kept. Checks set up by alpha.26 stay `sandbox-v1` until you run
+  `redue init` again.
+- **Measured.** In the product census, after each project's own build and
+  tests ran, checks that stayed CURRENT (alpha.26 in brackets, from the
+  measurement census): TypeScript on Linux 31 of 37 (5 of 43), on macOS 24
+  of 34 (5 of 38); Python on Linux 31 of 38 (24 of 37), on macOS 28 of 34
+  (20 of 33). Where a check qualifies with both, the sandbox stayed CURRENT
+  16 times and the general recipe 9 of 23 (Linux). The strace cross-check
+  found no read outside the recorded inputs.
+- **`redue stats`.** Per check: reruns the hook skipped, the time that
+  saved, recorded runs, and the top reasons a check was UNVERIFIED, from a
+  log in REDUE's local state.
+- `redue remove-state` no longer fails on Windows while the observer is
+  still closing its files.
+- Known limits: a sandboxed run can still see that a hidden file exists
+  (its name on macOS; listings, sizes and times on Linux), so a tool that
+  acts on existence alone is not covered; tests do not use hidden files for
+  that reason. On Linux, a file a run creates in a folder that holds hidden
+  files cannot be read back in the same run.
+- Contributors: eval entry points that run third-party code refuse to start
+  unless `GITHUB_ACTIONS=true`, and importing any eval entry point throws
+  before it does anything.
+
+## 0.1.0-alpha.26 — 2026-10-31
+
+Typecheck and lint checks run inside an OS sandbox, so REDUE can reuse them
+for native tools and for Python. Python projects are supported for the first
+time.
+
+- **Sandboxed recipe.** On macOS (Seatbelt) and Linux 6.7+ (Landlock), a
+  root typecheck or lint script runs in a sandbox that sees only the
+  project, its installed packages and the toolchain, the way CI does. Its
+  inputs are the whole checkout, git-ignored files included, plus the
+  installed packages and a fingerprint of the environment it was given. A
+  result holds for a run that sees only those. `init` tries the precise
+  TypeScript recipes first, then the sandbox, then the general recipe. See
+  [sandboxed recipe](docs/user/sandbox.md).
+- **Python.** `redue setup claude` and `init` find mypy, pyright, ty and
+  ruff in the project's `.venv`, from its CI workflows, Makefile, justfile,
+  tox, nox and scripts. The Claude Code hook recognizes `uv run`,
+  `poetry run`, `python -m` and `.venv/bin` forms.
+- **What the sandbox changes.** Network is off. HOME and the temp folder
+  are private to the check; HOME is kept between runs so caches persist.
+  Tools can read `.git`, but git commands find no repository. A background
+  process the check leaves running is stopped when the run ends.
+- **Checked at init.** `init` runs each check plainly and sandboxed, and
+  proposes the sandbox only when exit status and output (timings and paths
+  aside) match. Otherwise the general recipe applies. A failing run whose
+  output looks like a sandbox refusal is rerun plainly; if the plain run
+  exits differently, the result is UNVERIFIED. Other failures run once.
+- **Coverage.** In a census of 120 public TypeScript repositories (86
+  installed on macOS), 35 have a qualifying check (alpha.24 census: 30):
+  typecheck 22, lint 25, tests 2. Of 120 Python repositories, 23 of the 75
+  that installed on Linux have one (typecheck 15, lint 22); 20 of 64 on
+  macOS. 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.
+- **Measured with Claude Code.** On starlette, graphon and
+  claude-agent-sdk-python, sessions took 58 s with REDUE and 125 s without.
+  REDUE skipped 10 typechecks and every one matched a plain rerun.
+- Known limits: inside Claude Code's own macOS sandbox and on Windows, the
+  sandbox can't start and the general recipe applies. On Linux before 6.7,
+  sandboxed runs are UNVERIFIED.
+  A build or test run that writes into the checkout (`dist/`, `.next/`,
+  coverage files) makes a sandboxed check STALE, as it does a
+  general-recipe check: about 1 in 4 TypeScript and 2 in 3 Python checks
+  stayed CURRENT through the project's build and tests.
+
 ## 0.1.0-alpha.25 — 2026-10-29
 
 Running your tests no longer makes a typecheck STALE, and `status --sync`

package/README.md

@@ -10,9 +10,11 @@ check that still holds is not run again and one that is stale is.
 
 ## Quickstart (about 5 minutes)
 
-You need macOS or Linux, Node 22 or 24, Git, Claude Code, and a JavaScript or
-TypeScript project with its dependencies installed (`npm install`,
-`pnpm install` or `yarn`). On Linux, also Python 3.
+You need macOS or Linux, Node 22 or 24, Git, Claude Code, and either a
+JavaScript or TypeScript project with its dependencies installed
+(`npm install`, `pnpm install` or `yarn`), or a Python project with a `.venv`
+in its root (`uv sync`, or Poetry with in-project virtualenvs). On Linux, also
+Python 3.
 
 ```sh
 npm install --global @redue/cli@alpha
@@ -57,26 +59,39 @@ 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 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
+on your machine.
+
 To undo everything setup did: `redue remove`.
 
 ## What it covers today
 
-In a census of 120 active public TypeScript repositories (October 2026, REDUE
-at commit 0fcd19b, after 0.1.0-alpha.23), each installed as its users would,
-with dependencies' install scripts on, 86 installed cleanly. A check counts
-when two recorded runs on the same code both came out CURRENT on the same
-inputs. 30 repositories had at least one such check:
+In a census of 120 active public TypeScript repositories (November 2026, REDUE
+at commit e264a67, before 0.1.0-alpha.27), each installed as its users would,
+with dependencies' install scripts on, 90 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. 35 repositories had at least one such check:
 
 | Check | Repositories | How |
 |---|---|---|
-| Typecheck | 21 | 15 by running the project's script with every Node process recorded ([general recipe](docs/user/node-script.md)); 6 by running the local `tsc` directly ([direct recipe](docs/user/direct-typescript.md)) |
-| Lint | 18 | general recipe |
+| Typecheck | 22 | 16 by running the project's script in an OS sandbox ([sandboxed recipe](docs/user/sandbox.md)), 15 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 | 24 | 21 sandboxed recipe (19 with ignored files hidden), 3 general recipe |
 | Tests | 2 | Vitest run directly ([direct test recipe](docs/user/tests-direct.md)) |
 
+In a census of 120 Python repositories, 74 installed on a Linux runner
+and 23 had a qualifying check: typecheck (mypy, pyright, ty) 15, lint (ruff)
+22, all through the sandboxed recipe with ignored files hidden. A check whose
+git-ignored files are hidden stays CURRENT when a build or test run rewrites
+them: after each project's build and tests ran, 31 of 37 such TypeScript
+checks and 31 of 38 Python checks were still CURRENT on Linux. 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
-into (esbuild, turbo, nx, oxlint's tsgolint, TypeScript 7's native compiler),
-the project uses Bun, or a test suite writes into its own inputs.
+into and the sandbox can't run (inside Claude Code's macOS sandbox, on
+Windows), the project uses Bun, or a check writes into its own inputs.
 [Supported projects](docs/user/supported-projects.md) has the details.
 
 ## Measured with Claude Code

package/bin/redue.mjs

@@ -7,6 +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 os from 'node:os';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
@@ -31,7 +32,7 @@ Commands:
   setup claude [--yes] Set up REDUE and Claude Code in this project in one step:
                        init, agent setup claude, start, one recorded run per check
   remove [--yes]       Undo setup: integration, observer state, and the config setup created
-  init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct|node-script]
+  init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct|node-script|sandbox]
                        Discover existing scripts; optionally select one workspace/check
   agent setup codex|claude [--dry-run|--apply] [--json]
   agent doctor [codex|claude] [--json]
@@ -45,6 +46,7 @@ Commands:
   detail [CHECK] [--json]  Alias for explain
   run CHECK [--if-due] Execute one configured check and record its outcome; with --if-due,
                        only when its last pass does not apply to the files as they are now
+  stats [--json]       Per check: skips, time saved, recorded runs, why checks were UNVERIFIED
   remove-state         Stop and remove only this configuration's owned local state
 
 No checks run in the background. Direct commands outside redue create no receipts.`;
@@ -94,7 +96,7 @@ if(command==='agent'){
   catch(e){error(e.message);}
   await exit(0);
 }
-if(!['init','start','stop','status','detail','explain','run','remove-state'].includes(command))
+if(!['init','start','stop','status','detail','explain','run','stats','remove-state'].includes(command))
   error(`unknown command ${command||'<none>'}; use --help`);
 const json=args.includes('--json');
 // run --if-due: run the check only when its last pass does not apply now.
@@ -119,9 +121,28 @@ if(short&&(command!=='status'||json||sync))error('--short is a cached status opt
 if(dryRun&&command!=='init')error('--dry-run is for init');
 
 if(command==='init'){
-  const {discoverNodeProject}=await import('../src/node-onboarding.mjs');
-  let discovery;try{discovery=discoverNodeProject(process.cwd(),{recipe:recipeSelection});}
-  catch(e){error(e.message);}
+  const {discoverNodeProject,sourceLinkIssue}=await import('../src/node-onboarding.mjs');
+  const {discoverPythonProject}=await import('../src/python-onboarding.mjs');
+  const {sandboxTrial}=await import('../src/sandbox.mjs');
+  // A Node project, a Python project, or both in one checkout.
+  const python=!recipeSelection||recipeSelection==='sandbox'?discoverPythonProject(process.cwd()):null;
+  let discovery;
+  if(fs.existsSync('package.json')||!python)try{discovery=discoverNodeProject(process.cwd(),{recipe:recipeSelection});}
+    catch(e){error(e.message);}
+  else{const root=realObservedPath(process.cwd());
+    const git=spawnSync('git',['rev-parse','--show-toplevel'],{cwd:root,encoding:'utf8',timeout:3000,stdio:['ignore','pipe','ignore']});
+    discovery={schema:1,root,manager:{name:null,version:null,layout:null},observationIssue:git.status===0?sourceLinkIssue(root):
+      'Git checkout is unavailable; filesystem observation needs a checkout',workspaces:false,node:process.version,
+      checks:[],ambiguous:[],skipped:[],config:{schema:1,checks:[]}};}
+  if(python){
+    // A Python check takes its tool's name where the name is taken.
+    const taken=new Set(discovery.checks.map(row=>row.config.name));
+    for(const row of python.checks){if(taken.has(row.config.name))row.config.name=`${row.config.kind}:${row.config.command[0].split('/').at(-1)}`;
+      taken.add(row.config.name);}
+    if(!discovery.observationIssue)discovery.checks.push(...python.checks);
+    discovery.skipped.push(...python.skipped);
+    discovery.python=true;
+  }
   if(workspaceSelection||checkSelection){
     const chosen=discovery.checks.filter(row=>
       (!workspaceSelection||row.config.workspace===workspaceSelection||
@@ -130,6 +151,35 @@ if(command==='init'){
     if(!chosen.length)error('no discovered check matches the selected workspace and kind');
     discovery.checks=chosen;discovery.config.checks=chosen.map(row=>row.config);
   }
+  // 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 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.
+  const trialIssue=trial=>trial.issue?`the sandbox cannot run here (${trial.issue})`:
+    // A failure both ways that shows a refusal cannot be told from a real one.
+    trial.same?null:trial.plain!==trial.sandboxed?`exit ${trial.sandboxed} inside the sandbox, ${trial.plain} outside it${trial.line?` (${trial.line})`:''}`:
+    trial.line?`it fails both ways (exit ${trial.plain}), with a sign of a refusal inside the sandbox (${trial.line})`:
+    `the output differs inside the sandbox: ${JSON.stringify(trial.output.sandboxed)} instead of ${JSON.stringify(trial.output.plain)}`;
+  let trials=0;
+  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++;
+    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;}
+    // 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;
+    const issue=trialIssue(trial);
+    if(!issue){row.reason+=`; ran both ways at init, exit ${trial.plain}; it needs files git ignores (${hidden.issue??trialIssue(hidden)})`;continue;}
+    if(row.fallback)discovery.checks[at]={...row.fallback,reason:`Sandboxed recipe unavailable: ${issue}; ${row.fallback.reason}`};
+    else{discovery.checks[at]=null;discovery.skipped.push({kind:row.config.name,reason:`${row.config.name}: sandboxed recipe unavailable: ${issue}`});}
+  }
+  discovery.checks=discovery.checks.filter(Boolean).map(({fallback,...row})=>row);
+  discovery.config.checks=discovery.checks.map(row=>row.config);
   const configured=fs.existsSync(configFile),unsupported=Boolean(discovery.observationIssue||
     discovery.manager.issue&&!['npm','yarn','pnpm'].includes(discovery.manager.name)||
     discovery.manager.name==='yarn'&&!discovery.manager.version);
@@ -144,8 +194,9 @@ if(command==='init'){
       workspace:check.workspace||null,level,reason})),config:configFile,
     written:willWrite,existing:configured,writable:!configured&&!unsupported&&discovery.checks.length>0};
   if(!json) {
-    console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
+    if(summary.package_manager||!discovery.python)console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
       `${summary.version?' '+summary.version:''}; ${summary.installation_layout} installation.`);
+    if(discovery.python)console.log('Python project; tools run from .venv.');
     if(summary.issue)console.log(`Boundary: ${summary.issue}`);
     for(const row of summary.checks){
       console.log(`  ${row.name} (${row.script||row.command?.join(' ')}) — `+
@@ -167,7 +218,7 @@ if(command==='init'){
     if(!samePath(realObservedPath(path.dirname(configFile)),discovery.root))
       error('init writes only at the repository root; use --config there or --dry-run');
     fs.writeFileSync(configFile,JSON.stringify(discovery.config,null,2)+'\n',{flag:'wx'});
-    if(!json){console.log(`Created ${configFile}. No checks were executed.`);
+    if(!json){console.log(`Created ${configFile}. ${trials?'Sandboxed checks ran both ways to confirm them; no results were recorded.':'No checks were executed.'}`);
       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.');
@@ -269,6 +320,7 @@ const checks=publicConfig.checks.map(check=>{
   const pnpmTypecheck=check.qualification==='pnpm-tsc-v1';
   const testsDirect=check.qualification===testsQualification;
   const generalScript=check.qualification===scriptQualification;
+  const sandboxed=isSandboxed(check.qualification);
   if(check.script&&check.command&&!pnpmTypecheck&&!npmDirect&&!testsDirect)
     error(`${check.name}: choose script or command, not both`);
   const manager=publicConfig.packageManager;
@@ -278,12 +330,16 @@ const checks=publicConfig.checks.map(check=>{
     [`@which:${manager}`,'run',check.script]:null;
   const npmAutomatic=check.qualification==='typescript-noemit-v1';
   const yarnWorkspace=check.qualification==='yarn-workspace-tsc-v1';
-  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck&&!testsDirect&&!generalScript)
+  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck&&!testsDirect&&!generalScript&&!sandboxed)
     error(`${check.name}: unknown qualification contract`);
   // The general recipe runs the root package script through the package manager.
   if(generalScript&&(!['npm','pnpm','yarn'].includes(manager)||!check.script||check.command||check.cwd&&check.cwd!=='.'||
     check.workspace||!scriptKinds.includes(check.kind)))
     error(`${check.name}: the general recipe needs a root typecheck, test or lint script, without command or cwd`);
+  // The sandboxed recipe runs a root package script, or a tool from the project's .venv.
+  if(sandboxed&&(check.cwd&&check.cwd!=='.'||check.workspace||!sandboxKinds.includes(check.kind)||
+    (check.script?!['npm','pnpm','yarn'].includes(manager):!pythonTool(check))))
+    error(`${check.name}: the sandboxed recipe needs a root ${sandboxKinds.join(' or ')} script, or a command that runs a tool from .venv/bin, without cwd`);
   if(npmDirect&&(manager!=='npm'||check.cwd&&check.cwd!=='.'||!Array.isArray(check.command)||
     check.command[0]!=='@node'||check.command[1]!=='@typescript-compiler:.'||
     !tscRun({},{script:null,args:check.command.slice(2)}).run?.noEmit))
@@ -324,7 +380,8 @@ const checks=publicConfig.checks.map(check=>{
       check.workspace||'.',...run]]:[];
   const windowsContext=process.platform==='win32'?
     ['ComSpec','COMSPEC','PATHEXT','USERPROFILE']:[];
-  const autoEnvironment=npmDirect?directEnvironment:testsDirect?testEnvironment:generalScript?scriptEnvironment(manager):npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
+  const autoEnvironment=npmDirect?directEnvironment:testsDirect?testEnvironment:generalScript?scriptEnvironment(manager):
+    sandboxed?sandboxEnvironment(Boolean(pythonTool(check)),check.script?manager:null):npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
     'NODE_ENV','BASH_ENV','ENV',...windowsContext],prefixes:['npm_config_','DYLD_','TSGO_'],
     pathExecutables:['node','npm'],executableIdentity:true}:yarnWorkspace?
     {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
@@ -351,11 +408,18 @@ const checks=publicConfig.checks.map(check=>{
     ...(npmDirect?{qualificationInterpretation:directInterpretation}:{}),
     ...(testsDirect?{qualificationInterpretation:testsInterpretation}:{}),
     ...(generalScript?{qualificationInterpretation:scriptInterpretation}:{}),
+    ...(sandboxed?{qualificationInterpretation:sandboxInterpretationOf(check.qualification)}:{}),
     workspace:check.workspace||null,kind:check.kind||null};
 });
 const runtime={schema:1,provider:'declared-project@1',root,state,checks};
 try{assertOwnedStatePlacement(runtime);}catch(e){error(e.message);}
 const serialized=JSON.stringify(runtime,null,2)+'\n';
+if(command==='stats'){
+  const {readStats,renderStats}=await import('../src/stats.mjs');
+  const value=readStats(state,publicConfig.checks.map(item=>item.name));
+  console.log(json?JSON.stringify(value):renderStats(value));
+  await exit(0);
+}
 const maintenance=command==='stop'||command==='remove-state';
 if(maintenance&&!fs.existsSync(runtimeFile)){
   console.log(`No REDUE state exists for ${configFile}.`);
@@ -395,11 +459,14 @@ const internal=command==='remove-state'?'uninstall':
 // Asked when this part of a command runs, after earlier parts may have
 // changed files. REDUE_FORCE=1 runs it anyway.
 if(ifDue&&process.env.REDUE_FORCE!=='1'){
-  const {verdict}=await import('../src/claude-hook.mjs');
+  const [{verdict},{note,skipNote,dueNote}]=await Promise.all([import('../src/claude-hook.mjs'),import('../src/stats.mjs')]);
   const asked=spawnSync(process.execPath,[fileURLToPath(import.meta.url),'--config',configFile,...(stateOverride?['--state-dir',stateOverride]:[]),
     'status','--sync','--json'],{encoding:'utf8',stdio:['ignore','pipe','ignore'],env:process.env,timeout:600_000});
   let status=null;try{status=JSON.parse(asked.stdout);}catch{}
+  const due=dueNote(status,check);
+  if(due)note(state,due);
   if(verdict(status,check)){
+    note(state,skipNote(status,check,'if-due'));
     const row=status.checks.find(item=>item.name===check);
     if(json)console.log(JSON.stringify({check,skipped:true,result:'PASS',run_id:row.invocation.runId}));
     else console.error(`REDUE: ${check} passed on these exact inputs (run ${row.invocation.runId}); not run again. REDUE_FORCE=1 runs it anyway.`);

package/docs/README.md

@@ -5,6 +5,7 @@ For users:
 - [Install, initialize, run, and remove](user/getting-started.md)
 - [Fixed-build opt-in development pilot](user/pilot.md)
 - [Supported projects and conservative boundaries](user/supported-projects.md)
+- [Sandboxed recipe: typecheck and lint in any language, Python included](user/sandbox.md)
 - [Configuration](user/configuration.md)
 - [Connect coding agents and apply the decision policy](user/agents.md)
 - [JSON contract](user/json.md)

package/docs/user/node-script.md

@@ -4,10 +4,12 @@ The general recipe records a project's own typecheck or lint script, run
 through its package manager, and reports later whether that result still
 applies to the files you have. It is a lower tier than the strict recipes:
 `redue init` tries the [direct TypeScript recipe](direct-typescript.md), the
-pnpm and Yarn TypeScript recipes and the [direct test recipe](tests-direct.md)
-first, and uses the general recipe for a root typecheck or lint script none of
-them takes. Test scripts use the direct test recipe; `init` does not propose
-the general recipe for them.
+pnpm and Yarn TypeScript recipes, the [direct test recipe](tests-direct.md)
+and, on macOS and Linux, the [sandboxed recipe](sandbox.md) first. It uses
+the general recipe for a root typecheck or lint script none of them takes,
+and where the sandbox cannot run (at init, or at run time inside Claude
+Code's macOS sandbox). Test scripts use the direct test recipe; `init` does
+not propose the general recipe for them.
 
 It supports a project installed by npm, pnpm 9-12 (isolated or hoisted
 `node_modules`) or Yarn with the `node-modules` linker, with one lockfile kind
@@ -121,8 +123,10 @@ recording-only.
 Anything else makes the result UNVERIFIED and names the program: `git`,
 `sleep`, `find`, and native programs from installed packages such as esbuild,
 turbo, tsgo, tsgolint and biome, whose reads, writes and network use REDUE
-cannot see. `init` reads the script the same way and keeps a script that
-starts such a program recording-only, with the program in the reason.
+cannot see. `init` reads the script the same way. A typecheck or lint script
+gets the [sandboxed recipe](sandbox.md) first where it can run, which covers
+such programs; otherwise a script that starts one stays recording-only, with
+the program in the reason.
 
 A command line may use `&&`, `||`, `;`, `|`, quotes without expansions,
 globs in arguments and redirection to `/dev/null`. Variables, command

package/docs/user/sandbox.md

@@ -0,0 +1,221 @@
+# Sandboxed recipe (typecheck and lint, any language)
+
+The sandboxed recipe runs a typecheck or lint 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.
+
+**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.
+
+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).
+
+## Where it applies
+
+- **Node projects:** a root `typecheck` or `lint` script (npm, pnpm, or Yarn
+  with the `node-modules` linker). `init` tries the
+  [direct TypeScript recipe](direct-typescript.md) and the pnpm and Yarn
+  TypeScript recipes first; they stay first where they apply. Then the
+  sandboxed recipe, before the [general recipe](node-script.md), since it
+  also covers the native programs a script starts. Where init's trials show
+  a difference, or the sandbox cannot run, `init` writes the general recipe
+  as before. Where the sandbox cannot start at run time (inside Claude Code's
+  macOS sandbox), a script the general recipe takes is recorded as it records
+  it.
+- **Python projects:** mypy, pyright, ty and ruff installed in the project's
+  `.venv` (`uv sync` makes one; Poetry does with `virtualenvs.in-project`).
+  `init` uses the arguments your CI workflow, Makefile, tox, nox, justfile or
+  shell scripts in `scripts/` run the tool with, through `uv run`, `poetry run`,
+  `python -m` or `.venv/bin`. Without them it uses the tool's default:
+  `ruff check`, `ty check`, `pyright`, and `mypy` (with `.` when mypy's
+  configuration names no `files`).
+- **Platforms:** macOS (Seatbelt, `sandbox-exec`) and Linux 6.7 or later
+  (Landlock; the launcher needs Python 3).
+
+```sh
+redue init
+redue start
+redue run typecheck
+redue status --sync
+```
+
+A Python check in the config:
+
+```json
+{"name": "typecheck", "kind": "typecheck", "qualification": "sandbox-v2",
+ "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.
+
+With the Claude Code hook, `uv run mypy src`, `poetry run mypy src`,
+`python -m mypy src`, `.venv/bin/mypy src` and `mypy src` are recognized as
+that check. The last two count only when PATH finds the tool or Python in the
+project's `.venv/bin` first. When the hook runs the check through REDUE, it
+keeps `uv run` or `poetry run` in front, so the environment still syncs first.
+
+## Files git ignores
+
+`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`.
+
+With `sandbox-v2`, each run hides what `git ls-files --others --ignored
+--exclude-standard --directory` lists, except `node_modules`, `.venv` and
+runner caches: build output (`dist/`, `.next/`), coverage files, `.env` files.
+Only the project's rules count: its `.gitignore` files and
+`.git/info/exclude`, not your global excludes file. Those files are not
+inputs, so a build or test run that writes them leaves the result CURRENT.
+
+When a `sandbox-v2` 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.
+
+## What the run sees
+
+It may read and execute only beneath:
+
+- the checkout, without the files git ignores for `sandbox-v2`;
+- 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
+Unix sockets are in its own temporary directory, which is new for each run.
+On Linux 6.12 and later it cannot reach an abstract Unix socket outside the
+run.
+
+What the check leaves running is stopped when it exits, as at the end of a
+CI job: its process group gets SIGTERM, and SIGKILL a second later. On Linux
+the launcher also stops daemons that started their own session. On macOS
+such a daemon outlives the run, but no later run can reach it: its socket
+was in a temporary directory that is gone. The run gets no terminal input.
+
+The checkout's `.git` is not an input. Tools still see it, as they do in a CI
+checkout (a linter that applies `.gitignore` only inside a repository does),
+but git commands find no repository: `GIT_DIR` points nowhere. A script that
+runs git (`git diff --exit-code`) gives a different result inside the
+sandbox, and `init` leaves it to the other recipes.
+
+It gets a controlled environment, not yours:
+
+- the variables the check declares (`TZ`, `LANG`, `CI`, `USER`, `LC_*`,
+  `DYLD_*`, `LD_*`, and `NODE_*`, `npm_config_*`, `PNPM_*`, `YARN_*`,
+  `COREPACK_*` for Node, or `PYTHON*`, `MYPY*`, `RUFF_*`, `PYRIGHT*`, `TY_*`
+  for Python), with your values;
+- your PATH, without the project's `.venv/bin`, which a Python check gets
+  first instead, so `uv run` and an activated environment give the same PATH;
+- `HOME`, `TMPDIR` and the XDG directories in its private directories;
+  `VIRTUAL_ENV` for a Python check; Corepack's home where Corepack keeps it.
+
+## 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
+  in it, git-ignored files and git-ignored links to files in it included
+  (`sandbox-v1`), except `.git` and runner caches (the general recipe's, plus
+  `__pycache__`, `.mypy_cache`, `.ruff_cache` and `.pytest_cache`);
+- `node_modules` and `.venv`, observed as installed files, by identity;
+- the environment the run gets (without display variables such as `TERM`
+  and `COLUMNS`), and the places it may read;
+- Node's and the package managers' executables, or the interpreter the
+  `.venv` was made from, by file identity;
+- every directory on PATH, by identity: installing, removing or upgrading a
+  program in one makes the result STALE;
+- `.git/info/exclude` and `.git/config`, by content: ruff and biome read the
+  ignore rules there, and they decide what `sandbox-v2` hides. For a project
+  in a subdirectory of its repository, also the `.gitignore` files above it.
+
+## Telling a refusal from a real failure
+
+A run the sandbox refused something fails like any other. REDUE does not run
+every failure twice to find out:
+
+- `init` runs each proposed check twice, plainly and sandboxed, and proposes
+  it only when both give the same exit status and the same output, and a
+  failure shows no sign of a refusal. The output is compared without colors,
+  timings, the temporary and home directories, and lines about caches.
+  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
+  runs again in the sandbox without hiding (see
+  [files git ignores](#files-git-ignores)).
+- When a sandboxed run fails and its output has a line that looks like a
+  refusal ("Operation not permitted", "Permission denied", "Read-only file
+  system", a name lookup or a connection that failed), REDUE runs the check
+  again outside the sandbox. If that exits differently, the result is the
+  plain run's and UNVERIFIED: "the sandbox changed the result", with the
+  line. A failure without such a line is not run again.
+
+## The private home
+
+The run's home directory is kept between runs, per check, so caches tools
+build there (font caches, a type checker's cache) are not rebuilt every run.
+It starts empty: your configuration files are not in it. What a run leaves
+there can change a later run, and REDUE trusts it like a runner cache. Remove
+it with `redue remove-state`.
+
+## Limits
+
+- Inside Claude Code's own sandbox on macOS, `sandbox-exec` cannot start: the
+  run goes ahead unsandboxed and is UNVERIFIED ("the run was not sandboxed").
+  On Linux, Landlock works inside it.
+- Windows is not supported. The check stays recording-only there.
+- Linux before 6.7 (Landlock ABI below 4) cannot refuse TCP connections, so a
+  run there is UNVERIFIED. UDP is not refused on Linux.
+- System files (time zones, certificates, `/etc`) are not inputs: a change to
+  them does not make a result STALE.
+- A program that reads files in `.git` itself, without git (a commit hash for
+  a version string), reads something REDUE does not observe: a commit does
+  not make the result STALE.
+- Runner caches in the checkout are trusted as the general recipe trusts them.
+- On Linux, a run can still reach a daemon started outside it through a Unix
+  socket file (Landlock does not cover them), and what that daemon reads is
+  not seen. On macOS it cannot.
+- On Linux, uv hard-links `.venv` files to its cache. The cache is
+  toolchain: a file rewritten through the cache, not through the `.venv`, is
+  noticed only when the observer next reads the `.venv` (when it starts).
+- A `.venv` link that leads out of the checkout, other than the interpreter's,
+  keeps the check recording-only and names the link, and so does a `.venv`
+  that uses the system site-packages.
+- A git-ignored link to a directory, or out of the checkout, is not observed,
+  and neither is a `node_modules` directory outside the installed ones (a
+  nested example project's).
+- A script that changes files (`--fix`, `--write`) does not get this recipe:
+  `init` would run it twice.
+- With `sandbox-v2`, 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
+  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
+  back in the same run. `init`'s trial and the rerun without hiding catch a
+  check that needs to.
+- A file whose git status changes without a change to its content (`git add
+  -f` of an ignored file, `git rm --cached` of a tracked one) is noticed only
+  when its content next changes. A change to `.gitignore` or
+  `.git/info/exclude` makes the result STALE.
+- A run that moves a hidden folder into a visible place can read it there.
+  That changes the checkout during the run, so the run is not reused.

package/docs/user/supported-projects.md

@@ -18,11 +18,15 @@ build scripts. It prefers familiar script names (for typecheck: `typecheck`,
 (`typecheck:test`, `tsc:build`; not a watch script), then unique recognizable
 `tsc`, Vitest/Jest, ESLint, or Vite commands under other names. Multiple
 matches are reported as ambiguous rather than guessed. It never creates a new
-project script. Without `--recipe`, `init` tries the strict recipes below first,
-then the [general recipe](node-script.md) for a root typecheck or lint
-script: the script run through the package manager with every Node process
-recorded and the whole checkout as its input. `--recipe typescript-direct`,
-`tests-direct` or `node-script` selects one recipe alone. The direct TypeScript recipe supports
+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
+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
+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`,
+`tests-direct`, `node-script` or `sandbox` selects one recipe alone. The direct TypeScript recipe supports
 a typecheck script of `tsc --noEmit` runs in any argument order, chained runs,
 or no typecheck script at all (a proposed `tsc --noEmit`; see
 [script forms](direct-typescript.md#script-forms)), in a single-package npm installation using

package/package.json

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