elanous 0.2.35 → 0.2.37

package/src/ux-sim/skills-tools-shell-device.ts

@@ -0,0 +1,156 @@
+// ── skills-tools-shell-device — RunShell HQ 무거운 명령 가드 mock 무대 ──
+//
+// DEVICE-FIRST-STAGE 산출 장치. 부모 조각(TUI-HQ-LOCAL-HEAVY-GUARD)이
+// src/skills/tools/shell.ts 의 RunShell 정책에 넣을 «HQ 자리에서 무거운
+// 명령을 실제 자식 spawn 전에 거부하고 원격 대안을 제시» 동작을, 생산
+// 코드 무수정(운영 코드 변경 0)으로 시험하는 in-process mock 무대.
+//
+// 장치 재고(2026-10-22 실측):
+//   • src/ux-sim/headless-tui.ts — ANSI 해석·캡처. 거부 «원문»이 화면에서
+//     나올 때 재사용(본 시험은 결과 객체 원문이라 직접 쓰지 않음).
+//   • src/ux-sim/mock-seat-pty-frame.ts — 격리 PTY mock 무대. 실물 TUI
+//     무대 뒷 조각에서 재사용.
+//   • 이 장치는 위 두 장치가 못 주는 «spawn 카운트 0 ⊕ 원격 대안 ⊕
+//     격리 debug.log 거부 이벤트» 관측을 채운다.
+//
+// 배선 경계(의도적): 시험 무대 전용 — 생산 실행 경로에 연결하지 않는다.
+// 시험 파일(src/ux-sim/skills-tools-shell-device.test.ts)만 import한다.
+
+/** HQ 자리에서 실행 전 거부하는 무거운 명령 argv 패턴(하위 명령 토큰열). */
+export const HQ_HEAVY_COMMANDS: readonly (readonly string[])[] = [
+  ['self', 'gate', '--local'],
+];
+
+/** 거부 결과에 담기는 원격 대안 안내 템플릿. */
+export const REMOTE_ALTERNATIVE_TEMPLATE =
+  'run the gate from the ops harness host instead: elanous self gate (remote, not the HQ seat)';
+
+export const HQ_REJECTION_REASON =
+  'HQ 자리의 무거운 명령(self gate --local)은 실제 자식 spawn 전에 거부했다';
+
+/** elanous CLI 바이너리로 보이는 토큰(설치본 eln · elanous · bin/elanous.mjs). */
+const CLI_BIN = /(?:^|[/\\])(?:elanous|elanous\.mjs|elanous\.cjs|eln)$/;
+
+/** argv 앞의 실행 래퍼(bun/node/env …)를 벗겨 [cliBin, ...args]를 돌려준다. */
+function unwrapCliArgv(command: readonly string[]): { args: readonly string[] } | null {
+  let i = 0;
+  if (/(?:^|[/\\])env$/.test(command[0] ?? '')) {
+    i = 1;
+    while (i < command.length) {
+      const arg = command[i]!;
+      if (arg === '--') { i += 1; break; }
+      if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(arg)) { i += 1; continue; }
+      break;
+    }
+  }
+  if (command[i] === 'bun' || command[i] === 'bunx' || command[i] === 'node' || command[i] === 'npx') {
+    i += 1;
+    if (command[i] === '--bun') i += 1;
+  }
+  if (!CLI_BIN.test(command[i] ?? '')) return null;
+  return { args: command.slice(i + 1) };
+}
+
+/** 무거운 명령이면 그 args(전 CLI argv)를, 아니면 null. */
+export function matchHqHeavyCommand(
+  command: readonly string[],
+): readonly string[] | null {
+  const cli = unwrapCliArgv(command);
+  if (!cli) return null;
+  for (const pattern of HQ_HEAVY_COMMANDS) {
+    if (cli.args.length < pattern.length) continue;
+    if (pattern.every((token, k) => cli.args[k] === token)) return cli.args;
+  }
+  return null;
+}
+
+export interface DeviceSpawnResult {
+  output: string;
+  exitCode: number | null;
+}
+
+export interface DeviceLogEvent {
+  category: string;
+  event: string;
+  data: Record<string, unknown>;
+}
+
+export interface SkillsToolsShellRunResult {
+  seat: string;
+  command: readonly string[];
+  rejected: boolean;
+  rejection?: { reason: string; remoteAlternative: string };
+  output: string;
+  exitCode: number | null;
+  spawnCount: number;
+}
+
+export interface SkillsToolsShellDevice {
+  readonly seat: string;
+  run(command: readonly string[]): SkillsToolsShellRunResult;
+  spawnCount(): number;
+  logEvents(): readonly DeviceLogEvent[];
+}
+
+export interface SkillsToolsShellDeviceSpec {
+  /** 무대 자리. 'hq'(기본)면 무거운 명령 가드가 켜진다. */
+  seat?: string;
+  /** 자식 실행 mock. 기본: 성공(exit 0)하는 세이프 가짜. */
+  spawn?: (command: readonly string[]) => DeviceSpawnResult;
+}
+
+export function createSkillsToolsShellDevice(spec: SkillsToolsShellDeviceSpec = {}): SkillsToolsShellDevice {
+  const seat = spec.seat ?? 'hq';
+  const spawn = spec.spawn ?? ((command: readonly string[]): DeviceSpawnResult => ({
+    output: `spawned: ${command.join(' ')}`,
+    exitCode: 0,
+  }));
+  let spawnCount = 0;
+  const logEvents: DeviceLogEvent[] = [];
+  const isHq = seat === 'hq';
+
+  return {
+    seat,
+    spawnCount: () => spawnCount,
+    logEvents: () => [...logEvents],
+    run(command: readonly string[]): SkillsToolsShellRunResult {
+      const heavy = isHq ? matchHqHeavyCommand(command) : null;
+      if (heavy) {
+        const rejection = {
+          reason: HQ_REJECTION_REASON,
+          remoteAlternative: REMOTE_ALTERNATIVE_TEMPLATE,
+        };
+        logEvents.push({
+          category: 'shell.dispatch',
+          event: 'hq-heavy.rejected',
+          data: { command: [...command], reason: rejection.reason, remoteAlternative: rejection.remoteAlternative },
+        });
+        return {
+          seat,
+          command: [...command],
+          rejected: true,
+          rejection,
+          output: `RunShell rejected \`${heavy.join(' ')}\` on seat ${seat}: ${rejection.reason}. ${rejection.remoteAlternative}`,
+          exitCode: null,
+          spawnCount,
+        };
+      }
+      const spawned = spawn(command);
+      spawnCount += 1;
+      const runCommand = [...command];
+      logEvents.push({
+        category: 'shell.dispatch',
+        event: 'exec',
+        data: { command: runCommand, seat },
+      });
+      return {
+        seat,
+        command: runCommand,
+        rejected: false,
+        output: spawned.output,
+        exitCode: spawned.exitCode,
+        spawnCount,
+      };
+    },
+  };
+}

