elanous 0.2.19 → 0.2.20

package/src/cli/retro-cli.ts

@@ -0,0 +1,78 @@
+import { existsSync } from 'node:fs';
+import type { Command } from 'commander';
+import { LogStore, logsDbPath } from '../mss/logging/log-store.js';
+
+type RetroFact = { store: string; at: string; category: string; event: string; kind: 'draft-birth' | 'draft-death' | 'stop-reason' | 'ta-outcome'; data: unknown };
+
+const FACT_EVENTS = new Map<string, RetroFact['kind']>([
+  ['rework-blocked-draft-pr', 'draft-birth'],
+  ['lineage-supersede', 'draft-death'],
+  ['resolved', 'stop-reason'],
+  ['decision', 'stop-reason'],
+  ['action', 'ta-outcome'],
+  ['task-agent.action', 'ta-outcome'],
+]);
+
+export function parseRetroSince(value: string, now = Date.now()): number {
+  const match = /^([1-9]\d*)([smhd])$/.exec(value);
+  if (!match) throw new Error('--since requires a positive duration (e.g. 24h)');
+  const duration = Number(match[1]) * ({ s: 1000, m: 60000, h: 3600000, d: 86400000 }[match[2]!] ?? 0);
+  if (!Number.isSafeInteger(duration) || !Number.isSafeInteger(now - duration)) throw new Error('--since duration is out of range');
+  return now - duration;
+}
+
+export function collectRetroFacts(sinceMs: number, targets: readonly { name: string; dbPath: string }[] = [{ name: 'current', dbPath: logsDbPath() }]): { facts: RetroFact[]; unavailable: string[] } {
+  const facts: RetroFact[] = [];
+  const unavailable: string[] = [];
+  const untilMs = Date.now();
+  for (const target of targets) {
+    if (!existsSync(target.dbPath)) { unavailable.push(target.name); continue; }
+    try {
+      const store = LogStore.openReadOnly(target.dbPath);
+      try {
+        let beforeId: number | undefined;
+        for (;;) {
+          const rows = store.query({ sinceMs, beforeId, limit: 1000 });
+          for (const row of rows) {
+            if (Date.parse(row.ts) > untilMs) continue;
+            const kind = FACT_EVENTS.get(row.event);
+            if (!kind || (row.event === 'resolved' && row.category !== 'self-dev.supervisor') || ((row.event === 'task-agent.action' || row.event === 'action') && row.category !== 'task-agent')) continue;
+            let data: unknown;
+            try { data = row.data === null ? null : JSON.parse(row.data); } catch { data = row.data; }
+            const record = data && typeof data === 'object' && !Array.isArray(data) ? data as Record<string, unknown> : {};
+            if (row.event === 'rework-blocked-draft-pr' && (row.category !== 'self-implement' || !Number.isInteger(record.number) || record.skipped || record.error)) continue;
+            if (row.event === 'lineage-supersede' && (row.category !== 'self-implement' || !Array.isArray(record.closed) || record.closed.length === 0)) continue;
+            if (row.event === 'resolved' && typeof record.stopReason !== 'string') continue;
+            if (row.event === 'decision' && (row.category !== 'self-dev.supervisor' || record.action !== 'stop' || typeof record.stopReason !== 'string')) continue;
+            if ((row.event === 'task-agent.action' || row.event === 'action') && (row.category !== 'task-agent' || typeof record.result !== 'string' || !record.result.trim())) continue;
+            facts.push({ store: target.name, at: row.ts, category: row.category, event: row.event, kind, data });
+          }
+          if (rows.length < 1000) break;
+          beforeId = rows.at(-1)!.id;
+        }
+      } finally { store.close(); }
+    } catch { unavailable.push(target.name); }
+  }
+  facts.sort((a, b) => b.at.localeCompare(a.at));
+  return { facts, unavailable };
+}
+
+export function registerRetroCommands(program: Command): void {
+  program.command('retro').description('Read-only retrospective facts from existing logs')
+    .command('facts').description('Draft births/deaths, stop reasons and task-agent outcomes')
+    .option('--since <duration>', 'Lookback duration', '24h')
+    .option('--json', 'JSON output')
+    .action((opts: { since: string; json?: boolean }) => {
+      try {
+        const sinceMs = parseRetroSince(opts.since);
+        const result = { since: new Date(sinceMs).toISOString(), ...collectRetroFacts(sinceMs) };
+        console.log(opts.json ? JSON.stringify(result) : [
+          `retro facts since ${result.since} · ${result.facts.length} facts · unavailable: ${result.unavailable.join(', ') || 'none'}`,
+          ...result.facts.map((fact) => `${fact.at} ${fact.kind} ${fact.category}.${fact.event} ${JSON.stringify(fact.data)}`),
+        ].join('\n'));
+      } catch (error) {
+        console.error(`retro facts: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 2;
+      }
+    });
+}

package/src/cli/tasks-cli.ts

@@ -1,4 +1,6 @@
-import { readFileSync } from 'node:fs';
+import { closeSync, mkdirSync, openSync, readFileSync, readSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { loadRunLedger as loadRunLedgerSync } from '../self-implement/run-ledger.js';
 import { join, resolve } from 'node:path';
 import { InvalidArgumentError, Option, type Command } from 'commander';
 import { debug } from '../debug/log.js';
@@ -8,7 +10,7 @@ import { checklistDevVersion } from '../release-loop/checklist.js';
 import { cardsBoard, countBoardTasks, INTERNAL_PACK_PROJECT, mergeBoards, releasePackBoard, type BoardNode } from '../task-agent/board.js';
 import type { Task } from '../task-orchestrator/types.js';
 import { cardPrNumber, COMPLETION_KINDS, handTask, nextMoveFor, readTaskAgentState, readTaskCard, taskAgentStatePath as taskStatePathDefault, shellQuote, TASK_CARD_PREFIX, TASK_SEATS, type CompletionKind, type TaskCard, type TaskLaunchContext, type TaskLaunchReceipt, type TaskLauncher, type TaskSeat } from '../task-agent/task-hand.js';
-import { refreshCardRunBinding, type CardRunEvidenceDeps } from '../task-agent/card-evidence.js';
+import { readCardSalvageBranch, refreshCardRunBinding, type CardRunEvidenceDeps } from '../task-agent/card-evidence.js';
 import { advanceMission, handMission, MissionAdvanceError, openMissionIds, recordPieceRef, type AdvanceMissionResult, type MissionDecompose, type PieceEvidenceReader } from '../task-agent/mission.js';
 
 type TaskRow = Pick<Task, 'id' | 'title' | 'priority' | 'status' | 'createdAt' | 'approval' | 'generatedBy'>;
@@ -82,14 +84,89 @@ export function taskLauncherArgv(configDir: string, args: readonly string[]): st
   return [ELANOUS_CLI_ENTRY, '--config-dir', configDir, ...args];
 }
 
-export async function defaultTaskLauncher(args: string[], cwd?: string, context?: TaskLaunchContext, deps: { spawn?: DetachedSpawn } = {}): Promise<void | TaskLaunchReceipt> {
+/** STOP-RECORD launch-failed: 발사 직후 이 창 안에 자식이 비0 으로 끝나면 «발사 실패»로 본다. */
+export const LAUNCH_EARLY_EXIT_WINDOW_MS = 3_000;
+
+export interface DefaultTaskLauncherDeps {
+  spawn?: DetachedSpawn;
+  /** 조기 종료 감시 창(ms) — context(런 id)가 있을 때만 · 0 이면 감시하지 않는다(옛 동작). */
+  earlyExitWindowMs?: number;
+  /** 자식 stderr 를 받을 디렉토리(시험 주입). 기본 = `<tmpdir>/elanous-task-launch`. */
+  stderrDir?: string;
+  /** stop 줄 기록기(시험 주입). 기본 = 런 원장. */
+  writeStop?: import('../self-implement/run-ledger.js').RunLedgerWriter;
+  /** 이미 stop 이 있나(시험 주입). 기본 = 이 우주 런 원장 ⊕ 이 프로세스 기록. */
+  hasStop?: (runId: string) => boolean;
+}
+
+/** stderr 파일의 첫 비어 있지 않은 줄(최대 4KB 만 읽는다 — 원 로그 꼬리를 싣지 않는다). */
+function firstStderrLine(path: string): string {
+  try {
+    const fd = openSync(path, 'r');
+    try {
+      const buf = Buffer.alloc(4096);
+      const n = readSync(fd, buf, 0, buf.length, 0);
+      return buf.subarray(0, n).toString('utf8').split(/\r?\n/).map((line) => line.trim()).find((line) => line.length > 0) ?? '';
+    } finally { closeSync(fd); }
+  } catch { return ''; }
+}
+
+export async function defaultTaskLauncher(args: string[], cwd?: string, context?: TaskLaunchContext, deps: DefaultTaskLauncherDeps = {}): Promise<void | TaskLaunchReceipt> {
   const spawn = deps.spawn ?? ((await import('node:child_process')).spawn as unknown as DetachedSpawn);
   const { getElanousConfigDirOverride } = await import('../elanous-config-dir.js');
   const { prodInstanceRoot } = await import('../instance/resolve.js');
   const configDir = getElanousConfigDirOverride() ?? prodInstanceRoot();
-  // TA-CARD-RUN-LINK: 런 id 를 자식 환경에 얹는다 — `harness say` 의 런(호스트 orchestrate)이 그 id 를 상속한다.
-  await spawnDetachedConfirmed(spawn, process.execPath, taskLauncherArgv(configDir, args), SPAWN_CONFIRM_TIMEOUT_MS, cwd, context?.env);
-  return context ? { runId: context.runId } : undefined;
+  const argv = taskLauncherArgv(configDir, args);
+  const window = context ? deps.earlyExitWindowMs ?? LAUNCH_EARLY_EXIT_WINDOW_MS : 0;
+  if (!context || window <= 0) {
+    // TA-CARD-RUN-LINK: 런 id 를 자식 환경에 얹는다 — `harness say` 의 런(호스트 orchestrate)이 그 id 를 상속한다.
+    await spawnDetachedConfirmed(spawn, process.execPath, argv, SPAWN_CONFIRM_TIMEOUT_MS, cwd, context?.env);
+    return context ? { runId: context.runId } : undefined;
+  }
+  // STOP-RECORD launch-failed: stdio 를 버리면 자식이 exit 2 로 죽어도 흔적이 0 이고 카드는 «launched» 로 남는다
+  // (ORCH-LIVE-1008). stderr 만 파일로 받고(파이프는 부모가 먼저 끝나면 자식을 EPIPE 로 죽인다), 짧은 창 안의 종료를 본다.
+  const stderrDir = deps.stderrDir ?? join(tmpdir(), 'elanous-task-launch');
+  mkdirSync(stderrDir, { recursive: true });
+  const stderrPath = join(stderrDir, `${context.runId}.stderr`);
+  // 'w' — 같은 runId 재발사가 지난 시도의 stderr 를 이번 cause 로 읽지 않게(리뷰 must-fix).
+  const fd = openSync(stderrPath, 'w');
+  let exited: Promise<{ code: number | null; signal: string | null }> | undefined;
+  const watched: DetachedSpawn = (command, spawnArgs, options) => {
+    const child = (spawn as unknown as (c: string, a: string[], o: unknown) => ReturnType<DetachedSpawn>)(command, spawnArgs, { ...options, stdio: ['ignore', 'ignore', fd] });
+    const emitter = child as unknown as { once?: (event: 'exit', listener: (code: number | null, signal: string | null) => void) => unknown };
+    exited = new Promise((done) => { emitter.once?.('exit', (code, signal) => done({ code, signal })); });
+    return child;
+  };
+  try {
+    await spawnDetachedConfirmed(watched, process.execPath, argv, SPAWN_CONFIRM_TIMEOUT_MS, cwd, context.env);
+  } finally {
+    try { closeSync(fd); } catch { /* the child keeps its own copy */ }
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const early = exited
+    ? await Promise.race([exited, new Promise<undefined>((done) => { timer = setTimeout(() => done(undefined), window); })])
+    : undefined;
+  if (timer) clearTimeout(timer);
+  if (early && early.code !== 0) {
+    const first = firstStderrLine(stderrPath);
+    const cause = `child rc=${early.code ?? early.signal ?? 'unknown'}${first ? `: ${first}` : ''}`;
+    const { boundRunStopCause, recordRunStop, runStopRecorded, RUN_STOP_EVENT } = await import('../self-implement/run-stop.js');
+    const hasStop = deps.hasStop ?? ((id: string) => {
+      if (runStopRecorded(id)) return true;
+      try { return (loadRunLedgerSync(id) ?? []).some((entry) => entry.event === RUN_STOP_EVENT); } catch { return false; }
+    });
+    // 자식이 같은 runId 로 이미 stop 을 썼으면 더하지 않는다(런마다 한 줄 · 리뷰 must-fix).
+    if (hasStop(context.runId)) throw new Error(`발사 직후 자식이 종료했다 — ${boundRunStopCause(cause)}`);
+    const entry = recordRunStop({
+      runId: context.runId, site: 'launch-failed', class: 'launch-failed',
+      cause,
+      evidenceRef: stderrPath,
+      nextMove: 'Fix the launch argv/config from the stderr evidence, then re-hand the card',
+    }, ...(deps.writeStop ? [deps.writeStop] : []));
+    // handTask 가 이 예외로 카드를 `launch-failed` 로 적는다(«launched» 로 남지 않게).
+    throw new Error(`발사 직후 자식이 종료했다 — ${String(entry.data.cause)}`);
+  }
+  return { runId: context.runId };
 }
 
 /** `spawn` 의 필요한 면만(시험 주입). */
@@ -523,8 +600,17 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
           }
           return;
         }
-        if (opts.json) out(JSON.stringify({ card, nextMove: nextMoveFor(card) }));
-        else for (const line of taskCardLines(card)) out(line);
+        // DRAFT-NOT-ARCHIVE: 멈춘 런이 draft PR 대신 남긴 수확 가지(원장 `salvaged`). 못 읽었으면 «못 읽음»(⛔ 없음 아님).
+        let salvage: Awaited<ReturnType<typeof readCardSalvageBranch>> = { salvageBranch: null };
+        try { salvage = await readCardSalvageBranch(card, deps.cardRunEvidence ?? {}); }
+        catch (error) { salvage = { salvageBranch: null, readErrors: [error instanceof Error ? error.message : String(error)] }; }
+        const salvageUnread = !salvage.salvageBranch && !!salvage.readErrors?.length;
+        if (opts.json) out(JSON.stringify({ card, nextMove: nextMoveFor(card), salvageBranch: salvage.salvageBranch, ...(salvageUnread ? { salvageBranchUnread: true } : {}) }));
+        else {
+          for (const line of taskCardLines(card)) out(line);
+          if (salvage.salvageBranch) out(`수확 가지: ${salvage.salvageBranch} (draft PR 대신)`);
+          else if (salvageUnread) out('수확 가지: 못 읽음(원장 읽기 실패)');
+        }
         return;
       }
       try {

package/src/dashboard/slash-runtime/dashboard-handlers.ts

@@ -1505,15 +1505,16 @@ export function buildDashboardSlashRegistry(nowDeps?: ContextNowDeps, decideLedg
 
   registry.register(['help', '?'], (_args, ctx) => {
     const { cols, rows } = termSize();
+    // The transient modal paints only height - 2 content rows and does not scroll.
+    // The builder adds columns to fit that budget; only when it still overflows, use the scrollable chat log.
+    const minHeight = Math.min(6, Math.max(3, rows - 2));
+    const modalContentRows = Math.max(minHeight, Math.min(rows - 4, Math.floor(rows * 0.7))) - 2;
     const lines = buildEssentialHelpLines({
       names: registry.names(),
       descriptions: SLASH_COMMANDS,
       width: Math.max(1, Math.floor(cols * 0.7) - 2),
+      maxRows: modalContentRows,
     });
-    // The transient modal paints only height - 2 content rows and does not scroll.
-    // When the catalog outgrows it, use the scrollable chat log instead of hiding keys.
-    const minHeight = Math.min(6, Math.max(3, rows - 2));
-    const modalContentRows = Math.max(minHeight, Math.min(rows - 4, Math.floor(rows * 0.7))) - 2;
     if (ctx.showHelpModal && lines.length <= modalContentRows) {
       ctx.showHelpModal({ title: 'Dashboard help', lines });
     } else {

package/src/dashboard/slash-runtime/help-from-registry.ts

@@ -43,11 +43,15 @@ export function buildEssentialHelpLines({
   descriptions,
   width,
   audience = readTuiSlashAudience(),
+  maxRows,
 }: {
   names: readonly string[];
   descriptions: readonly Pick<SlashCommand, 'name' | 'aliases' | 'description'>[];
   width: number;
   audience?: { role: Role; showBeta: boolean };
+  /** The modal's row budget. When the readable layout overflows it, add columns (shorter descriptions)
+   *  before the caller has to fall back to the chat log — TUI-HELP-OVERLAY (0.2.19 tui node «help-closes»). */
+  maxRows?: number;
 }): string[] {
   const registered = new Set(names);
   const entries = descriptions
@@ -67,41 +71,63 @@ export function buildEssentialHelpLines({
   // in each cell. Never trade a missing label for a shorter modal.
   const widestLabel = Math.max(0, ...entries.map(({ label }) => visibleWidth(label)));
   const readableCellWidth = widestLabel + 2 + 28 + 1;
-  const columns = entries.length >= 40 && width >= 100
+  const baseColumns = entries.length >= 40 && width >= 100
     ? Math.max(1, Math.floor(width / (readableCellWidth + 1)))
     : 1;
-  const columnWidth = Math.floor(width / columns);
-  // Task order (TUI-SLASH-DECIDE-NOW C): group head line, then that group's commands by name.
-  // Empty groups print no head; unmapped commands land in «그 밖», so none disappears.
-  const commandLines: string[] = [];
-  for (const group of HELP_GROUP_ORDER) {
-    const members = entries.filter(({ name }) => helpGroupFor(name) === group);
-    if (members.length === 0) continue;
-    commandLines.push(fitLine(helpGroupHeading(group), width));
-    for (let start = 0; start < members.length; start += columns) {
-      const cells = members.slice(start, start + columns).map(({ label, description }) => {
-        const cellWidth = columnWidth - (columns > 1 ? 1 : 0);
-        return visibleWidth(`${label}  `) > cellWidth ? '' : fitLine(`${label}  ${description}`, cellWidth);
-      });
-      commandLines.push(cells.map((cell, index) =>
-        index === cells.length - 1 ? cell : cell + ' '.repeat(columnWidth - visibleWidth(cell)),
-      ).join('').trimEnd());
-    }
+  // Narrowest cell that still shows the whole label and a few description characters.
+  const minCellWidth = widestLabel + 2 + 10 + 1;
+  let lines = layout(baseColumns);
+  for (let columns = baseColumns + 1; maxRows !== undefined && lines.length > maxRows
+    && Math.floor(width / columns) - 1 >= minCellWidth; columns++) {
+    lines = layout(columns);
   }
-  const keyItems = ESSENTIAL_KEYS.map(([key, description]) => `${key}  ${description}`);
-  const keyLines: string[] = [];
-  if (entries.length >= 40 && width >= 100) {
-    let keyRow = '';
-    for (const item of keyItems) {
-      if (keyRow && visibleWidth(keyRow) + 2 + visibleWidth(item) > width) {
-        keyLines.push(keyRow);
-        keyRow = '';
+  return lines;
+
+  function layout(columns: number): string[] {
+    const columnWidth = Math.floor(width / columns);
+    // Task order (TUI-SLASH-DECIDE-NOW C): group head line, then that group's commands by name.
+    // Empty groups print no head; unmapped commands land in «그 밖», so none disappears.
+    const commandLines: string[] = [];
+    const cellWidth = columnWidth - (columns > 1 ? 1 : 0);
+    const cellOf = ({ label, description }: { label: string; description: string }) =>
+      visibleWidth(`${label}  `) > cellWidth ? '' : fitLine(`${label}  ${description}`, cellWidth);
+    const pushRow = (cells: string[]) => commandLines.push(cells.map((cell, index) =>
+      index === cells.length - 1 ? cell : cell + ' '.repeat(columnWidth - visibleWidth(cell)),
+    ).join('').trimEnd());
+    if (columns > 1) {
+      // TUI-HELP-OVERLAY · 2026-10-07 — in columns the group head is a cell and groups flow on: a head line plus a
+      // half-empty last row per group pushed the catalog past the modal's rows, so /help fell back to the chat log
+      // and Esc no longer closed it (0.2.19 release tui node «help-closes»).
+      const cells: string[] = [];
+      for (const group of HELP_GROUP_ORDER) {
+        const members = entries.filter(({ name }) => helpGroupFor(name) === group);
+        if (members.length === 0) continue;
+        cells.push(fitLine(helpGroupHeading(group), cellWidth), ...members.map(cellOf));
+      }
+      for (let start = 0; start < cells.length; start += columns) pushRow(cells.slice(start, start + columns));
+    } else {
+      for (const group of HELP_GROUP_ORDER) {
+        const members = entries.filter(({ name }) => helpGroupFor(name) === group);
+        if (members.length === 0) continue;
+        commandLines.push(fitLine(helpGroupHeading(group), width));
+        for (const member of members) pushRow([cellOf(member)]);
+      }
+    }
+    const keyItems = ESSENTIAL_KEYS.map(([key, description]) => `${key}  ${description}`);
+    const keyLines: string[] = [];
+    if (entries.length >= 40 && width >= 100) {
+      let keyRow = '';
+      for (const item of keyItems) {
+        if (keyRow && visibleWidth(keyRow) + 2 + visibleWidth(item) > width) {
+          keyLines.push(keyRow);
+          keyRow = '';
+        }
+        keyRow += (keyRow ? '  ' : '') + fitLine(item, width);
       }
-      keyRow += (keyRow ? '  ' : '') + fitLine(item, width);
+      if (keyRow) keyLines.push(keyRow);
+    } else {
+      keyLines.push(...keyItems.map((item) => fitLine(item, width)));
     }
-    if (keyRow) keyLines.push(keyRow);
-  } else {
-    keyLines.push(...keyItems.map((item) => fitLine(item, width)));
+    return [fitLine('Commands', width), ...commandLines, '', fitLine('Keys', width), ...keyLines];
   }
-  return [fitLine('Commands', width), ...commandLines, '', fitLine('Keys', width), ...keyLines];
 }

package/src/domains/outbound-log-probe.ts

@@ -2,7 +2,12 @@ import { inQuietHours, kstMinutes, sendOutbound, setInProcessOutbound } from './
 import { setUserConfigOverlay } from '../user-config.js';
 
 // Focused subprocess fixture: isolated state/config roots and a fake curl on PATH.
-setUserConfigOverlay(cfg => ({ ...cfg, telegram: { ...cfg.telegram, botToken: '123456:private-secret', homeChannel: 98765 } }));
+// Hermetic: the shared `.elanous-test` config may carry a routing table another test left behind (a declared
+// `channels` table is authoritative and never falls back to the main home), so the fixture owns every routing key.
+setUserConfigOverlay(cfg => ({ ...cfg, telegram: {
+  ...cfg.telegram, channels: undefined, reportChannel: undefined, testChannel: undefined,
+  botToken: '123456:private-secret', homeChannel: 98765,
+} }));
 process.env.SEND_VIA_ELANOUS = '0';
 // Quiet hours (00:00~06:30 KST) defer instead of sending, so a gate run at night saw no `sent` row.
 // Shift this fixture's clock back to 23:59 KST of the previous day; the shift stays inside this process.

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

@@ -0,0 +1,205 @@
+// CGE-RUN — 편집기에서 «내 그래프»를 실행하고 노드별 상태를 읽는다.
+// 실행은 `elanous graph run` 과 같은 범용 실행기(runGraph)다. 하니스(LLM) 런은 골 종류로만 그래프를 고르므로 여기서 다루지 않는다.
+// 그래프와 레시피는 런마다 작업 폴더로 «복사»해서 돌린다 — 실행 중에 편집기가 파일을 바꿔도 이 런은 시작한 판으로 끝난다.
+// ⛔ 레시피(실제로 도는 명령)는 «저장소»의 편집기 레시피(`graphs/demo/editor-recipes.yaml`)만 쓴다 — «mine» 폴더는 HTTP 로 쓸 수 있으므로
+//    거기 레시피를 읽으면 «편집한 그래프 실행»이 «편집한 명령 실행»이 된다(TC 10-07 19:31). 그래프가 부르는 레시피가 그 목록에 없으면 시작 전에 거부한다.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { jsonResponse } from '../nexus/api/json-response.js';
+import { defaultGraphsDir } from '../self-implement/graph-templates.js';
+import { runGraph, type GraphRunState } from './runner.js';
+
+const GRAPH_ID = /^[a-z0-9-]+$/;
+const RUN_ID = /^ed-[a-z0-9]+-[a-f0-9]{6}$/;
+/** 실행기가 받는 끝 노드 이름(runner.ts — `unsupported terminal node`). 미리 말해 준다. */
+const RUNNABLE_TERMINALS = new Set(['done', 'failed']);
+
+export interface GraphRunApiDeps {
+  mineDir?: string;
+  /** 편집기 실행이 쓰는 레시피 파일(저장소 것만) — 기본 `graphs/demo/editor-recipes.yaml`. */
+  recipesFile?: string;
+  root?: string;
+  run?: typeof runGraph;
+  now?: () => number;
+}
+
+/** 시작 전에 죽은 런(레시피 없음 등)은 원장 파일이 안 생긴다 — 그 이유를 여기 잠깐 들고 있다가 상태 조회에 돌려준다. */
+const startFailures = new Map<string, { error: string; at: string }>();
+
+const mineDirOf = (deps: GraphRunApiDeps) => deps.mineDir ?? join(elanousStateRoot(), 'graphs');
+const rootOf = (deps: GraphRunApiDeps) => deps.root ?? effectiveInstanceRoot();
+
+function decodeId(raw: string, pattern: RegExp): string | null {
+  try {
+    const id = decodeURIComponent(raw);
+    return pattern.test(id) ? id : null;
+  } catch { return null; }
+}
+
+/** 파일 이름이 아니라 선언된 graph_id 로 찾는다(graphs-api 와 같은 규칙). */
+function findMine(dir: string, id: string): { file: string; doc: Record<string, unknown> } | null {
+  let names: string[];
+  try { names = readdirSync(dir).filter((name) => name.endsWith('.yaml') || name.endsWith('.yml')).sort(); }
+  catch { return null; }
+  for (const name of names) {
+    if (name === 'recipes.yaml') continue;
+    try {
+      const doc: unknown = parseYaml(readFileSync(join(dir, name), 'utf8'));
+      if (doc && typeof doc === 'object' && !Array.isArray(doc) && (doc as Record<string, unknown>).graph_id === id) {
+        return { file: join(dir, name), doc: doc as Record<string, unknown> };
+      }
+    } catch { continue; }
+  }
+  return null;
+}
+
+/** 되돌이(순환) 위의 노드가 max_visits 1 이면 두 번째 방문에서 예산 초과로 멈춘다 — 시작 전에 말한다. */
+function loopVisitIssues(doc: Record<string, unknown>): string[] {
+  const next = new Map<string, Set<string>>();
+  for (const edge of Array.isArray(doc.edges) ? doc.edges : []) {
+    if (!edge || typeof edge !== 'object') continue;
+    const { from, to, map } = edge as Record<string, unknown>;
+    if (typeof from !== 'string') continue;
+    const targets = [...(typeof to === 'string' ? [to] : []),
+      ...(map && typeof map === 'object' ? Object.values(map as Record<string, unknown>).filter((v): v is string => typeof v === 'string') : [])];
+    for (const target of targets) (next.get(from) ?? next.set(from, new Set()).get(from)!).add(target);
+  }
+  const reaches = (start: string, goal: string): boolean => {
+    const seen = new Set<string>();
+    const stack = [...(next.get(start) ?? [])];
+    while (stack.length) {
+      const id = stack.pop()!;
+      if (id === goal) return true;
+      if (seen.has(id)) continue;
+      seen.add(id);
+      stack.push(...(next.get(id) ?? []));
+    }
+    return false;
+  };
+  const issues: string[] = [];
+  for (const node of Array.isArray(doc.nodes) ? doc.nodes : []) {
+    if (!node || typeof node !== 'object') continue;
+    const { node_id: id, max_visits: visits } = node as Record<string, unknown>;
+    if (typeof id === 'string' && (typeof visits !== 'number' || visits < 2) && reaches(id, id)) {
+      issues.push(`노드 '${id}' 는 되돌이 위에 있는데 max_visits 가 ${typeof visits === 'number' ? visits : '없음'} 이다 — 두 번째 방문에서 멈춘다 · 2 이상으로`);
+    }
+  }
+  return issues;
+}
+
+/** 실행기가 받지 않을 모양을 시작 «전»에 사람 말로. 빈 배열이면 돌릴 수 있다. */
+export function runnableIssues(doc: Record<string, unknown>, allowedRecipes: ReadonlySet<string>): string[] {
+  const issues: string[] = [];
+  for (const node of Array.isArray(doc.nodes) ? doc.nodes : []) {
+    if (!node || typeof node !== 'object') continue;
+    const { node_id: nodeId, recipe } = node as Record<string, unknown>;
+    if (typeof recipe !== 'string' || recipe === 'none') continue;
+    if (recipe.startsWith('approval:')) { issues.push(`노드 '${String(nodeId)}' 의 승인 레시피 '${recipe}' 는 편집기 데모 실행에서 쓸 수 없다`); continue; }
+    const prefixed = /^cmd:(.*)$/.exec(recipe);
+    if (prefixed && !allowedRecipes.has(prefixed[1]!)) {
+      issues.push(`노드 '${String(nodeId)}' 의 레시피 '${recipe}' 는 편집기 실행 목록에 없다 — 쓸 수 있는 것: ${[...allowedRecipes].map((r) => `cmd:${r}`).join(' · ')}`);
+    }
+  }
+  // grow 는 매핑 안 된 결과에서 LLM 제안기를 부른다 — 데모 실행 범위 밖(하니스 LLM 런은 0.2.21).
+  if (doc.grow !== undefined) issues.push('grow(그래프 자라기)는 편집기 데모 실행에서 쓸 수 없다 — grow 줄을 지우고 저장하라');
+  issues.push(...loopVisitIssues(doc));
+  const terminals = Array.isArray(doc.terminal_nodes) ? doc.terminal_nodes.filter((t): t is string => typeof t === 'string') : [];
+  if (!terminals.length) issues.push('끝 노드가 없다 — done 노드를 잇고 끝으로 지정하라');
+  for (const t of terminals) if (!RUNNABLE_TERMINALS.has(t)) issues.push(`끝 노드 '${t}' 는 실행할 수 없다 — 끝 노드 이름은 done 또는 failed 여야 한다`);
+  return issues;
+}
+
+export interface GraphRunNodeView { nodeId: string; ok: boolean; executed: boolean; startedAt?: string; endedAt?: string; error?: string }
+export interface GraphRunView {
+  graphId: string; runId: string; status: GraphRunState['status'] | 'starting';
+  startedAt?: string; finishedAt?: string; path: string[];
+  nodes: GraphRunNodeView[]; currentNode?: { nodeId: string; startedAt: string }; error?: string;
+}
+
+export function graphRunView(state: GraphRunState): GraphRunView {
+  return {
+    graphId: state.graphId, runId: state.runId, status: state.status,
+    ...(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,
+      ...(node.startedAt ? { startedAt: node.startedAt } : {}), ...(node.endedAt ? { endedAt: node.endedAt } : {}),
+      ...(node.error ? { error: node.error.slice(0, 300) } : {}),
+    })),
+    ...(state.currentNode ? { currentNode: state.currentNode } : {}),
+  };
+}
+
+/** POST /v1/graphs/<id>/run — 내 그래프만 실행한다(핵심 그래프는 복제해서 돌린다). 응답은 기다리지 않는다(202 ⊕ runId). */
+export function handleGraphRunStart(rawId: string, deps: GraphRunApiDeps = {}): Response {
+  const id = decodeId(rawId, GRAPH_ID);
+  if (!id) return jsonResponse({ error: 'bad_request', reason: 'invalid graph id' }, 400);
+  const mine = findMine(mineDirOf(deps), id);
+  if (!mine) return jsonResponse({ error: 'not-found', id, reason: '내 그래프에만 실행이 있다 — 핵심 그래프는 복제해서 돌린다' }, 404);
+  const recipesFile = deps.recipesFile ?? join(defaultGraphsDir(), 'demo', 'editor-recipes.yaml');
+  let recipeText: string;
+  let allowed: Set<string>;
+  try {
+    recipeText = readFileSync(recipesFile, 'utf8');
+    const parsed: unknown = parseYaml(recipeText);
+    allowed = new Set(parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? Object.keys(parsed) : []);
+  } catch {
+    return jsonResponse({ error: 'recipes-unavailable' }, 503);
+  }
+  const issues = runnableIssues(mine.doc, allowed);
+  if (issues.length) return jsonResponse({ error: 'not-runnable', id, issues }, 422);
+
+  const now = deps.now?.() ?? Date.now();
+  const runId = `ed-${now.toString(36)}-${randomBytes(3).toString('hex')}`;
+  const root = rootOf(deps);
+  const work = join(root, 'graph-run-work', id, runId);
+  try {
+    mkdirSync(work, { recursive: true });
+    copyFileSync(mine.file, join(work, 'graph.yaml'));
+    writeFileSync(join(work, 'recipes.yaml'), recipeText);
+  } catch (error) {
+    return jsonResponse({ error: 'run-workspace-failed', reason: error instanceof Error ? error.message.slice(0, 200) : 'unknown' }, 500);
+  }
+  debug.log('graphs.run', 'started', { id, runId });
+  void (deps.run ?? runGraph)(join(work, 'graph.yaml'), { runId, input: { source: 'editor' }, deps: { root } })
+    .then((state) => debug.log('graphs.run', 'finished', { id, runId, status: state.status, executed: state.executed }))
+    .catch((error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      startFailures.set(runId, { error: message.slice(0, 300), at: new Date().toISOString() });
+      if (startFailures.size > 50) startFailures.delete(startFailures.keys().next().value!);
+      debug.log('graphs.run', 'failed', { id, runId, error: message.slice(0, 200) }, { level: 'warn' });
+    });
+  return jsonResponse({ id, runId, demo: true }, 202);
+}
+
+/** GET /v1/graphs/<id>/runs/<runId> — 원장 그대로(노드별 ok·시각 · 지금 노드). 원장이 아직 없으면 starting, 시작 전에 죽었으면 failed ⊕ 이유. */
+export function handleGraphRunGet(rawId: string, rawRunId: string, deps: GraphRunApiDeps = {}): Response {
+  const id = decodeId(rawId, GRAPH_ID);
+  const runId = decodeId(rawRunId, RUN_ID);
+  if (!id || !runId) return jsonResponse({ error: 'bad_request', reason: 'invalid id' }, 400);
+  const file = join(rootOf(deps), 'graph-runs', id, `${runId}.json`);
+  let state: GraphRunState | null = null;
+  try { state = JSON.parse(readFileSync(file, 'utf8')) as GraphRunState; } catch { state = null; }
+  if (state && state.graphId === id && state.runId === runId) return jsonResponse(graphRunView(state));
+  const failed = startFailures.get(runId);
+  if (failed) return jsonResponse({ graphId: id, runId, status: 'failed', path: [], nodes: [], error: failed.error } satisfies GraphRunView);
+  if (!existsSync(join(rootOf(deps), 'graph-run-work', id, runId))) return jsonResponse({ error: 'not-found', id, runId }, 404);
+  return jsonResponse({ graphId: id, runId, status: 'starting', path: [], nodes: [] } satisfies GraphRunView);
+}
+
+const RUN_START = /^\/v1\/graphs\/([^/]+)\/run$/;
+const RUN_GET = /^\/v1\/graphs\/([^/]+)\/runs\/([^/]+)$/;
+
+/** http-server 가 인증 «뒤»에 부른다. 이 두 길이 아니면 null. */
+export function handleGraphRunRoute(method: string, pathname: string, deps: GraphRunApiDeps = {}): Response | null {
+  const start = RUN_START.exec(pathname);
+  if (start && method === 'POST') return handleGraphRunStart(start[1]!, deps);
+  const get = RUN_GET.exec(pathname);
+  if (get && method === 'GET') return handleGraphRunGet(get[1]!, get[2]!, deps);
+  return null;
+}

package/src/graph-runner/runner.ts

@@ -66,6 +66,12 @@ export interface GraphRunOptions {
   resumeGraphId?: string;
   fromNodeId?: string;
   useCurrentGraph?: boolean;
+  /**
+   * RELEASE-LEDGER-UNIVERSE — stamp every cmd: child with this run's ledger root (`ELANOUS_STATE_DIR`).
+   * Without it a child launched from a non-leader tree (`bun scripts/...` with cwd = that tree) re-resolves
+   * its own universe and lands in the tree-derived test universe while the run ledger is prod.
+   */
+  pinChildUniverse?: boolean;
   deps?: { root?: string; runBash?: BashRun; log?: (event: string, data: Record<string, unknown>) => void; processStartMs?: (pid: number) => number | null; growthProposer?: GrowthProposer; growthLLM?: (prompt: string) => Promise<string>; classifyGrowthRecipe?: (node: GraphNodeSpec, resolved: { command?: string; approval?: string }) => GrowthRecipeEffect; growthDecision?: GrowthDecisionDeps & { list?: (filters: { status: 'all' }) => DecisionEntry[] } };
 }
 
@@ -714,7 +720,11 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       // state stamp so a cmd: child resolves its default config in the same universe.
       // The ignored config-dir environment variable must not appear to propagate the flag.
       delete env.ELANOUS_CONFIG_DIR;
-      if (getElanousConfigDirOverride()) {
+      if (options.pinChildUniverse) {
+        // The run's own ledger root is the parent universe — the child writes where the run is recorded.
+        env.ELANOUS_STATE_DIR = root;
+        debug.log('graph-runner', 'child-universe-pinned', { graphId, runId, node: current, configDir: getElanousConfigDirOverride() ?? null, stateDir: env.ELANOUS_STATE_DIR, why: 'pinChildUniverse' });
+      } else if (getElanousConfigDirOverride()) {
         env.ELANOUS_STATE_DIR = effectiveInstanceRoot();
         debug.log('graph-runner', 'child-universe-pinned', { graphId, runId, node: current, configDir: getElanousConfigDirOverride(), stateDir: env.ELANOUS_STATE_DIR });
       }