elanous 0.2.35 → 0.2.37

package/src/domains/surface-events.ts

@@ -172,10 +172,58 @@ export function recordInboundTurn(
   finally { if (ownDb) db.close(); }
 }
 
+/** 발화 «원천» — 사람이 말한 것과 시험 fixture·외부 CLI agent 가 던진 것을 계측상 구분한다.
+ *  ⛔ 원천 표기가 없는 0건을 «사람 표본 0» 으로 오인하면 안 되고, 반대로 시험 fixture 가
+ *  사람과 같은 서피스(cli·telegram)에 기록됐다는 이유로 사람 표본으로 세어도 안 된다. */
+export type SurfaceUtteranceOrigin = 'human' | 'test-fixture' | 'external-cli-agent' | 'elanous-self' | 'unknown';
+
+const TEST_FIXTURE_ORIGIN = /^(?:test-fixture|test_fixture|fixture|test|test-runner|bun-test)$/i;
+const HUMAN_ORIGIN = /^(?:human|user|tui|pwa|telegram|discord|cli)$/i;
+const EXTERNAL_CLI_AGENT_ORIGIN = /^(?:claude-code|codex|gemini|agent|external|external-cli-agent|external:[\w-]+|ext:[\w-]+)$/i;
+const HUMAN_PROSE_SURFACE = /^(?:cli|tui|pwa|telegram|discord|ipad|watch)$/i;
+
+function refsOf(raw: string | null): Record<string, unknown> {
+  if (!raw) return {};
+  try {
+    const value: unknown = JSON.parse(raw);
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+  } catch { return {}; }
+}
+
+/** 원천 분류기 — provenance(recordInboundTurn opts.origin → refs.origin/tags.origin:<origin>)
+ *  표기를 먼저 읽고, 표기가 없을 때만 서피스로 추정한다. 시험 fixture 는 서피스 추정 «전에» 가른다. */
+export function classifySurfaceUtteranceOrigin(
+  row: Pick<SurfaceEventRow, 'direction' | 'surface' | 'kind' | 'refs' | 'tags'>,
+): SurfaceUtteranceOrigin {
+  if (row.direction !== 'inbound') return 'unknown';
+  const refs = refsOf(row.refs);
+  const explicit = typeof refs.origin === 'string' ? refs.origin : undefined;
+  const utteranceOrigin = typeof refs.utteranceOrigin === 'string' ? refs.utteranceOrigin : undefined;
+  const fixtureTagged = (row.tags ?? '').split(/\s+/).filter(Boolean)
+    .some((tag) => TEST_FIXTURE_ORIGIN.test(tag.split(':').pop() ?? ''));
+  if ((utteranceOrigin && TEST_FIXTURE_ORIGIN.test(utteranceOrigin)) || (explicit && TEST_FIXTURE_ORIGIN.test(explicit)) || fixtureTagged) {
+    return 'test-fixture';
+  }
+  if (utteranceOrigin === 'human') return 'human';
+  if (utteranceOrigin === 'agent') return 'external-cli-agent';
+  if (explicit) {
+    if (HUMAN_ORIGIN.test(explicit)) return 'human';
+    if (EXTERNAL_CLI_AGENT_ORIGIN.test(explicit)) return 'external-cli-agent';
+  }
+  // recordInboundTurn marks its recorder as elanous-self; on chat Q&A the speaker is the human.
+  if (row.kind === 'qna' && /^(?:telegram|discord)$/i.test(row.surface)) return 'human';
+  if (explicit === 'elanous-self') return 'elanous-self';
+  if (/^ext:/i.test(row.surface)) return 'external-cli-agent';
+  if (HUMAN_PROSE_SURFACE.test(row.surface)) return 'human';
+  return 'unknown';
+}
+
 export interface SurfaceUtteranceQuery {
   from: string;
   to: string;
   surface?: string;
+  /** 원천 필터(선택) — 미지정이면 종전과 같이 창 안의 모든 발화를 읽는다(보존 계약). */
+  origin?: SurfaceUtteranceOrigin | readonly SurfaceUtteranceOrigin[];
 }
 
 /** Read every event in a half-open UTC interval without touching recall state. */
