@redue/cli 0.1.0-alpha.3 → 0.1.0-alpha.31

package/bin/redue.mjs

@@ -1,15 +1,22 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
+import {mark,traceBase,traceContext,traceEnvironment,traceId} from '../src/decision-profile.mjs';
+traceBase({...traceContext(),request:traceId(),work:'client'});
+mark('client.loaded');
+import {directCompiler,directQualification,directEnvironment,directInstalledInputs,directInterpretation} from '../src/direct-typescript.mjs';
+import {runArgv,tscRun} from '../src/typescript-invocation.mjs';
+import {testEnvironment,testRunnerAt,testsInterpretation,testsQualification} from '../src/test-direct.mjs';
+import {scriptEnvironment,scriptInterpretation,scriptKinds,scriptQualification} from '../src/node-script.mjs';
+import {docsQualification,hiddenDocsIssue,hiddenListIssue,isSandboxed,pythonTool,sandboxEnvironment,sandboxInterpretationOf,sandboxKinds,sandboxQualification} from '../src/sandbox.mjs';
 import os from 'node:os';
 import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {spawn,spawnSync} from 'node:child_process';
 import {createRequire} from 'node:module';
-import {fileURLToPath} from 'node:url';
-import {discoverNodeProject} from '../src/node-onboarding.mjs';
+import {fileURLToPath,pathToFileURL} from 'node:url';
 import {processAlive} from '../src/process-liveness.mjs';
 import {samePath,withinPath,realObservedPath} from '../src/path-identity.mjs';
-import {stateIdentity,userStateBase} from '../src/platform-state.mjs';
+import {discoverConfig,projectState,canonicalConfig} from '../src/project-location.mjs';
 import {findExecutable} from '../src/executable-lookup.mjs';
 import {readCachedStatus} from '../src/cached-state.mjs';
 import {assertOwnedStatePlacement} from '../src/owned-state.mjs';
@@ -22,27 +29,57 @@ const help=`REDUE ${version}
 Usage: redue [--config FILE] [--state-dir DIR] COMMAND [OPTIONS]
 
 Commands:
-  init [--dry-run] [--workspace NAME] [--check KIND]
-                       Discover existing scripts; optionally select one workspace/check
+  setup claude [--yes] Set up REDUE and Claude Code in this project in one step:
+                       init, agent setup claude, start, one recorded run per check
+  remove [--yes]       Undo setup: integration, observer state, and the config setup created
+  init [--dry-run] [--workspace NAME] [--check KIND] [--recipe typescript-direct|tests-direct|node-script|sandbox]
+       [--no-time-limit]
+                       Discover existing scripts; optionally select one workspace/check.
+                       --no-time-limit: trial runs have no 5-minute limit; with a config, the checks
+                       it does not run in the sandbox are tried, and those that qualify are updated
+  agent setup codex|claude [--dry-run|--apply] [--json]
+  agent doctor [codex|claude] [--json]
+  agent remove codex|claude [--dry-run|--apply] [--json]
+                       Connect project instructions; explicit setup only
   start                Start the local observer
   stop                 Stop this observer
-  status [--json|--short] Read conservative cached status
-  status --sync        Reconcile inputs and caller context before answering
+  status [--json]      Reconcile inputs and caller context, then answer (--sync is the same)
+  status --cached [--json] | --short  The last answer the observer published, without reconciling
   explain [CHECK] [--json] Explain applicability (synchronized; may cost more than a rerun)
   detail [CHECK] [--json]  Alias for explain
-  run CHECK            Execute one configured check and record its outcome
+  run CHECK [--if-due] Execute one configured check and record its outcome; with --if-due,
+                       only when its last pass does not apply to the files as they are now
+  stats [--json]       Per check: skips, time saved, recorded runs, why checks were UNVERIFIED
   remove-state         Stop and remove only this configuration's owned local state
 
 No checks run in the background. Direct commands outside redue create no receipts.`;
 
 function error(message){console.error(`redue: ${message}`);process.exit(2);}
+// Exits once queued output is written. On macOS, output to a pipe is written
+// asynchronously; exiting with it queued cuts it (at 8 KB through the pipe a
+// Node program, such as an agent's shell tool, reads).
+async function exit(code){await new Promise(resolve=>process.stdout.write('',resolve));process.exit(code);}
 const args=process.argv.slice(2);
+if(args.length===3&&args[0]==='agent'&&args[1]==='hook'&&args[2]==='claude'){
+  // Runs before config discovery: the hook must exit 0 on every failure,
+  // because Claude Code treats exit 2 as a block.
+  const {runClaudeHook}=await import('../src/claude-hook.mjs');
+  await runClaudeHook(fileURLToPath(import.meta.url));process.exit(0);
+}
 if(args.length===1&&args[0]==='--version'){console.log(version);process.exit(0);}
