elanous 0.2.42 → 0.2.43

package/src/tui/sidetab/herdr-portal.ts

@@ -0,0 +1,225 @@
+import { defaultHerdrCliRunner, type HerdrCliRunner } from '../../pty-shell/herdr-prompt.js';
+import type { SidetabRow } from '../../sidetab-core/model.js';
+
+const HERDR_ROW_PREFIX = 'herdr:';
+const SNAPSHOT_TIMEOUT_MS = 1_500;
+const PANE_READ_TIMEOUT_MS = 1_000;
+const PANE_INPUT_TIMEOUT_MS = 1_000;
+
+export type HerdrSidetabStatus =
+  | 'working' | 'idle' | 'needs-approval' | 'done-verified' | 'done-unverified' | 'stopped' | 'unknown';
+
+export interface HerdrPaneSnapshot {
+  readonly pane_id: string;
+  readonly workspace_id?: string;
+  readonly agent?: string;
+  readonly agent_status?: string;
+  readonly terminal_title?: string;
+  readonly terminal_title_stripped?: string;
+  readonly cwd?: string;
+  readonly alive?: boolean;
+  readonly cost_usd?: number;
+  readonly costUsd?: number;
+  readonly cost?: number;
+  readonly [key: string]: unknown;
+}
+
+export interface HerdrSidetabPortalOptions {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly run?: HerdrCliRunner;
+  /** Independent completion evidence; Herdr's own `done` report is never treated as verification. */
+  readonly isVerified?: (pane: HerdrPaneSnapshot) => boolean;
+  readonly log?: (event: string, data: Record<string, unknown>) => void;
+}
+
+export interface HerdrSidetabPortal {
+  enabled(): boolean;
+  refreshRows(): Promise<readonly SidetabRow[]>;
+  rows(): readonly SidetabRow[];
+  readPane(paneId: string): Promise<string>;
+  sendText(paneId: string, text: string): Promise<void>;
+  sendKey(paneId: string, key: string): Promise<void>;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function paneRowsFromSnapshot(value: unknown): HerdrPaneSnapshot[] {
+  const root = asRecord(value);
+  const result = asRecord(root?.result);
+  if (!result) throw new Error('Herdr snapshot 형식 오류 · result 객체가 없습니다');
+  const session = asRecord(result?.session_snapshot);
+  const panes = result?.panes ?? session?.panes;
+  if (!Array.isArray(panes)) throw new Error('Herdr snapshot 형식 오류 · panes 배열이 없습니다');
+  const invalidPane = panes.findIndex((candidate) => {
+    const pane = asRecord(candidate);
+    return typeof pane?.pane_id !== 'string' || pane.pane_id.length === 0;
+  });
+  if (invalidPane >= 0) throw new Error(`Herdr snapshot 형식 오류 · panes[${invalidPane}].pane_id가 없습니다`);
+  return panes as HerdrPaneSnapshot[];
+}
+
+function statusOf(pane: HerdrPaneSnapshot, verified: boolean): HerdrSidetabStatus {
+  const state = (pane.agent_status ?? '').trim().toLowerCase().replaceAll('_', '-');
+  // Approval is a first-class state. Never collapse it into idle, even if a pane has no running process.
+  if (state === 'blocked' || state === 'needs-approval' || state === 'approval-required') return 'needs-approval';
+  // A completed pane remains completed after its process exits. Herdr's `done` is not verification.
+  if (state === 'done' || state === 'complete' || state === 'completed') return verified ? 'done-verified' : 'done-unverified';
+  if (pane.alive === false || state === 'stopped' || state === 'exited') return 'stopped';
+  if (state === 'working' || state === 'busy') return 'working';
+  if (state === 'idle') return 'idle';
+  return 'unknown';
+}
+
+function displayState(status: HerdrSidetabStatus): { badge: SidetabRow['badge']; label: string } {
+  switch (status) {
+    case 'working': return { badge: 'busy', label: '실행 중' };
+    case 'idle': return { badge: 'idle', label: '대기' };
+    case 'needs-approval': return { badge: 'busy', label: '승인 필요' };
+    case 'done-verified': return { badge: 'idle', label: '검증 완료' };
+    case 'done-unverified': return { badge: 'unknown', label: '미검증 완료' };
+    case 'stopped': return { badge: 'exited', label: '멈춤' };
+    case 'unknown': return { badge: 'unknown', label: '상태 미상' };
+  }
+}
+
+function finiteCost(pane: HerdrPaneSnapshot): number | undefined {
+  for (const value of [pane.cost_usd, pane.costUsd, pane.cost]) {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return value;
+  }
+  return undefined;
+}
+
+function rowFromPane(pane: HerdrPaneSnapshot, verified: boolean): SidetabRow {
+  const status = statusOf(pane, verified);
+  const display = displayState(status);
+  const title = pane.terminal_title_stripped || pane.terminal_title || pane.agent || pane.pane_id;
+  const cost = finiteCost(pane);
+  const costText = cost === undefined ? '비용 —' : `비용 $${cost.toFixed(2)}`;
+  return {
+    id: `${HERDR_ROW_PREFIX}${pane.pane_id}`,
+    label: `Herdr · ${display.label} · ${title} · ${costText}`,
+    kind: 'herdr',
+    badge: display.badge,
+  };
+}
+
+function paneIdFromRow(row: SidetabRow): string | undefined {
+  if (row.kind !== 'herdr' || !row.id.startsWith(HERDR_ROW_PREFIX)) return undefined;
+  const id = row.id.slice(HERDR_ROW_PREFIX.length);
+  return /^w[A-Za-z0-9_-]+:p[A-Za-z0-9_-]+$/.test(id) ? id : undefined;
+}
+
+function commandOutput(result: { code: number | null; stdout: string; stderr: string }): string {
+  if (result.code !== 0) {
+    const body = result.stderr.trim();
+    let message = body || `herdr exited with rc=${result.code ?? 'unknown'}`;
+    if (body.startsWith('{')) {
+      try {
+        const error = asRecord(asRecord(JSON.parse(body))?.error);
+        if (typeof error?.message === 'string') message = error.message;
+      } catch { /* preserve stderr */ }
+    }
+    throw new Error(message);
+  }
+  const text = result.stdout.trim();
+  if (!text.startsWith('{')) return text;
+  try {
+    const resultEnvelope = asRecord(asRecord(JSON.parse(text))?.result);
+    for (const key of ['text', 'output', 'screen', 'content'] as const) {
+      if (typeof resultEnvelope?.[key] === 'string') return resultEnvelope[key] as string;
+    }
+  } catch { /* plain terminal text may begin with a brace */ }
+  return text;
+}
+
+function logicalKey(key: string): string {
+  const aliases: Record<string, string> = {
+    '\r': 'enter', '\n': 'enter', '\x1b': 'esc', '\x7f': 'backspace', '\t': 'tab',
+    '\x03': 'ctrl+c', '\x04': 'ctrl+d', '\x1b[A': 'up', '\x1bOA': 'up', '\x1b[B': 'down', '\x1bOB': 'down',
+    '\x1b[C': 'right', '\x1bOC': 'right', '\x1b[D': 'left', '\x1bOD': 'left',
+  };
+  const mapped = aliases[key];
+  if (mapped) return mapped;
+  if (key.startsWith('\x1b')) throw new Error('지원되지 않는 Herdr escape key입니다');
+  return key;
+}
+
+export function createHerdrSidetabPortal(options: HerdrSidetabPortalOptions = {}): HerdrSidetabPortal {
+  const env = options.env ?? process.env;
+  const run = options.run ?? defaultHerdrCliRunner(env);
+  const isVerified = options.isVerified ?? (() => false);
+  const log = options.log ?? (() => {});
+  let cachedRows: SidetabRow[] = [];
+  let snapshotError: string | null = null;
+  let refreshPending: Promise<readonly SidetabRow[]> | null = null;
+
+  const visibleRows = (): SidetabRow[] => {
+    const rows = snapshotError
+      ? cachedRows.map((row) => ({ ...row, label: `${row.label} · 오래된 스냅샷` }))
+      : [...cachedRows];
+    if (snapshotError) {
+      rows.push({
+        id: 'herdr:snapshot-status',
+        label: `Herdr · snapshot 갱신 실패 · ${snapshotError}`,
+        kind: 'status',
+        badge: 'unknown',
+      });
+    }
+    return rows;
+  };
+
+  const requireEnabledPane = (paneId: string): void => {
+    if (env.HERDR_ENV !== '1') throw new Error('Herdr 포털은 Herdr 관리 pane 안에서만 사용할 수 있습니다');
+    if (!/^w[A-Za-z0-9_-]+:p[A-Za-z0-9_-]+$/.test(paneId)) throw new Error('Herdr pane id가 올바르지 않습니다');
+  };
+
+  return {
+    enabled: () => env.HERDR_ENV === '1',
+    async refreshRows() {
+      if (env.HERDR_ENV !== '1') return [];
+      if (refreshPending) return refreshPending;
+      refreshPending = (async () => {
+        const result = await run(['api', 'snapshot'], SNAPSHOT_TIMEOUT_MS);
+        const output = commandOutput(result);
+        let snapshot: unknown;
+        try { snapshot = JSON.parse(output); }
+        catch { throw new Error('Herdr snapshot 형식 오류 · JSON을 읽을 수 없습니다'); }
+        const panes = paneRowsFromSnapshot(snapshot);
+        cachedRows = panes.map((pane) => rowFromPane(pane, isVerified(pane)));
+        snapshotError = null;
+        log('snapshot', { panes: cachedRows.length });
+        return visibleRows();
+      })().catch((error: unknown) => {
+        snapshotError = (error instanceof Error ? error.message : String(error)).replace(/[\r\n\t]/g, ' ').slice(0, 160);
+        log('snapshot-failed', { error: snapshotError });
+        return visibleRows();
+      }).finally(() => { refreshPending = null; });
+      return refreshPending;
+    },
+    rows: visibleRows,
+    async readPane(paneId) {
+      requireEnabledPane(paneId);
+      const result = await run(['pane', 'read', paneId, '--source', 'visible', '--format', 'ansi'], PANE_READ_TIMEOUT_MS);
+      return commandOutput(result);
+    },
+    async sendText(paneId, text) {
+      requireEnabledPane(paneId);
+      if (!text) return;
+      const result = await run(['pane', 'send-text', paneId, text], PANE_INPUT_TIMEOUT_MS);
+      commandOutput(result);
+    },
+    async sendKey(paneId, key) {
+      requireEnabledPane(paneId);
+      const normalized = logicalKey(key);
+      if (!normalized) return;
+      const result = await run(['pane', 'send-keys', paneId, normalized], PANE_INPUT_TIMEOUT_MS);
+      commandOutput(result);
+    },
+  };
+}
+
+export function herdrPaneIdFromSidetabRow(row: SidetabRow): string | undefined {
+  return paneIdFromRow(row);
+}

package/src/user-config.ts

@@ -187,6 +187,8 @@ export interface LLMConfig {
   apiKey?: string;
   model?: string;
   baseUrl?: string;
+  /** Host that owns Codex OAuth refresh authority. Defaults to the HQ's mbp host. */
+  codexTokenOwnerHost?: string;
   /** Override the text stream idle watchdog in milliseconds. Omitted keeps provider/family defaults. */
   streamIdleTimeoutMs?: number;
   /** OpenRouter 설정 한 곳(두 골이 같은 키를 쓴다):
@@ -1177,6 +1179,8 @@ export interface SelfImplementToolConfig {
   goalRecordInDoc: boolean;
   /** Controls the persistent grounding loop used while authoring goals; absent preserves it. */
   goalAuthorPersistentGrounding?: boolean;
+  /** Explicit opt-in for the one-shot Terra medium goal-author reviewer precheck; absent/off preserves legacy authoring. */
+  goalAuthorReviewerPrecheck?: boolean;
   /** Uses the Fabric decomposer for SelfOrchestrate requests that omit `fabric_decompose`. */
   fabricDecompose: boolean;
   /** Normalized SelfOrchestrate goal count that automatically selects Fabric; null disables auto-selection. */
@@ -1294,7 +1298,7 @@ const TOOLS_DEFAULTS: ToolsConfig = {
   selfOrchestrate: {},
   nativeStructure: { enabled: false },
   // 대표 결정(2026-07-26): 오토 선호 — 기본 ON.
-  selfImplement: { worktreeRoot: join(homedir(), '.elanous', 'worktrees'), childInstanceMode: 'isolated', prApprovalDelivery: 'terminal' as const, observeOnly: false, goalRecordInDoc: true, fabricDecompose: false, fabricDecomposeAutoPathThreshold: 5, autoOpenPr: true, supervisor: { reasonRepair: false }, autoStop: { enabled: true, minRung: 2 }, autoAssist: { enabled: true, minRung: 2 }, screenStallTermination: { enabled: true, minRung: 2 }, reworkBudget: { shadowStop: false, maxRounds: 3 }, decompositionShadow: { enabled: false }, clarificationEscalation: { enabled: false } },
+  selfImplement: { worktreeRoot: join(homedir(), '.elanous', 'worktrees'), childInstanceMode: 'isolated', prApprovalDelivery: 'terminal' as const, observeOnly: false, goalRecordInDoc: true, goalAuthorReviewerPrecheck: false, fabricDecompose: false, fabricDecomposeAutoPathThreshold: 5, autoOpenPr: true, supervisor: { reasonRepair: false }, autoStop: { enabled: true, minRung: 2 }, autoAssist: { enabled: true, minRung: 2 }, screenStallTermination: { enabled: true, minRung: 2 }, reworkBudget: { shadowStop: false, maxRounds: 3 }, decompositionShadow: { enabled: false }, clarificationEscalation: { enabled: false } },
 };
 
 // ── Debug ────────────────────────────────────────────────────────────
@@ -2664,6 +2668,7 @@ function parseToolsConfig(raw: unknown): ToolsConfig {
   const goalAuthorPersistentGrounding = typeof selfImplRaw.goalAuthorPersistentGrounding === 'boolean'
     ? selfImplRaw.goalAuthorPersistentGrounding
     : undefined;
+  const goalAuthorReviewerPrecheck = selfImplRaw.goalAuthorReviewerPrecheck === true;
   const fabricDecompose = selfImplRaw.fabricDecompose === true;
   const fabricDecomposeAutoPathThresholdRaw = selfImplRaw.fabricDecomposeAutoPathThreshold;
   const fabricDecomposeAutoPathThreshold = fabricDecomposeAutoPathThresholdRaw === null
@@ -2813,7 +2818,7 @@ function parseToolsConfig(raw: unknown): ToolsConfig {
     runDevHarness,
     selfOrchestrate,
     nativeStructure,
-    selfImplement: { worktreeRoot, childInstanceMode, prApprovalDelivery, observeOnly, goalRecordInDoc, goalAuthorPersistentGrounding, fabricDecompose, fabricDecomposeAutoPathThreshold, autoOpenPr, supervisor, draftOnStop, salvageRetention, autoStop, autoAssist, screenStallTermination, reworkBudget, decompositionShadow, clarificationEscalation, ...(childLlm ? { childLlm } : {}), ...(escalateChild && Object.keys(escalateChild).length ? { escalateChild } : {}), ...(selfImplRaw.podChildDefault !== undefined ? { podChildDefault: selfImplRaw.podChildDefault } : {}), ...(runTtlHours !== undefined ? { runTtlHours } : {}), ...(draftSweepCloseCap !== undefined ? { draftSweepCloseCap } : {}), ...(runTtl ? { runTtl } : {}), ...(autoheal ? { autoheal } : {}) },
+    selfImplement: { worktreeRoot, childInstanceMode, prApprovalDelivery, observeOnly, goalRecordInDoc, goalAuthorPersistentGrounding, goalAuthorReviewerPrecheck, fabricDecompose, fabricDecomposeAutoPathThreshold, autoOpenPr, supervisor, draftOnStop, salvageRetention, autoStop, autoAssist, screenStallTermination, reworkBudget, decompositionShadow, clarificationEscalation, ...(childLlm ? { childLlm } : {}), ...(escalateChild && Object.keys(escalateChild).length ? { escalateChild } : {}), ...(selfImplRaw.podChildDefault !== undefined ? { podChildDefault: selfImplRaw.podChildDefault } : {}), ...(runTtlHours !== undefined ? { runTtlHours } : {}), ...(draftSweepCloseCap !== undefined ? { draftSweepCloseCap } : {}), ...(runTtl ? { runTtl } : {}), ...(autoheal ? { autoheal } : {}) },
   };
 }
 
@@ -3948,8 +3953,8 @@ export interface UserConfig {
   nexus?: { demoMode?: boolean };
   /** Execution-phase HITL answer deadline; absent means 30 minutes. */
   hitl?: { executionDeadlineMinutes?: number };
-  /** Deferred (quiet-hours) outbound queue. `deferredMaxAttempts`: failed flushes before an item is quarantined; absent = env ELANOUS_OUTBOUND_DEFERRED_MAX_ATTEMPTS, else 5. */
-  outbound?: { deferredMaxAttempts?: number };
+  /** Outbound notifications. quietHours is `off` or `HH:MM-HH:MM` KST; absent keeps 00:00-06:30. */
+  outbound?: { deferredMaxAttempts?: number; quietHours?: 'off' | string };
   coo?: { linearProject?: string };
   decisions?: { linearProjection: { enabled: boolean }; requireCrossCheck: boolean;
     crossCheckNeighbor: Record<EventSeat, EventSeat>; crossCheckWaitMinutes: number };
@@ -5032,6 +5037,21 @@ export function parseHqConfig(raw: unknown): HqConfig | undefined {
   return Object.keys(out).length ? out : undefined;
 }
 
+function parseOutboundConfig(raw: unknown): UserConfig['outbound'] {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const outbound = raw as Record<string, unknown>;
+  const attempts = outbound.deferredMaxAttempts;
+  const quietHours = outbound.quietHours;
+  const validQuietHours = quietHours === 'off'
+    || (typeof quietHours === 'string'
+      && /^(?:[01]\d|2[0-3]):[0-5]\d-(?:[01]\d|2[0-3]):[0-5]\d$/.test(quietHours)
+      && quietHours.slice(0, 5) !== quietHours.slice(6));
+  const result: NonNullable<UserConfig['outbound']> = {};
+  if (Number.isSafeInteger(attempts) && (attempts as number) > 0) result.deferredMaxAttempts = attempts as number;
+  if (validQuietHours) result.quietHours = quietHours as 'off' | string;
+  return Object.keys(result).length ? result : undefined;
+}
+
 export function buildUserConfig(path: string = defaultPath()): UserConfig {
   if (!existsSync(path)) return defaultConfigWithRuntimeProvider();
   let raw: unknown;
@@ -5156,6 +5176,7 @@ export function buildUserConfig(path: string = defaultPath()): UserConfig {
   const tuiRaw = rawObj.tui && typeof rawObj.tui === 'object' && !Array.isArray(rawObj.tui) ? rawObj.tui as Record<string, unknown> : {};
   const gateRemoteConfig = parseGateRemoteConfig(rawObj.gateRemote);
   const projects = parseProjectsConfig(rawObj.projects);
+  const outboundConfig = parseOutboundConfig(rawObj.outbound);
   return {
     tui: {
       sidetab: tuiRaw.sidetab === 'off' || tuiRaw.sidetab === 'open' ? tuiRaw.sidetab : 'collapsed',
@@ -5330,6 +5351,9 @@ export function buildUserConfig(path: string = defaultPath()): UserConfig {
         };
       })(),
       model: resolveRuntimeLlmModel(baseProvider, selectedProvider, str(llm.model), escalationProvider || undefined),
+      codexTokenOwnerHost: typeof llm.codexTokenOwnerHost === 'string'
+        && /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(llm.codexTokenOwnerHost.trim())
+        ? llm.codexTokenOwnerHost.trim() : undefined,
       streamIdleTimeoutMs: positiveFiniteNumber(llm.streamIdleTimeoutMs),
       openrouter: (() => {
         const router = llm.openrouter;
@@ -5954,11 +5978,7 @@ export function buildUserConfig(path: string = defaultPath()): UserConfig {
       && typeof (rawObj.hitl as Record<string, unknown>).executionDeadlineMinutes === 'number'
       ? { hitl: { executionDeadlineMinutes: (rawObj.hitl as { executionDeadlineMinutes: number }).executionDeadlineMinutes } }
       : {}),
-    ...(rawObj.outbound && typeof rawObj.outbound === 'object' && !Array.isArray(rawObj.outbound)
-      && Number.isSafeInteger((rawObj.outbound as Record<string, unknown>).deferredMaxAttempts)
-      && ((rawObj.outbound as { deferredMaxAttempts: number }).deferredMaxAttempts) > 0
-      ? { outbound: { deferredMaxAttempts: (rawObj.outbound as { deferredMaxAttempts: number }).deferredMaxAttempts } }
-      : {}),
+    ...(outboundConfig ? { outbound: outboundConfig } : {}),
     ...(parseHqConfig(rawObj.hq) ? { hq: parseHqConfig(rawObj.hq)! } : {}),
     ...(gateRemoteConfig ? { gateRemote: gateRemoteConfig } : {}),
     cli: { helpRole: parseCliHelpRole(rawObj.cli) },
@@ -6527,6 +6547,9 @@ export function saveUserConfig(
     },
   };
   const rawRest = { ...(cfg.raw ?? {}) };
+  const rawOutbound = rawRest.outbound && typeof rawRest.outbound === 'object' && !Array.isArray(rawRest.outbound)
+    ? rawRest.outbound as Record<string, unknown> : undefined;
+  delete rawRest.outbound;
   const rawTui = rawRest.tui && typeof rawRest.tui === 'object' && !Array.isArray(rawRest.tui)
     ? rawRest.tui as Record<string, unknown> : {};
   // projects: raw entries are kept verbatim — an invalid entry loaded from disk is preserved, not blocked (its error
@@ -6680,6 +6703,7 @@ export function saveUserConfig(
       // picks up capability fallback 'medium' → user thinks fix
       // regressed).
       reasoningLevel: cfg.llm.reasoningLevel,
+      codexTokenOwnerHost: cfg.llm.codexTokenOwnerHost,
       codexReasoning: cfg.llm.codexReasoning,
       goalLoop: cfg.llm.goalLoop,
       memoryJudge: cfg.llm.memoryJudge,
@@ -6974,6 +6998,7 @@ export function saveUserConfig(
     // M1-2b: sparse — emit only when explicitly set. Keeps Path-A-only
     // users' file clean (no empty modelTier:{} blobs).
     ...(cfg.modelTier ? { modelTier: parseModelTierConfig(cfg.modelTier) } : {}),
+    ...((cfg.outbound || rawOutbound) ? { outbound: stripUndef({ ...rawOutbound, ...cfg.outbound }) } : {}),
     ...(cfg.sessionFabric ? { sessionFabric: cfg.sessionFabric } : {}),
     ...(cfg.nextFluent ? { nextFluent: cfg.nextFluent } : {}),
     ...(cfg.taste ? { taste: cfg.taste } : {}),

package/src/user-intent/types.ts

@@ -3,8 +3,8 @@
 // PLAN: 내부 문서 `PLAN-user-intent-logging-2026-05-12` §2
 // MANUAL: 내부 문서 `MANUAL-user-intent-logging-2026-05-12`
 //
-// Single shape for every user-intent signal across the 7 surfaces
-// (tui · pwa · ios · watch · airpods · discord · telegram) and 7
+// Single shape for every user-intent signal across the 8 surfaces
+// (tui · ask · pwa · ios · watch · airpods · discord · telegram) and 7
 // layers (utterance · gesture · selection · navigation · ambient ·
 // device_state · system). Patcher (Y3) consumes the JSONL stream as
 // raw input; KGS card conversion happens in the Patcher, not here.
@@ -21,6 +21,7 @@
 export type UserIntentSurface =
   | 'unknown'
   | 'tui'
+  | 'ask'
   | 'pwa'
   | 'ios'
   | 'watch'
@@ -29,7 +30,7 @@ export type UserIntentSurface =
   | 'telegram';
 
 export const USER_INTENT_SURFACES: readonly UserIntentSurface[] = [
-  'unknown', 'tui', 'pwa', 'ios', 'watch', 'airpods', 'discord', 'telegram',
+  'unknown', 'tui', 'ask', 'pwa', 'ios', 'watch', 'airpods', 'discord', 'telegram',
 ];
 
 export type UserIntentLayer =

package/src/ux-sim/browser-hand.ts

@@ -0,0 +1,165 @@
+// BrowserHand 시뮬레이션 — 페이지·Linear 네트워크 경계만 대역하고 생산 coordinator와 browser-act를 부른다.
+import {
+  dispatchBrowserHand,
+  type BrowserHandArgs,
+  type BrowserHandDeps,
+  type BrowserHandRepairNode,
+  type BrowserHandResult,
+} from '../tool-runtime/browser-hand-runtime.js';
+import { performBrowserAction, type BrowserActionDeps, type BrowserActionResult } from '../harness/browser-act.js';
+import type { CdpClient, CdpEventListener } from '../browser-cdp/client.js';
+
+export type BrowserHandScenario = 'attach' | 'paywall-fallback' | 'selection-roundtrip';
+
+export interface BrowserHandSimulationResult {
+  scenario: BrowserHandScenario;
+  runId: string;
+  observedRunId: string | null;
+  observedBrowserActionRunIds: readonly (string | null)[];
+  result: BrowserHandResult;
+  pageReads: readonly string[];
+  browserActions: readonly string[];
+  repairNodes: readonly BrowserHandRepairNode[];
+  linear: {
+    uploads: readonly { filename: string; contentType: string; bytes: number }[];
+    attachments: readonly { issueId: string; title: string; url: string }[];
+    comments: readonly { issueId: string; body: string }[];
+  };
+}
+
+const ISSUE_ID = 'c0ffee00-0000-4000-8000-000000000001';
+const PERSONA = {
+  personaId: 'ux-sim-browser-hand',
+  displayName: 'UX simulation browser',
+  actionHosts: ['ir.example.test', 'archive.example.test'],
+};
+const PRIMARY_URL = 'https://ir.example.test/filing';
+const ALTERNATE_URL = 'https://archive.example.test/filing';
+const CAPTURE_REF = 'ux-sim://browser-hand/capture.png';
+
+function fakeCdp(): CdpClient {
+  let lifecycleListener: CdpEventListener | undefined;
+  return {
+    port: 0,
+    pid: 0,
+    get isAlive() { return true; },
+    on(method, listener) {
+      if (method === 'Page.lifecycleEvent') lifecycleListener = listener;
+      return () => { lifecycleListener = undefined; };
+    },
+    async navigate() {
+      queueMicrotask(() => lifecycleListener?.({
+        method: 'Page.lifecycleEvent',
+        params: { name: 'load', frameId: 'ux-sim-frame', loaderId: 'ux-sim-loader' },
+      }));
+      return { frameId: 'ux-sim-frame', loaderId: 'ux-sim-loader' };
+    },
+    async screenshot() { return Buffer.from([137, 80, 78, 71]); },
+    async evaluate() { throw new Error('unexpected page evaluation; execute seam supplies click coordinates'); },
+    async setScriptExecutionDisabled(value) {
+      // Canary: BrowserHand must not disable page scripts; fail loudly if that production behavior is introduced.
+      if (value) throw new Error('BrowserHand simulation must not disable page scripts');
+    },
+    async close() {},
+  };
+}
+
+/** Run the real BrowserHand coordinator and performBrowserAction with only browser and Linear I/O faked. */
+export async function simBrowserHand(scenario: BrowserHandScenario, linearSubtaskId = ISSUE_ID, runId = 'run-ux-sim-browser-hand'): Promise<BrowserHandSimulationResult> {
+  let observedRunId: string | null = null;
+  const observedBrowserActionRunIds: Array<string | null> = [];
+  const pageReads: string[] = [];
+  const browserActions: string[] = [];
+  const repairNodes: BrowserHandRepairNode[] = [];
+  const uploads: Array<{ filename: string; contentType: string; bytes: number }> = [];
+  const attachments: Array<{ issueId: string; title: string; url: string }> = [];
+  const comments: Array<{ issueId: string; body: string }> = [];
+
+  const args: BrowserHandArgs = {
+    url: PRIMARY_URL,
+    target: 'body',
+    armed: true,
+    linearSubtaskId,
+    persona: PERSONA.personaId,
+    ...(scenario === 'paywall-fallback' ? { alternateUrl: ALTERNATE_URL } : {}),
+    ...(scenario === 'selection-roundtrip'
+      ? { includeThisToo: true, selection: { text: 'Revenue rose 12%', tab: 'Q3 filing' } }
+      : {}),
+  };
+
+  const browserAct = async (request: Parameters<typeof performBrowserAction>[0], deps?: BrowserActionDeps): Promise<BrowserActionResult> => {
+    browserActions.push(request.url);
+    return performBrowserAction(request, {
+      ...deps,
+      connect: async () => fakeCdp(),
+      // `performBrowserAction` uses this injected click boundary, so the fake page's evaluate must stay unused.
+      execute: async () => ({ x: 41, y: 73 }),
+      loadWaitTimeoutMs: 20,
+      captureTimeoutMs: 20,
+      reclaimOpenedTabs: false,
+      saveAttachment: async () => ({
+        ok: true,
+        entry: {
+          id: 'ux-sim-browser-hand-capture',
+          path: CAPTURE_REF,
+          filename: 'capture.png',
+          mediaType: 'image/png',
+          size: 4,
+          createdAt: 0,
+        },
+      }),
+    });
+  };
+
+  const deps: BrowserHandDeps = {
+    browserAct,
+    confirmHuman: async () => true,
+    resolvePersona: async () => PERSONA,
+    readPageText: async url => {
+      pageReads.push(url);
+      return scenario === 'paywall-fallback' && url === PRIMARY_URL
+        ? 'Subscribe to continue'
+        : 'Public filing content';
+    },
+    browserActDeps: {
+      getRunId: () => { observedRunId = runId; return runId; },
+      observe(event, data) {
+        if (event === 'repair-node') repairNodes.push(data as BrowserHandRepairNode);
+        if (event === 'executed') {
+          const row = data as { runId?: unknown };
+          observedBrowserActionRunIds.push(typeof row.runId === 'string' ? row.runId : null);
+        }
+      },
+    },
+    getApiKey: async () => 'ux-sim-fake-linear-key',
+    readCapture: async path => {
+      if (path !== CAPTURE_REF) throw new Error(`unexpected simulated capture ref: ${path}`);
+      return Buffer.from([137, 80, 78, 71]);
+    },
+    upload: async input => {
+      uploads.push({ filename: input.filename, contentType: input.contentType, bytes: input.body.byteLength });
+      return 'https://uploads.example.test/browser-hand.png';
+    },
+    attach: async input => {
+      attachments.push({ issueId: input.issueId, title: input.title, url: input.url });
+      return 'ux-sim-attachment-1';
+    },
+    reflectSelection: async input => {
+      comments.push(input);
+      return true;
+    },
+  };
+  const result = await dispatchBrowserHand(args, undefined, deps);
+
+  return {
+    scenario,
+    runId,
+    observedRunId,
+    observedBrowserActionRunIds,
+    result,
+    pageReads,
+    browserActions,
+    repairNodes,
+    linear: { uploads, attachments, comments },
+  };
+}