open-tui-orchestrator 0.9.6

package/scripts/core/unit-runtime.mjs

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+import {expandUnitArgs} from './unit-command.mjs';
+import {nativeArgumentLines} from './native-argv.mjs';
+
+// 调用方自助通道（caller-driven）第二半：单元运行时。
+// 与 print-class 画像同构的启动器契约（tee 日志 + token 行抓取 + result 文件 + self-closed 标记），
+// 但 argv 完全来自调用方给的命令模板：不 probe、不解析版本、不做任何适配断言。
+// 完成判定仍由主控按 token + checkpoint + 验收复检执行，绝不依赖该 CLI 的输出格式。
+
+const quote = (s) => "'" + String(s).replaceAll("'", "''") + "'";
+const TOKEN_RE = /【本块唯一标识】\s*([A-Za-z0-9][A-Za-z0-9_-]*)/;
+
+export async function runUnitPlanner(config, prompt, cwd) {
+  const unit = config?.unit || config;   // 宿主 config 里画像挂在 unit 下；直连测试可直接传画像
+  const planDir = fs.mkdtempSync(path.join(os.tmpdir(), 'orch-unit-plan-'));
+  const pf = path.join(planDir, 'planner-prompt.md');
+  fs.writeFileSync(pf, String(prompt), 'utf8');
+  const args = expandUnitArgs(unit, { prompt: String(prompt), promptFile: pf, workspace: cwd });
+  const useStdin = unit.promptDelivery === 'stdin';
+  try {
+    return await new Promise((resolve, reject) => {
+      const child = spawn(unit.bin, args, { cwd, env: process.env, windowsHide: true, shell: false, stdio: [useStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
+      if (useStdin && child.stdin) { try { child.stdin.end(String(prompt)); } catch { /* stdin closed early */ } }
+      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(); }, unit.timeoutMs ? Math.min(unit.timeoutMs, timeoutMs) : 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); }
+      });
+    });
+  } finally {
+    try { fs.rmSync(planDir, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+}
+
+export function writeUnitLauncher(config, { key, prompt, suffix, workspace, temp }) {
+  const unit = config?.unit || config;   // 宿主 config 里画像挂在 unit 下；直连测试可直接传画像
+  const stem = String(key + '-' + suffix).replace(/[^a-zA-Z0-9_-]/g, '-');
+  const token = TOKEN_RE.exec(prompt)?.[1];
+  if (!token) throw new Error((unit.label || unit.id) + ' unit 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 = expandUnitArgs(unit, { prompt, promptFile: pf, workspace });
+  const useStdin = unit.promptDelivery === 'stdin';
+  const invoke = useStdin
+    ? `$p | & ${quote(unit.bin)} @agentArgs 2>&1 | ForEach-Object { if ($_ -is [System.Management.Automation.ErrorRecord]) { $_.TargetObject } else { $_ } } | Tee-Object -FilePath $log`
+    : `& ${quote(unit.bin)} @agentArgs 2>&1 | ForEach-Object { if ($_ -is [System.Management.Automation.ErrorRecord]) { $_.TargetObject } else { $_ } } | Tee-Object -FilePath $log`;
+  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(unit.label || unit.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(',') + ')',
+    ...nativeArgumentLines(),
+    invoke,
+    '$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 };
+}

package/scripts/gate.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * gate.mjs — the machine gate the release policy refers to, runnable from inside the repo.
+ *
+ *   node scripts/gate.mjs --all          # every criterion, in order
+ *   node scripts/gate.mjs --suite        # L1: the offline regression suite
+ *   node scripts/gate.mjs --doctor       # L2a: host resolution (hostError must be null)
+ *   node scripts/gate.mjs --canary       # L2b: a deliberately failing test must go red
+ *   node scripts/gate.mjs --unknown-run  # L3: an unknown run id fails closed, cleanly
+ *   node scripts/gate.mjs --consistency  # L4: version / seal / docs / suite total agree
+ *
+ * Rules that make it a gate rather than a smoke test:
+ *   - every criterion prints command / expectation / actual;
+ *   - a value that cannot be read counts as failure ("unknown is failure");
+ *   - exit 0 only if every requested criterion passed; any failure exits 1;
+ *   - L2b keeps the criteria themselves honest: it proves a red case still goes red.
+ *
+ * Environment: the suite follows the documented convention (`ORCH_AGENT` defaults to
+ * `codex` here; the codex CLI must be resolvable — see README "Test-env requirement").
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import {coordinatorDir} from './core/leases.mjs';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const AGENT = String(process.env.ORCH_GATE_AGENT || 'codex').trim();
+const args = new Set(process.argv.slice(2));
+const wants = (flag) => args.has(flag) || args.has('--all') || args.size === 0;
+const results = [];
+
+function check(id, title, ok, lines) {
+  results.push({id, ok});
+  console.log(`  ${id} ${title}`);
+  for (const line of lines) console.log(`    ${line}`);
+  console.log(`    → ${id} ${ok ? 'PASS' : 'FAIL'}`);
+}
+
+function node(argsArr, opts = {}) {
+  const r = spawnSync(process.execPath, argsArr, {cwd: REPO, encoding: 'utf8', windowsHide: true, timeout: opts.timeout || 900000, env: opts.env || process.env});
+  return {status: r.status, out: (r.stdout || '') + (r.stderr || '')};
+}
+
+// ---------------------------------------------------------------- L1: the suite
+function suite() {
+  const files = fs.readdirSync(path.join(REPO, 'test')).filter((n) => n.endsWith('.test.mjs')).sort().map((n) => path.join('test', n));
+  const env = {...process.env, ORCH_AGENT: process.env.ORCH_AGENT || AGENT};
+  console.error(`  [gate] running ${files.length} test files (this takes minutes)…`);
+  const r = node(['--test', '--test-concurrency=3', ...files], {env});
+  const num = (key) => {
+    const m = r.out.match(new RegExp('^ℹ ' + key + ' (\\d+)$', 'm'));
+    return m ? Number(m[1]) : null;
+  };
+  const pass = num('pass'), fail = num('fail'), skipped = num('skipped'), cancelled = num('cancelled');
+  const missing = [['pass', pass], ['fail', fail], ['skipped', skipped]].filter(([, v]) => v === null).map(([k]) => k);
+  if (missing.length) return check('L1', 'offline regression suite', false, [`expected: pass>0 / fail==0 / skipped==0 / exit==0`, `actual: missing ${missing.join(', ')} ⇒ unknown is failure`]);
+  const ok = pass > 0 && fail === 0 && skipped === 0 && r.status === 0;
+  check('L1', 'offline regression suite', ok, [
+    `expected: pass>0 / fail==0 / skipped==0 / exit==0`,
+    `actual: pass=${pass} fail=${fail} skipped=${skipped} cancelled=${cancelled} exit=${r.status}`,
+  ]);
+  return pass;
+}
+
+// ------------------------------------------------- L2a: host resolution (doctor)
+function doctor() {
+  const r = node(['cli.mjs', '--agent', AGENT, '--doctor']);
+  const m = r.out.match(/"hostError"\s*:\s*(null|"[^"]*")/);
+  check('L2a', `host resolution (\`--agent ${AGENT} --doctor\`)`, !!m && m[1] === 'null', [
+    'expected: "hostError": null',
+    `actual: hostError=${m ? m[1] : 'not found'} (exit=${r.status})`,
+  ]);
+}
+
+// ----------------------------------------- L2b: the criteria themselves can go red
+function canary() {
+  const file = path.join(REPO, 'test', 'zzz-gate-canary.test.mjs');
+  fs.writeFileSync(file, "import test from 'node:test';\nimport assert from 'node:assert/strict';\n\ntest('gate canary (must fail)', () => { assert.equal(1, 2); });\n");
+  try {
+    const r = node(['--test', file]);
+    const red = r.status !== 0 && /^ℹ fail 1$/m.test(r.out);
+    check('L2b', 'red-capability canary (a failing test must fail)', red, [
+      'expected: a deliberately failing test exits non-zero with `ℹ fail 1`',
+      `actual: exit=${r.status}, fail line ${/^ℹ fail 1$/m.test(r.out) ? 'present' : 'absent'}`,
+    ]);
+  } finally {
+    fs.rmSync(file, {force: true});
+  }
+}
+
+// ------------------------------------------------------ L3: unknown run, cleanly
+function unknownRun() {
+  const id = 'nosuch-run-gate-' + Math.random().toString(16).slice(2, 8);
+  const r = node(['cli.mjs', '--verify-run', id]);
+  const frames = (r.out.match(/^\s+at /gm) || []).length;
+  const named = r.out.includes('Run not found');
+  check('L3', 'unknown run fails closed with one diagnostic line', r.status !== 0 && frames === 0 && named, [
+    'expected: non-zero exit, no Node stack frames, mentions `Run not found`',
+    `actual: exit=${r.status}, stack frames=${frames}, Run not found=${named}`,
+  ]);
+}
+
+// ----------------------------------- L4: version / seal / docs / suite total agree
+function consistency(suitePass) {
+  const read = (rel) => fs.readFileSync(path.join(REPO, rel), 'utf8');
+  const core = (read('scripts/core/contracts.mjs').match(/CORE_VERSION\s*=\s*'([^']+)'/) || [])[1];
+  const seal = JSON.parse(read('release.json'));
+  const files = Object.keys(seal.files || {}).length;
+  const runtime = Object.keys(seal.runtimeFiles || {}).length;
+  const lines = [`expected: CORE_VERSION == release.json.coreVersion; README / README-zh / release-policy carry the live version, file counts and suite total`,
+    `actual: core=${core} sealCore=${seal.coreVersion} files=${files} runtime=${runtime}`];
+  let ok = !!core && seal.coreVersion === core;
+  if (!ok) lines.push(`core version and the seal disagree ⇒ FAIL`);
+
+  const sources = {
+    'README.md': [/core is ([\d.]+), with (\d+)\/(\d+) offline tests passing/, 0, 1, 2],
+    'README-zh.md': [/当前通用核心为 ([\d.]+)，离线回归为 (\d+)\/(\d+) 通过/, 0, 1, 2],
+    'docs/release-policy.md': [/当前源码封印记录通用核心 ([\d.]+)、(\d+) 个核心文件和 (\d+) 个运行时文件。最新离线回归为 (\d+)\/(\d+) 通过/, 0, 3, 4],
+  };
+  const totals = new Set();
+  for (const [rel, [pattern, ci, pi, ti]] of Object.entries(sources)) {
+    const m = read(rel).match(pattern);
+    if (!m) { ok = false; lines.push(`${rel}: no version line found ⇒ FAIL`); continue; }
+    const g = m.slice(1);
+    if (g[ci] !== core) { ok = false; lines.push(`${rel}: core ${g[ci]} != ${core} ⇒ FAIL`); }
+    if (g[pi] !== g[ti]) { ok = false; lines.push(`${rel}: regression total is not all-green ${g[pi]}/${g[ti]} ⇒ FAIL`); }
+    totals.add(`${g[pi]}/${g[ti]}`);
+  }
+  if (totals.size > 1) { ok = false; lines.push(`the three documents disagree on the regression total ${[...totals].join(' ')} ⇒ FAIL`); }
+  else if (totals.size === 1) lines.push(`three documents agree on the regression total: ${[...totals][0]}`);
+
+  const policy = read('docs/release-policy.md').match(sources['docs/release-policy.md'][0]);
+  if (policy && (Number(policy[2]) !== files || Number(policy[3]) !== runtime)) { ok = false; lines.push(`documented seal counts ${policy[2]}/${policy[3]} != ${files}/${runtime} ⇒ FAIL`); }
+  if (suitePass !== null && totals.size === 1 && [...totals][0] !== `${suitePass}/${suitePass}`) { ok = false; lines.push(`documented total ${[...totals][0]} != measured suite ${suitePass} ⇒ FAIL`); }
+  else if (suitePass !== null) lines.push(`documented total matches the measured suite: ${suitePass}`);
+
+  // Resolving the coordinator also sweeps stale tickets (entry-time reclamation), so any
+  // ticket older than ten minutes left behind means that reclamation is broken.
+  let coordinator = null;
+  try { coordinator = coordinatorDir(REPO); } catch (error) { lines.push(`coordinator directory could not be resolved (${error.message})`); }
+  if (coordinator && fs.existsSync(coordinator)) {
+    const cutoff = Date.now() - 600000;
+    const stale = fs.readdirSync(coordinator).filter((n) => n.startsWith('lock-')).filter((n) => fs.statSync(path.join(coordinator, n)).mtimeMs < cutoff);
+    if (stale.length) { ok = false; lines.push(`${stale.length} stale mutex ticket(s) older than ten minutes survive reclamation ⇒ FAIL: ${stale.slice(0, 5).join(' ')}`); }
+    else lines.push('no stale mutex tickets in the coordinator directory');
+  } else {
+    lines.push('coordinator directory not present (nothing to sweep)');
+  }
+  check('L4', 'version / seal / docs / suite total cross-check', ok, lines);
+}
+
+let measuredSuite = null;
+if (wants('--suite')) measuredSuite = suite();
+if (wants('--doctor')) doctor();
+if (wants('--canary')) canary();
+if (wants('--unknown-run')) unknownRun();
+if (wants('--consistency')) consistency(measuredSuite);
+
+const failed = results.filter((r) => !r.ok).map((r) => r.id);
+console.log(`ORCH_GATE: ${failed.length ? 'FAIL (' + failed.join(', ') + ')' : 'PASS'} — ${results.length} criteria`);
+process.exitCode = failed.length ? 1 : 0;

package/scripts/host-cli.mjs

@@ -0,0 +1,2 @@
+// Shared implementation; do not copy logic into this adapter.
+export * from './core/host-cli.mjs';

package/scripts/install-deps.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * install-deps.mjs — 公开安装路径的「补依赖」引导实现（node-pty + codex-sdk）。
+ *
+ * 关键约束：它**不能依赖引擎**。引擎在 ORCH_AGENT=codex 时会顶层导入 @openai/codex-sdk，
+ * 缺依赖时连「装依赖」的入口都进不去（鸡生蛋）。所以本模块只依赖 node 内置模块，并且由
+ * 壳层在加载引擎**之前**调用（CLI 直接调用核内分发时也走这里，实现只有一份）。
+ *
+ * 语义：幂等（已装则回 already-present、不联网）、stdout 纯数据（进度与失败原因走 stderr）、
+ * 失败时指名手工兜底命令、只装本包自己的锁定依赖、永不触碰任何 agent CLI。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+
+const tail = (text) => String(text || '').trim().split(/\r?\n/).slice(-12).join('\n');
+
+export function installDepsCli(pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')) {
+  const scriptsDir = path.join(pkgRoot, 'scripts');
+  const shim = (name) => path.join(scriptsDir, 'node_modules', name, 'package.json');
+  // 每次现算：装前算一次的常量会把「刚装成功」误判成失败（2026-09-14 真机回归抓到）。
+  const shimPresent = () => fs.existsSync(shim('@openai/codex-sdk')) && fs.existsSync(shim('@lydell/node-pty'));
+  if (shimPresent()) {
+    console.log(JSON.stringify({ok: true, action: 'already-present', scriptsDir}));
+    return 0;
+  }
+  if (!fs.existsSync(path.join(scriptsDir, 'package-lock.json'))) {
+    console.error('[orchestrator] FATAL: package-lock.json is missing from ' + scriptsDir + '; reinstall the package');
+    return 1;
+  }
+  console.error('[orchestrator] installing locked SDK dependencies into ' + scriptsDir + ' (npm ci; network required)');
+  // 优先用随 node 一起装好的 npm-cli.js 直启：避免 shell:true 带来的 DEP0190 噪音，
+  // 也避免把路径交给 shell 拼接（scriptsDir 可能含空格）。找不到才回落到 npm.cmd + shell。
+  const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+  const useCli = fs.existsSync(npmCli);
+  // 企业镜像/自定义 npm：ORCH_NPM_BIN 显式指定优先（.cmd/.exe/路径皆可）。
+  const npmBin = String(process.env.ORCH_NPM_BIN || '').trim();
+  const npm = npmBin
+    ? spawnSync(npmBin, ['ci', '--prefix', scriptsDir], {cwd: scriptsDir, encoding: 'utf8', windowsHide: true, timeout: 900000})
+    : (useCli
+      ? spawnSync(process.execPath, [npmCli, 'ci', '--prefix', scriptsDir], {cwd: scriptsDir, encoding: 'utf8', windowsHide: true, timeout: 900000})
+      : (process.platform === 'win32'
+        // 回落也避开 shell:true（DEP0190）：显式走 cmd /d /s /c，由 cmd 自己解析 npm.cmd 与引号。
+        ? spawnSync(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', 'npm ci --prefix "' + scriptsDir + '"'], {cwd: scriptsDir, encoding: 'utf8', windowsHide: true, timeout: 900000})
+        : spawnSync('npm', ['ci', '--prefix', scriptsDir], {cwd: scriptsDir, encoding: 'utf8', windowsHide: true, timeout: 900000})));
+  if (npm.status !== 0 || !shimPresent()) {
+    const missingToolchain = npm.error && ['ENOENT', 'EINVAL'].includes(npm.error.code);
+    console.error('[orchestrator] FATAL: dependency install failed (npm exit ' + (npm.status ?? 'null') + (npm.error ? ', ' + npm.error.message : '') + ')');
+    if (tail(npm.stderr)) console.error(tail(npm.stderr));
+    console.error('[orchestrator] hint: ' + (missingToolchain ? 'install Node.js 22+ so npm is on PATH (or point ORCH_NPM_BIN at your npm), or ' : '') + 'run it manually: npm ci --prefix "' + scriptsDir + '"');
+    return 1;
+  }
+  console.log(JSON.stringify({ok: true, action: 'installed', scriptsDir}));
+  return 0;
+}
+
+export default installDepsCli;

package/scripts/maintenance-lock.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * maintenance-lock — open-tui-orchestrator 维护锁 CLI。
+ *
+ * 对编排器自身做升级/优化/维护/更新等改动前先上锁；上锁期间任何 agent 调用编排器
+ * 都只返回一句话：open-tui-orchestrator正在维护更新，本轮跳过orchestrator直接开始执行
+ *
+ *   node scripts/maintenance-lock.mjs lock [--reason "文字"] [--ttl-minutes N]
+ *   node scripts/maintenance-lock.mjs unlock
+ *   node scripts/maintenance-lock.mjs status
+ *
+ * 锁默认 180 分钟自动过期（上限 24h），过期/损坏均 fail-open 视为未锁；
+ * 路径可用 ORCH_MAINTENANCE_LOCK 覆盖（默认 ~/.open-tui-orchestrator/maintenance-lock.json）。
+ */
+import { acquireMaintenanceLock, releaseMaintenanceLock, readMaintenanceLock, maintenanceLockPath, MAINTENANCE_MESSAGE } from './core/maintenance-lock.mjs';
+
+const args = process.argv.slice(2);
+const cmd = String(args[0] || 'status').toLowerCase();
+
+function flagValue(name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+if (cmd === 'lock') {
+  const reason = String(flagValue('--reason') || '').trim();
+  const ttl = flagValue('--ttl-minutes');
+  const data = acquireMaintenanceLock({ reason, ttlMinutes: ttl === undefined ? undefined : Number(ttl) });
+  console.log('LOCKED: ' + MAINTENANCE_MESSAGE);
+  console.log(JSON.stringify({ lock: maintenanceLockPath(), reason: data.reason, startedAt: new Date(data.startedAt).toISOString(), expiresAt: new Date(data.expiresAt).toISOString() }, null, 2));
+} else if (cmd === 'unlock') {
+  const had = readMaintenanceLock().locked;
+  releaseMaintenanceLock();
+  console.log(had ? 'unlocked: maintenance lock released.' : 'unlocked: no active maintenance lock.');
+} else if (cmd === 'status') {
+  const st = readMaintenanceLock();
+  if (st.locked) {
+    console.log('LOCKED: ' + MAINTENANCE_MESSAGE);
+    console.log(JSON.stringify({ lock: maintenanceLockPath(), reason: st.reason, startedAt: st.startedAt ? new Date(st.startedAt).toISOString() : null, expiresAt: st.expiresAt ? new Date(st.expiresAt).toISOString() : null }, null, 2));
+  } else {
+    console.log('not locked' + (st.expired ? ' (previous lock expired and was cleaned up)' : '') + (st.invalid ? ' (invalid lock file ignored; fail-open)' : ''));
+  }
+} else {
+  console.log('Usage: node scripts/maintenance-lock.mjs lock [--reason "文字"] [--ttl-minutes N] | unlock | status');
+  process.exitCode = 2;
+}

package/scripts/network-policy.mjs

@@ -0,0 +1,2 @@
+// Shared implementation; do not copy logic into this adapter.
+export * from './core/network-policy.mjs';

package/scripts/open-tui-orchestrator-force.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * open-tui-orchestrator-force — technical enforcement gate for open-tui-orchestrator.
+ *
+ * The ONLY sanctioned path for REAL execution (write / build / install / test / restart / any
+ * command that changes state) is a real, visible agent TUI window launched by
+ * `--run-windows`. This guard makes that a *checkable invariant*:
+ *
+ *   - `--enable`  : arm enforcement (write the marker). Once armed, real-execution kinds are
+ *                   refused from any NON-window context.
+ *   - `--disable` : disarm.
+ *   - `--status`  : report armed state + currently alive execution windows.
+ *   - `--assert <kind>` : returns 0 (ok) / 1 (refused). A sanctioned window sets
+ *                   $env:ORCH_WINDOW=1 (its launcher does), so it passes. A non-window
+ *                   context that tries a real-execution kind gets refused with a route hint.
+ *   - `--verify <file>` : best-effort check whether a changed file was written inside a live
+ *                   sanctioned window. Reliably PASS (in a window), reliably VIOLATION (no live
+ *                   window / not in a window), or INDETERMINATE (live window exists but this is
+ *                   not that context) — never fabricates a verdict it cannot support.
+ *
+ * A window is counted as ALIVE only if it is registered in `orchestrator-windows.json` AND its
+ * pid file still exists AND `process.kill(pid, 0)` (in try/catch) confirms the process is really
+ * running. A record whose pid file exists but whose process has already exited is treated as NOT
+ * alive and dropped from results — the old "pid file exists == alive" check is gone.
+ *
+ * Combined with the hard gate on headless `--run`/`--exec` inside orchestrate-sdk.mjs
+ * (ORCH_ALLOW_HEADLESS must be `1`, verboten for real work), this is the "once the skill is
+ * enabled, real executions must go through the TUI window" enforcement.
+ *
+ * Usage (from scripts dir):  node open-tui-orchestrator-force.mjs --status | --assert <kind> | --verify <file> | --enable | --disable
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, lstatSync, renameSync, realpathSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { powershellExe, systemToolExe } from "./core/contracts.mjs";
+
+// 锚定 SystemRoot：裸名会先按进程 cwd（任意工作区）解析，防二进制投毒。
+const PS_EXE = powershellExe();
+const TASKLIST_EXE = systemToolExe("tasklist.exe");
+
+import { resolveRuntimeContext } from './runtime-context.mjs';
+import { lockedForMaintenance, readMaintenanceLock, MAINTENANCE_MESSAGE } from './core/maintenance-lock.mjs';
+const { workspace: WORKSPACE, temp: TMP, state: STATE_DIR } = resolveRuntimeContext();
+const FLAG = path.join(STATE_DIR, ".orchestrator-enabled");
+const WINDOWS_REG = path.join(STATE_DIR, "orchestrator-windows.json");
+
+// 拒绝符号链接/非常规文件，防止伪造/篡改 registry 或 marker（安全网）。
+function isRegularFile(p) { try { return lstatSync(p).isFile(); } catch { return false; } }
+function armed() {
+  if (!existsSync(FLAG) || !isRegularFile(FLAG)) return false;
+  try { return /^\d+$/.test(readFileSync(FLAG, "utf8").trim()); } catch { return false; }
+}
+function loadJson(f, d) {
+  try {
+    if (!existsSync(f)) return d;
+    if (!isRegularFile(f)) { console.error("[force] refusing non-regular/symlinked registry: " + f); return d; }
+    return JSON.parse(readFileSync(f, "utf8"));
+  } catch (e) {
+    console.error("[force] registry read/parse failed: " + f + " :: " + e.message);
+    return d;
+  }
+}
+
+// Read the PID stored in a window's pid file. Returns 0 if the record has no pidFile, the pidFile
+// is unreadable, or the stored value is not a positive integer.
+function pidOf(w) {
+  try {
+    if (!w || !w.pidFile) return 0;
+    if (!isRegularFile(w.pidFile)) return 0; // 拒绝符号链接 pidFile
+    const p = Number(String(readFileSync(w.pidFile, "utf8")).trim());
+    return Number.isFinite(p) && p >= 1 && p <= 4194304 ? p : 0; // 合理 PID 范围
+  } catch { return 0; }
+}
+// process.kill(pid, 0) inside try/catch: true only if the process is actually alive (ESRCH/throw = dead).
+function pidAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  if (process.platform === "win32") {
+    // 防伪造：仅识别“编排器工作窗”的真实进程，而非任意 powershell/codex 像。
+    try {
+      const r = spawnSync(TASKLIST_EXE, ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], { encoding: "utf8", windowsHide: true });
+      const out = String(r.stdout || "");
+      if (!/"\S+","\d+"/.test(out)) return false; // 该 PID 无对应行
+      const img = String(out.split(/\r?\n/)[0] || "").split(",")[0].replace(/"/g, "");
+      const codexish = /codex|powershell/i.test(img);
+      if (!codexish) return false;
+      // 命令行动态核对：编排器工作窗的 launcher 命令行是 `powershell -File ...\win-launch-*.ps1`
+      // （其 agent 子进程命令行不含编排器字样），故需命中 win-launch-*.ps1；同时保留 orchestrate-sdk.mjs / --run-windows 以兼容旧判定。
+      // 其它任意 powershell/codex 一律视作伪造，不得过门禁（fail-closed）。
+      // pid 已在 pidOf() 校验为 1..4194304 的合法整数，直接内联进 -Filter 安全；用 `$args[0]` 传参会
+      // 触发 PowerShell 的 -Command 解析异常（UnexpectedToken），导致 CommandLine 查询返回空，故改为内联。
+      const ps = spawnSync(PS_EXE, ["-NoProfile", "-Command", `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}" -ErrorAction SilentlyContinue).CommandLine`], { encoding: "utf8", windowsHide: true });
+      const cl = String(ps.stdout || "");
+      return /win-launch-.*\.ps1/i.test(cl) || /orchestrate-sdk\.mjs/i.test(cl) || /--run-windows/i.test(cl);
+    } catch { return false; }
+  }
+  try { process.kill(pid, 0); return true; } catch (e) { return e && (e.code === "EPERM" || e.code === "EACCES") ? true : false; } // EPERM/EACCES = 存在但无权限, 不视为 dead
+}
+// Only windows whose process is really alive are returned. A record whose pidFile exists but whose
+// process has already exited is treated as NOT alive and dropped from the result.
+function liveWindows() {
+  const reg = loadJson(WINDOWS_REG, []);
+  if (!Array.isArray(reg)) { console.error("[force] refusing: orchestrator-windows.json is not an array (fail-closed)."); return []; }
+  return reg.filter((w) => {
+    if (!w.pidFile) return false;
+    return pidAlive(pidOf(w));
+  });
+}
+
+const mode = process.argv[2];
+
+function runCli() {
+  // 维护锁：上锁期间 --assert/--verify 一律放行并回固定话术（本轮跳过 orchestrator 直接执行）；
+  // --status 显示锁状态后继续正常输出；--enable/--disable 属维护操作，不受影响。
+  if (lockedForMaintenance()) {
+    if (mode === "--assert" || mode === "--verify") {
+      console.log(MAINTENANCE_MESSAGE);
+      process.exit(0);
+    }
+    if (mode === "--status") {
+      const mlock = readMaintenanceLock();
+      console.log("maintenance lock: LOCKED" + (mlock.reason ? " (" + mlock.reason + ")" : "") + (mlock.expiresAt ? ", expires " + new Date(mlock.expiresAt).toISOString() : "") + " - " + MAINTENANCE_MESSAGE);
+    }
+  }
+  if (mode === "--enable") {
+    mkdirSync(STATE_DIR, { recursive: true });
+    // 小标记直接用 writeFileSync 覆盖写，避免 tmp+rename→rm→rename 间隙内标记缺失的竞态。
+    writeFileSync(FLAG, String(Date.now()), "utf8");
+    console.log("enforcement ARMED: real executions must go through --run-windows (visible agent TUI).");
+  } else if (mode === "--disable") {
+    try { rmSync(FLAG, { force: true }); } catch { /* ignore */ }
+    console.log("enforcement disarmed.");
+  } else if (mode === "--status") {
+    const wins = liveWindows();
+    console.log("enforcement: " + (armed() ? "ARMED" : "disarmed"));
+    console.log("alive execution windows: " + wins.length);
+    for (const w of wins) console.log("  [" + w.title + "]");
+  } else if (mode === "--assert") {
+    const kind = String(process.argv[3] || "exec").toLowerCase();
+    const realKinds = new Set(["exec", "write", "build", "install", "test", "restart", "start", "stop", "real", "all", "run"]);
+    const readKinds = new Set(["read", "analyze", "plan", "view", "query", "search", "status", "list", "preview", "ls", "show", "check", "validate", "dry-run", "help"]);
+    if (!armed()) { console.log("ok: orchestrator not armed."); process.exit(0); }
+    if (process.env.ORCH_WINDOW === "1") {
+      const wins = liveWindows();
+      if (wins.length > 0) {
+        console.log("ok: sanctioned orchestration window (" + wins.length + " live registered window(s)).");
+        process.exit(0);
+      }
+      console.log(
+        "REFUSED: ORCH_WINDOW=1 but no live registered orchestration window (orchestrator-windows.json). " +
+          "The env var alone is not accepted — it may be forged. Route through  node orchestrate-sdk.mjs --run-windows \"<request>\"  (a real, visible agent TUI window)."
+      );
+      process.exit(1);
+    }
+    if (realKinds.has(kind)) {
+      console.log(
+        "REFUSED: real execution ('" + kind + "') from a NON-orchestrator context. " +
+          "Route it through  node orchestrate-sdk.mjs --run-windows \"<request>\"  (a real, visible agent TUI window)."
+      );
+      process.exit(1);
+    }
+    // Unknown kind = fail-closed by default (a typo / future real kind must NOT silently pass).
+    if (!readKinds.has(kind)) {
+      console.log(
+        "REFUSED: unknown execution kind ('" + kind + "'); refusing by default (fail-closed). " +
+          "'read/analyze/plan/view/query/search/status/list/preview/ls/show/check/validate/dry-run/help' are read-only kinds."
+      );
+      process.exit(1);
+    }
+    console.log("ok: read-only kind.");
+  } else if (mode === "--verify") {
+    const file = process.argv[3];
+    if (!file) { console.log("Usage: open-tui-orchestrator-force.mjs --verify <file>"); process.exit(2); }
+    if (!armed()) { console.log("verify: orchestrator not armed; in-window verification not applicable."); process.exit(0); }
+    if (!existsSync(file)) { console.log("verify: file not found: " + file); process.exit(2); }
+    // 归因精化：不再「任一活窗+文件在工作区内=放行」，而是按 conflictKeys 确定归因——
+    //   仅 1 个活窗且其 conflictKeys 命中该文件 → PASS；
+    //   多个活窗 → INDETERMINATE（无法唯一归因到某个窗）；
+    //   无活窗 / 无命中 → VIOLATION（不能确认是窗内受权写入）。
+    let realFile, ws;
+    try {
+      realFile = realpathSync(file);
+      ws = realpathSync(WORKSPACE);
+    } catch (e) {
+      // fail-closed：路径解析失败无法确认归属，不得放行。
+      console.log("VIOLATION: could not resolve the file/workspace path for in-window attribution (" + (e && e.message ? e.message : "unknown") + ").");
+      process.exit(1);
+    }
+    if (realFile !== ws && !realFile.startsWith(ws + path.sep)) {
+      console.log("VIOLATION: file is outside the orchestration workspace (" + WORKSPACE + "); cannot attribute to a sanctioned in-window write.");
+      process.exit(1);
+    }
+    const wins = liveWindows();
+    const lower = realFile.toLowerCase().replace(/\\/g, "/");
+    const covering = wins.filter((w) => {
+      const rawKeys = Array.isArray(w.keys) ? w.keys.map(String) : [];
+      const keys = rawKeys.length ? rawKeys : ["__" + (w.title || "block")];
+      return keys.some((kk) => {
+        let raw = String(kk).trim().replace(/^__\s*/, "");
+        if (!raw) return false;
+        // 去掉 SDK 归约键的资源前缀（file:/dir:/port:/service:），再做路径感知匹配，不做裸子串匹配。
+        raw = raw.replace(/^(file|dir|port|service):/i, "").trim();
+        if (!raw) return false;
+        const norm = raw.toLowerCase().replace(/\\/g, "/").replace(/\/+$/, "");
+        if (!norm) return false;
+        // 路径感知：精确 / 目录前缀(带分隔符) / 文件名；裸目录名(无分隔符)按路径段匹配。
+        if (norm === lower) return true;
+        if (lower.startsWith(norm + "/")) return true;
+        if (norm === lower.split("/").pop()) return true;
+        if (!norm.includes("/") && lower.includes("/" + norm + "/")) return true;
+        return false;
+      });
+    });
+    if (wins.length === 0) {
+      console.log("VIOLATION: no live registered orchestration window exists; this change cannot be confirmed as an in-window write. Verify/re-run inside a window (node orchestrate-sdk.mjs --run-windows \"<request>\").");
+      process.exit(1);
+    }
+    if (wins.length > 1) {
+      console.log("INDETERMINATE: " + wins.length + " live orchestration window(s) exist; the change cannot be uniquely attributed to one window. Confirm per-window attribution for [" + wins.map((w) => w.title).join(", ") + "].");
+      process.exit(2);
+    }
+    // 恰好一个活窗：按其 conflictKeys 归因。
+    if (covering.length === 1) {
+      console.log("PASS: change attributed to live sanctioned orchestration window [" + (wins[0].title || "?") + "] (conflictKeys hit).");
+      process.exit(0);
+    }
+    console.log("VIOLATION: the only live orchestration window [" + (wins[0].title || "?") + "] does not cover this file's conflictKeys; cannot attribute to a sanctioned in-window write.");
+    process.exit(1);
+  } else {
+    console.log("Usage: open-tui-orchestrator-force.mjs --enable | --disable | --status | --assert <kind> | --verify <file>");
+  }
+}
+
+// Only run the CLI when this module is the main entrypoint, so open-tui-orchestrator-preflight.mjs can reuse armed()/liveWindows().
+const isMain = process.argv[1] && path.resolve(process.argv[1]).toLowerCase() === fileURLToPath(import.meta.url).toLowerCase();
+if (isMain) runCli();
+
+export { armed, liveWindows, pidAlive, pidOf, WINDOWS_REG, TMP, FLAG, STATE_DIR };