elanous 0.2.38 → 0.2.41

package/src/graph-runner/runner.ts

@@ -26,9 +26,10 @@ import { createGraphVariant, type GraphVariantPlan } from '../self-implement/gra
 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 { requireInProcessHandler, type InProcessHandlerRegistry } from './in-process-registry.js';
 import { interpolate } from '../workflow-runtime/variables.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';
+import { releaseResumeAcceptedRegressions, releaseResumeGateExecutor, releaseResumeGatePodPool, releaseResumeGateShardReroute, releaseResumeWaiver, type AcceptedRegression, type GateExecutorOverride, type GatePodPoolOverride, type GateShardRerouteOverride } from '../../scripts/release-loop/resume.js';
 
 type BashRun = WorkflowDeps['runBash'];
 const DEFAULT_BASH_TIMEOUT_MS = 5 * 60 * 1_000;
@@ -148,7 +149,8 @@ export interface GraphRunState {
   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; reason?: string; decidedBy?: string; decidedAt?: string;
+  nodes: Array<{ nodeId: string; ok: boolean; exit: number | null; executed: boolean; output?: unknown; error?: string; reason?: string;
+    failure?: { errorCode: string; message: string; stage: string }; decidedBy?: string; decidedAt?: string;
     startedAt?: string; endedAt?: string; seconds?: number;
     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. */
@@ -170,7 +172,7 @@ 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?: Array<GateExecutorOverride | GatePodPoolOverride>;
+  inputOverrides?: Array<GateExecutorOverride | GatePodPoolOverride | GateShardRerouteOverride>;
   executed: number;
   dryRun: boolean;
   statePath: string;
@@ -241,6 +243,8 @@ export interface GraphRunOptions {
   releaseGateExecutor?: { executor: string; host?: string };
   /** Release-only (RESUME-GATE-POOL-OVERRIDE): replace the saved gate pool for this resumed gate. */
   releaseGatePodPool?: string;
+  /** Release-only: remeasure a shard after the same-commit resume preflight. */
+  releaseGateShardReroute?: { shard: string; host?: string; os?: 'darwin' | 'linux' };
   useCurrentGraph?: boolean;
   /** Internal unit invocation context, propagated only by runGraph. */
   unitContext?: { parentRunId: string; ancestors: readonly string[]; remainingSteps: number; entryNodeId?: string };
@@ -254,7 +258,7 @@ export interface GraphRunOptions {
   releaseCommandSource?: { root: string; cutTip: string; git?: (args: string[]) => string };
   /** Optional per-run Bloom edge policy hook. */
   researchEdgeDecisionRegistry?: ResearchEdgeDecisionRegistry;
-  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[] } };
+  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[] }; inProcessHandlers?: InProcessHandlerRegistry };
 }
 
 /** The command directory must itself be the checkout at the cut tip. */
@@ -652,6 +656,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   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');
+  if (options.releaseGateShardReroute && (!options.resumeRunId || options.fromNodeId !== 'gate')) throw new Error('shard reroute requires release resume --from gate');
   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)) : [];
@@ -718,6 +723,8 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     return existsSync(graphsDir) && graphFile.startsWith(`${realpathSync(graphsDir)}${sep}`);
   });
   const credentials = owner ? pluginEnv(owner.name, pluginRoot) : {};
+  const redactCredentials = (text: string) => Object.values(credentials).filter(value => value.length > 0)
+    .reduce((safe, value) => safe.replaceAll(value, '[REDACTED]'), text);
   const declaredEnv = [...new Set(installed.map(item => item.name))]
     .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) : [];
@@ -750,6 +757,10 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
   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;
