open-tui-orchestrator 0.9.6

package/scripts/core/run-guardian.mjs

@@ -0,0 +1,130 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {atomicJson,processSnapshot,sameProcess} from './leases.mjs';
+import {runDirectory} from './runner.mjs';
+import {resolveRuntimeContext} from './runtime-context.mjs';
+
+// Run guardian: a tiny detached process that outlives the engine. It watches the
+// engine process plus summary.json; when the engine dies abnormally (process gone
+// but the run never finalized) it relaunches `--resume-run <runId>` so surviving
+// windows are adopted and remaining tasks continue — no user re-invocation needed.
+// Fail-closed: a bounded restart budget, a run deadline, and snapshot failures all
+// stop respawning instead of risking a duplicate or endless controller loop.
+
+const ENTRY=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..','orchestrate-sdk.mjs');
+
+export function guardianFile(workspace,runId){return path.join(runDirectory(workspace,runId),'guardian.json');}
+
+export function readGuardianState(file){try{return JSON.parse(fs.readFileSync(file,'utf8'));}catch{return null;}}
+
+function validState(state,runId){
+  return !!state&&state.runId===runId&&Number.isSafeInteger(state.restarts)&&state.restarts>=0
+    &&Number.isSafeInteger(state.maxRestarts)&&Number.isSafeInteger(state.timeoutMs)&&state.timeoutMs>=60000
+    &&Number.isSafeInteger(state.createdAt)&&Array.isArray(state.engines)&&state.engines.length
+    &&state.engines.every(e=>e?.owner&&Number.isSafeInteger(Number(e.owner.ProcessId)));
+}
+
+// Spawn (or adopt) the guardian for a fresh run. Called by the engine once the
+// run ledger exists; guardian failure must never break the run itself.
+export function ensureRunGuardian({runId,workspace,timeoutMs,owner,agent,env=process.env,spawnImpl=spawn,snapshotImpl=processSnapshot,log=console.log}={}) {
+  if(env.ORCH_GUARDIAN==='0'||env.NODE_TEST_CONTEXT)return {disabled:true};
+  const dir=runDirectory(workspace,runId),file=guardianFile(workspace,runId);
+  const prev=readGuardianState(file);
+  if(prev&&Number.isSafeInteger(Number(prev.guardianPid))&&Number(prev.guardianPid)>0) {
+    try {
+      const p=snapshotImpl().get(Number(prev.guardianPid));
+      if(p&&/run-guardian\.mjs/i.test(String(p.CommandLine||''))&&String(p.CommandLine).includes(runId))return {already:true,pid:Number(prev.guardianPid)};
+    }catch{ /* snapshot unavailable: fall through and replace the suspect guardian */ }
+  }
+  const state={
+    runId,guardianPid:0,restarts:prev?.restarts||0,
+    maxRestarts:Math.max(0,Math.min(10,Number(env.ORCH_GUARDIAN_MAX_RESTARTS)||3)),
+    intervalMs:Math.max(500,Math.min(10000,Number(env.ORCH_GUARDIAN_INTERVAL_MS)||2000)),
+    timeoutMs:Math.max(60000,Number(timeoutMs)||21600000),
+    createdAt:prev?.createdAt||Date.now(),
+    engines:[...(Array.isArray(prev?.engines)?prev.engines:[]),{owner,startedAt:Date.now(),by:'initiator'}],
+    status:'watching',updatedAt:Date.now(),
+  };
+  atomicJson(file,state);
+  const out=fs.openSync(path.join(dir,'guardian.log'),'a');
+  const child=spawnImpl(process.execPath,[path.join(path.dirname(fileURLToPath(import.meta.url)),'run-guardian.mjs'),'--run-id',runId],
+    {cwd:workspace,env:{...env,ORCH_AGENT:agent,ORCH_RUN_ID:runId,WORKSPACE_DIR:workspace},detached:true,windowsHide:true,stdio:['ignore',out,out]});
+  fs.closeSync(out);
+  child.on?.('error',()=>{});child.unref?.();
+  state.guardianPid=Number(child?.pid)||0;state.updatedAt=Date.now();atomicJson(file,state);
+  log('[guardian] watching runId='+runId+' pid='+state.guardianPid);
+  return {spawned:true,pid:state.guardianPid};
+}
+
+export function parseGuardianOptions(argv) {
+  const result={};
+  for(let i=0;i<argv.length;i++) {
+    if(argv[i]==='--run-id') {
+      const value=argv[++i];
+      if(!value||value.startsWith('--'))throw new Error('GUARDIAN_ARGUMENT_INVALID: --run-id is required');
+      result.runId=value;
+    } else throw new Error('GUARDIAN_ARGUMENT_INVALID: '+argv[i]);
+  }
+  if(!result.runId)throw new Error('GUARDIAN_ARGUMENT_INVALID: --run-id is required');
+  return result;
+}
+
+export async function main(argv=process.argv.slice(2),hooks={}) {
+  const {runId}=parseGuardianOptions(argv);
+  const env=hooks.env||process.env;
+  const {workspace}=resolveRuntimeContext(env);
+  const dir=runDirectory(workspace,runId),stateFile=guardianFile(workspace,runId);
+  const now=hooks.now||(()=>Date.now()),sleep=hooks.sleep||(ms=>new Promise(r=>setTimeout(r,ms)));
+  const snapshot=hooks.snapshot||processSnapshot,spawnImpl=hooks.spawn||spawn;
+  const log=hooks.log||(m=>{console.log(m);try{fs.appendFileSync(path.join(dir,'guardian.log'),m+'\n');}catch{}});
+  const load=hooks.load||(()=>{try{return JSON.parse(fs.readFileSync(path.join(dir,'summary.json'),'utf8'));}catch{return null;}});
+  const readState=hooks.readState||(()=>readGuardianState(stateFile));
+  const writeState=hooks.writeState||(s=>{s.updatedAt=Date.now();atomicJson(stateFile,s);});
+  // The engine writes the state file just before spawning us; tolerate a race.
+  let state=null;
+  for(let i=0;i<20&&!state;i++){state=readState();if(!state)await sleep(500);}
+  if(!validState(state,runId)){log('[guardian] missing or invalid state; exit');process.exitCode=2;return;}
+  const finish=(status,code)=>{state.status=status;writeState(state);log('[guardian] '+status+' runId='+runId+' restarts='+state.restarts);process.exitCode=code;};
+  let engine=state.engines.at(-1).owner;
+  const guardianDeadline=state.createdAt+state.timeoutMs+600000;
+  while(now()<guardianDeadline) {
+    const sum=load();
+    if(sum&&sum.finishedAt){finish('done',0);return;}
+    if(sum===null){finish('error',2);return;}
+    let snap=null;
+    try{snap=snapshot();}catch{/* identity unverifiable: never respawn blind */}
+    if(snap===null){await sleep(state.intervalMs);continue;}
+    if(sameProcess(engine,snap.get(Number(engine.ProcessId)))){await sleep(state.intervalMs);continue;}
+    // Engine is gone but the run is not finalized: abnormal interruption.
+    if(now()>state.createdAt+state.timeoutMs){finish('deadline',1);return;}
+    if(state.restarts>=state.maxRestarts){finish('exhausted',1);return;}
+    await sleep(Math.min(5000*2**state.restarts,30000));
+    const again=load();
+    if(again?.finishedAt){finish('done',0);return;}
+    if(again===null){finish('error',2);return;}
+    try{snap=snapshot();}catch{snap=null;}
+    if(snap&&sameProcess(engine,snap.get(Number(engine.ProcessId))))continue;
+    const number=state.restarts+1;
+    log('[guardian] engine lost (pid='+engine.ProcessId+'); resuming run '+runId+' (restart '+number+'/'+state.maxRestarts+')');
+    let outFd;
+    try{outFd=fs.openSync(path.join(dir,'resumed-engine-'+number+'.log'),'a');}catch{outFd='ignore';}
+    const child=spawnImpl(process.execPath,[ENTRY,'--resume-run',runId],{
+      cwd:workspace,
+      env:{...env,ORCH_AGENT:String(again.agent||'codex'),ORCH_RUN_ID:runId,WORKSPACE_DIR:workspace},
+      detached:true,windowsHide:true,stdio:['ignore',outFd,outFd],
+    });
+    if(outFd!=='ignore')try{fs.closeSync(outFd);}catch{}
+    child?.on?.('error',()=>{});child?.unref?.();
+    let identity=null;
+    if(child&&child.pid){try{identity=snapshot().get(Number(child.pid))||null;}catch{identity=null;}}
+    state.restarts++;
+    if(identity){state.engines.push({owner:identity,startedAt:Date.now(),by:'guardian'});engine=identity;}
+    writeState(state);
+    if(!identity){log('[guardian] resumed engine vanished immediately; will re-evaluate');await sleep(state.intervalMs);}
+  }
+  finish('deadline',1);
+}
+
+if(process.argv[1]&&path.resolve(process.argv[1]).toLowerCase()===fileURLToPath(import.meta.url).toLowerCase())main().catch(e=>{console.error('[guardian] FATAL: '+e.message);process.exitCode=2;});

