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

package/src/sandbox.mjs

@@ -0,0 +1,493 @@
+// 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';
+import picomatch from 'picomatch';
+
+export const sandboxQualification='sandbox-v1';
+export const sandboxInterpretation='sandbox@1';
+// The same recipe with the checkout's git-ignored files hidden from the run
+// (hiddenEntries): they are not its inputs, so build and test outputs do not
+// make it STALE. init gives it when the run gives the same result that way.
+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;
+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 repository's .git that tools read to choose files (ruff's
+// and biome's ignore rules), and that decide what sandbox-v2 hides: its
+// exclude file and config. For a project in a subdirectory of the
+// repository, also the .gitignore files above it. The observer watches
+// neither, so they are compared as context.
+function gitIgnoreSources(root){
+  let top=root;
+  while(!fs.existsSync(path.join(top,'.git'))){const up=path.dirname(top);if(up===top)return [];top=up;}
+  let dir=path.join(top,'.git');
+  try{if(fs.statSync(dir).isFile()){
+    const gitdir=path.resolve(top,/^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 [];}
+  const read=file=>{try{return digest(fs.readFileSync(file));}catch{return null;}};
+  const above=[];
+  for(let at=path.dirname(root);top!==root&&(at===top||at.startsWith(top+path.sep));at=path.dirname(at)){
+    above.push([path.relative(top,path.join(at,'.gitignore')),read(path.join(at,'.gitignore'))]);
+    if(at===top)break;
+  }
+  return [...['info/exclude','config'].map(rel=>[rel,read(path.join(dir,rel))]),...above];
+}
+// 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-')))};
+}
+
+// The checkout's git-ignored entries a run may be kept from reading: what
+// `git ls-files --others --ignored --exclude-standard --directory` lists (a
+// wholly ignored directory as one entry, ending in /), but the installed
+// trees (node_modules, .venv) and runner caches. Relative to root. null when
+// git cannot list them. Only the project's rules count (.gitignore files and
+// .git/info/exclude), not a user's global excludes file, as on CI.
+const installedTree=/(?:^|\/)(?:node_modules|\.venv)(?:\/|$)/;
+const runnerCache=picomatch(sandboxCaches,{dot:true});
+const projectGit=['-c','core.excludesFile=/dev/null'],gitEnv=()=>({...process.env,GIT_OPTIONAL_LOCKS:'0'});
+export function hiddenEntries(root){
+  const r=spawnSync('git',[...projectGit,'ls-files','-z','--others','--ignored','--exclude-standard','--directory'],
+    {cwd:root,encoding:'utf8',maxBuffer:256*1024*1024,timeout:60000,stdio:['ignore','pipe','ignore'],env:gitEnv()});
+  if(r.status!==0)return null;
+  return r.stdout.split('\0').filter(Boolean).filter(rel=>!installedTree.test(rel)&&
+    !runnerCache(rel)&&!runnerCache(rel.replace(/\/$/,'')+'/x'));
+}
+
+// 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
+// inside an ignored build directory is). {has(rel)} for a file, or null when
+// git cannot tell. A directory git ignores holds no file it does not, so
+// asking a new directory once covers its files.
+export function ignoredNow(root,paths){
+  const asked=paths;
+  if(!asked.length)return {has:()=>false};
+  const listed=new Set();
+  for(let at=0;at<asked.length;at+=500){
+    const r=spawnSync('git',[...projectGit,'ls-files','-z','--others','--ignored','--exclude-standard','--directory','--',...asked.slice(at,at+500)],
+      {cwd:root,encoding:'utf8',maxBuffer:256*1024*1024,timeout:10000,stdio:['ignore','pipe','ignore'],env:gitEnv()});
+    if(r.status!==0)return null;
+    for(const entry of r.stdout.split('\0'))if(entry)listed.add(entry);
+  }
+  const entries=[...listed].filter(entry=>!installedTree.test(entry));
+  return {has:rel=>entries.some(entry=>rel===entry||entry.endsWith('/')&&rel.startsWith(entry))};
+}
+// The files git tracks now beneath `entries` (relative). null when git cannot tell.
+export function trackedBeneath(root,entries){
+  if(!entries.length)return new Set();
+  const r=spawnSync('git',['ls-files','-z','--cached','--',...entries],
+    {cwd:root,encoding:'utf8',maxBuffer:256*1024*1024,timeout:10000,stdio:['ignore','pipe','ignore'],env:gitEnv()});
+  return r.status===0?new Set(r.stdout.split('\0').filter(Boolean)):null;
+}
+// A refusal line that names a hidden entry (relative): a refusal by the
+// sandbox, or a missing file, which Linux tools report for an unreadable one.
+export function hiddenRefusal(text,hidden){
+  const names=hidden.map(file=>file.replace(/\/$/,'')).filter(Boolean)
+    .map(name=>new RegExp(`(?:^|[\\s'"\`(=/])${escape(name)}(?:[/\\s'"\`):,]|$)`));
+  for(const line of String(text).split(/\r?\n/))
+    if((denial.test(line)||missing.test(line))&&names.some(name=>name.test(line)))return line.trim().slice(0,200);
+  return null;
+}
+
+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. `hidden`:
+// absolute paths it may not read at all, not even their metadata.
+export function seatbeltProfile(reads,own=null,hidden=[]){
+  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(' ')})`,
+    // The entry's own path, by its directory's real path: a hidden link's target is not hidden.
+    ...hidden.length?[`(deny file-read* 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(' ')})`]:[],
+    '(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, 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.
+export function sandboxArgv(mode,argv,{reads,tmp=null,python,hidden=[],stats=null}){
+  if(mode==='seatbelt')return ['/usr/bin/sandbox-exec','-p',seatbeltProfile(reads,tmp,hidden),...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]),
+    ...hidden.flatMap(file=>['--hide',file]),...stats?['--stats',stats]:[],'--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;
+// A missing file counts only when the line names a path the run was kept
+// from (`hidden`, relative to the checkout or absolute): Linux tools report
+// an unreadable file as not found.
+const missing=/not found|no such file|cannot find|can't find|could not find|cannot read|\bENOENT\b/i;
+const escape=text=>text.replace(/[.*+?^${}()|[\]\\]/g,'\\$&');
+export function denialLine(text,hidden=[]){
+  // A name as a whole path or path component, not inside a longer word.
+  const names=hidden.map(file=>file.replace(/\/$/,'')).filter(Boolean)
+    .map(name=>new RegExp(`(?:^|[\\s'"\`(=/])${escape(name)}(?:[/\\s'"\`):,]|$)`));
+  for(const line of String(text).split(/\r?\n/))
+    if(denial.test(line)||missing.test(line)&&names.some(name=>name.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.
+// 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.
+// `plain`: the plain run of an earlier trial of the same check, reused.
+export async function sandboxTrial(root,check,{timeout=300000,hide=false,plain:earlier=null}={}){
+  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 entries=hide?hiddenEntries(root):[];
+    if(!entries)return {issue:hiddenListIssue};
+    const hidden=entries.map(rel=>path.join(root,rel.replace(/\/$/,""))),stats=hide&&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}),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,entries);
+    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)};
+    let launcher=null;if(stats)try{launcher=JSON.parse(fs.readFileSync(stats,'utf8'));}catch{}
+    return {same:plain.status===sandboxed.status&&!denied&&!output,plain:plain.status,sandboxed:sandboxed.status,output,plainRun:plain,
+      line: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}:{}}:{}};
+  }finally{fs.rmSync(scratch,{recursive:true,force:true});}
+}