+    if (node.recipe.startsWith('handler:')) {
+      requireInProcessHandler(node.recipe, node.nodeId, options.deps?.inProcessHandlers);
+      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.
@@ -921,6 +932,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.releaseGateShardReroute) {
+      if (graphId !== 'release-loop') throw new Error('shard reroute requires the release-loop graph');
+      const override = releaseResumeGateShardReroute(state, { from: options.fromNodeId, ...options.releaseGateShardReroute });
+      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 => {
@@ -1094,6 +1112,31 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
     let commandFailureReason: string | undefined;
     let output: unknown;
     const waiving = options.releaseWaiver?.nodeId === current && waivedRecord !== undefined;
+    const inProcessHandler = requireInProcessHandler(node.recipe, current, options.deps?.inProcessHandlers);
+    let handlerExecuted = false;
+    if (inProcessHandler && !waiving && !state.dryRun && !resumingCompleted) {
+      const outputs: Record<string, unknown> = Object.create(null);
+      for (const previous of state.nodes) outputs[previous.nodeId] = lastJsonObject(previous.output) ?? previous.output ?? null;
+      handlerExecuted = true;
+      debug.log('graph.run', 'handler-dispatch', { graphId, runId, nodeId: current, recipe: node.recipe });
+      try {
+        const result = await inProcessHandler({ graphId, runId, nodeId: current, input: state.input ?? null, outputs });
+        if (!result || typeof result.ok !== 'boolean' || typeof result.outcome !== 'string' || !result.outcome.trim())
+          throw new Error(`invalid in-process handler result: ${current}`);
+        output = JSON.stringify({ ...(result.evidence === undefined ? {} : { evidence: result.evidence }), outcome: result.outcome });
+        ok = result.ok;
+        exit = ok ? 0 : 1;
+        error = result.error;
+      } catch (cause) {
+        ok = false;
+        exit = 1;
+        error = redactCredentials(cause instanceof Error ? cause.message : String(cause));
+        output = JSON.stringify({ outcome: 'fail', error });
+      }
+      debug.log('graph.run', 'handler-result', { graphId, runId, nodeId: current, recipe: node.recipe, ok,
+        outcome: lastJsonObject(output)?.outcome ?? null, ...(error ? { error } : {}) });
+      state.executed++;
+    }
     if (command && !waiving && (!approval || state.dryRun || ok) && (!state.dryRun || command.dry_run_command) && !resumingCompleted) {
       const outputs: Record<string, unknown> = Object.create(null);
       // 구조 산출(마지막 JSON 줄)이 있으면 그것을, 없으면 원문을 준다 — 다음 노드가 판단을 «값»으로 받는다.
@@ -1102,8 +1145,6 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       mkdirSync(dirname(contextPath), { recursive: true });
       writeFileSync(contextPath, JSON.stringify({ graphId, runId, startedAt: state.startedAt, nodeId: current, input: state.input ?? null, outputs }, null, 2) + '\n');
       let code: number | null = null;
-      const redactCredentials = (text: string) => Object.values(credentials).filter(value => value.length > 0)
-        .reduce((safe, value) => safe.replaceAll(value, '[REDACTED]'), text);
       const runBash: BashRun = async (body, opts) => {
         const commandRoot = verifyReleaseSource();
         // Hash the actual /bin/bash argv after interpolation. Keep the command text (which may contain
@@ -1243,7 +1284,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
         log('graph.unit', { ...info, phase: 'exit', exit: childExit, steps });
       } catch (cause) {
         ok = false;
-        error = cause instanceof Error ? cause.message : String(cause);
+        error = redactCredentials(cause instanceof Error ? cause.message : String(cause));
         if (entered) {
           debug.log('graph.unit', 'exit', { ...info, error });
           log('graph.unit', { ...info, phase: 'exit', error });
@@ -1326,7 +1367,16 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
         output = JSON.stringify({ outcome: ok ? 'approved' : 'rejected', graphId, runId, nodeId: current,
           ...(state.pending?.decidedBy === undefined ? {} : { decidedBy: state.pending.decidedBy }), decidedAt: state.pending?.decidedAt ?? null });
       }
-      state.nodes.push({ nodeId: current, ok, exit, executed: !waiving && ((!!command && (!state.dryRun || !!command.dry_run_command)) || (!!prompt && !state.dryRun) || (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 } : {}), ...(commandFailureReason ? { reason: commandFailureReason } : {}),
+      const failureMessage = !ok
+        ? redactCredentials(commandFailureReason ?? error ?? `Node ${current} failed without a diagnostic.`)
+        : undefined;
+      const failure = failureMessage === undefined ? undefined : {
+        errorCode: error?.startsWith('unit input missing:') ? 'GRAPH_UNIT_INPUT_MISSING' : 'GRAPH_NODE_FAILED',
+        message: failureMessage,
+        stage: units.has(current) ? 'unit-invocation' : command ? 'command-execution' : prompt ? 'prompt-execution' : 'node-execution',
+      };
+      state.nodes.push({ nodeId: current, ok, exit, executed: !waiving && (handlerExecuted || (!!command && (!state.dryRun || !!command.dry_run_command)) || (!!prompt && !state.dryRun) || (node.kind === 'classify' && !state.dryRun) || unitExecuted), ...((waiving || harnessLoopRoute || units.has(current) || handlerExecuted || ((command || prompt || approval || node.kind === 'classify') && (!state.dryRun || !!command?.dry_run_command))) && output !== undefined ? { output } : {}), ...(error ? { error } : {}),
+        ...(failure ? { reason: failure.message, failure } : {}), ...(commandFailureReason && !failure ? { reason: commandFailureReason } : {}),
         ...(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 });
@@ -1339,15 +1389,17 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
       delete state.pending;
       delete state.approvalSourceHash;
     }
-    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 reported: unknown = waiving || harnessLoopRoute || units.has(current) || handlerExecuted || (resumingCompleted && inProcessHandler) || (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)`);
+    const nodeFailure = state.nodes.at(-1)?.nodeId === current ? state.nodes.at(-1)?.failure : undefined;
+    const nodeReason = state.nodes.at(-1)?.nodeId === current ? state.nodes.at(-1)?.reason : undefined;
     debug.log('graph.run', 'node', { graphId, runId, nodeId: current, phase: ok ? 'ok' : 'fail', seconds, exit,
-      ...(commandFailureReason ? { reason: commandFailureReason } : {}) });
+      ...(nodeReason ? { reason: nodeReason } : {}), ...(nodeFailure ? { failure: nodeFailure } : {}) });
     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 }) });
     log('node-end', { graphId, runId, nodeId: current, ok, exit,
-      ...(commandFailureReason ? { reason: commandFailureReason } : {}),
+      ...(nodeReason ? { reason: nodeReason } : {}), ...(nodeFailure ? { failure: nodeFailure } : {}),
       ...(namedOutcome === undefined ? {} : { outcome: namedOutcome }), dryRun: state.dryRun });
     if (!resumingCompleted) {
       // Recipe commands expose stdout/exit but no provider usage; never infer zero from success.

package/src/graph-wizard/generate.ts

@@ -34,6 +34,8 @@ export interface GraphWizardRequest {
   history?: GraphWizardTurn[];
   /** Installed pack selected for a knowledge (RAG) node. */
   packId?: string;
+  /** Task hand composition: only existing verb units and terminal gates, never free-form commands. */
+  missionBase?: { id: string; text: string };
 }
 
 export interface GraphWizardResult {
@@ -653,6 +655,11 @@ function buildPrompt(input: {
   if (req.history?.length) {
     lines.push('', '지금까지의 대화:', ...req.history.slice(-10).map((t) => `${t.role === 'user' ? '사용자' : '마법사'}: ${t.text.slice(0, 500)}`));
   }
+  if (req.missionBase) {
+    lines.push('', '미션 조합: 기존 graphs/work 표준 조합의 동사 단위(subgraph call: verb-…@정수판)와 끝 gate 만 사용한다.',
+      'cmd·새 권한·외부 효과를 추가하지 마라. merge 앞에는 gate·freeze-check·review 가 모든 경로에서 먼저 와야 한다.',
+      `표준 조합 ${req.missionBase.id}:`, '```yaml', req.missionBase.text.trim(), '```');
+  }
   if (editing) {
     lines.push('', '지금 그래프(이것을 고친다 — 바뀌지 않는 노드의 id 는 그대로 둔다):', '```yaml', req.currentYaml!.trim(), '```',
       '', `사용자의 수정 지시: ${req.prompt}`,
@@ -705,7 +712,7 @@ export async function generateGraphFromPrompt(req: GraphWizardRequest, deps: Gra
   let id = editing ? currentId! : wizardGraphId(prompt, undefined, taken);
   const callLLM = deps.callLLM ?? defaultCallLLM;
   const maxAttempts = Math.max(1, deps.maxAttempts ?? GRAPH_WIZARD_MAX_ATTEMPTS);
-  let base = keywordBase?.id;
+  let base = req.missionBase?.id ?? keywordBase?.id;
   let yaml = '';
   let issues: string[] = [];
   let llmSummary: string | undefined;
@@ -726,7 +733,7 @@ export async function generateGraphFromPrompt(req: GraphWizardRequest, deps: Gra
     }
     if (attempts === 1 && !editing) {
       const picked = lineValue(text, 'BASE');
-      if (picked && picked !== base && templates.some((t) => t.id === picked)) { base = picked; baseReason = `LLM 재선택 (키워드 후보 ${keywordBase?.id ?? '-'})`; }
+      if (!req.missionBase && picked && picked !== base && templates.some((t) => t.id === picked)) { base = picked; baseReason = `LLM 재선택 (키워드 후보 ${keywordBase?.id ?? '-'})`; }
       const slug = lineValue(text, 'SLUG');
       if (slug && !currentId) id = wizardGraphId(prompt, slug, taken);
     }
@@ -746,13 +753,15 @@ export async function generateGraphFromPrompt(req: GraphWizardRequest, deps: Gra
     recipes = undefined;
     dryRun = undefined;
     if (kind === 'harness' && issues.length === 0) {
-      issues = stepIssues(yaml, steps);
+      if (!req.missionBase) issues = stepIssues(yaml, steps);
       const nodes = ((parseYaml(yaml) as { nodes?: Array<{ node_id?: unknown; recipe?: unknown }> }).nodes ?? [])
         .map((n) => ({ nodeId: String(n.node_id), recipe: typeof n.recipe === 'string' ? n.recipe : '' }));
-      recipes = recipesYamlFor(nodes, steps);
-      const walked = await dryRunWizardGraph(yaml, recipes);
-      dryRun = { status: walked.status, path: walked.path };
-      if (walked.status !== 'done') issues.push(`graph run --dry-run: ${walked.status}${walked.error ? ` — ${walked.error}` : ''} (경로 ${walked.path.join(' → ')})`);
+      if (!req.missionBase) {
+        recipes = recipesYamlFor(nodes, steps);
+        const walked = await dryRunWizardGraph(yaml, recipes);
+        dryRun = { status: walked.status, path: walked.path };
+        if (walked.status !== 'done') issues.push(`graph run --dry-run: ${walked.status}${walked.error ? ` — ${walked.error}` : ''} (경로 ${walked.path.join(' → ')})`);
+      }
     }
     debug.log('graph.wizard', 'attempt', { id, attempt: attempts, base, ok: issues.length === 0, issues: issues.slice(0, 10) });
     if (issues.length === 0) break;

package/src/graph-wizard/mission-compose.ts

@@ -0,0 +1,201 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { validateGraphYaml } from '../nexus/api/graph-kinds.js';
+import { edgeMapOf, parseGraphTemplateYaml, type GraphTemplateSpec } from '../self-implement/graph-yaml.js';
+import { resolveGraphUnit } from '../self-implement/graph-unit-resolver.js';
+import { inspectPipelineGraph } from '../self-implement/pipeline-shape.js';
+import { debug } from '../debug/log.js';
+import { generateGraphFromPrompt, type GraphWizardDeps } from './generate.js';
+import type { CompletionKind, CompositionSelection } from '../task-agent/task-hand.js';
+
+export interface MissionComposeInput {
+  text: string;
+  completion: CompletionKind;
+  root: string;
+  ledgerPath: string;
+  cardId: string;
+  standard: CompositionSelection;
+}
+
+/** The LLM may choose the order of existing verb calls, but not their authority or the hand's launcher. */
+export function missionGraphIssues(yaml: string, baseYaml: string, root: string, generatedPath?: string): string[] {
+  const checked = validateGraphYaml('harness', yaml);
+  const issues = checked.errors.map(error => typeof error === 'string' ? error : JSON.stringify(error));
+  const parsed = parseGraphTemplateYaml(yaml);
+  const base = parseGraphTemplateYaml(baseYaml);
+  issues.push(...parsed.errors.map(error => `${error.path}: ${error.message}`));
+  if (!parsed.template || !base.template) return issues;
+  const graph = parsed.template;
+  const standard = base.template;
+  const raw = parseYaml(yaml) as Record<string, unknown>;
+  const baseRaw = parseYaml(baseYaml) as Record<string, unknown>;
+  if (raw.launcher !== baseRaw.launcher) issues.push('I6: 표준 launcher 제어를 바꿀 수 없다');
+  for (const key of new Set([...Object.keys(baseRaw), ...Object.keys(raw)])) {
+    if (['graph_id', 'loop', 'nodes', 'edges'].includes(key)) continue;
+    if (JSON.stringify(raw[key]) !== JSON.stringify(baseRaw[key])) issues.push(`I6: 표준 제어 ${key} 변경 금지`);
+  }
+  if (raw.entry_node !== baseRaw.entry_node) issues.push('I6: 표준 진입 노드를 바꿀 수 없다');
+  if (JSON.stringify(raw.terminal_nodes) !== JSON.stringify(baseRaw.terminal_nodes)) issues.push('I4: 표준 종료 노드를 바꿀 수 없다');
+  const baseLoop = baseRaw.loop as { trigger?: unknown } | undefined;
+  const loop = raw.loop as { trigger?: unknown } | undefined;
+  if (JSON.stringify(loop?.trigger) !== JSON.stringify(baseLoop?.trigger)) issues.push('I6: 표준 트리거 변경 금지');
+  const rawNodes = Array.isArray(raw.nodes) ? raw.nodes as Array<Record<string, unknown>> : [];
+  const baseNodes = Array.isArray(baseRaw.nodes) ? baseRaw.nodes as Array<Record<string, unknown>> : [];
+  for (const node of rawNodes) {
+    const original = baseNodes.find(candidate => candidate.call && candidate.call === node.call)
+      ?? baseNodes.find(candidate => candidate.node_id === node.node_id && candidate.kind === 'gate');
+    if (!original) continue;
+    const keys = new Set([...Object.keys(node), ...Object.keys(original)]);
+    for (const key of keys) {
+      if (key === 'node_id' || key === 'max_visits') continue;
+      if (JSON.stringify(node[key]) !== JSON.stringify(original[key])) issues.push(`I6: ${String(node.node_id)} 권한 ${key} 변경 금지`);
+    }
+  }
+  const rawEdges = Array.isArray(raw.edges) ? raw.edges as Array<Record<string, unknown>> : [];
+  if (rawEdges.some(edge => Object.keys(edge).some(key => !['from', 'to', 'on', 'map'].includes(key))))
+    issues.push('I6: 간선 조건·폴백 권한 추가 금지');
+  const allowed = new Map(standard.nodes.filter(n => n.kind === 'subgraph' && n.call?.startsWith('verb-')).map(n => [n.call!, n]));
+  const standardById = new Map(standard.nodes.map(n => [n.nodeId, n]));
+  const seenCalls = new Set<string>();
+  for (const node of graph.nodes) {
+    const original = standardById.get(node.nodeId);
+    if (!original && /(?:merge|publish|send|pay|charge|deploy|release)/i.test(`${node.nodeId} ${node.call ?? ''}`))
+      issues.push(`I5: 외부 효과 동사 추가 금지 (${node.nodeId})`);
+    if (original?.kind === 'gate' && node.kind === 'gate'
+      && JSON.stringify(node) === JSON.stringify(original)) continue;
+    const known = node.kind === 'subgraph' && node.call ? allowed.get(node.call) : undefined;
+    if (!known || node.recipe !== 'none' || node.maxVisits > known.maxVisits
+      || JSON.stringify(node.contract) !== JSON.stringify(known.contract)
+      || JSON.stringify(node.budget) !== JSON.stringify(known.budget)
+      || node.skipWhen !== undefined || node.callEntry !== undefined)
+      issues.push(`권한 표: ${node.nodeId} 는 허용된 동사 단위가 아니다`);
+    if (node.call) seenCalls.add(node.call);
+  }
+  for (const call of allowed.keys()) if (!seenCalls.has(call)) issues.push(`권한 표: 표준 동사 단위 ${call} 누락`);
+  for (const required of standard.nodes.filter(n => n.kind === 'gate' || ['gate', 'freeze-check', 'review'].includes(n.nodeId))) {
+    if (!graph.nodes.some(n => n.nodeId === required.nodeId && JSON.stringify(n) === JSON.stringify(required))) issues.push(`권한 표: 보호 노드 ${required.nodeId} 누락 또는 변경`);
+  }
+  for (const terminal of standard.terminalNodes) if (!graph.terminalNodes.includes(terminal)) issues.push(`I4: 종료 ${terminal} 누락`);
+  const edges = edgeMapOf(graph);
+  issues.push(...inspectPipelineGraph(edges, graph.entryNode).map(defect => `I4: ${JSON.stringify(defect)}`));
+  for (const node of graph.nodes) {
+    const reachable = new Set<string>();
+    const queue = [node.nodeId];
+    while (queue.length) {
+      const id = queue.shift()!;
+      if (reachable.has(id)) continue;
+      reachable.add(id);
+      queue.push(...(edges[id] ?? []));
+    }
+    if (![...reachable].some(id => graph.terminalNodes.includes(id))) issues.push(`I4: ${node.nodeId} 에서 종료 불가`);
+  }
+  const mergeNodes = graph.nodes.filter(n => n.nodeId.includes('merge') || n.call?.includes('merge'));
+  for (const merge of mergeNodes) {
+    const prerequisites = ['gate', 'freeze-check', 'review'];
+    const walk = (id: string, seen: Set<string>, met: Set<string>): void => {
+      if (id === merge.nodeId) {
+        for (const required of prerequisites) if (!met.has(required)) issues.push(`I1~I3: merge 앞 ${required} 없음`);
+        return;
+      }
+      if (seen.has(id)) return;
+      const nextMet = new Set(met);
+      if (prerequisites.includes(id)) nextMet.add(id);
+      const nextSeen = new Set(seen).add(id);
+      for (const target of edges[id] ?? []) walk(target, nextSeen, nextMet);
+    };
+    walk(graph.entryNode, new Set(), new Set());
+  }
+  for (const node of graph.nodes.filter(n => n.kind === 'subgraph')) {
+    if (!node.call || !allowed.has(node.call)) continue;
+    try {
+      const canonical = resolveGraphUnit(node.call, join(root, 'graphs/work', 'generated.yaml'));
+      const actual = resolveGraphUnit(node.call, generatedPath ?? join(root, 'graphs/work', 'generated.yaml'));
+      const unit = actual.template;
+      if (actual.hash !== canonical.hash || `${unit.graphId}@${unit.version}` !== node.call || !unit.unit ||
+        JSON.stringify(unit.unit.inputs) !== JSON.stringify(node.contract?.inputs) ||
+        JSON.stringify(unit.unit.outputs) !== JSON.stringify(node.contract?.outputs)) issues.push(`권한 표: 동사 단위 미해석 ${node.call}`);
+    } catch { issues.push(`권한 표: 동사 단위 미해석 ${node.call}`); }
+  }
+  return [...new Set(issues)];
+}
+
+export async function composeMissionGraph(input: MissionComposeInput, deps: Pick<GraphWizardDeps, 'callLLM'> & { deferPersistence?: boolean } = {}): Promise<{
+  selection: CompositionSelection; reason: string; persist: () => void;
+}> {
+  const fallback = input.standard;
+  let files: string[] = [];
+  try { files = readdirSync(join(input.root, 'graphs/work')).filter(name => name.endsWith('.yaml') && name !== 'recipes.yaml'); }
+  catch { /* The fixed selection already carries the missing or unreadable-template reason. */ }
+  const candidates = files.flatMap(file => {
+    const path = join(input.root, 'graphs/work', file);
+    try {
+      const yaml = readFileSync(path, 'utf8');
+      const parsed = parseGraphTemplateYaml(yaml, path);
+      return parsed.template && !parsed.errors.length && (parseYaml(yaml) as { launcher?: unknown }).launcher
+        ? [{ file: `graphs/work/${file}`, yaml, template: parsed.template }] : [];
+    } catch { return []; }
+  });
+  const standardFile = fallback.composition?.file;
+  const words = input.text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+  const score = (item: { file: string; template: GraphTemplateSpec }) => {
+    const label = `${item.file} ${item.template.graphId} ${item.template.loop?.title ?? ''} ${item.template.loop?.description ?? ''}`.toLowerCase();
+    return words.reduce((total, word) => total + (word.length > 1 && label.includes(word) ? 1 : 0), 0);
+  };
+  const standardLauncher = standardFile ? candidates.find(item => item.file === standardFile) : undefined;
+  const compatible = candidates.filter(item => (parseYaml(item.yaml) as { launcher: unknown }).launcher ===
+    (standardLauncher ? (parseYaml(standardLauncher.yaml) as { launcher: unknown }).launcher : undefined)
+    && item.template.nodes.every(node => node.kind === 'gate' || node.kind === 'subgraph' && node.call?.startsWith('verb-')));
+  const base = compatible.sort((a, b) => score(b) - score(a) || Number(b.file === standardFile) - Number(a.file === standardFile))[0];
+  const prefix = base ? `문면 선택 ${base.file} (일치 ${score(base)})` : '표준 조합 없음';
+  let generated = '';
+  let issues: string[] = [];
+  let selection = fallback;
+  if (base && base.file !== standardFile && fallback.launcher === 'graph-run' && !fallback.error) {
+    const missingUnits: string[] = [];
+    const { validateUnitCalls } = await import('../graph-runner/runner.js');
+    try { validateUnitCalls(base.template, join(input.root, base.file), [], call => missingUnits.push(call)); }
+    catch (error) { issues.push(`표준 조합 단위 해석 오류: ${error instanceof Error ? error.message : String(error)}`); }
+    if (!issues.length && !missingUnits.length) selection = {
+      composition: { file: base.file, version: base.template.version }, launcher: 'graph-run', unitsResolved: true, missingUnits: [],
+    };
+    else if (missingUnits.length) issues.push(`표준 조합 단위 미해석: ${missingUnits.join(', ')}`);
+  }
+  if (base && selection.composition && !selection.error && !issues.length &&
+    (base.file === standardFile || selection.launcher === 'graph-run')) {
+    try {
+      const proposal = await generateGraphFromPrompt({ prompt: input.text, kind: 'harness', missionBase: { id: base.template.graphId, text: base.yaml } },
+        { callLLM: deps.callLLM, graphsDir: join(input.root, 'graphs'), existingIds: () => new Set(), maxAttempts: 1 });
+      generated = proposal.yaml;
+      const launcher = (parseYaml(base.yaml) as { launcher: string }).launcher;
+      if (!(parseYaml(generated) as { launcher?: unknown }).launcher)
+        generated = generated.replace(/^(graph_id:\s*[^\n]+\n)/, `$1launcher: ${launcher}\n`);
+      issues = missionGraphIssues(generated, base.yaml, input.root,
+        join(dirname(input.ledgerPath), `${input.cardId}.generated.yaml`));
+      if (!proposal.ok) issues.push(...proposal.issues);
+      if (launcher !== 'graph-run') issues.push('권한 표: harness-say 는 생성된 graph-run 조합으로 전환할 수 없다');
+      const directory = dirname(input.ledgerPath);
+      const recipePath = join(directory, 'recipes.yaml');
+      if (existsSync(recipePath) && readFileSync(recipePath, 'utf8') !== readFileSync(join(input.root, 'graphs/work/recipes.yaml'), 'utf8'))
+        issues.push('권한 표: 원장 옆 recipes.yaml 이 표준과 다르다');
+      if (!issues.length) {
+        const target = join(dirname(input.ledgerPath), `${input.cardId}.generated.yaml`);
+        selection = { composition: { file: target, version: parseGraphTemplateYaml(generated).template!.version },
+          launcher: launcher as 'graph-run' | 'harness-say', unitsResolved: true, missingUnits: [] };
+      }
+    } catch (error) { issues.push(`생성 실패: ${error instanceof Error ? error.message : String(error)}`); }
+  } else if (!issues.length) issues.push('표준 조합을 읽을 수 없다');
+  const reason = issues.length ? `${prefix} → fallback-standard: ${issues.join('; ')}` : `${prefix} → composed: 동사 단위 검증 통과`;
+  const persist = (): void => {
+    const directory = dirname(input.ledgerPath);
+    mkdirSync(directory, { recursive: true });
+    if (generated) writeFileSync(join(directory, `${input.cardId}.generated.yaml`), generated);
+    if (selection.composition?.file === join(directory, `${input.cardId}.generated.yaml`) && !existsSync(join(directory, 'recipes.yaml')))
+      writeFileSync(join(directory, 'recipes.yaml'), readFileSync(join(input.root, 'graphs/work/recipes.yaml'), 'utf8'), { flag: 'wx' });
+    writeFileSync(join(directory, `${input.cardId}.composition.json`), JSON.stringify({ base: base?.file ?? null,
+      selected: selection.composition?.file ?? null, reason, issues, generated: generated ? `${input.cardId}.generated.yaml` : null }));
+  };
+  if (!deps.deferPersistence) persist();
+  debug.log('graph.compose', issues.length ? 'fallback-standard' : 'composed', { card: input.cardId, base: base?.file ?? null, reason });
+  return { selection, reason, persist };
+}

package/src/grok/agent-search.ts

@@ -55,6 +55,9 @@ export interface GrokAgentSearchOpts {
   signal?: AbortSignal;
   fetchImpl?: FetchLike;
   apiKey?: string;
+  /** Subscription proxy endpoint and required CLI headers. Omit for the metered xAI API. */
+  baseUrl?: string;
+  headers?: Record<string, string>;
 }
 
 export interface GrokCitation {
@@ -106,10 +109,13 @@ export async function grokAgentSearch(
 
   let res: Response;
   try {
-    res = await fetchImpl(GROK_RESPONSES_URL, {
+    const endpoint = opts.baseUrl
+      ? `${opts.baseUrl.replace(/\/$/, '').replace(/\/responses$/, '')}/responses`
+      : GROK_RESPONSES_URL;
+    res = await fetchImpl(endpoint, {
       method: 'POST',
       signal: ac.signal,
-      headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}`, ...opts.headers },
       body: JSON.stringify({
         model,
         input,

package/src/grok/credential.ts

@@ -345,6 +345,11 @@ function readGrokCredential(opts: {
   return null;
 }
 
+/** Read-only credential check for synchronous provider availability. Never refreshes or calls the network. */
+export function peekGrokCredential(opts: { home?: string; model?: string } = {}): GrokCredential | null {
+  return readGrokCredential(opts);
+}
+
 export interface ResolveGrokCredentialOpts {
   env?: NodeJS.ProcessEnv;
   home?: string;

package/src/grounding/ref-index.ts

@@ -50,6 +50,8 @@ export interface ReferenceCard {
   kind: GroundingSource['kind'];
   name: string;
   oneLine: string;
+  /** Relative path that supplied oneLine, when a README was readable. */
+  oneLineFile?: string;
   directories: string[];
   receivedAt?: string;
   /** L1 */
@@ -57,6 +59,13 @@ export interface ReferenceCard {
   commands: string[];
   /** A file-count or byte limit cut the read short — the lists may be incomplete. */
   truncated: boolean;
+  /** Stable identity of this card inside the grounding orchestration log. */
+  orchestrationId: string;
+}
+
+/** Stable identity of this card inside the grounding orchestration log. */
+export function orchestrationId(kind: string, id: string): string {
+  return `grounding:${kind}:${id}`;
 }
 
 export function buildReferenceCard(
@@ -132,14 +141,35 @@ export function buildReferenceCard(
     kind: source.kind,
     name: packageName ?? basename(root),
     oneLine,
+    ...(oneLine && readme ? { oneLineFile: readme.name } : {}),
     directories,
     ...(receivedAt ? { receivedAt } : {}),
     titles,
     commands,
     truncated,
+    orchestrationId: orchestrationId(source.kind, source.id),
   };
 }
 
+/**
+ * Cards for a whole registry/discovery batch. Read-only: no writes anywhere.
+ * Non-local kinds and unreadable paths are skipped — one bad source must not
+ * sink the batch. Pure value out.
+ */
+export function buildReferenceCardsForRegistry(
+  sources: readonly GroundingSource[],
+  fs: RefIndexFs = nodeRefIndexFs,
+  limits: Partial<RefIndexLimits> = {},
+): ReferenceCard[] {
+  const cards: ReferenceCard[] = [];
+  for (const source of sources) {
+    if ((source.kind !== 'local-repo' && source.kind !== 'local-docs') || !source.path) continue;
+    if (fs.mtimeMs(source.path) === undefined) continue;
+    cards.push(buildReferenceCard(source, fs, limits));
+  }
+  return cards;
+}
+
 function receivedAtOf(source: GroundingSource, fs: RefIndexFs, root: string): string | undefined {
   if (source.kind === 'local-repo') {
     const commit = fs.lastCommitAt(root);

package/src/grounding/ref-vector.ts

@@ -0,0 +1,61 @@
+import type { Database } from 'bun:sqlite';
+import { chunkReport, hybridQueryKnowledge, ingestText, type EmbedFn, type HybridMatch } from '../domains/knowledge.js';
+import type { ReferenceCard } from './ref-index.js';
+
+export interface ReferenceIngestOptions {
+  embed: EmbedFn;
+  maxChunks?: number;
+}
+
+export interface ReferenceQueryOptions {
+  embed: EmbedFn;
+  k?: number;
+}
+
+/** Keep the source ID and a real relative file path together in each returned citation. */
+function sourceRef(id: string, file: string): string | null {
+  if (!id || !file || file.startsWith('/') || /^[a-zA-Z]:/.test(file) || file.split(/[\\/]/).some((part) => part === '..' || part === '.')) return null;
+  return `${id}#${file}`;
+}
+
+/** Index only card text whose original file is known; an invented README path must never become a citation. */
+export async function ingestReferenceCard(
+  db: Database,
+  card: ReferenceCard,
+  opts: ReferenceIngestOptions,
+): Promise<{ ingested: number; truncated: boolean }> {
+  const maxChunks = opts.maxChunks ?? 200;
+  if (!Number.isSafeInteger(maxChunks) || maxChunks < 0) throw new Error('reference maxChunks must be a nonnegative integer');
+  const entries: Array<{ file: string; text: string }> = [];
+  if (card.oneLine && card.oneLineFile) entries.push({ file: card.oneLineFile, text: card.oneLine });
+  for (const title of card.titles) entries.push({ file: title.file, text: title.title });
+  for (const command of card.commands) entries.push({ file: 'package.json', text: command });
+  const chunks = entries.flatMap(({ file, text }) => {
+    const ref = sourceRef(card.id, file);
+    return ref ? chunkReport(text).map((chunk) => ({ ref, text: chunk })) : [];
+  });
+  let ingested = 0;
+  const ts = card.receivedAt ?? new Date(0).toISOString();
+  for (const [index, chunk] of chunks.slice(0, maxChunks).entries()) {
+    if (await ingestText(db, {
+      id: `reference:${card.id}:${index}`,
+      ts,
+      kind: 'reference',
+      domain: 'elanous',
+      text: chunk.text,
+      source_ref: chunk.ref,
+    }, opts.embed)) ingested++;
+  }
+  return { ingested, truncated: card.truncated || chunks.length > maxChunks };
+}
+
+/** Reuse the knowledge hybrid ranker, but never return a result without a source link. */
+export async function queryReferences(
+  db: Database,
+  query: string,
+  opts: ReferenceQueryOptions,
+): Promise<HybridMatch[]> {
+  const k = Math.min(Math.max(opts.k ?? 5, 1), 20);
+  const matches = await hybridQueryKnowledge(db, query, { kind: 'reference', domain: 'elanous', k: 20, embed: opts.embed });
+  return matches.filter((match) => !!match.source_ref).slice(0, k);
+}