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

package/src/node-onboarding.mjs

@@ -1,6 +1,7 @@
 import {directProject,directQualification} from './direct-typescript.mjs';
-import {testProject,testRecipeScript,testCheckInputs,testEnvironmentIssue,testsQualification} from './test-direct.mjs';
-import {commandLineIssue,scriptCheckInputs,scriptPath,scriptProject,scriptQualification} from './node-script.mjs';
+import {testProject,testRecipeScript,testCheckInputs,testsQualification} from './test-direct.mjs';
+import {generalIssue,scriptCheckInputs,scriptProject,scriptQualification} from './node-script.mjs';
+import {sandboxCheckInputs,sandboxKinds,sandboxQualification} from './sandbox.mjs';
 // Init proposes the general recipe for typecheck and lint scripts; test
 // scripts use the direct test recipe (Vitest, Jest).
 const generalKinds=['typecheck','lint'];
@@ -110,7 +111,7 @@ const proposable=(dir,scripts)=>exists(path.join(dir,'tsconfig.json'))&&!typeche
 // The inputs a TypeScript contract adds to its check's config: no exclusions,
 // which would outlive the tsconfig they came from; the plan adds the current ones.
 const contractInputs=contract=>[...contract.configs,...contract.sourcePatterns.filter(p=>!p.startsWith('!'))];
