elanous 0.2.35 → 0.2.36

package/src/domains/standalone-log-sink.ts

@@ -10,20 +10,33 @@
 /**
  * 독립 프로세스에서 logs.db 싱크를 등록한다. 반환된 off 는 process 'exit' 에 자동 배선된다.
  * @param surface  이 프로세스가 남기는 로그의 surface 라벨(예: 'scheduler'·'autopilot').
+ * @param opts.wrapSink  logs.db 싱크를 감싼다(예: TUI 는 pid·`--name`·세션을 data 에 찍는다 — debug/tui-log-tag.ts).
  */
-export async function registerStandaloneLogSink(surface: string): Promise<boolean> {
+export async function registerStandaloneLogSink(
+  surface: string,
+  opts: { wrapSink?: (sink: import('../mss/logging/sink.js').LogSink) => import('../mss/logging/sink.js').LogSink } = {},
+): Promise<boolean> {
   try {
     const [storeMod, dbgMod, cfgMod] = await Promise.all([
       import('../mss/logging/log-store.js'),
       import('../debug/log.js'),
       import('../user-config.js'),
     ]);
+    // TUI-LOG-SESSION-TAG — 한 logs.db 를 여러 TUI(클래식·next)가 쓴다: 행마다 pid·`--name`·소유 세션을 data 에 찍는다.
+    if (surface === 'tui' && !opts.wrapSink) {
+      const tagMod = await import('../debug/tui-log-tag.js');
+      const tag = tagMod.processTuiLogTag();
+      opts = { ...opts, wrapSink: (s) => tagMod.withTuiLogTag(s, tag) };
+    }
     const logsCfg = cfgMod.getUserConfig().logs;
     storeMod.setLogInstanceName(logsCfg.instanceName);
+    // TUI-TYPING-LAG — TUI 는 워커 로그 폭주를 덩어리로 나눠 넣는다(키가 drain 전체를 기다리지 않게).
+    const drainChunkSize = storeMod.logStoreDrainChunkForSurface(surface);
     const offStore = storeMod.registerLogStoreSink(
-      (s) => dbgMod.debug.registerSink(s),
+      (s) => dbgMod.debug.registerSink(opts.wrapSink ? opts.wrapSink(s) : s),
       surface,
       logsCfg.retention,
+      drainChunkSize !== undefined ? { drainChunkSize } : {},
     );
     if (!offStore) return false;
     process.on('exit', offStore);

package/src/esc-abort-gate.ts

@@ -145,6 +145,75 @@ export function createHarnessEscHint(pushLine: (line: string) => void): (targets
   };
 }
 
+export interface EscAbortPendingSoftStopRunnerDeps {
+  getActiveHarnessSpace: () => string | null;
+  pushChatLine: (line: string) => void;
+  showHarnessEscHint: (targets: readonly string[]) => boolean;
+}
+
+export interface EscAbortPendingSoftStopOutcomeLike {
+  outcome: 'stopped' | 'failed' | 'hint' | 'waiting';
+  stoppedHarnessSpace: string | null;
+}
+
+export interface EscAbortPendingGateDeps {
+  /**
+   * Production soft-stop runner (`runEscAbortPendingSoftStop` in
+   * src/dashboard/index.ts): enqueues the durable soft-stop marker,
+   * verifies it, and paints the stopped/failure line. Injected (not
+   * imported) to keep this module free of a dashboard import cycle.
+   */
+  runSoftStop: (targets: readonly string[], deps: EscAbortPendingSoftStopRunnerDeps) => EscAbortPendingSoftStopOutcomeLike;
+  formatWaitingTargets: (targets: readonly string[]) => string;
+  getActiveHarnessSpace: () => string | null;
+  pushChatLine: (line: string) => void;
+  showHarnessEscHint: (targets: readonly string[]) => boolean;
+  /** Dashboard paint hook (chatScrollOffset reset) after each callback. */
+  afterAbortEvent?: () => void;
+}
+
+export interface EscAbortPendingGate {
+  onAbortPending(event: { running: number; repeat: number; targets: readonly string[] }): void;
+  onAbortRepeat(event: { running: number; repeat: number; targets: readonly string[]; phase: 'confirming' | 'pending' }): void;
+  getStoppedHarnessSpace(): string | null;
+}
+
+/**
+ * ⭐ TUI-ESC-EXIT production seam — the onAbortPending/onAbortRepeat
+ * callback pair that `attachChatStreamingKeys` wires into
+ * `createEscAbortGate`. Extracted from the dashboard inline closure so the
+ * incident test exercises the same function the dashboard executes.
+ *
+ * ⛔ Preservation rule: `stoppedHarnessSpace` only advances on a successful
+ * soft stop (a real stopped space). Later waiting/hint/failed callbacks must
+ * NOT clear a previously successful space — `onAbortRepeat` and the
+ * teardown `settleEscAbortPendingLines` decision depend on the retained value.
+ */
+export function createEscAbortPendingGate(deps: EscAbortPendingGateDeps): EscAbortPendingGate {
+  let stoppedHarnessSpace: string | null = null;
+  return {
+    onAbortPending({ targets }) {
+      const softStop = deps.runSoftStop(targets, {
+        getActiveHarnessSpace: deps.getActiveHarnessSpace,
+        pushChatLine: deps.pushChatLine,
+        showHarnessEscHint: deps.showHarnessEscHint,
+      });
+      if (softStop.stoppedHarnessSpace) stoppedHarnessSpace = softStop.stoppedHarnessSpace;
+      if (softStop.outcome === 'waiting') {
+        deps.pushChatLine(`  ⏳ 중단 요청됨 — ${deps.formatWaitingTargets(targets)} 종료를 기다리는 중입니다.`);
+      }
+      deps.afterAbortEvent?.();
+    },
+    onAbortRepeat({ repeat, targets }) {
+      if (!stoppedHarnessSpace && !deps.showHarnessEscHint(targets)) {
+        deps.pushChatLine(`  ⏳ ESC 재시도 ${repeat}회 — ${deps.formatWaitingTargets(targets)} 종료를 기다리는 중입니다.`);
+      }
+      deps.afterAbortEvent?.();
+    },
+    getStoppedHarnessSpace: () => stoppedHarnessSpace,
+  };
+}
+
 export function createEscAbortGate(deps: EscAbortGateDeps): EscAbortGate {
   let current: ApprovalModalHandle | null = null;
   let currentDispose: (() => void) | null = null;

package/src/git-fs/worktree.ts

@@ -10,7 +10,7 @@
 // because elanous's primary surface runs native git.
 
 import { spawnSync, execFileSync, type SpawnSyncReturns } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync, rmSync, symlinkSync, lstatSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync, rmSync, symlinkSync, lstatSync, unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { findGitDir } from './locate.js';
@@ -18,6 +18,7 @@ import { isTransientGitError } from './retry.js';
 import { runGitCommand } from './runner.js';
 import { debug } from '../debug/log.js';
 import { getUserConfig } from '../user-config.js';
+import { GATE_DEPS_DIR, GATE_DEPS_TREES, projectDepsManifest } from '../task-orchestrator/surfaces/pod-gate-deps.js';
 
 const GIT_TIMEOUT_MS = 30_000;
 /** 얕은 클론(Pod `git clone --depth 50` · docker/harness/job.yaml)에서 base 를 가져올 깊이 — 클론과 같은 값.
@@ -30,6 +31,7 @@ const TRACKED_FILE_COUNT_MAX_BUFFER = 16 * 1024 * 1024;
 
 export interface WorktreeAddDeps {
   spawn?: (command: string, args: string[], options: { cwd: string; encoding: 'utf8'; timeout: number; maxBuffer: number }) => SpawnSyncReturns<string>;
+  installDependencies?: (cwd: string, timeoutMs: number) => { status: number | null; stderr?: string | null; error?: Error };
   countTrackedFiles?: (repoRoot: string, ref?: string) => number | null;
 }
 
@@ -324,6 +326,81 @@ export function linkWorktreeDependencies(
   return result;
 }
 
+const WORKTREE_DEPENDENCY_INSTALL_TIMEOUT_MS = 600_000;
+
+/** A lockfile-bearing child must have dependencies before its tests start. */
+export class WorktreeDependencyPreparationError extends Error {
+  readonly code = 'WORKTREE_DEPENDENCIES_UNAVAILABLE';
+  constructor(readonly worktreePath: string, readonly dependencyPath: string, readonly reason: string) {
+    super(`worktree dependencies unavailable (${dependencyPath}) at ${worktreePath}: ${reason}`);
+    this.name = 'WorktreeDependencyPreparationError';
+  }
+}
+
+function bakedDependenciesMatch(repoTree: string, bakedTree: string): boolean {
+  try {
+    if (!existsSync(join(bakedTree, 'node_modules'))) return false;
+    if (!readFileSync(join(repoTree, 'bun.lock')).equals(readFileSync(join(bakedTree, 'bun.lock')))) return false;
+    const source = projectDepsManifest(JSON.parse(readFileSync(join(repoTree, 'package.json'), 'utf8')) as Record<string, unknown>);
+    const baked = projectDepsManifest(JSON.parse(readFileSync(join(bakedTree, 'package.json'), 'utf8')) as Record<string, unknown>);
+    return JSON.stringify(source) === JSON.stringify(baked);
+  } catch { return false; }
+}
+
+function prepareWorktreeDependencies(repoRoot: string, worktreePath: string, opts: CreateWorktreeOpts, deps: WorktreeAddDeps): void {
+  const fallbackRoot = opts.dependencyFallbackRoot?.trim() || GATE_DEPS_DIR;
+  const timeoutMs = opts.dependencyInstallTimeoutMs ?? WORKTREE_DEPENDENCY_INSTALL_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) throw new Error('dependencyInstallTimeoutMs must be a positive integer');
+  for (const tree of GATE_DEPS_TREES) {
+    const targetTree = join(worktreePath, tree);
+    const relativePath = tree === '.' ? 'node_modules' : 'apps/pwa/node_modules';
+    const target = join(worktreePath, relativePath);
+    const source = join(repoRoot, relativePath);
+    const fallbackTree = join(fallbackRoot, tree);
+    const fallback = join(fallbackTree, 'node_modules');
+    const report = (installed: boolean, ok: boolean, error: string | null, method: string): void => {
+      debug.log('git-fs.worktree', 'dependencies.prepared', {
+        worktreePath, path: relativePath, source, fallback, installed, ok, error, method,
+      }, ok ? undefined : { level: 'warn' });
+    };
+    if (existsSync(target)) { report(false, true, null, existsSync(source) ? 'source' : 'existing'); continue; }
+    try { if (lstatSync(target).isSymbolicLink()) unlinkSync(target); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+    // Plain git repositories without a Bun lockfile have no dependency contract.
+    if (!existsSync(join(targetTree, 'package.json')) || !existsSync(join(targetTree, 'bun.lock'))) {
+      report(false, true, null, 'not-required');
+      continue;
+    }
+    if (bakedDependenciesMatch(targetTree, fallbackTree)) {
+      try {
+        mkdirSync(dirname(target), { recursive: true });
+        symlinkSync(fallback, target, 'dir');
+        report(false, true, null, 'fallback');
+        continue;
+      } catch (error) {
+        debug.log('git-fs.worktree', 'dependencies.fallback-failed', { worktreePath, path: relativePath, error: String(error) }, { level: 'warn' });
+      }
+    }
+    let result: { status: number | null; stderr?: string | null; error?: Error };
+    try {
+      result = deps.installDependencies
+        ? deps.installDependencies(targetTree, timeoutMs)
+        : spawnSync('bun', ['install', '--frozen-lockfile'], { cwd: targetTree, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      report(true, false, reason, 'install');
+      throw new WorktreeDependencyPreparationError(worktreePath, relativePath, reason);
+    }
+    if (result.status === 0 && existsSync(target)) { report(true, true, null, 'install'); continue; }
+    const reason = (result.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT'
+      ? `install timed out after ${timeoutMs}ms`
+      : (result.stderr ?? result.error?.message ?? `install exited ${result.status}`).trim().slice(-4096) || `install exited ${result.status}`;
+    report(true, false, reason, 'install');
+    throw new WorktreeDependencyPreparationError(worktreePath, relativePath, reason);
+  }
+}
+
 export interface CreateWorktreeOpts {
   /** Absolute repo root (main checkout). */
   repoRoot: string;
@@ -361,6 +438,12 @@ export interface CreateWorktreeOpts {
    *  기록된 owner 와 **정확히 같을 때**만 더티를 재사용 거부 사유로 쓰지 않는다(그 dirt 는 그 런 자신의 산출).
    *  ⛔ 생략·공백이면 종전 동작: 더티는 `worktree-dirty` 로 거부한다. */
   currentOwner?: string;
+  /** Baked dependency root; defaults to the harness image tree. */
+  dependencyFallbackRoot?: string;
+  /** Pod child only: require dependencies before its tests. Other callers remain fail-soft. */
+  requireDependencies?: boolean;
+  /** Maximum install time for each missing dependency tree; default 600 seconds. */
+  dependencyInstallTimeoutMs?: number;
 }
 
 /** base 를 무엇으로 확정했는지 — **모름과 부재를 값으로 가른다.**
@@ -715,6 +798,7 @@ export function createWorktree(opts: CreateWorktreeOpts, deps: WorktreeAddDeps =
       debug.log('git-fs.worktree', 'add.branch-held-reused', { branch, worktreePath: branchHolder, owner: gate.owner }, { level: 'warn' });
       const reusedLinks = linkWorktreeDependencies(repoRoot, branchHolder);
       debug.log('git-fs.worktree', 'dependencies.linked', { branch, worktreePath: branchHolder, dependencyLinks: reusedLinks });
+      if (opts.requireDependencies) prepareWorktreeDependencies(repoRoot, branchHolder, opts, deps);
       const head = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: branchHolder, encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
       const headSha = (head.stdout ?? '').trim();
       if (head.status !== 0 || headSha.length === 0) {
@@ -809,6 +893,16 @@ export function createWorktree(opts: CreateWorktreeOpts, deps: WorktreeAddDeps =
   //   idempotent). fail-soft — 링크 실패해도 worktree 자체는 유효(caller 가 필요시 install).
   const dependencyLinks = linkWorktreeDependencies(repoRoot, wtPath);
   debug.log('git-fs.worktree', 'dependencies.linked', { branch, worktreePath: wtPath, dependencyLinks });
+  if (opts.requireDependencies) {
+    try { prepareWorktreeDependencies(repoRoot, wtPath, opts, deps); }
+    catch (error) {
+      try { removeWorktree(repoRoot, wtPath, true); }
+      catch (cleanupError) {
+        debug.log('git-fs.worktree', 'dependencies.cleanup-failed', { worktreePath: wtPath, error: String(cleanupError) }, { level: 'warn' });
+      }
+      throw error;
+    }
+  }
   const resolvedBase = spawnSync('git', ['rev-parse', 'HEAD'], {
     cwd: wtPath,
     encoding: 'utf8',

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

@@ -28,6 +28,24 @@ function findGraphFile(graphId: string): string | 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('wizard-run <request>')
+    .description('Run one request through the smart wizard graph and stop at its approval gate')
+    .option('--json', 'Print run identity and transitions as JSON')
+    .action(async (request: string, opts: { json?: boolean }) => {
+      try {
+        await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
+        const { runWizardRequest } = await import('../smart-wizard/run.js');
+        const result = await runWizardRequest(request);
+        const summary = { graphId: result.state.graphId, runId: result.runId, status: result.status,
+          path: result.path, transitions: result.transitions };
+        if (opts.json) await writeStdoutJson(JSON.stringify(summary) + '\n');
+        else console.log(`${summary.graphId} ${summary.runId}: ${summary.status} (${summary.path.join(' → ')})`);
+        if (result.status !== 'awaiting-approval' && result.status !== 'done') process.exitCode = 1;
+      } catch (error) {
+        console.error(`graph wizard-run: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+    });
   graph.command('run <file>')
     .option('--dry-run', 'Walk the success path without executing commands')
     .option('--json', 'Print run state as JSON')

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' },
@@ -266,6 +270,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 +798,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();
@@ -1070,7 +1079,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);

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,104 @@ 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));
+}
+
+export type GraphVariantDesignResult =
+  | { readonly status: 'composed'; readonly plan: GraphVariantPlan; readonly variant: Extract<GraphVariantResult, { ok: true }> }
+  | { readonly status: 'fallback-standard'; readonly template: GraphTemplateSpec; readonly reason: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** 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 { status: 'fallback-standard', template: input.template, reason };
+  }
+  const record = isRecord(raw) ? raw : null;
+  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 { status: 'fallback-standard', template: input.template, reason };
+  }
+  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 { status: 'fallback-standard', template: input.template, reason };
+  }
+  debug.log('graph.compose', 'composed', { goal: input.goal, overlayId: variant.overlay.overlayId, patches: variant.patches.length });
+  return { status: 'composed', plan, variant };
+}
+
 /** 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 +180,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 +223,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 +622,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 };
+}