open-tui-orchestrator 0.9.6

package/scripts/core/pi-host.mjs

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {probeCli} from './host-probe.mjs';
+export function resolvePiHost(env=process.env) {
+  const explicit=env.ORCH_CLI||env.PI_EXE;
+  const candidates=explicit?[path.resolve(explicit)]:String(env.PATH||env.Path||'').split(path.delimiter).flatMap(dir=>['pi.exe','pi.cmd','pi'].map(n=>path.join(dir,n)));
+  const rejected=[];
+  for(const file of [...new Set(candidates)]) {
+    if(!fs.existsSync(file)||!fs.statSync(file).isFile())continue;
+    let bin=file,prefixArgs=[];
+    if(!/\.exe$/i.test(file)) {
+      let entry=/\.[cm]?js$/i.test(file)?file:null;
+      if(!entry){const shim=fs.readFileSync(file,'utf8');const match=shim.match(/node_modules[\\/](@(?:earendil-works|mariozechner))[\\/]pi-coding-agent[\\/](dist[\\/](?:bundle[\\/])?cli\.js)/);if(match)entry=path.join(path.dirname(file),'node_modules',match[1],'pi-coding-agent',...match[2].split(/[\\/]/));}
+      if(!entry||!fs.existsSync(entry))continue;
+      const sibling=path.join(path.dirname(file),'node.exe');bin=fs.existsSync(sibling)?sibling:process.execPath;prefixArgs=[entry];
+    }
+    const label=[bin,...prefixArgs].join(' ');
+    const help=probeCli(bin,[...prefixArgs,'--help'],{env});
+    if(help.status!==0||!/pi - AI coding assistant/.test(help.stdout)||!['--session','--extension','--approve'].every(flag=>help.stdout.includes(flag))){rejected.push(`${label}: --help ${help.error?'probe error '+help.error:'exit '+help.status+'; banner/flags mismatch'}`);continue;}
+    const versionResult=probeCli(bin,[...prefixArgs,'--version'],{env});
+    const version=versionResult.stdout.trim();if(versionResult.status!==0||!/^\d+\.\d+\.\d+$/.test(version)){rejected.push(`${label}: --version ${versionResult.error?'probe error '+versionResult.error:'exit '+versionResult.status+'; unusable output '+JSON.stringify(version.slice(0,120))}`);continue;}
+    const [major,minor,patch]=version.split('.').map(Number);if(major===0&&(minor<84||(minor===84&&patch<4))){rejected.push(`${label}: version ${version} below floor 0.84.4`);continue;}
+    return {agent:'pi',config:{id:'pi',label:'pi agent',version,bin,prefixArgs,available:true,native:prefixArgs.length===0,modelEnv:'ORCH_MODEL',effortEnv:'ORCH_EFFORT'}};
+  }
+  throw new Error(`CLI_MISSING: pi; no supported installed pi CLI found. No fallback or automatic install. Tried: ${rejected.join(' | ')||'no candidate found on disk'}`);
+}
+export function piArgs(config,{model,effort}={}) {
+  return [...(config.prefixArgs||[]),'--approve','--offline',...(model?['--model',model]:[]),...(effort?['--thinking',effort]:[])];
+}

