elanous 0.2.40 → 0.2.41

package/src/domains/guardian-tick.ts

@@ -1,12 +1,18 @@
 import type { Database } from 'bun:sqlite';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
 import { debug } from '../debug/log.js';
+import { withFileLockSync } from '../storage/file-lock.js';
 import { calendarFields, resolveTimeZone } from '../time/format.js';
 import { cronMatches } from './cron-match.js';
 import { listScheduleRuns } from './schedule-runs.js';
 import { listSchedules, openSchedulesDb, type ScheduleRow } from './schedule-registry.js';
 import type { SpawnOutcome } from './schedule-runner.js';
+import { classifyTcellHealthCards, type TcellHealthCard, type TcellHealthClassification } from '../harness/harness-incidents.js';
 
 export interface GuardianPlan {
   jobs: readonly (Pick<ScheduleRow, 'id' | 'cron' | 'enabled' | 'source' | 'run_via'> & Partial<Pick<ScheduleRow, 'command'>>)[];
@@ -21,9 +27,147 @@ export interface GuardianDeps {
   grokExpiry?: () => string | null;
   /** Injected in tests; production reevaluates recorded doctor visits without dispatching a prescription. */
   doctorShadow?: () => void | Promise<void>;
+  /** Read-only health-card source. T-cell classification remains shadow-only and never dispatches an action. */
+  readTcellHealthCards?: (now: Date) => readonly TcellHealthCard[] | Promise<readonly TcellHealthCard[]>;
+  /** Test-only path override; production uses the resolved state root. */
+  tcellDedupeStatePath?: string;
   hostName?: string;
 }
 
+type TcellPatrolSummary = Pick<TcellHealthClassification, 'total' | 'measured' | 'counts'> & { unmeasured: number };
+
+type TcellShadowMailTarget = 'doctor' | 'macrophage';
+interface TcellShadowMailProposal {
+  causeGroupId: string;
+  target: TcellShadowMailTarget;
+  reason: 'no-progress-30m' | 'risk-signal' | 'cause-quorum';
+  runIds: string[];
+  runIdsTruncated: boolean;
+  causeGroupSize: number;
+}
+
+const TCELL_SHADOW_DEDUPE_WINDOW_MS = 60 * 60_000;
+interface TcellShadowDedupeState {
+  version: 1;
+  lastProposedAt: Record<string, number>;
+}
+interface TcellShadowMailSuppression {
+  proposal: TcellShadowMailProposal;
+  lastProposedAt?: number;
+  eligibleAt?: number;
+  suppressionReason: 'hourly-dedupe' | 'dedupe-state-unavailable';
+}
+
+function tcellShadowDedupePath(): string {
+  return join(elanousStateRoot(), 'guardian', 'tcell-dedupe.json');
+}
+
+function loadTcellShadowDedupeState(path: string): TcellShadowDedupeState {
+  let raw: string;
+  try { raw = readFileSync(path, 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { version: 1, lastProposedAt: {} };
+    throw error;
+  }
+  const parsed: unknown = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('invalid T-cell dedupe state');
+  const record = parsed as Record<string, unknown>;
+  if (record.version !== 1 || !record.lastProposedAt || typeof record.lastProposedAt !== 'object' || Array.isArray(record.lastProposedAt)) {
+    throw new Error('invalid T-cell dedupe state shape');
+  }
+  const lastProposedAt: Record<string, number> = Object.create(null) as Record<string, number>;
+  for (const [causeGroupId, at] of Object.entries(record.lastProposedAt)) {
+    if (!causeGroupId || !Number.isSafeInteger(at) || (at as number) < 0) throw new Error('invalid T-cell dedupe timestamp');
+    lastProposedAt[causeGroupId] = at as number;
+  }
+  return { version: 1, lastProposedAt };
+}
+
+/** Reserve the per-cause hourly shadow proposal before logging it, so concurrent guardian ticks share the limit. */
+function reserveTcellShadowMail(proposals: readonly TcellShadowMailProposal[], nowMs: number, statePath?: string): {
+  proposed: TcellShadowMailProposal[];
+  suppressed: TcellShadowMailSuppression[];
+  stateError?: unknown;
+} {
+  if (proposals.length === 0) return { proposed: [], suppressed: [] };
+  const path = statePath ?? tcellShadowDedupePath();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    return withFileLockSync(`${path}.lock`, () => {
+      const state = loadTcellShadowDedupeState(path);
+      const lastProposedAt = Object.assign(Object.create(null) as Record<string, number>, state.lastProposedAt);
+      let changed = false;
+      for (const [causeGroupId, at] of Object.entries(lastProposedAt)) {
+        if (nowMs - at >= TCELL_SHADOW_DEDUPE_WINDOW_MS) {
+          delete lastProposedAt[causeGroupId];
+          changed = true;
+        }
+      }
+
+      const proposed: TcellShadowMailProposal[] = [];
+      const suppressed: TcellShadowMailSuppression[] = [];
+      for (const proposal of proposals) {
+        const last = lastProposedAt[proposal.causeGroupId];
+        if (last !== undefined && nowMs - last < TCELL_SHADOW_DEDUPE_WINDOW_MS) {
+          suppressed.push({ proposal, lastProposedAt: last, eligibleAt: last + TCELL_SHADOW_DEDUPE_WINDOW_MS,
+            suppressionReason: 'hourly-dedupe' });
+          continue;
+        }
+        lastProposedAt[proposal.causeGroupId] = nowMs;
+        changed = true;
+        proposed.push(proposal);
+      }
+
+      if (changed) {
+        const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+          writeFileSync(tmp, `${JSON.stringify({ version: 1, lastProposedAt }, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+          renameSync(tmp, path);
+        } finally {
+          try { unlinkSync(tmp); } catch { /* rename succeeded or temp was never created */ }
+        }
+      }
+      return { proposed, suppressed };
+    });
+  } catch (stateError) {
+    return { proposed: [], suppressed: proposals.map(proposal => ({ proposal, suppressionReason: 'dedupe-state-unavailable' })), stateError };
+  }
+}
+
+function proposeTcellShadowMail(classification: TcellHealthClassification): {
+  proposals: TcellShadowMailProposal[]; proposalsTruncated: number; missingCause: number;
+} {
+  const byCause = new Map<string, typeof classification.decisions>();
+  let missingCause = 0;
+  for (const decision of classification.decisions) {
+    if (decision.classification !== 'stalled' && decision.classification !== 'infected') continue;
+    if (!decision.causeGroupId || !decision.causeGroupSize) { missingCause++; continue; }
+    const group = byCause.get(decision.causeGroupId) ?? [];
+    group.push(decision);
+    byCause.set(decision.causeGroupId, group);
+  }
+
+  const proposals: TcellShadowMailProposal[] = [];
+  for (const [causeGroupId, decisions] of byCause) {
+    const infected = decisions.filter(decision => decision.classification === 'infected');
+    const selected = infected.length ? infected : decisions;
+    const first = selected[0]!;
+    const reason = infected.length
+      ? (infected.some(decision => decision.reason === 'cause-quorum') ? 'cause-quorum' : 'risk-signal')
+      : 'no-progress-30m';
+    const runIds = [...new Set(selected.map(decision => decision.runId))];
+    proposals.push({
+      causeGroupId,
+      target: infected.length ? 'macrophage' : 'doctor',
+      reason,
+      runIds: runIds.slice(0, 25),
+      runIdsTruncated: runIds.length > 25,
+      causeGroupSize: first.causeGroupSize!,
+    });
+  }
+  return { proposals: proposals.slice(0, 100), proposalsTruncated: Math.max(0, proposals.length - 100), missingCause };
+}
+
 export const GROK_EXPIRY_ALERT_WINDOW_MS = 4 * 60 * 60 * 1000;
 
 function durationLabel(ms: number): string {
@@ -85,7 +229,7 @@ function liveCommand(jobId: string, raw: string): string {
 }
 
 /** One five-minute guardian observation. No schedule state or crontab is mutated in shadow mode. */
-export async function guardianTick(now: Date, plan: GuardianPlan, deps: GuardianDeps = {}): Promise<{ mode: 'shadow' | 'live'; wouldRun: string[]; executed: number; credentialAlert?: string }> {
+export async function guardianTick(now: Date, plan: GuardianPlan, deps: GuardianDeps = {}): Promise<{ mode: 'shadow' | 'live'; wouldRun: string[]; executed: number; credentialAlert?: string; tcellPatrol?: TcellPatrolSummary }> {
   if (!Number.isFinite(now.getTime())) throw new RangeError('invalid tick time');
   const mode = deps.config?.guardian?.mode === 'live' ? 'live' : 'shadow';
   let expiryLine: string | null = null;
@@ -109,6 +253,51 @@ export async function guardianTick(now: Date, plan: GuardianPlan, deps: Guardian
       errorName: error instanceof Error ? error.name : 'unknown',
     });
   }
+  let tcellPatrol: TcellPatrolSummary | undefined;
+  if (deps.readTcellHealthCards) {
+    try {
+      const cards = await deps.readTcellHealthCards(now);
+      const classification = classifyTcellHealthCards(cards, now.getTime());
+      const shadowMail = proposeTcellShadowMail(classification);
+      const reservedMail = reserveTcellShadowMail(shadowMail.proposals, now.getTime(), deps.tcellDedupeStatePath);
+      tcellPatrol = { total: classification.total, measured: classification.measured,
+        unmeasured: classification.unmeasuredRunIds.length, counts: classification.counts };
+      // One bounded shadow observation per guardian tick. Cause signatures are represented only by a digest.
+      debug.log('guardian.tcell', 'shadow-classification', {
+        mode: 'shadow', ...tcellPatrol,
+        shadowMailProposed: reservedMail.proposed.length,
+        shadowMailSuppressed: reservedMail.suppressed.length,
+        shadowMailProposalsTruncated: shadowMail.proposalsTruncated,
+        shadowMailMissingCause: shadowMail.missingCause,
+        decisions: classification.decisions.slice(0, 100).map(({ runId, stage, classification: verdict, reason, causeGroupId, causeGroupSize }) => ({
+          runId, stage, classification: verdict, reason, ...(causeGroupId ? { causeGroupId, causeGroupSize } : {}),
+        })),
+        decisionsTruncated: classification.decisions.length > 100,
+      });
+      if (reservedMail.stateError) {
+        debug.log('guardian.tcell', 'shadow-mail-dedupe-unavailable', {
+          mode: 'shadow', errorName: reservedMail.stateError instanceof Error ? reservedMail.stateError.name : 'unknown',
+          suppressed: reservedMail.suppressed.length,
+        });
+      }
+      for (const suppressed of reservedMail.suppressed) {
+        debug.log('guardian.tcell', 'shadow-mail-suppressed', {
+          mode: 'shadow', ...suppressed.proposal, suppressionReason: suppressed.suppressionReason,
+          ...(suppressed.lastProposedAt !== undefined ? { lastProposedAt: suppressed.lastProposedAt } : {}),
+          ...(suppressed.eligibleAt !== undefined ? { eligibleAt: suppressed.eligibleAt } : {}),
+        });
+      }
+      for (const proposal of reservedMail.proposed) {
+        debug.log('guardian.tcell', 'shadow-mail-proposed', {
+          mode: 'shadow', recipientCandidate: 'OP', ownerRule: 'first-recipient-ack', ...proposal,
+        });
+      }
+    } catch (error) {
+      debug.log('guardian.tcell', 'observation-failed', {
+        mode: 'shadow', errorName: error instanceof Error ? error.name : 'unknown',
+      });
+    }
+  }
   const timeZone = plan.timeZone ?? resolveTimeZone().timeZone;
   const wouldRun: string[] = [];
   let executed = 0;
@@ -125,7 +314,7 @@ export async function guardianTick(now: Date, plan: GuardianPlan, deps: Guardian
       if (outcome.code !== 0) throw new Error(`guardian job ${job.id} exited ${outcome.code}`);
     }
   }
-  return { mode, wouldRun, executed, ...(expiryLine ? { credentialAlert: expiryLine } : {}) };
+  return { mode, wouldRun, executed, ...(expiryLine ? { credentialAlert: expiryLine } : {}), ...(tcellPatrol ? { tcellPatrol } : {}) };
 }
 
 export interface GuardianDayDeps {

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

@@ -258,10 +258,31 @@ export function registerGraphCommands(program: Command, runsDeps: { root?: strin
           const { createScheduleSource } = await import('../workflow-runtime/triggers/schedule-source.js');
           const graphFile = resolve(file);
           const source = createScheduleSource();
+          const graphDocument = parseYaml(readFileSync(graphFile, 'utf8')) as { graph_id?: string; loop?: { trigger?: { events?: string[] } } };
+          const cutEventSubscribed = graphDocument.graph_id === 'release-loop'
+            && graphDocument.loop?.trigger?.events?.includes('release.cut.due') === true;
           // The CLI tick callback is the graph counterpart of the workflow scheduler's onEmit.
           const onScheduledTick = async () => {
             try {
               const { notifyGraphEvents } = await import('./graph-notify.js');
+              if (cutEventSubscribed) {
+                const { emitDueReleaseCutEvents } = await import('../release-loop/release-schedule.js');
+                const { runUnattendedRelease } = await import('../../scripts/release-loop/unattended-release.js');
+                try {
+                  await emitDueReleaseCutEvents(new Date().toISOString(), async event => {
+                    const fired = await runUnattendedRelease({ version: event.version, triggerEvent: event });
+                    await notifyGraphEvents();
+                    if (fired.state?.status === 'failed') console.error(`graph tick: ${fired.state.runId}: failed`);
+                  });
+                } catch (error) {
+                  debug.log('graph.runner', 'cut-event-failed', { file: graphFile, error: error instanceof Error ? error.message : String(error) });
+                  console.error(`graph cut event: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                const resumed = await graphTick(graphFile, { deps: { notify: async () => { await notifyGraphEvents(); } } });
+                if (resumed.status === 'refused') console.error(`graph tick: refused: ${resumed.reason}`);
+                else if (resumed.status === 'failed') console.error(`graph tick: ${resumed.runId}: failed`);
+                return;
+              }
               const result = await graphTick(graphFile, { startIfIdle: true, deps: { notify: async () => { await notifyGraphEvents(); } } });
               if (result.status === 'refused') console.error(`graph tick: refused: ${result.reason}`);
               else if (result.status === 'failed') console.error(`graph tick: ${result.runId}: failed`);

package/src/graph-runner/in-process-registry.ts

@@ -0,0 +1,37 @@
+/** A run-scoped registry keeps in-process graph effects out of YAML and shell recipes. */
+export interface InProcessHandlerContext {
+  readonly graphId: string;
+  readonly runId: string;
+  readonly nodeId: string;
+  readonly input: unknown;
+  readonly outputs: Readonly<Record<string, unknown>>;
+}
+
+export interface InProcessHandlerResult {
+  readonly ok: boolean;
+  /** Named edge outcome from the graph's declared map. */
+  readonly outcome: string;
+  readonly evidence?: Readonly<Record<string, unknown>>;
+  readonly error?: string;
+}
+
+export type InProcessHandler = (context: InProcessHandlerContext) =>
+  InProcessHandlerResult | Promise<InProcessHandlerResult>;
+
+export type InProcessHandlerRegistry = Readonly<Record<string, InProcessHandler>>;
+
+function inProcessHandlerName(recipe: string): string | undefined {
+  if (!recipe.startsWith('handler:')) return undefined;
+  const name = recipe.slice('handler:'.length);
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) throw new Error(`invalid in-process handler recipe: ${recipe}`);
+  return name;
+}
+
+export function requireInProcessHandler(recipe: string, nodeId: string,
+  registry: InProcessHandlerRegistry | undefined): InProcessHandler | undefined {
+  const name = inProcessHandlerName(recipe);
+  if (name === undefined) return undefined;
+  const handler = registry && Object.hasOwn(registry, name) ? registry[name] : undefined;
+  if (typeof handler !== 'function') throw new Error(`unknown in-process handler for ${nodeId}: ${name}`);
+  return handler;
+}

package/src/graph-runner/runner.ts

@@ -26,6 +26,7 @@ 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, releaseResumeGateShardReroute, releaseResumeWaiver, type AcceptedRegression, type GateExecutorOverride, type GatePodPoolOverride, type GateShardRerouteOverride } from '../../scripts/release-loop/resume.js';
@@ -257,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. */
@@ -756,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.
@@ -1107,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 줄)이 있으면 그것을, 없으면 원문을 준다 — 다음 노드가 판단을 «값»으로 받는다.
@@ -1345,7 +1375,7 @@ export async function runGraph(path: string, options: GraphRunOptions = {}): Pro
         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 && ((!!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 } : {}),
+      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 } : {}),
@@ -1359,7 +1389,7 @@ 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;

package/src/grounding/ref-index.ts

@@ -151,6 +151,25 @@ export function buildReferenceCard(
   };
 }
 