@@ -183,9 +231,40 @@ export function querySurfaceUtterances(db: Database, opts: SurfaceUtteranceQuery
   const where = ["julianday(e.ts) >= julianday(?)", "julianday(e.ts) < julianday(?)", "e.direction = 'inbound'", "e.kind IN ('utterance', 'qna')"];
   const params: string[] = [opts.from, opts.to];
   if (opts.surface) { where.push('e.surface = ?'); params.push(opts.surface); }
-  return db.prepare(
+  const rows = db.prepare(
     `SELECT e.* FROM events e WHERE ${where.join(' AND ')} ORDER BY julianday(e.ts) ASC, e.id ASC`,
   ).all(...params) as SurfaceEventRow[];
+  if (opts.origin === undefined) return rows;
+  const wanted = new Set<SurfaceUtteranceOrigin>(typeof opts.origin === 'string' ? [opts.origin] : opts.origin);
+  return rows.filter((row) => wanted.has(classifySurfaceUtteranceOrigin(row)));
+}
+
+/** 원천별 발화 수 — «사람 원천 0» 을 사람 표본으로 읽지 않게 하는 계측 입구(read-only·recall 무접촉). */
+export interface SurfaceUtteranceOriginCounts {
+  human: number;
+  testFixture: number;
+  externalCliAgent: number;
+  elanousSelf: number;
+  unknown: number;
+  total: number;
+}
+
+export function countSurfaceUtterancesByOrigin(
+  db: Database,
+  opts: Omit<SurfaceUtteranceQuery, 'origin'>,
+): SurfaceUtteranceOriginCounts {
+  const counts: SurfaceUtteranceOriginCounts = { human: 0, testFixture: 0, externalCliAgent: 0, elanousSelf: 0, unknown: 0, total: 0 };
+  for (const row of querySurfaceUtterances(db, opts)) {
+    counts.total += 1;
+    switch (classifySurfaceUtteranceOrigin(row)) {
+      case 'human': counts.human += 1; break;
+      case 'test-fixture': counts.testFixture += 1; break;
+      case 'external-cli-agent': counts.externalCliAgent += 1; break;
+      case 'elanous-self': counts.elanousSelf += 1; break;
+      default: counts.unknown += 1;
+    }
+  }
+  return counts;
 }
 
 export interface QueryEventsOpts {

package/src/esc-abort-gate.ts

@@ -145,6 +145,75 @@ export function createHarnessEscHint(pushLine: (line: string) => void): (targets
   };
 }
 
+export interface EscAbortPendingSoftStopRunnerDeps {
+  getActiveHarnessSpace: () => string | null;
+  pushChatLine: (line: string) => void;
+  showHarnessEscHint: (targets: readonly string[]) => boolean;
+}
+
+export interface EscAbortPendingSoftStopOutcomeLike {
+  outcome: 'stopped' | 'failed' | 'hint' | 'waiting';
+  stoppedHarnessSpace: string | null;
+}
+
+export interface EscAbortPendingGateDeps {
+  /**
+   * Production soft-stop runner (`runEscAbortPendingSoftStop` in
+   * src/dashboard/index.ts): enqueues the durable soft-stop marker,
+   * verifies it, and paints the stopped/failure line. Injected (not
+   * imported) to keep this module free of a dashboard import cycle.
+   */
+  runSoftStop: (targets: readonly string[], deps: EscAbortPendingSoftStopRunnerDeps) => EscAbortPendingSoftStopOutcomeLike;
+  formatWaitingTargets: (targets: readonly string[]) => string;
+  getActiveHarnessSpace: () => string | null;
+  pushChatLine: (line: string) => void;
+  showHarnessEscHint: (targets: readonly string[]) => boolean;
+  /** Dashboard paint hook (chatScrollOffset reset) after each callback. */
+  afterAbortEvent?: () => void;
+}
+
+export interface EscAbortPendingGate {
+  onAbortPending(event: { running: number; repeat: number; targets: readonly string[] }): void;
+  onAbortRepeat(event: { running: number; repeat: number; targets: readonly string[]; phase: 'confirming' | 'pending' }): void;
+  getStoppedHarnessSpace(): string | null;
+}
+
+/**
+ * ⭐ TUI-ESC-EXIT production seam — the onAbortPending/onAbortRepeat
+ * callback pair that `attachChatStreamingKeys` wires into
+ * `createEscAbortGate`. Extracted from the dashboard inline closure so the
+ * incident test exercises the same function the dashboard executes.
+ *
+ * ⛔ Preservation rule: `stoppedHarnessSpace` only advances on a successful
+ * soft stop (a real stopped space). Later waiting/hint/failed callbacks must
+ * NOT clear a previously successful space — `onAbortRepeat` and the
+ * teardown `settleEscAbortPendingLines` decision depend on the retained value.
+ */
+export function createEscAbortPendingGate(deps: EscAbortPendingGateDeps): EscAbortPendingGate {
+  let stoppedHarnessSpace: string | null = null;
+  return {
+    onAbortPending({ targets }) {
+      const softStop = deps.runSoftStop(targets, {
+        getActiveHarnessSpace: deps.getActiveHarnessSpace,
+        pushChatLine: deps.pushChatLine,
+        showHarnessEscHint: deps.showHarnessEscHint,
+      });
+      if (softStop.stoppedHarnessSpace) stoppedHarnessSpace = softStop.stoppedHarnessSpace;
+      if (softStop.outcome === 'waiting') {
+        deps.pushChatLine(`  ⏳ 중단 요청됨 — ${deps.formatWaitingTargets(targets)} 종료를 기다리는 중입니다.`);
+      }
+      deps.afterAbortEvent?.();
+    },
+    onAbortRepeat({ repeat, targets }) {
+      if (!stoppedHarnessSpace && !deps.showHarnessEscHint(targets)) {
+        deps.pushChatLine(`  ⏳ ESC 재시도 ${repeat}회 — ${deps.formatWaitingTargets(targets)} 종료를 기다리는 중입니다.`);
+      }
+      deps.afterAbortEvent?.();
+    },
+    getStoppedHarnessSpace: () => stoppedHarnessSpace,
+  };
+}
+
 export function createEscAbortGate(deps: EscAbortGateDeps): EscAbortGate {
   let current: ApprovalModalHandle | null = null;
   let currentDispose: (() => void) | null = null;

package/src/exec-requests/planner.ts

@@ -10,6 +10,41 @@ import { debug } from '../debug/log.js';
 import { peerEditRunGate } from '../nexus/api/graph-peer-edit.js';
 import { OUTPUT_KINDS, pickDefaultOutput, type OutputKind } from './default-outputs.js';
 
+/**
+ * 코드포인트 순서 비교 — `localeCompare` 는 «실행 로케일의 ICU 콜레이션» 을 쓰므로 같은 문자열 쌍의 대소가
+ * 플랫폼/로케일마다 뒤집힌다(실측: '🎉party' vs '2026-10-23', 'alpha' vs 'Zebra' 는 콜레이션과 코드포인트가 반대).
+ * 순서가 실행 환경에 따라 달라지면 «가장 새 것» 선택이 재현 불가능해진다 — 그래서 코드포인트로 고정한다.
+ */
+export function compareCodePoints(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** 숫자 구간의 선행 0 을 지운다(01 == 1). */
+const stripLeadingZeros = (digits: string): string => digits.replace(/^0+(?=\d)/, '');
+
+/**
+ * 버전 문자열 비교 — 숫자 구간만 «수치» 로, 나머지는 «코드포인트» 로 비교한다.
+ * `localeCompare(..., { numeric: true })` 의 수치 규칙은 그대로 두고 콜레이션 의존만 걷어낸 등가물이다.
+ */
+export function compareVersionish(a: string, b: string): number {
+  const chunks = (value: string): string[] => value.match(/\d+|\D+/g) ?? [];
+  const left = chunks(a);
+  const right = chunks(b);
+  for (let index = 0; index < Math.min(left.length, right.length); index += 1) {
+    const [x, y] = [left[index]!, right[index]!];
+    if (/^\d/.test(x) && /^\d/.test(y)) {
+      const [dx, dy] = [stripLeadingZeros(x), stripLeadingZeros(y)];
+      if (dx.length !== dy.length) return dx.length < dy.length ? -1 : 1;
+      const digits = compareCodePoints(dx, dy);
+      if (digits !== 0) return digits;
+      continue;
+    }
+    const text = compareCodePoints(x, y);
+    if (text !== 0) return text;
+  }
+  return left.length === right.length ? 0 : left.length < right.length ? -1 : 1;
+}
+
 export interface InstalledGraph {
   id: string;
   title: string;
@@ -43,7 +78,7 @@ export function installedPluginGraphs(pluginsRoot = join(elanousStateRoot(), 'pl
   };
   for (const market of dirs(pluginsRoot)) {
     for (const name of dirs(join(pluginsRoot, market))) {
-      const versions = dirs(join(pluginsRoot, market, name)).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+      const versions = dirs(join(pluginsRoot, market, name)).sort((a, b) => compareVersionish(b, a));
       const version = versions[0];
       if (!version) continue;
       const root = join(pluginsRoot, market, name, version);
@@ -146,7 +181,7 @@ export function latestFieldFolder(configRoot = getElanousConfigDir()): string |
         const photos = readdirSync(path, { withFileTypes: true }).filter(file => file.isFile() && /\.(?:png|jpe?g|webp|heic)$/i.test(file.name));
         for (const photo of photos) {
           const time = statSync(join(path, photo.name)).mtimeMs;
-          if (!latest || time > latest.time || (time === latest.time && path.localeCompare(latest.path) > 0)) latest = { path, time };
+          if (!latest || time > latest.time || (time === latest.time && compareCodePoints(path, latest.path) > 0)) latest = { path, time };
         }
       } catch { /* Unreadable event does not supply photos. */ }
     }

package/src/execution-loop/launch-gate.ts

@@ -88,8 +88,6 @@ export function activeRunsForGoal(goalId: string, deps: ActiveRunsForGoalDeps =
   }
 }
 
-const LAUNCH_BUDGET_PROVIDER: Readonly<Record<string, string>> = { 'codex-rotate': CODEX_PROVIDER, grok: GROK_PROVIDER };
-
 /**
  * L6 발사 관문의 예산 입력 보정 — 발사 우주의 config 에 체인이 없으면(작업 트리 = 시험 우주) 막지 않고
  * 코드 기본 체인으로 판단한다. `--child-llm-provider` 를 명시했으면 그것이 체인이다(예산 판정 밖 provider 는 통과).
@@ -98,6 +96,9 @@ export function harnessLaunchBudgetDecision(
   inputs: BudgetInputs,
   opts: { readonly childLlmProvider?: string; readonly childLlmModel?: string } = {},
 ): { readonly decision: BudgetDecision; readonly warning?: string; readonly unmeasuredProvider?: string } {
+  // Resolve imported provider constants only when the launch gate is called.
+  // This module participates in the CLI/tool catalog import cycle.
+  const launchBudgetProvider: Readonly<Record<string, string>> = { 'codex-rotate': CODEX_PROVIDER, grok: GROK_PROVIDER };
   const explicit = opts.childLlmProvider?.trim();
   const judged = (selected: BudgetInputs) => {
     const { decision, unmeasuredProvider } = decideLaunchBudget(selected);
@@ -114,7 +115,7 @@ export function harnessLaunchBudgetDecision(
     return judged({ ...inputs, preference: { ...inputs.preference, chain } });
   }
   if (inputs.preference.chain.length > 0) return judged(inputs);
-  const chain = DEFAULT_FALLBACK_CHAIN.map((step) => ({ provider: LAUNCH_BUDGET_PROVIDER[step] ?? step }));
+  const chain = DEFAULT_FALLBACK_CHAIN.map((step) => ({ provider: launchBudgetProvider[step] ?? step }));
   const result = judged({ ...inputs, preference: { ...inputs.preference, chain } });
   return {
     ...result,

package/src/git-fs/cli-stderr.ts

@@ -0,0 +1,45 @@
+import { debug } from '../debug/log.js';
+
+export type CliStderrRecord = {
+  readonly source: 'git' | 'gh';
+  readonly exitCode: number;
+  readonly raw: Buffer;
+};
+
+export type CliStderrSink = (record: CliStderrRecord) => void;
+
+let activeSink: CliStderrSink | null = null;
+
+export function hasCliStderrSink(): boolean {
+  return activeSink !== null;
+}
+
+/** Install a surface-specific sink; without one, CLI stderr keeps its process contract. */
+export function setCliStderrSink(sink: CliStderrSink | null): () => void {
+  const previous = activeSink;
+  activeSink = sink;
+  return () => {
+    if (activeSink === sink) activeSink = previous;
+  };
+}
+
+/** Preserve raw bytes for the caller and keep ordinary CLI invocations on process.stderr. */
+export function writeCliStderr(record: CliStderrRecord): void {
+  const sink = activeSink;
+  if (!sink) {
+    process.stderr.write(record.raw);
+    return;
+  }
+  // A failed screen redraw must not fall through to the physical TTY and overwrite its prompt.
+  try { sink(record); } catch (error) {
+    // Keep the prompt isolated, but leave a forensic breadcrumb for a failed presentation path.
+    try {
+      debug.log('tui.cli-stderr', 'sink-failed', {
+        source: record.source,
+        exitCode: record.exitCode,
+        byteLength: record.raw.length,
+        errorName: error instanceof Error ? error.name : typeof error,
+      });
+    } catch { /* never fall through to the physical TTY */ }
+  }
+}

package/src/git-fs/gh-cli.ts

@@ -1,5 +1,6 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { debug } from '../debug/log.js';
+import { writeCliStderr } from './cli-stderr.js';
 
 const LF = 0x0a;
 const MAX_GH_RETRY_ATTEMPTS = 3;
@@ -195,14 +196,16 @@ export function runGhCli(args: string[]): void {
   const auxiliaryFailure = exitCode === 0 ? undefined : auxiliaryFailureSignature(stderr);
 
   if (stdout.length) process.stdout.write(stdout);
-  if (stderr.length) process.stderr.write(stderr);
+  const stderrChunks: Buffer[] = [];
+  if (stderr.length) stderrChunks.push(stderr);
   // ⛔⭐⭐⭐⭐⭐ **상태 줄은 `stderr` 로** — `git-cli.ts` 의 같은 주석이 canonical.
   //   `--json` 산출 뒤에 비-JSON 한 줄이 붙으면 ***모든 JSON 소비자가 죽는다***(`jq: parse error` 실측).
   //   stdout 은 ***원 바이트 그대로만*** 나간다.
   const endsWithoutLf = (buffer: Buffer): boolean => buffer.length > 0 && buffer[buffer.length - 1] !== LF;
-  if (endsWithoutLf(stderr)) process.stderr.write('\n');
+  if (endsWithoutLf(stderr)) stderrChunks.push(Buffer.from('\n'));
 
-  process.stderr.write(`${statusLine(label, result, auxiliaryFailure)}\n`);
+  stderrChunks.push(Buffer.from(`${statusLine(label, result, auxiliaryFailure)}\n`));
+  writeCliStderr({ source: 'gh', exitCode, raw: Buffer.concat(stderrChunks) });
   process.exitCode = exitCode;
   if (auxiliaryFailure) {
     debug.log('gh.cli', 'partial-outcome', {

package/src/git-fs/git-cli.ts

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { debug } from '../debug/log.js';
+import { hasCliStderrSink, writeCliStderr } from './cli-stderr.js';
 import { runGitWithRetry, type GitRunner } from './retry.js';
 
 const LF = 0x0a;
@@ -134,7 +135,11 @@ export function runGitCli(args: string[]): void {
   // ⛔ 실행 «전» 스냅샷 — 이 명령이 마커를 남길 수 있는 종류일 때만 잰다(무관한 명령엔 비용 0).
   const probesForRun = SUBCOMMAND_PROBES[subcommand];
   const probesBefore = probesForRun ? probeSnapshot(args, probesForRun, process.env) : undefined;
-  if (HELP_ARGUMENTS.has(args[0] ?? '')) process.stderr.write(HELP_GUIDANCE);
+  const stderrChunks: Buffer[] = [];
+  if (HELP_ARGUMENTS.has(args[0] ?? '')) {
+    if (hasCliStderrSink()) stderrChunks.push(Buffer.from(HELP_GUIDANCE));
+    else process.stderr.write(HELP_GUIDANCE);
+  }
   let attempts = 0;
   let rawStdout: Buffer = Buffer.alloc(0);
   let rawStderr: Buffer = Buffer.alloc(0);
@@ -154,7 +159,7 @@ export function runGitCli(args: string[]): void {
   const result = runGitWithRetry(args, runner);
 
   if (rawStdout.length) process.stdout.write(rawStdout);
-  if (rawStderr.length) process.stderr.write(rawStderr);
+  if (rawStderr.length) stderrChunks.push(rawStderr);
 
   // ⛔⭐⭐⭐⭐⭐ **상태 줄은 `stderr` 로 나간다** — 2026-08-09 정정(라이브에서 «둘이» 밟았다).
   //   초판은 stdout 에 썼다. 그러면 ***산출을 값으로 쓰는 모든 소비자가 깨진다***:
@@ -166,7 +171,7 @@ export function runGitCli(args: string[]): void {
   //     `git`·`gh` 자신의 오류도 똑같이 사라지므로 일관된다.
   //   ⇒ 📌 stdout 은 이제 ***원 바이트 그대로만*** 나간다(separator 도 안 붙인다).
   const endsWithoutLf = (buf: Buffer): boolean => buf.length > 0 && buf[buf.length - 1] !== LF;
-  if (endsWithoutLf(rawStderr)) process.stderr.write('\n');
+  if (endsWithoutLf(rawStderr)) stderrChunks.push(Buffer.from('\n'));
 
   const exitCode = result.status ?? 1;
   const leftKind = exitCode !== 0 && probesForRun
@@ -176,11 +181,12 @@ export function runGitCli(args: string[]): void {
   const leftReason = leftKind
     ? `${leftKind}-${hasUnmergedPaths(args, process.env) ? 'conflict' : 'in-progress'}`
     : undefined;
-  process.stderr.write(
+  stderrChunks.push(Buffer.from(
     `[git] ${subcommand} ${exitCode === 0 ? 'ok' : 'FAILED'} rc=${exitCode}`
     + (leftReason ? ` worktree-changed=yes reason=${leftReason}` : '')
     + '\n',
-  );
+  ));
+  writeCliStderr({ source: 'git', exitCode, raw: Buffer.concat(stderrChunks) });
   process.exitCode = exitCode;
   debug.log('git.cli', 'completed', {
     subcommand,

package/src/git-fs/worktree.ts

@@ -10,7 +10,7 @@
 // because elanous's primary surface runs native git.
 
 import { spawnSync, execFileSync, type SpawnSyncReturns } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync, rmSync, symlinkSync, lstatSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync, rmSync, symlinkSync, lstatSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { findGitDir } from './locate.js';
@@ -18,6 +18,7 @@ import { isTransientGitError } from './retry.js';
 import { runGitCommand } from './runner.js';
 import { debug } from '../debug/log.js';
 import { getUserConfig } from '../user-config.js';
+import { GATE_DEPS_DIR, GATE_DEPS_TREES, projectDepsManifest } from '../task-orchestrator/surfaces/pod-gate-deps.js';
 
 const GIT_TIMEOUT_MS = 30_000;
 /** 얕은 클론(Pod `git clone --depth 50` · docker/harness/job.yaml)에서 base 를 가져올 깊이 — 클론과 같은 값.
@@ -30,6 +31,7 @@ const TRACKED_FILE_COUNT_MAX_BUFFER = 16 * 1024 * 1024;
 
 export interface WorktreeAddDeps {
   spawn?: (command: string, args: string[], options: { cwd: string; encoding: 'utf8'; timeout: number; maxBuffer: number }) => SpawnSyncReturns<string>;
+  installDependencies?: (cwd: string, timeoutMs: number) => { status: number | null; stderr?: string | null; error?: Error };
   countTrackedFiles?: (repoRoot: string, ref?: string) => number | null;
 }
 
@@ -324,6 +326,81 @@ export function linkWorktreeDependencies(
   return result;
 }
 
+const WORKTREE_DEPENDENCY_INSTALL_TIMEOUT_MS = 600_000;
+
+/** A lockfile-bearing child must have dependencies before its tests start. */
+export class WorktreeDependencyPreparationError extends Error {
+  readonly code = 'WORKTREE_DEPENDENCIES_UNAVAILABLE';
+  constructor(readonly worktreePath: string, readonly dependencyPath: string, readonly reason: string) {
+    super(`worktree dependencies unavailable (${dependencyPath}) at ${worktreePath}: ${reason}`);
+    this.name = 'WorktreeDependencyPreparationError';
+  }
+}
+
+function bakedDependenciesMatch(repoTree: string, bakedTree: string): boolean {
+  try {
+    if (!existsSync(join(bakedTree, 'node_modules'))) return false;
+    if (!readFileSync(join(repoTree, 'bun.lock')).equals(readFileSync(join(bakedTree, 'bun.lock')))) return false;
+    const source = projectDepsManifest(JSON.parse(readFileSync(join(repoTree, 'package.json'), 'utf8')) as Record<string, unknown>);
+    const baked = projectDepsManifest(JSON.parse(readFileSync(join(bakedTree, 'package.json'), 'utf8')) as Record<string, unknown>);
+    return JSON.stringify(source) === JSON.stringify(baked);
+  } catch { return false; }
+}
+
+function prepareWorktreeDependencies(repoRoot: string, worktreePath: string, opts: CreateWorktreeOpts, deps: WorktreeAddDeps): void {
+  const fallbackRoot = opts.dependencyFallbackRoot?.trim() || GATE_DEPS_DIR;
+  const timeoutMs = opts.dependencyInstallTimeoutMs ?? WORKTREE_DEPENDENCY_INSTALL_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error('dependencyInstallTimeoutMs must be a positive integer');
+  for (const tree of GATE_DEPS_TREES) {
+    const targetTree = join(worktreePath, tree);
+    const relativePath = tree === '.' ? 'node_modules' : 'apps/pwa/node_modules';
+    const target = join(worktreePath, relativePath);
+    const source = join(repoRoot, relativePath);
+    const fallbackTree = join(fallbackRoot, tree);
+    const fallback = join(fallbackTree, 'node_modules');
+    const report = (installed: boolean, ok: boolean, error: string | null, method: string): void => {
+      debug.log('git-fs.worktree', 'dependencies.prepared', {
+        worktreePath, path: relativePath, source, fallback, installed, ok, error, method,
+      }, ok ? undefined : { level: 'warn' });
+    };
+    if (existsSync(target)) { report(false, true, null, existsSync(source) ? 'source' : 'existing'); continue; }
+    try { if (lstatSync(target).isSymbolicLink()) unlinkSync(target); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    // Plain git repositories without a Bun lockfile have no dependency contract.
+    if (!existsSync(join(targetTree, 'package.json')) || !existsSync(join(targetTree, 'bun.lock'))) {
+      report(false, true, null, 'not-required');
+      continue;
+    }
+    if (bakedDependenciesMatch(targetTree, fallbackTree)) {
+      try {
+        mkdirSync(dirname(target), { recursive: true });
+        symlinkSync(fallback, target, 'dir');
+        report(false, true, null, 'fallback');
+        continue;
+      } catch (error) {
+        debug.log('git-fs.worktree', 'dependencies.fallback-failed', { worktreePath, path: relativePath, error: String(error) }, { level: 'warn' });
+      }
+    }
+    let result: { status: number | null; stderr?: string | null; error?: Error };
+    try {
+      result = deps.installDependencies
+        ? deps.installDependencies(targetTree, timeoutMs)
+        : spawnSync('bun', ['install', '--frozen-lockfile'], { cwd: targetTree, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      report(true, false, reason, 'install');
+      throw new WorktreeDependencyPreparationError(worktreePath, relativePath, reason);
+    }
+    if (result.status === 0 && existsSync(target)) { report(true, true, null, 'install'); continue; }
+    const reason = (result.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT'
+      ? `install timed out after ${timeoutMs}ms`
+      : (result.stderr ?? result.error?.message ?? `install exited ${result.status}`).trim().slice(-4096) || `install exited ${result.status}`;
+    report(true, false, reason, 'install');
+    throw new WorktreeDependencyPreparationError(worktreePath, relativePath, reason);
+  }
+}
+
 export interface CreateWorktreeOpts {
   /** Absolute repo root (main checkout). */
   repoRoot: string;
@@ -361,6 +438,12 @@ export interface CreateWorktreeOpts {
    *  기록된 owner 와 **정확히 같을 때**만 더티를 재사용 거부 사유로 쓰지 않는다(그 dirt 는 그 런 자신의 산출).
    *  ⛔ 생략·공백이면 종전 동작: 더티는 `worktree-dirty` 로 거부한다. */
   currentOwner?: string;
+  /** Baked dependency root; defaults to the harness image tree. */
+  dependencyFallbackRoot?: string;
+  /** Pod child only: require dependencies before its tests. Other callers remain fail-soft. */
+  requireDependencies?: boolean;
+  /** Maximum install time for each missing dependency tree; default 600 seconds. */
+  dependencyInstallTimeoutMs?: number;
 }
 
 /** base 를 무엇으로 확정했는지 — **모름과 부재를 값으로 가른다.**
@@ -715,6 +798,7 @@ export function createWorktree(opts: CreateWorktreeOpts, deps: WorktreeAddDeps =
       debug.log('git-fs.worktree', 'add.branch-held-reused', { branch, worktreePath: branchHolder, owner: gate.owner }, { level: 'warn' });
       const reusedLinks = linkWorktreeDependencies(repoRoot, branchHolder);
       debug.log('git-fs.worktree', 'dependencies.linked', { branch, worktreePath: branchHolder, dependencyLinks: reusedLinks });
+      if (opts.requireDependencies) prepareWorktreeDependencies(repoRoot, branchHolder, opts, deps);
       const head = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: branchHolder, encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
       const headSha = (head.stdout ?? '').trim();
       if (head.status !== 0 || headSha.length === 0) {
@@ -809,6 +893,16 @@ export function createWorktree(opts: CreateWorktreeOpts, deps: WorktreeAddDeps =
   //   idempotent). fail-soft — 링크 실패해도 worktree 자체는 유효(caller 가 필요시 install).
   const dependencyLinks = linkWorktreeDependencies(repoRoot, wtPath);
   debug.log('git-fs.worktree', 'dependencies.linked', { branch, worktreePath: wtPath, dependencyLinks });
+  if (opts.requireDependencies) {
+    try { prepareWorktreeDependencies(repoRoot, wtPath, opts, deps); }
+    catch (error) {
+      try { removeWorktree(repoRoot, wtPath, true); }
+      catch (cleanupError) {
+        debug.log('git-fs.worktree', 'dependencies.cleanup-failed', { worktreePath: wtPath, error: String(cleanupError) }, { level: 'warn' });
+      }
+      throw error;
+    }
+  }
   const resolvedBase = spawnSync('git', ['rev-parse', 'HEAD'], {
     cwd: wtPath,
     encoding: 'utf8',

package/src/graph-runner/graph-cli.ts

@@ -28,6 +28,46 @@ function findGraphFile(graphId: string): string | undefined {
 
 export function registerGraphCommands(program: Command, runsDeps: { root?: string; processStartMs?: (pid: number) => number | null } = {}): void {
   const graph = program.command('graph').description('Run a declared command graph or inspect its latest run');
+  graph.command('adapt-report')
+    .description('Measure recorded graph path diversity, unit calls, adaptations and landings for one goal')
+    .requiredOption('--goal <id>', 'Goal ID to measure')
+    .option('--json', 'Print measurement as JSON')
+    .action(async (opts: { goal: string; json?: boolean }) => {
+      try {
+        const { queryGraphAdaptReport } = await import('../self-implement/run-ledger.js');
+        const report = queryGraphAdaptReport(opts.goal);
+        if (opts.json) await writeStdoutJson(JSON.stringify(report) + '\n');
+        else if (report.runCount === 0) console.log(`graph adapt-report: ${opts.goal} · 표본 0 · 제외 ${report.excludedCount} ${JSON.stringify(report.exclusionReasons)}`);
+        else {
+          const landing = (group: typeof report.adapted) => group.denominator
+            ? `${group.landed}/${group.denominator} (${(group.rate! * 100).toFixed(1)}%)` : '표본 0';
+          console.log(`graph adapt-report: ${opts.goal} · 경로 ${report.uniquePathSignatures} · 유닛 호출 ${report.unitCallCount} · 적응 ${report.adaptationCount}`);
+          console.log(`적응 착지율 ${landing(report.adapted)} · 비적응 착지율 ${landing(report.nonAdapted)}`);
+          console.log(`제외 ${report.excludedCount} ${JSON.stringify(report.exclusionReasons)}`);
+        }
+      } catch (error) {
+        console.error(`graph adapt-report: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
+  graph.command('wizard-run <request>')
+    .description('Run one request through the smart wizard graph and stop at its approval gate')
+    .option('--json', 'Print run identity and transitions as JSON')
+    .action(async (request: string, opts: { json?: boolean }) => {
+      try {
+        await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
+        const { runWizardRequest } = await import('../smart-wizard/run.js');
+        const result = await runWizardRequest(request);
+        const summary = { graphId: result.state.graphId, runId: result.runId, status: result.status,
+          path: result.path, transitions: result.transitions };
+        if (opts.json) await writeStdoutJson(JSON.stringify(summary) + '\n');
+        else console.log(`${summary.graphId} ${summary.runId}: ${summary.status} (${summary.path.join(' → ')})`);
+        if (result.status !== 'awaiting-approval' && result.status !== 'done') process.exitCode = 1;
+      } catch (error) {
+        console.error(`graph wizard-run: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
   graph.command('run <file>')
     .option('--dry-run', 'Walk the success path without executing commands')
     .option('--json', 'Print run state as JSON')
@@ -387,12 +427,14 @@ export function registerGraphCommands(program: Command, runsDeps: { root?: strin
         const state = matches[0]!;
         const detail = { ...row(state), nodes: state.nodes.map((node) => {
           const summary = lastJsonObject(node.output)?.summary;
-          return { nodeId: node.nodeId, ok: node.ok, summary: typeof summary === 'string' ? summary.slice(0, 300) : null };
+          return { nodeId: node.nodeId, ok: node.ok, exit: node.exit,
+            ...(node.reason === undefined ? {} : { reason: node.reason }),
+            summary: typeof summary === 'string' ? summary.slice(0, 300) : null };
         }), pending: state.pending ?? null, resume: state.resume ?? null };
         if (opts.json) await writeStdoutJson(JSON.stringify(detail) + '\n');
         else {
           console.log(`${detail.runId} · ${detail.graphId} · ${detail.status} · alive=${detail.alive}`);
-          for (const node of detail.nodes) console.log(`  ${node.nodeId} · ok=${node.ok} · ${node.summary ?? '-'}`);
+          for (const node of detail.nodes) console.log(`  ${node.nodeId} · ok=${node.ok} · exit=${node.exit ?? '-'} · ${node.reason ?? node.summary ?? '-'}`);
           console.log(`pending: ${JSON.stringify(detail.pending)}`);
           console.log(`resume: ${JSON.stringify(detail.resume)}`);
         }

package/src/graph-runner/graph-run-api.ts

@@ -117,7 +117,7 @@ export function runnableIssues(doc: Record<string, unknown>, allowedRecipes: Rea
   return issues;
 }
 
-export interface GraphRunNodeView { nodeId: string; ok: boolean; executed: boolean; startedAt?: string; endedAt?: string; error?: string }
+export interface GraphRunNodeView { nodeId: string; ok: boolean; exit: number | null; executed: boolean; startedAt?: string; endedAt?: string; error?: string; reason?: string }
 export interface GraphRunView {
   graphId: string; runId: string; status: GraphRunState['status'] | 'starting';
   startedAt?: string; finishedAt?: string; path: string[];
@@ -130,9 +130,10 @@ export function graphRunView(state: GraphRunState): GraphRunView {
     ...(state.startedAt ? { startedAt: state.startedAt } : {}), ...(state.finishedAt ? { finishedAt: state.finishedAt } : {}),
     path: state.path,
     nodes: state.nodes.map((node) => ({
-      nodeId: node.nodeId, ok: node.ok, executed: node.executed,
+      nodeId: node.nodeId, ok: node.ok, exit: node.exit, executed: node.executed,
       ...(node.startedAt ? { startedAt: node.startedAt } : {}), ...(node.endedAt ? { endedAt: node.endedAt } : {}),
       ...(node.error ? { error: node.error.slice(0, 300) } : {}),
+      ...(node.reason === undefined ? {} : { reason: node.reason }),
     })),
     ...(state.currentNode ? { currentNode: state.currentNode } : {}),
   };