package/scripts/core/pi-runtime.mjs

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {spawn} from 'node:child_process';
+import {piArgs} from './pi-host.mjs';
+import {nativeArgumentLines} from './native-argv.mjs';
+export function piAssistantText(raw) {
+  let final='';
+  for(const line of raw.split(/\r?\n/))try{
+    const event=JSON.parse(line),message=event.message||event;
+    if(message.role==='assistant') {
+      if(message.stopReason==='error'||message.stopReason==='aborted')throw new Error('PI_RESPONSE_FAILED');
+      const text=(message.content||[]).filter(c=>c.type==='text').map(c=>c.text).join('');if(text)final=text;
+    }
+  }catch(error){if(error.message==='PI_RESPONSE_FAILED')throw error;}
+  return final;
+}
+export async function runPiPlanner(config,prompt,cwd) {
+  const args=[...piArgs(config,{model:process.env.ORCH_MODEL,effort:process.env.ORCH_EFFORT}),'--print','--mode','json','--no-session','--no-tools','--no-extensions','--no-skills','--no-context-files','--',prompt];
+  return new Promise((resolve,reject)=>{
+    const child=spawn(config.bin,args,{cwd,env:process.env,windowsHide:true,shell:false,stdio:['ignore','pipe','pipe']});
+    let raw='',errorText='',timedOut=false;
+    const timer=setTimeout(()=>{timedOut=true;child.kill();},Number(process.env.ORCH_DECOMPOSE_TIMEOUT_MS||60000));
+    child.stdout.on('data',b=>{raw+=b;if(raw.length>8000000)child.kill();});child.stderr.on('data',b=>{errorText+=b;});
+    child.on('error',e=>{clearTimeout(timer);reject(e);});
+    child.on('exit',code=>{clearTimeout(timer);try{if(timedOut||code!==0)throw new Error(timedOut?'PI_PLANNER_TIMEOUT':'PI_PLANNER_FAILED: exit '+code);const final=piAssistantText(raw);if(!final)throw new Error('PI_PLANNER_EMPTY_RESPONSE');resolve({final});}catch(e){reject(e);}});
+  });
+}
+const quote=s=>"'"+String(s).replaceAll("'","''")+"'";
+export function writePiLauncher(config,{key,prompt,suffix,workspace,temp}) {
+  const stem=String(key+'-'+suffix).replace(/[^a-zA-Z0-9_-]/g,'-');
+  const token=/【本块唯一标识】\s*([A-Za-z0-9][A-Za-z0-9_-]*)/.exec(prompt)?.[1];
+  if(!token)throw new Error('Pi window requires a completion token');
+  fs.mkdirSync(temp,{recursive:true});
+  const lp=path.join(temp,'win-launch-'+stem+'.ps1'),pidf=path.join(temp,'window-'+stem+'.pid'),pf=path.join(temp,'agent-win-'+stem+'.md'),rf=path.join(temp,'win-'+stem+'.result.json');
+  const piSession=path.join(temp,'orchestrator','pi','sessions',stem+'.jsonl');fs.mkdirSync(path.dirname(piSession),{recursive:true});
+  fs.writeFileSync(pf,prompt,'utf8');
+  const args=[...piArgs(config,{model:process.env.ORCH_MODEL,effort:process.env.ORCH_EFFORT}),'--session',piSession,'--extension',fileURLToPath(new URL('./pi-shutdown.mjs',import.meta.url)),'--','@'+pf];
+  const body=["$ErrorActionPreference = 'Stop'",`$PID | Set-Content -LiteralPath ${quote(pidf)} -Encoding UTF8`,
+    '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8','$OutputEncoding = [System.Text.Encoding]::UTF8','chcp 65001 | Out-Null',
+    `Set-Location -LiteralPath ${quote(workspace)}`,`$env:ORCH_WINDOW = '1'`,`$env:ORCH_PI_TOKEN = ${quote(token)}`,`$env:ORCH_PI_RESULT = ${quote(rf)}`,
+    '$code = 1','try {','$agentArgs = @('+args.map(quote).join(',')+')',...nativeArgumentLines(),`& ${quote(config.bin)} @agentArgs`,'$code = $LASTEXITCODE','} catch { $code = 1 }',
+    `if (-not (Test-Path -LiteralPath ${quote(rf)})) { @{__EXIT__=$code;__DONE__=$true;token=${quote(token)}} | ConvertTo-Json -Compress | Set-Content -LiteralPath ${quote(rf)} -Encoding UTF8 }`,'exit 0'].join('\r\n');
+  fs.writeFileSync(lp,'\ufeff'+body,'utf8');return {lp,pidf,pf,rf,piSession};
+}
+export async function waitPiResult(rf,timeoutMs,pidf) {
+  const end=Date.now()+timeoutMs;
+  while(Date.now()<end) {
+    if(fs.existsSync(rf)){try{const r=JSON.parse(fs.readFileSync(rf,'utf8').replace(/^\uFEFF/,''));return {done:true,exitCode:r.__EXIT__,text:r.__REPORT__||''};}catch{}}
+    if(fs.existsSync(pidf)){const pid=Number(fs.readFileSync(pidf,'utf8').replace(/^\uFEFF/,''));try{process.kill(pid,0);}catch{return {done:true,exitCode:1,text:'Pi launcher exited without result'};}}
+    await new Promise(r=>setTimeout(r,300));
+  }
+  return {done:false,exitCode:null,text:'Pi completion timeout'};
+}

package/scripts/core/pi-shutdown.mjs

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+import path from 'node:path';
+// Pi's settled event happens after automatic retries/compaction and queued work.
+export default function orchestratorCompletion(pi) {
+  pi.on('agent_settled',async(_event,ctx)=>{
+    if(!ctx.isIdle())return;
+    const file=process.env.ORCH_PI_RESULT,token=process.env.ORCH_PI_TOKEN;if(!file||!token)return;
+    const messages=ctx.sessionManager.getBranch().filter(e=>e.type==='message'&&e.message?.role==='assistant');
+    const last=messages.at(-1)?.message;
+    const text=(last?.content||[]).filter(c=>c.type==='text').map(c=>c.text).join('');
+    const ok=!['error','aborted'].includes(last?.stopReason)&&text.includes('__ORCH_DONE__ '+token);
+    fs.mkdirSync(path.dirname(file),{recursive:true});const tmp=file+'.'+process.pid+'.tmp';
+    fs.writeFileSync(tmp,JSON.stringify({__EXIT__:ok?0:1,__DONE__:true,__REPORT__:text,token}));fs.renameSync(tmp,file);
+    ctx.shutdown();
+  });
+}