-function sourceLinkIssue(root) {
+export function sourceLinkIssue(root) {
   const stack=likelyDirs.filter(name=>exists(path.join(root,name)));
   let inspected=0;
   while(stack.length){
@@ -207,22 +208,16 @@ export function workspacePackages(root){
 // supported package manager and platform, and a script (with its pre and post
 // scripts) that, read as text, starts only Node programs.
 function generalCheck(root,kind,script){
-  if(!['darwin','linux'].includes(process.platform))throw Error('the general recipe records runs on macOS and Linux only');
-  const environmentIssue=testEnvironmentIssue();
-  if(environmentIssue)throw Error(environmentIssue);
-  let project;
-  try{project=scriptProject(root,script);}catch(e){throw Error(e.code?.replace(/^test-/,'')||e.message);}
-  for(const name of ['pre'+script,script,'post'+script]){
-    if(typeof project.scripts[name]!=='string')continue;
-    const issue=commandLineIssue(project.scripts[name],{cwd:root,searchPath:scriptPath(root,process.env.PATH)});
-    if(issue)throw Error(name===script?issue:`${name}: ${issue}`);
-  }
+  const issue=generalIssue(root,script);
+  if(issue)throw Error(issue);
+  const project=scriptProject(root,script);
   return {config:{name:kind,script,kind,qualification:scriptQualification,...scriptCheckInputs(project.dirs)},manager:project.manager};
 }
 export function discoverNodeProject(root,{recipe=null}={}) {
-  if(recipe&&!['typescript-direct','tests-direct','node-script'].includes(recipe))
-    throw Error('unknown recipe; use typescript-direct, tests-direct or node-script');
-  // Without --recipe, init tries the strict recipes first, then the general one.
+  if(recipe&&!['typescript-direct','tests-direct','node-script','sandbox'].includes(recipe))
+    throw Error('unknown recipe; use typescript-direct, tests-direct, node-script or sandbox');
+  // Without --recipe, init tries the strict recipes first, then the general
+  // one, then the sandboxed one.
   const auto=recipe===null;
   root=realObservedPath(root);
   const packageFile=path.join(root,'package.json');
@@ -281,7 +276,7 @@ export function discoverNodeProject(root,{recipe=null}={}) {
           reason:`explicit local ${project.runner} ${project.version} run of script ${JSON.stringify(chosen.script)}; the whole checkout is its input; npm and lifecycle scripts are not executed`};
       }catch(e){classification={level:'recording',reason:`Test recipe unavailable (${e.code||e.message}); original npm script retained`};}
     }
-    if(recipe!=='node-script'&&pm.name==='pnpm'&&kind==='typecheck'&&!workspaces&&!pm.issue&&(script===undefined||tscRuns(scripts[script]))){
+    if(recipe!=='node-script'&&recipe!=='sandbox'&&pm.name==='pnpm'&&kind==='typecheck'&&!workspaces&&!pm.issue&&(script===undefined||tscRuns(scripts[script]))){
       try{
         parts=tscChecks('typecheck',script??null,scripts,run=>{
           const contract=pnpmTypecheckInputs(root,'.',run);
@@ -294,14 +289,40 @@ export function discoverNodeProject(root,{recipe=null}={}) {
           qualification:'pnpm-tsc-v1'};}
       catch(e){classification={level:'recording',reason:`pnpm TypeScript contract needs review: ${e.message}`};}
     }
+    // The general recipe's row, when it takes the script.
+    let generalIssue=null,generalRow=null;
     if((auto||recipe==='node-script')&&script&&generalKinds.includes(kind)&&classification.level!=='ready'&&!observationIssue){
       try{
         const general=generalCheck(root,kind,script);
-        checks.push({config:general.config,level:'ready',qualification:scriptQualification,
-          reason:`general recipe: ${general.manager} runs script ${JSON.stringify(script)} with REDUE's recorder in every Node process; the whole checkout is its input`});
+        generalRow={config:general.config,level:'ready',qualification:scriptQualification,
+          reason:`general recipe: ${general.manager} runs script ${JSON.stringify(script)} with REDUE's recorder in every Node process; the whole checkout is its input`};
+      }catch(e){generalIssue=e.message;classification={...classification,reason:`General recipe unavailable (${e.message}); ${classification.reason}`};}
+    }
+    // After the strict recipes, a root typecheck or lint script gets the
+    // sandboxed recipe, which also covers programs the general recipe cannot
+    // record. It is ready only once init has run it both ways (bin/redue.mjs);
+    // `fallback` is the row init writes when that shows a difference or the
+    // sandbox cannot run here: the general recipe's, when it takes the script.
+    // Where the sandbox cannot start at run time, a script the general recipe
+    // takes is recorded as it would record it (cli.mjs).
+    // A script whose program is not installed gets none, and neither does one
+    // that changes files (`--fix`, `--write`): init would run it twice.
+    const writes=script&&['pre'+script,script,'post'+script].map(name=>scripts[name]).find(text=>typeof text==='string'&&
+      /(?:^|\s)--(?:fix|write|unsafe-fixes)(?=[\s=]|$)/.test(text));
+    if(writes)classification={...classification,reason:`Sandboxed recipe unavailable (the script changes files: ${writes.match(/--(?:fix|write|unsafe-fixes)/)[0]}); ${classification.reason}`};
+    if((auto||recipe==='sandbox')&&script&&sandboxKinds.includes(kind)&&classification.level!=='ready'&&!observationIssue&&
+      !/REDUE cannot find/.test(generalIssue||'')&&!writes){
+      try{
+        const project=scriptProject(root,script);
+        const fallback=generalRow??{config:{...check,...classification.qualification?{qualification:classification.qualification}:{}},...classification};
+        checks.push({config:{name:kind,script,kind,qualification:sandboxQualification,...sandboxCheckInputs(project.dirs)},level:'ready',
+          qualification:sandboxQualification,fallback,
+          reason:`sandboxed recipe: ${project.manager} runs script ${JSON.stringify(script)} inside the OS sandbox${generalIssue?` (the general recipe cannot record it: ${generalIssue})`:
+            generalRow?'; where the sandbox cannot run, the general recipe records it':''}; the whole checkout is its input`});
         continue;
-      }catch(e){classification={...classification,reason:`General recipe unavailable (${e.message}); ${classification.reason}`};}
+      }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;
     if(parts&&classification.level==='ready'){
       for(const part of parts)checks.push({config:{...check,...part,qualification:classification.qualification},...classification});

package/src/node-script.mjs

@@ -12,7 +12,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import {pnpmShimTarget} from './pnpm-shims.mjs';
-import {testPackageManager,testWorkspaceDirs,testEnvironment} from './test-direct.mjs';
+import {testPackageManager,testWorkspaceDirs,testEnvironment,testEnvironmentIssue} from './test-direct.mjs';
 
 export const scriptQualification='node-script-v1';
 export const scriptInterpretation='node-script@1';
@@ -358,6 +358,21 @@ export function childProgram({file,args,cwd,searchPath,env=null,script=null},{to
     return {needsHeader:false};
   return {issue:`ran ${name}, a program REDUE does not record`};
 }
+// Why the general recipe could not record a root script now, or null: what
+// init checks before it proposes it. A sandboxed check whose sandbox cannot
+// start is recorded this way instead (cli.mjs).
+export function generalIssue(root,script){
+  if(!['darwin','linux'].includes(process.platform))return 'the general recipe records runs on macOS and Linux only';
+  const environment=testEnvironmentIssue();
+  if(environment)return environment;
+  let project;try{project=scriptProject(root,script);}catch(e){return e.code?.replace(/^test-/,'')||e.message;}
+  for(const name of ['pre'+script,script,'post'+script]){
+    if(typeof project.scripts[name]!=='string')continue;
+    const issue=commandLineIssue(project.scripts[name],{cwd:root,searchPath:scriptPath(root,process.env.PATH)});
+    if(issue)return name===script?issue:`${name}: ${issue}`;
+  }
+  return null;
+}
 // What a recorded run needs from the check: the workspace package directories
 // whose node_modules its installed inputs list. The script must still exist.
 export function scriptRunFacts(root,check){

package/src/presentation.mjs

@@ -2,7 +2,7 @@
 // The recipe that made a receipt, by the qualification it names.
 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'};
+  'typescript-noemit-v1':'npm TypeScript recipe','sandbox-v1':'sandboxed recipe'};
 export const recipeLabel=recipe=>recipes[recipe]??null;
 export function checkLabel(row) {
   return row.result==='FAIL'?'FAILED':row.freshness;

package/src/python-onboarding.mjs

@@ -0,0 +1,87 @@
+// Python projects for `redue init`: typecheck and lint checks that run mypy,
+// pyright, ty or ruff from the project's .venv under the sandboxed recipe
+// (sandbox.mjs). A tool is proposed when it is installed in .venv/bin. Its
+// arguments are the ones the project runs it with, read from CI workflows,
+// the Makefile, tox, nox, a justfile and shell scripts; without one, the
+// tool's own default (`ruff check`, `ty check`, `pyright`, and `mypy` with
+// its configured files or `.`).
+import fs from 'node:fs';
+import path from 'node:path';
+import {realObservedPath} from './path-identity.mjs';
+import {sandboxCheckInputs,sandboxQualification} from './sandbox.mjs';
+
+const read=file=>{try{return fs.readFileSync(file,'utf8');}catch{return '';}};
+const exists=file=>{try{fs.lstatSync(file);return true;}catch{return false;}};
+const executable=file=>{try{fs.accessSync(file,fs.constants.X_OK);return fs.statSync(file).isFile();}catch{return false;}};
+// Each tool, its kind, and the subcommand it runs as a check.
+export const pythonTools=[{tool:'mypy',kind:'typecheck',sub:[]},{tool:'pyright',kind:'typecheck',sub:[]},
+  {tool:'ty',kind:'typecheck',sub:['check']},{tool:'ruff',kind:'lint',sub:['check']}];
+// The text of a TOML or INI section, up to the next section header.
+const section=(text,header)=>{const at=text.split(/\r?\n/).findIndex(line=>line.trim()===header);
+  if(at<0)return null;const rest=text.split(/\r?\n/).slice(at+1);const end=rest.findIndex(line=>/^\s*\[/.test(line));
+  return (end<0?rest:rest.slice(0,end)).join('\n');};
+// Ways a project starts a tool: through uv, poetry or pdm, `python -m`, or from .venv/bin.
+const wrappers=[/^uv run(?: --(?:frozen|locked|no-sync|offline|quiet|all-extras|all-groups))*(?: --(?:group|extra|with|python|package) [^ ]+)* /,
+  /^poetry run /,/^pdm run /,/^python3?(?:\.\d+)? -m /,/^(?:\.\/)?\.venv\/bin\//,
+  // A variable that names the environment's bin directory: `${PREFIX}mypy`.
+  /^\$\{?[A-Za-z_]+\}?(?=[A-Za-z])/];
+// A tool's arguments in one line of a script or workflow, or null. The line
+// must run the tool and its subcommand plainly; arguments with shell syntax,
+// or ones that change files or install packages, are not taken.
+export function toolArgs(line,{tool,sub}){
+  let text=line.trim().replace(/^-\s+/,'').replace(/^run:\s*/,'').replace(/^[@-]+/,'');
+  text=text.split(/\s(?:&&|\|\||;|\|)\s/)[0].replace(/\s+/g,' ').trim();
+  for(let changed=true;changed;){changed=false;for(const wrapper of wrappers)if(wrapper.test(text)){text=text.replace(wrapper,'');changed=true;}}
+  const words=text.split(' ');
+  if(words[0]!==tool||JSON.stringify(words.slice(1,1+sub.length))!==JSON.stringify(sub))return null;
+  const args=words.slice(1+sub.length);
+  if(args.some(arg=>!/^[A-Za-z0-9_./:=,@+%-]+$/.test(arg)||/^--(?:fix|unsafe-fixes|write|install-types|watch)(?:=|$)/.test(arg)||arg.startsWith('..')||arg.startsWith('/')))return null;
+  return args;
+}
+// The places a project writes how it runs its tools, in order of preference.
+function scriptTexts(root){
+  const texts=[];
+  const workflows=path.join(root,'.github','workflows');
+  let files=[];try{files=fs.readdirSync(workflows).filter(file=>/\.ya?ml$/.test(file)).sort();}catch{}
+  for(const file of files)texts.push(read(path.join(workflows,file)));
+  for(const file of ['Makefile','makefile','justfile','tox.ini','noxfile.py'])texts.push(read(path.join(root,file)));
+  // Shell scripts: *.sh, or a file whose #! line runs a shell (scripts/check).
+  for(const dir of ['scripts','script','bin','ci']){let names=[];try{names=fs.readdirSync(path.join(root,dir)).sort();}catch{}
+    for(const name of names){const text=read(path.join(root,dir,name)).slice(0,65536);
+      if(name.endsWith('.sh')||/^#!\S*(?:\/|env\s+)(?:ba|z|da)?sh\b/.test(text))texts.push(text);}}
+  return texts;
+}
+// The arguments the project runs `tool` with, or its default.
+export function projectArgs(root,spec,texts=scriptTexts(root)){
+  for(const text of texts)for(const line of text.split(/\r?\n/)){
+    if(/^\s*#/.test(line))continue;
+    const args=toolArgs(line,spec);
+    if(args)return {args,source:'project'};
+  }
+  if(spec.tool!=='mypy')return {args:[],source:'default'};
+  // mypy without targets needs `files` in its configuration.
+  const configured=[section(read(path.join(root,'pyproject.toml')),'[tool.mypy]'),section(read(path.join(root,'mypy.ini')),'[mypy]'),
+    section(read(path.join(root,'.mypy.ini')),'[mypy]'),section(read(path.join(root,'setup.cfg')),'[mypy]')].some(text=>text&&/^\s*files\s*=/m.test(text));
+  return {args:configured?[]:['.'],source:'default'};
+}
+// The Python checks `init` proposes, or null when the root is not a Python
+// project. Each row is ready only once init has run it both ways (bin/redue.mjs).
+export function discoverPythonProject(root){
+  root=realObservedPath(root);
+  if(!['pyproject.toml','setup.cfg','setup.py','requirements.txt'].some(file=>exists(path.join(root,file))))return null;
+  const checks=[],skipped=[];
+  if(!exists(path.join(root,'.venv','pyvenv.cfg'))){
+    skipped.push({kind:'python',reason:'no .venv in the project root; REDUE runs Python tools from the project\'s .venv (uv sync, or Poetry with virtualenvs.in-project)'});
+    return {root,checks,skipped};
+  }
+  const texts=scriptTexts(root);
+  const found=pythonTools.filter(spec=>executable(path.join(root,'.venv','bin',spec.tool)));
+  for(const spec of found){
+    const {args,source}=projectArgs(root,spec,texts);
+    const several=found.filter(other=>other.kind===spec.kind).length>1;
+    checks.push({config:{name:several?`${spec.kind}:${spec.tool}`:spec.kind,kind:spec.kind,qualification:sandboxQualification,
+      command:[`.venv/bin/${spec.tool}`,...spec.sub,...args],...sandboxCheckInputs()},level:'ready',qualification:sandboxQualification,
+      reason:`sandboxed recipe: ${[spec.tool,...spec.sub,...args].join(' ')} from .venv${source==='project'?' as the project runs it':''}; the whole checkout is its input`});
+  }
+  return {root,checks,skipped};
+}

package/src/sandbox.mjs

@@ -0,0 +1,396 @@
+// The sandboxed recipe: a typecheck or lint command run inside an OS sandbox
+// that lets it read only the checkout, its installed packages, the toolchain,
+// system directories and a private home and temporary directory, with no
+// network: Seatbelt (sandbox-exec) on macOS, Landlock (landlock.py) on Linux.
+// The sandbox holds for every process the run starts, so programs REDUE
+// cannot record (native compilers and linters, Python tools) are covered.
+// The claim: the result holds for a run that sees only the project, its
+// installed packages and the toolchain, the way CI does.
+//
+// The run gets a controlled environment: the check's declared variables and
+// prefixes, a normalized PATH, a private HOME kept between runs, and a fresh
+// TMPDIR. All of it is fingerprinted (sandboxContext), with the identity of
+// the toolchain's executables.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawn,spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {lookup,scriptCaches,scriptCheckInputs,scriptProject,toolchainDirs} from './node-script.mjs';
+import {displayVariables} from './test-direct.mjs';
+
+export const sandboxQualification='sandbox-v1';
+export const sandboxInterpretation='sandbox@1';
+export const sandboxKinds=['typecheck','lint'];
+const fail=code=>{throw Object.assign(Error(code),{code});};
+const digest=value=>createHash('sha256').update(value).digest('hex');
+const real=file=>{try{return fs.realpathSync(file);}catch{return null;}};
+const within=(file,dir)=>file===dir||file.startsWith(dir.endsWith('/')?dir:dir+'/');
+const landlockScript=path.join(path.dirname(fileURLToPath(import.meta.url)),'landlock.py');
+
+// Python's caches in the checkout, as runner caches: not inputs.
+const pythonCaches=['**/__pycache__/**','**/.mypy_cache/**','**/.ruff_cache/**','**/.pytest_cache/**'];
+export const sandboxCaches=[...scriptCaches,...pythonCaches];
+// The project's virtual environment: installed files, observed by identity,
+// without Python's bytecode caches. Its interpreter links lead out of the
+// checkout to the interpreter it was made from, which sandboxContext
+// identifies instead.
+// Python 3.14 adds a `𝜋thon` link beside `python`.
+const venvInstalled=['.venv/**','!.venv/**/__pycache__/**','!.venv/bin/python*','!.venv/bin/pypy*','!.venv/bin/𝜋thon*'];
+// Inputs: the whole checkout, git-ignored files included, except .git, the
+// installed trees (node_modules, .venv) and runner caches.
+export function sandboxCheckInputs(dirs=[]){
+  const base=scriptCheckInputs(dirs);
+  return {inputs:[...base.inputs,'!.venv/**',...pythonCaches.map(pattern=>`!${pattern}`)],
+    installedInputs:[...base.installedInputs,...venvInstalled]};
+}
+// A Python check runs a tool from the project's .venv: `.venv/bin/TOOL ARGS`.
+export const pythonTool=check=>Array.isArray(check?.command)&&/^\.venv\/bin\/[A-Za-z0-9_.-]+$/.test(check.command[0]||'')?
+  path.basename(check.command[0]):null;
+// The variables a run gets from the caller, compared before reuse. HOME,
+// TMPDIR, PATH and the XDG directories are set by REDUE (sandboxEnv). A
+// script check names its package manager first among the executables, as the
+// general recipe does.
+const managers=['npm','pnpm','yarn','corepack'];
+export function sandboxEnvironment(python=false,manager=null){
+  return {variables:['TZ','LANG','LANGUAGE','CI','USER','LOGNAME'],
+    prefixes:['LC_','DYLD_','LD_',...python?['PYTHON','MYPY','RUFF_','PYRIGHT','TY_']:
+      ['NODE_','npm_config_','PNPM_','YARN_','COREPACK_','TSGO_']],
+    ...manager?{pathExecutables:['node',manager,...managers.filter(name=>name!==manager)]}:{}};
+}
+
+// Whether this machine can sandbox a run: {mode} or {issue}. Asked once per process.
+let support=null;
+export function sandboxSupport(){
+  if(support)return support;
+  if(process.env.VSTATE_TEST_FAULTS==='1'&&process.env.VSTATE_TEST_SANDBOX==='unavailable')
+    return support={mode:null,issue:'the sandbox is turned off for this test'};
+  if(process.platform==='darwin'){
+    const r=spawnSync('/usr/bin/sandbox-exec',['-p','(version 1)(allow default)','/usr/bin/true'],{encoding:'utf8',timeout:10000});
+    // Seatbelt cannot start inside another Seatbelt sandbox (Claude Code's, for one).
+    return support=r.status===0?{mode:'seatbelt'}:{mode:null,issue:/Operation not permitted/.test(r.stderr||'')?
+      'sandbox-exec cannot start inside another sandbox':`sandbox-exec cannot start (${(r.stderr||r.error?.code||r.status||'').toString().trim().slice(0,120)})`};
+  }
+  if(process.platform==='linux'){
+    const python=launcherPython();
+    if(!python)return support={mode:null,issue:'the Landlock launcher needs Python 3'};
+    let abi=null;
+    try{abi=JSON.parse(spawnSync(python,['-I','-W','ignore',landlockScript,'--probe'],{encoding:'utf8',timeout:10000}).stdout).abi;}catch{}
+    if(!Number.isInteger(abi))return support={mode:null,issue:'Landlock is unavailable in this kernel'};
+    // ABI 4 (Linux 6.7) is the first that can refuse TCP connections.
+    if(abi<4)return support={mode:null,issue:`Landlock ABI ${abi} cannot keep a run off the network; it needs ABI 4 (Linux 6.7)`};
+    return support={mode:'landlock',abi,python};
+  }
+  return support={mode:null,issue:'the sandboxed recipe runs on macOS and Linux only'};
+}
+const launcherPython=()=>['/usr/bin/python3','/bin/python3'].find(file=>{try{fs.accessSync(file,fs.constants.X_OK);return true;}catch{return false;}})||
+  lookup('python3',process.env.PATH,process.cwd());
+
+export const systemPlaces=process.platform==='darwin'?
+  ['/usr','/bin','/sbin','/System','/Library','/Applications','/opt/homebrew','/private/etc','/private/var/db','/private/var/select','/dev']:
+  ['/usr','/bin','/sbin','/lib','/lib32','/lib64','/libx32','/etc','/proc','/sys','/dev','/run'];
+// The PATH a run gets: the caller's, without the project's .venv/bin, which
+// `uv run`, `poetry run` and an activated environment put first; a Python
+// check gets it first again. So the forms of a command agree.
+export function sandboxPath(check,env,root){
+  const venvBin=path.join(root,'.venv','bin');
+  const rest=String(env.PATH??'').split(path.delimiter).filter(dir=>dir&&path.resolve(root,dir)!==venvBin);
+  return [...pythonTool(check)?[venvBin]:[],...rest].join(path.delimiter);
+}
+// The interpreter a .venv was made from: its real executable and installation
+// (pyvenv.cfg's `home` is the directory of the executable it was made with).
+export function venvBase(root){
+  const venv=path.join(root,'.venv');
+  let home=null;
+  try{home=/^home\s*=\s*(.+)$/m.exec(fs.readFileSync(path.join(venv,'pyvenv.cfg'),'utf8'))?.[1].trim()??null;}catch{}
+  const executable=real(path.join(venv,'bin','python'));
+  return {home,executable,prefix:home&&path.isAbsolute(home)?path.dirname(home):null};
+}
+// Program files a run starts from outside the checkout: Node, the package
+// managers, and a Python check's interpreter. Their identity is compared
+// before reuse.
+function toolchainExecutables(check,env,root){
+  if(pythonTool(check))return [venvBase(root).executable];
+  const searchPath=sandboxPath(check,env,root);
+  return ['node','npm','npx','pnpm','yarn','corepack'].map(name=>lookup(name,searchPath,root));
+}
+const sharedPrefixes=()=>{const home=os.homedir();return [home,path.join(home,'.local'),'/usr/local','/usr','/opt/homebrew','/'];};
+// What a run may read and execute outside the checkout: the toolchain's
+// installations and stores, and system directories.
+export function sandboxPlaces(check,env,root){
+  const home=os.homedir(),places=new Set();
+  const add=dir=>{const resolved=dir&&path.isAbsolute(dir)?real(dir):null;
+    if(resolved&&resolved!=='/'&&resolved!==home&&!within(home,resolved))places.add(resolved);};
+  // An installation root (bin/..), or the program alone when bin/.. is shared (~/.local, /usr/local).
+  const addRoot=file=>{const dir=path.dirname(path.dirname(file));add(sharedPrefixes().includes(dir)?file:dir);};
+  for(const file of toolchainExecutables(check,env,root))if(file)addRoot(file);
+  if(pythonTool(check)){const base=venvBase(root);add(base.prefix);add(base.home);}
+  else{
+    for(const dir of toolchainDirs(env))add(dir);
+    const cache=path.isAbsolute(env.XDG_CACHE_HOME||'')?env.XDG_CACHE_HOME:path.join(home,'.cache');
+    add(path.isAbsolute(env.COREPACK_HOME||'')?env.COREPACK_HOME:path.join(cache,'node','corepack'));
+    add(path.join(home,'.yarn','berry'));
+  }
+  return [...places].sort();
+}
+// The environment a run gets.
+export function sandboxEnv(check,env,{root,home,tmp}){
+  const variables=check.environment?.variables||[],prefixes=(check.environment?.prefixes||[]).map(prefix=>prefix.toLowerCase());
+  const out={};
+  for(const [key,value] of Object.entries(env))
+    if(variables.includes(key)||prefixes.some(prefix=>key.toLowerCase().startsWith(prefix))||displayVariables.includes(key))out[key]=value;
+  delete out._;delete out.REDUE_RUN_RECORD;
+  Object.assign(out,{PATH:sandboxPath(check,env,root),HOME:home,XDG_CONFIG_HOME:path.join(home,'.config'),
+    XDG_CACHE_HOME:path.join(home,'.cache'),XDG_DATA_HOME:path.join(home,'.local','share'),XDG_STATE_HOME:path.join(home,'.local','state'),
+    TMPDIR:tmp,TMP:tmp,TEMP:tmp,
+    // The checkout's .git is not an input. Tools may still see it, as in CI,
+    // but git commands find no repository.
+    GIT_DIR:path.join(home,'.no-repository'),GIT_CEILING_DIRECTORIES:path.dirname(root)});
+  if(pythonTool(check))out.VIRTUAL_ENV=path.join(root,'.venv');
+  else{
+    // Corepack's downloads stay where Corepack keeps them; npm's and pnpm's
+    // update checks read the network; Nx would hand work to its daemon.
+    const cache=path.isAbsolute(env.XDG_CACHE_HOME||'')?env.XDG_CACHE_HOME:path.join(os.homedir(),'.cache');
+    out.COREPACK_HOME=path.isAbsolute(env.COREPACK_HOME||'')?env.COREPACK_HOME:path.join(cache,'node','corepack');
+    Object.assign(out,{npm_config_update_notifier:'false',NX_DAEMON:'false'});
+  }
+  return out;
+}
+// The files in the checkout's .git that tools read to choose files (ruff's
+// and biome's ignore rules): the repository's exclude file and config. The
+// observer does not watch .git, so they are compared as context.
+function gitIgnoreSources(root){
+  let dir=path.join(root,'.git');
+  try{if(fs.statSync(dir).isFile()){
+    const gitdir=path.resolve(root,/^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dir,'utf8'))?.[1].trim()??'');
+    let common=gitdir;try{common=path.resolve(gitdir,fs.readFileSync(path.join(gitdir,'commondir'),'utf8').trim());}catch{}
+    dir=common;}}catch{return [];}
+  return ['info/exclude','config'].map(rel=>{try{return [rel,digest(fs.readFileSync(path.join(dir,rel)))];}catch{return [rel,null];}});
+}
+// What a sandboxed result depends on outside the observed files, compared
+// before reuse, one entry each so a change can be named (sandboxChange): every
+// variable the run gets (but its private directories and display variables),
+// the places it may read, the identity of the toolchain's executables and of
+// every directory on PATH (an installed or upgraded program changes its
+// directory), and the ignore rules in .git.
+export const sandboxPrefix='__redue_sandbox_';
+export function sandboxContext(check,env,root){
+  const identity=(file,keys=['dev','ino','mode','size','mtimeNs','ctimeNs'])=>{try{const st=fs.statSync(file,{bigint:true});
+    return [file,...keys.map(key=>String(st[key]))];}catch{return [file,'<unavailable>'];}};
+  const environment=sandboxEnv(check,env,{root,home:'<home>',tmp:'<tmp>'});
+  for(const key of displayVariables)delete environment[key];
+  const out={[`${sandboxPrefix}places__`]:digest(JSON.stringify(sandboxPlaces(check,env,root))),
+    [`${sandboxPrefix}executables__`]:digest(JSON.stringify(toolchainExecutables(check,env,root).map(file=>file?identity(file):null))),
+    [`${sandboxPrefix}git__`]:digest(JSON.stringify(gitIgnoreSources(root)))};
+  for(const [key,value] of Object.entries(environment))out[`${sandboxPrefix}variable:${key}__`]=digest(value);
+  for(const dir of environment.PATH.split(path.delimiter).filter(dir=>path.isAbsolute(dir)))
+    out[`${sandboxPrefix}directory:${dir}__`]=digest(JSON.stringify(identity(dir,['dev','ino','mtimeNs','ctimeNs'])));
+  return out;
+}
+// What changed between two sandboxed contexts, in words, or null.
+export function sandboxChange(before={},now={}){
+  const keys=[...new Set([...Object.keys(before),...Object.keys(now)])].filter(key=>key.startsWith(sandboxPrefix)).sort();
+  const key=keys.find(key=>before[key]!==now[key]);
+  if(!key)return null;
+  const name=key.slice(sandboxPrefix.length,-2);
+  return name==='places'?'the places a sandboxed run may read changed':
+    name==='executables'?'Node, a package manager or the interpreter changed':
+    name==='git'?'.git/info/exclude or .git/config changed':
+    name.startsWith('variable:')?`environment variable ${name.slice(9)} differs from the last run`:
+    !(key in now)?`PATH no longer has directory ${name.slice(10)}`:!(key in before)?`PATH has a new directory ${name.slice(10)}`:
+    `PATH directory ${name.slice(10)} changed (a program in it was installed, removed or upgraded)`;
+}
+// A run's private directories, in REDUE's state: the home it keeps between
+// runs, and a fresh temporary directory.
+// The temporary directory is under the system's, so a Unix socket path in it
+// stays short enough.
+export function sandboxDirs(state,name){
+  const home=path.join(state,'sandbox',digest(name).slice(0,16),'home');
+  fs.mkdirSync(home,{recursive:true,mode:0o700});
+  return {home,tmp:fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(),'redue-run-')))};
+}
+
+const ancestors=list=>[...new Set(list.flatMap(dir=>{const out=[];for(let at=path.dirname(dir);at!=='/'&&at!=='.';at=path.dirname(at))out.push(at);return out;}))];
+// The Seatbelt profile: reads and executes only beneath the places, the
+// metadata of their parent directories, and no network but Unix sockets in
+// 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.
+export function seatbeltProfile(reads,own=null){
+  const quote=value=>JSON.stringify(value);
+  const all=[...new Set(reads.flatMap(dir=>[dir,real(dir)]).filter(Boolean))];
+  return ['(version 1)','(allow default)','(deny file-read* process-exec*)',
+    `(allow file-read* process-exec* ${all.map(dir=>`(subpath ${quote(dir)})`).join(' ')} (literal "/") (literal "/etc") (literal "/var") (literal "/tmp"))`,
+    `(allow file-read-metadata ${ancestors(all).map(dir=>`(literal ${quote(dir)})`).join(' ')})`,
+    '(deny network*)',...own?[`(allow network* ${[own,real(own)].filter(Boolean).map(dir=>`(subpath ${quote(dir)})`).join(' ')})`]:[]].join('\n');
+}
+// The argv that runs `argv` sandboxed: reads beneath `reads`, no network but
+// Unix sockets beneath `tmp` on macOS.
+export function sandboxArgv(mode,argv,{reads,tmp=null,python}){
+  if(mode==='seatbelt')return ['/usr/bin/sandbox-exec','-p',seatbeltProfile(reads,tmp),...argv];
+  // 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]),'--no-tcp','--',...argv];
+  throw Error(`unknown sandbox ${mode}`);
+}
+// A line of a failed run's output that looks like the sandbox refused
+// something: a refused read or write, or the network unreachable. Such a
+// failure is run again outside the sandbox to tell a denial from a real one.
+const denial=/operation not permitted|permission denied|read-only file system|\bE(?:PERM|ACCES|ROFS|NOTFOUND|AI_AGAIN|CONNREFUSED|NETUNREACH|HOSTUNREACH)\b|sandbox-exec:|landlock\.py:|network is unreachable|could not resolve host|name or service not known|nodename nor servname|temporary failure in name resolution|getaddrinfo|connection refused/i;
+export function denialLine(text){
+  for(const line of String(text).split(/\r?\n/))if(denial.test(line))return line.trim().slice(0,200);
+  return null;
+}
+
+// Links in the .venv that lead out of the checkout, other than the
+// interpreter's in bin/: REDUE cannot observe what they point to. Looks in
+// the .venv itself, bin/, and the top of each site-packages.
+export function venvOutsideLinks(root){
+  const venv=path.join(root,'.venv'),found=[],realRoot=real(root)||root;
+  const look=dir=>{let entries;try{entries=fs.readdirSync(dir,{withFileTypes:true});}catch{return;}
+    for(const entry of entries){
+      if(!entry.isSymbolicLink())continue;
+      const file=path.join(dir,entry.name),rel=path.relative(root,file).split(path.sep).join('/');
+      if(/^\.venv\/bin\/(?:python|pypy|𝜋thon)/.test(rel))continue;
+      const target=real(file);
+      if(!target||!within(target,realRoot))found.push(rel);
+    }};
+  look(venv);look(path.join(venv,'bin'));
+  // lib64 is often a link to lib: looked at once.
+  for(const lib of ['lib','lib64']){let versions=[];
+    try{if(lib==='lib64'&&fs.lstatSync(path.join(venv,lib)).isSymbolicLink())continue;versions=fs.readdirSync(path.join(venv,lib));}catch{}
+    for(const version of versions)look(path.join(venv,lib,version,'site-packages'));}
+  return [...new Set(found)].sort();
+}
+// Plan qualification: the check is what `init` writes for the project now.
+export function qualifySandbox(root,selected){
+  const issues=[];
+  if(!['darwin','linux'].includes(process.platform))issues.push('the sandboxed recipe runs on macOS and Linux only');
+  if(!sandboxKinds.includes(selected.kind))issues.push(`the sandboxed recipe takes ${sandboxKinds.join(' and ')} checks`);
+  if(selected.cwd&&selected.cwd!=='.')issues.push('the sandboxed recipe runs checks at the project root');
+  const tool=pythonTool(selected);
+  try{
+    let dirs=[];
+    if(tool){
+      try{fs.accessSync(path.join(root,selected.command[0]),fs.constants.X_OK);}catch{fail(`${selected.command[0]} is not installed`);}
+      const base=venvBase(root);
+      if(!base.home||!base.executable)fail('.venv has no pyvenv.cfg home or bin/python');
+      // The interpreter's own site-packages are not observed.
+      if(/^include-system-site-packages\s*=\s*true\s*$/mi.test(fs.readFileSync(path.join(root,'.venv','pyvenv.cfg'),'utf8')))
+        issues.push('.venv uses the system site-packages, which REDUE does not observe');
+      for(const rel of venvOutsideLinks(root))issues.push(`${rel} links outside the checkout, where REDUE does not observe it`);
+    }else{
+      if(typeof selected.script!=='string')fail('script-missing');
+      const project=scriptProject(root,selected.script);
+      if(JSON.stringify(selected.command?.slice(1))!==JSON.stringify(['run',selected.script])||selected.environment?.pathExecutables?.[1]!==project.manager)
+        issues.push('the package manager or script changed; run redue init again');
+      dirs=project.dirs;
+    }
+    const expected=sandboxCheckInputs(dirs),sorted=list=>JSON.stringify([...(list||[])].sort());
+    if(sorted(selected.inputs)!==sorted(expected.inputs)||sorted(selected.installedInputs)!==sorted(expected.installedInputs))
+      issues.push('inputs must be the whole checkout, with node_modules and .venv observed as installed files; run redue init again');
+    const environment=sandboxEnvironment(Boolean(tool));
+    if(!environment.variables.every(key=>selected.environment?.variables?.includes(key))||
+      !environment.prefixes.every(key=>selected.environment?.prefixes?.includes(key)))
+      issues.push('execution context incomplete; run redue init again');
+  }catch(e){issues.push(e.code||'sandboxed check prerequisites unavailable');}
+  if(selected.probes?.length)issues.push('the sandboxed recipe takes no probes');
+  if(selected.generatedInputs?.length)issues.push('the sandboxed recipe takes no generated inputs');
+  return {qualified:issues.length===0,issues};
+}
+// Installed paths a sandboxed plan leaves out: the .venv's links that lead out
+// of the checkout, which the index cannot observe. Qualification reports them.
+export const sandboxInstalledExclusions=root=>venvOutsideLinks(root).map(rel=>`!${rel}`);
+// A run's output for comparison: without colors, timings, the temporary and
+// home directories each run had, and lines about caches, which differ
+// between two runs of the same check (a task runner's cache hit).
+const units='(?:ns|µs|us|ms|s|sec|secs|seconds?|m|min|mins|minutes?|h)';
+export function comparableOutput(text,paths=[]){
+  let out=String(text).replace(/\x1b\[[0-9;?]*[A-Za-z]/g,'');
+  for(const [from,to] of paths.filter(([from])=>from).sort((a,b)=>b[0].length-a[0].length))out=out.split(from).join(to);
+  return out.split(/\r?\n/).filter(line=>!/\bcache[ds]?\b|\bcached\b/i.test(line))
+    .map(line=>line.replace(new RegExp(`\\d+(?:[.,]\\d+)?\\s?${units}\\b`,'g'),'<time>')
+      .replace(/\b\d{1,2}:\d{2}(?::\d{2}(?:\.\d+)?)?\b/g,'<clock>').replace(/\d{4}-\d{2}-\d{2}T[\d:.]+Z?/g,'<date>').trimEnd())
+    .filter(Boolean).join('\n');
+}
+// `init` runs a proposed check both ways before it writes it: plainly, as the
+// project would, and sandboxed. The check is proposed only when both give
+// the same exit status and the same output (comparableOutput), and a failure
+// shows no sign of a refusal by the sandbox; else the reason names the
+// difference.
+// Stops what a run left running when it ends, as a CI job's end does: the
+// run's process group gets SIGTERM, and SIGKILL a second later if it still
+// has members. Its pid is not signalled again once the group is empty, so a
+// reused number is never hit. The timer keeps REDUE alive until then, and
+// the promise settles then. On Linux the Landlock launcher also stops
+// processes that left the group (landlock.py).
+export function stopGroup(pid){
+  const signal=name=>{try{process.kill(-pid,name);return true;}catch{return false;}};
+  if(!signal('SIGTERM'))return Promise.resolve();
+  const until=Date.now()+1000;
+  return new Promise(resolve=>{const check=setInterval(()=>{
+    if(!signal(0)){clearInterval(check);resolve();return;}
+    if(Date.now()>=until){signal('SIGKILL');clearInterval(check);resolve();}
+  },100);});
+}
+// A sandboxed run's end: when the command exits, what it left running is
+// stopped, and its pipes are closed a second later, so a helper that holds
+// them open does not hold the run.
+export function endWithChild(child){
+  child.on('exit',()=>{stopGroup(child.pid);setTimeout(()=>{child.stdout?.destroy();child.stderr?.destroy();},1000).unref();});
+}
+// Runs argv in its own process group to the end, with no terminal input:
+// {status, signal, error, timedOut, stdout, stderr}, each output kept up to
+// 64 MB and decoded at the end. `echo` also passes the output through.
+// `started` gets the child, so a caller can forward signals to its group;
+// without one, an interrupt stops the group and then REDUE.
+const outputCap=64*1024*1024;
+export function runToEnd(argv,{cwd,env,timeout=0,echo=false,started=null}){
+  return new Promise(resolve=>{
+    const kept={stdout:[],stderr:[]},size={stdout:0,stderr:0};
+    let timer=null,timedOut=false;
+    const child=spawn(argv[0],argv.slice(1),{cwd,env,detached:true,stdio:['ignore','pipe','pipe']});
+    const stop=async name=>{process.off('SIGINT',interrupt);process.off('SIGTERM',terminate);
+      await stopGroup(child.pid);process.kill(process.pid,name);};
+    const interrupt=()=>stop('SIGINT'),terminate=()=>stop('SIGTERM');
+    if(started)started(child);else{process.once('SIGINT',interrupt);process.once('SIGTERM',terminate);}
+    for(const name of ['stdout','stderr'])child[name].on('data',chunk=>{
+      if(echo)process[name].write(chunk);
+      if(size[name]<outputCap){kept[name].push(chunk);size[name]+=chunk.length;}
+    });
+    if(timeout)timer=setTimeout(()=>{timedOut=true;stopGroup(child.pid);},timeout);
+    endWithChild(child);
+    const finish=value=>{clearTimeout(timer);process.off('SIGINT',interrupt);process.off('SIGTERM',terminate);
+      resolve({...value,timedOut,stdout:Buffer.concat(kept.stdout).toString('utf8'),stderr:Buffer.concat(kept.stderr).toString('utf8')});};
+    child.on('error',error=>finish({status:null,signal:null,error}));
+    child.on('close',(status,signal)=>finish({status,signal}));
+  });
+}
+// {same, plain, sandboxed, line} or {issue} when the sandbox cannot run here.
+export async function sandboxTrial(root,check,{timeout=300000}={}){
+  const supported=sandboxSupport();
+  if(supported.issue)return {issue:supported.issue};
+  const python=Boolean(pythonTool(check));
+  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)};
+  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);
+  try{
+    const run=async(argv,env)=>{const 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}`};};
+    const plain=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}),sandboxEnv(selected,process.env,{root,home,tmp}));
+    // A failure both ways counts as the same only without a sign of a refusal.
+    const denied=sandboxed.status===0?null:denialLine(sandboxed.output);
+    const realOf=dir=>{try{return fs.realpathSync(dir);}catch{return null;}},plainTmp=process.env.TMPDIR||os.tmpdir();
+    const paths=[[home,'<home>'],[realOf(home),'<home>'],[tmp,'<tmp>'],[realOf(tmp),'<tmp>'],[plainTmp,'<tmp>'],[realOf(plainTmp),'<tmp>'],
+      [os.homedir(),'<home>'],[realOf(os.homedir()),'<home>']];
+    const [a,b]=[plain,sandboxed].map(r=>comparableOutput(r.output,paths).split('\n'));
+    // The first line that differs; past the end of the shorter output when one goes on.
+    let at=a.findIndex((line,i)=>line!==b[i]);
+    if(at<0&&b.length>a.length)at=a.length;
+    const output=at<0?null:{plain:(a[at]??'(no more output)').slice(0,160),sandboxed:(b[at]??'(no more output)').slice(0,160)};
+    return {same:plain.status===sandboxed.status&&!denied&&!output,plain:plain.status,sandboxed:sandboxed.status,output,
+      line:denied||(plain.status===sandboxed.status?null:sandboxed.output.trim().split('\n').at(-1)?.slice(0,200)||null)};
+  }finally{fs.rmSync(scratch,{recursive:true,force:true});}
+}