elanous 0.2.9 → 0.2.10

package/src/exec-requests/runner.ts

@@ -1,16 +1,20 @@
-import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { debug } from '../debug/log.js';
+import { notifyExecRequestTransition } from '../web-push/notify-exec-request.js';
 import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { lastJsonObject, runGraph, type GraphRunState } from '../graph-runner/runner.js';
 import { installedGraphs, planExecRequest, type ExecPlanItem, type InstalledGraph } from './planner.js';
-import { ExecRequestStore, type ExecRequest, type ExecResult, type ExecSeat } from './store.js';
+import { ExecRequestStore, type ExecAttachment, type ExecRequest, type ExecResult, type ExecSeat } from './store.js';
+import { answerAsSeat } from '../intake-plane/seat-answer.js';
+import { redactSecrets } from '../task-cards/card-store.js';
 
 export interface ExecRunnerDeps {
   store?: ExecRequestStore;
   graphs?: () => Promise<InstalledGraph[]>;
-  plan?: (text: string) => Promise<ExecPlanItem[]>;
+  plan?: (text: string, attachments?: readonly ExecAttachment[]) => Promise<ExecPlanItem[]>;
+  answer?: typeof answerAsSeat;
   run?: typeof runGraph;
   root?: string;
 }
@@ -38,7 +42,11 @@ function safeFile(path: string, root: string, graphId: string, runId: string): s
       ? realpathSync(artifactsDir) : null;
     const inRunDirectory = realArtifactsDir === join(base, `${runId}.json.artifacts`)
       && real.startsWith(`${realArtifactsDir}${sep}`);
-    if ((!local && !inRunDirectory) || !statSync(real).isFile()) return null;
+    // EXEC2 — plugin graphs (doc-draft · geo-check) write into `<graphId>/<runId>/`; that directory is this run's own too.
+    const runDir = join(allowed, runId);
+    const realRunDir = existsSync(runDir) && statSync(runDir).isDirectory() ? realpathSync(runDir) : null;
+    const inOwnRunDir = realRunDir === join(base, runId) && real.startsWith(`${realRunDir}${sep}`);
+    if ((!local && !inRunDirectory && !inOwnRunDir) || !statSync(real).isFile()) return null;
     return real;
   } catch { return null; }
 }
@@ -56,8 +64,32 @@ function fileName(path: string, runId: string): string {
   return `${runId}--${digest}--${basename(path)}`;
 }
 