package/scripts/core/poll-windows.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {performance} from 'node:perf_hooks';
+import {resolveRuntimeContext} from './runtime-context.mjs';
+import {runDirectory} from './runner.mjs';
+import {processSnapshot,sameProcess} from './leases.mjs';
+import {TERMINAL,SUCCESS,summaryComplete} from './contracts.mjs';
+export {TERMINAL,SUCCESS,summaryComplete};
+export const summaryTerminal=sum=>summaryComplete(sum,false);
+export const failures=sum=>Object.entries(sum?.taskResults||{}).filter(([,r])=>!SUCCESS.has(r.status)).map(([id,r])=>id+':'+r.status);
+export function loadSummary(workspace,runId){try{return JSON.parse(fs.readFileSync(path.join(runDirectory(workspace,runId),'summary.json'),'utf8'));}catch{return null;}}
+export function parsePollingOptions(argv,env=process.env){
+  const result={runId:env.ORCH_RUN_ID,timeoutMs:1800000,intervalMs:5000};
+  const fields={'--run-id':'runId','--timeoutMs':'timeoutMs','--intervalMs':'intervalMs'};
+  for(let i=0;i<argv.length;i++){
+    const flag=argv[i];if(flag==='--require-all-success')continue;
+    const field=Object.hasOwn(fields,flag)?fields[flag]:null,value=argv[++i];
+    if(!field||value===undefined||!value.trim()||value.startsWith('--'))throw new Error('POLL_ARGUMENT_INVALID: '+flag);
+    result[field]=field==='runId'?value:Number(value);
+  }
+  if(!result.runId)throw new Error('POLL_ARGUMENT_INVALID: --run-id is required');
+  for(const key of ['timeoutMs','intervalMs'])if(!Number.isSafeInteger(result[key])||result[key]<(key==='timeoutMs'?0:1)||result[key]>2147483647)throw new Error('POLL_ARGUMENT_INVALID: '+key);
+  result.intervalMs=Math.max(500,result.intervalMs);return result;
+}
+export async function main(argv=process.argv.slice(2),hooks={}) {
+  const {runId,timeoutMs,intervalMs:interval}=parsePollingOptions(argv);
+  const {workspace}=resolveRuntimeContext();runDirectory(workspace,runId);
+  const now=hooks.now||(()=>performance.now()),sleep=hooks.sleep||(ms=>new Promise(r=>setTimeout(r,ms)));
+  const snapshot=hooks.snapshot||processSnapshot,load=hooks.load||loadSummary,log=hooks.log||console.log,error=hooks.error||console.error;
+  const deadline=now()+timeoutMs;
+  let stable=0;
+  while(now()<deadline) {
+    const sum=load(workspace,runId);
+    if(sum?.runId===runId&&sum.finishedAt&&summaryTerminal(sum)) {
+      const remaining=deadline-now();if(remaining<=0)break;
+      const processes=snapshot(Math.max(1,Math.ceil(remaining)));
+      if(now()>=deadline)break;
+      const alive=Object.values(sum.results).some(r=>r.launcher&&sameProcess(r.launcher,processes.get(r.launcher.ProcessId)));
+      if(!alive&&++stable>=2){const ok=summaryComplete(sum,true);log(JSON.stringify({runId,success:ok,failures:failures(sum)}));process.exitCode=ok?0:1;return;}
+      if(alive)stable=0;
+    }else stable=0;
+    log('[poll-windows] runId='+runId+' waiting for finalized inventory and closed windows');
+    await sleep(Math.min(interval,Math.max(0,deadline-now())));
+  }
+  error('[poll-windows] timeout runId='+runId);process.exitCode=1;
+}
+if(process.argv[1]&&path.resolve(process.argv[1]).toLowerCase()===fileURLToPath(import.meta.url).toLowerCase())main().catch(e=>{console.error(e.message);process.exitCode=2;});

package/scripts/core/print-profile.mjs

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {probeCli} from './host-probe.mjs';
+
+// print-class 通用适配：任何"一次性提示词 → stdout 终文本 → 自行退出"形态的 agent CLI
+// 都可以用一份 JSON 画像（profile）接入，不必手写专用适配器。画像由 `node adapt.mjs`
+// 探测生成（scripts/core/agent-profiles/<id>.json），也可以在适配目录里手写。
+//
+// 画像 schema（v1）:
+//   { schema:1, id, label, bin:[候选名...], helpFlags:[必须出现在 --help 的旗标...],
+//     versionPattern:'正则(含捕获组)', probePrompt:'探活提示词',
+//     args:{ approve:[自动批准旗标...], extra:[附加旗标...], model:['--model']|null,
+//            effort:['--effort']|null, prompt:['--message']|null } }
+//   prompt 旗标取值为提示词本身（提示词跟在旗标之后，作为最后一个 argv 元素）。
+
+export const DEFAULT_PROFILE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), 'agent-profiles');
+
+export function profilesDir(env = process.env) {
+  const override = String(env.ORCH_AGENT_PROFILES_DIR || '').trim();
+  return override ? path.resolve(override) : DEFAULT_PROFILE_DIR;
+}
+
+export function loadProfile(id, env = process.env) {
+  const file = path.join(profilesDir(env), String(id || '') + '.json');
+  try {
+    const profile = JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+    if (profile && profile.schema === 1 && profile.id && Array.isArray(profile.bin) && profile.bin.length) return profile;
+    return null;
+  } catch { return null; }
+}
+
+export function listProfiles(env = process.env) {
+  try {
+    return fs.readdirSync(profilesDir(env)).filter((f) => f.endsWith('.json')).map((f) => f.replace(/\.json$/, ''));
+  } catch { return []; }
+}
+
+export function profileArgs(config, {model, effort} = {}) {
+  const p = config?.profile || {};
+  const a = p.args || {};
+  const flagValue = (flag, value) => (Array.isArray(flag) && flag.length && value && String(value).trim() && !/\s/.test(String(value)) ? [...flag, String(value).trim()] : []);
+  return [
+    ...(config.prefixArgs || []),
+    ...(a.approve || []),
+    ...(a.extra || []),
+    ...flagValue(a.model, model),
+    ...flagValue(a.effort, effort),
+    ...(a.prompt || ['-p']),
+  ];
+}
+
+export function resolveProfileHost(env = process.env, id) {
+  const profile = loadProfile(id, env);
+  if (!profile) return null;
+  const explicit = env.ORCH_CLI || env[String(id).toUpperCase() + '_EXE'];
+  const names = profile.bin;
+  const candidates = explicit
+    ? [path.resolve(explicit)]
+    : String(env.PATH || env.Path || '').split(path.delimiter).filter(Boolean).flatMap((dir) => names.map((n) => path.join(dir, n)));
+  const rejected = [];
+  for (const file of [...new Set(candidates)]) {
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+    // .mjs/.cjs 形态：以 node + 脚本运行（本地 Node CLI 的常见发布形态）。
+    let bin = file, prefixArgs = [];
+    if (/\.m?js$/i.test(file)) {
+      const sibling = path.join(path.dirname(file), 'node.exe');
+      bin = fs.existsSync(sibling) ? sibling : process.execPath; prefixArgs = [file];
+    }
+    const help = probeCli(bin, [...prefixArgs, '--help'], {env});
+    const missing = (profile.helpFlags || []).filter((f) => !help.out.includes(f));
+    if (help.status !== 0 || missing.length) { rejected.push(`${file}: --help ${help.error ? 'probe error ' + help.error : 'exit ' + help.status}${missing.length ? '; missing ' + missing.join(' ') : ''}`); continue; }
+    const versionResult = probeCli(bin, [...prefixArgs, '--version'], {env});
+    const version = new RegExp(profile.versionPattern || '(\\d+\\.\\d+\\.\\d+)').exec(String(versionResult.stdout || ''))?.[1];
+    if (versionResult.status !== 0 || !version) { rejected.push(`${file}: --version ${versionResult.error ? 'probe error ' + versionResult.error : 'exit ' + versionResult.status + '; unusable output ' + JSON.stringify(String(versionResult.stdout || '').trim().slice(0, 120))}`); continue; }
+    return { agent: id, config: { id, label: profile.label || id, version, bin, prefixArgs, available: true, native: prefixArgs.length === 0, completionMarker: '__ORCH_DONE__', modelEnv: 'ORCH_MODEL', effortEnv: 'ORCH_EFFORT', profile, profileFile: path.join(profilesDir(env), id + '.json'), reusable: true } };
+  }
+  throw new Error(`CLI_MISSING: ${id}; no supported installed ${id} CLI found (print-class profile ${path.join(profilesDir(env), id + '.json')}). No fallback or automatic install. Tried: ${rejected.join(' | ') || 'no candidate found on disk'}`);
+}

