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

package/src/claude-hook.mjs

@@ -22,10 +22,41 @@ 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.
+const sandboxed=check=>check?.qualification==='sandbox-v1'&&['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 +172,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 +290,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 +368,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 +376,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;
 }
 
@@ -488,7 +526,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;
@@ -530,7 +568,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,runToEnd,sandboxArgv,sandboxContext,sandboxDirs,sandboxEnv,sandboxInterpretation,sandboxPlaces,
+  sandboxQualification,sandboxSupport,systemPlaces} from './sandbox.mjs';
 import path from 'node:path';
 import net from 'node:net';
 import os from 'node:os';
@@ -55,7 +57,17 @@ function publishedProbeDeadline() {
   try{return publishedDeadline(JSON.parse(fs.readFileSync(path.join(state,'status.json'),'utf8')).probe_deadline_ms);}
   catch{return 0;}
 }
-const decisionDeadline=()=>Math.max(decisionBaseMs,publishedProbeDeadline()+10000);
+// The wait for a decision, read when it starts: the base at once, and the
+// published deadline when status.json has been read. That file is rewritten
+// at every decision, and a first read of a fresh file is slow where a scanner
+// checks files as they are opened, so it is read off the main thread while
+// the call runs. On Windows it is read before the call, as before: the
+// observer replaces it during the call, and a replacement fails there while a
+// reader holds the file open. An override is exact.
+const decisionWait=override=>override?{timeout:Number(override),deadline:null}:
+  process.platform==='win32'?{timeout:Math.max(decisionBaseMs,publishedProbeDeadline()+10000),deadline:null}:{timeout:decisionBaseMs,
+  deadline:fs.promises.readFile(path.join(state,'status.json'),'utf8')
+    .then(text=>Math.max(decisionBaseMs,publishedDeadline(JSON.parse(text).probe_deadline_ms)+10000),()=>decisionBaseMs)};
 const digest=value=>createHash('sha256').update(value).digest('hex');
 function nodeIdentity() {const real=fs.realpathSync(process.execPath),st=fs.statSync(real,{bigint:true});
   return digest(JSON.stringify([real,process.version,...['dev','ino','mode','size','mtimeNs','ctimeNs']
@@ -73,7 +85,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,sandboxQualification].includes(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>')]),
@@ -85,6 +98,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).
+    ...(check.qualification===sandboxQualification?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.
@@ -120,20 +135,26 @@ function owner(){
     atomicJson(ownerFile,expected);
   }
 }
-function call(message,timeout=5000) {
+// deadline, when given, resolves to the whole wait in ms, which replaces
+// timeout when it is longer.
+function call(message,timeout=5000,deadline=null) {
   return new Promise((resolve,reject)=>{
     let data='',done=false;mark('client.control_connect',{deadlineMs:timeout});const client=net.createConnection(socket);
-    const timer=setTimeout(()=>{mark('client.control_timeout');client.destroy();reject(Error('observer synchronization timeout'));},timeout);
+    const started=Date.now(),expire=()=>{mark('client.control_timeout');client.destroy();reject(Error('observer synchronization timeout'));};
+    let timer=setTimeout(expire,timeout);
+    deadline?.then(total=>{if(done||total<=timeout)return;mark('client.control_deadline',{deadlineMs:total});
+      clearTimeout(timer);timer=setTimeout(expire,Math.max(0,total-(Date.now()-started)));});
     client.on('connect',()=>{mark('client.control_submit');client.write(JSON.stringify({...message,...(profiling?{diagnostic:traceContext()}: {})})+'\n');});
     client.on('data',chunk=>data+=chunk);
     client.on('end',()=>{mark('client.control_complete',{bytes:data.length});clearTimeout(timer);if(done)return;done=true;
       try{resolve(JSON.parse(data));}catch(e){reject(e);}});
-    client.on('error',e=>{mark('client.control_error',{code:e.code});clearTimeout(timer);reject(e);});
+    client.on('error',e=>{mark('client.control_error',{code:e.code});clearTimeout(timer);done=true;reject(e);});
   });
 }
-async function decisionCall(message,timeout) {
-  const started=Date.now(),remaining=()=>Math.max(1,timeout-(Date.now()-started));
-  try{return await call(message,remaining());}
+async function decisionCall(message,{timeout,deadline}) {
+  let total=timeout;deadline?.then(value=>{total=Math.max(total,value);});
+  const started=Date.now(),remaining=()=>Math.max(1,total-(Date.now()-started));
+  try{return await call(message,timeout,deadline);}
   catch(error){
     if(process.platform!=='win32'||!['ENOENT','ECONNREFUSED','ECONNRESET'].includes(error.code))throw error;
     const pidFile=path.join(state,'observer.lock','pid');
@@ -195,10 +216,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){
@@ -233,8 +255,7 @@ async function execute() {
     const environmentBefore=contextHashes()[name];
     const observedContext=selected.qualification===directQualification?{interpretation:directInterpretation,npmProxyDigest:observedNpmContext()}:null;
     timing('cli.context_before',contextStarted);
-    const
-      captureTimeout=Number(process.env.VSTATE_CAPTURE_TIMEOUT_MS||decisionDeadline());
+    const captureWait=decisionWait(process.env.VSTATE_CAPTURE_TIMEOUT_MS);
     let before=null,after=null;
     // Expensive state probes can take seconds. Keep the filesystem checkpoint
     // adjacent to process launch so a late notification from earlier work
@@ -244,7 +265,7 @@ async function execute() {
     let probeBefore=callerCertificate?null:probeHash(probePlan);
     const startSnapshotStarted=performance.now();
     try{before=await call({action:'snapshot',name,contextHashes:contextHashes(),
-      ...(callerCertificate?{runCertificate:1}:{})},captureTimeout);}
+      ...(callerCertificate?{runCertificate:1}:{})},captureWait.timeout,captureWait.deadline);}
     catch(error){captureIssues.push('start observation unavailable'+
       (typeof error.code==='string'&&/^[A-Z0-9_]+$/.test(error.code)?` (${error.code})`:''));}
     timing('cli.start_checkpoint',startSnapshotStarted,{available:before?.snapshots?.[name]?1:0});
@@ -275,10 +296,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=selected.qualification===sandboxQualification,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.
@@ -298,6 +324,27 @@ 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={mode:support.mode,dirs,argv:sandboxArgv(support.mode,command,{reads,tmp:dirs.tmp,python:support.python}),
+          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
@@ -307,7 +354,7 @@ async function execute() {
       await new Promise(resolve=>setTimeout(resolve,100));
       const prelaunchStarted=performance.now();
       try{before=await call({action:'prelaunch',name,
-        contextHashes:contextHashes()},Math.min(captureTimeout,5000));}
+        contextHashes:contextHashes()},Math.min(captureWait.timeout,5000));}
       catch{before=null;captureIssues.push('prelaunch observation unavailable');}
       timing('cli.prelaunch_checkpoint',prelaunchStarted,
         {available:before?.snapshots?.[name]?1:0});
@@ -320,11 +367,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});
@@ -332,7 +387,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
@@ -354,7 +409,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);
@@ -393,11 +448,12 @@ async function execute() {
     if(recordFile)try{fs.writeFileSync(recordFile,recordText,{mode:0o600});}catch{}
     const endSnapshotStarted=performance.now();
     if(!unobservedDirectRun){
+      // 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}:{})},
-        // The start checkpoint's probe may have raised the deadline.
-        Number(process.env.VSTATE_CAPTURE_TIMEOUT_MS||decisionDeadline()));}
+        endWait.timeout,endWait.deadline);}
       catch{captureIssues.push('end observation unavailable');}
       finally{if(recordFile)fs.rmSync(recordFile,{force:true});}
       timing('cli.end_checkpoint',endSnapshotStarted,{available:after?.snapshots?.[name]?1:0});
