elanous 0.2.34 → 0.2.36

package/src/graph-runner/runner.ts

@@ -1,7 +1,8 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { execFile, spawnSync } from 'node:child_process';
-import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { getElanousConfigDir, getElanousConfigDirOverride } from '../elanous-config-dir.js';
 import { debug } from '../debug/log.js';
@@ -23,8 +24,9 @@ export { UnitNotFoundError } from '../self-implement/graph-unit-resolver.js';
 import { createGraphVariant, type GraphVariantPlan } from '../self-implement/graph-variant.js';
 import { psProcessStartMs, START_TOLERANCE_MS } from '../harness/harness-stop.js';
 import { executeBashNode } from '../workflow-runtime/nodes/bash.js';
+import { executeClassifyNode } from '../workflow-runtime/nodes/classify.js';
 import { interpolate } from '../workflow-runtime/variables.js';
-import type { BashNode, NodeExecContext, WorkflowDeps } from '../workflow-runtime/types.js';
+import type { BashNode, ClassifyNode, NodeExecContext, NodeOutput, WorkflowDeps } from '../workflow-runtime/types.js';
 import { releaseResumeAcceptedRegressions, releaseResumeGateExecutor, releaseResumeGatePodPool, releaseResumeWaiver, type AcceptedRegression, type GateExecutorOverride, type GatePodPoolOverride } from '../../scripts/release-loop/resume.js';
 
 type BashRun = WorkflowDeps['runBash'];
@@ -36,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' },
@@ -46,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' },
@@ -83,6 +89,47 @@ function topLevelTerminalStatus(graphId: string, terminal: string): 'done' | 'fa
   return terminal === 'done' || terminal === 'failed' ? terminal : undefined;
 }
 
