elanous 0.2.32 → 0.2.35

package/src/graph-runner/runner.ts

@@ -1,8 +1,8 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { execFile } from 'node:child_process';
-import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { execFile, spawnSync } from 'node:child_process';
+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 { fileURLToPath } from 'node:url';
+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';
@@ -17,13 +17,17 @@ import { recordFailureEvent } from '../self-implement/heal-intake.js';
 import { growthApprovalRef, proposeGrowth, type GraphGrowth, type GrowthProposer, type GrowthRecipeEffect, type GrowthDecisionDeps, type GrowthCommand } from './graph-grow.js';
 import { DecisionLedger, type DecisionEntry } from '../decisions/decision-ledger.js';
 import { createLLMGrowthProposer } from './graph-grow-llm.js';
-import { parseGraphTemplateYaml, type GraphEdgeSpec, type GraphNodeSpec, type GraphTemplateSpec } from '../self-implement/graph-yaml.js';
+import { graphVersionHash, parseGraphTemplateYaml, type GraphEdgeSpec, type GraphNodeSpec, type GraphTemplateSpec } from '../self-implement/graph-yaml.js';
+import { createGraphUnitResolver, resolveGraphUnit, UnitNotFoundError, type ResolvedGraphUnit } from '../self-implement/graph-unit-resolver.js';
+import { flattenGraphUnits } from '../self-implement/graph-unit-flatten.js';
+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 { releaseResumeAcceptedRegressions, releaseResumeGateExecutor, releaseResumeWaiver, type AcceptedRegression, type GateExecutorOverride } from '../../scripts/release-loop/resume.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'];
 const DEFAULT_BASH_TIMEOUT_MS = 5 * 60 * 1_000;
@@ -67,6 +71,61 @@ function assertReleaseCommandBinding(node: GraphNodeSpec, command: string | unde
   }
 }
 
