@redue/cli 0.1.0-alpha.15 → 0.1.0-alpha.16

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.1.0-alpha.16 — 2026-10-22
+
+Changes to the Claude Code integration, and one fix for commands that meet
+on fresh state. Run `redue agent setup claude --apply` again to get the new
+hook entries.
+
+- A SessionStart hook starts the project's observer when a session starts,
+  resumes, clears or compacts, if none is running. It returns at once and
+  prints nothing. Without a running observer every check was UNVERIFIED, so
+  the hook could neither skip nor record. `agent doctor` reports it.
+- The hook matches more command forms, each mapping to one configured check:
+  `pnpm SCRIPT`, `pnpm run SCRIPT`, `yarn SCRIPT`, `yarn run SCRIPT`,
+  `pnpm exec tsc ...`; for a workspace package's check, `pnpm --filter NAME
+  SCRIPT`, `yarn workspace NAME SCRIPT`, `npm run SCRIPT -w NAME`, and its
+  script after a `cd` into the package. In the census of 108 public
+  TypeScript repos, 61 use pnpm or Yarn.
+- `turbo run TASK` and, in pnpm projects, `pnpm -r TASK` (or a root script
+  that is one of them) are skipped only when every workspace package with the
+  task's script has a check and all are CURRENT; otherwise they run as typed,
+  never rewritten. No skip when turbo may run more (other `dependsOn` tasks,
+  `with`, package-scoped keys, a package turbo.json), when pnpm includes the
+  workspace root, or for a root script with pre/post scripts. Filters and nx
+  are not matched.
+- Fixed: when two commands met on fresh state (SessionStart's `start` and the
+  first `status`), the second failed and no observer started.
+
+Pilot eval on alpha.16 code (CI 39799994225, 96 sessions over twilio,
+semiotic, Ultra-Card and SwitchHosts): 0 critical findings; 29 skipped
+typechecks, each confirmed by a plain rerun.
 ## 0.1.0-alpha.15 — 2026-10-22
 
 No change to observation, status or `redue run` since alpha.14; the changes

package/README.md

@@ -37,7 +37,7 @@ it; relevant source edits make it stale. [Run the reproducible demo](docs/contri
 
 ## Install the alpha
 
-The opt-in pilot uses **0.1.0-alpha.15**. Follow the
+The opt-in pilot uses **0.1.0-alpha.16**. Follow the
 [fixed-version pilot guide](docs/user/pilot.md) for supported projects, setup,
 updates and voluntary feedback. No external usage results are claimed yet.
 

package/bin/redue.mjs

@@ -323,7 +323,13 @@ if(maintenance&&!fs.existsSync(runtimeFile)){
   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');
@@ -333,7 +339,7 @@ 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);

package/docs/user/agents.md

@@ -69,25 +69,58 @@ Start a fresh agent session in this checkout, then give it your ordinary task.
 Interactive setup shows the changes and asks before applying; noninteractive
 setup requires `--apply`. `--dry-run` never writes. Installing REDUE or running
 `init` does not connect an agent automatically. Setup does not start an observer
-or execute verification. Use `redue start` when you want observation.
+or execute verification. With Claude Code, a SessionStart hook starts the
+observer when a session starts (below); otherwise use `redue start`.
 
 ## Claude Code typecheck hook
 
-`redue agent setup claude --apply` also adds a PreToolUse hook to
-`.claude/settings.local.json`. The hook needs a local REDUE install, so it is
+`redue agent setup claude --apply` also adds a PreToolUse hook and a
+SessionStart hook to `.claude/settings.local.json`. Both run
+`redue agent hook claude`, which needs a local REDUE install, so they are
 per-developer; keep that file out of commits. Other settings in the file are kept,
 but the file is rewritten as 2-space JSON. `.claude/settings.json` is not touched.
-`redue agent remove claude --apply` removes only the entry REDUE added.
+`redue agent remove claude --apply` removes only the entries REDUE added.
 
-The hook skips an exact rerun of a configured typecheck: a check with
-`kind: "typecheck"` or named `typecheck`. It matches these commands, run from the
-project root:
+When a session starts, resumes, clears or compacts, the SessionStart hook starts
+this project's observer if none is running. It launches `redue start` in the
+background and returns at once, and prints nothing, so it adds nothing to the
+agent's context. Until the observer's first index is done, checks are
+UNVERIFIED and run as typed. An observer you stopped with `redue stop` starts
+again with the next session; remove the hook to prevent that. Setups from
+alpha.15 or earlier get the hook by running `redue agent setup claude --apply`
+again.
+
+The hook skips an exact rerun of a configured typecheck (a check with
+`kind: "typecheck"` or named `typecheck`) or direct test check. It matches
+these commands, run from the project root:
 
 - `redue run CHECK`, or `redue --config FILE run CHECK` when the config is not
   `redue.config.json`
-- `npm run SCRIPT`, when the check has an npm script
-- `npx tsc --noEmit`, for the direct-TypeScript recipe
+- the check's script through the project's package manager: `npm run SCRIPT`
+  (and `npm test`), `pnpm SCRIPT`, `pnpm run SCRIPT`, `yarn SCRIPT` or
+  `yarn run SCRIPT`. The short form is left out when the script is named like
+  one of the package manager's own commands.
+- the tool the check runs: `npx tsc ARGS` (and `pnpm exec tsc ARGS` with pnpm)
+  for a direct TypeScript check, or the runner's command, alone or after `npx`,
+  for a direct test check
 - the check's `command`, when it has no `@` tokens
+- for a workspace package's check: `pnpm --filter NAME SCRIPT` (also
+  `--filter=NAME`, `-F NAME`, and with `run`), `yarn workspace NAME SCRIPT`, or
+  `npm run SCRIPT -w NAME` (also `--workspace NAME`, `--workspace=NAME` and
+  `npm -w NAME run SCRIPT`). After `cd` into the package's directory, the
+  package-manager script forms and tool forms match that check.
+
+A `turbo run TASK` (or `turbo TASK`, alone or after `npx` or `pnpm exec`) or,
+in a pnpm project, `pnpm -r TASK` (`--recursive`, with or without `run`) that
+runs a checked task in every workspace package is skipped only when every check
+it would run is CURRENT, PASS and `reuse_eligible`. Every package with the
+task's script must have a check. turbo must define the task, with `dependsOn`
+listing at most `^TASK`, no `with`, no `PACKAGE#TASK` entries and no package
+`turbo.json`; `pnpm -r` must not include the workspace root. A root script
+whose text is such a command counts as that command, unless it has pre- or
+post-scripts. In every other case the command runs as typed: turbo caches its
+own results, so the hook never rewrites it. Filters (`--filter`) and nx are not
+matched.
 
 Each form may end with `2>&1` and then one `| tail -n N`, `| head -n N`,
 `| tail -N` or `| head -N`. It may also be the first command of a `;` or `&&`