package/scripts/core/print-runtime.mjs

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {profileArgs} from './print-profile.mjs';
+import {nativeArgumentLines} from './native-argv.mjs';
+
+// print-class 通用运行时：与 kimi/claude 适配器同构的启动器契约（tee 日志 + token 行抓取 +
+// result 文件 + self-closed 标记），供任何带画像的 agent 使用。
+
+const quote = (s) => "'" + String(s).replaceAll("'", "''") + "'";
+
+export async function runProfilePlanner(config, prompt, cwd) {
+  const args = [...profileArgs(config, {model: process.env.ORCH_MODEL, effort: process.env.ORCH_EFFORT}), prompt];
+  return new Promise((resolve, reject) => {
+    const child = spawn(config.bin, args, { cwd, env: process.env, windowsHide: true, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+    let raw = '', errorText = '', timedOut = false;
+    const timeoutMs = (() => { const v = Number(process.env.ORCH_DECOMPOSE_TIMEOUT_MS); return Number.isFinite(v) && v > 0 ? v : 240000; })();
+    const timer = setTimeout(() => { timedOut = true; child.kill(); }, timeoutMs);
+    child.stdout.on('data', (b) => { raw += b; if (raw.length > 8000000) child.kill(); });
+    child.stderr.on('data', (b) => { errorText += b; });
+    child.on('error', (e) => { clearTimeout(timer); reject(e); });
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      try {
+        if (timedOut || code !== 0) throw new Error((timedOut ? 'PLANNER_TIMEOUT' : 'PLANNER_FAILED: exit ' + code) + (errorText ? ': ' + String(errorText).slice(0, 300) : ''));
+        const final = String(raw || '').trim();
+        if (!final) throw new Error('PLANNER_EMPTY_RESPONSE' + (errorText ? ': ' + String(errorText).slice(0, 300) : ''));
+        resolve({ final });
+      } catch (e) { reject(e); }
+    });
+  });
+}
+
+export function writeProfileLauncher(config, { key, prompt, suffix, workspace, temp }) {
+  const stem = String(key + '-' + suffix).replace(/[^a-zA-Z0-9_-]/g, '-');
+  const token = /【本块唯一标识】\s*([A-Za-z0-9][A-Za-z0-9_-]*)/.exec(prompt)?.[1];
+  if (!token) throw new Error((config.label || config.id) + ' window requires a completion token');
+  fs.mkdirSync(temp, { recursive: true });
+  const lp = path.join(temp, 'win-launch-' + stem + '.ps1');
+  const pidf = path.join(temp, 'window-' + stem + '.pid');
+  const pf = path.join(temp, 'agent-win-' + stem + '.md');
+  const rf = path.join(temp, 'win-' + stem + '.result.json');
+  const log = path.join(temp, 'win-' + stem + '.out.log');
+  fs.writeFileSync(pf, prompt, 'utf8');
+  const args = profileArgs(config, { model: process.env.ORCH_MODEL, effort: process.env.ORCH_EFFORT });
+  const body = [
+    "$ErrorActionPreference = 'Continue'",
+    'trap { exit 0 }',
+    `$PID | Set-Content -LiteralPath ${quote(pidf)} -Encoding UTF8`,
+    '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8',
+    '$OutputEncoding = [System.Text.Encoding]::UTF8',
+    'chcp 65001 | Out-Null',
+    '[Console]::InputEncoding = [System.Text.Encoding]::UTF8',
+    'Write-Host "============================================="',
+    'Write-Host "  ' + String(config.label || config.id).toUpperCase() + ' TASK RUNNING - closes automatically on completion"',
+    'Write-Host "============================================="',
+    `Set-Location -LiteralPath ${quote(workspace)}`,
+    `$env:ORCH_WINDOW = '1'`,
+    `$token = ${quote(token)}`,
+    `$log = ${quote(log)}`,
+    `$resultFile = ${quote(rf)}`,
+    "function Write-Result {",
+    "  param([int]$code,[string]$report)",
+    "  try {",
+    "    $json = '{\"__EXIT__\":' + $code + ',\"__DONE__\":true,\"__REPORT__\":' + (ConvertTo-Json $report -Compress) + '}'",
+    "    $d = Split-Path -Parent $resultFile; if ($d -and -not (Test-Path -LiteralPath $d)) { New-Item -ItemType Directory -Force -Path $d | Out-Null }",
+    "    Set-Content -LiteralPath $resultFile -Value ($json + \"`r`n__EXIT__=\" + $code) -Encoding UTF8",
+    "    try { Set-Content -LiteralPath ($resultFile + '.self-closed') -Value '1' -Encoding ASCII } catch { }",
+    "  } catch { }",
+    "}",
+    "$p = (Get-Content -Raw -Encoding UTF8 '" + String(pf).replace(/'/g, "''") + "').Trim()",
+    "if ([string]::IsNullOrWhiteSpace($p)) { Write-Result 2 ''; exit 0 }",
+    "$agentArgs = @(" + args.map(quote).join(',') + ') + @($p)',
+    ...nativeArgumentLines(),
+    `& ${quote(config.bin)} @agentArgs 2>&1 | ForEach-Object { if ($_ -is [System.Management.Automation.ErrorRecord]) { $_.TargetObject } else { $_ } } | Tee-Object -FilePath $log`,
+    '$code = $LASTEXITCODE',
+    "$report = ''",
+    "if (Test-Path -LiteralPath $log) {",
+    "  $lines = Get-Content -LiteralPath $log -Encoding UTF8 -ErrorAction SilentlyContinue",
+    "  $hit = $lines | Where-Object { $_.Contains($token) } | Select-Object -Last 1",
+    "  if ($hit) { $report = $hit } else { $report = ($lines | Select-Object -Last 3) -join \"`n\" }",
+    "}",
+    'Write-Result $code $report',
+    'exit 0',
+  ].join('\r\n');
+  fs.writeFileSync(lp, '\uFEFF' + body, 'utf8');
+  return { lp, pidf, pf, rf, log };
+}
+
+export async function waitProfileResult(rf, timeoutMs, pidf) {
+  const end = Date.now() + timeoutMs;
+  while (Date.now() < end) {
+    if (fs.existsSync(rf)) {
+      try {
+        const r = JSON.parse(fs.readFileSync(rf, 'utf8').replace(/^\uFEFF/, '').split(/\r?\n/)[0]);
+        return { done: true, exitCode: r.__EXIT__, text: r.__REPORT__ || '' };
+      } catch { /* keep polling */ }
+    }
+    if (fs.existsSync(pidf)) {
+      const pid = Number(fs.readFileSync(pidf, 'utf8').replace(/^\uFEFF/, ''));
+      try { process.kill(pid, 0); } catch { return { done: true, exitCode: 1, text: 'Launcher exited without result' }; }
+    }
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  return { done: false, exitCode: null, text: 'Completion timeout' };
+}

package/scripts/core/pty-host.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// PTY 载体宿主：把单个启动器（win-launch-*.ps1）放进 ConPTY 伪终端里运行。
+// 需要终端的 TUI 类 agent 因此拿到真实控制台，而整条链完全不可见（无窗口、不抢焦点）。
+// 独立进程：控制器死亡不影响本宿主；进程树（宿主→ps1→agent）、pidf、身份、租约、
+// 恢复/收编契约与窗口模式同构。stdout/stderr 落在 ORCH_PTY_LOG 指向的日志文件里，
+// 供失败诊断（该文件由控制器的清理钩子在块结束后回收）。
+// 用法：node pty-host.mjs <win-launch-*.ps1>   （cwd/env 由控制器给出）
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadPtyEngine } from './unit-carrier.mjs';
+import { powershellExe } from './contracts.mjs';
+
+const lp = String(process.argv[2] || '');
+const logFile = String(process.env.ORCH_PTY_LOG || '').trim()
+  || (lp ? path.join(path.dirname(lp), path.basename(lp).replace(/\.ps1$/, '') + '.pty.log') : '');
+
+function fail(message) {
+  try { if (logFile) fs.appendFileSync(logFile, '[pty-host] ' + message + '\n', 'utf8'); } catch { /* best effort */ }
+  console.error(message);
+  process.exit(3);
+}
+
+if (!lp || !fs.existsSync(lp)) fail('PTY_HOST_USAGE: node pty-host.mjs <win-launch.ps1> (got: ' + lp + ')');
+
+let pty;
+try { pty = loadPtyEngine(); } catch (error) { fail(String(error && error.message || error)); }
+
+let stream = null;
+try { stream = fs.createWriteStream(logFile, { flags: 'a' }); } catch { /* diagnostics only */ }
+
+const term = pty.spawn(powershellExe(), ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', lp], {
+  name: 'xterm-256color', cols: 200, rows: 50, cwd: process.cwd(), env: process.env,
+});
+term.onData((data) => { if (stream) { try { stream.write(data); } catch { /* best effort */ } } });
+term.onExit(() => {
+  if (stream) { try { stream.end(); } catch { /* best effort */ } }
+  process.exit(0);
+});