package/src/setup.mjs

@@ -38,7 +38,8 @@ export async function setupCommand(args,{entry,cwd=process.cwd()}){
   const top=git(cwd,'rev-parse','--show-toplevel');
   if(top.status!==0)throw Error('run this inside a Git checkout');
   const root=fs.realpathSync(top.stdout.trim());
-  if(!fs.existsSync(path.join(root,'package.json')))throw Error(`no package.json at the repository root (${root})`);
+  if(!['package.json','pyproject.toml','setup.cfg','setup.py','requirements.txt'].some(file=>fs.existsSync(path.join(root,file))))
+    throw Error(`no package.json or Python project at the repository root (${root})`);
   // The entry as invoked, so a hook written by a child names the install's
   // stable bin link rather than the versioned file behind it.
   const invoked=typeof process.argv[1]==='string'&&path.isAbsolute(process.argv[1])&&
@@ -59,8 +60,12 @@ export async function setupCommand(args,{entry,cwd=process.cwd()}){
 }
 
 async function setup({root,redue,yes,record:previous,recordFile,exclude,save}){
-  if(!fs.existsSync(path.join(root,'node_modules')))
+  // A Node project needs node_modules; a Python one its .venv.
+  const node=fs.existsSync(path.join(root,'package.json'));
+  if(node&&!fs.existsSync(path.join(root,'node_modules')))
     throw Error('dependencies are not installed: run your package manager\'s install (npm install, pnpm install, yarn) first');
+  if(!node&&!fs.existsSync(path.join(root,'.venv','pyvenv.cfg')))
+    throw Error('no .venv in the project root: create it first (uv sync, or Poetry with virtualenvs.in-project)');
   if(fs.existsSync(path.join(root,'vstate.config.json'))&&!fs.existsSync(path.join(root,configName)))
     throw Error('a legacy vstate.config.json exists; rename it to redue.config.json or remove it first');
   if(git(root,'ls-files','--error-unmatch',localSettings).status===0)

package/src/stats.mjs

@@ -0,0 +1,72 @@
+// `redue stats`: what REDUE did for each check, from a local log. The hook,
+// `run --if-due` and recorded runs append one line each to stats-v1.jsonl in
+// the project's state: a skip (with the skipped run's duration), a recorded
+// run, or a check that was due (STALE or UNVERIFIED, with the reason). The log
+// stays on this machine and goes away with `redue remove-state`.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const statsFile=state=>path.join(state,'stats-v1.jsonl');
+
+// Never fails the command it is called from.
+export function note(state,entry){
+  try{fs.appendFileSync(statsFile(state),JSON.stringify({at:Date.now(),...entry})+'\n',{mode:0o600});}catch{}
+}
+
+// A skip of `name`, from a status row that allowed it.
+export const skipNote=(status,name,via)=>{
+  const ms=status?.checks?.find(row=>row?.name===name)?.invocation?.durationMs;
+  return {kind:'skip',check:name,via,savedMs:Number.isFinite(ms)&&ms>=0?ms:null};
+};
+// A check about to run because its last result does not apply, or null.
+export const dueNote=(status,name)=>{
+  const row=status?.observation?.healthy===true?status.checks?.find(item=>item?.name===name):null;
+  return row&&row.freshness!=='CURRENT'?{kind:'due',check:name,freshness:row.freshness,reason:row.reason??null}:null;
+};
+
+// Run ids, hashes and digits in a reason say nothing about its kind.
+const reasonKind=reason=>String(reason??'no reason').replace(/[0-9a-f]{8}(?:-?[0-9a-f]{4,})+|[0-9a-f]{12,}/g,'…').slice(0,160);
+
+export function readStats(state,names=[]){
+  let text='';try{text=fs.readFileSync(statsFile(state),'utf8');}catch{}
+  // Configured checks first, in config order, then any the log still names.
+  const checks=new Map();
+  const row=name=>{let value=checks.get(name);
+    if(!value)checks.set(name,value={name,skips:0,savedMs:0,runs:0,passed:0,failed:0,runMs:0,stale:0,unverified:0,reasons:{}});
+    return value;};
+  for(const name of names)row(name);
+  let since=null;
+  for(const line of text.split('\n')){
+    let entry;try{entry=JSON.parse(line);}catch{continue;}
+    if(typeof entry?.check!=='string')continue;
+    since??=entry.at;
+    const value=row(entry.check);
+    if(entry.kind==='skip'){value.skips++;value.savedMs+=entry.savedMs??0;}
+    else if(entry.kind==='run'){value.runs++;value.runMs+=entry.ms??0;
+      if(entry.result==='PASS')value.passed++;else if(entry.result==='FAIL')value.failed++;}
+    else if(entry.kind==='due'&&entry.freshness==='STALE')value.stale++;
+    else if(entry.kind==='due'&&entry.freshness==='UNVERIFIED'){value.unverified++;
+      const kind=reasonKind(entry.reason);value.reasons[kind]=(value.reasons[kind]??0)+1;}
+  }
+  const list=[...checks.values()].map(({reasons,...value})=>({...value,
+    topUnverified:Object.entries(reasons).sort((a,b)=>b[1]-a[1]).slice(0,3).map(([reason,count])=>({reason,count}))}));
+  return {schema:1,since:since===null?null:new Date(since).toISOString(),checks:list};
+}
+
+export const duration=ms=>!ms?'0s':ms<60_000?`${(ms/1000).toFixed(ms<10_000?1:0)}s`:
+  ms<3_600_000?`${Math.floor(ms/60_000)}m ${Math.round(ms%60_000/1000)}s`:`${Math.floor(ms/3_600_000)}h ${Math.round(ms%3_600_000/60_000)}m`;
+
+export function renderStats(value){
+  if(!value.since)return 'No skips or recorded runs yet.';
+  const head=['check','skips','saved','runs','pass','fail','stale','unverified'];
+  const rows=value.checks.map(c=>[c.name,c.skips,duration(c.savedMs),c.runs,c.passed,c.failed,c.stale,c.unverified].map(String));
+  const total=value.checks.reduce((sum,c)=>({skips:sum.skips+c.skips,savedMs:sum.savedMs+c.savedMs}),{skips:0,savedMs:0});
+  const widths=head.map((h,i)=>Math.max(h.length,...rows.map(r=>r[i].length)));
+  const line=r=>r.map((cell,i)=>i?cell.padStart(widths[i]):cell.padEnd(widths[i])).join('  ');
+  const lines=[`Since ${value.since.slice(0,10)}: ${total.skips} skips saved ${duration(total.savedMs)}.`,'',line(head),...rows.map(line)];
+  const reasons=value.checks.filter(c=>c.topUnverified.length);
+  if(reasons.length){lines.push('','Why checks were UNVERIFIED when they were due:');
+    for(const c of reasons)for(const r of c.topUnverified)lines.push(`  ${c.name}  ${r.count}×  ${r.reason}`);}
+  lines.push('','Saved is the duration of the run each skip reused.');
+  return lines.join('\n');
+}