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

package/src/claude-hook.mjs

@@ -13,6 +13,7 @@ import {processAlive} from './process-liveness.mjs';
 import {scriptRunChecks} from './typescript-invocation.mjs';
 import {recipeLabel} from './presentation.mjs';
 import {findExecutable} from './executable-lookup.mjs';
+import {note,skipNote,dueNote} from './stats.mjs';
 
 export const hookCommand='redue agent hook claude';
 // No shell metacharacters; `@` starts scoped package names.
@@ -22,10 +23,42 @@ const typecheck=check=>check?.kind==='typecheck'||check?.name==='typecheck';
 const tests=check=>check?.qualification==='npm-tests-direct-v1'&&Array.isArray(check.command)&&
   /^@test-runner:(?:vitest|jest)$/.test(check.command[1]||'');
 // A general recipe check: a root typecheck, test or lint script run through the package manager.
-const general=check=>check?.qualification==='node-script-v1'&&['typecheck','test','lint'].includes(check.kind)&&
-  typeof check.script==='string';
-const eligibleCheck=check=>typecheck(check)||tests(check)||general(check);
-export const checkKind=check=>tests(check)?'test':general(check)?check.kind:'typecheck';
+const general=check=>(check?.qualification==='node-script-v1'&&['typecheck','test','lint'].includes(check.kind)||
+  sandboxed(check))&&typeof check.script==='string';
+// A sandboxed check: a root package script, or a tool from the project's .venv.
+// sandbox.mjs's isSandboxed, written out: the hook does not load the sandbox module.
+const sandboxed=check=>['sandbox-v1','sandbox-v2'].includes(check?.qualification)&&['typecheck','lint'].includes(check.kind);
+const python=check=>sandboxed(check)&&Array.isArray(check.command)&&/^\.venv\/bin\/[A-Za-z0-9_.-]+$/.test(check.command[0]||'')&&
+  check.command.every(word=>typeof word==='string'&&safe.test(word));
+const eligibleCheck=check=>typecheck(check)||tests(check)||general(check)||python(check);
+export const checkKind=check=>tests(check)?'test':general(check)||python(check)?check.kind:'typecheck';
+// The ways an agent runs a Python check's tool: through uv or Poetry, with
+// `python -m`, from .venv/bin, or by name. A form that starts with `python`
+// or the tool's name depends on PATH, so the hook takes it only when PATH
+// finds that program in the project's .venv/bin first (pathForm).
+const wrappers=['uv run ','poetry run '];
+function pythonForms(check){
+  const [file,...args]=check.command,tool=file.split('/').at(-1),rest=args.length?' '+args.join(' '):'';
+  return [`.venv/bin/${tool}${rest}`,`./.venv/bin/${tool}${rest}`,`.venv/bin/python -m ${tool}${rest}`,
+    ...wrappers.flatMap(wrapper=>[`${wrapper}${tool}${rest}`,`${wrapper}python -m ${tool}${rest}`]),
+    `python -m ${tool}${rest}`,`python3 -m ${tool}${rest}`,`${tool}${rest}`];
+}
+// For a form that names a program PATH finds (`mypy .`, `python -m mypy .`),
+// whether PATH finds it first in the project's .venv/bin.
+export function pathForm(form,projectRoot,env=process.env){
+  const word=form.split(' ')[0];
+  if(word.includes('/')||wrappers.some(wrapper=>form.startsWith(wrapper)))return true;
+  if(!projectRoot)return false;
+  for(const dir of String(env.PATH??'').split(path.delimiter)){
+    if(!dir||!path.isAbsolute(dir))continue;
+    try{fs.accessSync(path.join(dir,word),fs.constants.X_OK);}catch{continue;}
+    try{return fs.realpathSync(dir)===fs.realpathSync(path.join(projectRoot,'.venv','bin'));}catch{return false;}
+  }
+  return false;
+}
+// The wrapper a matched form starts with, kept when the hook runs the check
+// through REDUE: `uv run` and `poetry run` sync the environment first.
+const wrapperOf=form=>wrappers.find(wrapper=>form.startsWith(wrapper))||'';
 
 export const defaultConfig='redue.config.json';
 // The `redue` prefix for a config beside the project root; null when the name
