elanous 0.2.35 → 0.2.37

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

@@ -1,5 +1,6 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
 import { refuseProductionLedgerWriteInTest } from '../harness/ledger-write-guard.js';
 import { tracedPathReferences, verbatimOriginalAsk } from './goal-author.js';
 import { parseAskTargetPathHintsResult } from '../self-dev/launch-preflight-text.js';
@@ -408,6 +409,49 @@ export function describeFederatedMissingRunLedger(runId: string, options: Federa
   };
 }
 
+/** 런 원장 옆 `.graph.yaml` 경로 — 원장 경로 계약(runLedgerPath)에서 파생한다. */
+export function runGraphVariantPath(runId: string, dir = runLedgerDir()): string {
+  return `${runLedgerPath(runId, dir)}.graph.yaml`;
+}
+
+/** 최초 graph variant 선택의 원장 옆 재조회 계약 — 같은 runId·파일이면 같은 id·선택 이유가 돌아온다. */
+export interface RunGraphVariantSelection {
+  /** createGraphVariant 가 골 종류·대상 경로 수에서 유도한 최초 variant id. */
+  readonly variantId: string;
+  /** 그 variant가 최초로 선택된 근거(종류·경로 수 기반) — 저장·재조회가 같은 문자열. */
+  readonly reason: string;
+}
+
+/** 런 원장 옆 .graph.yaml 을 처음 한 번 쓰고 저장 경로를 돌려준다 — 이미 있으면 덮쓰지 않는다(flag wx). */
+export function saveRunGraphVariant(runId: string, yamlText: string, dir = runLedgerDir()): string {
+  mkdirSync(dir, { recursive: true });
+  const path = runGraphVariantPath(runId, dir);
+  writeFileSync(path, yamlText, { flag: 'wx' });
+  return path;
+}
+
+/** 런 원장 옆 .graph.yaml 에서 최초 graph variant 선택(id·이유)을 재조회한다 — 파일·선택이 없으면 null. */
+export function loadRunGraphVariant(runId: string, dir = runLedgerDir()): RunGraphVariantSelection | null {
+  const path = runGraphVariantPath(runId, dir);
+  let text: string;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw new Error(`unable to read run graph variant ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(text);
+  } catch (error) {
+    throw new Error(`invalid run graph variant YAML at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  const record = parsed as { variant_id?: unknown; reason?: unknown };
+  if (typeof record.variant_id !== 'string' || typeof record.reason !== 'string') return null;
+  return { variantId: record.variant_id, reason: record.reason };
+}
+
 /** Append one observer event. Callers own fail-soft handling. */
 export function appendRunLedgerEntry(entry: RunLedgerEntry, dir = runLedgerDir()): void {
   if (refuseProductionLedgerWriteInTest(dir, 'run-ledger')) return;
@@ -423,6 +467,70 @@ export function appendRunLedgerEntry(entry: RunLedgerEntry, dir = runLedgerDir()
   });
 }
 
