elanous 0.2.8 → 0.2.10

package/src/graph-runner/graph-approval-card.ts

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { DecisionLedger, type DecisionEntry } from '../decisions/decision-ledger.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { decideGraphApproval, type GraphRunState } from './runner.js';
+
+export interface GraphApprovalCardDeps {
+  root?: string;
+  ledger?: Pick<DecisionLedger, 'list' | 'raise'>;
+}
+
+type Pending = NonNullable<GraphRunState['pending']>;
+const REF = /^graph-approval:([A-Za-z0-9][A-Za-z0-9._-]*):([A-Za-z0-9][A-Za-z0-9._-]*):([A-Za-z0-9][A-Za-z0-9._-]*):([1-9]\d*)$/;
+
+function ledgerFor(deps: GraphApprovalCardDeps, root: string): Pick<DecisionLedger, 'list' | 'raise'> {
+  return deps.ledger ?? new DecisionLedger({ stateDir: root });
+}
+
+function observation(event: 'raised' | 'dedup' | 'applied' | 'skipped', state: Pick<GraphRunState, 'graphId' | 'runId'> & { nodeId: string }, decisionId?: string, outcome?: string, reason?: string): void {
+  debug.log('graph.approval-card', event, { graphId: state.graphId, runId: state.runId, nodeId: state.nodeId, decisionId, outcome, ...(reason ? { reason } : {}) });
+}
+
+export function raiseApprovalCard(state: GraphRunState, pending: Pending, deps: GraphApprovalCardDeps = {}): DecisionEntry | undefined {
+  const root = deps.root ?? effectiveInstanceRoot();
+  const nodeId = pending.nodeId;
+  const identity = { graphId: state.graphId, runId: state.runId, nodeId };
+  const visit = state.path.filter(node => node === nodeId).length;
+  if (state.dryRun || state.status !== 'awaiting-approval' || state.pending?.nodeId !== nodeId ||
+      state.pending.decision || state.path.at(-1) !== nodeId || visit < 1 ||
+      existsSync(`${join(root, 'graph-runs', state.graphId, `${state.runId}.json`)}.${state.path.length}.decision.json`)) {
+    observation('skipped', identity);
+    return undefined;
+  }
+  const ref = `graph-approval:${state.graphId}:${state.runId}:${nodeId}:${visit}`;
+  const ledger = ledgerFor(deps, root);
+  const existing = ledger.list({ status: 'all' }).find(entry => entry.refs?.includes(ref));
+  if (existing) {
+    observation('dedup', identity, existing.id, existing.choice);
+    return existing;
+  }
+  const publish = state.graphId === 'release-loop' && nodeId === 'approve-publish';
+  const firstLine = pending.message.split(/\r?\n/, 1)[0]?.trim();
+  const version = state.input && typeof state.input === 'object' && 'version' in state.input && typeof state.input.version === 'string'
+    ? state.input.version : state.runId;
+  const title = publish && firstLine ? firstLine : `${state.graphId} ${version} — ${nodeId} 승인`;
+  const entry = ledger.raise({ title, category: publish ? 'publish' : 'scope',
+    scqa: { s: `${state.graphId} / ${state.runId} 런이 ${nodeId} 승인에서 대기 중이다.`, c: pending.message.slice(0, 220) || '승인 대기 중이다.' },
+    options: [{ key: 'a', label: '승인', consequence: `${nodeId} 승인 후 런을 계속할 수 있다` },
+      { key: 'b', label: '거절', consequence: `${nodeId} 거절로 기록한다` }],
+    recommendation: { skipped: true, reason: '사람 판단' }, raisedBy: { agent: 'graph-runner' }, refs: [ref] });
+  observation('raised', identity, entry.id);
+  return entry;
+}
+
+/** A card answer only claims the same pending visit; runner owns the atomic decision file. */
+export function applyDecidedApprovals(deps: GraphApprovalCardDeps = {}): number {
+  const root = deps.root ?? effectiveInstanceRoot();
+  let applied = 0;
+  for (const entry of ledgerFor(deps, root).list({ status: 'decided' })) {
+    for (const ref of entry.refs ?? []) {
+      const match = REF.exec(ref);
+      if (!match) continue;
+      const [, graphId, runId, nodeId, rawVisit] = match;
+      const identity = { graphId: graphId!, runId: runId!, nodeId: nodeId! };
+      // One unreadable run must not block every later card (L11 review round 1 should-fix).
+      try { if (applyOne(entry, identity, Number(rawVisit), root)) applied++; }
+      catch (error) {
+        observation('skipped', identity, entry.id, entry.choice, error instanceof Error ? error.message : String(error));
+      }
+    }
+  }
+  return applied;
+}
+
+function applyOne(entry: DecisionEntry, identity: { graphId: string; runId: string; nodeId: string }, visit: number, root: string): boolean {
+  const { graphId, runId, nodeId } = identity;
+  // Graph approvals gate irreversible steps (publish) — only a person's answer approves or rejects, never a delegated auto decision.
+  if ((entry.choice !== 'a' && entry.choice !== 'b') || entry.decidedBy?.kind !== 'human' || !Number.isSafeInteger(visit)) {
+    observation('skipped', identity, entry.id, entry.choice);
+    return false;
+  }
+  const statePath = join(root, 'graph-runs', graphId, `${runId}.json`);
+  let state: GraphRunState;
+  try { state = JSON.parse(readFileSync(statePath, 'utf8')) as GraphRunState; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    observation('skipped', identity, entry.id, entry.choice);
+    return false;
+  }
+  if (state.graphId !== graphId || state.runId !== runId || state.dryRun || state.status !== 'awaiting-approval' ||
+      !state.pending || state.pending.nodeId !== nodeId || state.pending.decision || state.path.at(-1) !== nodeId ||
+      state.path.filter(node => node === nodeId).length !== visit ||
+      existsSync(`${statePath}.${state.path.length}.decision.json`)) {
+    observation('skipped', identity, entry.id, entry.choice);
+    return false;
+  }
+  const outcome = entry.choice === 'a' ? 'approved' : 'rejected';
+  try { decideGraphApproval(graphId, runId, outcome, `owner:${entry.decidedBy.kind}`, root,
+    { nodeId, visit: visit }); }
+  catch (error) {
+    // A CLI approver (or another notifier) may win the atomic hard-link claim.
+    // A resumed run may also have left this visit before the writer reads it.
+    const current = JSON.parse(readFileSync(statePath, 'utf8')) as GraphRunState;
+    if (!existsSync(`${statePath}.${state.path.length}.decision.json`) &&
+        current.status === 'awaiting-approval' && current.pending?.nodeId === nodeId && !current.pending.decision &&
+        current.path.at(-1) === nodeId && current.path.filter(node => node === nodeId).length === visit) throw error;
+    observation('skipped', identity, entry.id, outcome);
+    return false;
+  }
+  observation('applied', identity, entry.id, outcome);
+  return true;
+}

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[];