elanous 0.2.35 → 0.2.37

package/src/graph-runner/runner.ts

@@ -38,6 +38,7 @@ const RELEASE_NODE_COMMANDS: Readonly<Record<string, { recipe: string; command?:
   'checklist-gate': { recipe: 'cmd:checklist-gate', command: 'bun scripts/release-loop/checklist-gate-node.ts' },
   prefetch: { recipe: 'cmd:docs', command: 'bun scripts/release-loop/docs-node.ts --json' },
   gate: { recipe: 'cmd:gate', command: 'bun scripts/release-loop/gate-node.ts --json' },
+  'traffic-gate-passed': { recipe: 'cmd:traffic-gate-passed', command: 'bun scripts/release-loop/traffic-node.ts traffic-gate-passed' },
   'gate-triage': { recipe: 'cmd:gate-triage', command: 'bun scripts/release-loop/gate-triage-node.ts' },
   'mac-smoke': { recipe: 'cmd:mac-smoke', command: 'bun scripts/release-loop/mac-smoke-node.ts' },
   'export-check': { recipe: 'cmd:export-check', command: 'bun scripts/release-loop/export-check-node.ts' },
@@ -48,12 +49,15 @@ const RELEASE_NODE_COMMANDS: Readonly<Record<string, { recipe: string; command?:
   docs: { recipe: 'cmd:docs', command: 'bun scripts/release-loop/docs-node.ts --json' },
   'known-issues': { recipe: 'cmd:known-issues', command: 'bun scripts/release-loop/known-issues-node.ts' },
   'notes-check': { recipe: 'cmd:notes-check', command: 'bun scripts/announce-loop/check-node.ts --json' },
+  'notes-repair': { recipe: 'cmd:docs', command: 'bun scripts/release-loop/docs-node.ts --json' },
+  'notes-recheck': { recipe: 'cmd:notes-check', command: 'bun scripts/announce-loop/check-node.ts --json' },
   'auto-approve': { recipe: 'cmd:auto-approve', command: 'bun scripts/release-loop/auto-approve-node.ts' },
   'approve-publish': { recipe: 'approval:publish' },
   publish: { recipe: 'cmd:publish-command', command: 'bun scripts/release-loop/publish-node.ts' },
   'npm-publish': { recipe: 'cmd:npm-publish', command: 'bun scripts/release-loop/npm-publish-node.ts' },
   'docs-land': { recipe: 'cmd:docs-land', command: 'bun scripts/release-loop/docs-land-node.ts' },
   verify: { recipe: 'cmd:verify', command: 'bun scripts/release-loop/verify-node.ts' },
+  'traffic-verify-complete': { recipe: 'cmd:traffic-verify-complete', command: 'bun scripts/release-loop/traffic-node.ts traffic-verify-complete' },
   'vault-note': { recipe: 'cmd:vault-note', command: 'bun scripts/release-loop/vault-note-node.ts' },
   'release-story': { recipe: 'cmd:release-story', command: 'bun scripts/release-story/draft.ts --graph' },
   'ops-upgrade': { recipe: 'cmd:ops-upgrade', command: 'bun scripts/release-loop/ops-upgrade-node.ts' },
@@ -140,7 +144,7 @@ export interface GraphRunState {
   reason?: string;
   path: string[];
   /** startedAt/endedAt (ISO) and seconds are written when the node runs; ledgers before GRAPH-NODE-TIMES (0.2.19) have none. */
-  nodes: Array<{ nodeId: string; ok: boolean; exit: number | null; executed: boolean; output?: unknown; error?: string; decidedBy?: string; decidedAt?: string;
+  nodes: Array<{ nodeId: string; ok: boolean; exit: number | null; executed: boolean; output?: unknown; error?: string; reason?: string; decidedBy?: string; decidedAt?: string;
     startedAt?: string; endedAt?: string; seconds?: number;
     waiver?: { reason: string; at: string; /** RELEASE-WAIVE-UNMEASURED — why the waived gate had no verdict. */ unmeasured?: string; original: { exit: number | null; output?: unknown; error?: string } } }>;
   /** The node now running and when it started; cleared when its record is written. */
@@ -168,6 +172,11 @@ export interface GraphRunState {
   statePath: string;
 }
 
+function failedCommandStderrTail(exitCode: number, stderr: string): string | undefined {
+  if (exitCode === 0 || !stderr.trim()) return undefined;
+  return stderr.replace(/(?:\r?\n)+$/, '').split(/\r?\n/).slice(-40).join('\n') || undefined;
+}
+
 export interface GraphClassifyInput {
   arguments: string;
   classify: ClassifyNode['classify'];
@@ -266,6 +275,20 @@ export function verifyReleaseCommandRoot(root: string, cutTip: string, git?: (ar
   return commandRoot;
 }
 
+/** Reject a checkout whose saved release graph or recipes differ, including before an injected graph runner is called. */
+export function verifyReleaseRecipeSnapshot(commandRoot: string, snapshot?: { graphSha: string; recipesSha: string }): void {
+  if (!snapshot) throw new Error('release recipe snapshot missing — cannot pin command source');
+  const cutGraph = join(commandRoot, 'graphs', 'release', 'release-loop.yaml');
+  const cutRecipes = join(commandRoot, 'graphs', 'release', 'recipes.yaml');
+  const hashFile = (file: string): string => {
+    try { return createHash('sha256').update(readFileSync(file)).digest('hex'); }
+    catch { throw new Error(`release recipe source missing in cut checkout: ${file}`); }
+  };
+  if (hashFile(cutGraph) !== snapshot.graphSha || hashFile(cutRecipes) !== snapshot.recipesSha) {
+    throw new Error('release recipe source differs from the saved graph snapshot at cut tip');
+  }
+}
+
 function safeSegment(value: string): string {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) || value === '.' || value === '..') {
     throw new Error(`invalid graph run identifier: ${value}`);
@@ -780,16 +803,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     const commandRoot = verifyReleaseCommandRoot(source.root, savedCutTip, source.git);
     // The ledger snapshot must be the recipe that the cut checkout actually carries.
     // HEAD alone does not bind a saved graph to that checkout.
-    if (!state.graphSnapshot) throw new Error('release recipe snapshot missing — cannot pin command source');
-    const cutGraph = join(commandRoot, 'graphs', 'release', 'release-loop.yaml');
-    const cutRecipes = join(commandRoot, 'graphs', 'release', 'recipes.yaml');
-    const hashFile = (file: string): string => {
-      try { return createHash('sha256').update(readFileSync(file)).digest('hex'); }
-      catch { throw new Error(`release recipe source missing in cut checkout: ${file}`); }
-    };
-    if (hashFile(cutGraph) !== state.graphSnapshot.graphSha || hashFile(cutRecipes) !== state.graphSnapshot.recipesSha) {
-      throw new Error('release recipe source differs from the saved graph snapshot at cut tip');
-    }
+    verifyReleaseRecipeSnapshot(commandRoot, state.graphSnapshot);
     return commandRoot;
   };
   verifyReleaseSource();
@@ -1062,6 +1076,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     let ok = approval && !state.dryRun ? state.pending?.decision === 'approved' : true;
     let exit: number | null = null;
     let error: string | undefined;
+    let commandFailureReason: string | undefined;
     let output: unknown;
     const waiving = options.releaseWaiver?.nodeId === current && waivedRecord !== undefined;
     if (command && !waiving && (!approval || state.dryRun || ok) && (!state.dryRun || command.dry_run_command) && !resumingCompleted) {
@@ -1070,7 +1085,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       for (const previous of state.nodes) outputs[previous.nodeId] = lastJsonObject(previous.output) ?? previous.output ?? null;
       const contextPath = join(`${statePath}.contexts`, `${state.path.length}.json`);
       mkdirSync(dirname(contextPath), { recursive: true });
-      writeFileSync(contextPath, JSON.stringify({ graphId, runId, nodeId: current, input: state.input ?? null, outputs }, null, 2) + '\n');
+      writeFileSync(contextPath, JSON.stringify({ graphId, runId, startedAt: state.startedAt, nodeId: current, input: state.input ?? null, outputs }, null, 2) + '\n');
       let code: number | null = null;
       const redactCredentials = (text: string) => Object.values(credentials).filter(value => value.length > 0)
         .reduce((safe, value) => safe.replaceAll(value, '[REDACTED]'), text);
@@ -1096,7 +1111,9 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
         try {
           const result = await execute(body, commandRoot ? { ...opts, cwd: commandRoot } : opts);
           code = result.exitCode;
-          return { ...result, stdout: redactCredentials(result.stdout), stderr: redactCredentials(result.stderr) };
+          const stderr = redactCredentials(result.stderr);
+          commandFailureReason = failedCommandStderrTail(result.exitCode, stderr);
+          return { ...result, stdout: redactCredentials(result.stdout), stderr };
         } finally {
           if (state.activeNode?.nodeId === current) {
             delete state.activeNode;
@@ -1287,13 +1304,14 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       exit = completed.exit;
       output = completed.output;
       error = completed.error;
+      commandFailureReason = completed.reason;
     } else {
       // 승인 노드도 결과를 «값»으로 남긴다 — 뒤 노드가 문맥(outputs)에서 승인 여부를 확인할 수 있게(발행 노드가 승인 없이 돌지 않도록).
       if (approval && !state.dryRun && !command) {
         output = JSON.stringify({ outcome: ok ? 'approved' : 'rejected', graphId, runId, nodeId: current,
           ...(state.pending?.decidedBy === undefined ? {} : { decidedBy: state.pending.decidedBy }), decidedAt: state.pending?.decidedAt ?? null });
       }
-      state.nodes.push({ nodeId: current, ok, exit, executed: !waiving && ((!!command && (!state.dryRun || !!command.dry_run_command)) || (!!prompt && !state.dryRun) || (node.kind === 'classify' && !state.dryRun) || unitExecuted), ...((waiving || harnessLoopRoute || units.has(current) || ((command || prompt || approval || node.kind === 'classify') && (!state.dryRun || !!command?.dry_run_command))) && output !== undefined ? { output } : {}), ...(error ? { error } : {}),
+      state.nodes.push({ nodeId: current, ok, exit, executed: !waiving && ((!!command && (!state.dryRun || !!command.dry_run_command)) || (!!prompt && !state.dryRun) || (node.kind === 'classify' && !state.dryRun) || unitExecuted), ...((waiving || harnessLoopRoute || units.has(current) || ((command || prompt || approval || node.kind === 'classify') && (!state.dryRun || !!command?.dry_run_command))) && output !== undefined ? { output } : {}), ...(error ? { error } : {}), ...(commandFailureReason ? { reason: commandFailureReason } : {}),
         ...(waiving ? { waiver: { reason: options.releaseWaiver!.reason, at: nodeEndedAt, ...(options.releaseWaiver!.unmeasured === undefined ? {} : { unmeasured: options.releaseWaiver!.unmeasured }), original: { exit: waivedRecord!.exit, ...(waivedRecord!.output === undefined ? {} : { output: waivedRecord!.output }), ...(waivedRecord!.error === undefined ? {} : { error: waivedRecord!.error }) } } } : {}),
         ...(approval && state.pending ? { ...(state.pending.decidedBy === undefined ? {} : { decidedBy: state.pending.decidedBy }), decidedAt: state.pending.decidedAt } : {}),
         startedAt: nodeStartedAt, endedAt: nodeEndedAt, seconds });
@@ -1309,10 +1327,13 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     const reported: unknown = waiving || harnessLoopRoute || units.has(current) || (prompt && !state.dryRun) || (command && (!state.dryRun || command.dry_run_command)) ? lastJsonObject(resumingCompleted ? completed?.output : output)?.outcome : undefined;
     const namedOutcome: string | undefined = typeof reported === 'string' ? reported : undefined;
     if (!options.quiet) console.error(`[graph] ${current} ${ok ? 'ok' : 'fail'} (${seconds.toFixed(2)}s)`);
-    debug.log('graph.run', 'node', { graphId, runId, nodeId: current, phase: ok ? 'ok' : 'fail', seconds, exit });
+    debug.log('graph.run', 'node', { graphId, runId, nodeId: current, phase: ok ? 'ok' : 'fail', seconds, exit,
+      ...(commandFailureReason ? { reason: commandFailureReason } : {}) });
     publishInsideEvent({ kind: 'node', graphId, runId, nodeId: current, phase: ok ? 'ok' : 'fail', seconds });
     publishInsideEvent({ kind: 'verdict', graphId, runId, nodeId: current, verdict: ok ? 'ok' : 'fail', ...(namedOutcome === undefined ? {} : { outcome: namedOutcome }) });
-    log('node-end', { graphId, runId, nodeId: current, ok, exit, ...(namedOutcome === undefined ? {} : { outcome: namedOutcome }), dryRun: state.dryRun });
+    log('node-end', { graphId, runId, nodeId: current, ok, exit,
+      ...(commandFailureReason ? { reason: commandFailureReason } : {}),
+      ...(namedOutcome === undefined ? {} : { outcome: namedOutcome }), dryRun: state.dryRun });
     if (!resumingCompleted) {
       // Recipe commands expose stdout/exit but no provider usage; never infer zero from success.
       observeModelInputTokens({ scope: 'harness-node', nodeKind: node.kind, runId, nodeId: current });

package/src/graph-wizard/generate.ts

@@ -16,11 +16,13 @@ import { debug } from '../debug/log.js';
 import { listNodeKinds, type GraphKind } from '../graph-kinds/registry.js';
 import { validateGraphYaml } from '../nexus/api/graph-kinds.js';
 import { defaultGraphsDir } from '../self-implement/graph-templates.js';
+import { createGraphVariant, type GraphVariantPlan, type GraphVariantResult } from '../self-implement/graph-variant.js';
+import type { GraphTemplateSpec } from '../self-implement/graph-yaml.js';
 import { WORKFLOW_SYNTH_SYSTEM_PROMPT } from '../workflow-synth/system-prompt.js';
 import { WIZARD_ARCHETYPES } from './archetypes.js';
 import { listInstalledPacks, queryInstalledPack } from '../knowledge/query.js';
 import { parsePackIdString } from '../knowledge/kgs/pack.js';
-import { WIZARD_MAX_RETRIES, WIZARD_STEPS, WIZARD_STEP_IDS, recipesYamlFor, type WizardNodeStep } from './steps.js';
+import { WIZARD_MAX_RETRIES, WIZARD_STEPS, WIZARD_STEP_IDS, recipesSiblingOf, recipesYamlFor, type WizardNodeStep } from './steps.js';
 
 export interface GraphWizardTurn { role: 'user' | 'assistant'; text: string }
 
@@ -71,6 +73,127 @@ export interface GraphWizardDeps {
 
 export const GRAPH_WIZARD_MAX_ATTEMPTS = 3;
 
+export interface KnownGraphUnit {
+  readonly id: string;
+  readonly call: string;
+  readonly inputs: readonly string[];
+  readonly outputs: readonly string[];
+  readonly exits: readonly string[];
+}
+
+/** Use the same validated template inventory as the wizard; only templates declaring a unit are candidates. */
+export function listKnownGraphUnits(dir = defaultGraphsDir()): KnownGraphUnit[] {
+  return listWizardTemplates(dir).flatMap((template) => {
+    let raw: { version?: unknown; unit?: { inputs?: unknown; outputs?: unknown; exits?: unknown } };
+    try { raw = parseYaml(template.text) as typeof raw; } catch { return []; }
+    if (!raw?.unit || !Number.isSafeInteger(raw.version)) return [];
+    const { inputs, outputs, exits } = raw.unit;
+    if (![inputs, outputs, exits].every((value) => Array.isArray(value) && value.every((item) => typeof item === 'string'))) return [];
+    return [{ id: template.id, call: `${template.id}@${raw.version}`, inputs: inputs as string[], outputs: outputs as string[], exits: exits as string[] }];
+  }).sort((a, b) => a.call.localeCompare(b.call));
+}
+
+/** 호출 경계로 올리는 조작 growth 요약 — 어느 from 노드에서 무엇을 끼우려 했나. */
+export interface GraphVariantGrowthTrace {
+  readonly from: string;
+  readonly outcome: string;
+  readonly nodeId: string;
+  readonly returnTo?: string;
+}
+
+/**
+ * 설계자 한 턴의 결말 — mode·reason 은 호출 경계가 관측으로 기록하는 필드다(composed 는 'composed',
+ * fallback-standard 는 그 사유 문자열 그대로). growth 는 설계자가 조작한 from 노드를 그대로 올린다.
+ */
+export type GraphVariantDesignResult =
+  | { readonly mode: 'variant'; readonly status: 'composed'; readonly reason: 'composed'; readonly plan: GraphVariantPlan; readonly variant: Extract<GraphVariantResult, { ok: true }>; readonly growth?: GraphVariantGrowthTrace }
+  | { readonly mode: 'variant'; readonly status: 'fallback-standard'; readonly template: GraphTemplateSpec; readonly reason: string; readonly growth?: GraphVariantGrowthTrace };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** 설계자 출력에서 조작 growth 의 좌표만 읽는다 — 모양이 틀려도 «어느 from 이었나»는 남긴다. */
+function growthTraceOf(record: Record<string, unknown> | null): GraphVariantGrowthTrace | undefined {
+  const growth = record?.growth;
+  if (!isRecord(growth) || typeof growth.from !== 'string' || typeof growth.outcome !== 'string') return undefined;
+  const node = isRecord(growth.node) ? growth.node : undefined;
+  if (typeof node?.nodeId !== 'string') return undefined;
+  return { from: growth.from, outcome: growth.outcome, nodeId: node.nodeId,
+    ...(typeof growth.returnTo === 'string' ? { returnTo: growth.returnTo } : {}) };
+}
+
+/** One L2 designer proposal. The model returns only a plan; the existing variant authority decides whether it may run. */
+export async function designGraphVariantPlan(input: {
+  readonly goal: string;
+  readonly prompt: string;
+  readonly template: GraphTemplateSpec;
+  readonly knownUnits?: readonly KnownGraphUnit[];
+}, deps: Pick<GraphWizardDeps, 'callLLM' | 'graphsDir'> = {}): Promise<GraphVariantDesignResult> {
+  const units = input.knownUnits ?? listKnownGraphUnits(deps.graphsDir);
+  const unitCalls = new Set(units.map((unit) => unit.call));
+  const lines = [
+    '알려진 그래프 유닛(새 노드를 짓기 전에 먼저 찾는다):',
+    ...units.map((unit) => `- ${unit.call} · inputs=${unit.inputs.join(',')} · outputs=${unit.outputs.join(',')} · exits=${unit.exits.join(',')}`),
+    '', '너는 발사 시점 L2 그래프 설계자다. 전체 YAML 대신 GraphVariantPlan JSON 객체 하나만 출력하라. 설명·코드 펜스·추가 키 금지.',
+    '허용 키: maxVisits(기존 nodeId→양의 정수), routes([{from,outcome,to}] 기존 조건 간선), growth({node,from,outcome,returnTo}) 한 개.',
+    '유닛 추가가 필요하면 growth.node는 kind=subgraph, call=<위 목록의 id@version>, recipe=none, maxVisits=1로 제안하라.',
+    'growth.node.contract는 선택한 유닛의 inputs와 outputs를 위 목록에서 순서까지 그대로 복사하고 tools="read-only"로 쓴다. 빈 배열로 바꾸거나 이름을 지어내지 마라.',
+    'growth는 기존 from 노드의 비어 있는 outcome에서만 가능하며 returnTo는 기존 노드여야 한다. 삭제·무조건 간선 변경·전체 그래프 생성은 불가하다.',
+    `골: ${input.goal}`, `요청: ${input.prompt}`, `기반: ${input.template.graphId}@${input.template.version}`,
+    `기존 노드: ${input.template.nodes.map((node) => `${node.nodeId}(${node.kind},maxVisits=${node.maxVisits})`).join(', ')}`,
+    `기존 간선: ${input.template.edges.map((edge) => `${edge.from}:${edge.on ?? 'direct'}→${edge.to ?? JSON.stringify(edge.map ?? {})}`).join(', ')}`,
+  ];
+  let raw: unknown;
+  try { raw = JSON.parse((await (deps.callLLM ?? defaultCallLLM)(lines.join('\n'))).trim()); }
+  catch (error) {
+    const reason = `designer-output: ${error instanceof Error ? error.message : String(error)}`;
+    debug.log('graph.compose', 'fallback-standard', { goal: input.goal, reason });
+    return { mode: 'variant', status: 'fallback-standard', template: input.template, reason };
+  }
+  const record = isRecord(raw) ? raw : null;
+  const growthTrace = growthTraceOf(record);
+  const allowed = new Set(['maxVisits', 'routes', 'growth']);
+  const maxVisits = record?.maxVisits;
+  const routes = record?.routes;
+  const growth = record?.growth;
+  const growthRecord = isRecord(growth) ? growth : null;
+  const growthNode = isRecord(growthRecord?.node) ? growthRecord.node : null;
+  const growthContract = isRecord(growthNode?.contract) ? growthNode.contract : null;
+  const selectedUnit = typeof growthNode?.call === 'string' ? units.find((unit) => unit.call === growthNode.call) : undefined;
+  const valid = record !== null && Object.keys(record).every((key) => allowed.has(key)) &&
+    (maxVisits === undefined || (maxVisits !== null && typeof maxVisits === 'object' && !Array.isArray(maxVisits) &&
+      Object.values(maxVisits).every((value) => Number.isSafeInteger(value) && (value as number) > 0))) &&
+    (routes === undefined || (Array.isArray(routes) && routes.every((route) => route !== null && typeof route === 'object' &&
+      !Array.isArray(route) && Object.keys(route).sort().join(',') === 'from,outcome,to' &&
+      [route.from, route.outcome, route.to].every((value) => typeof value === 'string')))) &&
+    (growth === undefined || (growthRecord !== null &&
+      Object.keys(growthRecord).sort().join(',') === 'from,node,outcome,returnTo' &&
+      typeof growthRecord.from === 'string' && typeof growthRecord.outcome === 'string' && typeof growthRecord.returnTo === 'string' &&
+      growthNode !== null && Object.keys(growthNode).sort().join(',') === 'call,contract,kind,maxVisits,nodeId,recipe' &&
+      typeof growthNode.nodeId === 'string' && growthNode.kind === 'subgraph' && growthNode.recipe === 'none' &&
+      growthNode.maxVisits === 1 && typeof growthNode.call === 'string' && unitCalls.has(growthNode.call) && selectedUnit !== undefined &&
+      growthContract !== null && growthContract.tools === 'read-only' &&
+      Array.isArray(growthContract.inputs) && growthContract.inputs.every((value) => typeof value === 'string') &&
+      Array.isArray(growthContract.outputs) && growthContract.outputs.every((value) => typeof value === 'string') &&
+      JSON.stringify(growthContract.inputs) === JSON.stringify(selectedUnit.inputs) &&
+      JSON.stringify(growthContract.outputs) === JSON.stringify(selectedUnit.outputs)));
+  if (!valid) {
+    const reason = 'designer-output: invalid GraphVariantPlan or unknown unit';
+    debug.log('graph.compose', 'fallback-standard', { goal: input.goal, reason });
+    return { mode: 'variant', status: 'fallback-standard', template: input.template, reason, ...(growthTrace ? { growth: growthTrace } : {}) };
+  }
+  const plan = record as GraphVariantPlan;
+  const variant = createGraphVariant({ template: input.template, goal: input.goal, plan });
+  if (!variant.ok) {
+    const reason = `variant-rejected: ${JSON.stringify(variant.rejections)}`;
+    debug.log('graph.compose', 'fallback-standard', { goal: input.goal, reason });
+    return { mode: 'variant', status: 'fallback-standard', template: input.template, reason, ...(growthTrace ? { growth: growthTrace } : {}) };
+  }
+  debug.log('graph.compose', 'composed', { goal: input.goal, overlayId: variant.overlay.overlayId, patches: variant.patches.length });
+  return { mode: 'variant', status: 'composed', reason: 'composed', plan, variant, ...(growthTrace ? { growth: growthTrace } : {}) };
+}
+
 /** Inventory used by the editor's pack picker and the wizard's validation. */
 export function wizardInstalledPacks(deps: GraphWizardDeps = {}): Array<{ id: string; title: string }> {
   return (deps.packs ?? listInstalledPacks)();
@@ -80,7 +203,7 @@ export function wizardInstalledPacks(deps: GraphWizardDeps = {}): Array<{ id: st
 export class GraphWizardInputError extends Error { override name = 'GraphWizardInputError'; }
 const GRAPH_ID = /^[a-z0-9-]+$/;
 
-interface TemplateEntry { id: string; description: string; text: string; runnable: boolean; keywords?: string[] }
+interface TemplateEntry { id: string; description: string; text: string; runnable: boolean; keywords?: string[]; recipes?: string }
 
 function walkYaml(dir: string, depth = 0): string[] {
   if (depth > 3 || !existsSync(dir)) return [];
@@ -123,7 +246,8 @@ export function listWizardTemplates(dir = defaultGraphsDir()): TemplateEntry[] {
     const description = [loop.title, loop.description].filter((v): v is string => typeof v === 'string').join(' — ') || raw.graph_id;
     const terminals = Array.isArray(raw.terminal_nodes) ? raw.terminal_nodes : [];
     seen.add(raw.graph_id);
-    out.push({ id: raw.graph_id, description: description.slice(0, 160), text, runnable: terminals.every((t) => t === 'done' || t === 'failed') });
+    const recipes = recipesSiblingOf(file);
+    out.push({ id: raw.graph_id, description: description.slice(0, 160), text, runnable: terminals.every((t) => t === 'done' || t === 'failed'), ...(recipes ? { recipes } : {}) });
   }
   return out;
 }
@@ -521,7 +645,10 @@ function buildPrompt(input: {
   ];
   if (kind === 'harness' && !editing) {
     lines.push('', '기존 템플릿 목록(id — 설명):', ...templates.filter((t) => t.runnable).slice(0, 30).map((t) => `- ${t.id} — ${t.description}`));
-    if (base) lines.push('', `가장 가까운 템플릿(${base.id}) — 구조를 참고하라:`, '```yaml', base.text.trim(), '```');
+    if (base) {
+      lines.push('', `가장 가까운 템플릿(${base.id}) — 구조를 참고하라:`, '```yaml', base.text.trim(), '```');
+      if (base.recipes) lines.push('', `같은 템플릿의 recipes.yaml — 같은 단계의 명령·타임아웃·승인 문구를 그대로 재사용하라:`, '```yaml', base.recipes.trim(), '```');
+    }
   }
   if (req.history?.length) {
     lines.push('', '지금까지의 대화:', ...req.history.slice(-10).map((t) => `${t.role === 'user' ? '사용자' : '마법사'}: ${t.text.slice(0, 500)}`));

package/src/graph-wizard/steps.ts

@@ -76,6 +76,21 @@ export function recipesYamlFor(nodes: ReadonlyArray<{ nodeId: string; recipe: st
   return out.length ? `${out.join('\n')}\n` : '{}\n';
 }
 
+/**
+ * 템플릿과 같은 디렉터리의 recipes.yaml — 로더(src/self-implement/graph-yaml.ts)가 템플릿에서
+ * 빼는 «명령 카탈로그» 쪽을 읽는다. 그래프의 cmd/approval 노드가 실제로 무엇을 부르는지가 여기 있다.
+ */
+export function recipesSiblingOf(graphFile: string): string | undefined {
+  const slash = graphFile.lastIndexOf('/');
+  const dir = slash < 0 ? '' : `${graphFile.slice(0, slash + 1)}`;
+  for (const name of ['recipes.yaml', 'recipes.yml']) {
+    const path = `${dir}${name}`;
+    if (!existsSync(path)) continue;
+    try { return readFileSync(path, 'utf8'); } catch { return undefined; }
+  }
+  return undefined;
+}
+
 interface GraphContext { graphId?: string; runId?: string; nodeId?: string; input?: unknown; outputs?: Record<string, unknown> }
 
 function readContext(): GraphContext {

package/src/grounding/proactive-ground.ts

@@ -0,0 +1,86 @@
+// Proactive grounding — one request goes to three indexes (우리가 함 / 남이 함 /
+// 전에 실패함) and only the citable survivors come back.
+//
+// Pure in/out: the three query functions are injected, nothing is read or
+// written here. A hit is citable only when it carries a `ref` (source id ⊕
+// file path), so everything else is dropped; if nothing survives, the caller
+// stays silent instead of inventing a reason.
+
+import type { ReferenceCard } from './ref-index.js';
+
+/** Which index answered: what we did, what others did, what failed before. */
+export type RefIndexKey = 'ours' | 'others' | 'failed';
+
+export interface ReferenceHit {
+  /** Source id ⊕ file path. A hit without it cannot be linked, so it is dropped. */
+  ref?: string;
+  title?: string;
+  score?: number;
+  /** L0 identity of the source, when the index handed it over. */
+  card?: ReferenceCard;
+}
+
+/** One index, asked once per request. */
+export type ReferenceQuery = (request: string) => readonly ReferenceHit[];
+
+export interface ProactiveReferenceSources {
+  ours: ReferenceQuery;
+  others: ReferenceQuery;
+  failed: ReferenceQuery;
+}
+
+export interface ProactiveGroundOptions {
+  /** Hits scoring under this are dropped. Default 0. */
+  minScore?: number;
+  /** Max hits kept per index, strongest first. Default 2. */
+  perIndex?: number;
+}
+
+export interface GroundedReference {
+  index: RefIndexKey;
+  ref: string;
+  title: string;
+  score: number;
+  card?: ReferenceCard;
+}
+
+export interface ProactiveReferencesResult {
+  refs: GroundedReference[];
+  /** Nothing survived every filter — the request grounds to nothing, so stay silent. */
+  silent: boolean;
+}
+
+export const DEFAULT_MAX_PER_INDEX = 2;
+export const DEFAULT_MIN_SCORE = 0;
+
+/** Asked in this order, so a merged list always reads ours → others → failed. */
+const INDEX_ORDER: readonly RefIndexKey[] = ['ours', 'others', 'failed'];
+
+export function proactiveReferences(
+  request: string,
+  sources: ProactiveReferenceSources,
+  opts: ProactiveGroundOptions = {},
+): ProactiveReferencesResult {
+  const minScore = opts.minScore ?? DEFAULT_MIN_SCORE;
+  const perIndex = Math.max(0, Math.trunc(opts.perIndex ?? DEFAULT_MAX_PER_INDEX));
+
+  const refs: GroundedReference[] = [];
+  for (const index of INDEX_ORDER) {
+    const kept = sources[index](request)
+      .filter((hit): hit is ReferenceHit & { ref: string } => typeof hit.ref === 'string' && hit.ref.trim() !== '')
+      .map((hit) => ({ hit, score: hit.score ?? DEFAULT_MIN_SCORE }))
+      .filter(({ score }) => score >= minScore)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, perIndex)
+      .map(({ hit, score }) => ({
+        index,
+        ref: hit.ref,
+        title: hit.title ?? hit.ref,
+        score,
+        ...(hit.card ? { card: hit.card } : {}),
+      }));
+    refs.push(...kept);
+  }
+
+  return { refs, silent: refs.length === 0 };
+}

package/src/harness/control-inbox.ts

@@ -448,6 +448,18 @@ function consumeRecord(
     return;
   }
   messages.push(message);
+  // A Pod sender asks for this exact record's acknowledgement before publishing
+  // it. Missing ack is safe: delivery has happened, but the sender must report
+  // read state as unobserved rather than infer it from file disappearance.
+  if (existsSync(`${recordPath}.ack-request`)) {
+    // Rename consumes the request atomically. If the sender already removed it,
+    // this cannot leave a late ack file after the sender's cleanup.
+    try { renameSync(`${recordPath}.ack-request`, `${recordPath}.ack`); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT')
+        logger(opts)('control-inbox', 'memo-ack-failed', { spaceId, path: recordPath, reason: String(error) });
+    }
+  }
 }
 
 /** Inspect existing ready records without claiming, deleting, or creating any inbox entry. */
@@ -541,7 +553,43 @@ export function cleanupStaleControlInbox(spaceId: string, maxAgeMs: number, opts
       restoreClaim(claimPath, recordPath, spaceId, opts);
     }
   }
-  logger(opts)('control-inbox', 'cleanup', { spaceId, path, maxAgeMs, count });
+  // A sender killed without an EXIT trap can leave receipt markers behind.
+  // Its wait is capped at 60s; keep at least two minutes before sweeping only
+  // markers whose exact record no longer exists. Never infer a read from cleanup.
+  let markerCount = 0;
+  let tempCount = 0;
+  let markerNames: string[] = [];
+  try { markerNames = readdirSync(ready); } catch { /* absent ready directory */ }
+  const markerCutoff = Date.now() - Math.max(maxAgeMs, 120_000);
+  for (const name of markerNames) {
+    // Only the Pod publisher's mktemp shape; local enqueue has a different name.
+    if (/^\.write-[A-Za-z0-9]{8}$/.test(name)) {
+      const tempPath = join(ready, name);
+      try {
+        if (statSync(tempPath).mtimeMs > markerCutoff) continue;
+        rmSync(tempPath);
+        tempCount += 1;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT')
+          logger(opts)('control-inbox', 'cleanup-temp-failed', { spaceId, path: tempPath, reason: String(error) });
+      }
+      continue;
+    }
+    const suffix = name.endsWith('.ack-request') ? '.ack-request' : name.endsWith('.ack') ? '.ack' : null;
+    if (!suffix) continue;
+    const recordName = name.slice(0, -suffix.length);
+    if (!isReadyRecord(recordName) || existsSync(join(ready, recordName))) continue;
+    const markerPath = join(ready, name);
+    try {
+      if (statSync(markerPath).mtimeMs > markerCutoff) continue;
+      rmSync(markerPath);
+      markerCount += 1;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT')
+        logger(opts)('control-inbox', 'cleanup-marker-failed', { spaceId, path: markerPath, reason: String(error) });
+    }
+  }
+  logger(opts)('control-inbox', 'cleanup', { spaceId, path, maxAgeMs, count, markerCount, tempCount });
   return count;
 }