@redue/cli 0.1.0-alpha.21 → 0.1.0-alpha.23

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.23",
   "publishConfig": {
     "access": "public",
     "tag": "alpha"

package/src/agent-integration.mjs

@@ -11,7 +11,7 @@ import {readProject,projectState,canonicalConfig} from './project-location.mjs';
 import {readCachedStatus} from './cached-state.mjs';
 import {samePath,withinPath} from './path-identity.mjs';
 import {processAlive} from './process-liveness.mjs';
-import {fanoutRules,hookCommand,hookForms,redueFor} from './claude-hook.mjs';
+import {fanoutRules,hookCommand,hookForms,redueFor,runsEntry,shellQuote as quote} from './claude-hook.mjs';
 
 const policy=fs.readFileSync(new URL('./agent-policy.md',import.meta.url),'utf8');
 const hosts={codex:{instruction:'AGENTS.md',skill:'.agents/skills/redue-verification/SKILL.md'},
@@ -25,17 +25,53 @@ const sameJson=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
 // The hook waits for status up to 10 s; 15 s leaves room for starting Node.
 // Fan-out commands (turbo, nx, `pnpm -r`) and root scripts that run one get
 // prefix rules; the hook decides from the full command.
-function hookFor(config,relative,scripts){
+function hookFor(config,relative,scripts,command=hookCommand){
   const rules=[...new Set([...hookForms(config,relative,scripts).flatMap(row=>[...row.forms,...row.local]),
     ...fanoutRules(config,scripts)])].map(form=>`Bash(${form}*)`);
-  return rules.length?{matcher:'Bash',hooks:rules.map(rule=>({type:'command',if:rule,command:hookCommand,timeout:15}))}:null;
+  return rules.length?{matcher:'Bash',hooks:rules.map(rule=>({type:'command',if:rule,command,timeout:15}))}:null;
 }
 // The same command on SessionStart starts the observer; it needs no check to match.
-const sessionHook={hooks:[{type:'command',command:hookCommand,timeout:10}]};
+const sessionHookFor=(command=hookCommand)=>({hooks:[{type:'command',command,timeout:10}]});
 const events=['PreToolUse','SessionStart'];
+// The absolute form: Node and REDUE's entry (redue.mjs), each quoted as quote()
+// writes it. [node, entry] or null.
+function absoluteHook(command){
+  const word="'((?:[^']|'\\\\'')*)'";
+  const match=new RegExp(`^${word} ${word} agent hook claude$`).exec(command??'');
+  if(!match)return null;
+  const [node,entry]=[match[1],match[2]].map(value=>value.replaceAll("'\\''","'"));
+  // REDUE's entry file, or the bin link npm installs for it.
+  return /^redue(\.mjs)?$/.test(path.basename(entry))?[node,entry]:null;
+}
+export const isHookCommand=command=>command===hookCommand||Boolean(absoluteHook(command));
+// The command Claude Code runs for the hook. Plain `redue` when this install
+// is the one both this shell and a login shell find on PATH. Otherwise this
+// install's Node and entry by absolute path, so a Claude Code started from
+// another shell, an IDE or with a shorter PATH still runs it, and an older
+// install on PATH does not answer for this one. The settings file is
+// per-developer, so a machine path is fine there.
+export function hookInvocation(entry,{env=process.env,platform=process.platform}={}){
+  if(platform==='win32')return {command:hookCommand,reason:'Windows: plain redue on PATH'};
+  let target;try{target=fs.realpathSync(entry);}catch{target=entry;}
+  // Paths that survive upgrades where they can: the entry as invoked (a
+  // global bin link, not the versioned file behind it) and the node on PATH
+  // (Homebrew's link, not its versioned cellar).
+  const real=file=>{try{return fs.realpathSync(file);}catch{return null;}};
+  const invoked=typeof process.argv[1]==='string'&&path.isAbsolute(process.argv[1])&&real(process.argv[1])===target?process.argv[1]:target;
+  const execReal=real(process.execPath);
+  const node=(env.PATH||'').split(path.delimiter).map(dir=>path.join(dir||'.','node')).find(file=>real(file)===execReal)??process.execPath;
+  const same=file=>runsEntry(file,target,env);
+  const here=findExecutable('redue',{env});
+  const login=spawnSync(env.SHELL||'/bin/sh',['-lc','command -v redue'],{env,encoding:'utf8',timeout:5000,stdio:['ignore','pipe','ignore']});
+  const loginPath=login.status===0?login.stdout.trim().split('\n').pop():null;
+  if(same(here)&&same(loginPath))return {command:hookCommand,reason:`redue on PATH is this install (${here})`};
+  return {command:`${quote(node)} ${quote(invoked)} agent hook claude`,
+    reason:!here&&!loginPath?'redue is not on PATH; the hook names this install by its absolute path':
+      `redue on PATH is ${here||loginPath||'missing'} in ${same(here)?'a login shell':'this shell'}, not this install; the hook names this install by its absolute path`};
+}
 // REDUE's entry is recognized by its command, not by a committed record: the
 // local file differs between checkouts, and users may edit the entry.
-const ownedHook=entry=>Array.isArray(entry?.hooks)&&entry.hooks.length>0&&entry.hooks.every(h=>h?.command===hookCommand);
+const ownedHook=entry=>Array.isArray(entry?.hooks)&&entry.hooks.length>0&&entry.hooks.every(h=>isHookCommand(h?.command));
 function parseSettings(text){
   if(text===null)return {};
   let value;try{value=JSON.parse(text);}catch{throw Error(`${settingsPath} is not valid JSON; fix it before agent setup or removal`);}
@@ -65,6 +101,45 @@ function hookInstalled(root,event='PreToolUse'){
   try{return (parseSettings(read(root,settingsPath)).hooks?.[event]||[]).some(ownedHook);}
   catch{return false;}
 }
+// What removing a host's integration changes, from its setup record: the
+// managed block, the skill, the hooks and the record.
+function removalChanges(root,host,record){
+  const h=hosts[host],before=read(root,h.instruction),after=before===null?null:before.replace(record.block,'');
+  const changes=[{path:h.instruction,before,after:record.instructionCreated&&after===''?null:after},
+    {path:h.skill,before:read(root,h.skill),after:null}];
+  if(host==='claude'){const settings=read(root,settingsPath);
+    changes.push({path:settingsPath,before:settings,after:settingsWith(settings,null)});}
+  changes.push({path:marker(host),before:read(root,marker(host)),after:null});
+  return changes;
+}
+// Removes a host's integration without needing the project config (redue
+// remove after the config is gone): the changed paths, each with its operation.
+export function removeIntegration(root,host='claude'){
+  const record=saved(root,host);if(!record)return [];
+  const health=inspect(root,host,record);if(health.integrity==='conflict')throw Error(health.reason);
+  const changes=removalChanges(root,host,record).filter(c=>c.before!==c.after);
+  apply(root,changes);
+  return changes.map(c=>`${c.after===null?'remove':'update'} ${c.path}`);
+}
+// Whether REDUE's Claude Code hooks are in the local settings.
+export const claudeHooksInstalled=root=>hookInstalled(root,'SessionStart')||hookInstalled(root);
+// Removes REDUE's Claude Code hooks from the local settings and keeps the
+// rest; the file's path when it changed, else null.
+export function removeClaudeHooks(root){
+  const before=read(root,settingsPath);if(before===null)return null;
+  const after=settingsWith(before,null);if(after===before)return null;
+  apply(root,[{path:settingsPath,before,after}]);return settingsPath;
+}
+// Whether the installed hook's command can start: an absolute one by its
+// files, plain redue by PATH.
+function hookRunnable(root){
+  let command=null;
+  try{command=(parseSettings(read(root,settingsPath)).hooks?.SessionStart||[]).find(ownedHook)?.hooks[0]?.command??null;}catch{}
+  const absolute=absoluteHook(command);
+  if(absolute)return fs.existsSync(absolute[0])&&fs.existsSync(absolute[1])?'installed (absolute path)':
+    'installed, but its Node or REDUE path no longer exists; run redue agent setup claude again';
+  return findExecutable('redue')?'installed':'installed, but redue is not on PATH, so it never runs';
+}
 function safeFile(root,relative){
   if(path.isAbsolute(relative)||relative.split(/[\\/]/).some(p=>p==='..'||p===''))throw Error('unsafe integration path');
   const file=path.resolve(root,relative);
@@ -273,7 +348,7 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
   const {root,relative,config}=project(configFile),h=hosts[host],record=saved(root,host),health=inspect(root,host,record);
   if(health.integrity==='conflict')throw Error(health.reason);
   const changes=[],notes=action==='setup'?warnings(root,host,cwd):[];
-  let hook=null,block=null;
+  let hook=null,sessionHook=null,block=null;
   if(action==='setup'){
     const before=read(root,h.instruction),skill=skillFor(relative,host,config);
     block=blockFor(host,blockForms(host,config,relative));
@@ -281,7 +356,12 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
       throw Error('unowned REDUE instruction or skill already exists; inspect it before setup');
     const after=record?before.replace(record.block,block):(before||'')+block;
     let scripts={};try{scripts=JSON.parse(read(root,'package.json')??'{}').scripts||{};}catch{}
-    hook=host==='claude'?hookFor(config,relative,scripts):null;
+    const invocation=host==='claude'?hookInvocation(entry):null;
+    if(invocation)notes.push(`Hook command: ${invocation.command} (${invocation.reason})`);
+    if(invocation&&invocation.command!==hookCommand)
+      notes.push('The agent instructions say `redue ...`: put this install on PATH (npm install --global @redue/cli@alpha) so the agent\'s shell can run them. The hook runs the checks it rewrites through this install either way.');
+    hook=host==='claude'?hookFor(config,relative,scripts,invocation.command):null;
+    sessionHook=host==='claude'?sessionHookFor(invocation.command):null;
     const next={schema:1,host,config:relative,instruction:h.instruction,skill:h.skill,
       block,skillHash:hash(skill),instructionCreated:record?.instructionCreated??before===null};
     changes.push({path:h.skill,before:read(root,h.skill),after:skill},
@@ -291,14 +371,7 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
         content:JSON.stringify(hook?next:{SessionStart:sessionHook},null,2)+
           (hook?'':'\nno PreToolUse hook: no typecheck or test check to match')});}
     changes.push({path:marker(host),before:read(root,marker(host)),after:JSON.stringify(next,null,2)+'\n'});
-  }else if(record){
-    const before=read(root,h.instruction),after=before.replace(record.block,'');
-    changes.push({path:h.instruction,before,after:record.instructionCreated&&after===''?null:after},
-      {path:h.skill,before:read(root,h.skill),after:null});
-    if(host==='claude'){const settings=read(root,settingsPath);
-      changes.push({path:settingsPath,before:settings,after:settingsWith(settings,null)});}
-    changes.push({path:marker(host),before:read(root,marker(host)),after:null});
-  }
+  }else if(record)changes.push(...removalChanges(root,host,record));
   const actual=changes.filter(c=>c.before!==c.after);
   const summary={schema:1,action,host,config:configFile,applied:false,
     changes:actual.map(c=>({path:c.path,operation:c.after===null?'remove':c.before===null?'create':'update',
@@ -355,7 +428,7 @@ export async function doctor({configFile,stateOverride,entry,cwd,host}){
       const out=spawnSync(launch.file,launch.args,{...launch.options,encoding:'utf8',timeout:2000,maxBuffer:4096,stdio:['ignore','pipe','pipe']});
       if(out.status===0)version=out.stdout.trim();}
     let integration={installed:false,integrity:'unknown'},hook=name==='claude'?'absent':'none',sessionHook=hook;
-    const installed=()=>value.command.path?'installed':'installed, but redue is not on PATH, so it never runs';
+    const installed=()=>hookRunnable(p.root);
     if(p)try{const record=saved(p.root,name);integration=inspect(p.root,name,record);
       if(name==='claude'&&hookInstalled(p.root))hook=installed();
       if(name==='claude'&&hookInstalled(p.root,'SessionStart'))sessionHook=installed();

package/src/claude-hook.mjs

@@ -6,12 +6,13 @@
 // Never exit 2: Claude Code treats exit 2 as a block.
 import fs from 'node:fs';
 import path from 'node:path';
-import {spawn} from 'node:child_process';
+import {spawn,spawnSync} from 'node:child_process';
 import {projectState} from './project-location.mjs';
 import {realObservedPath} from './path-identity.mjs';
 import {processAlive} from './process-liveness.mjs';
 import {scriptRunChecks} from './typescript-invocation.mjs';
 import {recipeLabel} from './presentation.mjs';
+import {findExecutable} from './executable-lookup.mjs';
 
 export const hookCommand='redue agent hook claude';
 // No shell metacharacters; `@` starts scoped package names.
@@ -31,6 +32,22 @@ export const defaultConfig='redue.config.json';
 // would need shell quoting.
 export const redueFor=(configFile=defaultConfig)=>configFile===defaultConfig?'redue':
   safe.test(configFile)?`redue --config ${configFile}`:null;
+export const shellQuote=value=>`'${String(value).replaceAll("'","'\\''")}'`;
+// How a rewritten command starts REDUE: plain `redue` when the hook's PATH
+// finds this install, else this install by absolute path. An agent shell
+// without redue on PATH cannot run the plain form.
+export function redueInvocation(entry,{env=process.env,platform=process.platform}={}){
+  if(platform==='win32'||runsEntry(findExecutable('redue',{env}),entry,env))return 'redue';
+  return `${shellQuote(process.execPath)} ${shellQuote(entry)}`;
+}
+// Whether the command at `file` runs this install's entry: the same file, or
+// a shim or wrapper that reports it (redue --entry).
+export function runsEntry(file,entry,env=process.env){
+  if(!file)return false;
+  try{const target=fs.realpathSync(entry);if(fs.realpathSync(file)===target)return true;
+    const out=spawnSync(file,['--entry'],{env,encoding:'utf8',timeout:5000,stdio:['ignore','pipe','ignore']});
+    return out.status===0&&fs.realpathSync(out.stdout.trim())===target;}catch{return false;}
+}
 
 // Package-manager commands that a script of the same name would not reach.
 const builtins={pnpm:new Set(['add','audit','bin','config','create','dedupe','deploy','dlx','doctor','env','exec','fetch',
@@ -265,9 +282,9 @@ export function matchCheck(command,config,configFile,dir,scripts){
 }
 // 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){
+export function recordedCommand(command,name,configFile=defaultConfig,invoke='redue'){
   const names=Array.isArray(name)?name:[name];
-  const parts=split(command),redue=redueFor(configFile);
+  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(' && ');
   return parts.base===run?null:names.length>1&&parts.suffix?`(${run})${parts.suffix}`:run+parts.suffix;
@@ -374,7 +391,7 @@ export function sessionStart(input,{entry}){
 }
 
 // Returns the hook's stdout object, or null to allow the command.
-export async function claudeHook(input,{entry,timeout}){
+export async function claudeHook(input,{entry,timeout,invoke=null}){
   if(input?.tool_name!=='Bash')return null;
   const command=input.tool_input?.command,root=input.cwd;
   if(typeof command!=='string'||/^\s*REDUE_FORCE=1(?:\s|$)/.test(command))return null;
@@ -414,7 +431,7 @@ export async function claudeHook(input,{entry,timeout}){
       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)&&
-        names.every(name=>status.checks.some(item=>item?.name===name))?recordedCommand(entered.command,pending,configPath):null;
+        names.every(name=>status.checks.some(item=>item?.name===name))?recordedCommand(entered.command,pending,configPath,invoke??redueInvocation(entry)):null;
       return rewritten?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow',
         permissionDecisionReason:`REDUE: ${pending.map(name=>JSON.stringify(name)).join(', ')} of this script's checks ${pending.length===1?'is':'are'} not CURRENT; running ${pending.length===1?'it':'them'} through redue run so the result is recorded.`,
         updatedInput:{...input.tool_input,command:entered.prefix+rewritten}}}:null;
@@ -429,7 +446,7 @@ export async function claudeHook(input,{entry,timeout}){
   // 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):null;
+    status.checks.some(item=>item?.name===name)?recordedCommand(entered.command,name,configPath,invoke??redueInvocation(entry)):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

@@ -5,7 +5,7 @@ import {directQualification,directInterpretation,observedNpmContext} from './dir
 import {directRunCertificateAllowed,directRunCertificate,directRunRecordable,directRunRecording,probeQuestions,validateRunRecord} from './direct-run-certificate.mjs';
 import {queryAnswer,runFactChange} from './typescript-list.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,toolOutput,toolchainDirs} from './node-script.mjs';
+import {childProgram,lookup,pnpmConfigFiles,scriptCaches,scriptInstalledPaths,scriptInterpretation,scriptQualification,scriptRunFacts,pnpmNameless,toolOutput,toolchainDirs} from './node-script.mjs';
 import path from 'node:path';
 import net from 'node:net';
 import os from 'node:os';
@@ -400,7 +400,7 @@ async function execute() {
     // what was there (test/tmp). When they are the only observed change, the
     // run is kept with the end checkpoint, which includes them.
     let outputs=null;
-    let eventsExplained=false;
+    let eventsExplained=false,unexplained=end?.inputEventPaths||null;
     if(guard&&snap&&end&&snap.planId===end.planId&&snap.probeHash===end.probeHash&&snap.observationHealthy&&end.observationHealthy&&
       (snap.inputEventSerial===end.inputEventSerial||end.inputEventPathsComplete===true)){
       // A directory event is not an input change; a change to its files shows
@@ -408,9 +408,10 @@ async function execute() {
       const directory=rel=>{try{return fs.lstatSync(path.join(root,rel)).isDirectory();}catch{return false;}};
       const changed=changedFiles(snap.files,end.files),events=(end.inputEventPaths||[]).filter(rel=>!directory(rel));
       const touched=[...new Set([...changed,...events])].sort();
-      const output=rel=>guard.isOutput(rel)||general&&toolOutput(rel,guard);
+      const output=rel=>guard.isOutput(rel)||general&&(toolOutput(rel,guard)||pnpmNameless(rel,guard,root,[snap.files,end.files]));
       const ignored=touched.length&&touched.every(output)?gitIgnored(root,touched):new Set();
-      if(touched.every(file=>ignored.has(file))){eventsExplained=true;if(changed.length)outputs=changed;}
+      unexplained=touched.filter(file=>!ignored.has(file));
+      if(!unexplained.length){eventsExplained=true;if(changed.length)outputs=changed;}
     }
     // The end certificate, recorded or probed, must cover what this compile received.
     // With no input event, gap or content change in between, it also holds at the start.
@@ -442,8 +443,13 @@ async function execute() {
       captureIssues.push('observer generation changed during execution');
     if(snap?.planGeneration!==end?.planGeneration)
       captureIssues.push('input plan rebuilt during execution');
-    if(snap?.inputEventSerial!==end?.inputEventSerial&&!eventsExplained)
-      captureIssues.push('declared input event occurred during execution');
+    // The reason names up to five files the run did not explain, and a count of the rest.
+    if(snap?.inputEventSerial!==end?.inputEventSerial&&!eventsExplained){
+      const named=[...new Set(unexplained||[])],more=named.length-5,
+        unrecorded=end?.inputEventPathsComplete===false?' (not every event path was kept)':'';
+      captureIssues.push('declared input event occurred during execution'+(named.length?
+        `: ${named.slice(0,5).join(', ')}${more>0?` and ${more} more`:''}`:'')+unrecorded);
+    }
     // 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');

package/src/node-script.mjs

@@ -57,6 +57,15 @@ export const toolOutputPath=rel=>pnpmState(rel)||pnpmTemp(rel)||vueTypes(rel);
 // The run wrote it: a recorded process did, or, for pnpm's files, the pnpm
 // executable ran, which writes them natively.
 export const toolOutput=(rel,guard)=>toolOutputPath(rel)&&(guard.wroteInstalled(rel)||(pnpmState(rel)||pnpmTemp(rel))&&guard.opaque);
+// On Linux, pnpm 12 also writes a file with no name (O_TMPFILE) in the root
+// node_modules, whose writes inotify reports as '#<inode>'. Such an event is
+// the run's output when the pnpm executable ran and no file has that name, at
+// either checkpoint or now. Limit: another program's file with no name there,
+// during a run that started the pnpm executable, is taken as pnpm's too; once
+// linked in under any name, its writes through the open file are missed.
+export const pnpmNameless=(rel,guard,root,checkpoints,platform=process.platform)=>platform==='linux'&&/^node_modules\/#\d+$/.test(rel)&&
+  guard.opaque&&checkpoints.every(files=>files&&!Object.hasOwn(files,rel))&&
+  (()=>{try{fs.lstatSync(path.join(root,rel));return false;}catch(error){return error.code==='ENOENT';}})();
 // The installed paths the recorder treats as observed by identity.
 export const scriptInstalledPaths=(root,dirs=[])=>[...modulesDirs(dirs),...installState].map(at=>path.join(root,at));
 // Variables a recorded run cannot be seen reading: Node's and libc's (as in
@@ -227,6 +236,19 @@ export const scriptPath=(dir,callerPath)=>{
 // Why a shell command line could start a program REDUE does not record, or
 // null. Names are looked up along `searchPath` from `cwd`. A script the pnpm
 // executable runs is read the same way, since the recorder cannot see it.
+// TypeScript 7's Node launchers (tsc in typescript@7, tsgo in
+// @typescript/native-preview) replace themselves with a native compiler REDUE
+// does not record: the package and version, or null.
+export function nativeTypeScriptLauncher(file){
+  let dir;try{dir=path.dirname(fs.realpathSync(file));}catch{return null;}
+  for(let n=0;n<3;n++,dir=path.dirname(dir)){
+    let pkg;try{pkg=JSON.parse(fs.readFileSync(path.join(dir,'package.json'),'utf8'));}catch{continue;}
+    if(pkg.name==='typescript'&&Number(String(pkg.version).split('.')[0])>=7||pkg.name==='@typescript/native-preview')
+      return `${pkg.name} ${pkg.version}`;
+    return null;
+  }
+  return null;
+}
 export function commandLineIssue(text,{cwd,searchPath,depth=0}={}){
   if(depth>8)return 'the scripts run each other too deeply for REDUE to read';
   const parsed=parseCommandLine(text);
@@ -261,6 +283,8 @@ export function commandLineIssue(text,{cwd,searchPath,depth=0}={}){
       if(kind==='node'){
         const flag=['node','nodejs'].includes(path.basename(file))&&args.find(arg=>nativeReads.test(arg.text));
         if(flag)return `runs node ${flag.text.split('=')[0]}, which reads a file REDUE cannot see`;
+        const native=nativeTypeScriptLauncher(file);
+        if(native)return `runs ${path.basename(name)} from ${native}, a native compiler REDUE does not record`;
         break;
       }
       if(kind==='pnpm'){const issue=pnpmRunIssue(args.map(arg=>arg.text),{cwd:dir,searchPath,depth});if(issue)return issue;break;}

package/src/pnpm-inputs.mjs

@@ -2,7 +2,7 @@
 // repository-relative input sets and resolution relationships, never pnpm
 // virtual-store names as semantic identities.
 import {probeTimeLeft} from './probe-deadline.mjs';
-import {compilerFiles} from './typescript-list.mjs';
+import {compilerApiIssue,compilerFiles} from './typescript-list.mjs';
 import fs from 'node:fs';
 import path from 'node:path';
 import {createRequire} from 'node:module';
@@ -298,7 +298,9 @@ export function pnpmTypecheckInputs(root,workspace,run,{captureQueries=false}={}
   let tsPackage;try{tsPackage=realObservedPath(lookup.resolve('typescript/package.json'));}
   catch{throw Error('installed TypeScript compiler cannot be resolved');}
   if(!within(tsPackage,root))throw Error('TypeScript compiler is outside the observed checkout');
-  const tsRoot=path.dirname(tsPackage),ts=lookup('typescript');
+  const tsRoot=path.dirname(tsPackage),apiIssue=compilerApiIssue(tsRoot);
+  if(apiIssue)throw Error(apiIssue);
+  const ts=lookup('typescript');
   const tsc=path.join(tsRoot,'bin','tsc');
   if(!exists(tsc))throw Error('installed TypeScript executable is missing');
   const configStarted=performance.now();

package/src/setup.mjs

@@ -0,0 +1,178 @@
+// `redue setup claude` and `redue remove`: one command from a project with
+// installed dependencies to a working Claude Code integration, and one to
+// undo it. Setup runs init when the project has no config, agent setup
+// claude, start, and one recorded run of each check init can qualify that is
+// not CURRENT. It prints every file it writes. What it created is kept in a
+// record in the clone's Git directory (never committed); a later setup adds
+// to that account and never forgets it. Remove undoes exactly what the record
+// says setup created: the agent files or just this machine's hooks, the
+// observer state, the local ignore line, and the config if it is unchanged
+// since setup wrote it.
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {createInterface} from 'node:readline/promises';
+import {projectState} from './project-location.mjs';
+import {claudeHooksInstalled,removeClaudeHooks,removeIntegration} from './agent-integration.mjs';
+
+const configName='redue.config.json',localSettings='.claude/settings.local.json',agentRecord='.redue/agents/claude.json';
+const hash=text=>createHash('sha256').update(text).digest('hex');
+const readText=file=>{try{return fs.readFileSync(file,'utf8');}catch{return null;}};
+const git=(root,...args)=>spawnSync('git',args,{cwd:root,encoding:'utf8',stdio:['ignore','pipe','ignore']});
+const ignoreLine=`/${localSettings}`;
+
+async function confirm(question,yes,{defaultYes}){
+  if(yes)return true;
+  if(!process.stdin.isTTY||!process.stdout.isTTY)throw Error('not a terminal; run again with --yes to proceed without prompts');
+  const prompt=createInterface({input:process.stdin,output:process.stdout});
+  try{const answer=(await prompt.question(`${question} ${defaultYes?'[Y/n]':'[y/N]'} `)).trim();
+    return defaultYes?!/^n/i.test(answer):/^y/i.test(answer);}finally{prompt.close();}
+}
+
+export async function setupCommand(args,{entry,cwd=process.cwd()}){
+  const action=args.shift();
+  const yes=args.includes('--yes'),rest=args.filter(arg=>arg!=='--yes');
+  if(action==='setup'&&(rest.length!==1||rest[0]!=='claude'))throw Error('use redue setup claude [--yes]');
+  if(action==='remove'&&rest.length)throw Error('use redue remove [--yes]');
+  const top=git(cwd,'rev-parse','--show-toplevel');
+  if(top.status!==0)throw Error('run this inside a Git checkout');
+  const root=fs.realpathSync(top.stdout.trim());
+  if(!fs.existsSync(path.join(root,'package.json')))throw Error(`no package.json at the repository root (${root})`);
+  // The entry as invoked, so a hook written by a child names the install's
+  // stable bin link rather than the versioned file behind it.
+  const invoked=typeof process.argv[1]==='string'&&path.isAbsolute(process.argv[1])&&
+    (()=>{try{return fs.realpathSync(process.argv[1])===fs.realpathSync(entry);}catch{return false;}})()?process.argv[1]:entry;
+  // Every step is the ordinary command, so its own output says what it did.
+  const redue=(argv,options={})=>spawnSync(process.execPath,[invoked,...argv],{cwd:root,encoding:'utf8',
+    stdio:options.capture?['ignore','pipe','pipe']:'inherit',timeout:options.timeout});
+  // One record per checkout, beside the others in the shared Git directory:
+  // linked worktrees share .git/info/exclude.
+  const common=path.resolve(root,git(root,'rev-parse','--git-common-dir').stdout.trim());
+  const recordFile=path.join(common,`redue-setup-${hash(root).slice(0,16)}.json`);
+  // Other checkouts' records, for checkouts that still exist.
+  const others=()=>{try{return fs.readdirSync(common).filter(name=>/^redue-setup-[0-9a-f]{16}\.json$/.test(name)&&path.join(common,name)!==recordFile)
+    .map(name=>JSON.parse(readText(path.join(common,name))??'null')).filter(other=>other&&fs.existsSync(other.root));}catch{return [];}};
+  const context={root,redue,yes,record:JSON.parse(readText(recordFile)??'null'),recordFile,
+    exclude:path.join(common,'info','exclude'),others,save:next=>fs.writeFileSync(recordFile,JSON.stringify(next,null,2)+'\n')};
+  return action==='setup'?setup(context):remove(context);
+}
+
+async function setup({root,redue,yes,record:previous,recordFile,exclude,save}){
+  if(!fs.existsSync(path.join(root,'node_modules')))
+    throw Error('dependencies are not installed: run your package manager\'s install (npm install, pnpm install, yarn) first');
+  if(fs.existsSync(path.join(root,'vstate.config.json'))&&!fs.existsSync(path.join(root,configName)))
+    throw Error('a legacy vstate.config.json exists; rename it to redue.config.json or remove it first');
+  if(git(root,'ls-files','--error-unmatch',localSettings).status===0)
+    throw Error(`${localSettings} is committed; the hooks REDUE adds there name this machine's paths. Untrack it (git rm --cached) first`);
+  const configPath=path.join(root,configName),configExisted=fs.existsSync(configPath);
+  // init's account of the checks: which can qualify, also with a config.
+  const preview=redue(['init','--dry-run','--json'],{capture:true});
+  if(preview.status!==0)throw Error(preview.stderr.trim().replace(/^redue: /,'')||'init failed');
+  const found=JSON.parse(preview.stdout);
+  if(!configExisted&&!found.writable)throw Error(`nothing to set up: ${found.issue||(found.checks.length?found.checks.map(check=>`${check.name}: ${check.reason}`).join('; '):'no typecheck, lint or test script REDUE can use')}`);
+  const levels=new Map(found.checks.map(check=>[check.name,check.level]));
+  const names=configExisted?JSON.parse(readText(configPath)).checks.map(check=>check.name):found.checks.map(check=>check.name);
+  const ready=names.filter(name=>levels.get(name)==='ready');
+  console.log(`Setting up REDUE for Claude Code in ${root}`);
+  console.log(configExisted?`  keep ${configName} (exists)`:`  create ${configName}: ${names.map(name=>`${name} (${levels.get(name)==='ready'?'can qualify':'recording-only'})`).join(', ')}`);
+  console.log(`  write the Claude Code integration: CLAUDE.md section, .claude/skills/redue-verification/SKILL.md, ${localSettings} hooks, ${agentRecord}`);
+  console.log(`  start the observer and record ${ready.length?ready.join(', '):'no check'} once, unless already CURRENT`);
+  if(!await confirm('Proceed?',yes,{defaultYes:true})){console.log('Nothing written.');return {applied:false};}
+  // What this run creates is added to what earlier runs created.
+  const state=projectState(root,configPath);
+  const own={schema:1,host:'claude',root,config:configName,state,
+    configCreated:Boolean(previous?.configCreated),configHash:previous?.configHash??null,
+    agentCreated:Boolean(previous?.agentCreated)||!fs.existsSync(path.join(root,agentRecord)),
+    hooksAdded:Boolean(previous?.hooksAdded)||!claudeHooksInstalled(root),
+    stateCreated:Boolean(previous?.stateCreated)||!fs.existsSync(state),
+    excludeAdded:Boolean(previous?.excludeAdded)};
+  if(!configExisted){
+    const init=redue(['init']);
+    if(init.status!==0||!fs.existsSync(configPath))throw Error(`init did not write ${configName}; nothing else was written`);
+    Object.assign(own,{configCreated:true,configHash:hash(readText(configPath))});
+  }
+  save(own);
+  console.log(`${previous?'update':'create'} ${recordFile}: what setup created, for redue remove`);
+  const agent=redue(['agent','setup','claude','--apply']);
+  if(agent.status!==0)throw Error('agent setup failed; see above. redue remove undoes what setup wrote');
+  // The hooks' settings hold machine paths: keep them out of commits in this
+  // clone when Git does not ignore them.
+  if(git(root,'check-ignore','-q',localSettings).status===1){
+    fs.mkdirSync(path.dirname(exclude),{recursive:true});
+    const text=readText(exclude)??'';
+    fs.writeFileSync(exclude,`${text}${text&&!text.endsWith('\n')?'\n':''}${ignoreLine}\n`);
+    console.log(`update ${exclude}: ignore ${ignoreLine} in this clone`);
+    own.excludeAdded=true;save(own);
+  }
+  // An observer that is already running is what start would give.
+  const started=redue(['start'],{capture:true});
+  process.stdout.write(started.stdout);
+  if(started.status!==0){
+    if(!/already running/.test(started.stderr))throw Error(`the observer did not start: ${started.stderr.trim().replace(/^redue: /,'')}`);
+    console.log('Observer already running.');
+  }
+  // The observer indexes the project first; a run before that cannot be
+  // recorded as reusable. Wait while it plans and indexes; once its plan is
+  // ready, an observer that is still unhealthy says why in the status below.
+  // Nothing to wait for when no check can qualify.
+  const observation=()=>{const out=redue(['status','--json'],{capture:true});try{return JSON.parse(out.stdout).observation??null;}catch{return null;}};
+  // An answer without a phase (a stopped observer) for 10 s in a row ends the
+  // wait too.
+  const begun=Date.now();let told=-1,unread=0,phaseless=0;
+  for(let state=observation();ready.length&&!(state?.phase==='ready'||state?.phase==='unavailable')&&phaseless<10;state=observation()){
+    const seconds=Math.round((Date.now()-begun)/1000);
+    unread=state===null?unread+1:0;phaseless=state&&!state.phase?phaseless+1:0;
+    if(unread>=30)throw Error('the observer\'s status cannot be read; run redue status to see why');
+    if(seconds>15*60)throw Error(`the observer is not ready after 15 minutes (${state?.reason||state?.phase||'unknown'}); run redue status, then redue setup claude again`);
+    if(Math.floor(seconds/15)>told){told=Math.floor(seconds/15);console.log(seconds?`Still indexing (${seconds} s)...`:'Waiting for the observer to index the project...');}
+    await new Promise(resolve=>setTimeout(resolve,1000));
+  }
+  // One recorded run of each check that can qualify and is not CURRENT.
+  const statusOf=()=>{const out=redue(['status','--sync','--json'],{capture:true,timeout:600_000});try{return JSON.parse(out.stdout).checks;}catch{return [];}};
+  const rows=statusOf(),due=ready.filter(name=>rows.find(row=>row.name===name)?.freshness!=='CURRENT');
+  for(const name of due){console.log(`Recording ${name} once:`);redue(['run',name]);}
+  if(ready.length&&!due.length)console.log(`Already CURRENT: ${ready.join(', ')}.`);
+  for(const row of statusOf())console.log(`  ${row.name}: ${row.freshness}${row.result?' / '+row.result:''}${row.freshness==='CURRENT'?'':' — '+row.reason}`);
+  console.log('Done. Start a new Claude Code session in this project. Undo with redue remove.');
+  return {applied:true};
+}
+
+async function remove({root,redue,yes,record:own,recordFile,exclude,others}){
+  if(!own){console.log('No setup record for this checkout: nothing redue setup created to remove.');
+    console.log('To undo a setup made step by step: redue agent remove claude --apply, then redue remove-state.');return {removed:false};}
+  const configPath=path.join(root,configName),configText=readText(configPath);
+  const removeAgent=own.agentCreated&&fs.existsSync(path.join(root,agentRecord));
+  const removeHooks=!removeAgent&&own.hooksAdded&&claudeHooksInstalled(root);
+  const removeState=own.stateCreated&&fs.existsSync(own.state);
+  const deleteConfig=own.configCreated&&configText!==null&&hash(configText)===own.configHash;
+  // The ignore line goes only when no other checkout of this repository is
+  // set up: those rely on it too, whichever added it.
+  const removeIgnore=own.excludeAdded&&!others().length;
+  console.log(`Removing what redue setup created in ${root}`);
+  if(removeAgent)console.log('  remove the Claude Code integration');
+  if(removeHooks)console.log(`  remove REDUE's hooks from ${localSettings} (the integration predates setup)`);
+  if(removeState)console.log('  stop the observer and remove its local state (receipts included)');
+  else if(!own.stateCreated)console.log('  keep the observer state (it predates setup)');
+  if(own.configCreated&&configText!==null)console.log(deleteConfig?`  delete ${configName}`:`  keep ${configName} (edited since setup)`);
+  if(removeIgnore)console.log(`  remove ${ignoreLine} from ${exclude}`);
+  console.log(`  delete ${recordFile}`);
+  if(!await confirm('Proceed?',yes,{defaultYes:false})){console.log('Nothing removed.');return {removed:false};}
+  if(removeAgent)for(const line of removeIntegration(root))console.log(line);
+  if(removeHooks){const changed=removeClaudeHooks(root);if(changed)console.log(`update ${changed}`);}
+  if(removeState&&redue(['--state-dir',own.state,'remove-state']).status!==0)
+    throw Error('the observer state was not removed; see above. The config and setup record are kept so you can retry');
+  if(deleteConfig){fs.unlinkSync(configPath);console.log(`remove ${configName}`);}
+  if(removeIgnore){
+    const text=readText(exclude);
+    if(text!==null&&text.split('\n').includes(ignoreLine)){
+      fs.writeFileSync(exclude,text.split('\n').filter(line=>line!==ignoreLine).join('\n'));
+      console.log(`update ${exclude}`);}
+  }
+  fs.unlinkSync(recordFile);console.log(`remove ${recordFile}`);
+  // Folders the integration lived in, when nothing else is left in them.
+  for(const dir of ['.redue/agents','.redue','.claude/skills/redue-verification','.claude/skills','.claude'])
+    try{fs.rmdirSync(path.join(root,dir));console.log(`remove ${dir}/`);}catch{}
+  console.log('Done.');
+  return {removed:true};
+}

package/src/test-direct.mjs

@@ -16,6 +16,8 @@ import {queryAnswer} from './typescript-list.mjs';
 import {pnpmInstallInfo,pnpmProjectInfo,yaml} from './pnpm-inputs.mjs';
 import {workspaceManifests} from './workspace-manifests.mjs';
 import {atomicJson} from './state-store.mjs';
+// node-script.mjs imports this module too; childProgram is only called at run time.
+import {childProgram} from './node-script.mjs';
 import {racyUntil} from './path-identity.mjs';
 
 const digest=value=>createHash('sha256').update(value).digest('hex');
@@ -73,7 +75,7 @@ export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=t
   const issues=[],add=issue=>{if(!issues.includes(issue))issues.push(issue);};
   const included=patternMatcher(sourcePatterns);
   const observed=rel=>Object.hasOwn(files||{},rel);
-  const headers=new Map(),records=[];
+  const headers=new Map(),records=[],headerCount=new Map(),threadsStarted=new Map();
   let names=[];
   try{names=fs.readdirSync(dir).filter(name=>name.endsWith('.jsonl'));}
   catch{return {issues:['the run record is unavailable'],runFacts:[],environmentReads:{},isOutput:()=>false};}
@@ -84,6 +86,9 @@ export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=t
     const header=rows[0]?.[0]==='H'?rows[0][1]:null;
     if(!header||!Number.isSafeInteger(header.pid)||!Number.isSafeInteger(header.threadId)){add('a run record is unreadable');continue;}
     headers.set(`${header.pid}-${header.threadId}`,header);
+    // After process.execve, the new program's threads append to the same
+    // records: each thread started needs its own header.
+    headerCount.set(`${header.pid}-${header.threadId}`,rows.filter(row=>row?.[0]==='H'&&!row[1]?.internal).length);
     records.push({header,rows:rows.slice(1)});
   }
   let opaque=false;
@@ -101,7 +106,24 @@ export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=t
   // PIDs is that child, not an execSync child (which reports no PID).
   const installedWrites=new Set();
   const reads=new Map(),produced=new Set(),created=new Set(),environmentReads={},spawned=new Map(),childPids=new Map();
+  // Whether a started program is accounted for: {issue} or {needsHeader}.
+  // The tests recipe wants every program to become a recorded process; a
+  // shell, which can run other programs first, is read by its command as
+  // the general recipe reads it.
+  const judge=(child,main)=>{
+    if(!programs){
+      const judged=/^(sh|bash|dash|zsh|ksh|fish|csh|tcsh)$/.test(path.basename(String(child.file)))?childProgram(child,{parentMain:main}):{};
+      return judged.issue?judged:{needsHeader:true};}
+    const judged=programs.judge(child,main);
+    if(!judged.issue)opaque||=Boolean(judged.opaque);
+    return judged;
+  };
   for(const {header,rows} of records){
+    // A program this process replaced itself with (process.execve) that must
+    // load the recorder: its header follows in this record, from the same
+    // parent. Later rows come from the program now running. (A reused PID
+    // also appends a header to an old record.)
+    let replaced=null,main=header.main??null;
     for(const row of rows){
       const [kind,...value]=Array.isArray(row)?row:[];
       if(kind==='U')add(`recorder: ${value[0]}`);
@@ -121,16 +143,26 @@ export function testRunGuard(dir,{root,sourcePatterns,files,runner,environment=t
         if(kind==='C')childPids.set(header.pid,[...childPids.get(header.pid)||[],value[0]]);
         // The general recipe accounts for each program; one that needs no
         // recorder (a shell, the pnpm executable) is not matched to a header.
-        if(programs){const judged=programs.judge({file,args,cwd,searchPath,env,script},header.main??null);
-          if(judged.issue){add(judged.issue);continue;}
-          opaque||=Boolean(judged.opaque);
-          if(!judged.needsHeader)continue;}
+        const judged=judge({file,args,cwd,searchPath,env,script},main);
+        if(judged.issue){add(judged.issue);continue;}
+        if(!judged.needsHeader)continue;
         const list=spawned.get(header.pid)||[];list.push({pid:kind==='C'?value[0]:null,file});
         spawned.set(header.pid,list);}
-      else if(kind==='T'){if(!headers.has(`${header.pid}-${value[0]}`))add('a worker thread did not load the REDUE recorder');}
-      else if(kind!=='H')add('a run record is unreadable');
+      else if(kind==='X'){
+        const [file,args,cwd,searchPath,env,script]=value;
+        const judged=judge({file,args,cwd,searchPath,env,script},main);
+        if(judged.issue){add(judged.issue);replaced=null;continue;}
+        replaced=judged.needsHeader?file:null;}
+      else if(kind==='Y')replaced=null;
+      else if(kind==='T'){const key=`${header.pid}-${value[0]}`;threadsStarted.set(key,(threadsStarted.get(key)||0)+1);}
+      else if(kind==='H'){
+        if(replaced!==null&&value[0]?.ppid!==header.ppid)add(`replaced itself with ${path.basename(String(replaced))}, which REDUE does not record`);
+        replaced=null;main=value[0]?.main??null;}
+      else add('a run record is unreadable');
     }
+    if(replaced!==null)add(`replaced itself with ${path.basename(String(replaced))}, which REDUE does not record`);
   }
+  for(const [key,count] of threadsStarted)if((headerCount.get(key)||0)<count)add('a worker thread did not load the REDUE recorder');
   // Every child must be a recorded Node process: by PID when known, otherwise
   // by the number of recorded processes whose parent started it.
   for(const [parent,children] of spawned){