+const LOOP_TERMINAL_STATUS: Readonly<Record<string, Readonly<Record<string, 'done' | 'failed'>>>> = {
+  'ta-journey': { done: 'done', failed: 'failed', 'needs-human': 'failed', rework: 'failed' },
+  'default-loop': { landed: 'done', stopped: 'failed' },
+  'document-loop': { landed: 'done', 'document-blocked': 'failed', 'needs-human': 'failed' },
+  'operate-loop': { landed: 'done', 'operate-blocked': 'failed', 'needs-human': 'failed' },
+  'research-loop': { landed: 'done', 'needs-human': 'failed' },
+};
+
+function topLevelTerminalStatus(graphId: string, terminal: string): 'done' | 'failed' | undefined {
+  const aliases = Object.hasOwn(LOOP_TERMINAL_STATUS, graphId) ? LOOP_TERMINAL_STATUS[graphId] : undefined;
+  if (aliases) return Object.hasOwn(aliases, terminal) ? aliases[terminal] : undefined;
+  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;
@@ -77,6 +136,8 @@ export interface GraphRunState {
   activeNode?: { nodeId: string; pid: number; pidStartedAt: string };
   stoppedAt?: string;
   status: 'running' | 'done' | 'failed' | 'budget-exceeded' | 'awaiting-approval';
+  /** Original named terminal when status is its canonical done/failed mapping. */
+  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;
@@ -101,12 +162,52 @@ export interface GraphRunState {
   growthPark?: { from: string; outcome: string; reason: string; decisionId: string; decisionRef: string; growth: GraphGrowth; command?: GrowthCommand; approval?: string };
   resume?: { from: string; at: string; previousStatus: GraphRunState['status']; graph?: 'snapshot' | 'current' };
   /** GATE-HOST-EXECUTOR — every explicit input change a resume made (what was set and what it replaced), oldest first. */
-  inputOverrides?: GateExecutorOverride[];
+  inputOverrides?: Array<GateExecutorOverride | GatePodPoolOverride>;
   executed: number;
   dryRun: boolean;
   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. */
@@ -117,12 +218,16 @@ 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. */
   releaseAcceptedRegressions?: { requested: AcceptedRegression[]; acceptedRegressions: AcceptedRegression[] };
   /** Release-only (GATE-HOST-EXECUTOR): run the restarted gate on this executor — recorded in `inputOverrides`, never a waiver. */
   releaseGateExecutor?: { executor: string; host?: string };
+  /** Release-only (RESUME-GATE-POOL-OVERRIDE): replace the saved gate pool for this resumed gate. */
+  releaseGatePodPool?: string;
   useCurrentGraph?: boolean;
   /** Internal unit invocation context, propagated only by runGraph. */
   unitContext?: { parentRunId: string; ancestors: readonly string[]; remainingSteps: number; entryNodeId?: string };
@@ -132,9 +237,35 @@ export interface GraphRunOptions {
    * its own universe and lands in the tree-derived test universe while the run ledger is prod.
    */
   pinChildUniverse?: boolean;
+  /** Release resume: command checkout and cut tip, checked before every Bash dispatch. */
+  releaseCommandSource?: { root: string; cutTip: string; git?: (args: string[]) => string };
   deps?: { root?: string; runBash?: BashRun; callLLM?: (prompt: string) => Promise<string>; log?: (event: string, data: Record<string, unknown>) => void; beforeNode?: () => void; processStartMs?: (pid: number) => number | null; growthProposer?: GrowthProposer; growthLLM?: (prompt: string) => Promise<string>; classifyGrowthRecipe?: (node: GraphNodeSpec, resolved: { command?: string; approval?: string }) => GrowthRecipeEffect; growthDecision?: GrowthDecisionDeps & { list?: (filters: { status: 'all' }) => DecisionEntry[] } };
 }
 
+/** The command directory must itself be the checkout at the cut tip. */
+export function verifyReleaseCommandRoot(root: string, cutTip: string, git?: (args: string[]) => string): string {
+  let commandRoot: string;
+  try { commandRoot = realpathSync(root); }
+  catch { throw new Error(`release command root missing: ${root} — use --command-root <컷 tip checkout>`); }
+  const run = git ?? ((args: string[]): string => {
+    // git-spawn-allow: read-only checkout identity before release command dispatch.
+    // `git ls-files -v -z` exceeds Node's 1 MiB default in the 25k-path main checkout.
+    const result = spawnSync('git', args, { cwd: commandRoot, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0 || result.error) throw new Error(`release command root is not a git checkout: ${commandRoot} — use --command-root <컷 tip checkout>`);
+    return result.stdout.trim();
+  });
+  const head = run(['rev-parse', 'HEAD']);
+  // `status` can hide modified tracked code when assume-unchanged or skip-worktree is set.
+  // A release command checkout must not carry either index promise.
+  const hiddenTracked = run(['ls-files', '-v', '-z']).split('\0').find((entry) => entry && entry[0] !== 'H');
+  if (!/^[0-9a-f]{40}$/i.test(cutTip) || head.toLowerCase() !== cutTip.toLowerCase() ||
+      (!git && realpathSync(run(['rev-parse', '--show-toplevel'])) !== commandRoot) ||
+      hiddenTracked || run(['-c', 'status.showUntrackedFiles=all', 'status', '--porcelain', '--untracked-files=all'])) {
+    throw new Error(`release command root ${commandRoot}@${head.slice(0, 12)} differs from cut tip ${cutTip.slice(0, 12)} — use --command-root <컷 tip checkout>`);
+  }
+  return commandRoot;
+}
+
 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}`);
@@ -443,46 +574,22 @@ function nextNode(edges: readonly GraphEdgeSpec[], nodeId: string, exitOutcome:
   return edge.map?.[exitOutcome] ?? edge.fallback?.[0]?.node;
 }
 
-type ResolvedUnit = { path: string; template: GraphTemplateSpec; hash: string };
-
-export class UnitNotFoundError extends Error {
-  constructor(call: string) {
-    super(`unit not found: ${call}`);
-    this.name = 'UnitNotFoundError';
-  }
-}
+type ResolvedUnit = ResolvedGraphUnit;
+export const resolveUnit = resolveGraphUnit;
 
-export function resolveUnit(call: string, callerPath: string): ResolvedUnit {
-  const [id, requested] = call.split('@');
-  const repo = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
-  const directories = [join(dirname(callerPath), 'units'), dirname(callerPath), join(repo, 'graphs', 'units'), join(getElanousConfigDir(), 'graphs', 'units')];
-  for (const dir of directories) {
-    if (!existsSync(dir)) continue;
-    const matches = readdirSync(dir).filter(file => /\.ya?ml$/.test(file) && file !== 'recipes.yaml' && file !== 'recipes.yml').flatMap(file => {
-      const path = join(dir, file);
-      const source = readFileSync(path, 'utf8');
-      const header: unknown = parseYaml(source);
-      if (!header || typeof header !== 'object' || Array.isArray(header) || (header as Record<string, unknown>).graph_id !== id) return [];
-      const parsed = parseGraphTemplateYaml(source, path);
-      if (parsed.errors.length) throw new Error(parsed.errors.map(e => `${e.path}: ${e.message}`).join('\n'));
-      const template = parsed.template!;
-      return template.unit && (requested === String(template.version) || requested === `^${template.version}`)
-        ? [{ path, template, hash: createHash('sha256').update(source).digest('hex') }] : [];
-    });
-    if (matches.length > 1) throw new Error(`ambiguous unit: ${call}`);
-    if (matches.length) return matches[0]!;
-  }
-  throw new UnitNotFoundError(call);
+export function validateUnitCalls(graph: GraphTemplateSpec, path: string, ancestors: readonly string[] = [], onMissing?: (call: string) => void): Map<string, ResolvedUnit> {
+  return validateUnitCallsWithResolver(graph, path, ancestors, onMissing, createGraphUnitResolver());
 }
 
-export function validateUnitCalls(graph: GraphTemplateSpec, path: string, ancestors: readonly string[] = [], onMissing?: (call: string) => void): Map<string, ResolvedUnit> {
+function validateUnitCallsWithResolver(graph: GraphTemplateSpec, path: string, ancestors: readonly string[], onMissing: ((call: string) => void) | undefined,
+  resolve: typeof resolveGraphUnit): Map<string, ResolvedUnit> {
   if (ancestors.includes(graph.graphId)) throw new Error(`unit cycle: ${[...ancestors, graph.graphId].join(' -> ')}`);
   if (ancestors.length > 3) throw new Error('unit nesting exceeds depth 3');
   const result = new Map<string, ResolvedUnit>();
   for (const node of graph.nodes) {
     if (node.kind !== 'subgraph' || node.call === undefined) continue;
     let unit: ResolvedUnit;
-    try { unit = resolveUnit(node.call!, path); } catch (error) {
+    try { unit = resolve(node.call!, path); } catch (error) {
       if (error instanceof UnitNotFoundError && onMissing) { onMissing(node.call!); continue; }
       throw error;
     }
@@ -501,7 +608,7 @@ export function validateUnitCalls(graph: GraphTemplateSpec, path: string, ancest
       debug.log('graph.unit', 'contract-mismatch', { graphId: graph.graphId, nodeId: node.nodeId, call: node.call });
       throw new Error(`unit contract mismatch: ${node.nodeId} -> ${node.call}`);
     }
-    validateUnitCalls(unit.template, unit.path, [...ancestors, graph.graphId], onMissing);
+    validateUnitCallsWithResolver(unit.template, unit.path, [...ancestors, graph.graphId], onMissing, resolve);
     result.set(node.nodeId, unit);
   }
   return result;
@@ -515,6 +622,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   if (options.releaseWaiver && (!options.resumeRunId || options.fromNodeId !== options.releaseWaiver.nodeId)) throw new Error('release waiver requires --resume --from <waived node>');
   if (options.releaseAcceptedRegressions && (!options.resumeRunId || !options.fromNodeId || options.releaseWaiver)) throw new Error('accepted regressions require a release resume boundary');
   if (options.releaseGateExecutor && (!options.resumeRunId || !options.fromNodeId)) throw new Error('gate executor override requires a release resume boundary');
+  if (options.releaseGatePodPool !== undefined && (!options.resumeRunId || !options.fromNodeId)) throw new Error('gate pod pool override requires a release resume boundary');
   const root = options.deps?.root ?? effectiveInstanceRoot();
   const matchingRuns = options.resumeRunId && !options.resumeGraphId
     ? listGraphRuns(root).runs.filter((run) => run.runId === options.resumeRunId && run.graphPath === resolve(path)) : [];
@@ -547,7 +655,13 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   const variant = options.variant ? createGraphVariant({ template: graph, ...options.variant }) : undefined;
   if (variant && !variant.ok) throw new Error(`graph variant rejected: ${JSON.stringify(variant.rejections)}`);
   if (variant?.ok) graph = variant.template;
-  const units = validateUnitCalls(graph, path, options.unitContext?.ancestors);
+  const unitResolver = createGraphUnitResolver();
+  const units = validateUnitCallsWithResolver(graph, path, options.unitContext?.ancestors ?? [], undefined, unitResolver);
+  if (units.size > 0) {
+    const staticView = flattenGraphUnits(graph, path, unitResolver);
+    debug.log('graph.unit', 'static-view', { graphId: graph.graphId, hash: graphVersionHash(staticView),
+      nodeIds: staticView.nodes.map((node) => node.nodeId), edges: staticView.edges });
+  }
   const unitEntryNode = options.unitContext?.entryNodeId ?? saved?.entryNodeId ?? graph.entryNode;
   if (saved?.entryNodeId !== undefined && options.unitContext?.entryNodeId !== undefined && saved.entryNodeId !== options.unitContext.entryNodeId) {
     throw new Error('unit entry changed on resume');
@@ -579,11 +693,21 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     .flatMap(name => credentialStatus(name, pluginRoot).fields.map(field => field.env));
   const credentialFields = owner ? credentialStatus(owner.name, pluginRoot).fields.filter(field => field.set).map(field => field.name) : [];
   for (const terminal of graph.terminalNodes) {
-    if (terminal !== 'done' && terminal !== 'failed') {
-      throw new Error(`unsupported terminal node: ${terminal} (expected done or failed)`);
+    // Units use their declared exits. The four loop graphs also declare named
+    // top-level exits; all other graphs retain the done/failed contract.
+    if (!(graph.unit ? graph.unit.exits.includes(terminal) : topLevelTerminalStatus(graph.graphId, terminal) !== undefined)) {
+      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)) {
@@ -595,10 +719,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
@@ -636,6 +770,29 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       ...(options.input === undefined ? {} : { input: options.input }),
       ...(options.unitContext?.entryNodeId === undefined ? {} : { entryNodeId: options.unitContext.entryNodeId }),
       executed: 0, dryRun: options.dryRun === true, statePath };
+  const verifyReleaseSource = (): string | undefined => {
+    const source = options.releaseCommandSource;
+    if (!source) return undefined;
+    const savedCutTip = lastJsonObject(state.nodes.find((node) => node.nodeId === 'version-release')?.output)?.commit;
+    if (graphId !== 'release-loop' || !options.resumeRunId || typeof savedCutTip !== 'string' || source.cutTip !== savedCutTip) {
+      throw new Error('release command source differs from the saved cut tip');
+    }
+    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');
+    }
+    return commandRoot;
+  };
+  verifyReleaseSource();
   if (options.resumeRunId && graphMode === 'snapshot' && state.sourceHash && state.sourceHash !== approvalSourceHash) {
     throw new Error('graph snapshot changed since run started');
   }
@@ -728,6 +885,13 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       state.inputOverrides = [...(state.inputOverrides ?? []), override];
       debug.log('graph.runs', 'input-override', { graphId, runId, ...override });
     }
+    if (options.releaseGatePodPool !== undefined) {
+      if (graphId !== 'release-loop') throw new Error('gate pod pool override requires the release-loop graph');
+      const override = releaseResumeGatePodPool(state, { from: options.fromNodeId, pool: options.releaseGatePodPool });
+      state.input = { ...(state.input as Record<string, unknown>), ...override.set };
+      state.inputOverrides = [...(state.inputOverrides ?? []), override];
+      debug.log('graph.runs', 'input-override', { graphId, runId, ...override });
+    }
     if (state.unitCalls) {
       const calls = state.unitCalls;
       state.unitCalls = calls.filter(call => {
@@ -890,7 +1054,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 });
@@ -911,6 +1075,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       const redactCredentials = (text: string) => Object.values(credentials).filter(value => value.length > 0)
         .reduce((safe, value) => safe.replaceAll(value, '[REDACTED]'), text);
       const runBash: BashRun = async (body, opts) => {
+        const commandRoot = verifyReleaseSource();
         // Hash the actual /bin/bash argv after interpolation. Keep the command text (which may contain
         // credentials) out of logs, but leave enough to distinguish a replayed publish from npm/docs.
         const argvSha256 = createHash('sha256').update(JSON.stringify(['/bin/bash', '-c', body])).digest('hex');
@@ -929,7 +1094,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
           return true;
         });
         try {
-          const result = await execute(body, opts);
+          const result = await execute(body, commandRoot ? { ...opts, cwd: commandRoot } : opts);
           code = result.exitCode;
           return { ...result, stdout: redactCredentials(result.stdout), stderr: redactCredentials(result.stderr) };
         } finally {
@@ -968,7 +1133,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) {
@@ -978,9 +1148,13 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       for (const record of state.nodes) previous[record.nodeId] = lastJsonObject(record.output) ?? record.output;
       const supplied = state.input && typeof state.input === 'object' && !Array.isArray(state.input)
         ? state.input as Record<string, unknown> : {};
+      const lastPrior = state.nodes.at(-1);
+      const lastPriorOutput = lastPrior ? previous[lastPrior.nodeId] : undefined;
+      const priorResult = lastPriorOutput && typeof lastPriorOutput === 'object' && !Array.isArray(lastPriorOutput)
+        ? (lastPriorOutput as Record<string, unknown>).result : undefined;
       const inputs: Record<string, unknown> = Object.create(null);
       for (const key of contract.inputs) {
-        const value = Object.hasOwn(supplied, key) ? supplied[key] : previous[key];
+        const value = Object.hasOwn(supplied, key) ? supplied[key] : key === 'prior' ? priorResult : previous[key];
         if (value !== undefined) inputs[key] = value;
       }
       const alreadySpent = state.path.length + (state.unitCalls ?? []).reduce((sum, call) => sum + call.steps, 0);
@@ -1066,6 +1240,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();
@@ -1083,9 +1290,10 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     } else {
       // 승인 노드도 결과를 «값»으로 남긴다 — 뒤 노드가 문맥(outputs)에서 승인 여부를 확인할 수 있게(발행 노드가 승인 없이 돌지 않도록).
       if (approval && !state.dryRun && !command) {
-        output = JSON.stringify({ outcome: ok ? 'approved' : 'rejected', ...(state.pending?.decidedBy === undefined ? {} : { decidedBy: state.pending.decidedBy }), decidedAt: state.pending?.decidedAt ?? null });
+        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 });
@@ -1098,9 +1306,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 }) });
@@ -1111,7 +1319,10 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     }
     persist();
     if (graph.terminalNodes.includes(current)) {
-      state.status = current === 'failed' || !ok ? 'failed' : 'done';
+      state.status = !ok ? 'failed' : graph.unit ? (current === 'failed' ? 'failed' : 'done')
+        : topLevelTerminalStatus(graph.graphId, current)!;
+      if (!graph.unit && current !== 'done' && current !== 'failed') state.reason = current;
+      else delete state.reason;
       persist();
       if (state.status === 'failed' && !state.dryRun && graphId === 'release-loop') {
         recordReleaseRunFailure(state, root, `Graph ${graphId}/${runId} failed at ${current}`);
@@ -1155,7 +1366,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/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 는 반환하지 않는다. */
@@ -147,6 +153,11 @@ export function readGrokSubscriptionAccess(
   return { key: sub.token, expiresAt: sub.expiresAt };
 }
 
+/** Read only the selected subscription expiry for status/alert surfaces; never return token or account id. */
+export function readGrokSubscriptionExpiry(home?: string): string | null {
+  return readSubscriptionToken(grokAuthFilePath(home))?.expiresAt ?? null;
+}
+
 /** 프록시 필수 헤더. ⛔ `x-grok-client-version` 을 빼면 426 이다(실측). */
 export function grokSubscriptionHeaders(opts: {
   model?: string;
@@ -297,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,