@@ -121,8 +154,10 @@ Limits:
 
 - The hook judges its own environment, which Claude Code passes to it. The Bash
   tool can add variables from your shell profile. The hook cannot see those.
-- Commands run from a subdirectory, after another command (`cd x && tsc`), or
-  combined with `||`, `&` or other pipes, are not matched.
+- Commands run from a session that started in a subdirectory, after a `cd`
+  outside the project, or combined with `||`, `&` or other pipes, are not
+  matched. After a `cd` into any other directory than the root or a checked
+  package's, nothing matches.
 - A skip writes nothing. If a typecheck command also emits files, later
   commands see the files from its last run.
 - Only the Bash tool is covered, not PowerShell.

package/docs/user/pilot.md

@@ -1,4 +1,4 @@
-# Opt-in development pilot: alpha.15
+# Opt-in development pilot: alpha.16
 
 Use one fixed build for several ordinary development sessions. The owner will
 invite two or three willing testers and approve their projects; nothing is
@@ -35,7 +35,7 @@ are **NOT RUN**. The recording shortcut is macOS/direct-recipe only.
 For a new default npm installation:
 
 ```sh
-npm install --global @redue/cli@0.1.0-alpha.15
+npm install --global @redue/cli@0.1.0-alpha.16
 redue --version
 cd my-project
 redue --config redue.config.json init --recipe typescript-direct --check typecheck --dry-run
@@ -89,7 +89,7 @@ using it; keep the same npm prefix, config and any explicit state selection.
 
 ```sh
 redue --config redue.config.json stop
-npm install --global @redue/cli@0.1.0-alpha.15
+npm install --global @redue/cli@0.1.0-alpha.16
 redue --config redue.config.json agent setup codex --dry-run
 redue --config redue.config.json agent setup codex --apply
 redue --config redue.config.json start

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.16",
   "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 {hookCommand,hookForms,redueFor} from './claude-hook.mjs';
+import {fanoutRules,hookCommand,hookForms,redueFor} 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'},
@@ -23,10 +23,16 @@ const settingsPath='.claude/settings.local.json';
 const sameJson=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
 // One handler per exact command form; `if` keeps other Bash calls from starting Node.
 // The hook waits for status up to 10 s; 15 s leaves room for starting Node.