package/src/ux-sim/subagent-tools-device.ts

@@ -0,0 +1,81 @@
+// N03 장치 — SUBAGENT-TOOLS-EMPTY (0.2.36 · 2026-10-22 · 대표 P0).
+// 진짜 classic TUI(bare `elanous`) ⊕ fake LLM 이 Agent 도구를 «틀린 이름» tool_filter 로 부른다
+// (10-22 운영 실물: allow 5~12개를 줘도 49→0 · «0 tools · Blocked»). 판정은 같은 바이너리의 `logs --json`:
+//   mismatch  — allow 가 모르는 이름뿐 → tool-filter allowIgnored ⊕ dispatch noTools=false(도구 상속)
+//   deny-all  — 모든 도구를 deny → no-tools-refused(발사 거부 · 빈손 실행 0)
+// ⛔ 생산 로직 재구현 0 — Agent 도구·필터·레지스트리 모두 진짜 TUI 안에서 돈다.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { mockSeatPtySequence, type SeatPtySequenceEvidence } from './mock-seat-pty-sequence.js';
+import { TEST_FAKE_LLM_ENV, TEST_FAKE_LLM_RESPONSE_ENV, TEST_FAKE_LLM_TOOL_CALL_ENV } from './fake-llm.js';
+import { parseData, readLogs } from './next-tui-seat-scenarios.js';
+
+export type SubagentToolsScenario = 'mismatch' | 'zero-refused';
+
+export interface SubagentToolsSpec { scenario: SubagentToolsScenario; root: string; executable: string; entry: string }
+
+export interface SubagentToolsResult {
+  spec: SubagentToolsSpec;
+  run: SeatPtySequenceEvidence;
+  logs: ReturnType<typeof readLogs>;
+  checks: Record<string, boolean>;
+}
+
+type Row = { category?: string; event?: string; data?: string };
+
+export async function runSubagentToolsDevice(spec: SubagentToolsSpec): Promise<SubagentToolsResult> {
+  const root = resolve(spec.root);
+  mkdirSync(root, { recursive: true });
+  writeFileSync(join(root, 'config.json'), JSON.stringify({ onboarding: { completed: true }, errorReports: { enabled: false } }));
+  // zero-refused: allow [Read] ⊕ deny [Read] leaves exactly 0 whatever the host's other tool names are.
+  const toolFilter = spec.scenario === 'mismatch'
+    ? { allow: ['read_file', 'shell', 'grep_search'] }
+    : { allow: ['Read'], deny: ['Read'] };
+  const run = await mockSeatPtySequence({
+    executable: spec.executable,
+    args: [spec.entry, '--config-dir', '{root}', '--test-state-dir', '{root}'],
+    root,
+    rows: 30,
+    cols: 100,
+    env: {
+      ELANOUS_SESSION_ROOT: join(root, 'sessions'),
+      [TEST_FAKE_LLM_ENV]: '1',
+      ELANOUS_TEST_FAKE_LLM_AS_PROVIDER: '1',
+      [TEST_FAKE_LLM_RESPONSE_ENV]: '[fake-llm] 맡겼습니다',
+      // zero-refused 는 «사람이 좁히기를 켠» 경우의 0-거부 안전망을 잰다(기본은 allow 무시라 0 이 안 생긴다).
+      ...(spec.scenario === 'zero-refused' ? { ELANOUS_SUBAGENT_HONOR_ALLOW: '1' } : {}),
+      [TEST_FAKE_LLM_TOOL_CALL_ENV]: JSON.stringify({ when: '서브에이전트로', name: 'Agent', args: { description: '도구 확인', prompt: '파일 하나 읽어라', tool_filter: toolFilter } }),
+    },
+    ready: { label: 'boot', until: (s: string) => s.includes('elanous | daemon') && s.includes('❯'), timeoutMs: 90_000 },
+    quitKeys: '/exit\r',
+    exitTimeoutMs: 20_000,
+    steps: [{ label: 'delegated', text: '서브에이전트로 확인해줘', until: (s) => /✔ 완료|✘ 실패/.test(s), timeoutMs: 60_000 }],
+  });
+  const logs = readLogs({ root, executable: spec.executable, entry: spec.entry }, 'agent.spawn');
+  const rows: Row[] = logs.lines.map((l) => { try { return JSON.parse(l) as Row; } catch { return {}; } });
+  const ev = (event: string) => rows.filter((r) => r.category === 'agent.spawn' && r.event === event).map((r) => parseData<Record<string, unknown>>(r.data));
+  const filterRows = ev('tool-filter');
+  const dispatch = ev('dispatch');
+  const refused = ev('no-tools-refused');
+  const f0 = filterRows[0] ?? {};
+  const dispatchedTools = Array.isArray(dispatch[0]?.tools) ? (dispatch[0]!.tools as unknown[]).length : -1;
+  const checks: Record<string, boolean> = spec.scenario === 'mismatch'
+    ? {
+        filterObserved: filterRows.length === 1,
+        // SUBAGENT-NO-NARROWING — 모델이 넘긴 allow 는 기본 무시(이름이 맞든 틀리든).
+        allowIgnored: f0.allowIgnored === 'model-allow-ignored',
+        unknownLogged: JSON.stringify(f0.unknownAllow) === JSON.stringify(['read_file', 'shell', 'grep_search']),
+        // Full inheritance, not «some tools»: nothing removed and the child got every available tool.
+        nothingRemoved: typeof f0.available === 'number' && f0.available > 0 && f0.remaining === f0.available && f0.removed === 0,
+        childGotAllTools: dispatch.length === 1 && dispatch[0]?.noTools === false && dispatchedTools === f0.available,
+        noRefusal: refused.length === 0,
+        exitedClean: run.exitCode === 0,
+      }
+    : {
+        filterLeftZero: filterRows.length === 1 && f0.remaining === 0 && typeof f0.available === 'number' && f0.available > 0,
+        refusedOnce: refused.length === 1,
+        noDispatch: dispatch.length === 0,
+        exitedClean: run.exitCode === 0,
+      };
+  return { spec, run, logs, checks };
+}