-if(args.includes('--help')||args.includes('-h')||!args.length){console.log(help);process.exit(0);}
-const preferredConfig=path.resolve('redue.config.json');
-const legacyConfig=path.resolve('vstate.config.json');
-let configFile=fs.existsSync(preferredConfig)||!fs.existsSync(legacyConfig)?
-  preferredConfig:legacyConfig,stateOverride=null;
+// Internal: the entry this command runs, so setup and the hook can tell
+// whether the `redue` on PATH (a link, a package manager's shim, a wrapper)
+// is this install.
+if(args.length===1&&args[0]==='--entry'){console.log(fs.realpathSync(fileURLToPath(import.meta.url)));process.exit(0);}
+if(args.includes('--help')||args.includes('-h')||!args.length){console.log(help);await exit(0);}
+if(args[0]==='setup'||args[0]==='remove'){
+  // Loaded on demand; setup works before a config exists.
+  const {setupCommand}=await import('../src/setup.mjs');
+  try{await setupCommand(args,{entry:fileURLToPath(import.meta.url)});}
+  catch(e){error(e.message);}
+  await exit(0);
+}
+let configFile=null,stateOverride=null;
 for(let i=0;i<args.length;){
   if(args[i]==='--config'||args[i]==='--state-dir'){
     const flag=args[i],value=args[i+1];if(!value)error(`${flag} requires a path`);
@@ -51,30 +88,70 @@ for(let i=0;i<args.length;){
   }else i++;
 }
 const command=args.shift();
-if(!['init','start','stop','status','detail','explain','run','remove-state'].includes(command))
+try{configFile??=command==='init'||stateOverride&&['stop','remove-state'].includes(command)?
+  path.resolve(fs.existsSync('redue.config.json')||!fs.existsSync('vstate.config.json')?'redue.config.json':'vstate.config.json'):discoverConfig();}
+catch(e){error(e.message);}
+if(fs.existsSync(path.dirname(configFile)))configFile=canonicalConfig(configFile);
+if(command==='agent'){
+  // Loaded on demand: onboarding and agent setup are not on the run/status path.
+  const {agentCommand}=await import('../src/agent-integration.mjs');
+  try{await agentCommand(args,{configFile,stateOverride,entry:fileURLToPath(import.meta.url)});}
+  catch(e){error(e.message);}
+  await exit(0);
+}
+if(!['init','start','stop','status','detail','explain','run','stats','remove-state'].includes(command))
   error(`unknown command ${command||'<none>'}; use --help`);
 const json=args.includes('--json');
-const sync=args.includes('--sync');
+// run --if-due: run the check only when its last pass does not apply now.
+const ifDue=command==='run'&&args.includes('--if-due');
+if(ifDue)args.splice(args.indexOf('--if-due'),1);
+// status syncs by default (warm, it costs well under 100 ms more than the
+// cached answer); --cached and --short read the cached answer.
+const cachedOnly=args.includes('--cached');
 const dryRun=args.includes('--dry-run');
 const short=args.includes('--short');
-let workspaceSelection=null,checkSelection=null;
+const sync=args.includes('--sync')||command==='status'&&!cachedOnly&&!short;
+let workspaceSelection=null,checkSelection=null,recipeSelection=null;
 if(command==='init')for(let i=0;i<args.length;){
-  if(args[i]==='--workspace'||args[i]==='--check'){
+  if(args[i]==='--workspace'||args[i]==='--check'||args[i]==='--recipe'){
     const flag=args[i],value=args[i+1];if(!value||value.startsWith('--'))error(`${flag} requires a name`);
-    if(flag==='--workspace')workspaceSelection=value;else checkSelection=value;
+    if(flag==='--workspace')workspaceSelection=value;else if(flag==='--recipe')recipeSelection=value;else checkSelection=value;
     args.splice(i,2);
   }else i++;
 }
 const check=['run','detail','explain'].includes(command)&&args[0]&&!args[0].startsWith('--')?args.shift():null;
 if(command==='run'&&!check)error('run requires a check name');
-if(args.some(value=>!['--json','--sync','--dry-run','--short'].includes(value)))error('unknown option; use --help');
+if(args.some(value=>!['--json','--sync','--cached','--dry-run','--short','--no-time-limit'].includes(value)))error('unknown option; use --help');
 if(sync&&!['status','detail','explain'].includes(command))error('--sync is for status or detail');
-if(short&&(command!=='status'||json||sync))error('--short is a cached status option; do not combine it with --sync or --json');
+if(cachedOnly&&(command!=='status'||args.includes('--sync')))error('--cached is a status option; do not combine it with --sync');
+if(short&&(command!=='status'||json||args.includes('--sync')))error('--short is a cached status option; do not combine it with --sync or --json');
 if(dryRun&&command!=='init')error('--dry-run is for init');
+const noTimeLimit=args.includes('--no-time-limit');
+if(noTimeLimit&&command!=='init')error('--no-time-limit is for init');
 
 if(command==='init'){
-  let discovery;try{discovery=discoverNodeProject(process.cwd());}
-  catch(e){error(e.message);}
+  const {discoverNodeProject,sourceLinkIssue}=await import('../src/node-onboarding.mjs');
+  const {discoverPythonProject}=await import('../src/python-onboarding.mjs');
+  const {sandboxTrial}=await import('../src/sandbox.mjs');
+  // A Node project, a Python project, or both in one checkout.
+  const python=!recipeSelection||recipeSelection==='sandbox'?discoverPythonProject(process.cwd()):null;
+  let discovery;
+  if(fs.existsSync('package.json')||!python)try{discovery=discoverNodeProject(process.cwd(),{recipe:recipeSelection});}
+    catch(e){error(e.message);}
+  else{const root=realObservedPath(process.cwd());
+    const git=spawnSync('git',['rev-parse','--show-toplevel'],{cwd:root,encoding:'utf8',timeout:3000,stdio:['ignore','pipe','ignore']});
+    discovery={schema:1,root,manager:{name:null,version:null,layout:null},observationIssue:git.status===0?sourceLinkIssue(root):
+      'Git checkout is unavailable; filesystem observation needs a checkout',workspaces:false,node:process.version,
+      checks:[],ambiguous:[],skipped:[],config:{schema:1,checks:[]}};}
+  if(python){
+    // A Python check takes its tool's name where the name is taken.
+    const taken=new Set(discovery.checks.map(row=>row.config.name));
+    for(const row of python.checks){if(taken.has(row.config.name))row.config.name=`${row.config.kind}:${row.config.command[0].split('/').at(-1)}`;
+      taken.add(row.config.name);}
+    if(!discovery.observationIssue)discovery.checks.push(...python.checks);
+    discovery.skipped.push(...python.skipped);
+    discovery.python=true;
+  }
   if(workspaceSelection||checkSelection){
     const chosen=discovery.checks.filter(row=>
       (!workspaceSelection||row.config.workspace===workspaceSelection||
@@ -83,7 +160,72 @@ if(command==='init'){
     if(!chosen.length)error('no discovered check matches the selected workspace and kind');
     discovery.checks=chosen;discovery.config.checks=chosen.map(row=>row.config);
   }
-  const configured=fs.existsSync(configFile),unsupported=Boolean(discovery.observationIssue||
+  // A sandboxed check is proposed only when it gives the same exit status and
+  // output inside the sandbox as outside it, with the checkout's git-ignored
+  // files and documentation hidden (sandbox-v3). When the plain run passed
+  // and the sandboxed one failed only because it was refused a file it hid
+  // (sandboxTrial's refusedHidden), the check gets the whole checkout
+  // (sandbox-v1) without another run: without the hiding it can only fail
+  // where the plain run passes. Any other difference is tried once with the
+  // whole checkout, reusing the plain run. Otherwise init writes what it
+  // would have without the sandboxed recipe, with the reason. Each check
+  // costs one plain run and one or two sandboxed runs. A run past the trial
+  // limit ends the check's trials (time_limit); --no-time-limit sets none.
+  const trialIssue=trial=>trial.issue?`the sandbox cannot run here (${trial.issue})`:
+    trial.timedOut?`it ran past init's 5-minute trial limit${trial.timedOut==='sandboxed'?' inside the sandbox':''}`+
+      ` (redue init --check ${trial.kind} --no-time-limit tries it without the limit)`:
+    // A failure both ways that shows a refusal cannot be told from a real one.
+    trial.same?null:trial.plain!==trial.sandboxed?`exit ${trial.sandboxed} inside the sandbox, ${trial.plain} outside it${trial.line?` (${trial.line})`:''}`:
+    trial.line?`it fails both ways (exit ${trial.plain}), with a sign of a refusal inside the sandbox (${trial.line})`:
+    `the output differs inside the sandbox: ${JSON.stringify(trial.output.sandboxed)} instead of ${JSON.stringify(trial.output.plain)}`;
+  // With --no-time-limit and a config, the checks the config has and does
+  // not run in the sandbox are tried, and one it lacks when --check names
+  // it. Those that qualify replace their rows (a row that runs the same
+  // script) or are added.
+  const configured=fs.existsSync(configFile);
+  let existing=null,existingText=null;
+  if(configured&&noTimeLimit){
+    try{existingText=fs.readFileSync(configFile,'utf8');existing=JSON.parse(existingText);}catch(e){error(`cannot read ${configFile}: ${e.message}`);}
+    if(!Array.isArray(existing?.checks))error(`cannot read ${configFile}: it has no checks`);
+    if((existing.root??'.')!=='.'||!samePath(realObservedPath(path.dirname(configFile)),discovery.root))
+      error('init updates only a config at the repository root, without root; run it there');
+  }
+  const timeout=noTimeLimit?0:undefined,improved=new Map();
+  let trials=0;
+  for(const [at,row] of [...discovery.checks.entries()]){
+    if(row.qualification!==sandboxQualification||row.level!=='ready')continue;
+    const old=existing?.checks.find(check=>check.name===row.config.name);
+    const sameRun=old&&old.kind===row.config.kind&&(row.config.script?old.script===row.config.script:
+      JSON.stringify(old.command)===JSON.stringify(row.config.command));
+    const notTried=!existing?null:!old?(checkSelection?null:'the config does not have it; name its kind with --check to add it'):
+      isSandboxed(old.qualification)?'the config already runs it in the sandbox':sameRun?null:'the config runs something else under that name';
+    if(notTried){discovery.checks[at]=null;discovery.skipped.push({kind:row.config.name,reason:`${row.config.name}: not tried; ${notTried}`});continue;}
+    if(!json)console.error(`Running ${row.config.name} inside and outside the sandbox to confirm it...`);
+    const docs={...await sandboxTrial(discovery.root,row.config,{hide:'docs',timeout}),kind:row.config.kind};
+    if(!docs.issue)trials++;
+    if(!docs.issue&&docs.same){
+      row.config={...row.config,qualification:docsQualification};row.qualification=docsQualification;
+      row.reason=row.reason.replace('the whole checkout is its input',"the checkout's files git doesn't ignore, except its documentation, are its input")+`; ran both ways at init, exit ${docs.plain}`;
+      improved.set(row.config.name,row.config);continue;}
+    if(!docs.issue&&!docs.timedOut&&docs.refusedHidden){
+      row.reason+=`; at init it passed, then failed reading a file that was hidden (${docs.refusedHidden}), so the whole checkout is its input, not run that way at init`;
+      improved.set(row.config.name,row.config);continue;}
+    // Without a list of the ignored files or the documentation, the whole checkout is tried on its own.
+    const trial=docs.timedOut?docs:docs.plainRun?{...await sandboxTrial(discovery.root,row.config,{plain:docs.plainRun,timeout}),kind:row.config.kind}:
+      [hiddenListIssue,hiddenDocsIssue].includes(docs.issue)?{...await sandboxTrial(discovery.root,row.config,{timeout}),kind:row.config.kind}:docs;
+    if(trial!==docs&&!trial.issue)trials++;
+    const issue=trialIssue(trial);
+    if(!issue){row.reason+=`; ran both ways at init, exit ${trial.plain}; the whole checkout is its input: `+
+      (docs.issue?docs.issue:`with the files git ignores and the documentation hidden, ${trialIssue(docs)}`);
+      improved.set(row.config.name,row.config);continue;}
+    // time_limit: the kind that --check takes to try it without the limit.
+    const limited=trial.timedOut?{timeLimit:row.config.kind}:{};
+    if(row.fallback)discovery.checks[at]={...row.fallback,...limited,reason:`Sandboxed recipe unavailable: ${issue}; ${row.fallback.reason}`};
+    else{discovery.checks[at]=null;discovery.skipped.push({kind:row.config.name,...trial.timedOut?{time_limit:row.config.kind}:{},reason:`${row.config.name}: sandboxed recipe unavailable: ${issue}`});}
+  }
+  discovery.checks=discovery.checks.filter(Boolean).map(({fallback,...row})=>row);
+  discovery.config.checks=discovery.checks.map(row=>row.config);
+  const unsupported=Boolean(discovery.observationIssue||
     discovery.manager.issue&&!['npm','yarn','pnpm'].includes(discovery.manager.name)||
     discovery.manager.name==='yarn'&&!discovery.manager.version);
   const willWrite=!dryRun&&!configured&&!unsupported&&discovery.checks.length>0;
@@ -91,26 +233,30 @@ if(command==='init'){
     package_manager:discovery.manager.name,version:discovery.manager.version,
     installation_layout:discovery.manager.layout,
     issue:discovery.observationIssue||discovery.manager.issue,workspaces:discovery.workspaces,
-    ambiguous:discovery.ambiguous,
-    checks:discovery.checks.map(({config:check,level,reason})=>({name:check.name,
+    ambiguous:discovery.ambiguous,skipped:discovery.skipped||[],
+    checks:discovery.checks.map(({config:check,level,reason,timeLimit})=>({name:check.name,
       script:check.script||null,command:check.command||null,
-      workspace:check.workspace||null,level,reason})),config:configFile,
-    written:willWrite,existing:configured};
+      workspace:check.workspace||null,level,reason,...timeLimit?{time_limit:timeLimit}:{}})),config:configFile,
+    written:willWrite,existing:configured,writable:!configured&&!unsupported&&discovery.checks.length>0};
   if(!json) {
-    console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
+    if(summary.package_manager||!discovery.python)console.log(`Node ${summary.node}; ${summary.package_manager||'unknown package manager'}`+
       `${summary.version?' '+summary.version:''}; ${summary.installation_layout} installation.`);
+    if(discovery.python)console.log('Python project; tools run from .venv.');
     if(summary.issue)console.log(`Boundary: ${summary.issue}`);
     for(const row of summary.checks){
       console.log(`  ${row.name} (${row.script||row.command?.join(' ')}) — `+
         `${{ready:'ready to qualify',recording:'recording-only',unsupported:'unsupported'}[row.level]||row.level}: ${row.reason}`);
       if(row.script&&row.command)console.log(`    Recorded invocation: ${row.command.map(value=>
-        value==='@node'?'node':value.startsWith('@typescript-bin:')?
+        value==='@node'?'node':value==='@typescript-compiler:.'?'[reviewed local TypeScript compiler implementation]':
+          value.startsWith('@test-runner:')?`[local ${value.slice('@test-runner:'.length)}]`:value.startsWith('@typescript-bin:')?
           `[installed TypeScript in ${value.slice('@typescript-bin:'.length)}]`:value).join(' ')}`);
     }
     for(const row of summary.ambiguous)
       console.log(`  ${row.kind}: ambiguous scripts (${row.scripts.join(', ')}); choose one explicitly`);
+    for(const row of summary.skipped)console.log(`  Skipped: ${row.reason}`);
     if(!summary.checks.length)console.log('No useful existing verification scripts found.');
-    console.log(configured?`Existing ${configFile} left unchanged.`:
+    console.log(existing&&improved.size?(dryRun?`Preview only; ${configFile} was not updated.`:`Updating ${[...improved.keys()].join(', ')} in ${configFile}.`):
+      configured?`Existing ${configFile} left unchanged.`:
       dryRun?`Preview only; ${configFile} was not written.`:
         willWrite?`Writing ${configFile}; inspect it before running checks.`:'No configuration will be written.');
   }
@@ -118,13 +264,31 @@ if(command==='init'){
     if(!samePath(realObservedPath(path.dirname(configFile)),discovery.root))
       error('init writes only at the repository root; use --config there or --dry-run');
     fs.writeFileSync(configFile,JSON.stringify(discovery.config,null,2)+'\n',{flag:'wx'});
-    if(!json){console.log(`Created ${configFile}. No checks were executed.`);
+    if(!json){console.log(`Created ${configFile}. ${trials?'Checks ran inside and outside the sandbox to choose their recipe; no results were recorded.':'No checks were executed.'}`);
       console.log('Ready to qualify means the supported contract will be validated; it is not verification evidence.');
       console.log(`Next: review the config, then redue start and redue run ${JSON.stringify(discovery.checks[0].config.name)}.`);
-      console.log('Use redue status first. --sync can establish applicability, but may cost more than rerunning a cheap check.');}
+      console.log('Connect your agent: redue agent setup codex (or claude). Preview with --dry-run.');
+      console.log('Then redue status says whether each result applies to the files as they are now.');}
+  } else if(existing&&improved.size&&!dryRun){
+    if(fs.readFileSync(configFile,'utf8')!==existingText)error(`${configFile} changed while the checks ran; nothing was written. Run init again`);
+    // The observer keeps the config it started with: it is restarted around the update.
+    const state=stateOverride||projectState(discovery.root,configFile);
+    let running=false;try{running=processAlive(Number(fs.readFileSync(path.join(state,'observer.lock','pid'),'utf8')));}catch{}
+    const self=action=>spawnSync(process.execPath,[process.argv[1],'--config',configFile,...stateOverride?['--state-dir',stateOverride]:[],action],
+      {stdio:['ignore','pipe','pipe'],encoding:'utf8'});
+    if(running&&self('stop').status!==0)error('the observer did not stop; nothing was written');
+    const names=new Set(existing.checks.map(check=>check.name));
+    existing.checks=[...existing.checks.map(check=>improved.get(check.name)??check),...[...improved.values()].filter(check=>!names.has(check.name))];
+    const text=JSON.stringify(existing,null,2)+'\n';
+    fs.writeFileSync(configFile,text);
+    // A config setup created is still one redue remove deletes.
+    (await import('../src/setup.mjs')).configRewritten(discovery.root,existingText,text);
+    Object.assign(summary,{written:true,updated:[...improved.keys()],observer:!running?'not running':self('start').status===0?'restarted':'not started'});
+    if(!json)console.log(`Updated ${[...improved.keys()].join(', ')} in ${configFile}.`+
+      {restarted:' Restarted the observer with it.','not started':' The observer did not start again: run redue start.','not running':''}[summary.observer]);
   } else if(unsupported&&!json)console.log(`No config written: ${summary.issue||'unsupported discovery boundary'}.`);
   if(json)console.log(JSON.stringify({...summary,proposed_config:discovery.config}));
-  process.exit(0);
+  await exit(0);
 }
 function printLifecycle(output,action,machine){
   if(machine){process.stdout.write(output);return;}
@@ -141,11 +305,12 @@ function printLifecycle(output,action,machine){
 if(stateOverride&&['stop','remove-state'].includes(command)){
   const runtime=path.join(stateOverride,'project-runtime-v1.json');
   if(!fs.existsSync(runtime)){console.log('No REDUE state exists at this path.');process.exit(0);}
+  mark('client.engine_submit');
   const result=spawnSync(process.execPath,[engine,runtime,command==='stop'?'stop':'uninstall'],
     {cwd:os.tmpdir(),stdio:['inherit','pipe','inherit'],encoding:'utf8',env:process.env});
   if(result.error)error(result.error.message);
   if(result.stdout)printLifecycle(result.stdout,command,json);
-  process.exit(result.status??2);
+  await exit(result.status??2);
 }
 let publicConfig;
 try{publicConfig=JSON.parse(fs.readFileSync(configFile,'utf8'));}
@@ -157,10 +322,7 @@ for(const key of Object.keys(publicConfig))
   if(!['schema','root','checks','packageManager'].includes(key))error(`unsupported config field ${key}`);
 if(check&&!publicConfig.checks.some(row=>row.name===check))error(`unknown check ${check}; use redue status to list configured checks`);
 const root=realObservedPath(path.resolve(path.dirname(configFile),publicConfig.root||'.'));
-const stateBase=userStateBase(process.platform,process.env,os.homedir());
-const state=stateOverride||path.join(stateBase,'vstate',
-  `vstate-${createHash('sha256').update(stateIdentity(root)+'\0'+
-    stateIdentity(configFile)).digest('hex').slice(0,16)}`);
+const state=stateOverride||projectState(root,configFile);
 if(!/^(?:vstate|redue)-/.test(path.basename(state)))
   error('--state-dir must name a dedicated redue-* directory outside the checkout (legacy vstate-* is also supported)');
 const runtimeFile=path.join(state,'project-runtime-v1.json');
@@ -169,9 +331,18 @@ function which(name){
   if(found)return found;
   error(`cannot resolve executable ${name} on PATH`);
 }
-function token(value){
+function token(value,cwd='.'){
   if(value==='@node')return process.execPath;
   if(value==='@project')return root;
+  if(value==='@typescript-compiler:.'){
+    try{return directCompiler(root,{verify:false}).entry;}catch(e){error(`direct compiler unavailable: ${e.code||e.message}`);}
+  }
+  if(value.startsWith('@test-runner:')){
+    // Qualification reports a missing runner; status and stop still work.
+    try{return testRunnerAt(root,cwd,value.slice('@test-runner:'.length)).entry;}
+    catch{return path.join(root,cwd,'node_modules',value.slice('@test-runner:'.length),'<unavailable>');}
+  }
+  if(value==='@vstate/direct-typescript-probe')return path.join(productRoot,'src','direct-typescript-probe.mjs');
   if(value.startsWith('@typescript-bin:')){
     const dir=value.slice('@typescript-bin:'.length);
     if(!dir||path.isAbsolute(dir)||dir.split('/').includes('..'))
@@ -192,10 +363,10 @@ function token(value){
   if(value.startsWith('@which:'))return which(value.slice(7));
   return value;
 }
-function argv(values,label){
+function argv(values,label,cwd){
   if(!Array.isArray(values)||!values.length||values.some(v=>typeof v!=='string'||!v))
     error(`${label} must be nonempty exact argv`);
-  return values.map(token);
+  return values.map(value=>token(value,cwd));
 }
 const categories=['source','generated','installedDependencies','environment','toolchain','runtime',
   'probeContinuity'];
@@ -208,8 +379,12 @@ const checks=publicConfig.checks.map(check=>{
   for(const category of categories)if(check.coverage?.[category]&&
     typeof check.coverageReview?.[category]!=='string')
     error(`${check.name}: reviewed coverage ${category} needs a rationale`);
+  const npmDirect=check.qualification===directQualification;
   const pnpmTypecheck=check.qualification==='pnpm-tsc-v1';
-  if(check.script&&check.command&&!pnpmTypecheck)
+  const testsDirect=check.qualification===testsQualification;
+  const generalScript=check.qualification===scriptQualification;
+  const sandboxed=isSandboxed(check.qualification);
+  if(check.script&&check.command&&!pnpmTypecheck&&!npmDirect&&!testsDirect)
     error(`${check.name}: choose script or command, not both`);
   const manager=publicConfig.packageManager;
   if(check.script&&!['npm','yarn','pnpm'].includes(manager))
@@ -218,8 +393,24 @@ const checks=publicConfig.checks.map(check=>{
     [`@which:${manager}`,'run',check.script]:null;
   const npmAutomatic=check.qualification==='typescript-noemit-v1';
   const yarnWorkspace=check.qualification==='yarn-workspace-tsc-v1';
-  if(check.qualification&&!npmAutomatic&&!yarnWorkspace&&!pnpmTypecheck)
+  if(check.qualification&&!npmAutomatic&&!npmDirect&&!yarnWorkspace&&!pnpmTypecheck&&!testsDirect&&!generalScript&&!sandboxed)
     error(`${check.name}: unknown qualification contract`);
+  // The general recipe runs the root package script through the package manager.
+  if(generalScript&&(!['npm','pnpm','yarn'].includes(manager)||!check.script||check.command||check.cwd&&check.cwd!=='.'||
+    check.workspace||!scriptKinds.includes(check.kind)))
+    error(`${check.name}: the general recipe needs a root typecheck, test or lint script, without command or cwd`);
+  // The sandboxed recipe runs a root package script, or a tool from the project's .venv.
+  if(sandboxed&&(check.cwd&&check.cwd!=='.'||check.workspace||!sandboxKinds.includes(check.kind)||
+    (check.script?!['npm','pnpm','yarn'].includes(manager):!pythonTool(check))))
+    error(`${check.name}: the sandboxed recipe needs a root ${sandboxKinds.join(' or ')} script, or a command that runs a tool from .venv/bin, without cwd`);
+  if(npmDirect&&(manager!=='npm'||check.cwd&&check.cwd!=='.'||!Array.isArray(check.command)||
+    check.command[0]!=='@node'||check.command[1]!=='@typescript-compiler:.'||
+    !tscRun({},{script:null,args:check.command.slice(2)}).run?.noEmit))
+    error(`${check.name}: direct recipe requires its explicit local compiler command`);
+  // The script's own arguments follow the runner; qualification compares them with the script.
+  if(testsDirect&&(!['npm','pnpm','yarn'].includes(manager)||!check.script||check.cwd&&check.cwd!=='.'&&!check.workspace||!Array.isArray(check.command)||
+    check.command[0]!=='@node'||!/^@test-runner:(?:vitest|jest)$/.test(check.command[1]||'')))
+    error(`${check.name}: test recipe requires its explicit local test runner command`);
   if(npmAutomatic&&(manager!=='npm'||check.cwd&&check.cwd!=='.'))
     error(`${check.name}: automatic TypeScript qualification currently needs root npm script`);
   if(yarnWorkspace&&(manager!=='yarn'||!check.workspace||check.cwd&&check.cwd!=='.'||
@@ -227,25 +418,33 @@ const checks=publicConfig.checks.map(check=>{
     check.command[1]!=='workspace'||check.command[2]!==check.workspace||
     check.command[3]!=='run'))
     error(`${check.name}: Yarn workspace qualification needs its discovered workspace command`);
-  if(pnpmTypecheck&&(manager!=='pnpm'||!check.script||!check.command||
+  if(pnpmTypecheck&&(manager!=='pnpm'||!Array.isArray(check.command)||
     check.command[0]!=='@node'||
     check.command[1]!==`@typescript-bin:${check.cwd||'.'}`||
     check.workspace&&check.cwd==='.'||
-    !check.command.slice(2).every(value=>typeof value==='string'&&value)))
+    !tscRun({},{script:null,args:check.command.slice(2)}).run))
     error(`${check.name}: pnpm qualification needs its discovered standalone TypeScript command`);
   const reason=check.kind==='test'?'test runtime, transforms and cache inputs need review':
     check.kind==='lint'?'lint plugins, config and resolver inputs need review':
     check.kind==='build'?'build environment and generated inputs need review':
     'check inputs need review';
-  const autoProbes=npmAutomatic?[['@node','@vstate/typescript-contract-probe',
+  // A chained script has one check per tsc run: each check's run counts them,
+  // so a run added to or removed from the script invalidates them all.
+  const runCount=(npmDirect||pnpmTypecheck)&&check.script?publicConfig.checks.filter(other=>
+    other.qualification===check.qualification&&other.script===check.script&&
+    (other.cwd||'.')===(check.cwd||'.')&&(other.workspace||null)===(check.workspace||null)).length:1;
+  if(runCount>16)error(`${check.name}: more than 16 checks for script ${check.script}`);
+  const run=npmDirect||pnpmTypecheck?runArgv({script:check.script??null,args:check.command.slice(2),count:runCount}):null;
+  const autoProbes=npmDirect?[['@node','@vstate/direct-typescript-probe','@project',...run]]:npmAutomatic?[['@node','@vstate/typescript-contract-probe',
     '@project',check.script,'@which:npm']]:yarnWorkspace?
     [['@node','@vstate/yarn-workspace-typecheck-probe','@project',
       check.workspace,check.command[4],'@which:yarn']]:pnpmTypecheck?
     [['@node','@vstate/pnpm-typecheck-probe','@project',
-      check.workspace||'.',check.script]]:[];
+      check.workspace||'.',...run]]:[];
   const windowsContext=process.platform==='win32'?
     ['ComSpec','COMSPEC','PATHEXT','USERPROFILE']:[];
-  const autoEnvironment=npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
+  const autoEnvironment=npmDirect?directEnvironment:testsDirect?testEnvironment:generalScript?scriptEnvironment(manager):
+    sandboxed?sandboxEnvironment(Boolean(pythonTool(check)),check.script?manager:null,check.kind):npmAutomatic?{variables:['NODE_OPTIONS','NODE_PATH','CI','HOME',
     'NODE_ENV','BASH_ENV','ENV',...windowsContext],prefixes:['npm_config_','DYLD_','TSGO_'],
     pathExecutables:['node','npm'],executableIdentity:true}:yarnWorkspace?
     {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
@@ -254,10 +453,11 @@ const checks=publicConfig.checks.map(check=>{
     {variables:['NODE_OPTIONS','NODE_PATH','CI','HOME','NODE_ENV','BASH_ENV','ENV',...windowsContext],
       prefixes:['PNPM_','COREPACK_','npm_config_','DYLD_','TSGO_'],
       pathExecutables:['node'],executableIdentity:true}:{};
-  return {name:check.name,command:argv(scriptCommand||check.command,`${check.name}.command`),
+  return {name:check.name,command:argv(scriptCommand||check.command,`${check.name}.command`,
+    typeof check.cwd==='string'&&check.cwd&&!path.isAbsolute(check.cwd)&&!check.cwd.split('/').includes('..')?check.cwd:'.'),
     cwd:check.cwd,inputs:check.inputs||[],generatedInputs:check.generatedInputs||[],
     installedInputs:check.installedInputs||(
-      npmAutomatic?['node_modules/**']:[]),
+      npmDirect?[...directInstalledInputs]:npmAutomatic||testsDirect?['node_modules/**']:[]),
     allowedExternalRoots:check.allowedExternalRoots||[],
     probes:[...(check.probes||[]),...autoProbes]
       .map((p,i)=>argv(p,`${check.name}.probes[${i}]`)),
@@ -266,18 +466,36 @@ const checks=publicConfig.checks.map(check=>{
     coverageReasons:check.coverageReasons||Object.fromEntries(
       categories.map(category=>[category,reason])),
     qualification:check.qualification||null,script:check.script||null,
+    ...(runCount>1?{runCount}:{}),
+    ...(npmAutomatic?{qualificationInterpretation:'npm-launcher-withheld@1'}:{}),
+    ...(npmDirect?{qualificationInterpretation:directInterpretation}:{}),
+    ...(testsDirect?{qualificationInterpretation:testsInterpretation}:{}),
+    ...(generalScript?{qualificationInterpretation:scriptInterpretation}:{}),
+    ...(sandboxed?{qualificationInterpretation:sandboxInterpretationOf(check.qualification,check.kind)}:{}),
     workspace:check.workspace||null,kind:check.kind||null};
 });
 const runtime={schema:1,provider:'declared-project@1',root,state,checks};
 try{assertOwnedStatePlacement(runtime);}catch(e){error(e.message);}
 const serialized=JSON.stringify(runtime,null,2)+'\n';
+if(command==='stats'){
+  const {readStats,renderStats}=await import('../src/stats.mjs');
+  const value=readStats(state,publicConfig.checks.map(item=>item.name));
+  console.log(json?JSON.stringify(value):renderStats(value));
+  await exit(0);
+}
 const maintenance=command==='stop'||command==='remove-state';
 if(maintenance&&!fs.existsSync(runtimeFile)){
   console.log(`No REDUE state exists for ${configFile}.`);
   process.exit(0);
 }
 if(!maintenance)fs.mkdirSync(state,{recursive:true,mode:0o700});
-if(!maintenance&&fs.existsSync(runtimeFile)){
+// Two commands can meet on fresh state (SessionStart's start and the first
+// status): whichever creates the runtime file first wins, and the other
+// treats it as existing.
+let created=false;
+if(!maintenance&&!fs.existsSync(runtimeFile))
+  try{fs.writeFileSync(runtimeFile,serialized,{flag:'wx',mode:0o600});created=true;}catch(e){if(e.code!=='EEXIST')throw e;}
+if(!maintenance&&!created){
   const previous=fs.readFileSync(runtimeFile,'utf8');
   if(previous!==serialized){
     const pidFile=path.join(state,'observer.lock','pid');
@@ -287,18 +505,41 @@ if(!maintenance&&fs.existsSync(runtimeFile)){
     }
     fs.writeFileSync(runtimeFile,serialized,{mode:0o600});
   }
-}else if(!maintenance)fs.writeFileSync(runtimeFile,serialized,{flag:'wx',mode:0o600});
+}
 
 if(command==='status'&&!sync){
   const value=readCachedStatus(state,publicConfig.checks);
   console.log(json?JSON.stringify(value):renderStatus(value,{short}));
-  process.exit(0);
+  await exit(0);
 }
 
 const details=command==='detail'||command==='explain';
 const internal=command==='remove-state'?'uninstall':
   details?'sync':command==='status'&&sync?'sync':command;
-if(command==='run'){
+// On macOS and Linux the engine runs in this process, which saves a Node startup
+// on every run; its own handlers receive SIGINT and SIGTERM. Windows keeps a
+// child engine because cancellation reaches it over IPC.
+// Asked when this part of a command runs, after earlier parts may have
+// changed files. REDUE_FORCE=1 runs it anyway.
+if(ifDue&&process.env.REDUE_FORCE!=='1'){
+  const [{verdict},{note,skipNote,dueNote}]=await Promise.all([import('../src/claude-hook.mjs'),import('../src/stats.mjs')]);
+  const asked=spawnSync(process.execPath,[fileURLToPath(import.meta.url),'--config',configFile,...(stateOverride?['--state-dir',stateOverride]:[]),
+    'status','--sync','--json'],{encoding:'utf8',stdio:['ignore','pipe','ignore'],env:process.env,timeout:600_000});
+  let status=null;try{status=JSON.parse(asked.stdout);}catch{}
+  const due=dueNote(status,check);
+  if(due)note(state,due);
+  if(verdict(status,check)){
+    note(state,skipNote(status,check,'if-due'));
+    const row=status.checks.find(item=>item.name===check);
+    if(json)console.log(JSON.stringify({check,skipped:true,result:'PASS',run_id:row.invocation.runId}));
+    else console.error(`REDUE: ${check} passed on these exact inputs (run ${row.invocation.runId}); not run again. REDUE_FORCE=1 runs it anyway.`);
+    await exit(0);
+  }
+}
+if(command==='run'&&process.platform!=='win32'){
+  process.argv=[process.argv[0],engine,runtimeFile,internal,check,...(!json?['--human']:[])];
+  await import(pathToFileURL(engine).href);
+}else if(command==='run'){
   const child=spawn(process.execPath,[engine,runtimeFile,internal,check,...(!json?['--human']:[])],
     {stdio:['inherit','inherit','inherit','ipc'],env:process.env});
   const forward=signal=>{if(child.exitCode!==null)return;
@@ -313,17 +554,32 @@ if(command==='run'){
   process.off('SIGINT',interrupt);process.off('SIGTERM',terminate);
   if(outcome.error)error(outcome.error.message);
   process.exit(outcome.status??(outcome.signal?128+os.constants.signals[outcome.signal]:1));
+}else if(internal==='sync'&&process.platform!=='win32'){
+  // As for run, the synchronized status engine runs in this process.
+  process.argv=[process.argv[0],engine,runtimeFile,internal,'','--value'];
+  mark('client.engine_submit',{inProcess:true});
+  const synchronized=await import(pathToFileURL(engine).href);
+  await synchronized.finished;
+  mark('client.engine_complete',{exit:process.exitCode??0});
+  if(synchronized.syncValue)showSynchronized(synchronized.syncValue);
+  await exit(process.exitCode??0);
+}else{
+  mark('client.engine_submit');
+  const result=spawnSync(process.execPath,[engine,runtimeFile,internal,...(check?[check]:[])],
+    {stdio:['inherit','pipe','inherit'],
+      encoding:'utf8',env:traceEnvironment()});
+  mark('client.engine_complete',{exit:result.status,signal:result.signal});
+  if(result.error)error(result.error.message);
+  if(result.stdout){
+    if(['status','detail','explain'].includes(command)){
+      let value;try{value=JSON.parse(result.stdout);}catch{error('status response could not be read; applicability is unknown');}
+      showSynchronized(value);
+    }else printLifecycle(result.stdout,command,json);
+  }
+  await exit(result.status??1);
 }
-const result=spawnSync(process.execPath,[engine,runtimeFile,internal,...(check?[check]:[])],
-  {stdio:['inherit','pipe','inherit'],
-    encoding:'utf8',env:process.env});
-if(result.error)error(result.error.message);
-if(result.stdout){
-  if(['status','detail','explain'].includes(command)){
-    let value;try{value=JSON.parse(result.stdout);}catch{error('status response could not be read; applicability is unknown');}
-    if(details&&check)value={...value,checks:value.checks.filter(row=>row.name===check)};
-    if(json)console.log(JSON.stringify(value));
-    else console.log(details?renderExplain(value,check):renderStatus(value,{short}));
-  }else printLifecycle(result.stdout,command,json);
+function showSynchronized(value){
+  if(details&&check)value={...value,checks:value.checks.filter(row=>row.name===check)};
+  if(json)console.log(JSON.stringify(value));
+  else console.log(details?renderExplain(value,check):renderStatus(value,{short}));
 }
-process.exit(result.status??1);

package/docs/README.md

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