+/** HARNESS-FULL-GRAPH-LOOPS — the four goal loops are self-implement harness templates: their recipes are
+ *  catalog roles (no `recipes.yaml` sidecar) and some edges branch on `changed-files`. `graph run` can only
+ *  *plan* them: `--dry-run` walks the declared success route; a real run is refused (the harness owns effects). */
+const HARNESS_LOOP_GRAPH_IDS: ReadonlySet<string> = new Set(['default-loop', 'document-loop', 'operate-loop', 'research-loop']);
+
+type PlannedStep = { outcome?: string; to: string };
+
+/** Shortest declared route (map/to edges only — fallbacks are not a success branch) to a terminal that maps to `done`.
+ *  Ties keep the first declared outcome, so the plan follows the YAML's own order. A unit call only takes its first
+ *  declared exit (the same stand-in a plain dry run uses) — its `rework` exit is a shortcut, not the success path. */
+function planHarnessLoopRoute(graph: GraphTemplateSpec, unitSuccessExit: (nodeId: string) => string | undefined): Map<string, PlannedStep> {
+  const candidates = new Map<string, PlannedStep[]>();
+  for (const node of graph.nodes) {
+    const edge = graph.edges.find((e) => e.from === node.nodeId);
+    if (!edge) continue;
+    const exit = unitSuccessExit(node.nodeId);
+    candidates.set(node.nodeId, edge.to !== undefined ? [{ to: edge.to }]
+      : Object.entries(edge.map ?? {}).filter(([outcome]) => exit === undefined || outcome === exit).map(([outcome, to]) => ({ outcome, to })));
+  }
+  const distance = new Map<string, number>();
+  for (const terminal of graph.terminalNodes) if (topLevelTerminalStatus(graph.graphId, terminal) === 'done') distance.set(terminal, 0);
+  const route = new Map<string, PlannedStep>();
+  for (let changed = true; changed;) {
+    changed = false;
+    for (const [nodeId, steps] of candidates) {
+      if (graph.terminalNodes.includes(nodeId)) continue;
+      let best: { step: PlannedStep; d: number } | undefined;
+      for (const step of steps) {
+        const d = distance.get(step.to);
+        if (d !== undefined && (!best || d + 1 < best.d)) best = { step, d: d + 1 };
+      }
+      if (best && (distance.get(nodeId) ?? Infinity) > best.d) {
+        distance.set(nodeId, best.d);
+        route.set(nodeId, best.step);
+        changed = true;
+      }
+    }
+  }
+  return route;
+}
+
 export interface GraphRunState {
   graphId: string;
   runId: string;
@@ -125,6 +172,46 @@ export interface GraphRunState {
   statePath: string;
 }
 
+export interface GraphClassifyInput {
+  arguments: string;
+  classify: ClassifyNode['classify'];
+  /** Production consumer that asked for the verdict, so one ledger shape separates callers. */
+  caller?: string;
+}
+
+/** Run the workflow classifier as a persisted harness graph node. The workflow verdict is unchanged. */
+export async function runGraphClassifyNode(node: ClassifyNode, ctx: NodeExecContext, callLLM: WorkflowDeps['callLLM'],
+  meta: { caller?: string } = {}): Promise<NodeOutput> {
+  const dir = mkdtempSync(join(tmpdir(), 'elanous-graph-classify-'));
+  try {
+    const path = join(dir, 'graph.yaml');
+    writeFileSync(join(dir, 'recipes.yaml'), '{}\n');
+    writeFileSync(path, stringifyYaml({
+      graph_id: 'self-implement-classify', version: 1, entry_node: 'classify', terminal_nodes: ['done', 'failed'],
+      nodes: [
+        { node_id: 'classify', kind: 'classify', recipe: 'none', max_visits: 1 },
+        { node_id: 'done', kind: 'gate', recipe: 'none', max_visits: 1 },
+        { node_id: 'failed', kind: 'gate', recipe: 'none', max_visits: 1 },
+      ],
+      edges: [{ from: 'classify', on: 'outcome', map: { ok: 'done', fail: 'failed' } }],
+    }));
+    const run = await runGraph(path, { input: { arguments: ctx.arguments, classify: node.classify,
+      ...(meta.caller === undefined ? {} : { caller: meta.caller }) } satisfies GraphClassifyInput,
+      quiet: true,
+      deps: { callLLM: async (prompt) => callLLM({ prompt, ...(ctx.resolvedModel === undefined ? {} : { model: ctx.resolvedModel }),
+        ...(ctx.resolvedProvider === undefined ? {} : { provider: ctx.resolvedProvider }),
+        ...(ctx.signal === undefined ? {} : { signal: ctx.signal }) }) } });
+    const recorded = lastJsonObject(run.nodes[0]?.output);
+    if (!recorded || typeof recorded.durationMs !== 'number' || typeof recorded.ok !== 'boolean' || !('output' in recorded)) {
+      throw new Error(`classify graph did not record a result: ${run.statePath}`);
+    }
+    return { ok: recorded.ok, output: recorded.output, durationMs: recorded.durationMs,
+      ...(typeof recorded.error === 'string' ? { error: recorded.error } : {}) };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 export interface GraphRunOptions {
   input?: unknown;
   /** Bytes already checked by the tick gate, used for a current-graph start or legacy resume. */
@@ -135,6 +222,8 @@ export interface GraphRunOptions {
   resumeRunId?: string;
   resumeGraphId?: string;
   fromNodeId?: string;
+  /** Embedded runs (a classify verdict inside self-implement) keep the per-node `[graph]` stderr lines off the caller's terminal; debug.log still records every node. */
+  quiet?: boolean;
   /** Release-only: accept the recorded failed node without executing it, and expose its regression to known-issues. */
   releaseWaiver?: { nodeId: string; reason: string; requestedRegressions: AcceptedRegression[]; acceptedRegressions: AcceptedRegression[]; unmeasured?: string };
   /** Release-only: add accepted issues independently of a waiver at a restart boundary. */
@@ -181,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}`);
@@ -614,7 +717,15 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       throw new Error(`unsupported terminal node: ${terminal} (expected ${graph.unit ? graph.unit.exits.join(' or ') : 'done or failed'})`);
     }
   }
-  const recipeSource = readFileSync(graphMode === 'snapshot' ? join(snapshotDir!, 'recipes.yaml') : join(dirname(path), 'recipes.yaml'), 'utf8');
+  const recipePath = graphMode === 'snapshot' ? join(snapshotDir!, 'recipes.yaml') : join(dirname(path), 'recipes.yaml');
+  // A harness loop template without a command sidecar is planned, never executed, by this runner.
+  const harnessLoopTemplate = !graph.unit && HARNESS_LOOP_GRAPH_IDS.has(graph.graphId) && graphMode === 'current' && !existsSync(recipePath);
+  if (harnessLoopTemplate && (options.dryRun !== true || options.resumeRunId)) {
+    debug.log('graph.run', 'harness-loop-refused', { graphId: graph.graphId, path: resolve(path), why: 'real-run' });
+    throw new Error(`harness loop template ${graph.graphId} runs through the self-implement harness — graph run only plans it with --dry-run`);
+  }
+  const harnessLoopRoute = harnessLoopTemplate ? planHarnessLoopRoute(graph, (nodeId) => units.get(nodeId)?.template.unit?.exits[0]) : undefined;
+  const recipeSource = harnessLoopTemplate ? '{}\n' : readFileSync(recipePath, 'utf8');
   if (graphMode === 'snapshot' && saved?.graphSnapshot &&
     (createHash('sha256').update(source).digest('hex') !== saved.graphSnapshot.graphSha ||
       createHash('sha256').update(recipeSource).digest('hex') !== saved.graphSnapshot.recipesSha)) {
@@ -626,10 +737,20 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   const approvalSourceHash = createHash('sha256').update(variantSource).update('\0').update(recipeSource).digest('hex');
   // Resolve all commands before executing any node; an unknown recipe must never produce a partial publication.
   for (const node of graph.nodes) {
+    if (node.kind === 'classify' && node.recipe !== 'none') throw new Error(`classify node cannot execute a recipe: ${node.nodeId}`);
     if (node.recipe === 'none') continue;
     const resolved = resolveNodeRecipe(node, recipes, catalogRoles);
+    // Harness loop recipes are labels the self-implement harness dispatches by node id (most are outside the
+    // node catalog — graph-catalog.test.ts); a planned loop never executes them, and a real run is refused above.
+    if (harnessLoopRoute) continue;
     if (!resolved.command && !resolved.prompt && !resolved.approval) throw new Error(`unknown command recipe for ${node.nodeId}: ${node.recipe}`);
   }
+  if (harnessLoopRoute) {
+    if (!harnessLoopRoute.has(graph.entryNode)) throw new Error(`harness loop ${graph.graphId} has no declared route from ${graph.entryNode} to a success terminal`);
+    const planned: string[] = [graph.entryNode];
+    for (let at = harnessLoopRoute.get(graph.entryNode); at; at = harnessLoopRoute.get(at.to)) planned.push(at.to);
+    debug.log('graph.run', 'harness-loop-plan', { graphId: graph.graphId, path: resolve(path), route: planned });
+  }
   const graphId = safeSegment(graph.graphId);
   const isReleaseLoop = graphId === 'release-loop';
   // A copied or saved release graph is still a release graph. Its path cannot grant or revoke
@@ -677,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();
@@ -951,7 +1063,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     const startedAt = performance.now();
     const nodeStartedAt = new Date().toISOString();
     if (!resumingCompleted) state.currentNode = { nodeId: current, startedAt: nodeStartedAt };
-    console.error(`[graph] ${current} start (0.00s)`);
+    if (!options.quiet) console.error(`[graph] ${current} start (0.00s)`);
     debug.log('graph.run', 'node', { graphId, runId, nodeId: current, phase: 'start', dryRun: state.dryRun });
     publishInsideEvent({ kind: 'node', graphId, runId, nodeId: current, phase: 'start' });
     log('node-start', { graphId, runId, nodeId: current, visit: visits.get(current), dryRun: state.dryRun });
@@ -967,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);
@@ -1030,7 +1142,12 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       state.executed++;
     }
     let unitExecuted = false;
-    if (units.has(current) && !waiving && state.dryRun && !resumingCompleted) {
+    const plannedStep: PlannedStep | undefined = harnessLoopRoute?.get(current);
+    if (harnessLoopRoute && !graph.terminalNodes.includes(current)) {
+      if (!plannedStep) throw new Error(`harness loop ${graphId} has no declared success route from ${current}`);
+      // The planned outcome stands in for the harness node (or unit) that a real loop run would execute.
+      output = JSON.stringify({ outcome: plannedStep.outcome ?? 'ok', dryRun: true, plannedNext: plannedStep.to });
+    } else if (units.has(current) && !waiving && state.dryRun && !resumingCompleted) {
       // Dry run plans the walk only: no child run, no unit event, no unitCalls entry; the first declared exit stands in.
       output = JSON.stringify({ outcome: units.get(current)!.template.unit!.exits[0], dryRun: true });
     } else if (units.has(current) && !waiving && !resumingCompleted) {
@@ -1132,6 +1249,39 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       }
       state.executed++;
     }
+    if (node.kind === 'classify' && !waiving && !state.dryRun && !resumingCompleted) {
+      const input = state.input as GraphClassifyInput | undefined;
+      const classify = input?.classify;
+      if (!input || typeof input.arguments !== 'string' || !classify || typeof classify.input !== 'string' ||
+          !Array.isArray(classify.classes) || !classify.classes.length || !classify.classes.every(c => typeof c === 'string' && c.length > 0) ||
+          (classify.retries !== undefined && (!Number.isSafeInteger(classify.retries) || classify.retries < 0)) ||
+          (classify.retryDelayMs !== undefined && (!Number.isSafeInteger(classify.retryDelayMs) || classify.retryDelayMs < 0))) {
+        throw new Error('classify node requires input.arguments and a valid input.classify');
+      }
+      try {
+        const result = await executeClassifyNode({ id: current, classify }, {
+          arguments: input.arguments, artifactsDir: dirname(statePath), outputs: {},
+          resolvedProvider: undefined, resolvedModel: undefined, toolPolicy: {},
+        }, { callLLM: async ({ prompt }) => {
+          if (!options.deps?.callLLM) throw new Error('classify node requires an injected LLM (deps.callLLM)');
+          return options.deps.callLLM(prompt);
+        }, runBash: async () => ({ stdout: '', stderr: '', exitCode: 0 }) });
+        output = JSON.stringify({ input: input.arguments, ok: result.ok, verdict: result.output, output: result.output,
+          durationMs: result.durationMs, ...(result.error ? { error: result.error } : {}) });
+        ok = result.ok;
+        error = result.error;
+      } catch (cause) {
+        ok = false;
+        error = cause instanceof Error ? cause.message : String(cause);
+        output = JSON.stringify({ input: input.arguments, ok, verdict: 'unknown', output: 'unknown', durationMs: 0, error });
+      }
+      const recorded = lastJsonObject(output);
+      debug.log('graph.classify', 'node-result', { graphId, runId, nodeId: current, caller: input.caller ?? null,
+        input: input.arguments, inputChars: input.arguments.length, classes: classify.classes,
+        verdict: recorded?.verdict ?? 'unknown', output: recorded?.output ?? 'unknown', ok,
+        ...(error ? { error } : {}) });
+      state.executed++;
+    }
     const seconds = Number(((performance.now() - startedAt) / 1000).toFixed(2));
     // A wall clock stepped back mid-node must not record an end before the start.
     const nodeEndedAt = new Date(Math.max(Date.now(), Date.parse(nodeStartedAt))).toISOString();
@@ -1152,7 +1302,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
         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) || unitExecuted), ...((waiving || units.has(current) || ((command || prompt || approval) && (!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 } : {}),
         ...(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 });
@@ -1165,9 +1315,9 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       delete state.pending;
       delete state.approvalSourceHash;
     }
-    const reported = waiving || units.has(current) || (prompt && !state.dryRun) || (command && (!state.dryRun || command.dry_run_command)) ? lastJsonObject(resumingCompleted ? completed?.output : output)?.outcome : undefined;
-    const namedOutcome = typeof reported === 'string' ? reported : undefined;
-    console.error(`[graph] ${current} ${ok ? 'ok' : 'fail'} (${seconds.toFixed(2)}s)`);
+    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 });
     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 }) });
@@ -1225,7 +1375,9 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       }
       persist();
     }
-    current = nextNode(graph.edges, current, state.dryRun && !command?.dry_run_command ? 'ok' : ok ? 'ok' : 'fail', namedOutcome);
+    // A planned harness loop follows its route directly: `changed-files` edges have no runner condition.
+    current = plannedStep ? plannedStep.to
+      : nextNode(graph.edges, current, state.dryRun && !command?.dry_run_command ? 'ok' : ok ? 'ok' : 'fail', namedOutcome);
     resumedGrowth = false;
     if (current !== undefined) publishInsideEvent({ kind: 'edge', graphId, runId, from: fromNodeId, to: current });
     if (current === undefined) {

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/grok/credential.ts

@@ -87,6 +87,8 @@ export interface GrokCredential {
   baseUrl: string;
   /** Bearer 값. ⛔ 로그·관측에 실지 마라. */
   token: string;
+  /** Expiry for the selected subscription scope; absent for API-key credentials. */
+  expiresAt?: string | null;
   /** 이 자격에 «반드시» 붙어야 하는 헤더(Authorization 제외). */
   headers: Record<string, string>;
   /** 관측용 — 값이 아니라 «출처»만. */
@@ -120,8 +122,10 @@ function readSubscriptionToken(
   }
   if (!parsed || typeof parsed !== 'object') return null;
 
-  let best: { token: string; expiresAt: string | null; userId: string | null; ms: number } | null = null;
-  for (const scope of Object.values(parsed as Record<string, unknown>)) {
+  type SubscriptionToken = { token: string; expiresAt: string | null; userId: string | null; ms: number };
+  let best: SubscriptionToken | null = null;
+  let hqMirror: SubscriptionToken | null = null;
+  for (const [scopeName, scope] of Object.entries(parsed as Record<string, unknown>)) {
     if (!scope || typeof scope !== 'object') continue;
     const s = scope as GrokAuthScope;
     if (typeof s.key !== 'string' || s.key.length === 0) continue;
@@ -133,9 +137,11 @@ function readSubscriptionToken(
       userId: typeof s.user_id === 'string' ? s.user_id : null,
       ms: Number.isNaN(ms) ? Number.NEGATIVE_INFINITY : ms,
     };
+    if (scopeName === 'https://auth.x.ai::hq-mirror') hqMirror = cand;
     if (best === null || cand.ms > best.ms) best = cand;
   }
-  return best ? { token: best.token, expiresAt: best.expiresAt, userId: best.userId } : null;
+  const selected = hqMirror ?? best;
+  return selected ? { token: selected.token, expiresAt: selected.expiresAt, userId: selected.userId } : null;
 }
 
 /** 호스트 발급 문이 응답에 실을 access. user id 는 반환하지 않는다. */
@@ -302,6 +308,7 @@ function readGrokCredential(opts: {
         kind: 'subscription',
         baseUrl: GROK_SUBSCRIPTION_BASE_URL,
         token: sub.token,
+        expiresAt: sub.expiresAt,
         headers: grokSubscriptionHeaders({
           ...(opts.model ? { model: opts.model } : {}),
           userId: sub.userId,

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