package/src/ux-sim/task-agent-parent-host-device.ts

@@ -0,0 +1,264 @@
+import { spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { appendFileSync, chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { appendRunLedgerEntry, loadRunLedger, runLedgerDir } from '../self-implement/run-ledger.js';
+import { launchRemoteParent, preflightParentHost, resolveParentHosts, type ParentHostSetting, type SshRunner } from '../task-agent/parent-host.js';
+
+/**
+ * L2 가짜 ssh 장치 — HARNESS-PARENT-ON-MSB1 의 부모-호스트 사건(호스트 목록 해석 · 발사 전 점검 gap 통과/차단 ·
+ * 원격 부모 발사)을 고정 입력으로 주입해, 생산 함수 `resolveParentHosts`·`preflightParentHost`·`launchRemoteParent`
+ * (`src/task-agent/parent-host.ts`)를 «운영 코드 변경 0»으로 mock 무대에서 돌려 관찰한다.
+ * 장치는 운영 코드가 아니다 — 생산 함수의 질의(ssh 스크립트)에만 스크립트대로 답한다.
+ *
+ * 관측 공백(장치가 메운다): 운영 발사 경로에는 원장 기록이 없다 — 장치가 사건마다 `parent-host-run`(시작) ⊕
+ * `parent-host-evidence`(증거) 관찰 줄과 incident row 한 줄을 임시 ELANOUS_STATE_DIR 하나에만 쓰고 지운다.
+ *
+ * 현재 계약(RED 기록 대상): 원격 부모 PR 은 게이트 PASS ⊕ 리뷰 must-fix 0 이어도 HQ 에 착지 노드가 없어
+ * draft 로 남는다(10-14 06:2x 120건) — `settleHqLandingProposals` 가 «자격 PR 은 제안 1건, 미충족 PR 은
+ * 제안 0건» 경계를 HQ 착지 제안 원장에 고정한다. 실제 원장 결속이 운영 코드에 들어오면 이 시험이 그 착지의
+ * 회귀가 된다.
+ */
+export type ParentHostDeviceEventKind =
+  | 'resolve-parent-hosts'
+  | 'preflight-gap-clear'
+  | 'preflight-gap-blocked'
+  | 'launch-remote-parent';
+
+export interface ParentHostDeviceEvent {
+  kind: ParentHostDeviceEventKind;
+  host: string;
+  cwd: string;
+  /** E1 — resolveParentHosts 에 주입할 `taskAgent.parentHost` 설정(목록). */
+  config?: ParentHostSetting;
+  /** E1 — env 축(`ELANOUS_TA_PARENT_HOST`). */
+  env?: Record<string, string>;
+  /** E2/E3 — preflight 판 기준(HQ 판). */
+  localVersion?: string;
+  /** E2/E3 — HQ 발사 동결 칸. */
+  launchHoldActive?: boolean;
+  /** E2/E3 — 스크립트 장치가 발사 전 점검 질문에 답하는 key=value 사실 줄. */
+  facts?: string;
+}
+
+export interface ParentHostDeviceCall { host: string; script: string; stdin?: string }
+
+export interface ScriptedSshDevice {
+  ssh: SshRunner;
+  calls: ParentHostDeviceCall[];
+}
+
+/** 부모-호스트 고정 사건 넷 — E4(launch-remote-parent)는 로컬 sh 실제 spawn 으로 돈다. */
+export const PARENT_HOST_DEVICE_EVENTS: readonly ParentHostDeviceEvent[] = [
+  {
+    kind: 'resolve-parent-hosts', host: 'node-b', cwd: '/Users/me/source/elanous',
+    config: [{ host: 'node-b', cwd: '/Users/me/source/elanous', approvalCapacity: 2 }, { host: 'node-c', cwd: '/srv/elanous' }], env: {},
+  },
+  {
+    kind: 'preflight-gap-clear', host: 'node-b', cwd: '/Users/me/source/elanous', localVersion: '0.2.20-dev.0',
+    facts: 'version=0.2.20-dev.0\nconfig=1\npodPool=1\nrepo=1\nkubectl=1\ncodexAccounts=3\ngrok=1\nopenrouter=1\n',
+  },
+  {
+    kind: 'preflight-gap-blocked', host: 'node-c', cwd: '/srv/elanous', localVersion: '0.2.20-dev.0', launchHoldActive: true,
+    facts: 'version=0.2.19\n',
+  },
+  { kind: 'launch-remote-parent', host: 'node-b', cwd: '/Users/me/source/elanous' },
+];
+
+export function makeScriptedSshDevice(events: readonly ParentHostDeviceEvent[]): ScriptedSshDevice {
+  const calls: ParentHostDeviceCall[] = [];
+  const ssh: SshRunner = (host, script, _timeoutMs, stdin) => {
+    calls.push({ host, script, ...(stdin !== undefined ? { stdin } : {}) });
+    // 발사 전 점검 사건만 답한다 — 같은 호스트의 다른 사건(E1 해석 · E4 발사)은 점검 질문에 답하지 않는다.
+    const fixture = events.find((candidate) => candidate.host === host && candidate.facts !== undefined);
+    if (!fixture?.facts) return { status: 1, stdout: '', stderr: `no preflight fixture for host ${host}` };
+    // 점검 질문(preflightScript)에만 사실 줄로 답한다 — 그 밖의 스크립트는 조용히 성공(빈 출력).
+    if (script.includes('--version')) return { status: 0, stdout: fixture.facts, stderr: '' };
+    return { status: 0, stdout: '', stderr: '' };
+  };
+  return { ssh, calls };
+}
+
+// ── HQ 착지 제안 결속(완료 경계 · RED 조각) ─────────────────────────────────────────────
+
+/** HQ 착지 제안 원장 이벤트 — 자격 PR 마다 정확히 한 줄(제안 1건)이고 미충족 PR 은 줄이 없다(= 0건). */
+export const HQ_LANDING_PROPOSAL_EVENT = 'hq-landing-proposal';
+
+/** 같은 PR 에 대한 무대 관측 — gate 결과와 self review(must-fix 목록)가 나란히 있다. */
+export interface ParentPrObservation {
+  pr: number;
+  gate: 'PASS' | 'FAIL';
+  review: { verdict: 'pass' | 'fail'; mustFix: readonly string[] };
+}
+
+/** HQ 무대가 관측한 부모 PR 고정 입력 — 26101 만 자격, 나머지는 미충족 축(gate FAIL · must-fix > 0)마다 하나씩. */
+export const PARENT_PR_OBSERVATIONS: readonly ParentPrObservation[] = [
+  { pr: 26101, gate: 'PASS', review: { verdict: 'pass', mustFix: [] } },
+  { pr: 26102, gate: 'FAIL', review: { verdict: 'pass', mustFix: [] } },
+  { pr: 26103, gate: 'PASS', review: { verdict: 'fail', mustFix: ['같은 must-fix 서명의 재발사는 같은 수로 하지 않는다'] } },
+  { pr: 26104, gate: 'PASS', review: { verdict: 'pass', mustFix: ['좁혀 재발사할 must-fix 하나', '남은 must-fix 둘'] } },
+];
+
+export interface HqLandingProposal {
+  pr: number;
+  /** 자격 PR 의 제안 수는 정확히 1이다. */
+  proposals: 1;
+  gate: 'PASS';
+  mustFix: 0;
+}
+
+/** 이 리뷰의 must-fix 수 — 목록이 없으면 «0이 아니라 못 쟀다»(-1)로, 자격 판정에 통과로 접히지 않게 한다. */
+function mustFix(review: { mustFix?: readonly string[] }): number {
+  if (!Array.isArray(review.mustFix)) return -1;
+  return review.mustFix.filter((finding) => typeof finding === 'string' && finding.trim() !== '').length;
+}
+
+export interface HqLandingProposalSettleOptions {
+  /** 제안 원장을 쓸 런 원장 디렉터리(ux-sim mock 무대). 주어지면 제안마다 원장 줄을 쓴다. */
+  dir?: string;
+  /** 제안 원장 줄의 runId. */
+  runId?: string;
+}
+
+/**
+ * 완료 경계 코드: 게이트 PASS ⊕ 리뷰 must-fix 0 인 부모 PR 은 HQ 착지 제안 «한 건»으로 결속하고 조건을
+ * 충족하지 않은 PR(gate FAIL 또는 must-fix > 0)은 제안 0건이다. 원격 부모 PR 이 draft 로 남는 현재 계약을
+ * 닫는 결속 규칙 — 장치(mock 무대)가 운영 코드 변경 0으로 이 경계를 원장에 고정한다.
+ */
+export function settleHqLandingProposals(observations: readonly ParentPrObservation[], options: HqLandingProposalSettleOptions = {}): readonly HqLandingProposal[] {
+  const proposals: HqLandingProposal[] = [];
+  for (const observation of observations) {
+    if (!Number.isSafeInteger(observation.pr) || observation.pr <= 0) throw new Error(`invalid parent PR number: ${String(observation.pr)}`);
+    if (observation.gate !== 'PASS') continue;
+    if (observation.review.verdict !== 'pass') continue;
+    if (mustFix(observation.review) !== 0) continue;
+    proposals.push({ pr: observation.pr, proposals: 1, gate: observation.gate, mustFix: 0 });
+  }
+  if (options.dir !== undefined) {
+    if (!options.runId) throw new Error('runId is required to record HQ landing proposals');
+    for (const proposal of proposals) {
+      appendRunLedgerEntry({ runId: options.runId, event: HQ_LANDING_PROPOSAL_EVENT,
+        data: { pr: proposal.pr, proposals: proposal.proposals, gate: proposal.gate, mustFix: proposal.mustFix } }, options.dir);
+    }
+  }
+  return proposals;
+}
+
+/** 제안 원장을 PR 번호 → 제안 수로 접는다(완료 경계 실물 비교의 읽기). 줄이 없는 PR 은 맵에 없다(= 0건). */
+export function hqLandingProposalCountByPr(entries: readonly { event: string; data: Record<string, unknown> }[]): ReadonlyMap<number, number> {
+  const counts = new Map<number, number>();
+  for (const entry of entries) {
+    if (entry.event !== HQ_LANDING_PROPOSAL_EVENT) continue;
+    const pr = entry.data.pr;
+    const proposals = entry.data.proposals;
+    if (typeof pr !== 'number' || !Number.isSafeInteger(pr) || typeof proposals !== 'number' || !Number.isSafeInteger(proposals) || proposals < 1) continue;
+    counts.set(pr, (counts.get(pr) ?? 0) + proposals);
+  }
+  return counts;
+}
+
+// ── E사다리: 사건 하나를 «생산 경로 그대로» 돌린다 ───────────────────────────────────────
+
+export interface ParentHostIncidentObservation {
+  readonly injectionId: string;
+  readonly kind: ParentHostDeviceEventKind;
+  readonly host: string;
+  /** 이 사건이 실제 운영 경로에서 관측한 결과(호스트 목록 · preflight 판정 · 발사 영수증). */
+  readonly observed: Readonly<Record<string, unknown>>;
+  /** 장치가 임시 원장에 쓴 관찰 이벤트 이름(`parent-host-run` ⊕ `parent-host-evidence`). */
+  readonly ledgerEvents: readonly string[];
+  /** 이 런의 `incidents/YYYY-MM-DD.jsonl` 줄 원문. */
+  readonly incidentLine: string;
+  readonly incidentRows: number;
+}
+
+/** E4 실제 spawn — 원격 발사 스크립트를 진짜 셸(ssh 대신 로컬 sh · HOME = 임시 원격 홈)에서 돈다. */
+function realShellSsh(remoteHome: string): SshRunner {
+  return (_host, script, timeoutMs, stdin) => {
+    // ProcessEnv 의 ambient NODE_ENV 요구는 이 원격 홈의 몫이 아니다(pod-device 패턴: `{} as NodeJS.ProcessEnv`).
+    const result = spawnSync('sh', ['-c', script], {
+      encoding: 'utf8', timeout: timeoutMs, ...(stdin !== undefined ? { input: stdin } : {}),
+      env: Object.assign({} as NodeJS.ProcessEnv, { PATH: process.env.PATH ?? '/usr/bin:/bin', HOME: remoteHome }),
+    });
+    return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+  };
+}
+
+/** 임시 원격 홈 — 설치본 경로(`$HOME/.local/share/elanous/bin/elanous`)에 살아 있는 부모 흉내 스크립트. */
+function fakeRemoteHome(): { home: string; cwd: string } {
+  const home = mkdtempSync(join(tmpdir(), 'ux-sim-parent-host-remote-'));
+  const bin = join(home, '.local/share/elanous/bin');
+  mkdirSync(bin, { recursive: true });
+  writeFileSync(join(bin, 'elanous'), '#!/bin/sh\necho "args: $*"; echo "run=$ELANOUS_RUN_ID"; sleep 5\n');
+  chmodSync(join(bin, 'elanous'), 0o755);
+  const cwd = join(home, 'repo');
+  mkdirSync(cwd);
+  return { home, cwd };
+}
+
+/** incident row 한 줄 — 임시 무대의 `incidents/YYYY-MM-DD.jsonl` 에 붙인다(운영 incidents 저장소 무접촉). */
+function recordParentHostIncident(root: string, row: Record<string, unknown>): void {
+  const dir = join(root, 'incidents');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, `${new Date().toISOString().slice(0, 10)}.jsonl`), `${JSON.stringify(row)}\n`, 'utf8');
+}
+
+/**
+ * 한 사건을 «생산 경로 그대로» 돌린다: 진짜 `resolveParentHosts` · 진짜 `preflightParentHost`(ssh = 이 장치) ·
+ * 진짜 `launchRemoteParent`(ssh = 로컬 sh 실제 spawn) → 장치가 쓴 관찰 원장(`parent-host-run` ⊕
+ * `parent-host-evidence`) → incident JSONL 한 줄. 실 ssh·원격 호스트·LLM·네트워크 0 · 쓰기는 임시
+ * ELANOUS_STATE_DIR 하나에만 가고 지운다.
+ */
+export async function simParentHostIncident(kind: ParentHostDeviceEventKind): Promise<ParentHostIncidentObservation> {
+  const fixture = PARENT_HOST_DEVICE_EVENTS.find((event) => event.kind === kind);
+  if (!fixture) throw new Error(`no device event: ${kind}`);
+  const suffix = randomBytes(4).toString('hex');
+  const runId = `run-sim-parent-host-${suffix}`;
+  const injectionId = `parent-host:${kind}:${suffix}`;
+  const root = mkdtempSync(join(tmpdir(), 'ux-sim-parent-host-'));
+  const ledgerDir = runLedgerDir(root);
+  let remote: { home: string; cwd: string } | undefined;
+  let launchedPid: number | undefined;
+  const previousStateDir = process.env.ELANOUS_STATE_DIR;
+  process.env.ELANOUS_STATE_DIR = root;
+  try {
+    let observed: Record<string, unknown>;
+    if (kind === 'resolve-parent-hosts') {
+      // ProcessEnv 의 ambient NODE_ENV 요구는 이 사건 env 의 몫이 아니다(pod-device 패턴).
+      observed = { hosts: resolveParentHosts(fixture.config, Object.assign({} as NodeJS.ProcessEnv, fixture.env ?? {})).map((target) => target.host) };
+    } else if (kind === 'preflight-gap-clear' || kind === 'preflight-gap-blocked') {
+      const device = makeScriptedSshDevice([fixture]);
+      const preflight = preflightParentHost({ target: { host: fixture.host, cwd: fixture.cwd },
+        localVersion: fixture.localVersion ?? '0.2.20-dev.0', launchHoldActive: fixture.launchHoldActive ?? false, ssh: device.ssh });
+      observed = { ok: preflight.ok, gaps: preflight.gaps, warnings: preflight.warnings };
+    } else {
+      remote = fakeRemoteHome();
+      const launched = launchRemoteParent({ host: fixture.host, cwd: remote.cwd },
+        ['harness', 'say', '--merge-by-host', `ux-sim ${injectionId}`], { ELANOUS_RUN_ID: runId }, realShellSsh(remote.home));
+      launchedPid = launched.pid;
+      const log = readFileSync(join(remote.home, '.elanous', 'remote-parents', `${runId}.log`), 'utf8');
+      observed = { pid: launched.pid,
+        argsRewritten: log.includes('--no-auto-merge') && !log.includes('--merge-by-host'),
+        runIdEchoed: log.includes(`run=${runId}`) };
+    }
+    appendRunLedgerEntry({ runId, event: 'parent-host-run', data: { kind, host: fixture.host, feature: `ux-sim ${injectionId}` } }, ledgerDir);
+    appendRunLedgerEntry({ runId, event: 'parent-host-evidence', data: { kind, host: fixture.host, observed } }, ledgerDir);
+    recordParentHostIncident(root, { at: new Date().toISOString(), runId, reason: `ux-sim ${injectionId}`,
+      parentHost: { kind, host: fixture.host, ...observed } });
+    const ledgerEvents = (loadRunLedger(runId, ledgerDir) ?? []).map((entry) => entry.event);
+    const incidents = join(root, 'incidents');
+    const lines = (existsSync(incidents) ? readdirSync(incidents) : []).flatMap((file) => readFileSync(join(incidents, file), 'utf8').split('\n')).filter(Boolean);
+    return { injectionId, kind, host: fixture.host, observed, ledgerEvents,
+      incidentLine: lines.find((line) => line.includes(runId)) ?? '', incidentRows: lines.length };
+  } finally {
+    if (launchedPid !== undefined) {
+      // 살아 있던 부모 흉내(sleep 5)는 여기서 끈다 — 임시 무대 밖 프로세스를 남기지 않는다.
+      try { process.kill(launchedPid); } catch { /* 이미 끝남 */ }
+    }
+    if (remote) rmSync(remote.home, { recursive: true, force: true });
+    if (previousStateDir === undefined) delete process.env.ELANOUS_STATE_DIR;
+    else process.env.ELANOUS_STATE_DIR = previousStateDir;
+    rmSync(root, { recursive: true, force: true });
+  }
+}