+/** EXEC2 — `report` is how geo-check names its file; treat it like `file`/`path`. */
+function fileCandidate(output: Record<string, unknown>): string | null {
+  if (typeof output.file === 'string') return output.file;
+  if (typeof output.path === 'string') return output.path;
+  if (typeof output.report === 'string' && /\.(md|txt|pdf)$/i.test(output.report)) return output.report;
+  return null;
+}
+
+const TEXT_RESULT_LIMIT = 200_000;
+const TEXT_RESULT_NAME = 'result.md';
+
+/** EXEC2 — a done seat whose graph only answered in text gets that text as a run artifact (redacted), so the result is viewable. */
+function textResultFile(seat: ExecSeat, state: GraphRunState, root: string): string | null {
+  const outputs = [...(state.nodes ?? [])].reverse().map(node => lastJsonObject(node.output)).filter((o): o is Record<string, unknown> => !!o);
+  const text = outputs.map(o => o.markdown ?? o.text).find((v): v is string => typeof v === 'string' && v.trim().length > 0);
+  if (!text || !SEGMENT.test(seat.graphId) || !SEGMENT.test(seat.runId)) return null;
+  const dir = join(root, 'graph-runs', seat.graphId, `${seat.runId}.json.artifacts`);
+  const path = join(dir, TEXT_RESULT_NAME);
+  try {
+    if (!existsSync(path)) { mkdirSync(dir, { recursive: true }); writeFileSync(path, redactSecrets(text.slice(0, TEXT_RESULT_LIMIT)), { mode: 0o600 }); }
+    return path;
+  } catch { return null; }
+}
+
 function resultOf(output: Record<string, unknown>, seat: ExecSeat, id: string, root: string): ExecResult | null {
-  const candidate = typeof output.file === 'string' ? output.file : typeof output.path === 'string' ? output.path : null;
+  const candidate = fileCandidate(output);
   let url: string;
   let kind: ExecResult['kind'];
   let name: string;
@@ -95,6 +127,7 @@ function syncRun(item: ExecRequest, seat: ExecSeat, state: GraphRunState, root:
   if (state.status === 'awaiting-approval' && state.pending && !state.pending.decision && !existsSync(claim)) {
     if (!item.approvals.some(a => a.graphId === seat.graphId && a.runId === seat.runId)) {
       item.approvals.push({ graphId: seat.graphId, runId: seat.runId, message: state.pending.message });
+      notifyTransition(item, item.status, item.approvals.length);
     }
   } else item.approvals = item.approvals.filter(a => a.graphId !== seat.graphId || a.runId !== seat.runId);
   for (const node of state.nodes ?? []) {
@@ -107,9 +140,28 @@ function syncRun(item: ExecRequest, seat: ExecSeat, state: GraphRunState, root:
       if (result && !item.results.some(existing => existing.seat === result.seat && existing.url === result.url)) item.results.push(result);
     }
   }
+  if (seat.status === 'done' && !item.results.some(existing => existing.seat === seat.seat)) {
+    const file = textResultFile(seat, state, root);
+    const result = file ? resultOf({ file, title: seat.title }, seat, item.id, root) : null;
+    if (result) item.results.push(result);
+    else {
+      const keys = [...new Set((state.nodes ?? []).flatMap(node => Object.keys(lastJsonObject(node.output) ?? {})))];
+      debug.log('exec.result', 'none', { seat: seat.seat, graphId: seat.graphId, keys });
+    }
+  }
   const summary = [...(state.nodes ?? [])].reverse().map(node => lastJsonObject(node.output)?.summary).find(value => typeof value === 'string');
   if (typeof summary === 'string') item.summary = summary;
-  if (seat.status === 'failed') seat.reason = state.nodes?.at(-1)?.error ?? `그래프 런 ${state.status}`;
+  if (seat.status === 'failed') seat.reason = failureReason(state);
+}
+
+/** EXEC2 — the failing node's own error (e.g. doc-draft `check` {outcome:'fail', error}) beats the terminal gate's empty one. */
+function failureReason(state: GraphRunState): string {
+  for (const node of [...(state.nodes ?? [])].reverse()) {
+    if (typeof node.error === 'string' && node.error) return node.error;
+    const output = lastJsonObject(node.output);
+    if (output && typeof output.error === 'string' && output.error) return redactSecrets(output.error);
+  }
+  return `그래프 런 ${state.status}`;
 }
 
 const PRIOR_TEXT_LIMIT = 4_000;
@@ -129,8 +181,14 @@ export function withPriorResults(inputs: Record<string, unknown> | undefined, pr
   return { ...base, context: `${previous}앞 자리 결과:\n${parts.join('\n\n')}` };
 }
 
+function notifyTransition(item: ExecRequest, from: ExecRequest['status'], pendingApprovals: number): void {
+  void notifyExecRequestTransition({ id: item.id, text: item.text, from, to: item.status,
+    summary: item.summary, pendingApprovals }).catch(() => { /* Push never interrupts execution. */ });
+}
+
 function aggregate(item: ExecRequest): void {
   if (item.status === 'planning' || item.seats.length === 0) return;
+  const previous = item.status;
   if (item.seats.some(seat => seat.status === 'waiting' || seat.status === 'running')) item.status = 'running';
   else item.status = item.seats.some(seat => seat.status === 'failed') ? 'failed' : 'done';
   // 실패면 요약은 «실패 사유»가 이긴다 — 먼저 끝난 자리의 산출 설명이 남아 있어도 덮는다(혼합 결과에서 성공처럼 보이지 않게).
@@ -138,6 +196,7 @@ function aggregate(item: ExecRequest): void {
     const reasons = item.seats.filter(seat => seat.status === 'failed').map(seat => seat.reason ?? `${seat.seat}: 그래프 실행 실패`);
     if (reasons.length > 0) item.summary = reasons.join('; ');
   }
+  if (previous !== item.status && (item.status === 'done' || item.status === 'failed')) notifyTransition(item, previous, item.approvals.length);
 }
 
 export class ExecRequestRunner {
@@ -156,10 +215,12 @@ export class ExecRequestRunner {
       if (item.status === 'planning') {
         item.status = 'failed';
         item.summary = '데몬 재시작으로 COO 계획이 중단됐습니다';
+        notifyTransition(item, 'planning', item.approvals.length);
       } else {
         if (item.seats.length === 0) {
           item.status = 'failed';
           item.summary = '데몬 재시작으로 자리 배정이 중단됐습니다';
+          notifyTransition(item, 'running', item.approvals.length);
         }
         for (const seat of item.seats) {
           if (seat.status === 'done' || seat.status === 'failed') continue;
@@ -192,14 +253,16 @@ export class ExecRequestRunner {
     }
   }
 
-  submit(text: string): ExecRequest {
-    const item = this.store.create(text);
+  submit(text: string, attachments?: ExecAttachment[]): ExecRequest {
+    const item = this.store.create(text, attachments);
     void this.execute(item.id).catch(error => {
       const current = this.store.get(item.id);
       if (!current) return;
+      const previous = current.status;
       current.status = 'failed';
       current.summary = error instanceof Error ? error.message : String(error);
       this.store.save(current);
+      if (previous !== current.status) notifyTransition(current, previous, current.approvals.length);
       debug.log('exec-requests', 'failed', { id: item.id, reason: current.summary });
     });
     return item;
@@ -209,8 +272,40 @@ export class ExecRequestRunner {
     const item = this.store.get(id);
     if (!item) return;
     const graphs = await (this.deps.graphs ?? installedGraphs)();
-    const plans = await (this.deps.plan ?? ((text: string) => planExecRequest(text, { graphs: async () => graphs })))(item.text);
+    const plans = await (this.deps.plan ?? ((text: string, attachments?: readonly ExecAttachment[]) => planExecRequest(text, { graphs: async () => graphs, attachments })))(item.text, item.attachments);
     const byId = new Map(graphs.map(graph => [graph.id, graph]));
+    // Every clause must be a question — «상황 알려줘? 카드 만들어줘» carries a work item (review r1).
+    const clauses = [...item.text.trim().matchAll(/([^?？.!。\n]+)([?？]?)/g)].map(m => ({ body: m[1]!.trim(), asked: m[2] !== '' })).filter(c => c.body);
+    const isQuestion = clauses.length > 0 && clauses.every(c => c.asked
+      || /(?:알려\s*줘|알려\s*주세요|보여\s*줘|보여\s*주세요|어떻게|무엇|뭐|어떤|언제|누구|질문|인가요|나요|습니까)$/.test(c.body));
+    if (isQuestion && plans.length > 0 && plans.every(plan => !plan.graphId
+      && !/\s—\s.+\s필요\s*$/.test(plan.title) && !/\s—\s.+\s필요\s*$/.test(plan.reason ?? '')
+      && !/(?:초안|작성|제작|생성|게시|분석|전략|메일|보고서)/.test(plan.title)) && !(item.attachments?.length)) {
+      for (const plan of plans) {
+        const answered = await (this.deps.answer ?? answerAsSeat)(plan.seat, item.text);
+        if (!answered) {
+          item.seats.push({ seat: plan.seat, title: plan.title, status: 'failed', graphId: '', runId: '',
+            reason: plan.reason ?? `${plan.seat}: 요청에 맞는 설치된 실행 그래프가 없습니다` });
+          continue;
+        }
+        const seat: ExecSeat = { seat: plan.seat, title: plan.title, status: 'done', graphId: 'seat-answer', runId: randomUUID() };
+        const dir = join(this.root, 'graph-runs', seat.graphId);
+        const statePath = join(dir, `${seat.runId}.json`);
+        const artifactDir = join(dir, `${seat.runId}.json.artifacts`);
+        mkdirSync(artifactDir, { recursive: true });
+        const file = join(artifactDir, TEXT_RESULT_NAME);
+        writeFileSync(file, redactSecrets(answered.text.slice(0, TEXT_RESULT_LIMIT)), { mode: 0o600 });
+        const state: GraphRunState = { graphId: seat.graphId, runId: seat.runId, status: 'done', path: [], executed: 0, dryRun: false, statePath, nodes: [] };
+        writeFileSync(statePath, JSON.stringify(state), { mode: 0o600 });
+        item.seats.push(seat);
+        const result = resultOf({ file, title: answered.title }, seat, id, this.root);
+        if (result) item.results.push(result);
+      }
+      item.status = 'running';
+      aggregate(item);
+      this.store.save(item);
+      return;
+    }
     item.seats = plans.map(plan => ({ seat: plan.seat, title: plan.title, status: plan.reason || !byId.has(plan.graphId) ? 'failed' : 'waiting', graphId: plan.graphId,
       runId: plan.reason || !byId.has(plan.graphId) ? '' : randomUUID(), inputs: plan.inputs, ...(plan.after?.length ? { after: plan.after } : {}),
       ...(plan.reason || !byId.has(plan.graphId) ? { reason: plan.reason ?? `${plan.seat}: 요청에 맞는 설치된 실행 그래프가 없습니다` } : {}) }));
@@ -366,12 +461,14 @@ export class ExecRequestRunner {
         for (const entry of Array.isArray(output.artifacts) ? output.artifacts : [output]) {
           if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
           const artifact = entry as Record<string, unknown>;
-          const candidate = typeof artifact.file === 'string' ? artifact.file : artifact.path;
+          const candidate = fileCandidate(artifact);
           if (typeof candidate !== 'string') continue;
           const path = safeFile(candidate, this.root, seat.graphId, seat.runId);
           if (path && fileName(path, seat.runId) === name) return path;
         }
       }
+      const text = safeFile(join(this.root, 'graph-runs', seat.graphId, `${seat.runId}.json.artifacts`, TEXT_RESULT_NAME), this.root, seat.graphId, seat.runId);
+      if (text && fileName(text, seat.runId) === name) return text;
     } catch { return null; }
     return null;
   }

package/src/exec-requests/store.ts

@@ -22,9 +22,15 @@ export interface ExecResult {
   url: string;
   sources?: Array<{ title: string; url: string }>;
 }
+export interface ExecAttachment {
+  name: string;
+  path: string;
+}
+
 export interface ExecRequest {
   id: string;
   text: string;
+  attachments?: ExecAttachment[];
   createdAt: string;
   status: 'planning' | 'running' | 'done' | 'failed';
   summary: string;
@@ -39,8 +45,8 @@ export class ExecRequestStore {
   readonly dir: string;
   constructor(configDir = getElanousConfigDir()) { this.dir = join(configDir, 'exec-requests'); }
 
-  create(text: string): ExecRequest {
-    const item: ExecRequest = { id: randomUUID(), text, createdAt: new Date().toISOString(), status: 'planning', summary: '', seats: [], results: [], approvals: [] };
+  create(text: string, attachments?: ExecAttachment[]): ExecRequest {
+    const item: ExecRequest = { id: randomUUID(), text, ...(attachments !== undefined ? { attachments } : {}), createdAt: new Date().toISOString(), status: 'planning', summary: '', seats: [], results: [], approvals: [] };
     this.save(item);
     return item;
   }

package/src/field/field-media.ts

@@ -219,19 +219,22 @@ function uniqueName(dir: string, name: string, size: number, taken: Set<string>)
 
 export const FIELD_CAPTION_TAG = '#현장';
 
-/** 캡션에 독립 토큰 `#현장` 이 있으면 `{ event? }`, 없으면 null.
- *  `#현장 <slug>` — 바로 다음 토큰을 소문자로 바꿔 슬러그 규칙에 맞으면 행사 이름, 아니면 기본 행사. */
-export function parseFieldCaption(caption: string | undefined | null): { event?: string; text?: string } | null {
+/** 캡션에 독립 토큰 `#현장` 이 있으면 `{ event?, mode?, text? }`, 없으면 null.
+ *  `#현장 <slug>` — 모드 토큰을 건너뛴 바로 다음 토큰을 소문자로 바꿔 슬러그 규칙에 맞으면 행사 이름, 아니면 기본 행사. */
+export function parseFieldCaption(caption: string | undefined | null): { event?: string; mode?: 'instant'; text?: string } | null {
   if (!caption) return null;
   const tokens = caption.trim().split(/\s+/);
   const at = tokens.indexOf(FIELD_CAPTION_TAG);
   if (at < 0) return null;
-  const next = tokens[at + 1]?.toLowerCase();
+  const isInstant = (token: string) => token === '즉석' || token.toLowerCase() === 'instant';
+  const mode = tokens.some(isInstant) ? 'instant' : undefined;
+  const eventAt = at + 1 + (tokens[at + 1] && isInstant(tokens[at + 1]) ? 1 : 0);
+  const next = tokens[eventAt]?.toLowerCase();
   const hasEvent = !!next && isFieldSlug(next);
-  // 태그·행사 이름을 뺀 나머지가 «글»(자막) — 태그 앞에 쓴 글도 같이.
-  const rest = tokens.filter((_, i) => i !== at && !(hasEvent && i === at + 1)).join(' ');
+  // 태그·행사 이름·모드를 뺀 나머지가 «글»(자막) — 태그 앞에 쓴 글도 같이.
+  const rest = tokens.filter((token, i) => i !== at && !(hasEvent && i === eventAt) && !isInstant(token)).join(' ');
   const text = normalizeFieldCaption(rest);
-  return { ...(hasEvent ? { event: next } : {}), ...(text ? { text } : {}) };
+  return { ...(hasEvent ? { event: next } : {}), ...(mode ? { mode } : {}), ...(text ? { text } : {}) };
 }
 
 export const FIELD_CAPTIONS_FILE = 'captions.txt';

package/src/field/field-reel.ts

@@ -4,11 +4,12 @@ import { join, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { spawn, execFileSync } from 'node:child_process';
 import { debug } from '../debug/log.js';
+import { mergeCapturedPath } from '../shell-env-bootstrap.js';
 import { listFieldMedia } from './field-media.js';
 import { startFieldFeed, type FieldFeedStart } from './field-feed-auto.js';
 
 export interface FieldReelResult { ok: boolean; file?: string; seconds: number; error?: string; feed?: FieldFeedStart }
-export type FieldReelRunner = (dir: string, opts: { title: string; sub: string }) => Promise<FieldReelResult>;
+export type FieldReelRunner = (dir: string, opts: { title: string; sub: string; mode?: 'standard' | 'instant' }) => Promise<FieldReelResult>;
 export interface FieldReelStatus {
   state: 'waiting' | 'rendering' | 'done' | 'failed';
   items: number;
@@ -23,6 +24,7 @@ export interface FieldReelOptions {
   quietMs?: number;
   title?: string;
   sub?: string;
+  mode?: 'standard' | 'instant';
   runner?: FieldReelRunner;
   onDone?: (result: FieldReelResult) => void | Promise<void>;
   /** 같은 수신자가 앨범 항목마다 예약해도 한 렌더당 한 번만 통지한다. */
@@ -96,10 +98,12 @@ export function readFieldReelStatus(dir: string): FieldReelStatus | null {
   }
 }
 
-export const defaultFieldReelRunner: FieldReelRunner = (dir, { title, sub }) => new Promise((finish) => {
+export const defaultFieldReelRunner = (dir: string, { title, sub, mode = 'standard' }: { title: string; sub: string; mode?: 'standard' | 'instant' }, spawnReel: typeof spawn = spawn): Promise<FieldReelResult> => new Promise((finish) => {
   const script = resolve(import.meta.dir, '../../skills/explainer-video/engine/reel.sh');
   const started = Date.now();
-  const child = spawn('zsh', [script, dir, '--title', title, '--sub', sub], { stdio: 'ignore' });
+  const env = { ...process.env };
+  mergeCapturedPath(env, { capture: true });
+  const child = spawnReel('zsh', [script, dir, '--title', title, '--sub', sub, ...(mode === 'instant' ? ['--instant'] : [])], { stdio: 'ignore', env });
   let settled = false;
   const done = (error?: string) => {
     if (settled) return;
@@ -147,6 +151,7 @@ async function render(dir: string, job: Job): Promise<void> {
     result = await (renderOpts.runner ?? defaultFieldReelRunner)(dir, {
       title: titleLines[0]?.trim() || renderOpts.title || event,
       sub: titleLines[1]?.trim() || renderOpts.sub || sub,
+      ...(renderOpts.mode ? { mode: renderOpts.mode } : {}),
     });
   } catch (err) {
     result = { ok: false, seconds: 0, error: err instanceof Error ? err.message : String(err) };
@@ -160,10 +165,15 @@ async function render(dir: string, job: Job): Promise<void> {
   debug.log('field.reel', result.ok ? 'done' : 'failed', { event, items, seconds: result.seconds });
   if (result.ok) {
     // EV10b: 엔진이 timeline.json 에 남긴 비전 호출 수·성공·«현장 N» 강등·걸린 ms — codex 잔량과 겹치므로 관측한다(OP 10-01).
+    let cardsCache: 'hit' | 'miss' | 'n/a' = 'n/a';
     try {
-      const t = JSON.parse(readFileSync(join(dir, 'reel', 'timeline.json'), 'utf8')) as { vision?: Record<string, unknown>; music?: unknown };
+      const t = JSON.parse(readFileSync(join(dir, 'reel', 'timeline.json'), 'utf8')) as { vision?: Record<string, unknown>; music?: unknown; cardsCache?: 'hit' | 'miss' };
       if (t.vision) debug.log('field.reel', 'vision', { event, ...t.vision, music: t.music === true });
+      if (renderOpts.mode === 'instant' && (t.cardsCache === 'hit' || t.cardsCache === 'miss')) cardsCache = t.cardsCache;
     } catch { debug.log('field.reel', 'vision-unread', { event }); }
+    // A custom runner without an explicit mode may render any way — say «unknown» instead of guessing the default.
+    const mode = renderOpts.mode ?? (renderOpts.runner ? 'unknown' : 'standard');
+    debug.log('field.reel', 'rendered', { mode, seconds: result.seconds, cardsCache });
   }
   // 뒤이은 업로드로 다시 렌더할 예정이면(dirty) 피드는 그 마지막 렌더 뒤에 한 번만 띄운다.
   if (result.ok && !job.dirty) result = { ...result, feed: (renderOpts.startFeed ?? ((d: string) => startFieldFeed(d, { enabled: renderOpts.autoFeed })))(dir) };

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