elanous 0.2.23 → 0.2.25

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'];
 
@@ -40,7 +41,7 @@ export interface GraphRunState {
   /** 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;
     startedAt?: string; endedAt?: string; seconds?: number;
-    waiver?: { reason: string; at: string; original: { exit: number | null; output?: unknown; error?: string } } }>;
+    waiver?: { reason: string; at: string; /** RELEASE-WAIVE-UNMEASURED — why the waived gate had no verdict. */ unmeasured?: string; original: { exit: number | null; output?: unknown; error?: string } } }>;
   /** The node now running and when it started; cleared when its record is written. */
   currentNode?: { nodeId: string; startedAt: string };
   input?: unknown;
@@ -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;
@@ -71,10 +76,14 @@ export interface GraphRunOptions {
   resumeGraphId?: string;
   fromNodeId?: string;
   /** 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[] };
+  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 };
   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
@@ -349,6 +358,9 @@ export function decideGraphApproval(graphId: string, runId: string, decision: 'a
   return applyRecordedDecision(state);
 }
 
+/** The record `graph runs stop` writes for the node it cut (release resume reads it as an unmeasured gate). */
+export const STOPPED_NODE_ERROR = 'stopped before node completed';
+
 /** 노드 stdout 의 «마지막 비어 있지 않은 줄»이 JSON 객체면 그것을 구조 산출로 본다(아니면 없음). */
 export function lastJsonObject(stdout: unknown): Record<string, unknown> | undefined {
   if (typeof stdout !== 'string') return undefined;
@@ -389,6 +401,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 +457,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 +490,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 +569,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) {
@@ -547,7 +614,8 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     if (options.releaseWaiver) {
       if (graphId !== 'release-loop') throw new Error('release waiver requires the release-loop graph');
       const checked = releaseResumeWaiver(state, { from: options.fromNodeId, waive: options.releaseWaiver.nodeId, reason: options.releaseWaiver.reason, acceptedRegressions: options.releaseWaiver.requestedRegressions });
-      if (!checked || JSON.stringify(checked.acceptedRegressions) !== JSON.stringify(options.releaseWaiver.acceptedRegressions)) throw new Error('release waiver input changed before restart');
+      if (!checked || JSON.stringify(checked.acceptedRegressions) !== JSON.stringify(options.releaseWaiver.acceptedRegressions) ||
+        checked.unmeasured !== options.releaseWaiver.unmeasured) throw new Error('release waiver input changed before restart');
       const route = new Set<string>();
       let cursor: string | undefined = nextNode(graph.edges, options.fromNodeId, 'ok', 'ok');
       while (cursor && !route.has(cursor) && cursor !== 'known-issues') {
@@ -577,6 +645,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 +743,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 +773,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 +885,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,8 +998,8 @@ 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 } : {}),
-        ...(waiving ? { waiver: { reason: options.releaseWaiver!.reason, at: nodeEndedAt, original: { exit: waivedRecord!.exit, ...(waivedRecord!.output === undefined ? {} : { output: waivedRecord!.output }), ...(waivedRecord!.error === undefined ? {} : { error: waivedRecord!.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, ...(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 });
     }
@@ -842,7 +1007,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 });
@@ -999,7 +1164,7 @@ export function manageGraphRun(graphId: string, runId: string, action: 'stop' |
     // One stop instant for the node end, finishedAt and stoppedAt — never before the running node's start.
     const stopMs = running === undefined ? Date.now() : Math.max(Date.now(), Date.parse(running));
     if (state.path.length === state.nodes.length + 1) {
-      state.nodes.push({ nodeId: state.path.at(-1)!, ok: false, exit: null, executed: false, error: 'stopped before node completed',
+      state.nodes.push({ nodeId: state.path.at(-1)!, ok: false, exit: null, executed: false, error: STOPPED_NODE_ERROR,
         // The stop instant is always the node end; a start (and so seconds) exists only when the ledger named the running
         // node — a run begun by a runner before GRAPH-NODE-TIMES did not, and a guessed start would be a false time.
         endedAt: new Date(stopMs).toISOString(),

package/src/graph-wizard/archetypes.ts

@@ -2,18 +2,20 @@
  * 마법사 «원형» — 사람이 말로 자주 시키는 일의 뼈대 셋. graphs/** 의 운영 템플릿(개발·출시 루프)은
  * «모아서 요약해 보내기» 같은 말과 낱말이 안 겹쳐 엉뚱한 기반(lecture-note)을 골랐다(10-08 라이브 실측).
  * 원형은 기반 후보 «맨 앞»에 서고, 키워드가 겹치는 만큼 점수를 얻는다.
+ * 각 원형은 그래프 값어치 신호를 둘 이상 실린다(G1 검증 judge · G2 되돌림 간선 ⊕ max_visits ≥ 2 · G3 승인 hitl · G4 갈래) —
+ * 단순 나열은 스킬 사슬이지 그래프가 아니다(RFC SW-GRAPH-SMELL · generate.ts graphSignals 로 잰다).
  */
 export interface WizardArchetype { id: string; description: string; keywords: string[]; text: string }
 
 export const WIZARD_ARCHETYPES: readonly WizardArchetype[] = [
   {
     id: 'wizard-collect-summarize-send',
-    description: '모아서 요약해 보내기 — 검색·수집 → 요약 → 텔레그램/알림 발송 (브리핑·다이제스트·동향)',
+    description: '모아서 요약해 보내기 — 검색·수집 → 요약 → 출처 대조(판정·되돌림) → 텔레그램/알림 발송 (브리핑·다이제스트·동향)',
     keywords: ['뉴스', '모아', '수집', '검색', '찾아', '요약', '정리', '보내', '알려', '텔레그램', '브리핑', '동향', '소식', 'news', 'digest', 'summary'],
     text: `graph_id: wizard-collect-summarize-send
 loop:
   title: 모아서 요약해 보내기
-  description: 검색으로 모은 내용을 요약해 텔레그램으로 보낸다
+  description: 검색으로 모은 내용을 요약하고 출처와 대조해 텔레그램으로 보낸다
   trigger:
     cron: "0 8 * * *"
 version: 1
@@ -21,13 +23,15 @@ entry_node: collect
 terminal_nodes: [done, failed]
 nodes:
   - { node_id: collect, kind: agent, recipe: 'cmd:collect', max_visits: 1 }  # 수집 | web-search | 검색어
-  - { node_id: summarize, kind: agent, recipe: 'cmd:summarize', max_visits: 1 }  # 요약 | summarize | 핵심 5줄 한국어
+  - { node_id: summarize, kind: agent, recipe: 'cmd:summarize', max_visits: 2 }  # 요약 | summarize | 핵심 5줄 한국어
+  - { node_id: check, kind: judge, recipe: 'cmd:check', max_visits: 2 }  # 출처 대조 | check | 요약이 수집 결과와 일치하는가
   - { node_id: send, kind: agent, recipe: 'cmd:send', max_visits: 1 }  # 텔레그램 발송 | telegram-send
   - { node_id: done, kind: gate, recipe: none, max_visits: 1 }  # 완료
   - { node_id: failed, kind: gate, recipe: none, max_visits: 1 }  # 실패
 edges:
   - { from: collect, on: outcome, map: { ok: summarize, fail: failed } }
-  - { from: summarize, on: outcome, map: { ok: send, fail: failed } }
+  - { from: summarize, on: outcome, map: { ok: check, fail: failed } }
+  - { from: check, on: outcome, map: { ok: send, rework: summarize, fail: failed } }
   - { from: send, on: outcome, map: { ok: done, fail: failed } }
 `,
   },
@@ -60,12 +64,12 @@ edges:
   },
   {
     id: 'wizard-research-approve-publish',
-    description: '조사해 정리하고 승인 뒤 게시 — 조사 → 표/초안 정리 → 사람 승인 → 게시',
+    description: '조사해 정리하고 승인 뒤 게시 — 조사 → 표/초안 정리 → 출처 대조(판정·되돌림) → 사람 승인 → 게시',
     keywords: ['조사', '가격', '경쟁', '표', '정리', '승인', '올려', '게시', '노션', '초안', '블로그', '보고서'],
     text: `graph_id: wizard-research-approve-publish
 loop:
   title: 조사해 정리하고 승인 뒤 게시
-  description: 조사한 내용을 표로 정리하고 사람 승인 뒤 게시한다
+  description: 조사한 내용을 표로 정리하고 출처와 대조해 사람 승인 뒤 게시한다
   trigger:
     events: [manual]
 version: 1
@@ -73,14 +77,16 @@ entry_node: research
 terminal_nodes: [done, failed]
 nodes:
   - { node_id: research, kind: agent, recipe: 'cmd:research', max_visits: 1 }  # 조사 | web-search | 조사 주제
-  - { node_id: tabulate, kind: agent, recipe: 'cmd:tabulate', max_visits: 1 }  # 표로 정리 | llm | 결과를 마크다운 표로 정리
+  - { node_id: tabulate, kind: agent, recipe: 'cmd:tabulate', max_visits: 2 }  # 표로 정리 | llm | 결과를 마크다운 표로 정리
+  - { node_id: check, kind: judge, recipe: 'cmd:check', max_visits: 2 }  # 출처 대조 | check | 표가 조사 결과와 일치하는가
   - { node_id: approve, kind: hitl, recipe: 'approval:approve', max_visits: 1 }  # 게시 승인 | approval
   - { node_id: publish, kind: agent, recipe: 'cmd:publish', max_visits: 1 }  # 게시 | custom | 게시처에 올리기
   - { node_id: done, kind: gate, recipe: none, max_visits: 1 }  # 완료
   - { node_id: failed, kind: gate, recipe: none, max_visits: 1 }  # 실패
 edges:
   - { from: research, on: outcome, map: { ok: tabulate, fail: failed } }
-  - { from: tabulate, on: outcome, map: { ok: approve, fail: failed } }
+  - { from: tabulate, on: outcome, map: { ok: check, fail: failed } }
+  - { from: check, on: outcome, map: { ok: approve, rework: tabulate, fail: failed } }
   - { from: approve, on: outcome, map: { ok: publish, fail: failed } }
   - { from: publish, on: outcome, map: { ok: done, fail: failed } }
 `,

package/src/graph-wizard/generate.ts

@@ -52,6 +52,8 @@ export interface GraphWizardResult {
   recipes?: string;
   /** 실행 가능성 증명: 그 recipes 로 `graph run --dry-run` 을 걸어 본 결과. 하니스만. */
   dryRun?: { status: string; path: string[] };
+  /** 검증을 통과했지만 곁들인 경고(생성 실패 아님) — 예: «smell: linear-chain» 과 칸 내리기·유닛 끼우기 제안. */
+  warnings?: string[];
 }
 
 export interface GraphWizardDeps {
@@ -303,6 +305,74 @@ export function validateWizardYaml(kind: GraphKind, yaml: string): string[] {
   return issues;
 }
 
+/** 그래프 값어치 신호(RFC SW-GRAPH-SMELL · G1~G7) — 기계로 셀 수 있는 넷만 센다. */
+export interface GraphSignals {
+  /** G1 검증 노드 = kind judge|gate 비종단 노드의 결과 map 이 둘 이상으로 갈림 · G2 되돌림 루프 = 뒤로 가는 간선(이미 지난 노드로) ⊕ 그 노드 max_visits ≥ 2 · G3 승인 지점 = kind hitl 노드 · G4 갈래 = 비종단 노드의 결과 map 이 종단 아닌 서로 다른 둘 이상으로 갈림 */
+  counted: { G1: number; G2: number; G3: number; G4: number };
+  /** 못 셈 표시 — G5(재개)·G6(병렬)·G7(해상도). 0 으로 지어내지 않는다. */
+  notCounted: readonly ['G5', 'G6', 'G7'];
+  /** counted 넷의 합 — 둘 이상이면 그래프 값어치가 있다. */
+  total: number;
+}
+
+const GRAPH_SIGNALS_NOT_COUNTED = ['G5', 'G6', 'G7'] as const;
+
+/** 순수 함수 — YAML 텍스트만 받아 센다(LLM·파일·실행 0). 못 세는 신호는 0 으로 지어내지 않고 «못 셈»으로 둔다. */
+export function graphSignals(yaml: string): GraphSignals {
+  const counted = { G1: 0, G2: 0, G3: 0, G4: 0 };
+  const none = (): GraphSignals => ({ counted, notCounted: GRAPH_SIGNALS_NOT_COUNTED, total: 0 });
+  let doc: {
+    entry_node?: unknown; terminal_nodes?: unknown;
+    nodes?: Array<{ node_id?: unknown; kind?: unknown; max_visits?: unknown }>;
+    edges?: Array<{ from?: unknown; to?: unknown; map?: unknown }>;
+  } | null;
+  try { doc = parseYaml(yaml) as typeof doc; } catch { return none(); }
+  if (!doc) return none();
+  const nodes = (Array.isArray(doc.nodes) ? doc.nodes : []).filter((n) => n != null && typeof n.node_id === 'string');
+  const ids = new Set(nodes.map((n) => n.node_id as string));
+  const kindOf = new Map(nodes.map((n) => [n.node_id as string, typeof n.kind === 'string' ? n.kind : '']));
+  const visitsOf = new Map(nodes.map((n) => [n.node_id as string, Number(n.max_visits) || 0]));
+  const terminals = new Set((Array.isArray(doc.terminal_nodes) ? doc.terminal_nodes : []).map((t) => String(t)));
+  const targetsOf = new Map<string, Set<string>>();
+  for (const edge of Array.isArray(doc.edges) ? doc.edges : []) {
+    if (edge == null || typeof edge.from !== 'string' || !ids.has(edge.from)) continue;
+    const tos = typeof edge.to === 'string' ? [edge.to]
+      : edge.map && typeof edge.map === 'object'
+        ? Object.values(edge.map as Record<string, unknown>).filter((to): to is string => typeof to === 'string') : [];
+    const targets = targetsOf.get(edge.from) ?? new Set<string>();
+    for (const to of tos) if (ids.has(to)) targets.add(to);
+    if (targets.size > 0) targetsOf.set(edge.from, targets);
+  }
+  const entry = typeof doc.entry_node === 'string' && ids.has(doc.entry_node) ? doc.entry_node : undefined;
+  /** entry 에서 avoid 노드를 거치지 않고 닿는 노드들 = «이미 지난 노드»(avoid = 되돌림 간선의 출발 노드). entry 자신도 지난 노드로 센다. */
+  const passedBefore = (avoid?: string): ReadonlySet<string> => {
+    if (!entry) return new Set<string>();
+    const visited = new Set<string>([entry]);
+    const queue = [entry];
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      if (current === avoid) continue;
+      for (const to of targetsOf.get(current) ?? []) if (!visited.has(to)) { visited.add(to); queue.push(to); }
+    }
+    return visited;
+  };
+  for (const node of nodes) {
+    const id = node.node_id as string;
+    const targets = targetsOf.get(id) ?? new Set<string>();
+    if (kindOf.get(id) === 'hitl') counted.G3 += 1;
+    if (terminals.has(id)) continue;
+    if ((kindOf.get(id) === 'judge' || kindOf.get(id) === 'gate') && targets.size >= 2) counted.G1 += 1;
+    if ([...targets].filter((to) => !terminals.has(to)).length >= 2) counted.G4 += 1;
+  }
+  for (const [from, targets] of targetsOf) {
+    for (const to of targets) {
+      if (terminals.has(to) || (visitsOf.get(to) ?? 0) < 2) continue;
+      if (to === from ? passedBefore().has(from) : passedBefore(from).has(to)) counted.G2 += 1;
+    }
+  }
+  return { counted, notCounted: GRAPH_SIGNALS_NOT_COUNTED, total: counted.G1 + counted.G2 + counted.G3 + counted.G4 };
+}
+
 /** 노드 줄 끝 주석 `# 이름 | 단계 | 인자` 를 읽는다. 흐름식 노드 줄에서만. */
 export function parseNodeAnnotations(yaml: string): Record<string, WizardNodeStep> {
   const out: Record<string, WizardNodeStep> = {};
@@ -562,11 +632,17 @@ export async function generateGraphFromPrompt(req: GraphWizardRequest, deps: Gra
   }
   attempts = Math.min(attempts, maxAttempts);
   const ok = issues.length === 0;
+  // «선형 사슬» 냄새(SW-GRAPH-SMELL) — 경고만, 생성 실패가 아니다. 값어치 신호가 둘 이하면 칸 내리기·유닛 끼우기를 제안한다.
+  const warnings: string[] = [];
+  if (kind === 'harness' && ok) {
+    const signals = graphSignals(yaml);
+    if (signals.total <= 1) warnings.push(`smell: linear-chain — G 신호 ${signals.total} · 칸 내리기(스킬 사슬) 또는 유닛 끼우기(unit-verify = G1·G2 · 승인 노드 = G3) 제안`);
+  }
   const counted = summarizeChange(kind, editing ? req.currentYaml : undefined, yaml);
   const summary = llmSummary ? `${llmSummary} (${counted})` : counted;
   debug.log('graph.wizard', ok ? 'validated' : 'failed', { id, kind, base, attempts, editing, issues: issues.slice(0, 10), summary, dryRun: dryRun?.status, ms: Date.now() - startedAt });
   const labels = Object.fromEntries(Object.entries(steps).filter(([, v]) => v.label).map(([k, v]) => [k, v.label!]));
-  return { ok, id, yaml, ...(base ? { base } : {}), ...(base && baseReason ? { baseReason } : {}), issues, attempts, summary, labels, steps, ...(recipes ? { recipes } : {}), ...(dryRun ? { dryRun } : {}) };
+  return { ok, id, yaml, ...(base ? { base } : {}), ...(base && baseReason ? { baseReason } : {}), issues, attempts, summary, labels, steps, ...(recipes ? { recipes } : {}), ...(dryRun ? { dryRun } : {}), ...(warnings.length ? { warnings } : {}) };
 }
 
 /** v1 이름 유지 — 생성 YAML 의 노드 주석(단계·인자)으로 실제 recipes.yaml 을 낸다(v1 의 «미구현» 자리표시를 대체). */

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

@@ -14,7 +14,8 @@
 import type { GrokAnalysis, DiffResult, EnvDelta } from './types.js';
 import * as ui from './ui.js';
 import { getUserConfig } from './user-config.js';
-import { getProviderForConfig, anyProviderAvailable, textOnly, type LLMMessage } from './llm.js';
+import { getProviderForConfig, anyProviderAvailable, logAgentTurnUsage, type LLMMessage } from './llm.js';
+import type { LLMUsage } from './prompt-cache/types.js';
 
 /** True when any provider (env OR user-config, including Codex OAuth)
  *  can answer. Thin wrapper around llm.anyProviderAvailable() kept
@@ -34,19 +35,24 @@ async function callAnalyzer(prompt: string, systemPrompt?: string): Promise<stri
   if (systemPrompt) messages.push({ role: 'system', content: systemPrompt });
   messages.push({ role: 'user', content: prompt });
 
-  const events = provider.streamChat
-    ? provider.streamChat(messages, { temperature: 0.1, maxTokens: 1024 })
-    : null;
+  const llmOpts = { temperature: 0.1, maxTokens: 1024 };
   let text = '';
-  if (events) {
-    for await (const delta of textOnly(events)) text += delta;
+  let usage: LLMUsage = {};
+  if (provider.streamChat) {
+    for await (const ev of provider.streamChat(messages, llmOpts)) {
+      if (ev.type === 'text' && ev.delta) text += ev.delta;
+      else if (ev.type === 'usage') usage = { ...usage, ...ev.usage };
+    }
   } else {
     // Fallback to text-only chat (shouldn't happen — every provider
     // ships streamChat now).
-    for await (const chunk of provider.chat(messages, { temperature: 0.1, maxTokens: 1024 })) {
+    for await (const chunk of provider.chat(messages, llmOpts)) {
       text += chunk;
     }
   }
+  try {
+    logAgentTurnUsage(provider.defaultModel, usage, { providerName: provider.name, site: 'grok.direct' });
+  } catch { /* best-effort observation */ }
   return text;
 }