@@ -141,7 +174,8 @@ export function hookForms(config,configFile=defaultConfig,packageScripts=null){
     const forms=redue?[`${redue} run ${check.name}`]:[],local=[],dir=checkDir(check),key=groupOf(check),
       group=key?scripts.get(key):null,part=group?.length>1;
     const own=group?null:checkScript(check);
-    if(dir==='.'){
+    if(dir==='.'&&python(check))forms.push(...pythonForms(check));
+    else if(dir==='.'){
       forms.push(...scriptForms(pm,own),...toolForms(pm,toolText(check,packageScripts)));
       if(!tests(check)&&Array.isArray(check.command)&&check.command.length&&
         check.command.every(v=>typeof v==='string'&&safe.test(v)&&!v.startsWith('@')))
@@ -258,11 +292,16 @@ function split(command){
 // {check, rest}, or {fanout, rest} for a turbo/nx/`pnpm -r` command or a root
 // script that runs one; null when nothing matches. `dir` is where the command
 // runs, relative to the project root.
-function matched(command,config,configFile,dir='.',scripts={}){
+function matched(command,config,configFile,dir='.',scripts={},projectRoot=null){
   const parts=split(command);
   if(!parts)return null;
   const row=hookForms(config,configFile,dir==='.'?scripts:null).find(row=>dir==='.'?row.forms.includes(parts.base):
     row.dir===dir&&row.local.includes(parts.base));
+  // A Python check's form that depends on PATH matches only where PATH finds
+  // the project's .venv/bin.
+  const check=row&&config.checks.find(item=>item.name===row.check);
+  if(python(check)&&!parts.base.startsWith('redue'))
+    return pathForm(parts.base,projectRoot)?{check:row.check,rest:parts.rest,wrapper:wrapperOf(parts.base)}:null;
   // A root script that a general check runs is that check, even when the script fans out.
   if(dir==='.'&&row&&general(config.checks.find(check=>check.name===row.check)))return {check:row.check,rest:parts.rest};
   if(dir==='.'){
@@ -331,7 +370,7 @@ export function chainCommand(command,config,configFile,dir='.',scripts={},invoke
   const names=[];let plain=true;
   const text=parts.map(({separator,text})=>{
     const lead=text.match(/^\s*/)[0],trail=text.match(/\s*$/)[0],body=text.trim();
-    const match=matched(body,config,configFile,dir,scripts),split_=split(body);
+    const match=matched(body,config,configFile,dir,scripts,projectRoot),split_=split(body);
     // A compiler script is its checks in the order of its runs.
     const checks=match?.check?[match.check]:match?.row&&projectRoot?scriptChecks(match.row,config,projectRoot):null;
     if(!checks?.length||match.rest!==null||!split_||!checks.every(name=>safe.test(name))){
@@ -339,22 +378,23 @@ export function chainCommand(command,config,configFile,dir='.',scripts={},invoke
     if(!plain)return null;
     names.push(...checks);
     // Grouped, so a separator before it applies to all its runs.
-    const runs=checks.map(name=>`${redue} run ${name} --if-due`).join(' && ');
+    const runs=checks.map(name=>`${match.wrapper||''}${redue} run ${name} --if-due`).join(' && ');
     return `${separator}${lead}${checks.length>1?`{ ${runs}; }`:runs}${split_.suffix}${trail}`;
   });
   return names.length&&!text.includes(null)?{command:text.join(''),names}:null;
 }
-export function matchCheck(command,config,configFile,dir,scripts){
-  const match=matched(command,config,configFile,dir,scripts);
+export function matchCheck(command,config,configFile,dir,scripts,projectRoot=null){
+  const match=matched(command,config,configFile,dir,scripts,projectRoot);
   return match?.row?match.row.checks.join(' && '):match?.check||null;
 }
 // The same check (or checks, in order) through REDUE, keeping the output
 // suffix; null if it already is, or if more commands follow it.
-export function recordedCommand(command,name,configFile=defaultConfig,invoke='redue'){
+// A `uv run` or `poetry run` wrapper stays in front, so the environment syncs first.
+export function recordedCommand(command,name,configFile=defaultConfig,invoke='redue',wrapper=''){
   const names=Array.isArray(name)?name:[name];
   const parts=split(command),redue=redueFor(configFile)?.replace(/^redue/,()=>invoke);
   if(!parts||parts.rest!==null||!names.length||!names.every(value=>safe.test(value))||!redue)return null;
-  const run=names.map(value=>`${redue} run ${value}`).join(' && ');
+  const run=names.map(value=>`${wrapper}${redue} run ${value}`).join(' && ');
   return parts.base===run?null:names.length>1&&parts.suffix?`(${run})${parts.suffix}`:run+parts.suffix;
 }
 
@@ -467,6 +507,9 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
   const project=hookProject(root);
   if(!project)return null;
   const {record,config,parsed}=project;
+  // For `redue stats`: the checks a decision skipped, or the ones that were due.
+  const tally=(status,names,skipped)=>{let state;try{state=projectState(project.projectRoot,config);}catch{return;}
+    for(const name of names){const entry=skipped?skipNote(status,name,'hook'):dueNote(status,name);if(entry)note(state,entry);}};
   const entered=enteredDir(command,root,project.projectRoot);
   if(!entered)return null;
   let scripts={};
@@ -488,7 +531,7 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
     return cached?.observation?.healthy===true&&chained.names.every(name=>cached.checks?.some(row=>row?.name===name))?
       {hookSpecificOutput:{hookEventName:'PreToolUse',updatedInput:{...input.tool_input,command:entered.prefix+chained.command}}}:null;
   }
-  const match=matched(entered.command,parsed,record.config,entered.dir,scripts);
+  const match=matched(entered.command,parsed,record.config,entered.dir,scripts,project.projectRoot);
   if(!match)return null;
   // A check followed by more than a simple chain runs untouched.
   if(match.rest!==null&&!match.fanout)return null;
@@ -499,6 +542,7 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
     if(!names)return null;
     const status=await synchronizedStatus(entry,config,root,timeout??lastRunTimeout(config,parsed,...names)),
       reason=fanoutVerdict(status,names,match.rest);
+    tally(status,names,Boolean(reason));
     return reason?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}:null;
   }
   // A compiler script: its checks in the order of its runs, or nothing when
@@ -512,6 +556,7 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
     else{
       const status=await synchronizedStatus(entry,config,root,timeout??lastRunTimeout(config,parsed,...names)),
         reason=fanoutVerdict(status,names,match.rest);
+      tally(status,names,Boolean(reason));
       if(reason)return {hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}};
       const pending=names.filter(name=>!verdict(status,name));
       const rewritten=status?.schema===1&&status.observation?.healthy===true&&Array.isArray(status.checks)&&
@@ -523,6 +568,7 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
   }
   const name=match.check,status=await synchronizedStatus(entry,config,root,timeout??lastRunTimeout(config,parsed,name)),
     reason=verdict(status,name,match.rest);
+  tally(status,[name],Boolean(reason));
   if(reason)return {hookSpecificOutput:{hookEventName:'PreToolUse',
     permissionDecision:'deny',permissionDecisionReason:reason}};
   // Rewrite only on a healthy answer for this check: without an observer,
@@ -530,7 +576,7 @@ export async function claudeHook(input,{entry,timeout,invoke=null}){
   // stays too: the rewrite returns "allow", which would also skip the prompt
   // for the rest of the chain.
   const rewritten=status?.schema===1&&status.observation?.healthy===true&&Array.isArray(status.checks)&&
-    status.checks.some(item=>item?.name===name)?recordedCommand(entered.command,name,configPath,invoke??redueInvocation(entry)):null;
+    status.checks.some(item=>item?.name===name)?recordedCommand(entered.command,name,configPath,invoke??redueInvocation(entry),match.wrapper):null;
   // updatedInput replaces the whole tool input. Deny and ask rules still apply
   // to the rewritten command; "allow" skips only the prompt.
   return rewritten?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow',

package/src/cli.mjs

@@ -7,7 +7,9 @@ import {queryAnswer,runFactChange} from './typescript-list.mjs';
 import {patternMatcher} from './glob.mjs';
 import {observedBy} from './installed-observation.mjs';
 import {changedFiles,coverageReadable,gitIgnored,recordedEnvironment,testEnvironmentIssue,testGuardConfig,testRunGuard,testRunFacts,sharedInstalledFile,testsInterpretation,testsQualification} from './test-direct.mjs';
-import {childProgram,lookup,pnpmConfigFiles,scriptCaches,scriptInstalledPaths,scriptInterpretation,scriptQualification,scriptRunFacts,pnpmNameless,toolOutput,toolchainDirs} from './node-script.mjs';
+import {childProgram,generalIssue,lookup,pnpmConfigFiles,scriptCaches,scriptInstalledPaths,scriptInterpretation,scriptQualification,scriptRunFacts,pnpmNameless,toolOutput,toolchainDirs} from './node-script.mjs';
+import {denialLine,endWithChild,hiddenEntries,hiddenQualification,hiddenRefusal,isSandboxed,runToEnd,sandboxArgv,sandboxContext,sandboxDirs,sandboxEnv,
+  sandboxInterpretation,sandboxInterpretationOf,sandboxPlaces,sandboxQualification,sandboxSupport,systemPlaces} from './sandbox.mjs';
 import path from 'node:path';
 import net from 'node:net';
 import os from 'node:os';
@@ -27,6 +29,7 @@ import {atomicJson,commitReceipt,readReceipts,receiptRevision} from './state-sto
 import {timing,profiling,mark,traceContext} from './decision-profile.mjs';
 import {readCachedStatus,unavailableCached} from './cached-state.mjs';
 import {renderRun} from './presentation.mjs';
+import {note} from './stats.mjs';
 
 mark('cli.loaded');
 const here=path.dirname(fileURLToPath(import.meta.url));
@@ -83,7 +86,8 @@ function environmentReads() {
   try{const value=JSON.parse(fs.readFileSync(readsFile,'utf8'));return value?.schema===1&&value.checks||{};}catch{return {};}
 }
 const recordedRecipes=[testsQualification,scriptQualification];
-function contextHashes() {const reads=config.checks.some(check=>recordedRecipes.includes(check.qualification))?environmentReads():{};
+// A sandboxed check's run is recorded where its sandbox cannot start (execute).
+function contextHashes() {const reads=config.checks.some(check=>recordedRecipes.includes(check.qualification)||isSandboxed(check.qualification))?environmentReads():{};
   return Object.fromEntries(config.checks.map(check=>[
   check.name,Object.fromEntries([...(check.environment?.variables||[])
     .map(key=>[key,digest(process.env[key]??'<unset>')]),
@@ -95,6 +99,8 @@ function contextHashes() {const reads=config.checks.some(check=>recordedRecipes.
     ...(check.environment?.pathExecutables||[]).map(name=>[
       `__vstate_path_executable_${name}__`,pathExecutableIdentity(name)]),
     ...(check.environment?.executableIdentity?[['__vstate_node_identity__',nodeIdentity()]]:[]),
+    // A sandboxed run's environment, toolchain and places (sandbox.mjs).
+    ...(isSandboxed(check.qualification)?Object.entries(sandboxContext(check,process.env,root)):[]),
     // The variables the last test run read directly, compared here: which
     // list was compared, and the first variable whose value now differs.
     // Control requests are small, so the values stay out of them.
@@ -211,10 +217,11 @@ async function execute() {
   const lockStarted=performance.now(),runLock=acquireRunLock(state);
   timing('cli.run_lock',lockStarted);
   const captureIssues=[];
-  let activeChild=null,requestedSignal=null,treeStop=null,preserveRunLock=false;
+  let activeChild=null,requestedSignal=null,treeStop=null,preserveRunLock=false,ownGroup=false;
   const forward=signal=>{requestedSignal=signal;
     if(activeChild&&activeChild.exitCode===null){
-      if(process.platform==='linux'&&activeChild.pid){
+      // A Linux run, and a sandboxed one on macOS, has its own process group.
+      if((process.platform==='linux'||ownGroup)&&activeChild.pid){
         try{process.kill(-activeChild.pid,signal);}
         catch(e){if(e.code!=='ESRCH')throw e;}
       }else if(process.platform==='win32'&&activeChild.pid){
@@ -290,10 +297,15 @@ async function execute() {
     const recorded=directRunRecordable(selected)&&!unobservedDirectRun;
     const launched=recorded?[command[0],'--require',path.join(here,'run-recorder.cjs'),
       ...command.slice(1)]:command;
+    // A sandboxed check runs inside the OS sandbox. Where the sandbox cannot
+    // start, a script the general recipe takes is recorded as that recipe
+    // records it (`fallback`); any other runs as it is, and is not reused.
+    const sandboxed=isSandboxed(selected.qualification),support=sandboxed?sandboxSupport():null;
+    const fallback=Boolean(support?.issue&&typeof selected.script==='string'&&!generalIssue(root,selected.script));
     // A test run's processes record what the guard checks (test-recorder.cjs),
     // and so do a general recipe run's, through the package manager.
-    const general=selected.qualification===scriptQualification;
-    const testRun=recordedRecipes.includes(selected.qualification)&&['darwin','linux'].includes(process.platform);
+    const general=selected.qualification===scriptQualification||fallback;
+    const testRun=(recordedRecipes.includes(selected.qualification)||fallback)&&['darwin','linux'].includes(process.platform);
     let testRecord=null,launchEnv=process.env,testFacts={},toolchain=[];
     if(testRun){
       // The package directory and installed node_modules, as the plan has them.
@@ -313,6 +325,31 @@ async function execute() {
       // npm's and pnpm's update checks read state outside the checkout and the network.
       if(general)launchEnv.npm_config_update_notifier='false';
     }
+    // The sandboxed run, with the environment REDUE gives it.
+    let sandbox=null;
+    if(sandboxed&&!fallback){
+      if(support.issue)captureIssues.push(`the run was not sandboxed: ${support.issue}`);
+      else{
+        const dirs=sandboxDirs(state,name);
+        const reads=[root,dirs.home,dirs.tmp,...sandboxPlaces(selected,process.env,root),...systemPlaces];
+        // sandbox-v2 hides the checkout's git-ignored entries. Where git
+        // cannot list them, nothing is hidden, and the receipt compares every file.
+        const hidden=selected.qualification===hiddenQualification?hiddenEntries(root):null;
+        sandbox={mode:support.mode,dirs,reads,hidden,argv:sandboxArgv(support.mode,command,{reads,tmp:dirs.tmp,python:support.python,
+          hidden:(hidden||[]).map(rel=>path.join(root,rel.replace(/\/$/,'')))}),
+          env:sandboxEnv(selected,process.env,{root,...dirs})};
+      }
+    }
+    const plainEnv={...process.env,...selected.script?{npm_config_update_notifier:'false'}:{}};
+    // Output kept, and its own process group, for a run as this recipe makes it.
+    const own=sandboxed&&!fallback;
+    ownGroup=own&&process.platform!=='win32';
+    // A sandboxed run's output is passed through and its start and end kept,
+    // to tell a refusal by the sandbox from a real failure.
+    const output={head:'',tail:''};
+    const keep=chunk=>{const text=chunk.toString('utf8');
+      if(output.head.length<65536)output.head+=text.slice(0,65536-output.head.length);
+      output.tail=(output.tail+text).slice(-65536);};
     let runnerPid=null;
     const record=[];
     // A Windows full reconciliation may finish while queued watcher callbacks
@@ -335,11 +372,19 @@ async function execute() {
       if(requestedSignal){resolve({status:'interrupted',exitCode:null,signal:requestedSignal});return;}
       let child,spawnError=null;
       try{runLock.phase('launching');
-        const launch=windowsLaunch(launched);
+        const launch=windowsLaunch(sandbox?.argv??launched);
         child=spawn(launch.file,launch.args,{cwd:plan.cwd,
-        stdio:recorded?['inherit','inherit','inherit','pipe']:'inherit',env:launchEnv,
-        detached:process.platform==='linux',...launch.options});
-        child.stdio[3]?.on('data',chunk=>record.push(chunk));}
+        // A sandboxed run's own group gets no terminal input, which would stop it.
+        stdio:recorded?['inherit','inherit','inherit','pipe']:own?['ignore','pipe','pipe']:'inherit',
+        env:sandbox?.env??(own?plainEnv:launchEnv),
+        detached:process.platform==='linux'||ownGroup,...launch.options});
+        child.stdio[3]?.on('data',chunk=>record.push(chunk));
+        if(own){child.stdout.on('data',chunk=>{process.stdout.write(chunk);keep(chunk);});
+          child.stderr.on('data',chunk=>{process.stderr.write(chunk);keep(chunk);});
+          // What the check left running is stopped when it exits, as a CI
+          // job's end does (on Linux the launcher also stops daemons that
+          // left the group), and the run ends a second after its exit.
+          endWithChild(child);}}
       catch(e){resolve({status:'start_failed',exitCode:null,signal:null,errorCode:e.code||e.name});return;}
       activeChild=child;runnerPid=child.pid??null;runLock.phase('running',child.pid??null);
       mark('cli.child_started',{childPid:child.pid});
@@ -347,7 +392,7 @@ async function execute() {
       child.on('error',e=>{spawnError=e.code||e.name;});
       child.on('close',async(exit,signal)=>{
         if(treeStop)await treeStop;
-        if(process.platform==='linux'&&requestedSignal&&child.pid){
+        if((process.platform==='linux'||ownGroup)&&requestedSignal&&child.pid){
           // A verification command may have forked children in its process
           // group. Normal cancellation must reach them even if the leader has
           // already exited. Commands that daemonize into a new session remain
@@ -369,7 +414,7 @@ async function execute() {
     invocation.argc=command.length;
     invocation.runId=runId;
     invocation.reporting='normal';
-    const result=invocation.status==='exited'?(invocation.exitCode===0?'PASS':'FAIL'):null;
+    let result=invocation.status==='exited'?(invocation.exitCode===0?'PASS':'FAIL'):null;
     const target={source:'direct-command',status:invocation.status==='exited'?'direct_executed':'unknown'};
     const afterContextStarted=performance.now(),environmentAfter=contextHashes()[name];
     timing('cli.context_after',afterContextStarted);
@@ -411,7 +456,7 @@ async function execute() {
       // The start checkpoint's probe may have raised the deadline.
       const endWait=decisionWait(process.env.VSTATE_CAPTURE_TIMEOUT_MS);
       try{after=await call({action:'snapshot',name,contextHashes:contextHashes(),
-        ...(testRun&&Number.isSafeInteger(snap?.inputEventSerial)?{sinceSerial:snap.inputEventSerial}:{}),
+        ...((testRun||sandboxed)&&Number.isSafeInteger(snap?.inputEventSerial)?{sinceSerial:snap.inputEventSerial}:{}),
         ...(recording?{runCertificate:1,adopt:recording}:recorded&&!certificate?{runCertificate:1,runFacts:1}:{})},
         endWait.timeout,endWait.deadline);}
       catch{captureIssues.push('end observation unavailable');}
@@ -476,12 +521,79 @@ async function execute() {
     // A recorded certificate changes only the probe part of the fingerprint.
     if(!outputs&&(!snap||!end||snap.planId!==end.planId||(recording?snap.inputKey!==end.inputKey:snap.fingerprint!==end.fingerprint)||
       snap.revision!==end.revision))captureIssues.push('declared inputs changed or were not observed');
+    // A run that hid git-ignored files and failed with a refusal that names
+    // one runs again in the sandbox without hiding them: the check needs
+    // them. That run's result is kept, compared on every file, when the
+    // inputs held through it too. Its own refusal is handled as below.
+    let hiddenRerun=null;
+    if(sandbox?.hidden?.length&&result==='FAIL'&&!requestedSignal){
+      const line=hiddenRefusal(output.head+'\n'+output.tail,sandbox.hidden);
+      if(line){
+        console.error(`redue: the sandboxed run failed with what looks like a refusal of a file git ignores (${line}); running it again in the sandbox without hiding them`);
+        const again=await runToEnd(sandboxArgv(sandbox.mode,command,{reads:sandbox.reads,tmp:sandbox.dirs.tmp,python:support.python}),
+          {cwd:plan.cwd,env:sandbox.env,echo:true,started:child=>{activeChild=child;}});
+        activeChild=null;
+        hiddenRerun={line,exitCode:again.status,signal:again.signal||null,...again.error?{errorCode:again.error.code||again.error.name}:{}};
+        if(requestedSignal){
+          captureIssues.push('interrupted during the run without hidden files');
+          Object.assign(invocation,{status:'interrupted',exitCode:null,signal:requestedSignal});
+        }
+        else if(again.error||again.status===null)
+          captureIssues.push(`the run without hidden files did not finish (${again.error?.code||again.signal}), so a refusal of a file git ignores is not ruled out (${line})`);
+        else{
+          const wait=decisionWait(process.env.VSTATE_CAPTURE_TIMEOUT_MS);
+          // Inputs, plan, observer and environment held through it as through the first run.
+          let confirmed=null;const environmentNow=contextHashes()[name];
+          try{confirmed=await call({action:'snapshot',name,contextHashes:contextHashes(),
+            ...Number.isSafeInteger(snap?.inputEventSerial)?{sinceSerial:snap.inputEventSerial}:{}},wait.timeout,wait.deadline);}catch{}
+          const last=confirmed?.snapshots?.[name];
+          if(!last?.observationHealthy||!snap||last.planId!==snap.planId||last.fingerprint!==snap.fingerprint||last.revision!==snap.revision||
+            last.inputEventSerial!==end?.inputEventSerial||last.planGeneration!==snap.planGeneration||
+            confirmed.observation?.generation!==before?.observation?.generation)
+            captureIssues.push('declared inputs changed or were not observed during the run without hidden files');
+          if(JSON.stringify(environmentNow)!==JSON.stringify(environmentBefore))
+            captureIssues.push('declared environment changed during the run without hidden files');
+          invocation.hiddenExitCode=invocation.exitCode;invocation.exitCode=again.status;
+          result=again.status===0?'PASS':'FAIL';
+          output.head=`${again.stdout}\n${again.stderr}`.slice(0,65536);output.tail='';
+          sandbox.hidden=null;
+        }
+      }
+    }
+    // A sandboxed run that failed with what looks like a refusal by the
+    // sandbox runs again outside it. When that run exits differently, the
+    // sandbox changed the result: the plain run's result is kept, not reused.
+    // An interrupt before or during it stops there: the run is interrupted.
+    let sandboxRerun=null;
+    if(sandbox&&result==='FAIL'&&!requestedSignal){
+      const line=denialLine(output.head+'\n'+output.tail);
+      if(line){
+        console.error(`redue: the sandboxed run failed with what looks like a refusal by the sandbox (${line}); running it again outside the sandbox`);
+        // Interrupting REDUE interrupts the rerun's group too (forward).
+        const plain=await runToEnd(command,{cwd:plan.cwd,env:plainEnv,echo:true,started:child=>{activeChild=child;}});
+        activeChild=null;
+        sandboxRerun={line,exitCode:plain.status,signal:plain.signal||null,...plain.error?{errorCode:plain.error.code||plain.error.name}:{}};
+        if(requestedSignal){
+          captureIssues.push('interrupted during the run outside the sandbox');
+          Object.assign(invocation,{status:'interrupted',exitCode:null,signal:requestedSignal});
+        }
+        // A rerun that did not start or finish tells nothing: the sandboxed result stands, not reused.
+        else if(plain.error||plain.status===null)
+          captureIssues.push(`the run outside the sandbox did not finish (${plain.error?.code||plain.signal}), so a refusal by the sandbox is not ruled out (${line})`);
+        else if(plain.status!==invocation.exitCode){
+          captureIssues.push(`the sandbox changed the result: exit ${invocation.exitCode} inside it, ${plain.status??plain.signal} outside it (${line})`);
+          invocation.sandboxedExitCode=invocation.exitCode;invocation.exitCode=plain.status;
+        }
+      }
+    }
+    if(sandbox)fs.rmSync(sandbox.dirs.tmp,{recursive:true,force:true});
     const stable=captureIssues.length===0;
     // Two runs on the same inputs, environment and plan that disagree make the
     // check nondeterministic until its inputs change.
     let nondeterministic=false;
     const declared=hashes=>Object.entries(hashes||{}).filter(([key])=>!key.startsWith('__redue_env_'));
-    if(testRun&&stable&&result){
+    if(sandboxRerun)result=invocation.status==='exited'?(invocation.exitCode===0?'PASS':'FAIL'):null;
+    if((testRun||sandboxed)&&stable&&result){
       const prior=readReceipts(state).checks[name];
       // A difference explained by inputs REDUE did not observe proves nothing.
       nondeterministic=Boolean(!guard?.issues.length&&prior?.stable&&!prior.guardIssues?.length&&prior.result&&prior.planId===(snap?.planId??plan.id)&&
@@ -494,7 +606,9 @@ async function execute() {
     // A recorded run's receipt carries its run facts, even none; observers that
     // predate run facts do not reuse version 2.
     // The recipe that made the receipt, which status and the hook name.
-    const receipt={result,invocation,target,stable,fingerprintVersion:recorded||testRun?2:1,recipe:selected.qualification||null,
+    // A sandboxed receipt names what the run did: hid the git-ignored files or not.
+    const receipt={result,invocation,target,stable,fingerprintVersion:recorded||testRun?2:1,
+      recipe:(fallback?scriptQualification:own?(sandbox?.hidden?hiddenQualification:sandboxQualification):selected.qualification)||null,
       ...(recorded||testRun?{runFacts}:{}),
       ...(testRun?{verificationRecipe:general?scriptInterpretation:testsInterpretation,guardIssues:guard?.issues||['the run record is unavailable'],
         environmentReads:guard?.environmentReads||{},...(nondeterministic?{nondeterministic}:{})}:{}),
@@ -508,10 +622,15 @@ async function execute() {
       planId:snap?.planId??plan.id,fingerprint:(recording||outputs?end:snap)?.fingerprint??null,
       provider:plan.provider,environmentHashes:environmentBefore,
       ...(observedContext?{observedContext,verificationRecipe:directInterpretation}:{}),
+      // `hidden`: the git-ignored entries the run did not see, which the observer does not compare.
+      ...(own?{verificationRecipe:sandbox?.hidden?sandboxInterpretationOf(hiddenQualification):sandboxInterpretation,
+        sandbox:{mode:sandbox?.mode??null,hidden:sandbox?.hidden??null,...hiddenRerun?{hiddenRerun}:{},...sandboxRerun?{rerun:sandboxRerun}:{}}}:{}),
+      ...(fallback?{sandbox:{mode:null,fallback:'node-script',issue:support.issue}}:{}),
       files:(outputs?end:snap)?.files??null,observerGeneration:before?.observation?.generation??null,
       startRevision:snap?.revision??null,endRevision:end?.revision??null};
     const persistenceStarted=performance.now();
     commitReceipt(state,name,receipt);
+    note(state,{kind:'run',check:name,ms:invocation.durationMs??null,result,stable});
     if(testRun){const reads=environmentReads();reads[name]=receipt.environmentReads;atomicJson(readsFile,{schema:1,checks:reads});}
     timing('cli.receipt_persistence',persistenceStarted);
     const reloadStarted=performance.now();
@@ -601,7 +720,8 @@ async function main(){
           await new Promise(r=>setTimeout(r,100));
         if(fs.existsSync(path.join(state,'observer.lock')))throw Error('observer did not stop');}
     }
-    fs.rmSync(state,{recursive:true,force:true});
+    // A stopping observer can still be closing its files (Windows: ENOTEMPTY, EBUSY).
+    fs.rmSync(state,{recursive:true,force:true,maxRetries:10,retryDelay:200});
     console.log(JSON.stringify({removed:state}));return;
   }
   if(action==='status'){console.log(JSON.stringify(cached()));return;}

package/src/daemon.mjs

@@ -25,6 +25,7 @@ import {npmCacheDir} from './npm-integrity.mjs';
 import {runFromArgv} from './typescript-invocation.mjs';
 import {buildInfoPath,recordedCertificate} from './direct-run-certificate.mjs';
 import {timing,mark,traceBase,traceContext,traceScope,traceEnvironment,traceId} from './decision-profile.mjs';
+import {ignoredNow,isSandboxed,sandboxChange,trackedBeneath} from './sandbox.mjs';
 
 const configFile=path.resolve(process.argv[2]);
 const config=JSON.parse(fs.readFileSync(configFile));
@@ -63,7 +64,9 @@ let identityChanged=false;
 let identityGapKey=null;
 let triggerHashes=new Map();
 let candidateDescendants=new Map();
-let workspacePatterns=(()=>{const w=JSON.parse(fs.readFileSync(path.join(root,'package.json'))).workspaces;
+// A Python project may have no package.json.
+let workspacePatterns=(()=>{let w;try{w=JSON.parse(fs.readFileSync(path.join(root,'package.json'))).workspaces;}
+  catch(e){if(e.code==='ENOENT')return [];throw e;}
   return Array.isArray(w)?w:w?.packages||[];})();
 let planningWorker=null;
 let validatedPlan=null;
@@ -345,6 +348,39 @@ function describeChangedInput(plan,file) {
     .map(mapping=>mapping.logical).slice(0,2);
   return file+' changed'+(matches.length?` (installed via ${matches.join(', ')})`:'');
 }
+// A run that hid the checkout's git-ignored entries (sandbox@2) did not see
+// them. A changed file the run saw always counts. A file beneath a hidden
+// entry counts only once git tracks it, and a new file only when git does
+// not list it as ignored now, as the next run's hidden entries would not.
+// Installed trees count whatever git says. The first changed input that
+// counts, or null; once per receipt and pair of fingerprints. When git
+// cannot tell, every change counts.
+const hiddenRun=r=>Array.isArray(r?.sandbox?.hidden)&&Boolean(r.files);
+function visibleChange(row,r,name) {
+  const key=(r.invocation?.runId||'')+'\0'+r.fingerprint+'\0'+combinedSummary(name).fingerprint;
+  if(row.visibleKey===key)return row.visibleChange;
+  const hidden=r.sandbox.hidden.map(entry=>entry.replace(/\/$/,''));
+  const beneath=file=>hidden.some(entry=>file===entry||file.startsWith(entry+'/'));
+  const current=combinedFiles(name);
+  const changed=[...new Set([...Object.keys(r.files),...Object.keys(current)])].filter(file=>r.files[file]!==current[file]).sort();
+  const seen=changed.filter(file=>file in r.files&&!beneath(file));
+  const covered=changed.filter(file=>beneath(file)),fresh=changed.filter(file=>!(file in r.files)&&!beneath(file));
+  let found=seen[0]??null;
+  if(!found&&covered.length){
+    const tracked=trackedBeneath(root,hidden.filter(entry=>covered.some(file=>file===entry||file.startsWith(entry+'/'))));
+    found=covered.find(file=>!tracked||tracked.has(file))??null;
+  }
+  if(!found&&fresh.length){
+    // Ask once per directory the run had no file in, then the files outside one.
+    const before=new Set(Object.keys(r.files).flatMap(file=>file.split('/').slice(0,-1).map((_,i,parts)=>parts.slice(0,i+1).join('/'))));
+    const newDir=file=>{const parts=file.split('/');for(let i=1;i<parts.length;i++){const dir=parts.slice(0,i).join('/');if(!before.has(dir))return dir+'/';}return null;};
+    const asked=[...new Set(fresh.filter(file=>!file.startsWith('external:')).map(file=>newDir(file)??file))];
+    const ignored=ignoredNow(root,asked);
+    found=fresh.find(file=>file.startsWith('external:')||!ignored||!ignored.has(file))??null;
+  }
+  row.visibleKey=key;row.visibleChange=found;
+  return found;
+}
 function rows(contextHashes,synchronizedInstalled=false,synchronizedFilesystem=false) {
   if(!index)return [];
   return [...index.checks].map(([name,row])=>{
@@ -365,7 +401,7 @@ function rows(contextHashes,synchronizedInstalled=false,synchronizedFilesystem=f
       return item;}
     if(pendingChecks.has(name)){item.reason='filesystem change pending content inspection';return item;}
     if(r&&r.planId) item.declared_inputs_match=r.planId===row.plan.id&&
-      r.fingerprint===combinedSummary(name).fingerprint;
+      (r.fingerprint===combinedSummary(name).fingerprint||hiddenRun(r)&&visibleChange(row,r,name)===null);
     if(r&&!(r.fingerprintVersion===1||r.fingerprintVersion===2&&Array.isArray(r.runFacts))){
       item.reason='receipt uses earlier input-resolution format';return item;}
     if(row.plan.unresolved.length){
@@ -396,13 +432,19 @@ function rows(contextHashes,synchronizedInstalled=false,synchronizedFilesystem=f
     if(r.target.status==='failed'&&result!=='FAIL'){
       item.reason='target failure conflicts with outer invocation outcome';return item;}
     if(!r.stable){const issues=r.checkpoint?.issues?.length?` (${r.checkpoint.issues.join('; ')})`:'';
-      item.reason=`inputs changed during execution or observation gap${issues}`;return item;}
+      // A sandboxed run that could not start, whose result the sandbox changed, or whose rerun outside it did not finish, says so alone.
+      const sandbox=r.checkpoint?.issues?.length&&r.checkpoint.issues.every(issue=>/^the (?:sandbox changed|run was not sandboxed|run outside the sandbox)/.test(issue));
+      item.reason=sandbox?r.checkpoint.issues.join('; '):`inputs changed during execution or observation gap${issues}`;return item;}
     const names=[...(row.plan.environment.variables||[]),
       ...(row.plan.environment.prefixes||[]).map(prefix=>
         `__vstate_env_prefix_${prefix.toLowerCase()}__`),
       ...(row.plan.environment.pathExecutables||[]).map(name=>
         `__vstate_path_executable_${name}__`),
       ...(row.plan.environment.executableIdentity?['__vstate_node_identity__']:[])];
+    // A sandboxed run's variables, toolchain, PATH directories and places
+    // (sandbox.mjs): every entry either side has, and the first change named.
+    const sandboxChanged=isSandboxed(row.plan.qualification)&&contextHashes?.[name]?
+      sandboxChange(r?.environmentHashes,contextHashes[name]):null;
     if(names.length&&!contextHashes?.[name])unconfirmed??='execution environment context not supplied';
     item.freshness='STALE';
     if(r.planId!==row.plan.id){
@@ -411,6 +453,7 @@ function rows(contextHashes,synchronizedInstalled=false,synchronizedFilesystem=f
       item.reason=changed?`installed input link changed: ${changed.path}`:'input plan changed';
       if(changed)item.changed_inputs=[changed.path];
     }
+    else if(sandboxChanged)item.reason=sandboxChanged;
     else if(contextHashes?.[name]&&names.some(key=>contextHashes[name][key]!==r.environmentHashes?.[key]))
       item.reason='declared execution environment changed';
     // Every variable a test run read directly must have the same value. The
@@ -421,8 +464,10 @@ function rows(contextHashes,synchronizedInstalled=false,synchronizedFilesystem=f
         item.freshness='UNVERIFIED';item.reason='environment variables the last run read were not compared';}
       else item.reason=`environment variable ${contextHashes[name].__redue_env_changed__} differs from the last run`;
     }
-    else if(r.fingerprint!==combinedSummary(name).fingerprint) {
+    else if(r.fingerprint!==combinedSummary(name).fingerprint&&!(hiddenRun(r)&&visibleChange(row,r,name)===null)) {
       const key=r.fingerprint+'\0'+combinedSummary(name).fingerprint;
+      if(row.staleReasonKey!==key&&hiddenRun(r)){
+        row.staleInputs=[visibleChange(row,r,name)];row.staleReason=describeChangedInput(row.plan,row.staleInputs[0]);row.staleReasonKey=key;}
       if(row.staleReasonKey!==key){
         let changed=row.lastReason;row.staleInputs=[];
         const candidate=changed?.endsWith(' changed')?changed.slice(0,-8):null;
@@ -796,8 +841,8 @@ function markInputEvent(name,rel,type,replay) {
   if(!hasHistory||historyDisabled||replay){
     const serial=(inputEventSerial.get(name)||0)+1;
     inputEventSerial.set(name,serial);
-    // Kept only for recorded test and script checks; trimmed in batches.
-    if(['npm-tests-direct-v1','node-script-v1'].includes(index?.checks.get(name)?.plan.qualification)){
+    // Kept only for recorded test and script checks and sandboxed ones; trimmed in batches.
+    if(['npm-tests-direct-v1','node-script-v1'].includes(index?.checks.get(name)?.plan.qualification)||isSandboxed(index?.checks.get(name)?.plan.qualification)){
       const list=inputEventPaths.get(name)||[];list.push([serial,rel]);
       if(list.length>2*eventPathLimit)list.splice(0,list.length-eventPathLimit);inputEventPaths.set(name,list);
     }

package/src/decision-validation.mjs

@@ -17,7 +17,8 @@ export function planGuard(bundle) {
     ...bundle.workspaceManifests||[],...bundle.configurationInputs||[],
     ...Object.values(bundle.plans).flatMap(plan=>plan.resolutionTriggers||[])]);
   const patterns=bundle.workspacePatterns?.length?bundle.workspacePatterns:
-    (()=>{const pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json')));
+    (()=>{let pkg;try{pkg=JSON.parse(fs.readFileSync(path.join(root,'package.json')));}
+      catch(e){if(e.code==='ENOENT')return [];throw e;}
       return Array.isArray(pkg.workspaces)?pkg.workspaces:pkg.workspaces?.packages||[];})();
   if(patterns.length){
     const files=execFileSync('git',['ls-files','--cached','--others','--exclude-standard',

package/src/declared-plan.mjs

@@ -8,6 +8,7 @@ import {qualifyTypeScript} from './typescript-qualification.mjs';
 import {directBuildInfo} from './direct-typescript.mjs';
 import {qualifyTests,testWorkspacePatterns,testsQualification} from './test-direct.mjs';
 import {qualifyNodeScript,scriptQualification} from './node-script.mjs';
+import {isSandboxed,qualifySandbox,sandboxInstalledExclusions} from './sandbox.mjs';
 import {yarnWorkspaceTypecheckInputs} from './yarn-workspace-inputs.mjs';
 import {pnpmTypecheckInputs} from './pnpm-inputs.mjs';
 import {checkRun} from './typescript-invocation.mjs';
@@ -78,12 +79,17 @@ export function discoverDeclared(config) {
     if(selected.qualification==='npm-typescript-direct-v1')
       try{buildInfo=directBuildInfo(root,checkRun(selected));}catch{}
     const excluded=buildInfo?['!'+buildInfo]:[];
+    // A sandboxed check leaves out the .venv's links that lead out of the
+    // checkout; its qualification names them.
+    const sandboxed=isSandboxed(selected.qualification);
+    if(sandboxed)excluded.push(...sandboxInstalledExclusions(root));
     const installedStarted=performance.now();
     const installed=resolveDeclaredInstalled(root,
       [...(selected.installedInputs||[]),...(workspace?.installed||[]),...excluded],allowedRoots);
     timing('plan.installed_resolution',installedStarted,{mappings:installed.mappings.length});
     const automatic=selected.qualification===testsQualification?qualifyTests(root,selected):
       selected.qualification===scriptQualification?qualifyNodeScript(root,selected):
+      sandboxed?qualifySandbox(root,selected):
       qualifyTypeScript(root,selected,{workspace,issue:workspaceIssue});
     const sourcePatterns=[...new Set([...selected.inputs,...(workspace?.source||[]),
       ...(workspace?.generated||[]),...excluded])].sort();
@@ -97,7 +103,8 @@ export function discoverDeclared(config) {
     // A workspace test check, and a general check in a workspace, is qualified
     // against the current package list: a package manifest appearing or pnpm's
     // package list changing re-plans.
-    if(selected.qualification===testsQualification&&selected.workspace||selected.qualification===scriptQualification)try{
+    if(selected.qualification===testsQualification&&selected.workspace||selected.qualification===scriptQualification||
+      sandboxed&&typeof selected.script==='string')try{
       for(const item of testWorkspacePatterns(root,JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'))))
         workspacePatterns.add(item);
       if(fs.existsSync(path.join(root,'pnpm-workspace.yaml')))configurationInputs.add('pnpm-workspace.yaml');
@@ -136,6 +143,8 @@ export function discoverDeclared(config) {
       probes:selected.probes||[],environment:selected.environment||{},
       qualification:selected.qualification||null,
       ...(buildInfo?{buildInfo}:{}),
+      // A sandboxed run's reads are not recorded: git-ignored files are inputs too.
+      ...(sandboxed?{ignoredInputs:true}:{}),
       executionProvenance:'declared-command',
       unresolved:[...new Set(unresolved)].sort()};
     plan.resolutionCandidates=workspace?.resolutionCandidates||[];