elanous 0.2.9 → 0.2.11

package/src/git-fs/worktree.ts

@@ -9,7 +9,7 @@
 // the pattern; we trim the hook-based fallback (sandboxed envs)
 // because elanous's primary surface runs native git.
 
-import { spawnSync, execFileSync } from 'node:child_process';
+import { spawnSync, execFileSync, type SpawnSyncReturns } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync, rmSync, symlinkSync, lstatSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
@@ -17,8 +17,33 @@ import { findGitDir } from './locate.js';
 import { isTransientGitError } from './retry.js';
 import { runGitCommand } from './runner.js';
 import { debug } from '../debug/log.js';
+import { getUserConfig } from '../user-config.js';
 
 const GIT_TIMEOUT_MS = 30_000;
+const WORKTREE_ADD_TIMEOUT_MS = 5 * 60_000;
+
+export interface WorktreeAddDeps {
+  spawn?: (command: string, args: string[], options: { cwd: string; encoding: 'utf8'; timeout: number; maxBuffer: number }) => SpawnSyncReturns<string>;
+}
+
+function worktreeAddTimeoutMs(): number {
+  const seconds = getUserConfig().harness?.worktreeAddTimeoutSec;
+  return typeof seconds === 'number' && Number.isSafeInteger(seconds) && seconds > 0 && seconds <= 2_147_483
+    ? seconds * 1000 : WORKTREE_ADD_TIMEOUT_MS;
+}
+
+function worktreeAddFailureLines(stderr: string): { lastProgress: string | null; details: string[] } {
+  let lastProgress: string | null = null;
+  const details: string[] = [];
+  for (const line of stderr.split(/[\r\n]+/).map((value) => value.trim()).filter(Boolean)) {
+    if (/^(?:Updating files|Checking out files|Receiving objects|Resolving deltas):\s*\d+%/.test(line)) {
+      lastProgress = line;
+    } else if (!/^Preparing worktree\b/.test(line)) {
+      details.push(line);
+    }
+  }
+  return { lastProgress, details: details.slice(-3) };
+}
 
 /** Git metadata left by an interrupted operation in one checkout. */
 /** ⚠️ 공개인 이유(무인 리뷰 질의) — `GitResidueObservation.residues` 의 **원소 타입**이라,
@@ -618,7 +643,7 @@ function worktreeHoldingBranch(repoRoot: string, branch: string): string | null
   return null;
 }
 
-export function createWorktree(opts: CreateWorktreeOpts): CreateWorktreeResult {
+export function createWorktree(opts: CreateWorktreeOpts, deps: WorktreeAddDeps = {}): CreateWorktreeResult {
   const { repoRoot, branch, worktreeRoot } = opts;
   validateBranchName(branch);
   const branchHolder = worktreeHoldingBranch(repoRoot, branch);
@@ -684,25 +709,39 @@ export function createWorktree(opts: CreateWorktreeOpts): CreateWorktreeResult {
   // ★ 병렬 안전 재시도(2026-07-21) — 동시 worktree add 가 git 락에서 경쟁하면 즉시 실패 → 락/일시적
   //   에러면 백오프 재시도(패자가 승자의 락 해제를 기다렸다 성공). non-transient 는 재시도 없이 throw.
   const MAX_ATTEMPTS = 6;
-  let res!: ReturnType<typeof spawnSync>;
+  const addTimeoutMs = worktreeAddTimeoutMs();
+  const addSpawn = deps.spawn ?? spawnSync;
   for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-    res = spawnSync(
+    const res = addSpawn(
       'git',
       ['worktree', 'add', branchFlag, branch, wtPath, baseCheckout],
-      { cwd: repoRoot, encoding: 'utf8', timeout: GIT_TIMEOUT_MS, maxBuffer: 4 * 1024 * 1024 },
+      { cwd: repoRoot, encoding: 'utf8', timeout: addTimeoutMs, maxBuffer: 4 * 1024 * 1024 },
     );
     if (res.status === 0) break;
     const err = (res.stderr || res.stdout || '').toString();
+    const { lastProgress, details } = worktreeAddFailureLines(err);
+    const timedOut = (res.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT';
+    if (timedOut) {
+      debug.log('git-fs.worktree', 'add.failed', { reason: 'timeout', ms: addTimeoutMs, signal: res.signal ?? null, lastProgress }, { level: 'warn' });
+      throw new Error(`git worktree add timed out after ${addTimeoutMs / 1000}s (${res.signal ?? 'none'}) — ${[...details, ...(lastProgress ? [`checkout was at «${lastProgress}»`] : [])].join(' | ') || `git exited ${res.status}`}`);
+    }
+    if (res.signal) {
+      debug.log('git-fs.worktree', 'add.failed', { reason: 'error', ms: addTimeoutMs, signal: res.signal, lastProgress }, { level: 'warn' });
+      throw new Error(`git worktree add failed (${res.signal}) — ${details.join(' | ') || lastProgress || `git exited ${res.status}`}`);
+    }
     const blockingPath = blockingWorktreePath(err);
     if (blockingPath) {
+      debug.log('git-fs.worktree', 'add.failed', { reason: 'error', ms: addTimeoutMs, signal: res.signal ?? null, lastProgress }, { level: 'warn' });
       debug.log('git-fs.worktree', 'add.branch-held', { attempt, branch, blockingPath }, { level: 'warn' });
       throw new Error(`git worktree add failed — branch ${branch} is already used by worktree at ${blockingPath}`);
     }
     if (isUnbornHeadError(err)) {
+      debug.log('git-fs.worktree', 'add.failed', { reason: 'error', ms: addTimeoutMs, signal: res.signal ?? null, lastProgress }, { level: 'warn' });
       throw new Error('git worktree add failed — this repository has no commits yet; create the first commit with: git commit --allow-empty -m "Initial commit"');
     }
     if (!isTransientGitError(err) || attempt === MAX_ATTEMPTS) {
-      throw new Error(`git worktree add failed — ${err.trim() || `git exited ${res.status}`}`);
+      debug.log('git-fs.worktree', 'add.failed', { reason: 'error', ms: addTimeoutMs, signal: res.signal ?? null, lastProgress }, { level: 'warn' });
+      throw new Error(`git worktree add failed — ${details.join(' | ') || lastProgress || `git exited ${res.status}`}`);
     }
     debug.log('git-fs.worktree', 'add.retry', { attempt, branch, err: err.trim().slice(0, 120) });
     sleepSyncMs(80 * attempt);   // 선형 백오프(80·160·240…ms)

package/src/graph-kinds/registry.ts

@@ -22,12 +22,12 @@ export interface NodeKindEntry {
 
 export const HARNESS_CORE_KINDS = ['agent', 'gate', 'git', 'judge', 'observe', 'hitl', 'subgraph'] as const;
 
-// Workflow validation and the palette read the same keys; runtime dispatch remains unchanged.
-export const WORKFLOW_CORE_KINDS = ['prompt', 'bash', 'skill', 'cft', 'approval', 'if', 'switch', 'iteration', 'classify', 'extract', 'set', 'filter', 'template', 'http', 'showroom', 'task', 'scheduleTrigger', 'webhookTrigger', 'discordTrigger', 'telegramTrigger', 'manualTrigger', 'chatTrigger'] as const;
+// Workflow validation, the palette, and executor variant labels read the same keys.
+export const WORKFLOW_CORE_KINDS = ['prompt', 'bash', 'skill', 'cft', 'approval', 'if', 'switch', 'iteration', 'classify', 'extract', 'set', 'filter', 'template', 'http', 'showroom', 'task', 'scheduleTrigger', 'webhookTrigger', 'discordTrigger', 'telegramTrigger', 'manualTrigger', 'chatTrigger', 'subworkflow'] as const;
 
 const descriptions: Record<GraphKind, readonly string[]> = {
   harness: ['Run an agent', 'Check an execution gate', 'Perform git operations', 'Judge an outcome', 'Observe a result', 'Request human input', 'Run a child graph'],
-  workflow: ['Run an LLM prompt', 'Run a shell command', 'Invoke a skill', 'Invoke a CFT method', 'Request approval', 'Branch on a condition', 'Select a case', 'Iterate items', 'Classify input', 'Extract structured data', 'Assign variables', 'Filter items', 'Render a template', 'Make an HTTP request', 'Run a showroom', 'Create a task', 'Start on a schedule', 'Start on a webhook', 'Start on Discord', 'Start on Telegram', 'Start manually', 'Start on chat'],
+  workflow: ['Run an LLM prompt', 'Run a shell command', 'Invoke a skill', 'Invoke a CFT method', 'Request approval', 'Branch on a condition', 'Select a case', 'Iterate items', 'Classify input', 'Extract structured data', 'Assign variables', 'Filter items', 'Render a template', 'Make an HTTP request', 'Run a showroom', 'Create a task', 'Start on a schedule', 'Start on a webhook', 'Start on Discord', 'Start on Telegram', 'Start manually', 'Start on chat', 'Call another workflow'],
 };
 
 const kinds = new Map<GraphKind, Map<string, NodeKindEntry>>();

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,41 @@
 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 type { GraphVariantPlan } from '../self-implement/graph-variant.js';
+import { debug } from '../debug/log.js';
+import { decideGraphApproval, graphRunAlive, lastJsonObject, latestGraphRun, listGraphRuns, manageGraphRun, 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 +48,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;
@@ -32,6 +57,43 @@ export function registerGraphCommands(program: Command): void {
         process.exitCode = 1;
       }
     });
+  graph.command('variant <template>')
+    .description('Validate and run a graph variant, preserving the resulting graph beside its run ledger')
+    .requiredOption('--plan <json>', 'JSON variant plan (maxVisits, routes, or growth)')
+    .option('--dry-run', 'Walk the variant without executing commands')
+    .option('--run', 'Execute the validated variant')
+    .option('--json', 'Print run state as JSON')
+    .action(async (file: string, opts: { plan: string; dryRun?: boolean; run?: boolean; json?: boolean }) => {
+      try {
+        if (opts.dryRun === opts.run) throw new Error('choose exactly one of --dry-run or --run');
+        let plan: unknown;
+        try { plan = JSON.parse(opts.plan); } catch { throw new Error('--plan must be a JSON object'); }
+        if (!plan || typeof plan !== 'object' || Array.isArray(plan) ||
+          Object.keys(plan).some(key => !['maxVisits', 'routes', 'growth'].includes(key)) ||
+          (plan as Record<string, unknown>).maxVisits !== undefined &&
+            (typeof (plan as Record<string, unknown>).maxVisits !== 'object' || (plan as Record<string, unknown>).maxVisits === null || Array.isArray((plan as Record<string, unknown>).maxVisits)) ||
+          (plan as Record<string, unknown>).routes !== undefined && (!Array.isArray((plan as Record<string, unknown>).routes) ||
+            !(plan as { routes: unknown[] }).routes.every(route => route !== null && typeof route === 'object' && !Array.isArray(route) &&
+              typeof (route as Record<string, unknown>).from === 'string' && typeof (route as Record<string, unknown>).to === 'string' &&
+              typeof (route as Record<string, unknown>).outcome === 'string')) ||
+          (plan as Record<string, unknown>).growth !== undefined &&
+            (!(plan as Record<string, unknown>).growth || typeof (plan as Record<string, unknown>).growth !== 'object' ||
+              Array.isArray((plan as Record<string, unknown>).growth) ||
+              !(plan as { growth: Record<string, unknown> }).growth.node ||
+              typeof (plan as { growth: Record<string, unknown> }).growth.from !== 'string' ||
+              typeof (plan as { growth: Record<string, unknown> }).growth.outcome !== 'string')) {
+          throw new Error('--plan must be a JSON variant plan');
+        }
+        await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
+        const state = await runGraph(file, { dryRun: opts.dryRun, variant: { goal: 'g_graph_variant', plan: plan as GraphVariantPlan }, 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;
+      } catch (error) {
+        console.error(`graph variant: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
   graph.command('tick <file>')
     .description('Advance one graph run, resuming a pending decision or starting only when requested')
     .option('--start', 'Start a new run when the graph is idle')
@@ -87,6 +149,129 @@ 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;
+      }
+    });
+  for (const action of ['stop', 'destroy'] as const) {
+    runs.command(`${action} <run_id>`)
+      .description(action === 'stop' ? 'Fail a running or orphaned run so it can be resumed' : 'Stop and delete a run and its owned artifacts')
+      .action(async (runId: string) => {
+        try {
+          // Without the sink the stop/destroy observation lines never reach the log store (only `graph run` had it).
+          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) throw new Error(matches.length ? `ambiguous run id: ${runId}\n${matches.map(state => `${state.graphId}/${state.runId}`).join('\n')}` : `no run: ${runId}`);
+          const saved = matches[0]!;
+          const state = manageGraphRun(saved.graphId, saved.runId, action, runsDeps.root, runsDeps.processStartMs);
+          console.log(`${state.graphId} ${state.runId}: ${action === 'stop' ? state.status : 'destroyed'}`);
+          warning(unreadable);
+        } catch (error) {
+          console.error(`graph runs ${action}: ${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-grow-llm.ts

@@ -0,0 +1,37 @@
+import { streamLLM } from '../llm.js';
+import type { GrowthProposal, GrowthProposer } from './graph-grow.js';
+
+type GrowthLLM = (prompt: string) => Promise<string>;
+const OUTPUT_TAIL_LENGTH = 4000;
+
+/** Model output is untrusted: structural and side-effect validation belongs to proposeGrowth. */
+export function createLLMGrowthProposer(callLLM: GrowthLLM = (prompt) =>
+  streamLLM([{ role: 'user', content: prompt }], () => {}, { reasoningEffort: 'low' })): GrowthProposer {
+  return async (input: Parameters<GrowthProposer>[0]) => {
+    const serializedOutput = typeof input.output === 'string' ? input.output : input.output === undefined ? '' : JSON.stringify(input.output);
+    const graphSummary = {
+      graphId: input.graph.graphId,
+      nodes: input.graph.nodes.map(({ nodeId, kind, recipe }) => ({ nodeId, kind, recipe })),
+      edges: input.graph.edges.map(({ from, to, on, map, fallback }) => ({ from, ...(to === undefined ? {} : { to }),
+        ...(on === undefined ? {} : { on }), ...(map === undefined ? {} : { map }), ...(fallback === undefined ? {} : { fallback }) })),
+    };
+    const prompt = [
+      'Propose exactly one new contracted graph node to handle the unseen outcome, then return to an existing node.',
+      'Reply with only JSON: {"node":{"nodeId":"...","kind":"...","recipe":"none","maxVisits":1,"contract":{"inputs":[],"tools":"read-only","outputs":[]}},"returnTo":"existing-node-id","reason":"..."}.',
+      'Do not alter existing nodes or edges. The proposal will be validated independently; do not assume a recipe is safe.',
+      `Graph summary: ${JSON.stringify(graphSummary)}`,
+      `Blocked node ID: ${JSON.stringify(input.nodeId)}`,
+      `Unseen outcome: ${JSON.stringify(input.outcome)}`,
+      `Blocked node output tail: ${JSON.stringify(serializedOutput.slice(-OUTPUT_TAIL_LENGTH))}`,
+    ].join('\n');
+    const response = await callLLM(prompt);
+    let parsed: unknown;
+    try { parsed = JSON.parse(response.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '')); }
+    catch { return undefined; }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
+    const proposal = parsed as Record<string, unknown>;
+    if (!proposal.node || typeof proposal.node !== 'object' || Array.isArray(proposal.node) ||
+      typeof proposal.reason !== 'string' || !proposal.reason.trim() || typeof proposal.returnTo !== 'string') return undefined;
+    return { node: proposal.node, reason: proposal.reason, returnTo: proposal.returnTo } as GrowthProposal;
+  };
+}

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