package/scripts/core/recovery.mjs

@@ -0,0 +1,75 @@
+import {levelWaves,verifyChecks,requestTasks,computeMaxWindows} from './contracts.mjs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Validate persisted structure before recovery can change state or invoke tools.
+export function validateRecoverySummary(sum) {
+  const fail=reason=>{throw new Error('Invalid recovery ledger: '+reason);};
+  const object=x=>x!==null&&typeof x==='object'&&!Array.isArray(x);
+  const strings=x=>Array.isArray(x)&&x.every(v=>typeof v==='string'&&v.length>0);
+  const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+  const exact=(ids,value)=>object(value)&&new Set(ids).size===ids.length&&Object.keys(value).length===ids.length&&ids.every(id=>Object.hasOwn(value,id)&&object(value[id]));
+  if(!object(sum)||sum.protocol!==2||typeof sum.request!=='string'||!Number.isSafeInteger(sum.generation)||sum.generation<1||!Array.isArray(sum.history))fail('invalid header');
+  if(sum.acceptanceSha256!==undefined&&(typeof sum.acceptanceSha256!=='string'||!/^[0-9a-f]{64}$/.test(sum.acceptanceSha256)))fail('invalid acceptance hash');
+  const tasks=requestTasks(sum.request);
+  if(!tasks.length||!Array.isArray(sum.tasks)||!same(sum.tasks.map(t=>({id:t?.id,prompt:t?.prompt})),tasks))fail('original task inventory mismatch');
+  if(!Array.isArray(sum.blocks)||!sum.blocks.length||sum.blocks.length>computeMaxWindows(os.totalmem()/1024**3)||!Array.isArray(sum.plan)||sum.plan.length!==sum.blocks.length)fail('block inventory mismatch');
+  const ids=tasks.map(t=>t.id),blockIds=sum.blocks.map(b=>b?.key);
+  if(!strings(blockIds)||!exact(blockIds,sum.results)||!exact(ids,sum.taskResults))fail('result inventory mismatch');
+  const covered=[];
+  // resolve 后的盘符根自带尾分隔符（D:\），再拼一个 sep 会变成 D:\\ 导致根工作区的
+  // 合法 launcherFiles 全被误判为逃逸（E 验收实跑发现）；只在缺尾分隔符时补。
+  const resolvedWorkspace=path.resolve(sum.workspace);
+  const workspaceRoot=resolvedWorkspace.endsWith(path.sep)?resolvedWorkspace:resolvedWorkspace+path.sep;
+  for(let i=0;i<sum.blocks.length;i++) {
+    const block=sum.blocks[i],plan=sum.plan[i],entry=sum.results[block.key];
+    if(!strings(block.taskIds)||!block.taskIds.length||!object(plan)||plan.key!==block.key||!strings(plan.keys)||!strings(plan.dependsOn)||!Array.isArray(plan.b?.tasks))fail('invalid block or plan');
+    if(!plan.b.tasks.every(t=>strings(t?.sourceIds)&&t.sourceIds.length)||!same(plan.b.tasks.flatMap(t=>t.sourceIds),block.taskIds))fail('plan task coverage mismatch');
+    covered.push(...block.taskIds);
+    if(!Array.isArray(entry.attempts))fail('missing attempt inventory');
+    // launcherFiles 会被 resume 的 adopt/cleanup 直接使用（含 rmSync）：每个路径都必须
+    // 解析到本工作区之内，否则被篡改的账本能借控制器之手删工作区外的任意文件。
+    for(const f of Object.values(entry.launcherFiles||{})) {
+      const resolved=typeof f==='string'&&f?path.resolve(f):'';
+      if(!resolved||!resolved.startsWith(workspaceRoot))fail('launcher files escape the workspace');
+    }
+    if(!entry.attempts.length&&(entry.launcherFiles||entry.launcher||entry.token||['launching','running','verified','awaiting-verification'].includes(entry.status)))fail('launched block has no attempt inventory');
+    for(const attempt of entry.attempts) {
+      if(!object(attempt)||attempt.runId!==sum.runId||typeof attempt.token!=='string'||!attempt.token||typeof attempt.file!=='string'||!attempt.file||!strings(attempt.taskIds)||!attempt.taskIds.length||new Set(attempt.taskIds).size!==attempt.taskIds.length||attempt.taskIds.some(id=>!block.taskIds.includes(id)))fail('invalid attempt identity or task coverage');
+    }
+  }
+  if(covered.length!==ids.length||new Set(covered).size!==ids.length||covered.some(id=>!ids.includes(id)))fail('incomplete or duplicate task coverage');
+  try{levelWaves(structuredClone(sum.plan));}catch(error){fail(error.message);}
+  return sum;
+}
+
+export async function scheduleReady(recs,execute,status,onBlocked=()=>{}) {
+  levelWaves(recs); // Validate the whole graph before any work starts.
+  const byKey=new Map(recs.map(r=>[r.key,r])),jobs=new Map();
+  const start=r=>{
+    if(jobs.has(r.key))return jobs.get(r.key);
+    const job=Promise.resolve().then(async()=>{
+      await Promise.all(r.dependsOn.map(id=>start(byKey.get(id))));
+      const failed=r.dependsOn.filter(id=>status(id)!=='verified');
+      if(failed.length)return onBlocked(r,failed);
+      return execute(r);
+    });
+    jobs.set(r.key,job);return job;
+  };
+  await Promise.all(recs.map(start));
+}
+
+export const taskPolicy=value=>Array.isArray(value)?{checks:value,retrySafe:false}:{checks:value?.checks||[],retrySafe:value?.retrySafe===true};
+export function recoveryTasks(tasks,checkpoints,checks,workspace) {
+  const result={verified:[],pending:[],uncertain:[],results:{}};
+  for(const task of tasks) {
+    const cp=checkpoints[task.id],policy=taskPolicy(checks[task.id]);
+    if(!cp){result.pending.push(task.id);continue;}
+    if(cp.state==='invalid'){result.uncertain.push(task.id);result.results[task.id]={status:'needs-reconciliation',reason:'Invalid checkpoint',checkpoint:cp};continue;}
+    const verification=verifyChecks(policy.checks,workspace);
+    if(verification.status==='verified'){result.verified.push(task.id);result.results[task.id]={...verification,checkpoint:cp};}
+    else if(policy.retrySafe){result.pending.push(task.id);}
+    else {result.uncertain.push(task.id);result.results[task.id]={status:'needs-reconciliation',reason:'Started task has no proven result and is not declared safe to retry',verification,checkpoint:cp};}
+  }
+  return result;
+}