-function hookFor(config,relative){
-  const rules=[...new Set(hookForms(config,relative).flatMap(row=>row.forms))].map(form=>`Bash(${form}*)`);
+// 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){
+  const rules=[...new Set([...hookForms(config,relative).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;
 }
+// The same command on SessionStart starts the observer; it needs no check to match.
+const sessionHook={hooks:[{type:'command',command:hookCommand,timeout:10}]};
+const events=['PreToolUse','SessionStart'];
 // 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);
@@ -35,23 +41,28 @@ function parseSettings(text){
   let value;try{value=JSON.parse(text);}catch{throw Error(`${settingsPath} is not valid JSON; fix it before agent setup or removal`);}
   if(!value||typeof value!=='object'||Array.isArray(value)||value.hooks!==undefined&&
     (!value.hooks||typeof value.hooks!=='object'||Array.isArray(value.hooks)||
-      value.hooks.PreToolUse!==undefined&&!Array.isArray(value.hooks.PreToolUse)))
+      events.some(event=>value.hooks[event]!==undefined&&!Array.isArray(value.hooks[event]))))
     throw Error(`${settingsPath} has an unexpected shape; fix it before agent setup or removal`);
   return value;
 }
-// Replace REDUE's entries with `next` (or remove them). Unchanged input returns
-// the same text, so idempotent setup does not rewrite the file.
+// Replace REDUE's entry for each event with next[event] (or remove it; a null
+// `next` removes them all). Unchanged input returns the same text, so
+// idempotent setup does not rewrite the file.
 function settingsWith(text,next){
-  const value=parseSettings(text),old=value.hooks?.PreToolUse||[];
-  const at=old.findIndex(ownedHook),list=old.filter(entry=>!ownedHook(entry));
-  if(next)list.splice(at<0?list.length:at,0,next);
-  if(sameJson(list,old))return text;
-  if(list.length)value.hooks={...value.hooks,PreToolUse:list};
-  else if(value.hooks){delete value.hooks.PreToolUse;if(!Object.keys(value.hooks).length)delete value.hooks;}
+  const value=parseSettings(text);let changed=false;
+  for(const event of events){
+    const old=value.hooks?.[event]||[],at=old.findIndex(ownedHook),list=old.filter(entry=>!ownedHook(entry));
+    if(next?.[event])list.splice(at<0?list.length:at,0,next[event]);
+    if(sameJson(list,old))continue;
+    changed=true;
+    if(list.length)value.hooks={...value.hooks,[event]:list};
+    else if(value.hooks){delete value.hooks[event];if(!Object.keys(value.hooks).length)delete value.hooks;}
+  }
+  if(!changed)return text;
   return Object.keys(value).length?JSON.stringify(value,null,2)+'\n':null;
 }
-function hookInstalled(root){
-  try{return (parseSettings(read(root,settingsPath)).hooks?.PreToolUse||[]).some(ownedHook);}
+function hookInstalled(root,event='PreToolUse'){
+  try{return (parseSettings(read(root,settingsPath)).hooks?.[event]||[]).some(ownedHook);}
   catch{return false;}
 }
 function safeFile(root,relative){
@@ -121,10 +132,10 @@ function earlierBlock(host,rows=[]){
     `If a check's last pass still applies to these exact files, a REDUE hook skips\n`+
     `the run and says so. The skip counts as a pass; don't check it again.\n`);
 }
-// One form per check: the npm script when there is one, since that is what
-// the project's own instructions usually name.
+// One form per check: the package manager's script form when there is one,
+// since that is what the project's own instructions usually name.
 const blockForms=(host,config,relative)=>host!=='claude'?[]:hookForms(config,relative).map(row=>({kind:row.kind,
-  form:row.forms.find(form=>form.startsWith('npm run '))??row.forms.find(form=>!form.startsWith('redue '))??row.forms[0]}));
+  form:row.forms.find(form=>/^(?:npm run|pnpm|yarn) /.test(form))??row.forms.find(form=>!form.startsWith('redue '))??row.forms[0]}));
 const priorBlocks=(host,relative)=>[false,true].map(legacy=>`\n\n<!-- REDUE:${host}:begin -->\n`+
   `Before deciding whether configured verification needs repeating, use REDUE.\n`+
   (legacy?`Read ${hosts[host].skill} for the decision policy, then query ordinary status\n`+
@@ -143,7 +154,7 @@ const priorBlocks=(host,relative)=>[false,true].map(legacy=>`\n\n<!-- REDUE:${ho
 // varies, and only in the safe character set. Earlier owned versions are
 // recognized so setup can replace them; other stored text never is.
 function knownBlock(host,relative,block){
-  const list='((?:`[A-Za-z0-9_./:=,+ -]+`(?: and )?)+)';
+  const list='((?:`[A-Za-z0-9_./:=,+@ -]+`(?: and )?)+)';
   const forms=pattern=>{const named=new RegExp(pattern).exec(block);return named?[...named[1].matchAll(/`([^`]+)`/g)].map(m=>m[1]):[];};
   const rows=[...forms(`^\\n\\n<!-- REDUE:[a-z]+:begin -->\\nTypecheck with ${list}\\.`).map(form=>({kind:'typecheck',form})),
     ...forms(`Run the unit tests with ${list}\\.\\n`).map(form=>({kind:'test',form}))];
@@ -245,7 +256,7 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
       if(value.state_access)console.log(`State access: ${value.state_access.status}${value.state_access.reason?' — '+value.state_access.reason:''}`);
       if(value.compatibility?.reason)console.log(`Observer compatibility: ${value.compatibility.reason}`);
       if(value.applicability?.requires_reassessment)console.log('Applicability: cached evidence needs reassessment; choose synchronization or execution deliberately.');
-      for(const row of value.hosts)console.log(`${row.host}: ${row.version||'host unavailable'}; integration ${row.integrity}; hook ${row.hook}; behavioral validation NOT VERIFIED by doctor${row.reason?' — '+row.reason:''}`);
+      for(const row of value.hosts)console.log(`${row.host}: ${row.version||'host unavailable'}; integration ${row.integrity}; hook ${row.hook}${row.host==='claude'?`; session start ${row.session_start}`:''}; behavioral validation NOT VERIFIED by doctor${row.reason?' — '+row.reason:''}`);
       console.log('Doctor does not start observers, execute checks, or prove agent behavior.');
       for(const warning of value.warnings)console.log(`Review: ${warning}`);
     }return value;
@@ -261,14 +272,16 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
     if(!record&&(before?.includes('<!-- REDUE:')||read(root,h.skill)!==null))
       throw Error('unowned REDUE instruction or skill already exists; inspect it before setup');
     const after=record?before.replace(record.block,block):(before||'')+block;
-    hook=host==='claude'?hookFor(config,relative):null;
+    let scripts={};try{scripts=JSON.parse(read(root,'package.json')??'{}').scripts||{};}catch{}
+    hook=host==='claude'?hookFor(config,relative,scripts):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},
       {path:h.instruction,before,after});