+/**
+ * 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/sources-cli.ts

@@ -6,6 +6,7 @@ import type { Command } from 'commander';
 import { homedir } from 'node:os';
 import { basename } from 'node:path';
 import { exportMirrorManifest } from './mirror-export.js';
+import { buildReferenceCardsForRegistry, nodeRefIndexFs } from './ref-index.js';
 import {
   addGroundingSource,
   discoverReferenceSources,
@@ -83,8 +84,15 @@ export function registerGroundingSourcesCli(program: Command): void {
     .description('~/source/ref 와 ~/docs/ref 후보를 찾는다(등록하지 않는다)')
     .option('--json', 'JSON 출력')
     .option('--home <dir>', '홈 디렉터리(기본: os homedir)')
-    .action((opts: { json?: boolean; home?: string }) => {
+    .option('--ref-index', 'local-repo·local-docs 후보를 L0 카드 ⊕ L1 목록으로 색인해 JSON 으로 낸다(읽기 전용 · 쓰기 0)')
+    .action((opts: { json?: boolean; home?: string; refIndex?: boolean }) => {
       const found = discoverReferenceSources(opts.home ?? homedir());
+      if (opts.refIndex) {
+        // 읽기 전용: 카드는 stdout 으로만 낸다 — `<stateDir>/ref-index.jsonl` 원장
+        // (⊕ BM25 낱말 색인 ⊕ 보조 서버 부하 규칙)은 다음 조각의 몫.
+        printJson(buildReferenceCardsForRegistry(found, nodeRefIndexFs));
+        return;
+      }
       if (opts.json) printJson(found);
       else if (found.length === 0) console.log('(none)');
       else for (const source of found) console.log(formatSource(source));