package/scripts/core/run-board.mjs

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// 执行看板（run board）：把运行账本投影成"块状态 + 任务状态"的实时视图。
+// 数据源：summary.json（block 级权威）+ attempts/**/checkpoints（task 级真实进度，
+// 因为 running 期间 taskResults 会滞后）。纯函数 + 只读文件访问，供引擎事件流、
+// --watch 和 --status 共用。
+
+const BLOCK_MARKS = { verified: '✓', running: '▶', launching: '…', waiting: '⏳', pending: '·', failed: '✗', timeout: '✗', 'popup-failed': '✗', 'needs-reconciliation': '⚠', blocked: '⊘', 'awaiting-verification': '◐' };
+const TERMINAL = new Set(['verified', 'failed', 'blocked', 'cancelled', 'awaiting-verification', 'preflight-failed', 'popup-failed', 'timeout', 'needs-reconciliation']);
+
+export function runDirectory(workspace, runId) {
+  return path.join(workspace, 'temp', 'orchestrator', 'runs', String(runId));
+}
+
+export function boardSignature(sum, taskStates = {}) {
+  return JSON.stringify([
+    sum?.generation ?? null,
+    sum?.finishedAt ?? null,
+    (sum?.blocks || []).map(b => [b.key, sum?.results?.[b.key]?.status || 'pending', sum?.results?.[b.key]?.attempts?.length || 0]),
+    Object.values(sum?.taskResults || {}).map(t => t?.status || 'pending'),
+    Object.entries(taskStates).map(([id, st]) => id + ':' + st),
+  ]);
+}
+
+export function boardCounts(sum) {
+  const counts = { total: 0, verified: 0, running: 0, waiting: 0, failed: 0 };
+  for (const b of sum?.blocks || []) {
+    counts.total++;
+    const st = sum?.results?.[b.key]?.status || 'pending';
+    if (st === 'verified') counts.verified++;
+    else if (st === 'running' || st === 'launching' || st === 'awaiting-verification') counts.running++;
+    else if (st === 'pending' || st === 'waiting') counts.waiting++;
+    else counts.failed++;
+  }
+  return counts;
+}
+
+export function boardSummaryLine(sum, taskStates = {}) {
+  const c = boardCounts(sum);
+  const parts = (sum?.blocks || []).map(b => b.key + (BLOCK_MARKS[sum?.results?.[b.key]?.status || 'pending'] || '?'));
+  const active = [];
+  for (const [id, st] of Object.entries(taskStates)) if (st && st !== 'completed') active.push(id + ':' + st);
+  return `[board] run=${sum?.runId || '?'} gen=${sum?.generation ?? '?'} mode=${sum?.spawnMode || 'window'} ${c.verified}/${c.total} verified${c.waiting ? ' ' + c.waiting + ' waiting' : ''}${c.failed ? ' ' + c.failed + ' failed' : ''} [${parts.join(' ')}]${active.length ? ' active=' + active.join(',') : ''}${sum?.finishedAt ? ' finalized success=' + (sum?.success === true) : ''}`;
+}
+
+export function boardFullText(sum, taskStates = {}) {
+  const c = boardCounts(sum);
+  const lines = [`── run ${sum?.runId || '?'} · mode=${sum?.spawnMode || 'window'} · gen=${sum?.generation ?? '?'} · ${c.verified}/${c.total} verified${sum?.finishedAt ? ' · finalized success=' + (sum?.success === true) : ''} ──`];
+  for (const b of sum?.blocks || []) {
+    const e = sum?.results?.[b.key] || {};
+    const st = e.status || 'pending';
+    const mark = BLOCK_MARKS[st] || '?';
+    const tasks = (b.taskIds || []).map(id => {
+      const t = sum?.taskResults?.[id] || {};
+      const cp = taskStates[id] ? ' ' + taskStates[id] : '';
+      const tm = t.status === 'verified' ? '✓' : t.status ? (t.status[0] || '?') : '·';
+      return id + tm + cp;
+    }).join(' ');
+    const reason = e.reason ? '  (' + String(e.reason).slice(0, 80) + ')' : '';
+    lines.push(' ' + b.key.padEnd(3) + (b.title || '').padEnd(22) + mark + ' ' + st.padEnd(20) + tasks + reason);
+  }
+  return lines.join('\n');
+}
+
+export function boardJson(sum, taskStates = {}) {
+  return {
+    ts: Date.now(),
+    runId: sum?.runId ?? null,
+    generation: sum?.generation ?? null,
+    spawnMode: sum?.spawnMode || 'window',
+    finished: !!sum?.finishedAt,
+    success: sum?.success ?? null,
+    blocks: (sum?.blocks || []).map(b => ({
+      key: b.key,
+      title: b.title,
+      status: sum?.results?.[b.key]?.status || 'pending',
+      attempts: sum?.results?.[b.key]?.attempts?.length || 0,
+      reason: sum?.results?.[b.key]?.reason || null,
+    })),
+    tasks: Object.entries(sum?.taskResults || {}).map(([id, t]) => ({ id, status: t?.status || 'pending', checkpoint: taskStates[id] || null })),
+  };
+}
+
+export function taskCheckpointStates(runDir, sum) {
+  const states = {};
+  for (const b of sum?.blocks || []) {
+    for (const a of sum?.results?.[b.key]?.attempts || []) {
+      for (const id of a.taskIds || []) {
+        try {
+          const f = path.join(path.dirname(String(a.file)), 'checkpoints', id + '.json');
+          const cp = JSON.parse(fs.readFileSync(f, 'utf8').replace(/^\uFEFF/, ''));
+          if (cp?.state) states[id] = cp.state;
+        } catch { /* not yet written */ }
+      }
+    }
+  }
+  return states;
+}
+
+export function readBoardSummary(runDir) {
+  try { return JSON.parse(fs.readFileSync(path.join(runDir, 'summary.json'), 'utf8').replace(/^\uFEFF/, '')); } catch { return null; }
+}
+
+export function readBoard(workspace, runId) {
+  const dir = runDirectory(workspace, runId);
+  const sum = readBoardSummary(dir);
+  if (!sum) return null;
+  return { dir, sum, taskStates: taskCheckpointStates(dir, sum) };
+}
+
+export function boardFinished(sum) {
+  return !!sum?.finishedAt && !!sum?.blocks?.every(b => TERMINAL.has(sum?.results?.[b.key]?.status || ''));
+}
+
+// --watch：只读流式看板。TTY 原地重绘完整看板；管道/--jsonl 输出机器可读行。
+// 机器可调用契约：未知 run 不许无限挂起。首次读到看板前有一个上界（graceMs /
+// ORCH_WATCH_GRACE_MS，默认 60s——覆盖「--run-windows 先规划、后建 run 目录」的竞态），
+// 超时即 fail-closed 一行诊断；已读到的运行中途丢 summary.json 也立刻报错，不静默停摆。
+export async function watchRun({ workspace, runId, intervalMs = 800, jsonl = false, out = process.stdout, graceMs = Number(process.env.ORCH_WATCH_GRACE_MS ?? 60000) }) {
+  const write = s => out.write(s);
+  const tty = !!out.isTTY && !jsonl;
+  const dir = runDirectory(workspace, runId);
+  const grace = Number.isFinite(graceMs) && graceMs >= 0 ? graceMs : 60000;
+  const startedAt = Date.now();
+  let lastSig = '', paintedLines = 0, announcedFinal = false, seen = false;
+  for (;;) {
+    const b = readBoard(workspace, runId);
+    if (b) {
+      seen = true;
+      const sig = boardSignature(b.sum, b.taskStates);
+      if (sig !== lastSig) {
+        lastSig = sig;
+        if (jsonl) write(JSON.stringify(boardJson(b.sum, b.taskStates)) + '\n');
+        else if (tty) {
+          const text = boardFullText(b.sum, b.taskStates) + '\n';
+          if (paintedLines) write('\x1b[' + paintedLines + 'A\x1b[J');
+          write(text);
+          paintedLines = text.split('\n').length - 1;
+        } else write(boardSummaryLine(b.sum, b.taskStates) + '\n');
+      }
+      if (b.sum.finishedAt) {
+        if (!jsonl && !tty && !announcedFinal) { announcedFinal = true; write('[board] run=' + runId + ' finalized success=' + (b.sum.success === true) + '\n'); }
+        return b.sum.success === true ? 0 : 1;
+      }
+    } else if (seen) {
+      throw new Error('Run ' + runId + ' lost its summary.json while being watched (dir: ' + dir + ')');
+    } else if (Date.now() - startedAt >= grace) {
+      throw new Error(fs.existsSync(dir)
+        ? 'Run ' + runId + ' has no readable summary.json (dir exists: ' + dir + ')'
+        : 'Run not found: ' + runId + ' (no run directory ' + dir + ')');
+    }
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+}