-    if(host==='claude'){const settings=read(root,settingsPath);
-      changes.push({path:settingsPath,before:settings,after:settingsWith(settings,hook),
-        content:hook?JSON.stringify(hook,null,2):'remove the REDUE PreToolUse hook (no typecheck or test check to match)'});}
+    if(host==='claude'){const settings=read(root,settingsPath),next={PreToolUse:hook,SessionStart:sessionHook};
+      changes.push({path:settingsPath,before:settings,after:settingsWith(settings,next),
+        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,'');
@@ -282,7 +295,7 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
   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',
       ...(action==='setup'?{content:c.path===h.instruction?block:c.content??c.after}: {})})),
-    warnings:notes,hooks:hook?`${settingsPath} PreToolUse`:'none',behavior_verified:false};
+    warnings:notes,hooks:host!=='claude'||action!=='setup'?'none':`${settingsPath} ${hook?'PreToolUse, ':''}SessionStart`,behavior_verified:false};
   if(!json){console.log(`${action} ${host}: ${configFile}`);
     for(const c of summary.changes)console.log(`  ${c.operation} ${c.path}${c.content?'\n'+c.content:''}`);
     if(!actual.length)console.log('Already in the requested state.');
@@ -302,7 +315,7 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
 export async function doctor({configFile,stateOverride,entry,cwd,host}){
   const value={schema:1,command:{path:findExecutable('redue'),invoked:entry},project:{config:configFile},
     observation:null,control:null,state_access:null,observer_process:null,compatibility:null,
-    applicability:null,hosts:[],warnings:[],hooks:`claude only: PreToolUse typecheck hook in ${settingsPath}`,behavior_verified:false};
+    applicability:null,hosts:[],warnings:[],hooks:`claude only: PreToolUse check hook and SessionStart observer start in ${settingsPath}`,behavior_verified:false};
   let p;try{p=project(configFile);value.project.root=p.root;
     const state=stateOverride||projectState(p.root,configFile);value.project.state=state;
     const cached=readCachedStatus(state,p.config.checks);value.observation=cached.observation;
@@ -333,12 +346,14 @@ export async function doctor({configFile,stateOverride,entry,cwd,host}){
     if(executable){const launch=windowsLaunch([executable,'--version']);
       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';
+    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';
     if(p)try{const record=saved(p.root,name);integration=inspect(p.root,name,record);
-      if(name==='claude'&&hookInstalled(p.root))hook=value.command.path?'installed':'installed, but redue is not on PATH, so it never runs';
+      if(name==='claude'&&hookInstalled(p.root))hook=installed();
+      if(name==='claude'&&hookInstalled(p.root,'SessionStart'))sessionHook=installed();
       value.warnings.push(...warnings(p.root,name,cwd));
     }catch(e){integration={installed:false,integrity:'conflict',reason:e.message};}
-    value.hosts.push({host:name,executable,version,...integration,hook,behavior_verified:false,
+    value.hosts.push({host:name,executable,version,...integration,hook,session_start:sessionHook,behavior_verified:false,
       loading:name==='codex'?'AGENTS.md at session start; .agents/skills; overrides and size limits apply':
         'CLAUDE.md at session start; .claude/skills; managed/user policies and exclusions apply'});
   }

package/src/claude-hook.mjs

@@ -2,15 +2,18 @@
 // reports CURRENT/PASS with reuse_eligible on the current inputs. When the check is not
 // CURRENT, the command becomes `redue run <check>` so the run is recorded. Every
 // other outcome, including errors and timeouts, allows the command unchanged.
+// The same command handles SessionStart: it starts the project's observer.
 // 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 {projectState} from './project-location.mjs';
-import {realObservedPath,samePath} from './path-identity.mjs';
+import {realObservedPath} from './path-identity.mjs';
+import {processAlive} from './process-liveness.mjs';
 
 export const hookCommand='redue agent hook claude';
-const safe=/^[A-Za-z0-9_./:=,+-]+$/;
+// No shell metacharacters; `@` starts scoped package names.
+const safe=/^[A-Za-z0-9_./:=,+@-]+$/;
 const typecheck=check=>check?.kind==='typecheck'||check?.name==='typecheck';
 // A direct test check: its command is the runner and the script's arguments.
 const tests=check=>check?.qualification==='npm-tests-direct-v1'&&Array.isArray(check.command)&&
@@ -22,32 +25,155 @@ 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;
+
+// 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',
+  'i','import','init','install','link','list','ln','ls','outdated','pack','patch','prune','publish','rebuild','recursive',
+  'remove','rm','root','run','self-update','server','setup','store','uninstall','unlink','up','update','why','x']),
+  // Yarn 4 and Yarn 1 together.
+  yarn:new Set(['access','add','audit','autoclean','bin','cache','check','config','constraints','create','dedupe','dir','dlx',
+  'exec','explain','generate-lock-entry','global','help','import','info','init','install','licenses','link','list','login',
+  'logout','node','npm','outdated','owner','pack','patch','plugin','policies','publish','rebuild','remove','run','set',
+  'stage','tag','team','unlink','unplug','up','upgrade','upgrade-interactive','version','versions','why','workspace','workspaces'])};
+// A package script run by the project's package manager, in the package's directory.
+function scriptForms(pm,script){
+  if(typeof script!=='string'||!safe.test(script))return [];
+  if(pm==='npm')return [`npm run ${script}`,...(script==='test'?['npm test']:[])];
+  if(pm==='pnpm'||pm==='yarn')return [...(builtins[pm].has(script)?[]:[`${pm} ${script}`]),`${pm} run ${script}`];
+  return [];
+}
+// A workspace package's script, run from the project root.
+function workspaceForms(pm,name,script){
+  if(typeof name!=='string'||!safe.test(name)||typeof script!=='string'||!safe.test(script))return [];
+  if(pm==='pnpm')return ['--filter ','--filter=','-F '].flatMap(flag=>
+    [...(builtins.pnpm.has(script)?[]:[`pnpm ${flag}${name} ${script}`]),`pnpm ${flag}${name} run ${script}`]);
+  if(pm==='yarn')return [...(builtins.yarn.has(script)?[]:[`yarn workspace ${name} ${script}`]),`yarn workspace ${name} run ${script}`];
+  if(pm==='npm')return [`npm run ${script} -w ${name}`,`npm run ${script} --workspace ${name}`,
+    `npm run ${script} --workspace=${name}`,`npm -w ${name} run ${script}`];
+  return [];
+}
+// The tool a check runs, as typed: `tsc ARGS` or the test runner's command.
+function toolText(check){
+  const command=check.command;
+  if(!Array.isArray(command)||command[0]!=='@node')return null;
+  const words=/^@typescript-(?:compiler|bin):/.test(command[1]||'')?['tsc',...command.slice(2)]:
+    tests(check)?[command[1].slice('@test-runner:'.length),...command.slice(2)]:null;
+  return words?.every(word=>typeof word==='string'&&safe.test(word))?words.join(' '):null;
+}
+// A bare `tsc` is rarely on PATH; a test runner's own text is what the script says.
+const toolForms=(pm,text)=>!text?[]:[...(/^tsc(?: |$)/.test(text)?[]:[text]),`npx ${text}`,...(pm==='pnpm'?[`pnpm exec ${text}`]:[])];
+// A workspace check's package: its `workspace`, or the package its generated
+// `npm run S --workspace W`, `yarn workspace W run S` or `pnpm --filter W run S`
+// command names; null for any other check.
+function workspaceName(check){
+  if(typeof check.workspace==='string')return check.workspace;
+  const command=check.command,flag={'@which:npm':'--workspace','@which:yarn':'workspace','@which:pnpm':'--filter'}[command?.[0]];
+  const at=flag&&Array.isArray(command)?command.indexOf(flag):-1;
+  return at>0&&typeof command[at+1]==='string'?command[at+1]:null;
+}
+// Where a check runs: '.' for a root check, the package directory for a
+// workspace check, or null. A workspace check's directory is its `cwd`, or the
+// one directory its inputs name as `DIR/package.json` or `DIR/**` with
+// `!DIR/node_modules/**`, as init writes them.
+export function checkDir(check){
+  if(!workspaceName(check))return check.cwd===undefined||check.cwd==='.'?'.':null;
+  if(typeof check.cwd==='string'&&check.cwd!=='.')return check.cwd;
+  const inputs=(check.inputs||[]).filter(value=>typeof value==='string');
+  const dirs=new Set(inputs.flatMap(value=>{
+    const manifest=/^([^!*]+)\/package\.json$/.exec(value)?.[1],tree=/^([^!*]+)\/\*\*$/.exec(value)?.[1];
+    return manifest?[manifest]:tree&&inputs.includes(`!${tree}/node_modules/**`)?[tree]:[];
+  }));
+  return dirs.size===1?[...dirs][0]:null;
+}
+// The package script a check runs: its `script`, or the last word of a
+// generated `pnpm --filter NAME run SCRIPT`-style command.
+const checkScript=check=>typeof check.script==='string'?check.script:
+  Array.isArray(check.command)&&/^@which:(?:npm|pnpm|yarn)$/.test(check.command[0])&&check.command.includes('run')?
+    check.command[check.command.indexOf('run')+1]:null;
+
 // Exact commands that rerun each configured typecheck or direct test check.
-// Names that would need shell quoting get no form, so the hook never fires for them.
+// `forms` work from the project root; `local` ones work in the check's own
+// directory `dir`, after a `cd` into it. Names that would need shell quoting
+// get no form, so the hook never fires for them.
 export function hookForms(config,configFile=defaultConfig){
-  const rows=[],redue=redueFor(configFile);
+  const rows=[],redue=redueFor(configFile),pm=config?.packageManager;
   for(const check of config?.checks||[]){
     if(!(typecheck(check)||tests(check))||typeof check.name!=='string'||!safe.test(check.name))continue;
-    const forms=redue?[`${redue} run ${check.name}`]:[];
-    // Other forms run from the project root, so they match only a root check.
-    if(check.cwd!==undefined&&check.cwd!=='.'){if(forms.length)rows.push({check:check.name,forms});continue;}
-    if(config.packageManager==='npm'&&typeof check.script==='string'&&safe.test(check.script))
-      forms.push(`npm run ${check.script}`);
-    if(check.qualification==='npm-typescript-direct-v1')forms.push('npx tsc --noEmit');
-    if(!tests(check)&&Array.isArray(check.command)&&check.command.length&&
-      check.command.every(v=>typeof v==='string'&&safe.test(v)&&!v.startsWith('@')))
-      forms.push(check.command.join(' '));
-    // The script's own text, which runs the same runner with the same arguments.
-    if(tests(check)){
-      if(check.script==='test'&&config.packageManager==='npm')forms.push('npm test');
-      const text=[check.command[1].slice('@test-runner:'.length),...check.command.slice(2)];
-      if(text.every(v=>typeof v==='string'&&safe.test(v)))forms.push(text.join(' '),`npx ${text.join(' ')}`);
+    const forms=redue?[`${redue} run ${check.name}`]:[],local=[],dir=checkDir(check),script=checkScript(check);
+    if(dir==='.'){
+      forms.push(...scriptForms(pm,script),...toolForms(pm,toolText(check)));
+      if(!tests(check)&&Array.isArray(check.command)&&check.command.length&&
+        check.command.every(v=>typeof v==='string'&&safe.test(v)&&!v.startsWith('@')))
+        forms.push(check.command.join(' '));
+    }else if(dir!==null&&safe.test(dir)){
+      forms.push(...workspaceForms(pm,workspaceName(check),script));
+      local.push(...scriptForms(pm,script),...(check.cwd===dir?toolForms(pm,toolText(check)):[]));
     }
-    if(forms.length)rows.push({check:check.name,kind:checkKind(check),forms:[...new Set(forms)]});
+    if(forms.length||local.length)rows.push({check:check.name,kind:checkKind(check),dir,
+      forms:[...new Set(forms)],local:[...new Set(local)]});
   }
   return rows;
 }
 
+// A turbo or `pnpm -r` command that runs one task in every workspace package:
+// {tool, task}. No filters and no nx: both can add packages or tasks that only
+// a fuller model of the tool would see. `pnpm turbo` is left out because a root
+// script named turbo would run instead.
+const turboPrefix='(?:npx |pnpm exec )?',task='([A-Za-z0-9_:.-]+)';
+const fanouts=[['turbo',new RegExp(`^${turboPrefix}turbo(?: run)? ${task}$`)],
+  ['pnpm',new RegExp(`^pnpm (?:-r|--recursive)(?: run)? ${task}$`)]];
+export function fanout(text){
+  for(const [tool,pattern] of fanouts){const match=pattern.exec(text);
+    if(match)return {tool,task:match[1]};}
+  return null;
+}
+// Bash `if` rules for fan-out commands of a task some workspace check runs,
+// and for root scripts that run one; other turbo or nx commands never start the hook.
+export function fanoutRules(config,scripts={}){
+  const tasks=new Set((config?.checks||[]).filter(check=>(typecheck(check)||tests(check))&&typeof check.name==='string'&&
+    ![null,'.'].includes(checkDir(check))).map(checkScript).filter(task=>typeof task==='string'&&/^[A-Za-z0-9_:.-]+$/.test(task)));
+  const rules=[];
+  for(const task of tasks){
+    for(const prefix of ['','npx ','pnpm exec '])rules.push(`${prefix}turbo run ${task}`,`${prefix}turbo ${task}`);
+    if(config.packageManager==='pnpm')rules.push(`pnpm -r ${task}`,`pnpm -r run ${task}`,`pnpm --recursive ${task}`,`pnpm --recursive run ${task}`);
+  }
+  for(const [name,text] of Object.entries(scripts||{})){
+    const fan=typeof text==='string'&&!scripts['pre'+name]&&!scripts['post'+name]?fanout(text.trim()):null;
+    if(fan&&tasks.has(fan.task))rules.push(...scriptForms(config.packageManager,name));
+  }
+  return rules;
+}
+// The checks a fan-out runs: one configured check for every workspace package
+// with the task's script, or null when any package has none, or when the
+// tool may run more: another task first (turbo `dependsOn` other than ^TASK,
+// `with`, package-scoped keys, package turbo.json), a task turbo does not
+// define, or pnpm's workspace root.
+export async function fanoutChecks(fan,config,projectRoot){
+  const {workspacePackages}=await import('./node-onboarding.mjs');
+  const packages=workspacePackages(projectRoot).filter(item=>typeof item.scripts[fan.task]==='string');
+  if(!packages.length)return null;
+  const text=file=>{try{return fs.readFileSync(path.join(projectRoot,file),'utf8');}catch(e){return e.code==='ENOENT'?undefined:null;}};
+  if(fan.tool==='turbo'){
+    let tasks;try{const turbo=JSON.parse(text('turbo.json'));tasks=turbo?.tasks??turbo?.pipeline;}catch{return null;}
+    const own=tasks?.[fan.task];
+    if(!own||typeof own!=='object'||own.with!==undefined||
+      own.dependsOn!==undefined&&!(Array.isArray(own.dependsOn)&&own.dependsOn.every(item=>item===`^${fan.task}`))||
+      Object.keys(tasks).some(key=>key.endsWith(`#${fan.task}`))||
+      packages.some(item=>text(`${item.dir}/turbo.json`)!==undefined||text(`${item.dir}/turbo.jsonc`)!==undefined))return null;
+  }
+  if(fan.tool==='pnpm'&&(config.packageManager!=='pnpm'||
+    ['.npmrc','pnpm-workspace.yaml'].some(file=>{const value=text(file);return value===null||/include-?workspace-?root/i.test(value??'');})))
+    return null;
+  const names=[];
+  for(const item of packages){
+    const check=config.checks.find(c=>(typecheck(c)||tests(c))&&typeof c.name==='string'&&
+      workspaceName(c)===item.name&&checkScript(c)===fan.task&&checkDir(c)===item.dir);
+    if(!check)return null;
+    names.push(check.name);
+  }
+  return names;
+}
+
 // Accept only an optional trailing `2>&1`, then an optional `| tail|head -n N`
 // or `-N`, then optionally `;` or `&&` and the rest of the command. A form has
 // no shell metacharacters, so the first separator after it ends it. Newlines
@@ -59,11 +185,25 @@ function split(command){
   const one=text=>text.replace(/[ \t]+/g,' ');
   return {base:one(base),suffix:one(suffix),rest};
 }
-function matched(command,config,configFile){
-  const parts=split(command),check=parts&&hookForms(config,configFile).find(row=>row.forms.includes(parts.base))?.check;
+// {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={}){
+  const parts=split(command);
+  if(!parts)return null;
+  if(dir==='.'){
+    // A root script that runs a fan-out is that fan-out, unless pre/post scripts
+    // run around it: then it matches nothing.
+    for(const [name,text] of Object.entries(scripts||{}))
+      if(typeof text==='string'&&scriptForms(config.packageManager,name).includes(parts.base)&&fanout(text.trim()))
+        return scripts['pre'+name]||scripts['post'+name]?null:{fanout:fanout(text.trim()),rest:parts.rest};
+    if(fanout(parts.base))return {fanout:fanout(parts.base),rest:parts.rest};
+  }
+  const check=hookForms(config,configFile).find(row=>dir==='.'?row.forms.includes(parts.base):
+    row.dir===dir&&row.local.includes(parts.base))?.check;
   return check?{check,rest:parts.rest}:null;
 }
-export function matchCheck(command,config,configFile){return matched(command,config,configFile)?.check||null;}
+export function matchCheck(command,config,configFile,dir,scripts){return matched(command,config,configFile,dir,scripts)?.check||null;}
 // The same check through REDUE, keeping the output suffix; null if it already
 // is, or if more commands follow it.
 export function recordedCommand(command,name,configFile=defaultConfig){
@@ -73,21 +213,30 @@ export function recordedCommand(command,name,configFile=defaultConfig){
   return parts.base===run?null:run+parts.suffix;
 }
 
-// A leading `cd DIR;` or `cd DIR &&` into the project root, which agents
-// often add before a check: {prefix, command} with the rest of the command,
-// the whole command when there is no such prefix, or null when it enters
-// another directory. DIR may be quoted; it may not use variables, a leading
+// A leading `cd DIR;` or `cd DIR &&`, which agents often add before a check:
+// {prefix, command, dir} with the rest of the command and DIR relative to the
+// project root ('.' for the root or no prefix), or null when DIR is outside
+// the project or missing. DIR may be quoted; it may not use variables, a leading
 // `~` or escapes. Inside double quotes a backslash before anything but
 // $ ` " \ is literal, so a quoted Windows path matches; unquoted it is an escape.
 const cdPrefix=/^[ \t]*cd[ \t]+(?:"((?:[^"$`\\]|\\(?![$`"\\\n]))*)"|'([^']*)'|((?!~)[^\s;&|'"$`\\]+))[ \t]*(?:;|&&)[ \t]*/;
-export function rootCd(command,cwd,projectRoot){
+export function enteredDir(command,cwd,projectRoot){
   const prefix=typeof command==='string'?cdPrefix.exec(command):null;
-  if(!prefix)return {prefix:'',command};
-  const dir=prefix[1]??prefix[2]??prefix[3];
-  try{if(!samePath(realObservedPath(path.resolve(cwd,dir)),projectRoot))return null;}catch{return null;}
-  return {prefix:prefix[0],command:command.slice(prefix[0].length)};
+  if(!prefix)return {prefix:'',command,dir:'.'};
+  let relative;
+  try{relative=path.relative(projectRoot,realObservedPath(path.resolve(cwd,prefix[1]??prefix[2]??prefix[3])));}catch{return null;}
+  if(relative.split(path.sep)[0]==='..'||path.isAbsolute(relative))return null;
+  return {prefix:prefix[0],command:command.slice(prefix[0].length),dir:relative?relative.split(path.sep).join('/'):'.'};
 }
 
+// The fan-out's skip message when every check it runs is CURRENT/PASS, else null.
+export function fanoutVerdict(status,names,rest=null){
+  if(!names.length||!names.every(name=>verdict(status,name)))return null;
+  return `REDUE: all ${names.length} checks this command runs (${names.join(', ')}) passed on these exact inputs; `+
+    'rerun skipped. This counts as a pass for the current files; no status check is needed. '+
+    'To run it anyway, prefix the command with REDUE_FORCE=1.'+
+    (rest===null?'':` Nothing else in the command ran either; run the rest on its own: ${rest}`);
+}
 export function verdict(status,name,rest=null){
   const row=status?.schema===1&&status.observation?.healthy===true&&Array.isArray(status.checks)?
     status.checks.find(item=>item?.name===name):null;
@@ -134,20 +283,56 @@ export function lastRunTimeout(config,parsed,name){
   catch{return 2000;}
 }
 
-// Returns the hook's stdout object, or null to allow the command.
-export async function claudeHook(input,{entry,timeout}){
-  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;
+// The project set up in the session's directory: its setup record, the config
+// beside it and the project root. null when there is none; throws on bad files.
+function hookProject(root){
   if(typeof root!=='string'||!path.isAbsolute(root))return null;
   const record=JSON.parse(fs.readFileSync(path.join(root,'.redue','agents','claude.json'),'utf8'));
   if(record?.schema!==1||record.host!=='claude'||typeof record.config!=='string'||
     !/^[^/\\]+\.json$/.test(record.config))return null;
   const config=path.join(root,record.config);
   const parsed=JSON.parse(fs.readFileSync(config,'utf8'));
-  const entered=rootCd(command,root,realObservedPath(path.resolve(path.dirname(config),parsed.root||'.')));
-  const match=entered&&matched(entered.command,parsed,record.config);
+  return {record,config,parsed,projectRoot:realObservedPath(path.resolve(path.dirname(config),parsed.root||'.'))};
+}
+
+// SessionStart: start the observer when none is running, so the session's
+// checks can be skipped or recorded without a manual `redue start`. It
+// launches `redue start` detached and returns at once, and prints nothing:
+// SessionStart output becomes agent context. Returns what it did.
+export function sessionStart(input,{entry}){
+  const project=hookProject(input?.cwd);
+  if(!project)return null;
+  try{const pid=Number(fs.readFileSync(path.join(projectState(project.projectRoot,project.config),'observer.lock','pid'),'utf8'));
+    if(Number.isSafeInteger(pid)&&pid>0&&processAlive(pid))return 'running';}catch{}
+  const child=spawn(process.execPath,[entry,'--config',project.config,'start'],
+    {cwd:input.cwd,detached:true,stdio:'ignore',windowsHide:true,env:process.env});
+  child.on('error',()=>{});child.unref();
+  return 'started';
+}
+
+// Returns the hook's stdout object, or null to allow the command.
+export async function claudeHook(input,{entry,timeout}){
+  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;
+  const project=hookProject(root);
+  if(!project)return null;
+  const {record,config,parsed}=project;
+  const entered=enteredDir(command,root,project.projectRoot);
+  if(!entered)return null;
+  let scripts={};
+  if(entered.dir==='.')try{scripts=JSON.parse(fs.readFileSync(path.join(project.projectRoot,'package.json'),'utf8')).scripts||{};}catch{}
+  const match=matched(entered.command,parsed,record.config,entered.dir,scripts);
   if(!match)return null;
+  // turbo, nx and `pnpm -r` cache their own results: skip only when every
+  // check the command runs is CURRENT, and otherwise leave it alone.
+  if(match.fanout){
+    const names=await fanoutChecks(match.fanout,parsed,project.projectRoot);
+    if(!names)return null;
+    const status=await synchronizedStatus(entry,config,root,timeout??Math.max(...names.map(name=>lastRunTimeout(config,parsed,name)))),
+      reason=fanoutVerdict(status,names,match.rest);
+    return reason?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'deny',permissionDecisionReason:reason}}:null;
+  }
   const name=match.check,status=await synchronizedStatus(entry,config,root,timeout??lastRunTimeout(config,parsed,name)),
     reason=verdict(status,name,match.rest);
   if(reason)return {hookSpecificOutput:{hookEventName:'PreToolUse',
@@ -157,7 +342,9 @@ 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,record.config):null;
+    status.checks.some(item=>item?.name===name)?recordedCommand(entered.command,name,
+      // Both sides resolved alike: Windows can spell the same directory RUNNER~1 or by its long name.
+      !entered.prefix?record.config:path.relative(path.join(project.projectRoot,entered.dir),realObservedPath(config)).split(path.sep).join('/')):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',
@@ -169,7 +356,9 @@ export async function runClaudeHook(entry){
   try{
     let text='';process.stdin.setEncoding('utf8');
     for await(const chunk of process.stdin){text+=chunk;if(text.length>1024*1024)return;}
-    const output=await claudeHook(JSON.parse(text),{entry});
+    const input=JSON.parse(text);
+    if(input?.hook_event_name==='SessionStart'){sessionStart(input,{entry});return;}
+    const output=await claudeHook(input,{entry});
     if(output)await new Promise(resolve=>process.stdout.write(JSON.stringify(output)+'\n',resolve));
   }catch{}
 }

package/src/node-onboarding.mjs

@@ -161,6 +161,15 @@ function workspaceManifests(root,patterns) {
   if(matched.length>50)throw Error('more than 50 workspace packages found; select checks explicitly');
   return matched.map(file=>({file,pkg:readJson(path.join(root,file))}));
 }
+// Workspace packages as init finds them, with their scripts; [] without workspaces.
+export function workspacePackages(root){
+  root=realObservedPath(root);
+  const pkg=readJson(path.join(root,'package.json')),pm=manager(root,pkg);
+  const patterns=pm.name==='pnpm'?pm.workspacePatterns:Array.isArray(pkg.workspaces)?pkg.workspaces:pkg.workspaces?.packages;
+  if(!Array.isArray(patterns)||!patterns.length)return [];
+  return workspaceManifests(root,patterns).map(({file,pkg:member})=>
+    ({name:member.name,dir:path.posix.dirname(file),scripts:member.scripts&&typeof member.scripts==='object'?member.scripts:{}}));
+}
 export function discoverNodeProject(root,{recipe=null}={}) {
   if(recipe&&!['typescript-direct','tests-direct'].includes(recipe))throw Error('unknown recipe; use typescript-direct or tests-direct');
   root=realObservedPath(root);