elanous 0.2.9 → 0.2.10

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

@@ -1,16 +1,40 @@
 import type { Command } from 'commander';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
 import { writeStdoutJson } from '../cli/stdout-json.js';
-import { decideGraphApproval, latestGraphRun, runGraph } from './runner.js';
+import { debug } from '../debug/log.js';
+import { decideGraphApproval, graphRunAlive, lastJsonObject, latestGraphRun, listGraphRuns, runGraph, type GraphRunState } from './runner.js';
 
-export function registerGraphCommands(program: Command): void {
+function findGraphFile(graphId: string): string | undefined {
+  const roots = [resolve('graphs'), resolve(import.meta.dir, '../../graphs')];
+  for (const root of roots) {
+    for (const dir of [root, ...['release', 'ops'].map((part) => join(root, part))]) {
+      if (!existsSync(dir)) continue;
+      for (const name of readdirSync(dir)) {
+        if (!name.endsWith('.yaml') || name === 'recipes.yaml') continue;
+        const file = join(dir, name);
+        if (!existsSync(join(dir, 'recipes.yaml'))) continue;
+        try {
+          const parsed: unknown = parseYaml(readFileSync(file, 'utf8'));
+          if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && (parsed as Record<string, unknown>).graph_id === graphId) return file;
+        } catch { continue; }
+      }
+    }
+  }
+  return 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('run <file>')
     .option('--dry-run', 'Walk the success path without executing commands')
     .option('--json', 'Print run state as JSON')
     .option('--resume <run_id>', 'Resume a persisted run awaiting approval or restart a failed path with --from')
     .option('--from <node_id>', 'Restart a failed run at a node on its saved path (requires --resume)')
+    .option('--use-current-graph', 'Use the installed graph rather than the run snapshot')
     .option('--input <json>', 'JSON object passed to the graph run')
-    .action(async (file: string, opts: { dryRun?: boolean; json?: boolean; resume?: string; from?: string; input?: string }) => {
+    .action(async (file: string, opts: { dryRun?: boolean; json?: boolean; resume?: string; from?: string; input?: string; useCurrentGraph?: boolean }) => {
       try {
         await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
         if (opts.resume && opts.dryRun) throw new Error('--resume cannot be combined with --dry-run');
@@ -23,7 +47,7 @@ export function registerGraphCommands(program: Command): void {
           if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('--input must be a JSON object');
           input = parsed as Record<string, unknown>;
         }
-        const state = await runGraph(file, { ...(opts.resume ? { resumeRunId: opts.resume } : { dryRun: opts.dryRun }), ...(opts.from ? { fromNodeId: opts.from } : {}), ...(input === undefined ? {} : { input }) });
+        const state = await runGraph(file, { ...(opts.resume ? { resumeRunId: opts.resume } : { dryRun: opts.dryRun }), ...(opts.from ? { fromNodeId: opts.from } : {}), useCurrentGraph: opts.useCurrentGraph, ...(input === undefined ? {} : { input }) });
         if (opts.json) await writeStdoutJson(JSON.stringify(state) + '\n');
         else console.log(`${state.graphId} ${state.runId}: ${state.status} (${state.path.join(' → ')}, executed: ${state.executed})${state.pending ? ` — ${state.pending.message}` : ''}`);
         if (state.status !== 'done' && state.status !== 'awaiting-approval') process.exitCode = 1;
@@ -87,6 +111,107 @@ export function registerGraphCommands(program: Command): void {
         process.exitCode = 1;
       }
     });
+  const runs = graph.command('runs').description('List and inspect persisted graph runs');
+  const alive = (state: GraphRunState) => graphRunAlive(state, runsDeps.processStartMs);
+  const row = (state: GraphRunState) => ({
+    runId: state.runId, graphId: state.graphId, status: state.status,
+    lastNode: state.path.at(-1) ?? null, startedAt: state.startedAt ?? null,
+    finishedAt: state.finishedAt ?? null, alive: alive(state),
+  });
+  const warning = (unreadable: number) => { if (unreadable) console.error(`⚠ 못 읽은 원장 ${unreadable}`); };
+  runs.command('list')
+    .option('--graph <id>', 'Filter by graph id')
+    .option('--state <status>', 'Filter by run status')
+    .option('--limit <N>', 'Maximum number of runs')
+    .option('--json', 'Print runs as JSON')
+    .action(async (opts: { graph?: string; state?: string; limit?: string; json?: boolean }) => {
+      try {
+        if (opts.limit !== undefined && (!/^[1-9]\d*$/.test(opts.limit) || !Number.isSafeInteger(Number(opts.limit)))) throw new Error('--limit must be a positive integer');
+        const { runs: all, unreadable } = listGraphRuns(runsDeps.root);
+        const selected = all.filter((state) => (!opts.graph || state.graphId === opts.graph) && (!opts.state || state.status === opts.state))
+          .slice(0, opts.limit === undefined ? undefined : Number(opts.limit)).map(row);
+        debug.log('graph.runs', 'list', { count: selected.length, unreadable, alive: selected.filter((state) => state.alive === true).length });
+        if (opts.json) await writeStdoutJson(JSON.stringify(selected) + '\n');
+        else for (const state of selected) console.log(`${state.runId} · ${state.graphId} · ${state.status} · ${state.lastNode ?? '-'} · ${state.startedAt ?? '-'} · ${state.finishedAt ?? '-'} · alive=${state.alive}`);
+        warning(unreadable);
+      } catch (error) {
+        console.error(`graph runs list: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
+  runs.command('resume <run_id>')
+    .option('--from <node_id>', 'Restart at this node on the saved path')
+    .option('--use-current-graph', 'Use the installed graph and enforce the original hash')
+    .option('--file <path>', 'Graph file for a legacy run without a recorded graph path')
+    .option('--json', 'Print run state as JSON')
+    .action(async (runId: string, opts: { from?: string; useCurrentGraph?: boolean; file?: string; json?: boolean }) => {
+      try {
+        await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId) || runId === '.' || runId === '..') throw new Error(`invalid run id: ${runId}`);
+        const { runs: all, unreadable } = listGraphRuns(runsDeps.root);
+        const exact = all.filter((state) => state.runId === runId);
+        const matches = exact.length ? exact : all.filter((state) => state.runId.startsWith(runId));
+        if (matches.length !== 1) {
+          if (matches.length) console.error(`ambiguous run id: ${runId}\n${matches.map((state) => `${state.graphId}/${state.runId}`).join('\n')}`);
+          else console.error(`no run: ${runId}`);
+          warning(unreadable);
+          process.exitCode = 1;
+          return;
+        }
+        const saved = matches[0]!;
+        if (saved.graphSnapshot && opts.file && (!saved.graphPath || resolve(opts.file) !== resolve(saved.graphPath))) {
+          throw new Error('--file cannot change the graph path of a snapshot run (이 런은 시작 때 그래프 사본이 있다 — --file 대신 --use-current-graph)');
+        }
+        const from = opts.from ?? (saved.status === 'failed' ? [...saved.nodes].reverse().find((node) => !node.ok)?.nodeId : undefined);
+        const file = saved.graphSnapshot
+          ? saved.graphPath
+          : opts.file ?? (saved.graphPath && existsSync(saved.graphPath) ? saved.graphPath : undefined) ?? findGraphFile(saved.graphId);
+        if (!file) throw new Error(`graph file not found for ${saved.graphId}/${saved.runId}; provide --file`);
+        const state = await runGraph(file, { resumeRunId: saved.runId, resumeGraphId: saved.graphId, fromNodeId: from,
+          useCurrentGraph: opts.useCurrentGraph, deps: { root: runsDeps.root } });
+        if (opts.json) await writeStdoutJson(JSON.stringify(state) + '\n');
+        else console.log(`${state.graphId} ${state.runId}: ${state.status} (${state.path.join(' → ')}, executed: ${state.executed})`);
+        if (state.status !== 'done' && state.status !== 'awaiting-approval') process.exitCode = 1;
+        warning(unreadable);
+      } catch (error) {
+        console.error(`graph runs resume: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
+  runs.command('status <run_id>')
+    .option('--json', 'Print run detail as JSON')
+    .action(async (runId: string, opts: { json?: boolean }) => {
+      try {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId) || runId === '.' || runId === '..') throw new Error(`invalid run id: ${runId}`);
+        const { runs: all, unreadable } = listGraphRuns(runsDeps.root);
+        const exact = all.filter((state) => state.runId === runId);
+        const matches = exact.length ? exact : all.filter((state) => state.runId.startsWith(runId));
+        debug.log('graph.runs', 'status', { count: matches.length, unreadable, alive: matches.filter((state) => alive(state) === true).length });
+        if (matches.length !== 1) {
+          if (matches.length) console.error(`ambiguous run id: ${runId}\n${matches.map((state) => `${state.graphId}/${state.runId}`).join('\n')}`);
+          else console.error(`no run: ${runId}`);
+          warning(unreadable);
+          process.exitCode = 1;
+          return;
+        }
+        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 };
+        }), 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 ?? '-'}`);
+          console.log(`pending: ${JSON.stringify(detail.pending)}`);
+          console.log(`resume: ${JSON.stringify(detail.resume)}`);
+        }
+        warning(unreadable);
+      } catch (error) {
+        console.error(`graph runs status: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
   graph.command('status <graph_id>')
     .option('--json', 'Print latest run state as JSON')
     .action(async (graphId: string, opts: { json?: boolean }) => {

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

@@ -2,6 +2,8 @@ import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readdirSy
 import { join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { debug } from '../debug/log.js';
+import { applyDecidedApprovals, raiseApprovalCard, type GraphApprovalCardDeps } from './graph-approval-card.js';
 import type { GraphRunState } from './runner.js';
 
 export interface GraphNotificationEvent {
@@ -20,6 +22,7 @@ export interface GraphNotifyOptions {
   graphsDir?: string;
   dryRun?: boolean;
   send?: (message: string, event: GraphNotificationEvent) => Promise<void> | void;
+  approvalCard?: Pick<GraphApprovalCardDeps, 'ledger'>;
 }
 
 type NotificationSetting = boolean | string | { on?: string | string[]; enabled?: boolean };
@@ -177,16 +180,35 @@ export async function notifyGraphEvents(options: GraphNotifyOptions = {}): Promi
     return collectGraphEvents({ root, graphsDir: options.graphsDir }).filter((event) => !sent.has(event.id));
   };
   if (options.dryRun) return collectFresh();
+  const syncApprovals = () => {
+    const deps = { root, ...options.approvalCard };
+    try { applyDecidedApprovals(deps); }
+    catch (error) {
+      debug.log('graph.approval-card', 'skipped', { graphId: undefined, runId: undefined, nodeId: undefined,
+        decisionId: undefined, outcome: undefined, reason: error instanceof Error ? error.message : String(error) });
+    }
+    for (const event of collectGraphEvents({ root, graphsDir: options.graphsDir })) {
+      if (event.kind !== 'approval') continue;
+      try {
+        const state = JSON.parse(readFileSync(join(root, 'graph-runs', event.graphId, `${event.runId}.json`), 'utf8')) as GraphRunState;
+        if (state.pending?.nodeId === event.nodeId) raiseApprovalCard(state, state.pending, deps);
+      } catch (error) {
+        debug.log('graph.approval-card', 'skipped', { graphId: event.graphId, runId: event.runId, nodeId: event.nodeId,
+          decisionId: undefined, outcome: undefined, reason: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  };
   // The former .lock path was a directory; use a separate, stable inode instead of trying to reclaim it.
   const lock = `${ledgerPath}.flock`;
   mkdirSync(join(root, 'graph-runs'), { recursive: true });
   const flock = await loadFlock();
-  if (!flock) return notifyWithExclusiveFile(`${ledgerPath}.owner`, collectFresh, options.send, ledgerPath);
+  if (!flock) return notifyWithExclusiveFile(`${ledgerPath}.owner`, collectFresh, options.send, ledgerPath, syncApprovals);
   const fd = openSync(lock, 'a');
   let acquired = false;
   try {
     if (flock(fd, LOCK_EX_NB) !== 0) throw new Error('graph notification is already running');
     acquired = true;
+    syncApprovals();
     return await sendFresh(collectFresh(), options.send, ledgerPath);
   } finally {
     try {
@@ -209,12 +231,12 @@ async function sendFresh(fresh: GraphNotificationEvent[], sendOption: GraphNotif
 }
 
 /** Platforms without flock (Windows, musl): an exclusive owner file. A crash leaves it behind, and the next run names it instead of double-sending. */
-async function notifyWithExclusiveFile(ownerPath: string, collectFresh: () => GraphNotificationEvent[], send: GraphNotifyOptions['send'], ledgerPath: string): Promise<GraphNotificationEvent[]> {
+async function notifyWithExclusiveFile(ownerPath: string, collectFresh: () => GraphNotificationEvent[], send: GraphNotifyOptions['send'], ledgerPath: string, syncApprovals: () => void): Promise<GraphNotificationEvent[]> {
   try { writeFileSync(ownerPath, String(process.pid), { flag: 'wx' }); }
   catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'EEXIST') throw new Error(`graph notification is already running (or a crashed run left ${ownerPath} — remove it if no notifier is running)`);
     throw error;
   }
-  try { return await sendFresh(collectFresh(), send, ledgerPath); }
+  try { syncApprovals(); return await sendFresh(collectFresh(), send, ledgerPath); }
   finally { rmSync(ownerPath, { force: true }); }
 }

package/src/graph-runner/runner.ts

@@ -11,6 +11,7 @@ import { credentialStatus, pluginEnv } from '../plugins/install/plugin-credentia
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { loadNodeCatalog } from '../self-implement/graph-catalog.js';
 import { parseGraphTemplateYaml, type GraphEdgeSpec, type GraphNodeSpec } from '../self-implement/graph-yaml.js';
+import { psProcessStartMs, START_TOLERANCE_MS } from '../harness/harness-stop.js';
 import { executeBashNode } from '../workflow-runtime/nodes/bash.js';
 import type { BashNode, NodeExecContext, WorkflowDeps } from '../workflow-runtime/types.js';
 
@@ -21,6 +22,8 @@ export interface GraphRunState {
   runId: string;
   startedAt?: string;
   finishedAt?: string;
+  pid?: number;
+  pidStartedAt?: string;
   status: 'running' | 'done' | 'failed' | 'budget-exceeded' | 'awaiting-approval';
   path: string[];
   nodes: Array<{ nodeId: string; ok: boolean; exit: number | null; executed: boolean; output?: unknown; error?: string; decidedBy?: string; decidedAt?: string }>;
@@ -29,7 +32,9 @@ export interface GraphRunState {
   approvalSourceHash?: string;
   /** Hash of the graph and recipes used for this run; required to safely restart a failed path. */
   sourceHash?: string;
-  resume?: { from: string; at: string; previousStatus: 'failed' };
+  graphSnapshot?: { graphSha: string; recipesSha: string };
+  graphPath?: string;
+  resume?: { from: string; at: string; previousStatus: GraphRunState['status']; graph?: 'snapshot' | 'current' };
   executed: number;
   dryRun: boolean;
   statePath: string;
@@ -40,8 +45,10 @@ export interface GraphRunOptions {
   dryRun?: boolean;
   runId?: string;
   resumeRunId?: string;
+  resumeGraphId?: string;
   fromNodeId?: string;
-  deps?: { root?: string; runBash?: BashRun; log?: (event: string, data: Record<string, unknown>) => void };
+  useCurrentGraph?: boolean;
+  deps?: { root?: string; runBash?: BashRun; log?: (event: string, data: Record<string, unknown>) => void; processStartMs?: (pid: number) => number | null };
 }
 
 function safeSegment(value: string): string {
@@ -157,13 +164,19 @@ function persistGraphRun(state: GraphRunState): void {
   renameSync(temporary, state.statePath);
 }
 
-export function decideGraphApproval(graphId: string, runId: string, decision: 'approved' | 'rejected', by?: string, root = effectiveInstanceRoot()): GraphRunState {
+export interface ExpectedGraphApprovalVisit { nodeId: string; visit: number }
+
+export function decideGraphApproval(graphId: string, runId: string, decision: 'approved' | 'rejected', by?: string, root = effectiveInstanceRoot(), expected?: ExpectedGraphApprovalVisit): GraphRunState {
   const state = readGraphRun(graphId, runId, root);
-  if (state.status !== 'awaiting-approval' || !state.pending || state.pending.decision) {
+  if (state.status !== 'awaiting-approval' || !state.pending || state.pending.decision ||
+      (expected && (state.dryRun || state.pending.nodeId !== expected.nodeId || state.path.at(-1) !== expected.nodeId ||
+        !Number.isSafeInteger(expected.visit) || expected.visit < 1 ||
+        state.path.filter(node => node === expected.nodeId).length !== expected.visit))) {
     throw new Error(`run is not awaiting an undecided approval: ${graphId}/${runId}`);
   }
   if (by !== undefined && !by.trim()) throw new Error('approver name must not be empty');
   const recorded = { nodeId: state.pending.nodeId, decision, ...(by === undefined ? {} : { decidedBy: by }), decidedAt: new Date().toISOString() };
+  // A card can claim only the visit it names; never derive a later visit's claim path from a fresh read.
   const decisionPath = approvalDecisionPath(state);
   const temporary = `${decisionPath}.${randomUUID()}.tmp`;
   writeFileSync(temporary, JSON.stringify(recorded) + '\n', { flag: 'wx' });
@@ -206,7 +219,26 @@ function nextNode(edges: readonly GraphEdgeSpec[], nodeId: string, exitOutcome:
 }
 
 export async function runGraph(path: string, options: GraphRunOptions = {}): Promise<GraphRunState> {
-  const source = readFileSync(path, 'utf8');
+  if (options.resumeRunId && options.runId) throw new Error('runId and resumeRunId cannot be combined');
+  if (options.fromNodeId && !options.resumeRunId) throw new Error('--from requires --resume');
+  if (options.useCurrentGraph && !options.resumeRunId) throw new Error('--use-current-graph requires --resume');
+  const root = options.deps?.root ?? effectiveInstanceRoot();
+  const matchingRuns = options.resumeRunId && !options.resumeGraphId
+    ? listGraphRuns(root).runs.filter((run) => run.runId === options.resumeRunId && run.graphPath === resolve(path)) : [];
+  if (matchingRuns.length > 1) throw new Error(`ambiguous run id: ${options.resumeRunId}`);
+  const currentSource = options.resumeRunId && (options.resumeGraphId || matchingRuns.length) && !options.useCurrentGraph
+    ? undefined : readFileSync(path, 'utf8');
+  const currentHeader: unknown = options.resumeRunId && !options.resumeGraphId && !matchingRuns.length ? parseYaml(currentSource!) : undefined;
+  const resumeGraphId = options.resumeGraphId ?? matchingRuns[0]?.graphId ?? (currentHeader && typeof currentHeader === 'object' && !Array.isArray(currentHeader)
+    ? (currentHeader as Record<string, unknown>).graph_id : undefined);
+  const saved = options.resumeRunId && typeof resumeGraphId === 'string'
+    ? readGraphRun(safeSegment(resumeGraphId), safeSegment(options.resumeRunId), root) : undefined;
+  if (saved?.graphSnapshot && (!saved.graphPath || resolve(path) !== resolve(saved.graphPath))) {
+    throw new Error('--file cannot change the graph path of a snapshot run (이 런은 시작 때 그래프 사본이 있다 — --file 대신 --use-current-graph)');
+  }
+  const snapshotDir = saved ? `${saved.statePath}.graph` : undefined;
+  const graphMode: 'snapshot' | 'current' = snapshotDir && saved?.graphSnapshot && !options.useCurrentGraph ? 'snapshot' : 'current';
+  const source = graphMode === 'snapshot' ? readFileSync(join(snapshotDir!, 'graph.yaml'), 'utf8') : currentSource ?? readFileSync(path, 'utf8');
   // The shared YAML parser requires a recipe string. A command-less node in
   // this runner is represented internally as `none`, without changing that parser.
   const raw: unknown = parseYaml(source);
@@ -220,7 +252,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   if (!parsed.template || parsed.errors.length) throw new Error(parsed.errors.map((e) => `${e.path}: ${e.message}`).join('\n'));
   const graph = parsed.template;
   const pluginRoot = elanousStateRoot();
-  const graphFile = realpathSync(path);
+  const graphFile = graphMode === 'snapshot' && !existsSync(path) ? resolve(path) : realpathSync(path);
   const installed = listInstalledPlugins(pluginRoot);
   const owner = installed.find(item => {
     const graphsDir = join(item.path, 'graphs');
@@ -235,7 +267,12 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       throw new Error(`unsupported terminal node: ${terminal} (expected done or failed)`);
     }
   }
-  const recipeSource = readFileSync(join(dirname(path), 'recipes.yaml'), 'utf8');
+  const recipeSource = readFileSync(graphMode === 'snapshot' ? join(snapshotDir!, 'recipes.yaml') : join(dirname(path), 'recipes.yaml'), 'utf8');
+  if (graphMode === 'snapshot' && saved?.graphSnapshot &&
+    (createHash('sha256').update(source).digest('hex') !== saved.graphSnapshot.graphSha ||
+      createHash('sha256').update(recipeSource).digest('hex') !== saved.graphSnapshot.recipesSha)) {
+    throw new Error('graph snapshot changed since run started');
+  }
   const recipes = recipesFor(path, recipeSource);
   const catalogRoles = new Set(loadNodeCatalog().roles.keys());
   // Bind a human decision to the exact graph and recipe contents, not just its id or approval prompt.
@@ -247,10 +284,12 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     if (!resolved.command && !resolved.approval) throw new Error(`unknown command recipe for ${node.nodeId}: ${node.recipe}`);
   }
   const graphId = safeSegment(graph.graphId);
-  if (options.resumeRunId && options.runId) throw new Error('runId and resumeRunId cannot be combined');
-  if (options.fromNodeId && !options.resumeRunId) throw new Error('--from requires --resume');
+  if (saved && graphId !== saved.graphId) {
+    if (options.fromNodeId && graphMode === 'current') throw new Error('graph or recipes changed since failed run');
+    throw new Error(`run identity mismatch: ${saved.graphId}/${saved.runId}`);
+  }
   const runId = safeSegment(options.resumeRunId ?? options.runId ?? randomUUID());
-  const statePath = graphRunPath(graphId, runId, options.deps?.root ?? effectiveInstanceRoot());
+  const statePath = graphRunPath(graphId, runId, root);
   // A resume owns the run from the first state read through its last write and command.
   // Fail closed on a concurrent (or interrupted) owner rather than replaying a command.
   const resumeLock = `${statePath}.resume.lock`;
@@ -263,12 +302,20 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     }
   }
   try {
+  const startMs = (options.deps?.processStartMs ?? psProcessStartMs)(process.pid);
+  const runnerOwner = { pid: process.pid, pidStartedAt: new Date(startMs ?? Date.now() - process.uptime() * 1_000).toISOString() };
   const state: GraphRunState = options.resumeRunId
-    ? readGraphRun(graphId, runId, options.deps?.root ?? effectiveInstanceRoot())
-    : { graphId, runId, startedAt: new Date().toISOString(), status: 'running', path: [], nodes: [], sourceHash: approvalSourceHash, ...(options.input === undefined ? {} : { input: options.input }), executed: 0, dryRun: options.dryRun === true, statePath };
+    ? readGraphRun(graphId, runId, root)
+    : { graphId, runId, startedAt: new Date().toISOString(), ...runnerOwner, status: 'running', path: [], nodes: [], sourceHash: approvalSourceHash,
+      graphSnapshot: { graphSha: createHash('sha256').update(source).digest('hex'), recipesSha: createHash('sha256').update(recipeSource).digest('hex') },
+      graphPath: resolve(path), ...(options.input === undefined ? {} : { input: options.input }), executed: 0, dryRun: options.dryRun === true, statePath };
+  if (options.resumeRunId && graphMode === 'snapshot' && state.sourceHash && state.sourceHash !== approvalSourceHash) {
+    throw new Error('graph snapshot changed since run started');
+  }
+  if (options.resumeRunId && options.dryRun !== undefined && options.dryRun !== state.dryRun) throw new Error('cannot change dryRun when resuming');
   if (options.fromNodeId) {
     if (state.status !== 'failed' || state.pending || state.dryRun) throw new Error('--from requires a failed, non-dry run without pending approval');
-    if (!state.sourceHash || state.sourceHash !== approvalSourceHash) throw new Error('graph or recipes changed since failed run');
+    if (graphMode === 'current' && (!state.sourceHash || state.sourceHash !== approvalSourceHash)) throw new Error('graph or recipes changed since failed run');
     const from = state.path.indexOf(options.fromNodeId);
     if (from < 0 || state.path.lastIndexOf(options.fromNodeId) !== from || graph.terminalNodes.includes(options.fromNodeId)) throw new Error(`--from node is not unique on the saved executable path: ${options.fromNodeId}`);
     if (state.path.length !== state.nodes.length || state.nodes.some((record, i) => record.nodeId !== state.path[i]) ||
@@ -306,10 +353,10 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     state.nodes = state.nodes.slice(0, from);
     state.executed = state.nodes.filter((node) => node.executed).length;
     state.status = 'running';
-    state.resume = { from: options.fromNodeId, at: new Date().toISOString(), previousStatus: 'failed' };
+    Object.assign(state, runnerOwner);
+    state.resume = { from: options.fromNodeId, at: new Date().toISOString(), previousStatus: 'failed', graph: graphMode };
     // Persist the restart boundary before executing it, so previous outputs remain durable.
     persistGraphRun(state);
-    debug.log('graph.run', 'resume', { graphId, runId, from: options.fromNodeId });
   }
   if (options.resumeRunId && state.status === 'running' && state.pending) {
     throw new Error(`run is not awaiting approval: ${graphId}/${runId}`);
@@ -323,10 +370,16 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   if (options.resumeRunId && (state.graphId !== graphId || state.runId !== runId)) {
     throw new Error(`run is not awaiting approval: ${graphId}/${runId}`);
   }
-  if (options.resumeRunId && options.dryRun !== undefined && options.dryRun !== state.dryRun) throw new Error('cannot change dryRun when resuming');
   if (options.resumeRunId && state.status === 'awaiting-approval' && state.approvalSourceHash !== approvalSourceHash) {
     throw new Error(`approval source changed since run was paused: ${graphId}/${runId}`);
   }
+  if (options.resumeRunId && !options.fromNodeId) {
+    const previousStatus = state.status;
+    Object.assign(state, runnerOwner);
+    state.resume = { from: state.pending?.nodeId ?? state.path.at(-1) ?? graph.entryNode, at: new Date().toISOString(), previousStatus, graph: graphMode };
+    persistGraphRun(state);
+  }
+  if (options.resumeRunId) debug.log('graph.runs', 'resume', { graphId, runId, from: state.resume?.from, graph: graphMode });
   const persist = () => {
     if (state.status === 'done' || state.status === 'failed' || state.status === 'budget-exceeded') state.finishedAt ??= new Date().toISOString();
     persistGraphRun(state);
@@ -345,6 +398,9 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       if ((error as NodeJS.ErrnoException).code === 'EEXIST') throw new Error(`run id already exists: ${graphId}/${runId}`);
       throw error;
     }
+    mkdirSync(`${statePath}.graph`);
+    writeFileSync(join(`${statePath}.graph`, 'graph.yaml'), source, { flag: 'wx' });
+    writeFileSync(join(`${statePath}.graph`, 'recipes.yaml'), recipeSource, { flag: 'wx' });
   }
   while (current !== undefined) {
     const node = graph.nodes.find((n) => n.nodeId === current);
@@ -474,6 +530,76 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   }
 }
 
+export type GraphRunAlive = boolean | 'unknown';
+
+export function graphRunAlive(state: GraphRunState, processStartMs: (pid: number) => number | null = psProcessStartMs): GraphRunAlive {
+  if (state.pid === undefined) return 'unknown';
+  if (!Number.isSafeInteger(state.pid) || state.pid <= 0 || typeof state.pidStartedAt !== 'string') return false;
+  const recorded = Date.parse(state.pidStartedAt);
+  if (!Number.isFinite(recorded)) return false;
+  try {
+    const actual = processStartMs(state.pid);
+    return actual !== null && Number.isFinite(actual) && Math.abs(actual - recorded) <= START_TOLERANCE_MS;
+  } catch { return false; }
+}
+
+function isDecisionClaim(raw: unknown): boolean {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return false;
+  const value = raw as Record<string, unknown>;
+  return typeof value.nodeId === 'string' && (value.decision === 'approved' || value.decision === 'rejected')
+    && typeof value.decidedAt === 'string' && (value.decidedBy === undefined || typeof value.decidedBy === 'string')
+    && !('graphId' in value) && !('runId' in value);
+}
+
+export function listGraphRuns(root = effectiveInstanceRoot()): { runs: GraphRunState[]; unreadable: number } {
+  const base = join(root, 'graph-runs');
+  let graphs: string[];
+  try { graphs = readdirSync(base); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { runs: [], unreadable: 0 };
+    throw error;
+  }
+  const runs: GraphRunState[] = [];
+  let unreadable = 0;
+  for (const graphId of graphs) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(graphId) || graphId === '.' || graphId === '..') continue;
+    const dir = join(base, graphId);
+    let files: string[];
+    try {
+      if (!statSync(dir).isDirectory()) continue;
+      files = readdirSync(dir);
+    } catch { unreadable++; continue; }
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+      const runId = file.slice(0, -5);
+      if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId) || runId === '.' || runId === '..') continue;
+      // Decision claims are named <runId>.json.<visit>.decision.json; a run
+      // may itself end in .decision, so check the ledger identity before skipping.
+      const decisionParent = file.match(/^(.*\.json)\.\d+\.decision\.json$/)?.[1];
+      try {
+        const raw: unknown = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+        // Skip only a VALID decision claim (decideGraphApproval writes { nodeId, decision, decidedBy?, decidedAt });
+        // anything else under a claim-like name is judged as a ledger and counts as unreadable when broken.
+        if (decisionParent && isDecisionClaim(raw)) continue;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw) ||
+          (raw as Partial<GraphRunState>).graphId !== graphId || (raw as Partial<GraphRunState>).runId !== runId) {
+          unreadable++;
+          continue;
+        }
+        const state = readGraphRun(graphId, runId, root);
+        if (typeof state.startedAt !== 'string' || !Number.isFinite(Date.parse(state.startedAt)) ||
+          !Array.isArray(state.path) || !state.path.every((node) => typeof node === 'string') ||
+          !Array.isArray(state.nodes) || !state.nodes.every((node) => node && typeof node.nodeId === 'string' && typeof node.ok === 'boolean')) {
+          throw new Error('invalid run state');
+        }
+        runs.push(state);
+      } catch { unreadable++; }
+    }
+  }
+  runs.sort((a, b) => Date.parse(b.startedAt!) - Date.parse(a.startedAt!) || a.graphId.localeCompare(b.graphId) || a.runId.localeCompare(b.runId));
+  return { runs, unreadable };
+}
+
 export function latestGraphRun(graphId: string, root = effectiveInstanceRoot()): GraphRunState | null {
   const dir = join(root, 'graph-runs', safeSegment(graphId));
   let files: string[];

package/src/harness/browser-verify.ts

@@ -22,6 +22,8 @@ import { IMAGE_LOAD_STATE_SOURCE } from './image-load-state.js';
 const execFileAsync = promisify(execFile);
 // Longer than aside's own ~10 s daemon auth-challenge timeout, so «Aside isn't running» reaches stderr before we kill it (10-01 live).
 const DEFAULT_ASIDE_TIMEOUT_MS = 30_000;
+const ASIDE_SHOT_MAX_BYTES = 8 * 1024 * 1024;
+const ASIDE_SHOT_MARKER = 'ELANOUS_SHOT_BASE64:';
 // Observed load events and complete page content arrive within this window; timeout remains non-blocking.
 const CDP_LOAD_WAIT_TIMEOUT_MS = 3_000;
 
@@ -188,6 +190,7 @@ function buildAsideScript(url: string): string {
     `    const state = await page.evaluate(() => { const imageCounts = ${IMAGE_COUNTS_EXPRESSION}; return { bodyLength: document.body?.innerText.length ?? 0, unloadedImageCount: imageCounts.broken, pendingLazyImages: imageCounts.pendingLazy }; });`,
     '    const screenshot = await page.screenshot({ fullPage: true });',
     '    console.log(JSON.stringify({ title, ...state, screenshotBytes: screenshot?.length ?? 0 }));',
+    `    if (screenshot?.length > 0 && screenshot.length <= ${ASIDE_SHOT_MAX_BYTES}) console.log('${ASIDE_SHOT_MARKER}' + Buffer.from(screenshot).toString('base64'));`,
     '  } finally { try { await closeTab(page); } catch {} }',
     '})();',
   ].join('\n');
@@ -223,6 +226,18 @@ function parseAsideObservation(stdout: string): { title: string; bodyLength: num
   throw new Error('aside observation output missing JSON');
 }
 
+function decodeAsideScreenshot(stdout: string, screenshotBytes: number): Buffer | undefined {
+  if (screenshotBytes === 0 || screenshotBytes > ASIDE_SHOT_MAX_BYTES) return undefined;
+  const lines = stripScreenAnsi(stdout).split(/\r?\n/);
+  const shots = lines.filter((line) => line.startsWith(ASIDE_SHOT_MARKER));
+  if (shots.length !== 1) return undefined;
+  const encoded = shots[0]!.slice(ASIDE_SHOT_MARKER.length);
+  if (encoded.length > Math.ceil(ASIDE_SHOT_MAX_BYTES / 3) * 4 || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded)) return undefined;
+  const buf = Buffer.from(encoded, 'base64');
+  if (buf.length !== screenshotBytes || buf.toString('base64') !== encoded) return undefined;
+  return buf;
+}
+
 function asideErrorResult(url: string, error: unknown, kind?: AsideRunStatus['kind']): DeployVerifyResult {
   const message = error instanceof Error ? error.message : String(error);
   const errorFinding = finding('aside-error', `aside 검증 오류: ${message.slice(0, 120)}${kind ? ` (${kind})` : ''}`, 'confirmed');
@@ -240,7 +255,7 @@ async function verifyAsidePage(url: string, deps: DeployVerifyDeps): Promise<Dep
     const script = await readFile(scriptPath, 'utf8');
     const runAside = deps.runAside ?? (async (command, args, options) => {
       try {
-        const result = await execFileAsync(command, args, { ...options, encoding: 'utf8' });
+        const result = await execFileAsync(command, args, { ...options, encoding: 'utf8', maxBuffer: Math.ceil(ASIDE_SHOT_MAX_BYTES / 3) * 4 + 1024 * 1024 });
         return { stdout: result.stdout, stderr: result.stderr, exitCode: 0 };
       } catch (error) {
         if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw error;
@@ -273,12 +288,20 @@ async function verifyAsidePage(url: string, deps: DeployVerifyDeps): Promise<Dep
     if (status.kind === 'repl-error') return asideErrorResult(url, new Error('aside repl reported error'), status.kind);
     if (status.kind === 'no-marker') return asideErrorResult(url, new Error('aside observation output missing completion marker'), status.kind);
     const state = parseAsideObservation(observation.stdout);
+    const screenshot = decodeAsideScreenshot(observation.stdout, state.screenshotBytes);
+    let shotReason = state.screenshotBytes === 0 ? '스크린샷 0바이트' : state.screenshotBytes > ASIDE_SHOT_MAX_BYTES ? '8MB 상한 초과' : screenshot ? undefined : '스크린샷 데이터 없음 또는 불일치';
+    if (screenshot && deps.onScreenshot) {
+      try { deps.onScreenshot(screenshot); }
+      catch (error) { shotReason = (error as NodeJS.ErrnoException)?.code ?? '저장 콜백 오류'; }
+    }
+    observe('aside-shot', { bytes: state.screenshotBytes, written: !!screenshot && !shotReason && !!deps.onScreenshot, reason: shotReason ?? (deps.onScreenshot ? '없음' : '저장 요청 없음') });
     const structuredFindings: DeployVerifyFinding[] = [];
+    if (state.screenshotBytes === 0) structuredFindings.push(finding('aside-error', '스크린샷 0바이트 — 렌더 증거 없음', 'confirmed'));
     if (state.bodyLength < minBody) structuredFindings.push(finding('empty-body', `페이지 본문이 비어있음(len=${state.bodyLength}·렌더 실패 의심)`, 'suspected'));
     if (state.unloadedImageCount) structuredFindings.push(finding('unloaded-image', `로드되지 못한 그림 ${state.unloadedImageCount}개`, 'confirmed'));
     if (!state.title.trim()) structuredFindings.push(finding('empty-title', '문서 제목이 비어있음', 'confirmed'));
     const findings = structuredFindings.map(({ message }) => message);
-    const result: DeployVerifyResult = { ok: findings.length === 0, url, title: state.title, bodyLength: state.bodyLength, screenshotBytes: state.screenshotBytes, findings, unmeasured: ['javascript-errors'], ...(state.pendingLazyImages ? { pendingLazyImages: state.pendingLazyImages } : {}), ...(structuredFindings.length ? { structuredFindings } : {}) };
+    const result: DeployVerifyResult = { ok: findings.length === 0, url, title: state.title, bodyLength: state.bodyLength, screenshotBytes: state.screenshotBytes, findings, unmeasured: shotReason && (state.screenshotBytes === 0 || state.screenshotBytes > ASIDE_SHOT_MAX_BYTES || !!deps.onScreenshot) ? ['javascript-errors', 'screenshot'] : ['javascript-errors'], ...(state.pendingLazyImages ? { pendingLazyImages: state.pendingLazyImages } : {}), ...(structuredFindings.length ? { structuredFindings } : {}) };
     observe('verified-aside', { url: url.slice(0, 80), ok: result.ok, bodyLength: state.bodyLength, bytes: state.screenshotBytes, findings: findings.length, unmeasured: result.unmeasured });
     return result;
   } catch (error) {