elanous 0.2.36 → 0.2.38

package/src/self-implement/run-ledger.ts

@@ -452,6 +452,237 @@ export function loadRunGraphVariant(runId: string, dir = runLedgerDir()): RunGra
   return { variantId: record.variant_id, reason: record.reason };
 }
 
+/**
+ * Axes compared between what a run asked for and what it actually ran with:
+ * the child LLM request (`childModel`/`childProvider`), `zaiCodingPlan.overage`,
+ * the Pod pool and the parent host.
+ */
+export type RunRequestEffectiveAxis = 'childModel' | 'childProvider' | 'overagePolicy' | 'podPool' | 'parentHost';
+
+/** Ledger event carrying one requested-vs-effective comparison row set. */
+export const RUN_REQUEST_VS_EFFECTIVE_EVENT = 'run-request-vs-effective';
+
+const RUN_REQUEST_EFFECTIVE_AXES: readonly RunRequestEffectiveAxis[] = [
+  'childModel',
+  'childProvider',
+  'overagePolicy',
+  'podPool',
+  'parentHost',
+];
+
+/** Values of the compared axes. Requested and effective sides share this shape so a row can name both. */
+export interface RunRequestEffectiveValues {
+  childModel?: string;
+  childProvider?: string;
+  overagePolicy?: string;
+  podPool?: string;
+  parentHost?: string;
+}
+
+/** One axis whose requested value differs from the effective value observed while the run executed. */
+export interface RunRequestEffectiveMismatch {
+  axis: RunRequestEffectiveAxis;
+  requested: string;
+  effective: string;
+}
+
+export interface RunRequestEffectiveComparison {
+  requested: RunRequestEffectiveValues;
+  effective: RunRequestEffectiveValues;
+  mismatches: RunRequestEffectiveMismatch[];
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readRunRequestEffectiveValues(value: unknown): RunRequestEffectiveValues {
+  if (!isPlainRecord(value)) return {};
+  const values: RunRequestEffectiveValues = {};
+  for (const axis of RUN_REQUEST_EFFECTIVE_AXES) {
+    const raw = value[axis];
+    if (typeof raw === 'string' && raw.trim()) values[axis] = raw.trim();
+  }
+  return values;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+/** Compare both sides axis by axis; an axis observed on one side only is not a mismatch. */
+export function compareRunRequestEffective(
+  requested: RunRequestEffectiveValues,
+  effective: RunRequestEffectiveValues,
+): RunRequestEffectiveMismatch[] {
+  const mismatches: RunRequestEffectiveMismatch[] = [];
+  for (const axis of RUN_REQUEST_EFFECTIVE_AXES) {
+    const requestedValue = requested[axis];
+    const effectiveValue = effective[axis];
+    if (requestedValue === undefined || effectiveValue === undefined || requestedValue === effectiveValue) continue;
+    mismatches.push({ axis, requested: requestedValue, effective: effectiveValue });
+  }
+  return mismatches;
+}
+
+/**
+ * Read the two sides out of one observer event. The canonical contract is an explicit
+ * `data.requested` / `data.effective` object. The real orchestrator records the
+ * requested child at run-origin and the selected execution provider at start.
+ */
+function runRequestEffectiveSidesOf(entry: RunLedgerEntry): RunRequestEffectiveComparison {
+  const data = isPlainRecord(entry.data) ? entry.data : {};
+  const requested = readRunRequestEffectiveValues(data.requested);
+  const effective = readRunRequestEffectiveValues(data.effective);
+
+  if (entry.event === 'run-origin') {
+    requested.childProvider ??= nonEmptyString(data.childProvider);
+    requested.childModel ??= nonEmptyString(data.childModel);
+  }
+  if (entry.event === 'start') {
+    effective.childProvider ??= nonEmptyString(data.provider);
+    effective.childModel ??= nonEmptyString(data.model);
+  }
+
+  const childLlm = data.childLlm;
+  if (isPlainRecord(childLlm)) {
+    const provider = nonEmptyString(childLlm.provider);
+    if (provider !== undefined && requested.childProvider === undefined) requested.childProvider = provider;
+    const model = nonEmptyString(childLlm.model);
+    if (model !== undefined && requested.childModel === undefined) requested.childModel = model;
+  }
+  const zaiCodingPlan = data.zaiCodingPlan;
+  if (isPlainRecord(zaiCodingPlan)) {
+    const overage = nonEmptyString(zaiCodingPlan.overage);
+    if (overage !== undefined && requested.overagePolicy === undefined) requested.overagePolicy = overage;
+  }
+
+  for (const key of ['childStart', 'llmConsumeStart'] as const) {
+    const start = data[key];
+    if (!isPlainRecord(start)) continue;
+    const provider = nonEmptyString(start.provider);
+    if (provider !== undefined && effective.childProvider === undefined) effective.childProvider = provider;
+    const model = nonEmptyString(start.model);
+    if (model !== undefined && effective.childModel === undefined) effective.childModel = model;
+  }
+
+  return { requested, effective, mismatches: compareRunRequestEffective(requested, effective) };
+}
+
+/**
+ * Merge every non-comparison event of a run into one comparison. The request side keeps the
+ * first recorded value (run-origin) and the effective side keeps the last observed one
+ * (child start, first llm consume-start, actual Pod pool).
+ */
+export function runRequestEffectiveFromLedger(ledger: readonly RunLedgerEntry[]): RunRequestEffectiveComparison {
+  const requested: RunRequestEffectiveValues = {};
+  const effective: RunRequestEffectiveValues = {};
+  for (const entry of ledger) {
+    if (entry.event === RUN_REQUEST_VS_EFFECTIVE_EVENT) continue;
+    const sides = runRequestEffectiveSidesOf(entry);
+    for (const axis of RUN_REQUEST_EFFECTIVE_AXES) {
+      const requestedValue = sides.requested[axis];
+      if (requestedValue !== undefined && requested[axis] === undefined) requested[axis] = requestedValue;
+      const effectiveValue = sides.effective[axis];
+      if (effectiveValue !== undefined && effective[axis] === undefined) effective[axis] = effectiveValue;
+    }
+  }
+  return { requested, effective, mismatches: compareRunRequestEffective(requested, effective) };
+}
+
+/** Mismatch rows this run already wrote, de-duplicated across repeated comparisons. */
+export function recordedRunRequestEffectiveMismatches(
+  ledger: readonly RunLedgerEntry[],
+): RunRequestEffectiveMismatch[] {
+  const seen = new Set<string>();
+  const rows: RunRequestEffectiveMismatch[] = [];
+  for (const entry of ledger) {
+    if (entry.event !== RUN_REQUEST_VS_EFFECTIVE_EVENT) continue;
+    const recorded = isPlainRecord(entry.data) ? entry.data.mismatches : undefined;
+    if (!Array.isArray(recorded)) continue;
+    for (const row of recorded) {
+      if (!isPlainRecord(row)) continue;
+      const axis = row.axis;
+      if (typeof axis !== 'string' || !RUN_REQUEST_EFFECTIVE_AXES.includes(axis as RunRequestEffectiveAxis)) continue;
+      const requested = nonEmptyString(row.requested);
+      const effective = nonEmptyString(row.effective);
+      if (requested === undefined || effective === undefined) continue;
+      const key = `${axis}\u0000${requested}\u0000${effective}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      rows.push({ axis: axis as RunRequestEffectiveAxis, requested, effective });
+    }
+  }
+  return rows;
+}
+
+export interface RunRequestVsEffectiveRecordOptions {
+  /** Ledger directory; default = `runLedgerDir()`. */
+  dir?: string;
+}
+
+/**
+ * Write one `run-request-vs-effective` row under the run's own ledger file, inheriting the
+ * run's goalId and shard identity so the run stays a single mission on the timeline.
+ */
+export function recordRunRequestVsEffective(
+  runId: string,
+  requested: RunRequestEffectiveValues,
+  effective: RunRequestEffectiveValues,
+  options: RunRequestVsEffectiveRecordOptions = {},
+): RunRequestEffectiveComparison {
+  const dir = options.dir ?? runLedgerDir();
+  const ledger = loadRunLedger(runId, dir) ?? [];
+  const start = ledger.find((entry) => entry.event === 'start' && typeof entry.timestamp === 'string');
+  const goalOwner = ledger.find((entry) => nonEmptyString(entry.goalId) !== undefined);
+  const comparison: RunRequestEffectiveComparison = {
+    requested,
+    effective,
+    mismatches: compareRunRequestEffective(requested, effective),
+  };
+  appendRunLedgerEntry({
+    timestamp: new Date().toISOString(),
+    runId,
+    event: RUN_REQUEST_VS_EFFECTIVE_EVENT,
+    data: { requested: comparison.requested, effective: comparison.effective, mismatches: comparison.mismatches },
+    ...(goalOwner?.goalId === undefined ? {} : { goalId: goalOwner.goalId }),
+    ...(start?.orchestrationId === undefined ? {} : { orchestrationId: start.orchestrationId }),
+    ...(start?.shardId === undefined ? {} : { shardId: start.shardId }),
+    ...(start?.pieceIndex === undefined ? {} : { pieceIndex: start.pieceIndex }),
+    ...(start?.pieceTotal === undefined ? {} : { pieceTotal: start.pieceTotal }),
+  }, dir);
+  return comparison;
+}
+
+function sameRunRequestEffectiveMismatches(
+  left: readonly RunRequestEffectiveMismatch[],
+  right: readonly RunRequestEffectiveMismatch[],
+): boolean {
+  if (left.length !== right.length) return false;
+  const keys = new Set(right.map((row) => `${row.axis}\u0000${row.requested}\u0000${row.effective}`));
+  return left.every((row) => keys.has(`${row.axis}\u0000${row.requested}\u0000${row.effective}`));
+}
+
+/**
+ * Production hook: after any observer event lands, compare the run's requested and effective
+ * sides and write the mismatch rows when they differ. Idempotent — a run whose rows already
+ * match its current comparison writes nothing. Recording only; no alerting and no repair.
+ */
+function recordRunRequestVsEffectiveFromLedger(runId: string, dir: string, appended: RunLedgerEntry): void {
+  // Keep unrelated observer writes O(1); only events carrying one side can
+  // change the comparison. In particular, a long run must not reread its
+  // complete ledger after every progress event.
+  if (!['run-origin', 'start', 'child-start', 'llm-consume-start'].includes(appended.event)
+    && !isPlainRecord(appended.data?.requested) && !isPlainRecord(appended.data?.effective)) return;
+  if (appended.event === RUN_REQUEST_VS_EFFECTIVE_EVENT) return;
+  const ledger = loadRunLedger(runId, dir);
+  if (!ledger?.length) return;
+  const comparison = runRequestEffectiveFromLedger(ledger);
+  if (comparison.mismatches.length === 0) return;
+  if (sameRunRequestEffectiveMismatches(recordedRunRequestEffectiveMismatches(ledger), comparison.mismatches)) return;
+  recordRunRequestVsEffective(runId, comparison.requested, comparison.effective, { dir });
+}
+
 /** Append one observer event. Callers own fail-soft handling. */
 export function appendRunLedgerEntry(entry: RunLedgerEntry, dir = runLedgerDir()): void {
   if (refuseProductionLedgerWriteInTest(dir, 'run-ledger')) return;
@@ -465,6 +696,11 @@ export function appendRunLedgerEntry(entry: RunLedgerEntry, dir = runLedgerDir()
     const line = `${JSON.stringify(row)}\n`;
     if (!restoreArchivedRunLedger(dir, entry.runId, line)) appendFileSync(live, line, 'utf8');
   });
+  try {
+    recordRunRequestVsEffectiveFromLedger(entry.runId, dir, entry);
+  } catch {
+    // The comparison is observation: it must never fail a producer write that already landed.
+  }
 }
 
 /** Caller decision inside `appendRunLedgerEntryChecked`: either `append` exactly one entry, or skip with `result`. */
@@ -834,6 +1070,15 @@ export interface RunLedgerTimelineEntry {
   shardId?: string;
   pieceIndex?: number;
   pieceTotal?: number;
+  /** Producer-recorded `graph.unit` visits of this run, with terminal unmatched enters reported as orphans. */
+  unitVisits?: GraphUnitVisitClassification;
+  /** Requested vs effective values this run recorded; present only when the two sides differ. */
+  requestVsEffective?: {
+    requested: RunRequestEffectiveValues;
+    effective: RunRequestEffectiveValues;
+  };
+  /** Mismatch rows (axis · requested · effective) for this run; absent when requested equals effective. */
+  mismatches?: RunRequestEffectiveMismatch[];
 }
 
 export interface RunLedgerTimelineQueryOptions {
@@ -842,6 +1087,20 @@ export interface RunLedgerTimelineQueryOptions {
   list?: (path: string) => string[];
 }
 
+/**
+ * Timeline projection of the requested-vs-effective rows. Recorded rows win over a derived
+ * comparison so the timeline shows what the run actually wrote; equal sides project nothing.
+ */
+function runRequestEffectiveTimelineFields(
+  ledger: readonly RunLedgerEntry[],
+): Pick<RunLedgerTimelineEntry, 'mismatches' | 'requestVsEffective'> {
+  const recorded = recordedRunRequestEffectiveMismatches(ledger);
+  const derived = runRequestEffectiveFromLedger(ledger);
+  const mismatches = recorded.length > 0 ? recorded : derived.mismatches;
+  if (mismatches.length === 0) return {};
+  return { mismatches, requestVsEffective: { requested: derived.requested, effective: derived.effective } };
+}
+
 /**
  * Read runs whose sole recorded goalId equals the historian missionId.
  * goalId is chosen because the producer already persists it on each observer event, while orchestrationId only groups shards.
@@ -875,6 +1134,8 @@ export function queryRunLedgerTimeline(missionId: string, options: RunLedgerTime
         ...(execution.shardId === undefined ? {} : { shardId: execution.shardId }),
         ...(execution.pieceIndex === undefined ? {} : { pieceIndex: execution.pieceIndex }),
         ...(execution.pieceTotal === undefined ? {} : { pieceTotal: execution.pieceTotal }),
+        unitVisits: classifyGraphUnitVisits(ledger),
+        ...runRequestEffectiveTimelineFields(ledger),
       });
     } catch {
       // A corrupt or concurrently replaced ledger must not leak a partial run into another mission timeline.
@@ -883,6 +1144,75 @@ export function queryRunLedgerTimeline(missionId: string, options: RunLedgerTime
   return entries.sort((left, right) => Date.parse(left.executedAt) - Date.parse(right.executedAt) || left.runId.localeCompare(right.runId));
 }
 
+export interface GraphAdaptReport {
+  goalId: string;
+  runCount: number;
+  uniquePathSignatures: number;
+  unitCallCount: number;
+  adaptationCount: number;
+  adapted: { landed: number; denominator: number; rate: number | null };
+  nonAdapted: { landed: number; denominator: number; rate: number | null };
+  excludedCount: number;
+  exclusionReasons: Record<string, number>;
+}
+
+/** Measure only producer-observed traversals and variant applications; never activate adaptation. */
+export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoot()): GraphAdaptReport {
+  const dir = runLedgerDir(stateDir);
+  const signatures = new Set<string>();
+  const counts = { adapted: { landed: 0, denominator: 0 }, nonAdapted: { landed: 0, denominator: 0 } };
+  const exclusionReasons: Record<string, number> = {};
+  const exclude = (reason: string): void => { exclusionReasons[reason] = (exclusionReasons[reason] ?? 0) + 1; };
+  let unitCallCount = 0;
+  let adaptationCount = 0;
+  let fileNames: string[];
+  try { fileNames = readdirSync(dir); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') fileNames = [];
+    else throw error;
+  }
+  for (const name of fileNames) {
+    const runId = runIdFromCanonicalLedgerFile(name);
+    if (!runId) continue;
+    let ledger: RunLedgerEntry[] | null;
+    try { ledger = loadRunLedger(runId, dir); }
+    catch { exclude('invalid-ledger'); continue; }
+    if (!ledger?.length) { exclude('empty-ledger'); continue; }
+    const goalIds = new Set(ledger.map(entry => entry.goalId).filter((id): id is string => typeof id === 'string' && id.length > 0));
+    if (goalIds.size === 1 && !goalIds.has(goalId)) continue;
+    if (goalIds.size !== 1) { exclude('goal-id-missing-or-conflicting'); continue; }
+    const traversals = ledger.filter(entry => entry.event === 'pipeline-traversal-shadow');
+    const paths = traversals.map(entry => entry.data.observedNodes);
+    if (paths.length === 0 || paths.some(path => !Array.isArray(path) || path.length === 0 || !path.every(node => typeof node === 'string' && node.length > 0))) {
+      exclude('path-missing-or-invalid'); continue;
+    }
+    let graphRun: unknown;
+    try { graphRun = JSON.parse(readFileSync(join(stateDir, 'graph-runs', 'self-implement', `${runId}.json`), 'utf8')); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') { exclude('graph-run-unreadable'); continue; }
+    }
+    const recorded = graphRun && typeof graphRun === 'object' && !Array.isArray(graphRun) ? graphRun as Record<string, unknown> : null;
+    if (recorded && (recorded.runId !== runId || recorded.graphId !== 'self-implement' ||
+      (recorded.unitCalls !== undefined && !Array.isArray(recorded.unitCalls)))) {
+      exclude('unit-calls-invalid'); continue;
+    }
+    const merge = [...ledger].reverse().find(entry => entry.event === 'merged');
+    if (merge && typeof merge.data.merged !== 'boolean') { exclude('landing-invalid'); continue; }
+    signatures.add(JSON.stringify(paths.at(-1)));
+    unitCallCount += recorded && Array.isArray(recorded.unitCalls) ? recorded.unitCalls.length : 0;
+    const adaptations = ledger.filter(entry => entry.event === 'graph-variant-applied');
+    adaptationCount += adaptations.length;
+    const group = adaptations.length ? counts.adapted : counts.nonAdapted;
+    group.denominator += 1;
+    if (merge?.data.merged === true) group.landed += 1;
+  }
+  const rate = (group: { landed: number; denominator: number }) => ({ ...group, rate: group.denominator ? group.landed / group.denominator : null });
+  return { goalId, runCount: counts.adapted.denominator + counts.nonAdapted.denominator,
+    uniquePathSignatures: signatures.size, unitCallCount, adaptationCount,
+    adapted: rate(counts.adapted), nonAdapted: rate(counts.nonAdapted),
+    excludedCount: Object.values(exclusionReasons).reduce((total, count) => total + count, 0), exclusionReasons };
+}
+
 export interface GoalSourceDistributionQuery {
   ledgerDirectory: string;
   runCount: number;
@@ -1416,6 +1746,8 @@ export interface UnfinishedRunLedgerEntry {
   lifecycle: UnfinishedRunLifecycle;
   /** Non-blocking request record (kind·reason·next) carried by this runId's ledger; absent for runs without one. */
   nonBlocking?: NonBlockingRunLedgerRecord;
+  /** ⭐ graph.unit enter without its exit on a *terminal* ledger — present only when non-empty. */
+  orphanUnitVisits?: readonly GraphUnitOrphanVisit[];
 }
 
 export interface UnfinishedRunLedgerQuery {
@@ -1435,6 +1767,12 @@ export interface UnfinishedRunLedgerQuery {
   pathFilter?: string;
   matchingPathCount?: number;
   unknownPathCount?: number;
+  /**
+   * ⭐ Total orphan unit visits across **every scanned ledger** — including terminal runs that are not
+   * returned as entries (they are counted, never revived). 같은 원장을 「미완」으로 되살리지 않고도
+   * 엉킨 visit 을 셀 수 있게 하는 값이다.
+   */
+  orphanUnitVisitCount?: number;
   scope: 'self-implement-run-ledger';
   note: string;
 }
@@ -1546,6 +1884,78 @@ function isTerminalOnlyByTrailingRunStatus(ledger: readonly RunLedgerEntry[]): b
     && !hasHumanStopEvent(ledger);
 }
 
+/** One producer-recorded `graph.unit` enter that the run never closed with a matching exit. */
+export interface GraphUnitOrphanVisit {
+  childRunId: string | null;
+  graphId: string | null;
+  nodeId: string | null;
+  unit: string | null;
+  /** Timestamp of the unmatched enter; null when the producer recorded none. */
+  enteredAt: string | null;
+}
+
+export interface GraphUnitVisitClassification {
+  /** Whether the ledger itself records the run's end (`run-status`, `terminal`, or `human-stop`). */
+  terminal: boolean;
+  enterCount: number;
+  exitCount: number;
+  /** Unmatched enters in a terminal run. An open enter on a non-terminal ledger is in flight, not an orphan. */
+  orphanCount: number;
+  orphanUnitVisits: readonly GraphUnitOrphanVisit[];
+}
+
+function dataString(data: Record<string, unknown>, field: string): string | null {
+  const value = data[field];
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function graphUnitVisitOf(entry: RunLedgerEntry): GraphUnitOrphanVisit {
+  return {
+    childRunId: dataString(entry.data, 'childRunId'),
+    graphId: dataString(entry.data, 'graphId'),
+    nodeId: dataString(entry.data, 'nodeId'),
+    unit: dataString(entry.data, 'unit'),
+    enteredAt: entry.timestamp ?? null,
+  };
+}
+
+/** An exit closes the visit with its own childRunId; without one it closes the latest visit on the same node. */
+function closesUnitVisit(exitChildRunId: string | null, exitNodeId: string | null, open: GraphUnitOrphanVisit): boolean {
+  if (open.childRunId !== null || exitChildRunId !== null) return open.childRunId === exitChildRunId;
+  return open.nodeId !== null && open.nodeId === exitNodeId;
+}
+
+/**
+ * Pair each producer-recorded `graph.unit` enter with its exit and report the visits a terminal run left open.
+ * This only reads the already-loaded ledger: it never synthesizes or writes an exit entry.
+ */
+export function classifyGraphUnitVisits(ledger: readonly RunLedgerEntry[]): GraphUnitVisitClassification {
+  const open: GraphUnitOrphanVisit[] = [];
+  let enterCount = 0;
+  let exitCount = 0;
+  for (const entry of ledger) {
+    if (entry.event !== 'graph.unit') continue;
+    if (entry.data.phase === 'enter') {
+      enterCount += 1;
+      open.push(graphUnitVisitOf(entry));
+      continue;
+    }
+    // `budget-exhausted` is a recorded failure the runner still follows with an exit, so it closes nothing.
+    if (entry.data.phase !== 'exit') continue;
+    exitCount += 1;
+    const exitChildRunId = dataString(entry.data, 'childRunId');
+    const exitNodeId = dataString(entry.data, 'nodeId');
+    for (let index = open.length - 1; index >= 0; index -= 1) {
+      if (!closesUnitVisit(exitChildRunId, exitNodeId, open[index]!)) continue;
+      open.splice(index, 1);
+      break;
+    }
+  }
+  const terminal = hasTerminalRunStatus(ledger);
+  const orphanUnitVisits = terminal ? open : [];
+  return { terminal, enterCount, exitCount, orphanCount: orphanUnitVisits.length, orphanUnitVisits };
+}
+
 /** ⛔⭐⭐⭐ 미완 항목의 «상태» — 종전엔 이 조회가 낸 것이 «한 값»(`terminal-status-missing`)뿐이었다.
  *  📏 2026-08-11 실측: 그 한 값 안에 서로 «다른 것»이 섞여 있었다 —
  *     실제로 도는 것 2 · 오래 전에 죽은 잔해 51(중앙 5.2일) · 종료를 «다른 이름»으로 적은 것 5.
@@ -1773,6 +2183,8 @@ interface UnfinishedLedgerFacts {
   goalFile: string | null;
   fixedLifecycle: UnfinishedRunLifecycle;
   nonBlocking: NonBlockingRunLedgerRecord | null;
+  /** Held here so a terminal ledger's orphan visits are countable before the terminal `continue`. */
+  unitVisits: GraphUnitVisitClassification;
 }
 
 // A full federated scan can exceed 5,000 files; keep the previous scan resident for stat-checked reuse.
@@ -1797,7 +2209,8 @@ function unfinishedLedgerCacheKey(path: string, read?: RunLedgerReader): string
 //   원장 옆에 (size, mtimeMs, ctimeMs) 스탬프로 저장하고, 스탬프가 같으면 재사용한다. 원장에 무엇이 «붙으면»
 //   스탬프가 바뀌므로 무효화는 자동이다 (같은 크기로 덮고 mtime 을 되돌려도 ctime 이 바뀐다). 읽기 실패는 전부 fail-soft: 색인이 없으면 그냥 새로 읽는다.
 const RUN_LEDGER_SCAN_INDEX_FILE = '.unfinished-scan-index.json';
-const RUN_LEDGER_SCAN_INDEX_VERSION = 2;
+// v3 added facts.unitVisits; a v2 record would hand back a facts object without it.
+const RUN_LEDGER_SCAN_INDEX_VERSION = 3;
 const RUN_LEDGER_SCAN_INDEX_LIMIT = 32_768;
 
 /** Where the persisted scan index lives: beside its ledgers, never mistaken for one (readdir filters canonical names). */
@@ -1829,7 +2242,9 @@ function isScanIndexFacts(value: unknown): value is UnfinishedLedgerFacts {
     && typeof facts.lastActivityStatus === 'string'
     && (facts.targetRoot === null || typeof facts.targetRoot === 'string')
     && (facts.goalFile === null || typeof facts.goalFile === 'string')
-    && typeof facts.fixedLifecycle === 'string' && UNFINISHED_LIFECYCLE_WORDS.has(facts.fixedLifecycle);
+    && typeof facts.fixedLifecycle === 'string' && UNFINISHED_LIFECYCLE_WORDS.has(facts.fixedLifecycle)
+    && typeof (facts.unitVisits as GraphUnitVisitClassification | undefined)?.orphanCount === 'number'
+    && Array.isArray((facts.unitVisits as GraphUnitVisitClassification | undefined)?.orphanUnitVisits);
 }
 
 function isScanIndexRecord(value: unknown): value is RunLedgerScanIndexRecord {
@@ -1895,6 +2310,7 @@ function unfinishedLedgerFacts(ledger: readonly RunLedgerEntry[]): UnfinishedLed
     goalFile: ledgerGoalDocument(ledger),
     fixedLifecycle: classifyUnfinishedLifecycle(ledger, null, 0),
     nonBlocking: readNonBlockingRunRecord(ledger),
+    unitVisits: classifyGraphUnitVisits(ledger),
   };
 }
 
@@ -2014,6 +2430,8 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
   let cacheMisses = 0;
   let ledgerTargetCount = 0;
   let callerCwdCount = 0;
+  // ⭐ 터미널 원장도 «세기만» 한다 — entries 로 되살리지 않는다(부활 금지).
+  let orphanUnitVisitCount = 0;
   for (const fileName of fileNames) {
     const runId = runIdFromCanonicalLedgerFile(fileName);
     if (!runId) continue;
@@ -2037,6 +2455,9 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
       callerCwdCount += 1;
       continue;
     }
+    const orphanUnitVisits = facts.unitVisits.orphanUnitVisits;
+    orphanUnitVisitCount += facts.unitVisits.orphanCount;
+    const orphanVisitField = orphanUnitVisits.length > 0 ? { orphanUnitVisits } : {};
     if (facts.terminal) {
       terminal += 1;
       if (facts.terminalByTrailingRunStatus) terminalByTrailingRunStatus += 1;
@@ -2070,7 +2491,7 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
           : goalDocument.status === 'directory-unreadable'
             ? 'goal-directory-unreadable'
             : 'goal-document-not-found';
-      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: [], plannedPathStatus, ...unknownDeclaredPaths(), pathMatchReasons: {}, goalDocumentPath: null, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle, ...(facts.nonBlocking ? { nonBlocking: facts.nonBlocking } : {}) });
+      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: [], plannedPathStatus, ...unknownDeclaredPaths(), pathMatchReasons: {}, goalDocumentPath: null, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle, ...(facts.nonBlocking ? { nonBlocking: facts.nonBlocking } : {}), ...orphanVisitField });
       continue;
     }
     try {
@@ -2078,9 +2499,9 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
       const text = typeof document === 'string' ? document : document.toString('utf8');
       const paths = [...new Set(tracedPathReferences(text).map((reference) => reference.path))];
       const declared = declaredPathsFromGoalDocument(text);
-      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: paths, plannedPathStatus: paths.length > 0 ? goalDocument.source === 'ledger' ? 'found-ledger-goal-file' : 'found-branch-fallback' : 'no-traced-paths', ...declared, pathMatchReasons: pathMatchReasons(declared.declaredPaths, paths), goalDocumentPath: goalDocument.path, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle, ...(facts.nonBlocking ? { nonBlocking: facts.nonBlocking } : {}) });
+      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: paths, plannedPathStatus: paths.length > 0 ? goalDocument.source === 'ledger' ? 'found-ledger-goal-file' : 'found-branch-fallback' : 'no-traced-paths', ...declared, pathMatchReasons: pathMatchReasons(declared.declaredPaths, paths), goalDocumentPath: goalDocument.path, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle, ...(facts.nonBlocking ? { nonBlocking: facts.nonBlocking } : {}), ...orphanVisitField });
     } catch {
-      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: [], plannedPathStatus: 'goal-document-unreadable', declaredPaths: [], declaredPathStatus: 'goal-document-unreadable', pathMatchReasons: {}, goalDocumentPath: goalDocument.path, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle, ...(facts.nonBlocking ? { nonBlocking: facts.nonBlocking } : {}) });
+      entries.push({ runId, branch, status: 'terminal-status-missing', plannedPaths: [], plannedPathStatus: 'goal-document-unreadable', declaredPaths: [], declaredPathStatus: 'goal-document-unreadable', pathMatchReasons: {}, goalDocumentPath: goalDocument.path, goalLookupBasis, goalDocumentSearchDirectory: searchDirectory, ...activity, lifecycle, ...(facts.nonBlocking ? { nonBlocking: facts.nonBlocking } : {}), ...orphanVisitField });
     }
   }
   entries.sort((left, right) => left.runId.localeCompare(right.runId));
@@ -2098,7 +2519,7 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
     ms: Date.now() - startedAt,
   });
   if (options.path === undefined) {
-    return { entries, ledgerDirectory: dir, goalsDirectory: goalsDir, unreadableLedgerCount, ledgerDirectoryMissing: false, terminalByTrailingRunStatus, cacheHits, cacheMisses, indexHits, indexOrigin, scope: 'self-implement-run-ledger', note: UNFINISHED_RUN_LEDGER_NOTE };
+    return { entries, ledgerDirectory: dir, goalsDirectory: goalsDir, unreadableLedgerCount, orphanUnitVisitCount, ledgerDirectoryMissing: false, terminalByTrailingRunStatus, cacheHits, cacheMisses, indexHits, indexOrigin, scope: 'self-implement-run-ledger', note: UNFINISHED_RUN_LEDGER_NOTE };
   }
   const pathFilter = options.path;
   const unknownPathStatus = (entry: UnfinishedRunLedgerEntry): boolean => entry.plannedPathStatus !== 'found-ledger-goal-file'
@@ -2114,6 +2535,7 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
     ledgerDirectory: dir,
     goalsDirectory: goalsDir,
     unreadableLedgerCount,
+    orphanUnitVisitCount,
     ledgerDirectoryMissing: false,
     terminalByTrailingRunStatus,
     cacheHits,

package/src/self-implement/run-stop.ts

@@ -15,7 +15,7 @@ import type { PodChildEvidence } from '../task-orchestrator/surfaces/self-implem
 
 /** 닫힌 목록 — 못 고르면 `unclassified`. */
 export const RUN_STOP_CLASSES = [
-  'env-unrelated', 'main-sync', 'pod-died', 'review-repeat',
+  'env-unrelated', 'main-sync', 'pod-died', 'pod-vanished', 'review-repeat',
   'review-out-of-scope', 'scope-escape', 'evidence-uncovered', 'fabric', 'launch-failed', 'gate-failed', 'unclassified',
 ] as const;
 export type RunStopClass = typeof RUN_STOP_CLASSES[number];

package/src/self-implement/running-runs.ts

@@ -246,6 +246,8 @@ export interface RunningRunsLedgerObservation {
 
 export interface RunningRunsQueryObservation {
   readonly caller?: string | null;
+  /** ID 조회(src/index.ts `self running-runs [runId]`가 넘겨준 runIds)가 요청한 runId 들 — 전체 관측 질의에는 이 키가 없다. */
+  readonly requestedRunIds?: readonly string[];
   readonly cacheHits?: number;
   readonly cacheMisses?: number;
   readonly elapsedMs: number;
@@ -478,6 +480,9 @@ export function queryRunningRuns(options: { includeTest?: boolean; runIds?: read
   const processStartTime = deps.processStartedAt ?? processStartedAt;
   const observeQuery = deps.observeQuery ?? ((observation: RunningRunsQueryObservation) => debug.log('self-implement.running-runs', 'query', observation));
   const startedAt = Date.now();
+  // ID 조회 배선 — src/index.ts의 `self running-runs [runId]` 액션이 넘겨준 options.runIds 를 이 조회가 소비한다:
+  // 정의된 runIds 는 연합 원장 질의 전달·엔트리·pty 관측을 모두 그 runId 들로 한정한다.
+  const requestedRunIdSet = options.runIds === undefined ? undefined : new Set(options.runIds);
   let ledgerDirectoryCollectionElapsedMs = 0;
   let ledgerReadElapsedMs = 0;
   let screenProcessReadElapsedMs = 0;
@@ -521,7 +526,15 @@ export function queryRunningRuns(options: { includeTest?: boolean; runIds?: read
     } finally {
       screenProcessReadElapsedMs = Date.now() - screenProcessReadStartedAt;
     }
-    const runIds = [...new Set([...ledger.entries.map((entry) => entry.runId), ...pty.refs.flatMap((ref) => ref.runId ? [ref.runId] : [])])];
+    // ID 조회 소비 지점 — deps·원장 질의가 runIds를 무시하고 넓게 관측해도 결과를 요청한 runId들로 한정하고,
+    // 일치하는 런이 없으면 entries는 []다(부분 관측 계수는 원장·pty 판독성 관측을 그대로 보존한다).
+    const scopedLedgerEntries = requestedRunIdSet === undefined
+      ? ledger.entries
+      : ledger.entries.filter((entry) => requestedRunIdSet.has(entry.runId));
+    const scopedPty = requestedRunIdSet === undefined
+      ? pty
+      : { ...pty, refs: pty.refs.filter((ref) => typeof ref.runId === 'string' && requestedRunIdSet.has(ref.runId)) };
+    const runIds = [...new Set([...scopedLedgerEntries.map((entry) => entry.runId), ...scopedPty.refs.flatMap((ref) => ref.runId ? [ref.runId] : [])])];
     let observedPhases: ObservedRunPhases = { events: [], targetCount: 0, unreadableTargets: [] };
     const stageStoreReadStartedAt = Date.now();
     try {
@@ -534,7 +547,7 @@ export function queryRunningRuns(options: { includeTest?: boolean; runIds?: read
       discardedNonStageEventCount = observedPhases.discardedNonStageEventCount ?? 0;
     }
     const phaseObservation = phaseObservationFor(observedPhases);
-    const result = assessRunningRuns(ledger.entries, pty, ledger, observedPhases.events, phaseObservation);
+    const result = assessRunningRuns(scopedLedgerEntries, scopedPty, ledger, observedPhases.events, phaseObservation);
     const unreadable: UnreadableRunningRunsLedger[] = [...(result.unreadable ?? [])].filter((entry) => entry.reason === 'unreadable-ledger');
     const failedDirectories = hasUnreadableLedgerObservation(ledger)
       ? collectedLedgerDirectories.filter((dir) => !ledger.ledgerDirectories.includes(dir))
@@ -571,7 +584,7 @@ export function queryRunningRuns(options: { includeTest?: boolean; runIds?: read
     let lingeringLaunchParents: LingeringLaunchParentAssessment;
     try {
       lingeringLaunchParents = assessLingeringLaunchParents(
-        ledger.entries, loadRun, isProcessAlive, processStartTime, ledger,
+        scopedLedgerEntries, loadRun, isProcessAlive, processStartTime, ledger,
       );
     } finally {
       launchParentClassificationElapsedMs = Date.now() - launchParentClassificationStartedAt;
@@ -581,6 +594,7 @@ export function queryRunningRuns(options: { includeTest?: boolean; runIds?: read
     try {
       observeQuery({
         caller: options.caller ?? null,
+        ...(options.runIds === undefined ? {} : { requestedRunIds: options.runIds }),
         cacheHits,
         cacheMisses,
         elapsedMs: Date.now() - startedAt,