@@ -460,12 +516,40 @@ 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 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)&&
@@ -478,7 +562,7 @@ 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,
+    const receipt={result,invocation,target,stable,fingerprintVersion:recorded||testRun?2:1,recipe:(fallback?scriptQualification:selected.qualification)||null,
       ...(recorded||testRun?{runFacts}:{}),
       ...(testRun?{verificationRecipe:general?scriptInterpretation:testsInterpretation,guardIssues:guard?.issues||['the run record is unavailable'],
         environmentReads:guard?.environmentReads||{},...(nondeterministic?{nondeterministic}:{})}:{}),
@@ -492,6 +576,8 @@ async function execute() {
       planId:snap?.planId??plan.id,fingerprint:(recording||outputs?end:snap)?.fingerprint??null,
       provider:plan.provider,environmentHashes:environmentBefore,
       ...(observedContext?{observedContext,verificationRecipe:directInterpretation}:{}),
+      ...(own?{verificationRecipe:sandboxInterpretation,sandbox:{mode:sandbox?.mode??null,...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();
@@ -601,7 +687,7 @@ async function main(){
         observedNpmDigest:observedNpmContext(),proxyShapes});
     }
     let value;try{value=await decisionCall({action:'sync',contextHashes:contextHashes()},
-      Number(process.env.VSTATE_SYNC_TIMEOUT_MS||decisionDeadline()));
+      decisionWait(process.env.VSTATE_SYNC_TIMEOUT_MS));
       // A client upgrade can encounter an older running observer. Its successful
       // control response does not establish that it evaluated the latest receipt.
       if(value.receipt_revision===null){
@@ -615,7 +701,9 @@ async function main(){
       }}
     catch(e){value=unavailableCached(state,e.message,config.checks);process.exitCode=2;}
     timing('cli.synchronized_status',started,{available:value.observation?.healthy?1:0});
-    if(action==='sync')console.log(JSON.stringify(value));
+    // In the front's process (bin/redue.mjs), the value is handed back.
+    if(action==='sync'&&process.argv.includes('--value'))syncValue=value;
+    else if(action==='sync')console.log(JSON.stringify(value));
     else for(const row of value.checks)console.log(`${row.name}: ${row.freshness}/${row.result||'NO RESULT'} — ${row.reason}`);
     return;
   }
@@ -623,4 +711,5 @@ async function main(){
   if(action==='run'){await execute();return;}
   throw Error(`unknown action ${action}`);
 }
-main().catch(e=>{console.error(`redue: ${e.message}`);process.exitCode=2;});
+export let syncValue=null;
+export const finished=main().catch(e=>{console.error(`redue: ${e.message}`);process.exitCode=2;});

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 {sandboxChange} 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;
@@ -269,6 +272,7 @@ function probe(row,allowReuse=false,{launch=true}={}) {
         'typescript-plugin-unsupported':'TypeScript compiler plugin needs explicit review',
         'typescript-input-list-unavailable':'TypeScript input listing did not complete',
         'typescript-input-outside-repository':'TypeScript consumes files outside the observed repository',
+        'typescript-vite-cache-consumed':'TypeScript asks about node_modules/.vite or lists node_modules; Vitest rewrites files there and this recipe does not observe them',
         'npm-installation-layout-unsupported':'npm executable or installation layout is unsupported',
         'npm-installation-unobservable':'npm installation contains unobservable entries',
         'npm-configuration-unsupported':'npm script configuration needs review',
@@ -395,13 +399,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=row.plan.qualification==='sandbox-v1'&&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){
@@ -410,6 +420,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
@@ -795,8 +806,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','sandbox-v1'].includes(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 {qualifySandbox,sandboxInstalledExclusions,sandboxQualification} 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=selected.qualification===sandboxQualification;
+    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||[];

package/src/direct-run-certificate.mjs

@@ -7,7 +7,7 @@ import {createHash} from 'node:crypto';
 import {inflateSync} from 'node:zlib';
 import {fileURLToPath} from 'node:url';
 import {timing} from './decision-profile.mjs';
-import {directCompiler,directContextHash,directEnvironmentIssue,directProbeOutput,directProbeValue} from './direct-typescript.mjs';
+import {directCompiler,directContextHash,directEnvironmentIssue,directProbeOutput,directProbeValue,viteCacheQuestion} from './direct-typescript.mjs';
 import {withinPath} from './path-identity.mjs';
 const hash=value=>createHash('sha256').update(value).digest('hex');
 // Whether a direct run is recorded at all: on macOS and Linux, always, so its
@@ -158,6 +158,8 @@ export function runRecordIssue(record,certificate,runFacts=null) {
   if(kept.issue)return kept.issue;
   if(record.main!==compiler.entry||!Array.isArray(record.node)||
     directContextHash(compiler,record.node)!==certificate.context)return 'execution context changed';
+  const vite=viteCacheQuestion(compiler.root,kept.facts);
+  if(vite)return `the compiler asked about ${vite}, which Vitest rewrites and REDUE does not observe`;
   const inCompiler=withinCompiler(compiler);
   const facts=new Map();
   for(const query of queries){if(!facts.has(query[1]))facts.set(query[1],[]);facts.get(query[1]).push(query);}

package/src/direct-typescript-probe.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import {directProject,directInterpretation,directContextHash,directProbeOutput} from './direct-typescript.mjs';
+import {directProject,directInterpretation,directContextHash,directProbeOutput,viteCacheQuestion} from './direct-typescript.mjs';
 import {typeScriptInputFacts} from './typescript-input-facts.mjs';
 import {contextOnly,probeResult} from './probe-result.mjs';
 import {realObservedPath} from './path-identity.mjs';
@@ -18,6 +18,9 @@ try{
   const contextHash=directContextHash(compiler,context.node);
   if(!contextOnly(contextHash)){
     const {queries,configs,files,buildInfo}=typeScriptInputFacts(root,compiler.tsRoot,compiler.entry,compiler.config);
+    // Captured questions include every config and program file read.
+    if(viteCacheQuestion(root,queries||[...configs,...files].map(([file])=>['readFile',file])))
+      throw Object.assign(Error('typescript-vite-cache-consumed'),{code:'typescript-vite-cache-consumed'});
     const layout={root,script,configs,files,context,...(buildInfo?{buildInfo}:{})};
     probeResult(directProbeOutput(layout),contextHash,queries,layout);
   }