elanous 0.2.0 → 0.2.5

package/scripts/ops/channel-bot-token-migrate.ts

@@ -0,0 +1,146 @@
+import { copyFileSync, existsSync, openSync, closeSync, readFileSync, chmodSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { setElanousConfigDir } from '../../src/elanous-config-dir.js';
+import { userConfigPath } from '../../src/nexus/config/paths.js';
+import { getSecret } from '../../src/nexus/config/secrets/index.js';
+import { isSecretRef, secretIdFromRef } from '../../src/nexus/config/types.js';
+import { probeChannelBotToken, resolveChannelBotToken, storeChannelBotToken, type ChannelBotPlatform } from '../../src/channel-bot-token.js';
+
+type RawConfig = Record<string, unknown> & { tabs?: Record<string, { tokenRef?: unknown }> };
+type Candidate = {
+  platform: ChannelBotPlatform;
+  token: string;
+  id: string;
+  action: 'new-ref' | 'replace-stale-ref' | 'reuse-ref' | 'remove-empty-plaintext' | 'skipped';
+  stale?: 'invalid-form' | 'missing-secret';
+  reason?: 'no-plaintext' | 'empty-plaintext';
+};
+const PLATFORMS: ChannelBotPlatform[] = ['telegram', 'discord'];
+
+class MigrationFailure extends Error {
+  constructor(readonly reason: string, readonly platform?: ChannelBotPlatform) {
+    super(reason);
+  }
+}
+
+const USAGE = 'usage: channel-bot-token-migrate.ts [--apply] [--verify] [--config-dir DIR]';
+
+function readConfig(path: string): RawConfig {
+  return JSON.parse(readFileSync(path, 'utf8')) as RawConfig;
+}
+
+function candidates(cfg: RawConfig, checkConflicts = true): Candidate[] {
+  const found: Candidate[] = [];
+  for (const platform of PLATFORMS) {
+    const section = cfg[platform];
+    const hasPlaintext = typeof section === 'object' && section !== null && Object.hasOwn(section, 'botToken');
+    if (!hasPlaintext && checkConflicts) continue;
+    const token = hasPlaintext ? (section as Record<string, unknown>).botToken : '';
+    if (typeof token !== 'string') throw new MigrationFailure('invalid botToken', platform);
+    const ref = cfg.tabs?.[`${platform}:1`]?.tokenRef;
+    const hasRef = ref != null && ref !== '';
+    const refId = isSecretRef(ref) ? secretIdFromRef(ref) : null;
+    const stale = hasRef && !refId ? 'invalid-form'
+      : refId && getSecret(refId) === undefined ? 'missing-secret' : undefined;
+    const id = `${platform}_1__tokenRef`;
+    const action = !hasPlaintext ? 'skipped' : !token ? 'remove-empty-plaintext'
+      : stale ? 'replace-stale-ref' : refId ? 'reuse-ref' : 'new-ref';
+    const reason = !hasPlaintext ? 'no-plaintext' : !token ? 'empty-plaintext' : undefined;
+    if (token && checkConflicts) {
+      const existing = getSecret(id);
+      const referenced = refId && !stale ? getSecret(refId) : undefined;
+      if ((existing !== undefined && existing !== token) || (referenced !== undefined && referenced !== token))
+        throw new MigrationFailure('secret conflict', platform);
+      const envName = platform === 'telegram' ? 'ELANOUS_TELEGRAM_BOT_TOKEN' : 'ELANOUS_DISCORD_BOT_TOKEN';
+      const envToken = process.env[envName];
+      if (envToken && envToken !== token && existing === undefined) {
+        throw new MigrationFailure('environment token conflict', platform);
+      }
+    }
+    found.push({ platform, token, id, action, ...(stale ? { stale } : {}), ...(reason ? { reason } : {}) });
+  }
+  return found;
+}
+
+export async function migrateChannelBotTokens(apply = false): Promise<void> {
+  const path = userConfigPath();
+  if (!existsSync(path)) { console.log('No config found; nothing to migrate'); return; }
+  if (!apply) {
+    for (const entry of candidates(readConfig(path), false)) {
+      console.log(`dry-run: ${entry.platform} · action=${entry.action} · plaintext=${entry.token ? 'present' : 'absent'}${entry.stale ? ` · stale=${entry.stale}` : ''}${entry.reason ? ` · reason=${entry.reason}` : ''}`);
+    }
+    return;
+  }
+  let pending: Candidate[] = [];
+  await storeChannelBotToken(cfg => {
+    pending = candidates(cfg as RawConfig);
+    if (pending.length === 0) return [];
+    const backup = `${path}.channel-bot-token-${randomUUID()}.bak`;
+    const fd = openSync(backup, 'wx', 0o600);
+    closeSync(fd);
+    copyFileSync(path, backup);
+    chmodSync(backup, 0o600);
+    console.log(`Backup: ${backup}`);
+    return pending.map(({ platform, token }) => ({ platform, token }));
+  }, true);
+  if (pending.length === 0) { console.log('Nothing to migrate'); return; }
+  for (const { platform } of pending) console.log(`migrated: ${platform}`);
+  console.log('Bot restart required; restart manually.');
+}
+
+export async function verifyChannelBotTokens(): Promise<boolean> {
+  const cfg = readConfig(userConfigPath());
+  let failed = false;
+  let verified = 0;
+  for (const platform of PLATFORMS) {
+    const ref = cfg.tabs?.[`${platform}:1`]?.tokenRef;
+    const hasRef = ref != null && ref !== '';
+    const refId = isSecretRef(ref) ? secretIdFromRef(ref) : null;
+    const referencedSecret = refId ? getSecret(refId) : undefined;
+    if (hasRef && !referencedSecret) {
+      console.error(`${platform}: verification failed (tokenRef secret unavailable)`);
+      failed = true;
+      continue;
+    }
+    const token = resolveChannelBotToken(platform, cfg as Parameters<typeof resolveChannelBotToken>[1])?.token;
+    if (!token) continue;
+    verified++;
+    const result = await probeChannelBotToken(platform, token);
+    if (result.ok) console.log(`${platform}: ${result.botName}`);
+    else {
+      console.error(`${platform}: verification failed`);
+      failed = true;
+    }
+  }
+  if (verified === 0 && !failed) {
+    console.error('No bot credentials to verify');
+    return false;
+  }
+  return !failed;
+}
+
+if (import.meta.main) {
+  try {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--help') || argv.includes('-h')) {
+      console.log(USAGE);
+    } else {
+      const dirIdx = argv.indexOf('--config-dir');
+      if (dirIdx !== -1) {
+        if (!argv[dirIdx + 1] || argv[dirIdx + 1].startsWith('--')) throw new MigrationFailure('usage');
+        setElanousConfigDir(argv[dirIdx + 1]);
+        argv.splice(dirIdx, 2);
+      }
+      if (argv.some(arg => arg !== '--apply' && arg !== '--verify')) throw new MigrationFailure('usage');
+      if (argv.includes('--apply')) await migrateChannelBotTokens(true);
+      else if (!argv.includes('--verify')) await migrateChannelBotTokens(false);
+      if (argv.includes('--verify') && !(await verifyChannelBotTokens())) process.exitCode = 1;
+    }
+  } catch (error) {
+    // Never forward arbitrary error messages: filesystem/HTTP errors can embed credentials.
+    const platform = error instanceof MigrationFailure ? error.platform ?? 'migration' : 'migration';
+    const reason = error instanceof MigrationFailure ? error.reason : 'config, secret store or file permissions';
+    console.error(`Channel bot token migration failed: ${platform}: ${reason}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/ops-health-check.ts

@@ -24,9 +24,16 @@ import { opsHealth, type OpsAnomaly } from '../src/domains/ops-status.js';
 import { recordAutonomousActionSafe } from '../src/domains/autonomy-log.js';
 import { sendOutbound } from '../src/domains/outbound-alert.js';
 import { getUserConfig } from '../src/user-config.js';
+import { elanousStateRoot } from '../src/autopilot/state-paths.js';
 
 const LOG = join(homedir(), '.elanous/conatus/ops_health.log');
-const STATE = join(homedir(), '.elanous/ops_health_state.json');
+// `--only <kind,...>` narrows what is judged and alerted (🅢 2026-09-28: only repeated_failure — the other kinds are noise today).
+// A narrowed run keeps its own dedup signature so it never overwrites the full run's memory, and both follow the
+// same state root as the log store (ELANOUS_STATE_DIR) — a test universe must not touch the operator's signature.
+const onlyArg = (() => { const i = process.argv.indexOf('--only'); return i >= 0 ? process.argv[i + 1] : undefined; })();
+if (process.argv.includes('--only') && (!onlyArg || onlyArg.startsWith('--'))) { console.error('ops-health-check: --only needs <kind,...>'); process.exit(2); }
+const ONLY_KINDS: ReadonlySet<string> | null = onlyArg ? new Set(onlyArg.split(',').map((k) => k.trim()).filter(Boolean)) : null;
+const STATE = join(elanousStateRoot(), ONLY_KINDS ? `ops_health_state.only-${[...ONLY_KINDS].sort().join('+')}.json` : 'ops_health_state.json');
 
 function logLine(s: string): void {
   const line = `${new Date().toISOString()} ${s}`;
@@ -61,7 +68,9 @@ function attemptSelfHeal(anomalies: OpsAnomaly[]): void {
 const asJson = process.argv.includes('--json');
 const force = process.argv.includes('--force');
 
-const report = opsHealth();
+const full = opsHealth();
+const anomalies = ONLY_KINDS ? full.anomalies.filter((a) => ONLY_KINDS.has(a.kind)) : full.anomalies;
+const report = { ...full, anomalies, healthy: anomalies.length === 0 };
 
 if (asJson) {
   console.log(JSON.stringify(report, null, 2));
@@ -98,7 +107,10 @@ if (changed) {
   const msg = `⚠️ 운영 상태 경보 — 자율 시스템 이상 ${report.anomalies.length}건\n\n${lines.join('\n')}${more}\n\n관측+알림만 자동(개입=대표 결정). 상세: elanous ops health`;
   const ok = sendOutbound(msg, 'ops-health');
   logLine(`[ops-health] 대표 알림 ${ok ? '발송' : '실패'}.`);
-  saveSignature(sig);
+  // Remember the signature only once it was delivered — a failed send must retry next run, not go silent forever
+  // (measured 2026-09-28: a failed first send saved the signature and the second run went «동일 이상 지속 — 무음»).
+  if (ok) saveSignature(sig);
+  else logLine('[ops-health] 발송 실패 — 시그니처를 저장하지 않는다(다음 실행이 다시 보낸다).');
 } else {
   logLine('[ops-health] 동일 이상 지속 — 중복 알림 무음(시그니처 변화 없음).');
 }

package/scripts/pty-scenarios/run.ts

@@ -0,0 +1,272 @@
+// Tool-ladder scenarios, run for real in a fresh shell PTY (RFC drive-coding-agents §1b S1·S2·S7).
+// env profile → chooseRung → (install if missing · sudo stays human) → the task as one shell line → check the artifact.
+//
+//   bun scripts/pty-scenarios/run.ts S1 [--narrow-path] [--json] [--keep]
+//   bun scripts/pty-scenarios/run.ts S2
+//   bun scripts/pty-scenarios/run.ts S3        # rung 2 · gh · no install
+//   bun scripts/pty-scenarios/run.ts S7        # S1 on a bare VM (no MCP · no harness)
+//
+// ⛔ Not under `bun test` (NODE_ENV=test turns the PTY manifest off). Artifacts go to a temp dir.
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { EnvProfile } from '../../src/agent-mission/env-profile.js';
+import type { RungChoice } from '../../src/agent-mission/tool-ladder.js';
+import { installMissingTool, waitForPtyCompletion, type ToolInstallResult } from '../../src/agent-mission/tool-install.js';
+import { installFromDocs } from '../../src/agent-mission/doc-guided-install.js';
+import { runPtySnapshot, runPtyText } from '../../src/cli/pty-takeover-cli.js';
+import { ensureRunIdentity } from '../../src/harness/harness-space.js';
+import { emitDecision, type DecisionEvent } from '../../src/live/detail-switch.js';
+import { ptyAvailable, startPty } from '../../src/pty-shell/registry.js';
+import { envLiteral } from '../../src/platform/env-literal.js';
+
+type ScenarioId = 'S1' | 'S2' | 'S3' | 'S7' | 'S8';
+interface Scenario {
+  id: ScenarioId;
+  mission: string;
+  /** Writes the input into dir and returns what the check needs. */
+  prepare: (dir: string) => Record<string, unknown>;
+  /** The one shell line for the chosen tool (null = this tool cannot do it). */
+  line: (tool: string, dir: string) => string | null;
+  /** Checks the artifact; returns a one-line verdict. */
+  check: (dir: string, prepared: Record<string, unknown>) => { ok: boolean; detail: string };
+  /** A tool nobody pre-packaged: research its official install page, pick a line for a manager this machine has (doc-guided install). */
+  docInstall?: { tool: string; smoke: string };
+  /** Lower-rung fallback when the preferred tool cannot be installed (e.g. sudo) — with its own smallest real task. */
+  fallback?: { tool: string; cmd: string[]; expect: string };
+}
+
+const ORDERS = 'id,customer,amount\n1,kim,1200\n2,lee,350\n3,park,4800\n4,choi,75\n';
+const orderTotal = 1200 + 350 + 4800 + 75;
+
+const s1: Scenario = {
+  id: 'S1',
+  mission: '이 CSV 에서 금액 합계를 JSON 으로',
+  prepare: (dir) => { writeFileSync(join(dir, 'orders.csv'), ORDERS); return { total: orderTotal }; },
+  line: (tool, dir) => tool === 'jq'
+    ? `cd ${q(dir)} && tail -n +2 orders.csv | cut -d, -f3 | jq -s '{total: add}' > out.json`
+    : tool === 'awk'
+      ? `cd ${q(dir)} && awk -F, 'NR>1{s+=$3} END{printf "{\\"total\\": %d}\\n", s}' orders.csv > out.json`
+      : null,
+  check: (dir, prepared) => {
+    const path = join(dir, 'out.json');
+    if (!existsSync(path)) return { ok: false, detail: 'out.json 없음' };
+    try {
+      const total = (JSON.parse(readFileSync(path, 'utf8')) as { total?: unknown }).total;
+      return total === prepared.total ? { ok: true, detail: `total=${total}` } : { ok: false, detail: `total=${String(total)} (기대 ${String(prepared.total)})` };
+    } catch (e) { return { ok: false, detail: `JSON 아님: ${String(e).slice(0, 80)}` }; }
+  },
+  fallback: { tool: 'awk', cmd: ['awk', 'BEGIN{print 1+1}'], expect: '2' },
+};
+
+const s2: Scenario = {
+  id: 'S2',
+  mission: '이 영상 앞 10초를 GIF 로',
+  prepare: (dir) => {
+    // A 12s test pattern — made on the host with whatever ffmpeg the host has (input only; the task runs in the PTY).
+    // A bare machine may have no ffmpeg at all — then there is no input yet; the scenario still shows the install decision.
+    try {
+      execFileSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', '-f', 'lavfi', '-i', 'testsrc=size=320x180:rate=10:duration=12', join(dir, 'in.mp4')]);
+    } catch { return { seconds: 10, fps: 10, noInput: true }; }
+    return { seconds: 10, fps: 10 };
+  },
+  line: (tool, dir) => tool === 'ffmpeg'
+    ? `cd ${q(dir)} && ffmpeg -hide_banner -loglevel error -y -i in.mp4 -t 10 -vf fps=10,scale=240:-1 out.gif`
+    : null,
+  check: (dir, prepared) => {
+    const path = join(dir, 'out.gif');
+    if (!existsSync(path)) return { ok: false, detail: 'out.gif 없음' };
+    try {
+      const frames = Number(execFileSync('ffprobe', ['-v', 'error', '-count_frames', '-select_streams', 'v:0', '-show_entries', 'stream=nb_read_frames', '-of', 'csv=p=0', path], { encoding: 'utf8' }).trim());
+      const want = Number(prepared.seconds) * Number(prepared.fps);
+      return Math.abs(frames - want) <= 2 ? { ok: true, detail: `frames=${frames}` } : { ok: false, detail: `frames=${frames} (기대 약 ${want})` };
+    } catch (e) { return { ok: false, detail: `ffprobe 실패: ${String(e).slice(0, 80)}` }; }
+  },
+};
+
+// Rung 2: the tool already knows the answer — no install, the domain CLI is the whole job.
+const REPO = process.env.ELANOUS_SCENARIO_REPO ?? 'ElanvitalAI/elanous';
+const draftCountLine = (cutoff: string) => `gh pr list --repo ${REPO} --state open --draft --limit 500 --json number,createdAt --jq '[.[] | select(.createdAt < "${cutoff}")] | length'`;
+const s3: Scenario = {
+  id: 'S3',
+  mission: '열린 PR 중 사흘 넘은 draft 목록',
+  prepare: () => {
+    const cutoff = new Date(Date.now() - 3 * 24 * 3600 * 1000).toISOString();
+    // The answer key comes from the host's own gh, outside the PTY.
+    const expected = Number(execFileSync('sh', ['-c', draftCountLine(cutoff)], { env: envLiteral(noProxyEnv(process.env as Record<string, string>)), encoding: 'utf8' }).trim());
+    return { cutoff, expected };
+  },
+  line: (tool, dir) => tool === 'gh' ? `cd ${q(dir)} && ${draftCountLine(String(prepared3.cutoff))} > out.txt` : null,
+  check: (dir, prepared) => {
+    const path = join(dir, 'out.txt');
+    if (!existsSync(path)) return { ok: false, detail: 'out.txt 없음' };
+    const got = Number(readFileSync(path, 'utf8').trim());
+    // PRs can open or close between the two calls — one off is still the same answer.
+    return Number.isFinite(got) && Math.abs(got - Number(prepared.expected)) <= 1
+      ? { ok: true, detail: `draft>3d=${got} (호스트 ${String(prepared.expected)})` }
+      : { ok: false, detail: `draft>3d=${got} (호스트 ${String(prepared.expected)})` };
+  },
+};
+let prepared3: Record<string, unknown> = {};
+
+/** gh talks to GitHub directly; the session's proxy variables break it. */
+function noProxyEnv(env: Record<string, string>): Record<string, string> {
+  const out = { ...env };
+  for (const key of ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy']) delete out[key];
+  return out;
+}
+
+// S8: a CLI the ladder has never heard of — research, read the official page, install with what this machine has.
+const s8: Scenario = {
+  id: 'S8',
+  mission: '처음 보는 CLI mlr(Miller) 로 이 CSV 에서 금액 합계를 JSON 으로',
+  prepare: s1.prepare,
+  docInstall: { tool: 'mlr', smoke: "printf 'a,b\\n1,2\\n' | mlr --icsv --ojson cat" },
+  line: (tool, dir) => tool === 'mlr'
+    ? `cd ${q(dir)} && mlr --icsv --ojson --no-jlistwrap stats1 -a sum -f amount then rename amount_sum,total orders.csv > out.json`
+    : null,
+  check: s1.check,
+};
+
+const SCENARIOS: Record<ScenarioId, Scenario> = { S1: s1, S2: s2, S3: s3, S7: { ...s1, id: 'S7' }, S8: s8 };
+
+const cliPath = join(import.meta.dir, '../../bin/elanous.mjs');
+
+/** Step 0 is the landed CLI (`agent-mission plan --json`), run with the PTY's own env so the profile sees the same PATH. */
+function planViaCli(mission: string, env: Record<string, string>): { profile: EnvProfile } & RungChoice {
+  const out = spawnSync(process.execPath, [cliPath, 'agent-mission', 'plan', '--json', mission], { env: envLiteral(env), encoding: 'utf8', timeout: 60_000 });
+  const line = (out.stdout ?? '').split('\n').filter((l) => l.startsWith('{')).pop();
+  if (out.status !== 0 || !line) throw new Error(`agent-mission plan failed (exit ${out.status}): ${(out.stderr ?? '').trim().slice(-200)}`);
+  return JSON.parse(line) as { profile: EnvProfile } & RungChoice;
+}
+
+function q(value: string): string { return `'${value.replace(/'/g, `'"'"'`)}'`; }
+
+async function snapshot(ref: string): Promise<string> { return (await runPtySnapshot(ref)).message; }
+
+/** Types one line with a completion marker and waits for it; returns the shell exit code. */
+async function runLine(ref: string, line: string, timeoutMs: number): Promise<number> {
+  const marker = `ELANOUS_SCN_${Date.now().toString(36)}_END_`;
+  const typed = await runPtyText(ref, `${line}; printf '\\n%s%s\\n' '${marker}' "$?"`, true, undefined, 'agent');
+  if (typed.exitCode) throw new Error(typed.message);
+  const screen = await waitForPtyCompletion(ref, { timeoutMs, completionMarker: marker }, snapshot);
+  const rc = new RegExp(`${marker}([0-9]+)`).exec(screen.replace(/\x1b\[[0-9;]*[A-Za-z]/g, ''))?.[1];
+  if (rc === undefined) throw new Error('exit marker missing');
+  return Number(rc);
+}
+
+export interface ScenarioResult {
+  scenario: ScenarioId; mission: string; rung: number; tool: string | null; chosenReason: string;
+  install: ToolInstallResult['outcome'] | 'not-needed'; installReason?: string;
+  used: string | null; fallback: boolean; ok: boolean; verdict: string; seconds: number;
+  decisions: Record<string, number>; ptyId: string; os: string;
+}
+
+export async function runScenario(id: ScenarioId, opts: { narrowPath?: boolean; keep?: boolean; holdSeconds?: number; hide?: string[] } = {}): Promise<ScenarioResult> {
+  const scenario = SCENARIOS[id];
+  if (!ptyAvailable()) throw new Error('node-pty unavailable');
+  ensureRunIdentity(process.env);
+  // A one-shot process must attach the logs.db sink itself — otherwise every decision and install log vanishes silently.
+  try { const { registerStandaloneLogSink } = await import('../../src/domains/standalone-log-sink.js'); await registerStandaloneLogSink('pty-scenarios'); } catch { /* observation must not stop the run */ }
+  const started = performance.now();
+  const decisions: Record<string, number> = {};
+  const decision = (event: DecisionEvent) => { decisions[event.kind] = (decisions[event.kind] ?? 0) + 1; emitDecision(event); };
+  const dir = mkdtempSync(join(tmpdir(), `elanous-${id.toLowerCase()}-`));
+  const prepared = scenario.prepare(dir);
+  if (id === 'S3') prepared3 = prepared;
+
+  // --narrow-path drops package-manager bins so the shell has to find (or install) the tool itself.
+  const env: Record<string, string> = { ...noProxyEnv(process.env as Record<string, string>), PS1: '$ ', PROMPT: '$ ' };
+  if (opts.narrowPath) env.PATH = '/usr/bin:/bin:/usr/sbin:/sbin';
+  // --hide <tool> puts a stub first on PATH that answers «not found» — to walk the fallback path on a machine that has everything.
+  if (opts.hide?.length) {
+    const shim = join(dir, '.hide');
+    mkdirSync(shim, { recursive: true });
+    for (const tool of opts.hide) { const f = join(shim, tool); writeFileSync(f, `#!/bin/sh\necho "${tool}: hidden for this scenario" >&2\nexit 127\n`); chmodSync(f, 0o755); }
+    env.PATH = `${shim}:${env.PATH ?? ''}`;
+  }
+
+  const choice = planViaCli(scenario.mission, env);
+  const profile = choice.profile;
+  decision({ kind: 'ROUTE', what: `칸 ${choice.rung} · ${choice.tool ?? '—'}`, reason: choice.reason, purpose: '가장 낮은 칸으로 끝낸다', target: choice.tool ?? 'harness' });
+  const pty = startPty({ cmd: '/bin/sh', args: ['-i'], kind: 'shell', nickname: `scenario-${id.toLowerCase()}`, accessMode: 'auto', cols: 140, rows: 40, env, workdir: dir });
+  const ref = pty.id;
+  console.error(`[scenario] ${id} pty=${ref} run=${process.env.ELANOUS_RUN_ID ?? '?'}`);
+  let install: ScenarioResult['install'] = 'not-needed';
+  let installReason: string | undefined;
+  let used: string | null = choice.tool;
+  let fallback = false;
+  try {
+    await new Promise((resolve) => setTimeout(resolve, 400));
+    if (scenario.docInstall) {
+      const doc = await installFromDocs({ tool: scenario.docInstall.tool, smoke: scenario.docInstall.smoke, ptyRef: ref }, {
+        typeLine: async (r, line) => { const t = await runPtyText(r, line, true, undefined, 'agent'); if (t.exitCode) throw new Error(t.message); },
+        waitIdle: (r, o) => waitForPtyCompletion(r, o, snapshot),
+        decision,
+      });
+      install = doc.outcome === 'dry-run' ? 'failed' : doc.outcome;
+      installReason = `${doc.line ?? '—'} · ${doc.url ?? '—'} · ${doc.reason.slice(0, 120)}`;
+      used = doc.outcome === 'installed' ? scenario.docInstall.tool : null;
+    } else if (choice.tool) {
+      const result = await installMissingTool({ tool: choice.tool as never, ptyRef: ref }, {
+        typeLine: async (r, line) => { const t = await runPtyText(r, line, true, undefined, 'agent'); if (t.exitCode) throw new Error(t.message); },
+        waitIdle: (r, o) => waitForPtyCompletion(r, o, snapshot),
+        decision,
+      });
+      install = result.outcome;
+      installReason = result.reason;
+      if (result.outcome === 'escalate' || result.outcome === 'failed') {
+        // The preferred tool needs a human (sudo / no remedy) — take the next lower tool that already works.
+        // Same PATH as the PTY; the install module only knows its own tools, so the fallback carries its own check.
+        const probe = scenario.fallback && spawnSync(scenario.fallback.cmd[0]!, scenario.fallback.cmd.slice(1), { env: envLiteral(env), encoding: 'utf8', timeout: 10_000 });
+        if (scenario.fallback && probe && probe.status === 0 && probe.stdout.trim() === scenario.fallback.expect) {
+          used = scenario.fallback.tool;
+          fallback = true;
+          decision({ kind: 'ROUTE', what: `${choice.tool} 대신 ${scenario.fallback.tool}`, reason: result.reason, purpose: '사람을 기다리지 않고 같은 칸의 다른 도구로', target: scenario.fallback.tool });
+        } else used = null;
+      }
+    }
+    const line = used ? scenario.line(used, dir) : null;
+    let verdict: { ok: boolean; detail: string };
+    if (!line) verdict = { ok: false, detail: `이 칸에 쓸 도구가 없다(${choice.tool ?? '—'} · ${installReason ?? ''})` };
+    else {
+      const rc = await runLine(ref, line, 120_000);
+      verdict = rc === 0 ? scenario.check(dir, prepared) : { ok: false, detail: `셸 exit ${rc}` };
+    }
+    decision({ kind: 'VERIFY', what: `${id} 산출물 확인`, reason: verdict.detail, purpose: '산출물을 직접 잰다', target: 'shell' });
+    if (opts.holdSeconds) await new Promise((resolve) => setTimeout(resolve, opts.holdSeconds! * 1000));
+    return {
+      scenario: id, mission: scenario.mission, rung: choice.rung, tool: choice.tool, chosenReason: choice.reason,
+      install, ...(installReason ? { installReason } : {}), used, fallback,
+      ok: verdict.ok, verdict: verdict.detail, seconds: Math.round((performance.now() - started) / 100) / 10,
+      decisions, ptyId: ref, os: profile.os,
+    };
+  } finally {
+    pty.kill();
+    if (!opts.keep) rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function table(r: ScenarioResult): string {
+  const d = Object.entries(r.decisions).map(([k, n]) => `${k} ${n}`).join(' · ');
+  return [
+    `| 시나리오 | 칸 | 도구(→실제) | 설치 | 결과 | 소요 | 판단 |`,
+    `|---|---|---|---|---|---|---|`,
+    `| ${r.scenario} «${r.mission}» | ${r.rung} | ${r.tool ?? '—'}${r.fallback ? ` → ${r.used}` : ''} | ${r.install}${r.installReason && r.install !== 'already' ? ` (${r.installReason.slice(0, 60)})` : ''} | ${r.ok ? "✅" : "❌"} ${r.verdict.slice(0, 120)} | ${r.seconds}s | ${d} |`,
+  ].join('\n');
+}
+
+if (import.meta.main) {
+  const id = (process.argv[2] ?? '').toUpperCase() as ScenarioId;
+  if (!(id in SCENARIOS)) { console.error('usage: bun scripts/pty-scenarios/run.ts <S1|S2|S3|S7|S8> [--narrow-path] [--hide <tool>]… [--hold <sec>] [--json] [--keep]'); process.exit(2); }
+  const arg = (name: string) => { const i = process.argv.indexOf(name); return i > 0 ? process.argv[i + 1] : undefined; };
+  const hide = process.argv.flatMap((v, i) => (process.argv[i - 1] === '--hide' ? [v] : []));
+  const result = await runScenario(id, {
+    narrowPath: process.argv.includes('--narrow-path'), keep: process.argv.includes('--keep'),
+    ...(arg('--hold') ? { holdSeconds: Number(arg('--hold')) } : {}), ...(hide.length ? { hide } : {}),
+  });
+  console.log(process.argv.includes('--json') ? JSON.stringify(result) : table(result));
+  process.exit(result.ok ? 0 : 1);
+}

package/scripts/public-export.ts

@@ -23,6 +23,7 @@ import { userInfo } from 'node:os';
 import { dirname, join, posix, resolve } from 'node:path';
 import ts from 'typescript';
 import { parse } from 'yaml';
+import { spawnSyncText } from '../src/util/spawn-sync-output.js';
 
 export interface ExportTransform {
   readonly id: string;
@@ -369,9 +370,7 @@ export function summarizeLeaks(hits: readonly LeakHit[]): Record<string, { hits:
 }
 
 function trackedFiles(root: string): string[] {
-  const listed = spawnSync('git', ['-C', root, 'ls-files', '-z'], { encoding: 'utf8' });
-  if (listed.status !== 0) throw new Error(`git ls-files failed: ${listed.stderr.trim()}`);
-  return listed.stdout.split('\0').filter(Boolean);
+  return spawnSyncText('git', ['-C', root, 'ls-files', '-z']).split('\0').filter(Boolean);
 }
 
 export function run(argv: readonly string[], root = resolve(import.meta.dir, '..')): number {

package/scripts/public-import-pr.ts

@@ -1,10 +1,12 @@
 #!/usr/bin/env bun
-/** Import a public PR patch without fetching, committing, or publishing it. */
+/** Import a public PR patch without committing or publishing it. */
 import { spawnSync } from 'node:child_process';
 import { existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, unlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join } from 'node:path';
 import { loadExportConfig, selectExportFiles, transformExportFiles } from './public-export.js';
+import { debug } from '../src/debug/log.js';
+import { spawnSyncText } from '../src/util/spawn-sync-output.js';
 
 export type ImportKind = 'clean' | 'renamed' | 'transformed' | 'outside-export';
 export interface ImportFile { publicPath: string; sourcePath?: string; kind: ImportKind; reason?: string }
@@ -83,9 +85,7 @@ function gitApply(root: string, patch: string, check = false): string | undefine
 }
 
 function trackedFiles(root: string): string[] {
-  const result = spawnSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf8' });
-  if (result.status !== 0) throw new Error(`git ls-files failed: ${result.stderr}`);
-  return result.stdout.split('\0').filter(Boolean);
+  return spawnSyncText('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf8' }).split('\0').filter(Boolean);
 }
 
 /** Classify against the real export, stage eligible edits, then write only on --apply. */
@@ -177,8 +177,82 @@ export function importPublicPatch(patch: string, root: string, apply = false, au
   } finally { rmSync(staging, { recursive: true, force: true }); }
 }
 
-/** CLI entrypoint: bun scripts/public-import-pr.ts [patch-file] --author 'Name <email>' [--apply]. */
-export function run(argv: readonly string[], root = process.cwd(), stdin?: string): number {
+interface GhResult { status: number | null; stdout: string; stderr?: string }
+interface RunDeps { gh?: (argv: readonly string[], root: string) => GhResult }
+
+function prAuthors(raw: string, databaseIdForLogin: (login: string) => number): string[] {
+  const parsed: unknown = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object' || !('commits' in parsed) || !Array.isArray(parsed.commits) || !parsed.commits.length) {
+    throw new Error('PR has no commits');
+  }
+  const unique = new Map<string, string>();
+  const seenEmails = new Set<string>();
+  for (const commit of parsed.commits) {
+    const identities = commit?.authors ?? (commit?.author ? [commit.author] : []);
+    if (!Array.isArray(identities) || !identities.length) throw new Error('PR commit has no author');
+    for (const identity of identities) {
+      const name = identity?.name?.trim();
+      const email = identity?.email?.trim();
+      const login = identity?.login?.trim() ?? identity?.user?.login?.trim();
+      const key = login ? `login:${login.toLowerCase()}` : `email:${email?.toLowerCase()}`;
+      if (unique.has(key) || (email && seenEmails.has(email.toLowerCase()))) continue;
+      const id = identity?.user?.databaseId ?? identity?.id;
+      const numericId = /^[1-9]\d*$/.test(String(id)) ? Number(id) : undefined;
+      const address = email || (login && /^[A-Za-z0-9-]+$/.test(login)
+        ? `${numericId && Number.isSafeInteger(numericId) ? numericId : databaseIdForLogin(login)}+${login}@users.noreply.github.com`
+        : undefined);
+      if (typeof name !== 'string' || !/^[^<>\r\n]+$/.test(name) || !address || !/^[^<>\s@]+@[^<>\s@]+$/.test(address)) {
+        throw new Error('PR commit author lacks a valid name or email/identity');
+      }
+      unique.set(key, `${name} <${address}>`);
+      seenEmails.add(address.toLowerCase());
+    }
+  }
+  return [...unique.values()];
+}
+
+/** CLI entrypoint: patch + --author, or --pr <number> --repo <owner/name>. */
+export function run(argv: readonly string[], root = process.cwd(), stdin?: string, deps: RunDeps = {}): number {
+  const prMode = argv.includes('--pr') || argv.includes('--repo');
+  if (prMode) {
+    const prIndex = argv.indexOf('--pr');
+    const repoIndex = argv.indexOf('--repo');
+    const pr = argv[prIndex + 1];
+    const repo = argv[repoIndex + 1];
+    const flags = argv.filter((arg) => arg === '--apply' || arg === '--dry-run');
+    if (prIndex < 0 || repoIndex < 0 || !pr || !/^[1-9]\d*$/.test(pr) || !repo ||
+        !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) ||
+        argv.length !== 4 + flags.length || flags.length > 1 ||
+        argv.some((arg, i) => (arg === '--pr' && i !== prIndex) || (arg === '--repo' && i !== repoIndex))) {
+      console.error('usage: bun scripts/public-import-pr.ts --pr <number> --repo <owner/name> [--dry-run|--apply]');
+      return 2;
+    }
+    try {
+      const gh = deps.gh ?? ((args: readonly string[], cwd: string) => spawnSync('gh', [...args], { cwd, encoding: 'utf8' }));
+      const fetch = (args: string[]): string => {
+        const result = gh(args, root);
+        if (result.status !== 0) throw new Error(result.stderr || `gh ${args[1]} failed`);
+        return result.stdout;
+      };
+      const patch = fetch(['pr', 'diff', pr, '--repo', repo]);
+      const authors = prAuthors(fetch(['pr', 'view', pr, '--repo', repo, '--json', 'commits']), (login) => {
+        const user: unknown = JSON.parse(fetch(['api', `users/${login}`]));
+        const id = user && typeof user === 'object' && 'id' in user ? user.id : undefined;
+        const resolvedLogin = user && typeof user === 'object' && 'login' in user ? user.login : undefined;
+        if (typeof id !== 'number' || !Number.isSafeInteger(id) || id <= 0 ||
+            typeof resolvedLogin !== 'string' || resolvedLogin.toLowerCase() !== login.toLowerCase()) {
+          throw new Error('GitHub user lacks a matching login or numeric database ID');
+        }
+        return id;
+      });
+      const result = importPublicPatch(patch, root, flags.includes('--apply'));
+      debug.log('public-import.pr', 'fetched', { repo, pr: Number(pr), files: result.files.length, authors: authors.length });
+      for (const file of result.files) console.log(`${file.kind}\t${file.publicPath}\t${file.sourcePath ?? '-'}${file.reason ? `\t${file.reason}` : ''}`);
+      console.log(`\nCommit message draft (not committed):\nImport public PR ${repo}#${pr}\n\nhttps://github.com/${repo}/pull/${pr}\n\n${authors.map((author) => `Co-Authored-By: ${author}`).join('\n')}`);
+      if (result.rc) console.error('import incomplete: one or more files were not applied');
+      return result.rc;
+    } catch (error) { console.error(`import failed: ${String(error)}`); return 1; }
+  }
   const apply = argv.includes('--apply');
   const authorIndex = argv.indexOf('--author');
   const author = authorIndex >= 0 ? argv[authorIndex + 1] : undefined;

package/scripts/public-leak-baseline.txt

@@ -496,7 +496,6 @@
 1	handoff-doc-link	test/integration/README.md
 1	handoff-doc-link	test/logs-timeline.test.ts
 1	handoff-doc-link	test/nexus-multi-llm-wire-smoke.test.ts
-1	handoff-doc-link	test/virtual-windows-skip-store-alt.test.ts
 1	handoff-doc-link	test/voice-wiring.test.ts
 4	pilot-tree	scripts/botlab/bot-canary.test.ts
 1	pilot-tree	scripts/botlab/bot-fault-drill.sh
@@ -704,12 +703,6 @@
 2	plan-doc-link	src/verifier/builtins/code-feedback.ts
 1	plan-doc-link	src/verifier/builtins/test-heuristic.ts
 1	plan-doc-link	src/verifier/types.ts
-1	plan-doc-link	src/virtual-windows/layout/persistence.ts
-1	plan-doc-link	src/virtual-windows/layout/presets.ts
-1	plan-doc-link	src/virtual-windows/layout/restore-planner.ts
-1	plan-doc-link	src/virtual-windows/layout/serializer.ts
-1	plan-doc-link	src/virtual-windows/layout/tree.ts
-1	plan-doc-link	src/virtual-windows/layout/types.ts
 1	plan-doc-link	src/widget-routing/terminal-pane-behavior.ts
 1	plan-doc-link	src/widgets/types.ts
 1	plan-doc-link	test/acp-session-id-unique.test.ts