@@ -0,0 +1,47 @@
+import { createGraphVariant } from '../self-implement/graph-variant.js';
+import type { GraphEdgeSpec, GraphNodeSpec, GraphTemplateSpec } from '../self-implement/graph-yaml.js';
+import { createLLMGrowthProposer } from './graph-grow-llm.js';
+
+export interface GrowthProposal {
+  node: GraphNodeSpec;
+  returnTo?: string;
+  reason: string;
+}
+
+export type GrowthProposer = (input: { graph: GraphTemplateSpec; nodeId: string; outcome: string; runId: string; output?: unknown }) => GrowthProposal | undefined | Promise<GrowthProposal | undefined>;
+export type GrowthRecipeEffect = 'read-only' | 'external-effect' | 'unknown';
+
+export interface GraphGrowth {
+  node: GraphNodeSpec;
+  edges: readonly GraphEdgeSpec[];
+  reason: string;
+  undo: { removeNode: string; removeOutcome: { from: string; outcome: string }; removeEdge?: GraphEdgeSpec };
+}
+
+export async function proposeGrowth(input: Parameters<GrowthProposer>[0],
+  proposer: GrowthProposer = createLLMGrowthProposer(), classifyRecipe?: (node: GraphNodeSpec) => GrowthRecipeEffect): Promise<{ ok: true; graph: GraphTemplateSpec; growth: GraphGrowth } | { ok: false; reason: string; park?: boolean }> {
+  let proposal: GrowthProposal | undefined;
+  try { proposal = await proposer(input); }
+  catch (error) { return { ok: false, reason: `proposer failed: ${String(error)}` }; }
+  if (!proposal) return { ok: false, reason: 'no proposal' };
+  if (!proposal.node || typeof proposal.reason !== 'string' || !proposal.reason.trim()) return { ok: false, reason: 'proposal requires a node and reason' };
+  const result = createGraphVariant({ template: input.graph, goal: `g_${input.runId.replace(/[^a-z0-9_-]/gi, '_')}`,
+    plan: { growth: { node: proposal.node, from: input.nodeId, outcome: input.outcome, returnTo: proposal.returnTo } } });
+  if (!result.ok) return { ok: false, reason: `growth rejected: ${JSON.stringify(result.rejections)}` };
+  // Neither a recipe id nor its declared tools certify arbitrary executable code.
+  // Only a trusted classification of the resolved recipe may authorize execution.
+  let effect: GrowthRecipeEffect = 'unknown';
+  if (proposal.node.recipe !== 'none') {
+    try { effect = classifyRecipe?.(proposal.node) ?? 'unknown'; }
+    catch { effect = 'unknown'; }
+    if (effect !== 'read-only') {
+      return { ok: false, park: true, reason: '사람 확인 필요: external or unclassified side-effect recipe' };
+    }
+  }
+  const edges: GraphEdgeSpec[] = [
+    { from: input.nodeId, on: 'outcome', map: { [input.outcome]: proposal.node.nodeId } },
+    { from: proposal.node.nodeId, to: proposal.returnTo as string },
+  ];
+  return { ok: true, graph: result.template, growth: { node: proposal.node, edges, reason: proposal.reason,
+    undo: { removeNode: proposal.node.nodeId, removeOutcome: { from: input.nodeId, outcome: input.outcome }, removeEdge: edges[1]! } } };
+}

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 }); }
 }