package/scripts/core/runner.mjs

@@ -0,0 +1,274 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+import {CORE_VERSION,ledgerPlan,levelWaves,verifyChecks,summaryComplete,TERMINAL,canonicalKey,requestTasks,acceptanceKeyDiff} from './contracts.mjs';
+import {coordinatorDir,reserve,bind,release,prepare,atomicJson,launcherIdentity,processSnapshot,sameProcess,claimRun,releaseRun,waitBackoffMs} from './leases.mjs';
+import {scheduleReady,recoveryTasks,taskPolicy,validateRecoverySummary} from './recovery.mjs';
+import {readCheckpoints} from './checkpoint.mjs';
+import {boardSignature,boardJson,boardSummaryLine} from './run-board.mjs';
+// 队列退避参数（env 可调，测试提速用）：首等 base、指数 ×1.7、封顶 max（抖动上界 ×1.2）。
+const WAIT_BACKOFF={base:Math.max(50,Number(process.env.ORCH_WAIT_BACKOFF_MS||600)||600),max:0};
+WAIT_BACKOFF.max=Math.max(WAIT_BACKOFF.base,Number(process.env.ORCH_WAIT_BACKOFF_MAX_MS||5000)||5000);
+export {scheduleReady,recoveryTasks};
+const pause=ms=>new Promise(r=>setTimeout(r,ms));
+// Identity acquisition under load: a full-process snapshot can be slow or miss a
+// just-spawned launcher, and one unlucky read used to burn the whole attempt
+// budget as popup-failed ('Launcher process identity mismatch'). Retry within a
+// short grace window before giving up; transient snapshot failures are retried,
+// a persistent one still fails fast.
+export async function identityWithGrace(hooks,la,{graceMs=10000,intervalMs=800}={}) {
+  const end=Date.now()+graceMs;let identity=null,lastError=null;
+  while(true){
+    try{identity=launcherIdentity(hooks.readPid(la.pidf),la.pidf);}catch(error){lastError=error;}
+    if(identity)return identity;
+    if(Date.now()>=end)break;
+    await pause(intervalMs);
+  }
+  if(lastError)throw lastError;
+  return null;
+}
+export async function waitForProcessExit(expected,{timeoutMs=5000,intervalMs=100,snapshot=processSnapshot}={}) {
+  if(!expected||!Number.isFinite(Number(expected.ProcessId)))return true;
+  const timeout=Math.max(0,Math.min(15000,Number(timeoutMs)||0)),interval=Math.max(10,Math.min(1000,Number(intervalMs)||100));
+  const deadline=Date.now()+timeout;
+  while(true){
+    let current;
+    try{current=snapshot(Math.min(3000,Math.max(1,deadline-Date.now())));}catch{return false;}
+    if(!sameProcess(expected,current?.get(Number(expected.ProcessId))))return true;
+    if(Date.now()>=deadline)return false;
+    await pause(Math.min(interval,Math.max(1,deadline-Date.now())));
+  }
+}
+async function coordinate(fn,deadline) {
+  while(Date.now()<deadline){try{return fn();}catch(e){if(!/busy|initializing|abandoned/.test(e.message))throw e;await pause(200);}}
+  throw new Error('Coordinator transaction timeout');
+}
+export function runDirectory(workspace,runId) {
+  if(!/^[a-zA-Z0-9_-]{1,100}$/.test(runId||''))throw new Error('A valid --run-id is required');
+  return path.join(workspace,'temp','orchestrator','runs',runId);
+}
+function loadChecks(file){return file?JSON.parse(fs.readFileSync(file,'utf8')):{};}
+// 验收契约（含 command 类检查，会以控制器权限执行）在创建时锚定哈希：run 目录可被窗内 agent 写入，
+// resume/verify 回读前比对，篡改即拒绝——不让被改写的 acceptance.json 借恢复流程获得执行权。
+function checksHash(checks){return crypto.createHash('sha256').update(JSON.stringify(checks||{})).digest('hex');}
+function blockCheckpoints(entry,block,sum) {
+  const out={};
+  for(const a of entry?.attempts||[]) {
+    try{Object.assign(out,readCheckpoints(a.file,{...a,runId:sum.runId}));}catch{for(const id of a.taskIds)out[id]={state:'invalid'};}
+  }
+  // Preserve read-only verification of historical protocol-1 runs.
+  if(!entry?.attempts&&entry?.receiptFile) {
+    try{for(const r of JSON.parse(fs.readFileSync(entry.receiptFile,'utf8')).tasks||[]){if(block.taskIds.includes(r.id))out[r.id]=r.runId===sum.runId&&r.token===entry.token&&r.status==='completed'?{state:'completed'}:{state:'invalid'};}}catch{}
+  }
+  for(const id of block.taskIds) {
+    if(!out[id]&&sum.taskResults[id]?.checkpoint)out[id]=sum.taskResults[id].checkpoint;
+    if(!out[id]&&sum.taskResults[id]?.status==='verified')out[id]={state:'invalid'};
+  }
+  return out;
+}
+function blockStatus(ids,results) {
+  const statuses=ids.map(id=>results[id]?.status);
+  if(statuses.every(s=>s==='verified'))return 'verified';
+  if(statuses.includes('needs-reconciliation'))return 'needs-reconciliation';
+  if(statuses.includes('awaiting-verification'))return 'awaiting-verification';
+  return 'failed';
+}
+export function collectVerification(sum,checks,workspace) {
+  for(const b of sum.blocks) {
+    const e=sum.results[b.key];if(!e?.endedAt)continue;
+    if(['blocked','popup-failed','preflight-failed','cancelled'].includes(e.status)&&!e.attempts?.length)continue;
+    const cps=blockCheckpoints(e,b,sum);
+    for(const id of b.taskIds) {
+      const cp=cps[id];if(!cp){sum.taskResults[id]={status:'failed',reason:'No durable task checkpoint'};continue;}
+      if(cp.state==='invalid'){sum.taskResults[id]={status:'needs-reconciliation',reason:'Invalid checkpoint',checkpoint:cp};continue;}
+      const check=verifyChecks(taskPolicy(checks[id]).checks,workspace);
+      sum.taskResults[id]=check.status==='verified'?{...check,checkpoint:cp}:
+        cp.state==='started'?{status:'needs-reconciliation',reason:'Task started but result is unproven',verification:check,checkpoint:cp}:{...check,checkpoint:cp};
+    }
+    e.status=blockStatus(b.taskIds,sum.taskResults);
+  }
+  return sum;
+}
+export function verifyRun(workspace,runId,acceptanceFile) {
+  const dir=runDirectory(workspace,runId),file=path.join(dir,'summary.json');
+  // 机器可调用契约：未知 run 必须 fail-closed 且只回一行可读诊断（不许裸栈帧/ENOENT 甩路径）。
+  if(!fs.existsSync(file))throw new Error('Run not found: '+runId+' (no summary.json in '+dir+')');
+  const sum=JSON.parse(fs.readFileSync(file,'utf8'));
+  if(sum.runId!==runId||!sum.finishedAt)throw new Error('Run is not finalized');
+  if(sum.protocol===2)validateRecoverySummary(sum);
+  const checks=loadChecks(acceptanceFile||path.join(dir,'acceptance.json'));
+  if(sum.acceptanceSha256&&checksHash(checks)!==sum.acceptanceSha256)throw new Error('Acceptance contract changed since run creation; refusing to verify');
+  const claim=claimRun(sum.coordinator||coordinatorDir(workspace),'run:'+path.resolve(dir).toLowerCase());
+  try{
+    if(sum.tasks?.length){
+      const keyDiff=acceptanceKeyDiff(checks,sum.tasks);
+      if(keyDiff?.unknown.length)throw new Error('Acceptance keys do not match any task id: '+keyDiff.unknown.join(', ')+'（task ids: '+sum.tasks.map(t=>t.id).join(', ')+'）');
+      if(keyDiff?.missing.length)console.warn('[orchestrator] acceptance has no checks for task(s): '+keyDiff.missing.join(', ')+'；这些任务将停在 awaiting-verification');
+    }
+    collectVerification(sum,checks,workspace);sum.success=summaryComplete(sum,true);atomicJson(file,sum);return sum.success;
+  }  finally{releaseRun(sum.coordinator||coordinatorDir(workspace),'run:'+path.resolve(dir).toLowerCase(),claim);}
+}
+
+export async function runWindows(request,hooks,options={}) {
+  const workspace=path.resolve(options.workspace),capacity=options.capacity;
+  // options.windowCap (ORCH_MAX_WINDOWS) throttles live-window admission only;
+  // planning keeps the full memory-derived capacity so block shape is unchanged.
+  const windowCap=Math.max(1,Math.min(capacity,Number(options.windowCap)||capacity));
+  const runId=options.runId||crypto.randomUUID(),dir=runDirectory(workspace,runId),summaryFile=path.join(dir,'summary.json');
+  const deadline=Date.now()+(options.timeoutMs||21600000),coordinator=options.coordinator||coordinatorDir(workspace);
+  const runKey='run:'+dir.toLowerCase(),claim=await coordinate(()=>claimRun(coordinator,runKey),deadline);
+  let sum;
+  try {
+    let checks;
+    if(options.resume) {
+      if(!fs.existsSync(summaryFile))throw new Error('Run not found: '+runId+' (no summary.json in '+dir+')');
+      sum=JSON.parse(fs.readFileSync(summaryFile,'utf8'));
+      if(sum.protocol!==2||!Array.isArray(sum.plan))throw new Error('This run has no recoverable task checkpoints');
+      if((sum.agent||'codex')!==(options.agent||'codex'))throw new Error('Resume agent must match the saved run');
+      if(path.resolve(sum.workspace)!==workspace||sum.runId!==runId)throw new Error('Run workspace/identity mismatch');
+      validateRecoverySummary(sum);
+      // 调用方自助通道：保存的运行用了调用方单元命令时，resume 必须重供同一条命令（防换命令重放副作用）。
+      {const savedUnit=sum.unitProfile||null,givenUnit=options.unitProfile||null;
+       if(savedUnit&&!givenUnit)throw new Error('This run used a caller-supplied unit command; re-supply the identical --unit-cmd/--unit-cmd-file to resume');
+       if(savedUnit&&givenUnit&&JSON.stringify(savedUnit)!==JSON.stringify(givenUnit))throw new Error('Resume unit command differs from the saved run; refusing to resume');}
+      if(sum.blocks.length>capacity)throw new Error('Current memory capacity is below the saved block count');
+      checks=loadChecks(options.acceptanceFile||path.join(dir,'acceptance.json'));
+      if(sum.acceptanceSha256&&checksHash(checks)!==sum.acceptanceSha256)throw new Error('Acceptance contract changed since run creation; refusing to resume');
+      sum.history.push({generation:sum.generation,finishedAt:sum.finishedAt,success:sum.success});
+      sum.generation++;delete sum.finishedAt;sum.success=false;
+    }else {
+      if(fs.existsSync(dir))throw new Error('Run ID already exists; use --resume-run or --verify-run');
+      fs.mkdirSync(dir,{recursive:true});checks=loadChecks(options.acceptanceFile);
+      atomicJson(path.join(dir,'manifest.json'),{runId,workspace,request,tasks:requestTasks(request),startedAt:Date.now()});
+      // The CLI may have already performed the deterministic preflight needed to
+      // decide whether a visible window is warranted. Reuse that exact plan so
+      // the policy decision and the launched plan cannot diverge after a second
+      // model classification or cache lookup.
+      const candidate=options.plan||await hooks.plan(request,capacity);
+      const {plan,tasks}=ledgerPlan(request,candidate,capacity,hooks.compact);
+      const recs=plan.map((b,i)=>({key:`B${i+1}`,title:b.title,b,dependsOn:b.dependsOn||[],keys:[...new Set([...(b.conflictKeys||[]),...b.tasks.flatMap(t=>hooks.infer(t.prompt||''))].map(k=>canonicalKey(k,workspace)))]}));
+      levelWaves(recs);
+      sum={protocol:2,version:CORE_VERSION,agent:options.agent||'codex',runId,workspace,request,capacity,coordinator,generation:1,history:[],startedAt:Date.now(),tasks,plan:recs,spawnMode:options.spawnMode||'window',
+        model:options.modelPlan?.model??null,effort:options.modelPlan?.effort??null,modelSource:options.modelPlan?.modelSource??null,effortSource:options.modelPlan?.effortSource??null,
+        blocks:recs.map(r=>({key:r.key,title:r.title,taskIds:r.b.tasks.flatMap(t=>t.sourceIds)})),results:{},taskResults:{}};
+      for(const r of recs){sum.results[r.key]={status:'pending',attempts:[]};for(const id of sum.blocks.find(b=>b.key===r.key).taskIds)sum.taskResults[id]={status:'pending'};}
+      sum.acceptanceSha256=checksHash(checks);
+      if(options.unitProfile)sum.unitProfile=options.unitProfile;
+    }
+    sum.owner=claim.owner;sum.coordinator=coordinator;
+    {
+      const keyDiff=acceptanceKeyDiff(checks,sum.tasks);
+      if(keyDiff?.unknown.length)throw new Error('Acceptance keys do not match any task id: '+keyDiff.unknown.join(', ')+'（task ids: '+sum.tasks.map(t=>t.id).join(', ')+'）');
+      if(keyDiff?.missing.length)console.warn('[orchestrator] acceptance has no checks for task(s): '+keyDiff.missing.join(', ')+'；这些任务将停在 awaiting-verification');
+    }
+    atomicJson(path.join(dir,'acceptance.json'),checks);
+    const eventsFile=path.join(dir,'events.jsonl');
+    let lastBoardSig='';
+    const emitBoard=()=>{try{const sig=boardSignature(sum);if(sig===lastBoardSig)return;lastBoardSig=sig;fs.appendFileSync(eventsFile,JSON.stringify(boardJson(sum))+'\n');console.log(boardSummaryLine(sum));}catch{/* board is best-effort; never fail the run */}};
+    const persist=()=>{atomicJson(summaryFile,sum);emitBoard();};
+    const mark=(r,status,reason)=>{sum.results[r.key]={...sum.results[r.key],status,reason};for(const id of sum.blocks.find(b=>b.key===r.key).taskIds)if(sum.taskResults[id]?.status!=='verified')sum.taskResults[id]={...sum.taskResults[id],status,reason};persist();};
+    persist();console.log(`[run] runId=${runId} blocks=${sum.blocks.length} capacity=${capacity} generation=${sum.generation} summary=${summaryFile}`);
+    // Auto-recovery: a detached guardian watches this controller and relaunches
+    // --resume-run if it dies before finalizing. Fresh runs only — a resumed run
+    // is already watched by the original guardian. Never let the guard fail a run.
+    if(!options.resume&&hooks.guardian)try{hooks.guardian({runId,workspace,coordinator,timeoutMs:options.timeoutMs||21600000,owner:claim.owner,dir});}catch(e){console.warn('[guardian] unavailable: '+e.message);}
+    // Optional spawn pacing (options.spawnStaggerMs, from ORCH_WINDOW_STAGGER_MS):
+    // serializes window births within this run so a burst of first turns cannot
+    // trip the agent account's per-minute rate limiter. 0 keeps the burst as-is.
+    const staggerMs=Math.max(0,Number(options.spawnStaggerMs||0));
+    let staggerChain=Promise.resolve();
+    const stagger=()=>{const turn=staggerChain;staggerChain=staggerChain.then(()=>pause(staggerMs));return turn;};
+    async function execute(r) {
+      const b=sum.blocks.find(b=>b.key===r.key),tasks=b.taskIds.map(id=>sum.tasks.find(t=>t.id===id));
+      const leaseId=crypto.createHash('sha256').update(runKey).digest('hex').slice(0,16)+'-'+r.key;
+      let attemptsThisController=0,spawnConfirmed=false;
+      const limit=Math.max(1,Math.min(3,Number(options.maxAttempts||2)));
+      while(Date.now()<deadline) {
+        let e=sum.results[r.key],la=e.launcherFiles,identity;spawnConfirmed=false;
+        if(la)try{identity=launcherIdentity(hooks.readPid(la.pidf),la.pidf);}catch{identity=undefined;}
+        const adopted=identity&&(!e.launcher||sameProcess(e.launcher,identity));
+        let active;
+        if(adopted) {
+          active=e.attempts.at(-1);console.log(`[resume] adopting live ${r.key}; no duplicate window`);
+        }else {
+          const cps=blockCheckpoints(e,b,sum);
+          const recovery=recoveryTasks(tasks,cps,checks,workspace);
+          Object.assign(sum.taskResults,recovery.results);
+          if(recovery.verified.length===tasks.length){e.status='verified';e.endedAt=Date.now();persist();return;}
+          if(recovery.uncertain.length){e.status='needs-reconciliation';e.reason='Uncertain tasks: '+recovery.uncertain.join(', ');e.endedAt=Date.now();persist();return;}
+          if(attemptsThisController>=limit){mark(r,'failed','Safe recovery attempt budget exhausted');return;}
+          if(attemptsThisController)await pause(Math.min(2000*attemptsThisController,Math.max(0,deadline-Date.now())));
+          let reserved=false,waitAttempt=0;
+          while(Date.now()<deadline) {
+            const result=await coordinate(()=>reserve(coordinator,{id:leaseId,runId,keys:r.keys},windowCap),deadline);
+            if(result.ok){reserved=true;break;}
+            // 排队退避（指数+抖动）：不再每秒重试；等待状态仅在理由变化时重写，少刷账本。
+            const waitMsg='Waiting for '+result.reason,cur=sum.results[r.key];
+            if(!cur||cur.status!=='waiting'||cur.reason!==waitMsg)mark(r,'waiting',waitMsg);
+            await pause(Math.min(waitBackoffMs(waitAttempt++,WAIT_BACKOFF),Math.max(0,deadline-Date.now())));
+          }
+          if(!reserved){mark(r,'timeout','Window capacity/resource wait timed out');return;}
+          attemptsThisController++;
+          const number=e.attempts.length+1,token=runId+'-'+r.key+'-a'+number+'-'+crypto.randomBytes(6).toString('hex');
+          const attemptFile=path.join(dir,'attempts',r.key,String(number),'attempt.json');
+          active={file:attemptFile,runId,token,number,taskIds:recovery.pending,createdAt:Date.now()};
+          atomicJson(attemptFile,active);e.attempts.push(active);
+          const helper=fileURLToPath(new URL('./checkpoint.mjs',import.meta.url));
+          const command=(id,state)=>`node "${helper}" "${attemptFile}" ${id} ${state}`;
+          const body=options.auth+'\n本窗目录为 '+workspace+'；所有工具 workdir 保持此目录，除非原始任务明确另指定。\n'+
+            '仅按顺序执行下列待办任务。每项开始前必须成功执行 started 命令，失败则停止该项，禁止重复执行。完成并自验后立即执行 completed 命令。每项都立即写检查点，不能等整块完成。任何项失败则停止后续任务，说明情况并退出本轮，不自行重跑整块。\n'+
+            '【硬规则】原始任务若包含要在 Windows 上执行的命令行（尤其含引号或 \\" 转义的 cmd 风格命令行），必须把整行原样交给 cmd /c 执行，禁止用 PowerShell 直接执行、也禁止按 PowerShell 语法改写参数——PowerShell 会吞掉或重排引号，导致目标程序收到的参数失真。\n'+
+            '已独立验收的任务禁止重做：'+recovery.verified.join(', ')+'\n'+
+            recovery.pending.map(id=>`任务 ${id}\n开始前：${command(id,'started')}\n原始任务：${tasks.find(t=>t.id===id).prompt}\n完成自验后：${command(id,'completed')}`).join('\n\n')+
+            '\n全部待办完成后，最后仅输出 __ORCH_DONE__ '+token;
+          try{la=hooks.launcher(r.key,hooks.prompt(body,token),runId+'-a'+number);}
+          catch(error){await coordinate(()=>release(coordinator,leaseId),deadline);throw error;}
+          e={...e,status:'launching',leaseId,token,launcherFiles:la,launcher:null,endedAt:null,startedAt:Date.now()};sum.results[r.key]=e;persist();
+          try {
+            hooks.register({id:leaseId,runId,title:r.title,keys:r.keys,pidFile:la.pidf,pid:0,pending:true,reservedAt:Date.now()});
+            await coordinate(()=>prepare(coordinator,leaseId,la.pidf),deadline);
+            await stagger();
+            if(!await hooks.spawn(la.lp,r.title,la.pidf,1,token))throw new Error('Visible window did not start');
+            spawnConfirmed=true;
+            // 秒退单元：结果文件已落盘时无需身份绑定（launcher 已退出，身份无法取得），直接进入结果读取路径。
+            if(fs.existsSync(la.rf)){
+              console.log(`[run] ${r.key} launcher already finished; reading its result without identity binding`);
+              identity=null;
+            }else{
+              identity=await identityWithGrace(hooks,la);
+              if(!identity)throw new Error('Launcher process identity mismatch');
+              await coordinate(()=>bind(coordinator,leaseId,identity),deadline);hooks.commit(leaseId,identity.ProcessId);
+            }
+          }catch(error){e.status='popup-failed';e.reason=error.message;}
+        }
+        e=sum.results[r.key];e.launcher=identity||e.launcher;
+        try {
+          if(identity||fs.existsSync(la.rf)) {
+            e.status='running';persist();
+            const session=await hooks.session('【本块唯一标识】'+active.token,Math.min(90000,Math.max(0,deadline-Date.now())),la.rf);
+            const result=session?await hooks.wait(session,Math.max(0,deadline-Date.now()),la.rf,'【本块唯一标识】'+active.token,la.pidf):{done:fs.existsSync(la.rf),exitCode:hooks.exitCode(la.rf)};
+            e.exitCode=result.exitCode??hooks.exitCode(la.rf);e.status=result.done?'awaiting-verification':'timeout';
+          }
+        }catch(error){e.status='failed';e.reason=error.message;}
+        finally {
+          if(!identity&&la&&spawnConfirmed&&!fs.existsSync(la.rf))try{identity=await identityWithGrace(hooks,la,{graceMs:4000,intervalMs:300});}catch{identity=undefined;}
+          if(identity)await hooks.close(identity.ProcessId,identity);
+          if(identity&&!(await waitForProcessExit(identity))){e.status='failed';e.reason='Launcher still alive; lease retained';persist();return;}
+          await coordinate(()=>release(coordinator,e.leaseId||leaseId),Date.now()+30000);
+          hooks.unregister(e.leaseId||leaseId);if(la)hooks.cleanup(la);
+          e.endedAt=Date.now();active.endedAt=e.endedAt;active.exitCode=e.exitCode;
+          collectVerification(sum,checks,workspace);persist();
+        }
+        if(e.status==='verified')return;
+        if(!identity&&e.attempts.length&&e.reason==='Visible window did not start'){mark(r,'popup-failed',e.reason);return;}
+      }
+      mark(r,'timeout','Run deadline exhausted');
+    }
+    await scheduleReady(sum.plan,async r=>{try{await execute(r);}catch(e){mark(r,'failed',e.message);}},key=>sum.results[key]?.status,
+      (r,failed)=>mark(r,'blocked','Predecessors not verified: '+failed.join(', ')));
+    for(const r of sum.plan)if(!TERMINAL.has(sum.results[r.key]?.status))mark(r,'failed','No terminal result');
+    sum.finishedAt=Date.now();sum.success=summaryComplete(sum,true);persist();
+    console.log(`[run] finalized runId=${runId} success=${sum.success} summary=${summaryFile}`);return sum;
+  }finally{await coordinate(()=>releaseRun(coordinator,runKey,claim),Date.now()+30000);}
+}