+/** Caller decision inside `appendRunLedgerEntryChecked`: either `append` exactly one entry, or skip with `result`. */
+export type RunLedgerCheckedAppendDecision<T> =
+  | { append: false; result: T }
+  | { append: true; entry: RunLedgerEntry };
+
+export interface RunLedgerCheckedAppendOutcome<T> {
+  appended: boolean;
+  result: T | null;
+  /** Named reason when `appended:false` was produced without calling the decision — e.g. a test-universe refusal of an operating-ledger write. */
+  refusal: 'ledger-write-refused' | null;
+}
+
+/**
+ * Thrown (typed, with the stable `runId-mismatch` reason) when a checked-append
+ * decision returns an entry whose `runId` differs from the locked `runId`. Callers
+ * classify identity violations from `error.reason === 'runId-mismatch'` instead of
+ * parsing message substrings.
+ */
+export class RunLedgerCheckedAppendRunIdMismatchError extends Error {
+  readonly reason = 'runId-mismatch' as const;
+  constructor(readonly decisionRunId: string, readonly lockedRunId: string) {
+    super(
+      `runId-mismatch: appendRunLedgerEntryChecked: decision entry runId ${JSON.stringify(decisionRunId)} does not match locked runId ${JSON.stringify(lockedRunId)}`,
+    );
+    this.name = 'RunLedgerCheckedAppendRunIdMismatchError';
+  }
+}
+
+/**
+ * Atomically decide-and-append under a single per-run lock: the caller-supplied
+ * decision runs on the loaded ledger inside `withRunLedgerLock`, and at most one
+ * append is written by the same lock. Never calls `appendRunLedgerEntry` inside
+ * the lock (that function acquires the same lock itself, so nesting it would
+ * time out). Preserves the archived-ledger restore contract exactly like
+ * `appendRunLedgerEntry`. A missing ledger yields `null` entries to the
+ * decision (which may throw); a corrupt ledger throws before any append.
+ * Test-universe writes are refused before any lock directory or ledger path is created.
+ * The caller-supplied entry must carry the same `runId` as the acquired lock — on mismatch,
+ * the lock is released and a runId mismatch error is thrown before any append or archive restore.
+ */
+export function appendRunLedgerEntryChecked<T>(
+  runId: string,
+  decide: (entries: RunLedgerEntry[] | null) => RunLedgerCheckedAppendDecision<T>,
+  dir = runLedgerDir(),
+): RunLedgerCheckedAppendOutcome<T> {
+  if (refuseProductionLedgerWriteInTest(dir, 'run-ledger')) return { appended: false, result: null, refusal: 'ledger-write-refused' as const };
+  return withRunLedgerLock(dir, runId, () => {
+    const decision = decide(loadRunLedger(runId, dir));
+    if (!decision.append) return { appended: false, result: decision.result, refusal: null };
+    const entry = decision.entry;
+    if (entry.runId !== runId) {
+      throw new RunLedgerCheckedAppendRunIdMismatchError(entry.runId, runId);
+    }
+    const live = runLedgerPath(entry.runId, dir);
+    const devProject = process.env.ELANOUS_DEV_PROJECT;
+    const row = entry.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
+      ? { ...entry, devProject }
+      : entry;
+    const line = `${JSON.stringify(row)}\n`;
+    if (!restoreArchivedRunLedger(dir, entry.runId, line)) appendFileSync(live, line, 'utf8');
+    return { appended: true, result: null, refusal: null };
+  });
+}
+
 export interface HumanStopRunLedgerOptions {
   stoppedBy: string;
   stoppedAt?: string;
@@ -726,6 +834,8 @@ 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;
 }
 
 export interface RunLedgerTimelineQueryOptions {
@@ -767,6 +877,7 @@ 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),
       });
     } catch {
       // A corrupt or concurrently replaced ledger must not leak a partial run into another mission timeline.
@@ -775,6 +886,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;
@@ -1308,6 +1488,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 {
@@ -1327,6 +1509,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;
 }
@@ -1438,6 +1626,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.
@@ -1665,6 +1925,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.
@@ -1689,7 +1951,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). */
@@ -1721,7 +1984,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 {
@@ -1787,6 +2052,7 @@ function unfinishedLedgerFacts(ledger: readonly RunLedgerEntry[]): UnfinishedLed
     goalFile: ledgerGoalDocument(ledger),
     fixedLifecycle: classifyUnfinishedLifecycle(ledger, null, 0),
     nonBlocking: readNonBlockingRunRecord(ledger),
+    unitVisits: classifyGraphUnitVisits(ledger),
   };
 }
 
@@ -1906,6 +2172,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;
@@ -1929,6 +2197,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;
@@ -1962,7 +2233,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 {
@@ -1970,9 +2241,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));
@@ -1990,7 +2261,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'
@@ -2006,6 +2277,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/run-ttl.ts

