elanous 0.2.23 → 0.2.24

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

@@ -155,11 +155,16 @@ export function registerGraphCommands(program: Command, runsDeps: { root?: strin
     .description('Advance one graph run, resuming a pending decision or starting only when requested')
     .option('--start', 'Start a new run when the graph is idle')
     .option('--schedule', 'Subscribe graph YAML triggers.schedule to the workflow scheduler and tick on each fire')
+    .option('--webhook', 'Subscribe graph YAML triggers.webhook to the workflow webhook router and tick on each request')
+    .option('--port <n>', 'Port for --webhook to listen on (default: any free port)')
     .option('--input <json>', 'JSON object passed to a newly started run')
     .option('--json', 'Print the tick result as JSON')
-    .action(async (file: string, opts: { start?: boolean; schedule?: boolean; input?: string; json?: boolean }) => {
+    .action(async (file: string, opts: { start?: boolean; schedule?: boolean; webhook?: boolean; port?: string; input?: string; json?: boolean }) => {
       try {
         if (opts.schedule && (opts.start || opts.input !== undefined || opts.json)) throw new Error('--schedule cannot be combined with --start, --input or --json');
+        if (opts.webhook && (opts.schedule || opts.start || opts.input !== undefined || opts.json)) throw new Error('--webhook cannot be combined with --schedule, --start, --input or --json');
+        if (opts.port !== undefined && !opts.webhook) throw new Error('--port requires --webhook');
+        if (opts.port !== undefined && (!/^\d+$/.test(opts.port) || Number(opts.port) > 65535)) throw new Error('--port must be an integer from 0 to 65535');
         if (opts.input !== undefined && !opts.start) throw new Error('--input requires --start');
         let input: Record<string, unknown> | undefined;
         if (opts.input !== undefined) {
@@ -171,6 +176,42 @@ export function registerGraphCommands(program: Command, runsDeps: { root?: strin
         }
         await (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink('graph');
         const { graphTick } = await import('./graph-tick.js');
+        if (opts.webhook) {
+          const { createWebhookSource } = await import('../workflow-runtime/triggers/webhook-source.js');
+          const graphFile = resolve(file);
+          const source = createWebhookSource();
+          // The CLI tick callback is the graph counterpart of the workflow webhook router's onEmit.
+          source.subscribeGraph(graphFile, async () => {
+            try {
+              const { notifyGraphEvents } = await import('./graph-notify.js');
+              const result = await graphTick(graphFile, { startIfIdle: true, deps: { notify: async () => { await notifyGraphEvents(); } } });
+              if (result.status === 'refused') return { ok: false, error: `refused: ${result.reason}` };
+              if (result.status === 'failed') return { ok: false, runId: result.runId, error: 'failed' };
+              return result.runId ? { ok: true, runId: result.runId } : { ok: false, error: `no run (${result.action})` };
+            } catch (error) {
+              debug.log('graph.runner', 'webhook-tick-failed', { file: graphFile, error: error instanceof Error ? error.message : String(error) });
+              return { ok: false, error: error instanceof Error ? error.message : String(error) };
+            }
+          });
+          if (!source.subscriptions().length) throw new Error('graph triggers.webhook is missing');
+          await source.start();
+          const server = Bun.serve({
+            hostname: '127.0.0.1',
+            port: opts.port === undefined ? 0 : Number(opts.port),
+            fetch: async (request) => {
+              const response = await source.dispatch({
+                method: request.method, path: new URL(request.url).pathname,
+                headers: Object.fromEntries(request.headers), body: await request.text(),
+              });
+              return response ? new Response(response.body, { status: response.status, headers: response.headers }) : new Response('webhook source not started', { status: 503 });
+            },
+          });
+          console.log(`graph webhook: ${source.subscriptions().length} active on http://127.0.0.1:${server.port}`);
+          const shutdown = () => { void server.stop(true).then(() => source.stop()).then(() => { process.exitCode = 0; }); };
+          process.once('SIGINT', shutdown);
+          process.once('SIGTERM', shutdown);
+          return;
+        }
         if (opts.schedule) {
           const { createScheduleSource } = await import('../workflow-runtime/triggers/schedule-source.js');
           const graphFile = resolve(file);

package/src/graph-runner/runner.ts

@@ -2,8 +2,9 @@ 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 { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-import { getElanousConfigDirOverride } from '../elanous-config-dir.js';
+import { getElanousConfigDir, getElanousConfigDirOverride } from '../elanous-config-dir.js';
 import { debug } from '../debug/log.js';
 import { observeModelInputTokens } from '../harness/model-input-observation.js';
 import { publishInsideEvent } from '../nexus/api/inside-events.js';
@@ -22,7 +23,7 @@ import { psProcessStartMs, START_TOLERANCE_MS } from '../harness/harness-stop.js
 import { executeBashNode } from '../workflow-runtime/nodes/bash.js';
 import { interpolate } from '../workflow-runtime/variables.js';
 import type { BashNode, NodeExecContext, WorkflowDeps } from '../workflow-runtime/types.js';
-import { releaseResumeAcceptedRegressions, releaseResumeWaiver, type AcceptedRegression } from '../../scripts/release-loop/resume.js';
+import { releaseResumeAcceptedRegressions, releaseResumeGateExecutor, releaseResumeWaiver, type AcceptedRegression, type GateExecutorOverride } from '../../scripts/release-loop/resume.js';
 
 type BashRun = WorkflowDeps['runBash'];
 
@@ -51,10 +52,14 @@ export interface GraphRunState {
   graphSnapshot?: { graphSha: string; recipesSha: string };
   graphPath?: string;
   variant?: { overlayId: string; goal: string; plan: GraphVariantPlan };
+  parentRunId?: string;
+  unitCalls?: Array<{ node: string; unit: string; version: number; hash: string; childRunId: string; exit: string; steps: number }>;
   growth?: GraphGrowth[];
   growthRejections?: Array<{ from: string; outcome: string; reason: string }>;
   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[];
   executed: number;
   dryRun: boolean;
   statePath: string;
@@ -74,7 +79,11 @@ export interface GraphRunOptions {
   releaseWaiver?: { nodeId: string; reason: string; requestedRegressions: AcceptedRegression[]; acceptedRegressions: AcceptedRegression[] };
   /** 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 };
   useCurrentGraph?: boolean;
+  /** Internal unit invocation context, propagated only by runGraph. */
+  unitContext?: { parentRunId: string; ancestors: readonly string[]; remainingSteps: number };
   /**
    * RELEASE-LEDGER-UNIVERSE — stamp every cmd: child with this run's ledger root (`ELANOUS_STATE_DIR`).
    * Without it a child launched from a non-leader tree (`bun scripts/...` with cwd = that tree) re-resolves
@@ -389,6 +398,55 @@ function nextNode(edges: readonly GraphEdgeSpec[], nodeId: string, exitOutcome:
   return edge.map?.[exitOutcome] ?? edge.fallback?.[0]?.node;
 }
 
+type ResolvedUnit = { path: string; template: GraphTemplateSpec; hash: string };
+
+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 Error(`unit not found: ${call}`);
+}
+
+function validateUnitCalls(graph: GraphTemplateSpec, path: string, ancestors: readonly string[] = []): 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;
+    const unit = resolveUnit(node.call!, path);
+    const contract = node.contract!;
+    const edge = graph.edges.find(e => e.from === node.nodeId);
+    if (!unit.template.unit || contract.inputs.length !== unit.template.unit.inputs.length ||
+        contract.inputs.some(key => !unit.template.unit!.inputs.includes(key)) ||
+        contract.outputs.length !== unit.template.unit.outputs.length ||
+        contract.outputs.some(key => !unit.template.unit!.outputs.includes(key)) || edge?.on !== 'outcome' ||
+        !edge.map || Object.keys(edge.map).length !== unit.template.unit.exits.length ||
+        unit.template.unit.exits.some(exit => !Object.hasOwn(edge.map!, exit))) {
+      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]);
+    result.set(node.nodeId, unit);
+  }
+  return result;
+}
+
 export async function runGraph(path: string, options: GraphRunOptions = {}): Promise<GraphRunState> {
   if (options.resumeRunId && options.runId) throw new Error('runId and resumeRunId cannot be combined');
   if (options.fromNodeId && !options.resumeRunId) throw new Error('--from requires --resume');
@@ -396,6 +454,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   if (options.variant && options.resumeRunId) throw new Error('variant cannot be combined with --resume');
   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');
   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)) : [];
@@ -428,6 +487,7 @@ 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 variantSource = variant?.ok ? stringifyYaml({ ...document,
     nodes: graph.nodes.map((node, index) => ({
       ...((document.nodes as Record<string, unknown>[])[index] ?? {}), node_id: node.nodeId, kind: node.kind,
@@ -506,6 +566,10 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   if (options.resumeRunId && state.growth?.length && graphMode === 'current' && state.sourceHash !== approvalSourceHash) {
     throw new Error('graph or recipes changed since grown run');
   }
+  if (options.unitContext) {
+    if (state.parentRunId !== undefined && state.parentRunId !== options.unitContext.parentRunId) throw new Error('unit parent run changed');
+    state.parentRunId = options.unitContext.parentRunId;
+  }
   if (state.growth?.length) graph = withGrowth(graph, state.growth);
   let waivedRecord: GraphRunState['nodes'][number] | undefined;
   if (options.fromNodeId) {
@@ -577,6 +641,22 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       state.input = { ...(state.input as Record<string, unknown>),
         acceptedRegressions: releaseResumeAcceptedRegressions(state, [], options.fromNodeId) };
     }
+    if (options.releaseGateExecutor) {
+      if (graphId !== 'release-loop') throw new Error('gate executor override requires the release-loop graph');
+      const override = releaseResumeGateExecutor(state, { from: options.fromNodeId, executor: options.releaseGateExecutor.executor, host: options.releaseGateExecutor.host });
+      const next: Record<string, unknown> = { ...(state.input as Record<string, unknown>), ...override.set };
+      for (const key of override.unset ?? []) delete next[key];
+      state.input = next;
+      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 => {
+        const keep = state.path.slice(0, from).filter(nodeId => nodeId === call.node).length;
+        return calls.filter(item => item.node === call.node).indexOf(call) < keep;
+      });
+    }
     state.path = state.path.slice(0, from);
     state.nodes = state.nodes.slice(0, from);
     state.executed = state.nodes.filter((node) => node.executed).length;
@@ -659,7 +739,11 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     if (state.status === 'done' || state.status === 'failed' || state.status === 'budget-exceeded') state.finishedAt ??= new Date().toISOString();
     persistOwnedRun(state, runnerOwner);
   };
-  const log = options.deps?.log ?? ((event: string, data: Record<string, unknown>) => debug.log('graph.runner', event, data));
+  const baseLog = options.deps?.log ?? ((event: string, data: Record<string, unknown>) => debug.log('graph.runner', event, data));
+  // RFC §U: every event of a unit (child) run carries its parentRunId.
+  const log = options.unitContext
+    ? (event: string, data: Record<string, unknown>) => baseLog(event, { ...data, parentRunId: options.unitContext!.parentRunId })
+    : baseLog;
   const visits = new Map<string, number>();
   for (const nodeId of state.path) visits.set(nodeId, (visits.get(nodeId) ?? 0) + 1);
   let current: string | undefined = options.fromNodeId ?? state.pending?.nodeId ?? state.path.at(-1) ?? graph.entryNode;
@@ -685,7 +769,9 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     const completed = state.nodes.at(-1);
     const resumingCompleted = options.resumeRunId !== undefined && !options.fromNodeId && completed?.nodeId === current &&
       state.path.at(-1) === current && !resumingPending;
-    if (!resumingPending && !resumingCompleted && (visits.get(current) ?? 0) >= node.maxVisits) {
+    const usedSteps = state.path.length + (state.unitCalls ?? []).reduce((sum, call) => sum + call.steps, 0);
+    if (!resumingPending && !resumingCompleted && ((visits.get(current) ?? 0) >= node.maxVisits ||
+        (options.unitContext && usedSteps >= options.unitContext.remainingSteps))) {
       state.status = 'budget-exceeded';
       log('budget-exceeded', { graphId, runId, nodeId: current });
       persist();
@@ -795,6 +881,81 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       error = result.error ? redactCredentials(result.error) : undefined;
       state.executed++;
     }
+    let unitExecuted = false;
+    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) {
+      const unit = units.get(current)!;
+      const contract = node.contract!;
+      const previous: Record<string, unknown> = Object.create(null);
+      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 inputs: Record<string, unknown> = Object.create(null);
+      for (const key of contract.inputs) {
+        const value = Object.hasOwn(supplied, key) ? supplied[key] : previous[key];
+        if (value !== undefined) inputs[key] = value;
+      }
+      const alreadySpent = state.path.length + (state.unitCalls ?? []).reduce((sum, call) => sum + call.steps, 0);
+      const remaining = options.unitContext ? options.unitContext.remainingSteps - alreadySpent : Infinity;
+      const childRunId = randomUUID();
+      const info = { graphId, runId, nodeId: current, unit: unit.template.graphId, childRunId, parentRunId: runId };
+      let entered = false;
+      try {
+        for (const key of contract.inputs) if (!Object.hasOwn(inputs, key)) throw new Error(`unit input missing: ${current}.${key}`);
+        if (createHash('sha256').update(readFileSync(unit.path, 'utf8')).digest('hex') !== unit.hash)
+          throw new Error(`unit source changed before call: ${current}`);
+        debug.log('graph.unit', 'enter', info);
+        log('graph.unit', { ...info, phase: 'enter' });
+        entered = true;
+        const child = await runGraph(unit.path, { runId: childRunId, input: inputs, dryRun: false,
+          pinChildUniverse: options.pinChildUniverse,
+          unitContext: { parentRunId: runId, ancestors: [...(options.unitContext?.ancestors ?? []), graphId],
+            remainingSteps: Math.min(node.budget!.innerSteps, remaining) }, deps: options.deps });
+        const steps = child.path.length + (child.unitCalls ?? []).reduce((sum, call) => sum + call.steps, 0);
+        const childExit = child.status === 'done' || child.status === 'failed' ? child.path.at(-1) : undefined;
+        // The last successful record carrying every contracted output is the source;
+        // intervening nodes (including terminal gates) need not reproduce those fields.
+        const values = child.nodes.reduce<Record<string, unknown> | undefined>((found, record) => {
+          if (!record.ok || !record.executed) return found;
+          const value = lastJsonObject(record.output) ??
+            (record.output && typeof record.output === 'object' && !Array.isArray(record.output)
+              ? record.output as Record<string, unknown> : undefined);
+          return value && contract.outputs.every(key => Object.hasOwn(value, key)) ? value : found;
+        }, undefined) ?? {};
+        state.unitCalls ??= [];
+        state.unitCalls.push({ node: current, unit: unit.template.graphId, version: unit.template.version,
+          hash: unit.hash, childRunId, exit: childExit ?? child.status, steps });
+        if (child.status === 'awaiting-approval') throw new Error(`unit cannot pause for approval: ${current}`);
+        if (child.status === 'budget-exceeded' || steps > node.budget!.innerSteps || steps > remaining) {
+          debug.log('graph.unit', 'budget-exhausted', { ...info, steps, innerSteps: node.budget!.innerSteps });
+          log('graph.unit', { ...info, phase: 'budget-exhausted', steps });
+          throw new Error(`unit inner_steps exceeded: ${current}`);
+        }
+        if (!childExit || !unit.template.unit!.exits.includes(childExit)) throw new Error(`unit exit missing: ${current}`);
+        if (child.status === 'done' && childExit === 'failed') throw new Error(`unit exit mismatch: ${current}`);
+        const result: Record<string, unknown> = { outcome: childExit };
+        for (const key of contract.outputs) {
+          if (!Object.hasOwn(values, key)) throw new Error(`unit output missing: ${current}.${key}`);
+          result[key] = values[key];
+        }
+        output = JSON.stringify(result);
+        ok = child.status === 'done';
+        debug.log('graph.unit', 'exit', { ...info, exit: childExit, steps });
+        log('graph.unit', { ...info, phase: 'exit', exit: childExit, steps });
+      } catch (cause) {
+        ok = false;
+        error = cause instanceof Error ? cause.message : String(cause);
+        if (entered) {
+          debug.log('graph.unit', 'exit', { ...info, error });
+          log('graph.unit', { ...info, phase: 'exit', error });
+        }
+      }
+      // A rejected invocation has no child ledger and did not execute a unit.
+      unitExecuted = existsSync(graphRunPath(unit.template.graphId, childRunId, root));
+      if (unitExecuted) state.executed++;
+    }
     if (prompt && !waiving && !state.dryRun && !resumingCompleted) {
       const outputs: Record<string, { ok: boolean; output: unknown; durationMs: number }> = Object.create(null);
       for (const previous of state.nodes) outputs[previous.nodeId] = { ok: previous.ok, output: lastJsonObject(previous.output) ?? previous.output ?? null, durationMs: 0 };
@@ -833,7 +994,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       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 });
       }
-      state.nodes.push({ nodeId: current, ok, exit, executed: !waiving && ((!!command && (!state.dryRun || !!command.dry_run_command)) || (!!prompt && !state.dryRun)), ...((waiving || ((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) || unitExecuted), ...((waiving || units.has(current) || ((command || prompt || approval) && (!state.dryRun || !!command?.dry_run_command))) && output !== undefined ? { output } : {}), ...(error ? { error } : {}),
         ...(waiving ? { waiver: { reason: options.releaseWaiver!.reason, at: nodeEndedAt, 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 });
@@ -842,7 +1003,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       delete state.pending;
       delete state.approvalSourceHash;
     }
-    const reported = waiving || (prompt && !state.dryRun) || (command && (!state.dryRun || command.dry_run_command)) ? lastJsonObject(resumingCompleted ? completed?.output : output)?.outcome : undefined;
+    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)`);
     debug.log('graph.run', 'node', { graphId, runId, nodeId: current, phase: ok ? 'ok' : 'fail', seconds, exit });

package/src/grok/usage.ts

@@ -182,13 +182,34 @@ export async function fetchGrokUsage(
   }
 }
 
-/** 이 조회는 구독 풀 잔량·리셋을 주지 않는다. 0·빈칸·미상과 다른 값. */
+/** 주간 사용률·리셋이 없거나 유효하지 않은 응답에서 구독 축이 제공되지 않음을 나타낸다. */
 export const GROK_SUBSCRIPTION_AXIS = {
   status: 'unavailable',
   reason: 'query-does-not-supply',
 } as const;
 
-/** 원본 크레딧 사용률·창·금액류 → 크레딧 축. ⛔ 구독 축으로 전용하지 않는다. */
+/** billing 쿼리가 주간 창과 사용률을 함께 돌려준 경우에만 실제 구독 잔량을 구성한다. */
+export function grokUsageToSubscriptionAxis(usage: GrokUsage):
+  | { readonly status: 'available'; readonly remainingPercent: number; readonly resetsAt: number; readonly windowKind: 'weekly' }
+  | typeof GROK_SUBSCRIPTION_AXIS {
+  const end = usage.periodEnd === null ? Number.NaN : Date.parse(usage.periodEnd);
+  if (
+    usage.periodType !== 'USAGE_PERIOD_TYPE_WEEKLY'
+    || usage.usedPercent === null
+    || !Number.isFinite(usage.usedPercent)
+    || usage.usedPercent < 0
+    || usage.usedPercent > 100
+    || !Number.isFinite(end)
+  ) return GROK_SUBSCRIPTION_AXIS;
+  return {
+    status: 'available',
+    remainingPercent: 100 - usage.usedPercent,
+    resetsAt: end,
+    windowKind: 'weekly',
+  };
+}
+
+/** 원본 크레딧 사용률·창·금액류 → 크레딧 축. ⛔ 크레딧 숫자만으로 구독 잔량을 만들지 않는다. */
 export function grokUsageToCreditAxis(usage: GrokUsage): {
   readonly status: 'ok';
   readonly usedPercent: number | null;

package/src/grounding/ref-index.ts

@@ -0,0 +1,253 @@
+// Reference card builder — L0 card + L1 listing for one local-repo / local-docs source.
+//
+// Pure value out: nothing is written. File access goes through the injected
+// `RefIndexFs`, and every read is capped (file count, bytes per file), so a
+// full file body is never loaded. Persistence (`grounding index` → jsonl) and
+// BM25 are deliberately not here — they are the next slice.
+
+import { spawnSync } from 'node:child_process';
+import { closeSync, openSync, readSync, readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { GroundingSourceError, type GroundingSource } from './sources.js';
+
+export interface RefIndexDirEntry {
+  name: string;
+  isDirectory: boolean;
+}
+
+export interface RefIndexFs {
+  /** Names directly under `dir`. Unreadable dir → empty list. */
+  readDir(dir: string): RefIndexDirEntry[];
+  /** At most `maxBytes` from the start of the file. `truncated` when the file is longer. */
+  readHead(file: string, maxBytes: number): { text: string; truncated: boolean } | undefined;
+  /** Modified time of a path, ms since epoch. */
+  mtimeMs(path: string): number | undefined;
+  /** Last commit time (ISO) of a git repo, when it has one. */
+  lastCommitAt(repoDir: string): string | undefined;
+}
+
+export interface RefIndexLimits {
+  /** Max markdown/readme/package files opened for one source. */
+  maxFiles: number;
+  /** Max bytes read from the head of any one file. */
+  maxBytesPerFile: number;
+}
+
+export const DEFAULT_REF_INDEX_LIMITS: RefIndexLimits = { maxFiles: 200, maxBytesPerFile: 16 * 1024 };
+
+const ONE_LINE_MAX = 200;
+const SKIP_DIRS = new Set(['node_modules']);
+
+export interface ReferenceTitle {
+  /** Path relative to the source root. */
+  file: string;
+  title: string;
+}
+
+export interface ReferenceCard {
+  /** L0 — `name` is the repository's own name (package.json `name`, else its directory name), not the registry `id`. */
+  id: string;
+  kind: GroundingSource['kind'];
+  name: string;
+  oneLine: string;
+  directories: string[];
+  receivedAt?: string;
+  /** L1 */
+  titles: ReferenceTitle[];
+  commands: string[];
+  /** A file-count or byte limit cut the read short — the lists may be incomplete. */
+  truncated: boolean;
+}
+
+export function buildReferenceCard(
+  source: GroundingSource,
+  fs: RefIndexFs,
+  limits: Partial<RefIndexLimits> = {},
+): ReferenceCard {
+  if ((source.kind !== 'local-repo' && source.kind !== 'local-docs') || !source.path) {
+    throw new GroundingSourceError(`reference card needs a local-repo/local-docs path: ${source.id}`);
+  }
+  const root = source.path;
+  // A missing root would otherwise yield an empty, untruncated card indistinguishable from an empty repo.
+  if (fs.mtimeMs(root) === undefined) {
+    throw new GroundingSourceError(`reference card source path is not readable: ${source.id} (${root})`);
+  }
+  const { maxFiles, maxBytesPerFile } = { ...DEFAULT_REF_INDEX_LIMITS, ...limits };
+  let opened = 0;
+  let truncated = false;
+
+  const open = (file: string): string | undefined => {
+    if (opened >= maxFiles) {
+      truncated = true;
+      return undefined;
+    }
+    opened += 1;
+    const head = fs.readHead(file, maxBytesPerFile);
+    if (!head) return undefined;
+    if (head.truncated) truncated = true;
+
+    return head.text;
+  };
+
+  const top = fs.readDir(root).sort((a, b) => a.name.localeCompare(b.name));
+  const directories = top
+    .filter((e) => e.isDirectory && !e.name.startsWith('.') && !SKIP_DIRS.has(e.name))
+    .map((e) => e.name);
+
+  const titles: ReferenceTitle[] = [];
+  const readme = top.find((e) => !e.isDirectory && /^readme(\.[a-z]+)?$/i.test(e.name));
+  let oneLine = '';
+  if (readme) {
+    const text = open(join(root, readme.name));
+    if (text !== undefined) {
+      oneLine = firstParagraphLine(text);
+      for (const title of headingTitles(text)) titles.push({ file: readme.name, title });
+    }
+  }
+
+  const docRoots = source.kind === 'local-docs' ? [''] : directories.includes('docs') ? ['docs'] : [];
+  for (const rel of docRoots) {
+    for (const file of markdownFiles(fs, root, rel, maxFiles + 2)) {
+      if (file === readme?.name) continue;
+      const text = open(join(root, file));
+      if (text === undefined) continue;
+      for (const title of headingTitles(text)) titles.push({ file, title });
+    }
+  }
+
+  const commands: string[] = [];
+  let packageName: string | undefined;
+  if (top.some((e) => !e.isDirectory && e.name === 'package.json')) {
+    const raw = open(join(root, 'package.json'));
+    if (raw !== undefined) {
+      const pkg = parsePackage(raw);
+      packageName = pkg.name;
+      commands.push(...pkg.commands);
+    }
+  }
+
+  const receivedAt = receivedAtOf(source, fs, root);
+  return {
+    id: source.id,
+    kind: source.kind,
+    name: packageName ?? basename(root),
+    oneLine,
+    directories,
+    ...(receivedAt ? { receivedAt } : {}),
+    titles,
+    commands,
+    truncated,
+  };
+}
+
+function receivedAtOf(source: GroundingSource, fs: RefIndexFs, root: string): string | undefined {
+  if (source.kind === 'local-repo') {
+    const commit = fs.lastCommitAt(root);
+    if (commit) return commit;
+  }
+  const mtime = fs.mtimeMs(root);
+  return mtime === undefined ? undefined : new Date(mtime).toISOString();
+}
+
+/**
+ * Markdown paths (relative to `root`) under `rel`, sorted. Directory listing only — no bodies.
+ * The walk stops once `cap` paths are found: past the file budget the caller only needs to know
+ * «there was more» (→ truncated), not the whole tree.
+ */
+function markdownFiles(fs: RefIndexFs, root: string, rel: string, cap: number): string[] {
+  const found: string[] = [];
+  const walk = (dirRel: string): void => {
+    if (found.length >= cap) return;
+    const entries = fs.readDir(dirRel ? join(root, dirRel) : root).sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      const childRel = dirRel ? join(dirRel, e.name) : e.name;
+      if (found.length >= cap) return;
+      if (e.isDirectory) {
+        if (!e.name.startsWith('.') && !SKIP_DIRS.has(e.name)) walk(childRel);
+      } else if (/\.md$/i.test(e.name)) {
+        found.push(childRel);
+      }
+    }
+  };
+  walk(rel);
+  return found;
+}
+
+function firstParagraphLine(text: string): string {
+  const lines: string[] = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line) {
+      if (lines.length > 0) break;
+      continue;
+    }
+    if (line.startsWith('#') || line.startsWith('![') || line.startsWith('[![') || line.startsWith('<') || line.startsWith('```')) {
+      if (lines.length > 0) break;
+      continue;
+    }
+    lines.push(line);
+  }
+  const joined = lines.join(' ');
+  return joined.length > ONE_LINE_MAX ? `${joined.slice(0, ONE_LINE_MAX - 1)}…` : joined;
+}
+
+function headingTitles(text: string): string[] {
+  const out: string[] = [];
+  let fenced = false;
+  for (const raw of text.split(/\r?\n/)) {
+    if (/^\s*(```|~~~)/.test(raw)) {
+      fenced = !fenced;
+      continue;
+    }
+    if (fenced) continue;
+    const m = /^#{1,6}\s+(.+?)(?:\s+#+)?\s*$/.exec(raw);
+    if (m?.[1]) out.push(m[1]);
+  }
+  return out;
+}
+
+function parsePackage(packageJson: string): { name?: string; commands: string[] } {
+  let pkg: unknown;
+  try { pkg = JSON.parse(packageJson); } catch { return { commands: [] }; }
+  if (!pkg || typeof pkg !== 'object') return { commands: [] };
+  const { bin, name } = pkg as { bin?: unknown; name?: unknown };
+  const pkgName = typeof name === 'string' && name.trim() ? name.trim() : undefined;
+  const base = pkgName ? { name: pkgName } : {};
+  if (typeof bin === 'string') return { ...base, commands: pkgName ? [pkgName.replace(/^@[^/]+\//, '')] : [] };
+  if (bin && typeof bin === 'object' && !Array.isArray(bin)) return { ...base, commands: Object.keys(bin).sort() };
+  return { ...base, commands: [] };
+}
+
+/** Real filesystem + local git. `git log` reads local refs only. */
+export const nodeRefIndexFs: RefIndexFs = {
+  readDir(dir) {
+    try {
+      return readdirSync(dir, { withFileTypes: true }).map((e) => ({ name: e.name, isDirectory: e.isDirectory() }));
+    } catch {
+      return [];
+    }
+  },
+  readHead(file, maxBytes) {
+    let fd: number | undefined;
+    try {
+      const size = statSync(file).size;
+      const length = Math.min(size, maxBytes);
+      const buf = Buffer.alloc(length);
+      fd = openSync(file, 'r');
+      readSync(fd, buf, 0, length, 0);
+      return { text: buf.toString('utf8'), truncated: size > maxBytes };
+    } catch {
+      return undefined;
+    } finally {
+      if (fd !== undefined) closeSync(fd);
+    }
+  },
+  mtimeMs(path) {
+    try { return statSync(path).mtimeMs; } catch { return undefined; }
+  },
+  lastCommitAt(repoDir) {
+    const result = spawnSync('git', ['-C', repoDir, 'log', '-1', '--format=%cI'], { encoding: 'utf8', timeout: 10_000 });
+    const out = result.status === 0 ? (result.stdout ?? '').trim() : '';
+    return out || undefined;
+  },
+};

package/src/harness/dispatch-backpressure.ts

@@ -36,7 +36,9 @@ const constants = { BUILD_STOP, BUILD_SLOW, QUEUE_STOP, QUEUE_SLOW, UNKNOWN_CAP
 const valid = (value: unknown): BackpressureSignal =>
   typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 'unknown';
 
-/** Fixed, reviewable thresholds; observations are normalized before any arithmetic. */
+/** Fixed, reviewable thresholds; observations are normalized before any arithmetic.
+ * Existing caller: the inline `.action(...)` callback registered by `queue.command('backpressure')` in src/harness/harness-cli-command.ts calls `decideBackpressure(signals, { maxPerCycle: opts.max === undefined ? 6 : Number(opts.max) })`.
+ */
 export function decideBackpressure(input: BackpressureSignals, { maxPerCycle = 6 }: { maxPerCycle?: number } = {}) {
   const max = Number.isSafeInteger(maxPerCycle) && maxPerCycle >= 0 ? maxPerCycle : 6;
   const signals: BackpressureSignals = {
@@ -81,7 +83,13 @@ export function decideBackpressure(input: BackpressureSignals, { maxPerCycle = 6
     budget = Math.min(budget, signals.queueDepth >= QUEUE_STOP ? 0 : Math.floor(max / 2));
     reasons.push('queue-depth');
   }
-  if (signals.staleParents !== 'unknown' && signals.staleParents > 0) reasons.push(`stale-parents:${signals.staleParents}`);
+  if (signals.staleParents !== 'unknown' && signals.staleParents > 0) {
+    reasons.push(`outdated-version-parents:${signals.staleParents} (legacy observation alias: stale-parents:${signals.staleParents}; 살아 있는 런 · 예산 안 깎음 · 낡은 부모 후보는 eln tasks parents)`);
+    // Co-occurrence only: staleParents is local ps, admitWaiting includes remote hosts — not proof that this parent is the one waiting.
+    if (signals.admitWaiting !== 'unknown' && signals.admitWaiting > 0) {
+      reasons.push('restart-stale-parent:approval-wait');
+    }
+  }
   return { launchBudget: Math.max(0, Math.min(max, Math.floor(budget))), reasons, signals, constants };
 }