package/src/ux-sim/task-agent-rejudge-on-head-device.ts

@@ -0,0 +1,114 @@
+import { REJUDGE_HEAD_CAP } from '../task-agent/rejudge-on-head.js';
+import { reviewResultPath } from '../task-agent/review-result-capture.js';
+
+/**
+ * TA-REJUDGE-ON-HEAD ux-sim mock 장치(L2) — 부모 칸에서 물려받은 리뷰 회차 상한 완료 경계를
+ * 고정 입력 격리 카드로 검증한다.
+ *
+ * - 왜: 재판정의 상한 논리는 `src/task-agent/rejudge-on-head.ts` 에 성숙하게 존재한다(재게이트 상한
+ *   `REJUDGE_HEAD_CAP` · `regateUnmeasured` «못 잰 것은 상한에 안 센다» · `cap-reached … needs owner`).
+ *   이 장치는 그 계약을 «중복 구현하지 않고» import 로 소비·재사용한다 — 같은 카드 자리의
+ *   `<state>/review-results/<card>-<pr>-<head12>.json` 근거 경로는 기존 `reviewResultPath` 를 그대로 쓴다.
+ * - 계약: 같은 PR 에서 «저장 완료»된 review-results 원문 회차가 `REVIEW_ROUND_CAP`(5) 에 닿으면
+ *   `requestReview` 전에 추가 리뷰를 막는다(요청 0건 · reviewer 호출 0회) — cap-reached · 근거 경로 ·
+ *   다음 판단 필요(nextDecisionNeeded) 상태와 원장 이유를 남긴다. 기존 head 와 저장 5건은 보존한다.
+ * - 파일 미회수(결과 파일을 회수하지 못한 회차)는 0회로 센다 — 상한에 오판으로 넣지 않는다.
+ * - 장치는 운영 코드가 아니다 — 이 모듈의 유일한 호출자는 같은 무대의 mock 시험
+ *   `task-agent-rejudge-on-head-device.test.ts` 다(DEVICE-FIRST-STAGE 의도적 경계).
+ */
+
+/** 한 PR 의 저장 완료된 리뷰 회차 상한 — 부모 칸의 완료 경계(원문 5회). */
+export const REVIEW_ROUND_CAP = 5;
+
+export interface StoredReviewResult {
+  pr: number;
+  head: string;
+  /** 회수되어 reviewed 판정이 난 회차만 저장 완료로 센다. */
+  reviewed?: boolean;
+  verdict?: string;
+  resultPath?: string;
+  /** 결과 파일을 회수하지 못한 회차 — 0회로 센다(상한에 안 넣는다). */
+  unrecovered?: boolean;
+}
+
+export interface RejudgeOnHeadIsolationCard {
+  id: string;
+  statePath: string;
+  pr: number;
+  head: string;
+  reviewRequests: readonly StoredReviewResult[];
+}
+
+export type RejudgeOnHeadDeviceDecision = 'review-allowed' | 'cap-reached';
+
+export interface RejudgeOnHeadDeviceReport {
+  card: string;
+  pr: number;
+  head: string;
+  decision: RejudgeOnHeadDeviceDecision;
+  /** 유효한 저장 완료 review-results 회차 수(미회수 제외). */
+  storedCompleted: number;
+  /** 회수되지 않은 회차 수 — 0회로 세므로 저장 완료 수에 들지 않는다. */
+  unrecovered: number;
+  /** 이번 review tick 에 requestReview 전에 남는 추가 요청 수 — cap-reached 면 0. */
+  reviewRequestsAllowed: number;
+  /** reviewer 호출 수 — cap-reached 면 requestReview 가 막혀 0회. */
+  reviewerCalls: number;
+  evidencePath: string;
+  nextDecisionNeeded: boolean;
+  reason: string;
+  ledgerReason: string;
+  /** 소비·재사용하는 기존 task-agent 재게이트 상한 계약값. */
+  rejudgeHeadCap: number;
+}
+
+/** 저장 완료 회차와 미회수 회차를 센다 — 미회수·다른 PR 은 저장 완료에서 뺀다. */
+export function countStoredCompletedReviews(card: RejudgeOnHeadIsolationCard): { storedCompleted: number; unrecovered: number } {
+  const entries = card.reviewRequests.filter((entry) => entry.pr === card.pr);
+  const completed = entries.filter((entry) => entry.reviewed === true
+    && ['pass', 'warn', 'fail'].includes(String(entry.verdict ?? ''))
+    && entry.unrecovered !== true && typeof entry.resultPath === 'string' && entry.resultPath !== '');
+  const unrecovered = entries.filter((entry) => entry.unrecovered === true).length;
+  return { storedCompleted: completed.length, unrecovered };
+}
+
+/** 격리 카드 하나를 이번 review tick 판단으로 옮긴다 — 저장 완료 5회면 cap-reached 로 막는다. */
+export function rejudgeOnHeadDevice(card: RejudgeOnHeadIsolationCard): RejudgeOnHeadDeviceReport {
+  const { storedCompleted, unrecovered } = countStoredCompletedReviews(card);
+  const evidencePath = reviewResultPath(card.statePath, card.id, card.pr, card.head);
+  const base = {
+    card: card.id, pr: card.pr, head: card.head, storedCompleted, unrecovered,
+    evidencePath, rejudgeHeadCap: REJUDGE_HEAD_CAP,
+  };
+  if (storedCompleted >= REVIEW_ROUND_CAP) {
+    return {
+      ...base,
+      decision: 'cap-reached',
+      reviewRequestsAllowed: 0,
+      reviewerCalls: 0,
+      nextDecisionNeeded: true,
+      reason: `reviewed ${storedCompleted} rounds already (cap ${REVIEW_ROUND_CAP} · unmeasured ${unrecovered} not counted) — no more review; needs owner`,
+      ledgerReason: `cap-reached: stored review-results ${storedCompleted}/${REVIEW_ROUND_CAP} · head ${card.head.slice(0, 12)} preserved · unrecovered ${unrecovered} counted 0`,
+    };
+  }
+  return {
+    ...base,
+    decision: 'review-allowed',
+    reviewRequestsAllowed: 1,
+    reviewerCalls: 1,
+    nextDecisionNeeded: false,
+    reason: `stored review-results ${storedCompleted}/${REVIEW_ROUND_CAP} — existing requestReview call path preserved`,
+    ledgerReason: `review-allowed: stored review-results ${storedCompleted}/${REVIEW_ROUND_CAP} · unrecovered ${unrecovered} counted 0`,
+  };
+}
+
+/** requestReview 게이트 — cap-reached 면 reviewer 를 부르지 않고 요청 0건을 돌려준다. */
+export function deviceRequestReview(
+  card: RejudgeOnHeadIsolationCard,
+  callReviewer: () => void,
+): { requested: 0 | 1; decision: RejudgeOnHeadDeviceDecision; report: RejudgeOnHeadDeviceReport } {
+  const report = rejudgeOnHeadDevice(card);
+  if (report.decision === 'cap-reached') return { requested: 0, decision: report.decision, report };
+  callReviewer();
+  return { requested: 1, decision: report.decision, report };
+}