package/scripts/core/runtime-context.mjs

@@ -0,0 +1,23 @@
+import path from 'node:path';
+
+// Resolve once at the caller's entry point. Never substitute the install directory
+// or CODEX_HOME for the directory that initiated this run.
+export function resolveRuntimeContext(env = process.env, cwd = process.cwd()) {
+  const workspace = path.resolve(cwd, String(env.WORKSPACE_DIR || '').trim() || '.');
+  const temp = path.join(workspace, 'temp');
+  const override = String(env.ORCH_STATE_DIR || '').trim();
+  const state = override ? resolveStateOverride(temp, override) : path.join(temp, 'orchestrator');
+  return { workspace, temp, state };
+}
+
+function resolveStateOverride(temp, override) {
+  // Runtime state is part of the initiating workspace. Relative overrides are
+  // rooted at workspace/temp, while absolute overrides are accepted only when
+  // they already point below that directory.
+  const candidate = path.isAbsolute(override) ? path.resolve(override) : path.resolve(temp, override);
+  const relative = path.relative(temp, candidate);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`ORCH_STATE_DIR must stay under the initiating workspace temp directory: ${candidate}`);
+  }
+  return candidate;
+}

package/scripts/core/unit-carrier.mjs

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+// 单元载体（carrier）解析——工具适配 agent 的载体分级层。
+//
+//   stdio = 无控制台的隐藏进程（print 类 CLI：自带一次性输出模式，不需要终端）
+//   pty   = ConPTY 伪终端宿主（TUI 类 CLI：需要真实终端，工具给它一个真实但完全不可见的控制台）
+//
+// 两载体共享同一条契约：同样的启动器 ps1、pidf、进程身份、租约、恢复/收编。
+// PTY 引擎解析顺序：工具自带安装（scripts/node_modules，dev 仓库与发行副本同构）
+// → 常规包解析。绝不静默借用其它 agent 安装目录里的副本（各副本独立升级、独立封印）。
+const require = createRequire(import.meta.url);
+const CORE_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+export function normalizeUnitCarrier(value) {
+  const v = String(value ?? '').trim().toLowerCase();
+  if (!v) return null;
+  if (v === 'pty' || v === 'stdio') return v;
+  throw new Error('UNSUPPORTED_UNIT_CARRIER: ' + value + ' (use pty|stdio)');
+}
+
+// 优先级：显式 ORCH_UNIT_CARRIER > agent 画像声明（registry/unit profile）> stdio 兜底。
+export function effectiveUnitCarrier(env = process.env, agentConfig = {}) {
+  return normalizeUnitCarrier(env.ORCH_UNIT_CARRIER)
+    || normalizeUnitCarrier(agentConfig.carrier)
+    || 'stdio';
+}
+
+function ptyCandidates() {
+  return [
+    path.join(CORE_DIR, '..', 'node_modules', '@lydell', 'node-pty', 'index.js'),
+    '@lydell/node-pty',
+  ];
+}
+
+export function ptyAvailability() {
+  for (const candidate of ptyCandidates()) {
+    try {
+      const resolved = path.isAbsolute(candidate) ? candidate : require.resolve(candidate);
+      if (fs.existsSync(resolved)) return { ok: true, resolved };
+    } catch { /* try the next candidate */ }
+  }
+  return { ok: false, tried: ptyCandidates() };
+}
+
+export function loadPtyEngine() {
+  const availability = ptyAvailability();
+  if (!availability.ok) {
+    throw new Error('PTY_CARRIER_UNAVAILABLE: @lydell/node-pty not found (tried: ' + availability.tried.join(' | ')
+      + '). Run `npm run setup` (or npm install --prefix scripts) to materialize the PTY engine, or fall back with ORCH_UNIT_CARRIER=stdio / --mode window.');
+  }
+  return require(availability.resolved);
+}