@@ -5,13 +5,15 @@
  * Past `tools.selfImplement.runTtlHours` (default 24) since its last commit, the sweep makes one pre-emptive move:
  *   · live owning run → one resync memo in its control inbox (same path as SIBLING-RESYNC #24893/#24899),
  *                       at most once per (PR, head sha) — a rebase moves the head and re-arms it
- *   · no live run     → the registered `elanous:needs-rebase` label, once (QUIET-PR-COMMENTS: never a comment);
- *                       when `requestRegate` is supplied, at most one of those stale PRs is also selected
- *                       for a re-gate request (shadow: would-regate observation only; live: one call)
+ *   · no live run     → when `requestRegate` is supplied, at most one of those stale PRs is selected for a
+ *                       re-gate request (shadow: would-regate observation only; live: one call), and the
+ *                       registered `elanous:needs-rebase` label otherwise — once (QUIET-PR-COMMENTS: never a comment)
  *
  * Mode `tools.selfImplement.runTtl.mode`: `shadow` (default) only logs what it would do; `live` writes.
  * Cost bound: a PR opened inside the TTL is still inside its own time-to-landing and is never fetched
- * (`freshByCreation`), already-marked PRs without a live run are skipped before any fetch, at most `maxFetch` last-commit lookups per sweep with `concurrency` in flight, and at most `cap` actions.
+ * (`freshByCreation`), already-marked PRs without a live run are skipped before any fetch, at most `maxFetch`
+ * last-commit lookups per sweep with `concurrency` in flight, and at most `cap` actions — memo, marker and
+ * re-gate request all draw from that one budget, so a sweep never performs more than `cap` side effects.
  *
  * Pure core: every side effect is an injected adapter so tests never touch GitHub or the inbox.
  */
@@ -208,6 +210,12 @@ export async function runRunTtlSweep(input: {
   stalePrs.sort((a, b) => b.ageMs - a.ageMs || a.pr.number - b.pr.number);
   let actions = 0;
   let selectedRegate = false;
+  // One budget for the whole sweep: a memo, a marker and a re-gate request each spend one unit.
+  const spend = (): boolean => {
+    if (actions >= cap) return false;
+    actions += 1;
+    return true;
+  };
   for (const { pr, target, ageMs } of stalePrs) {
     const ageHours = ageMs / 3_600_000;
     const key = `${pr.number}:${pr.headSha}`;
@@ -220,10 +228,10 @@ export async function runRunTtlSweep(input: {
         continue;
       }
       if (already) { alreadyMemoed.push(pr.number); continue; }
-    }
-    if (!target.alive && pr.labels.includes(RUN_TTL_MARKER_LABEL)) { alreadyMarked.push(pr.number); continue; }
-    if (actions >= cap) { skippedOverCap.push(pr.number); continue; }
-    actions += 1;
+    } else if (pr.labels.includes(RUN_TTL_MARKER_LABEL)) { alreadyMarked.push(pr.number); continue; }
+    // The move this PR makes — memo, re-gate, or marker — takes the budget slot up front, so a sweep
+    // never emits more than `cap` side effects no matter how many of them a single PR would attract.
+    if (!spend()) { skippedOverCap.push(pr.number); continue; }
     if (target.alive) {
       if (mode === 'shadow') {
         memo.push(pr.number);
@@ -248,15 +256,31 @@ export async function runRunTtlSweep(input: {
       }
     }
     const reason = target.alive ? 'memo-failed' : target.reason;
-    const canRegate = Boolean(input.requestRegate) && !target.alive && !selectedRegate;
-    if (mode === 'shadow') {
-      label.push(pr.number);
-      emit('would-label', { pr: pr.number, label: RUN_TTL_MARKER_LABEL, reason, ageHours: Math.floor(ageHours) });
-      if (canRegate) {
-        selectedRegate = true;
+    // A re-gate request is the stronger move and spends the same budget as the marker, so it goes
+    // first: at `cap` 1 a sweep either re-gates (no marker) or — with no adapter — only marks.
+    if (Boolean(input.requestRegate) && !target.alive && !selectedRegate) {
+      selectedRegate = true;
+      if (mode === 'shadow') {
         regate.push(pr.number);
         emit('would-regate', { pr: pr.number, reason, ageHours: Math.floor(ageHours) });
+      } else {
+        try {
+          await input.requestRegate!(pr);
+          regate.push(pr.number);
+          emit('regate-requested', { pr: pr.number, reason, ageHours: Math.floor(ageHours) });
+        } catch (error) {
+          emit('regate-failed', { pr: pr.number, error: String(error) });
+        }
+      }
+      // The marker that used to ride along must buy its own slot — at `cap` 1 there is none left.
+      if (!spend()) {
+        emit('label-deferred-cap', { pr: pr.number, reason, ageHours: Math.floor(ageHours) });
+        continue;
       }
+    }
+    if (mode === 'shadow') {
+      label.push(pr.number);
+      emit('would-label', { pr: pr.number, label: RUN_TTL_MARKER_LABEL, reason, ageHours: Math.floor(ageHours) });
       continue;
     }
     try {
@@ -267,16 +291,6 @@ export async function runRunTtlSweep(input: {
       failed.push(pr.number);
       emit('label-failed', { pr: pr.number, error: String(error) });
     }
-    if (canRegate) {
-      selectedRegate = true;
-      try {
-        await input.requestRegate!(pr);
-        regate.push(pr.number);
-        emit('regate-requested', { pr: pr.number, reason, ageHours: Math.floor(ageHours) });
-      } catch (error) {
-        emit('regate-failed', { pr: pr.number, error: String(error) });
-      }
-    }
   }
   return summary(result());
 }

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,

package/src/self-implement/scope-adjacency.ts

@@ -30,7 +30,9 @@ export function classifyOutOfScope(outsideFiles: readonly string[], declaredPath
 export type ScopeExpansionKind = 'neighbour' | 'caller-or-registration' | 'paired-test' | 'other';
 export interface ScopeExpansionFile { path: string; kind: ScopeExpansionKind }
 export interface ScopeExpansion { files: ScopeExpansionFile[]; count: number }
-export type ScopeStopReason = 'deletion' | 'protected-path' | 'over-cap' | 'name-cap';
+/** Every stop reason, in report order — the one source; the Pod parent (self-implement.ts) reads held results against it. */
+export const SCOPE_STOP_REASONS = ['deletion', 'protected-path', 'over-cap', 'name-cap'] as const;
+export type ScopeStopReason = (typeof SCOPE_STOP_REASONS)[number];
 
 /** Accepted outside files above this count stop the run: past it the change is no longer «the goal, adapted». */
 export const SCOPE_EXPANSION_CAP = 10;