package/scripts/core/unit-command.mjs

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizeUnitCarrier } from './unit-carrier.mjs';
+
+// 调用方自助通道（caller-driven / delegate 模式）第一半：单元命令画像的解析与展开。
+//
+// 调用方（任意 agent）给出"一个执行单元怎么跑"的命令模板，编排器只负责确定性机制
+// （载具/身份/租约/看板/守护/恢复/验收）。与 print-class 画像（探测 + 解析自检 + 活验的
+// 富路径）不同，这里是"自证"的瘦路径：不 probe、不解析 --help/--version、无名单限制。
+//
+// 画像 schema（v1）：
+//   { schema:1, id, label, bin,
+//     args:[...],                     // 模板；占位符 {promptFile} / {prompt} / {workspace}
+//     promptDelivery:"file"|"arg"|"stdin",
+//     modelArgs:["--model"]|null,     // 可选：按 ORCH_MODEL 注入
+//     effortArgs:["--effort"]|null,   // 可选：按 ORCH_EFFORT 注入
+//     carrier:"pty"|"stdio"|null,     // 可选：单元载体覆盖（默认按 agent 画像；TUI 类 CLI 用 pty）
+//     timeoutMs:number|null }         // 可选：单单元超时（当前由轮询/调度统一控制）
+//
+// 规则：file=提示词落文件并把路径代入 {promptFile}；arg=提示词作为最后一个 argv 元素；
+//       stdin=提示词写进程 stdin。三者互斥，缺占位符时以 promptDelivery 为准。
+
+export const UNIT_PROMPT_FILE_TOKEN = '{promptFile}';
+export const UNIT_PROMPT_TOKEN = '{prompt}';
+export const UNIT_WORKSPACE_TOKEN = '{workspace}';
+
+export function normalizeUnitProfile(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('UNIT_CMD_INVALID: profile must be a JSON object');
+  }
+  const bin = String(input.bin || '').trim();
+  if (!bin) throw new Error('UNIT_CMD_INVALID: bin (executable path or name) is required');
+  if (/\.(cmd|bat)$/i.test(bin)) {
+    throw new Error('UNIT_CMD_INVALID: bin must be a real executable (Windows cannot spawn .cmd/.bat directly without a shell); point to the underlying .exe');
+  }
+  const id = String(input.id || 'custom').trim().toLowerCase().replace(/[^a-z0-9_.-]/g, '') || 'custom';
+  const label = String(input.label || id);
+  const args = (Array.isArray(input.args) ? input.args : []).map((a) => String(a));
+  const modelArgs = Array.isArray(input.modelArgs) && input.modelArgs.length ? input.modelArgs.map(String) : null;
+  const effortArgs = Array.isArray(input.effortArgs) && input.effortArgs.length ? input.effortArgs.map(String) : null;
+  const rawTimeout = Number(input.timeoutMs);
+  const timeoutMs = Number.isFinite(rawTimeout) && rawTimeout > 0 ? rawTimeout : null;
+
+  const hasFile = args.some((a) => a.includes(UNIT_PROMPT_FILE_TOKEN));
+  const hasPrompt = args.some((a) => a.includes(UNIT_PROMPT_TOKEN));
+  if (hasFile && hasPrompt) throw new Error('UNIT_CMD_INVALID: args must not use both {promptFile} and {prompt}');
+  const requested = String(input.promptDelivery || '').trim().toLowerCase();
+  const promptDelivery = requested || (hasFile ? 'file' : hasPrompt ? 'arg' : '');
+  if (!['file', 'arg', 'stdin'].includes(promptDelivery)) {
+    throw new Error('UNIT_CMD_INVALID: promptDelivery must be file|arg|stdin, or thread the prompt through {promptFile}/{prompt} in args');
+  }
+  if (promptDelivery === 'file' && !hasFile) throw new Error('UNIT_CMD_INVALID: promptDelivery=file requires {promptFile} in args');
+  if (promptDelivery === 'arg' && hasFile) throw new Error('UNIT_CMD_INVALID: promptDelivery=arg must not use {promptFile}');
+  if (promptDelivery === 'stdin' && (hasFile || hasPrompt)) throw new Error('UNIT_CMD_INVALID: promptDelivery=stdin must not use prompt placeholders');
+
+  return { schema: 1, id, label, bin, args, promptDelivery, modelArgs, effortArgs, timeoutMs, source: 'caller' };
+}
+
+export function loadUnitProfile(env = process.env) {
+  const file = String(env.ORCH_UNIT_CMD_FILE || '').trim();
+  const inline = String(env.ORCH_UNIT_CMD || '').trim();
+  if (!file && !inline) return null;
+  if (file && inline) throw new Error('UNIT_CMD_INVALID: provide --unit-cmd or --unit-cmd-file, not both');
+  let raw = inline;
+  if (file) {
+    const resolved = path.resolve(file);
+    try { raw = fs.readFileSync(resolved, 'utf8'); }
+    catch (error) { throw new Error('UNIT_CMD_UNREADABLE: ' + resolved + ' (' + (error?.message || String(error)) + ')'); }
+  }
+  let parsed;
+  try { parsed = JSON.parse(String(raw).replace(/^\uFEFF/, '')); }
+  catch (error) { throw new Error('UNIT_CMD_INVALID: not valid JSON (' + (error?.message || String(error)) + ')'); }
+  return normalizeUnitProfile(parsed);
+}
+
+// 展开单元 argv：占位符代入 + 可选的 model/effort 注入；arg 投递时提示词固定为最后一个 argv 元素。
+export function expandUnitArgs(config, { prompt = '', promptFile = '', workspace = '' } = {}) {
+  const flagValue = (flag, value) => (Array.isArray(flag) && flag.length && value && String(value).trim() && !/\s/.test(String(value).trim()) ? [...flag, String(value).trim()] : []);
+  const out = [];
+  for (const arg of config.args || []) {
+    if (config.promptDelivery === 'arg' && String(arg).includes(UNIT_PROMPT_TOKEN)) continue;
+    out.push(String(arg)
+      .replaceAll(UNIT_PROMPT_FILE_TOKEN, promptFile)
+      .replaceAll(UNIT_PROMPT_TOKEN, prompt)
+      .replaceAll(UNIT_WORKSPACE_TOKEN, workspace));
+  }
+  out.push(...flagValue(config.modelArgs, process.env.ORCH_MODEL), ...flagValue(config.effortArgs, process.env.ORCH_EFFORT));
+  if (config.promptDelivery === 'arg') out.push(prompt);
+  return out;
+}
+
+// 面向 doctor/status 的一行摘要（不含提示词内容）。
+export function describeUnitProfile(config) {
+  if (!config) return null;
+  return { id: config.id, label: config.label, bin: config.bin, args: config.args, promptDelivery: config.promptDelivery };
+}