elanous 0.2.38 → 0.2.41

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

@@ -414,12 +414,20 @@ export function runGraphVariantPath(runId: string, dir = runLedgerDir()): string
   return `${runLedgerPath(runId, dir)}.graph.yaml`;
 }
 
+/** 원장에 실린 unit 선언 근거 한 줄 — 경로와 내용 해시뿐이고 본문은 원장에 없다. */
+export interface RunGraphVariantUnitDeclaration {
+  readonly path: string;
+  readonly contentHash: string;
+}
+
 /** 최초 graph variant 선택의 원장 옆 재조회 계약 — 같은 runId·파일이면 같은 id·선택 이유가 돌아온다. */
 export interface RunGraphVariantSelection {
   /** createGraphVariant 가 골 종류·대상 경로 수에서 유도한 최초 variant id. */
   readonly variantId: string;
   /** 그 variant가 최초로 선택된 근거(종류·경로 수 기반) — 저장·재조회가 같은 문자열. */
   readonly reason: string;
+  /** 이 런이 읽은 unit 선언의 경로·내용 해시 — 옛 원장에는 키가 없어 값도 없다(추가 키). */
+  readonly unitDeclarations?: readonly RunGraphVariantUnitDeclaration[];
 }
 
 /** 런 원장 옆 .graph.yaml 을 처음 한 번 쓰고 저장 경로를 돌려준다 — 이미 있으면 덮쓰지 않는다(flag wx). */
@@ -447,9 +455,24 @@ export function loadRunGraphVariant(runId: string, dir = runLedgerDir()): RunGra
     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 };
+  const record = parsed as { variant_id?: unknown; reason?: unknown; unit_declarations?: unknown };
   if (typeof record.variant_id !== 'string' || typeof record.reason !== 'string') return null;
-  return { variantId: record.variant_id, reason: record.reason };
+  const unitDeclarations = parseRunGraphVariantUnitDeclarations(record.unit_declarations);
+  return { variantId: record.variant_id, reason: record.reason,
+    ...(unitDeclarations === undefined ? {} : { unitDeclarations }) };
+}
+
+/** `unit_declarations: [{ path, content_hash }]` 추가 키의 재읽기 — 키가 없거나 비면 근거도 없다. */
+function parseRunGraphVariantUnitDeclarations(value: unknown): RunGraphVariantUnitDeclaration[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const declarations: RunGraphVariantUnitDeclaration[] = [];
+  for (const entry of value) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    const record = entry as { path?: unknown; content_hash?: unknown };
+    if (typeof record.path !== 'string' || typeof record.content_hash !== 'string') continue;
+    declarations.push({ path: record.path, contentHash: record.content_hash });
+  }
+  return declarations.length === 0 ? undefined : declarations;
 }
 
 /**
@@ -719,7 +742,9 @@ export interface RunLedgerCheckedAppendOutcome<T> {
  * 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.
+ * parsing message substrings. `RunLedgerEntryRunIdMismatchError` below is the same
+ * identity violation observed on already-written ledger bytes, so one `instanceof`
+ * covers both producers.
  */
 export class RunLedgerCheckedAppendRunIdMismatchError extends Error {
   readonly reason = 'runId-mismatch' as const;
@@ -731,6 +756,21 @@ export class RunLedgerCheckedAppendRunIdMismatchError extends Error {
   }
 }
 
+/**
+ * Thrown (typed, same `runId-mismatch` reason) when a stored ledger *row* declares a
+ * `runId` other than the one being loaded. The message prefixes the stable reason and keeps
+ * the parser's existing wording, so message-based classifiers (`goal-archive`, the
+ * doctor-compare caller's own regression test) keep recognizing it, while
+ * `decisionRunId`/`lockedRunId` travel as typed fields so no caller has to re-parse it.
+ */
+export class RunLedgerEntryRunIdMismatchError extends RunLedgerCheckedAppendRunIdMismatchError {
+  constructor(decisionRunId: string, lockedRunId: string, readonly lineNumber: number) {
+    super(decisionRunId, lockedRunId);
+    this.name = 'RunLedgerEntryRunIdMismatchError';
+    this.message = `runId-mismatch: invalid run ledger entry at line ${lineNumber}: runId does not match ${lockedRunId}`;
+  }
+}
+
 /**
  * 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
@@ -896,7 +936,7 @@ function parseRunLedgerEntry(line: string, lineNumber: number, expectedRunId: st
     throw new Error(`invalid run ledger entry at line ${lineNumber}: expected optional timestamp, goalId, shard identity, runId, event, and object data`);
   }
   if (entry.runId !== expectedRunId) {
-    throw new Error(`invalid run ledger entry at line ${lineNumber}: runId does not match ${expectedRunId}`);
+    throw new RunLedgerEntryRunIdMismatchError(entry.runId, expectedRunId, lineNumber);
   }
   return entry as RunLedgerEntry;
 }
@@ -1154,15 +1194,24 @@ export interface GraphAdaptReport {
   nonAdapted: { landed: number; denominator: number; rate: number | null };
   excludedCount: number;
   exclusionReasons: Record<string, number>;
+  unmeasuredCount: number;
+  unmeasuredReasons: Record<string, number>;
+  window: { since: string | null; until: string | null };
 }
 
 /** Measure only producer-observed traversals and variant applications; never activate adaptation. */
-export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoot()): GraphAdaptReport {
+export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoot(), window: { since?: string; until?: string } = {}): 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 unmeasuredReasons: Record<string, number> = {};
   const exclude = (reason: string): void => { exclusionReasons[reason] = (exclusionReasons[reason] ?? 0) + 1; };
+  const unmeasured = (reason: string): void => { unmeasuredReasons[reason] = (unmeasuredReasons[reason] ?? 0) + 1; };
+  const since = window.since === undefined ? null : Date.parse(window.since);
+  const until = window.until === undefined ? null : Date.parse(window.until);
+  if ((since !== null && !Number.isFinite(since)) || (until !== null && !Number.isFinite(until)) ||
+    (since !== null && until !== null && since > until)) throw new Error('invalid adaptation measurement window');
   let unitCallCount = 0;
   let adaptationCount = 0;
   let fileNames: string[];
@@ -1181,6 +1230,15 @@ export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoo
     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 start = ledger.find(entry => entry.event === 'start');
+    const startedAt = start && typeof start.timestamp === 'string' ? Date.parse(start.timestamp) : NaN;
+    if (!Number.isFinite(startedAt)) { unmeasured('start-time-missing-or-invalid'); continue; }
+    if ((since !== null && startedAt < since) || (until !== null && startedAt >= until)) { exclude('outside-start-window'); continue; }
+    const lastStatus = [...ledger].reverse().find(entry => entry.event === 'run-status');
+    if (lastStatus && !['completed', 'failed', 'cancelled'].includes(String(lastStatus.data.runStatus))) {
+      exclude('in-flight'); continue;
+    }
+    if (!lastStatus && !ledger.some(entry => entry.event === 'merged')) { exclude('in-flight'); 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))) {
@@ -1189,12 +1247,13 @@ export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoo
     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; }
+      unmeasured((error as NodeJS.ErrnoException).code === 'ENOENT' ? 'graph-run-missing' : '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;
+    if (!recorded || recorded.runId !== runId || recorded.graphId !== 'self-implement' ||
+      (recorded.unitCalls !== undefined && !Array.isArray(recorded.unitCalls))) {
+      unmeasured('graph-run-invalid'); continue;
     }
     const merge = [...ledger].reverse().find(entry => entry.event === 'merged');
     if (merge && typeof merge.data.merged !== 'boolean') { exclude('landing-invalid'); continue; }
@@ -1210,7 +1269,9 @@ export function queryGraphAdaptReport(goalId: string, stateDir = elanousStateRoo
   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 };
+    excludedCount: Object.values(exclusionReasons).reduce((total, count) => total + count, 0), exclusionReasons,
+    unmeasuredCount: Object.values(unmeasuredReasons).reduce((total, count) => total + count, 0), unmeasuredReasons,
+    window: { since: window.since ?? null, until: window.until ?? null } };
 }
 
 export interface GoalSourceDistributionQuery {
@@ -1773,6 +1834,8 @@ export interface UnfinishedRunLedgerQuery {
    * 엉킨 visit 을 셀 수 있게 하는 값이다.
    */
   orphanUnitVisitCount?: number;
+  /** True when a caller deadline stopped the scan before every ledger was visited. */
+  timedOut?: boolean;
   scope: 'self-implement-run-ledger';
   note: string;
 }
@@ -1786,6 +1849,8 @@ export interface UnfinishedRunLedgerQueryOptions {
   noCache?: boolean;
   /** ⛔ 「도는 중」으로 볼 마지막 활동 나이(ms). 호출자가 준다 — 이 모듈이 새 수를 정하지 않는다. */
   liveWindowMs?: number;
+  /** Absolute wall-clock deadline; when reached, return the rows scanned so far as partial evidence. */
+  deadlineAtMs?: number;
 }
 
 const UNFINISHED_RUN_LEDGER_NOTE = 'Read-only scan of the specified run-ledger directory. A terminal-status-missing ledger is not the same as an unreadable ledger; planned paths are extracted only from a goal document matched by the final hyphen-separated branch segment.';
@@ -2432,7 +2497,12 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
   let callerCwdCount = 0;
   // ⭐ 터미널 원장도 «세기만» 한다 — entries 로 되살리지 않는다(부활 금지).
   let orphanUnitVisitCount = 0;
+  let timedOut = false;
   for (const fileName of fileNames) {
+    if (options.deadlineAtMs !== undefined && Date.now() >= options.deadlineAtMs) {
+      timedOut = true;
+      break;
+    }
     const runId = runIdFromCanonicalLedgerFile(fileName);
     if (!runId) continue;
     scanned += 1;
@@ -2517,9 +2587,10 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
     indexOrigin,
     indexHits,
     ms: Date.now() - startedAt,
+    ...(timedOut ? { timedOut: true, stopReason: 'deadline-exceeded' } : {}),
   });
   if (options.path === undefined) {
-    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 };
+    return { entries, ledgerDirectory: dir, goalsDirectory: goalsDir, unreadableLedgerCount, orphanUnitVisitCount, ledgerDirectoryMissing: false, terminalByTrailingRunStatus, cacheHits, cacheMisses, indexHits, indexOrigin, ...(timedOut ? { timedOut: true } : {}), 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'
@@ -2545,6 +2616,7 @@ export function queryUnfinishedRunLedgers(options: UnfinishedRunLedgerQueryOptio
     pathFilter,
     matchingPathCount: matchingEntries.length,
     unknownPathCount: unknownEntries.length,
+    ...(timedOut ? { timedOut: true } : {}),
     scope: 'self-implement-run-ledger',
     note: UNFINISHED_RUN_LEDGER_NOTE,
   };
@@ -2581,6 +2653,8 @@ export interface FederatedUnfinishedRunLedgerQuery {
   cacheMisses?: number;
   /** Hits served by the persisted cross-process scan index (subset of cacheHits). */
   indexHits?: number;
+  timedOut?: boolean;
+  stalledStage?: 'ledger-scan' | 'cross-directory-reconciliation';
   pathFilter?: string;
   matchingPathCount?: number;
   unknownPathCount?: number;
@@ -2602,6 +2676,7 @@ export interface FederatedUnfinishedRunLedgerQueryOptions {
    * canonical *.jsonl plus the cross-directory unfinished-runId reconciliation.
    */
   runIds?: readonly string[];
+  deadlineAtMs?: number;
 }
 
 const FEDERATED_UNFINISHED_RUN_LEDGER_NOTE = 'Read-only union of run-ledger directories selected by the same --all/--include-test target policy as elanous logs. Each row carries its physical ledger directory because instance names can identify multiple state roots.';
@@ -2621,12 +2696,19 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
   let cacheHits = 0;
   let cacheMisses = 0;
   let indexHits = 0;
+  let timedOut = false;
+  let stalledStage: FederatedUnfinishedRunLedgerQuery['stalledStage'];
   const recordDirectoryFailure = (kind: FederatedLedgerDirectoryFailureKind): void => {
     if (kind === 'missing') missingLedgerDirectoryCount += 1;
     else if (kind === 'unreadable') unreadableLedgerDirectoryAccessCount += 1;
     else indeterminateLedgerDirectoryCount += 1;
   };
   for (const ledgerDirectory of candidateLedgerDirectories) {
+    if (options.deadlineAtMs !== undefined && Date.now() >= options.deadlineAtMs) {
+      timedOut = true;
+      stalledStage = 'ledger-scan';
+      break;
+    }
     try {
       const listDirectory = options.list ?? readdirSync;
       const list = requestedRunIds === undefined
@@ -2635,7 +2717,7 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
           const runId = runIdFromCanonicalLedgerFile(fileName);
           return runId !== null && requestedRunIds.has(runId);
         });
-      const result = queryUnfinishedRunLedgers({ dir: ledgerDirectory, goalsDir: goalsDirectory, ...(options.path === undefined ? {} : { path: options.path }), ...(list === undefined ? {} : { list }), noCache: options.noCache });
+      const result = queryUnfinishedRunLedgers({ dir: ledgerDirectory, goalsDir: goalsDirectory, ...(options.path === undefined ? {} : { path: options.path }), ...(list === undefined ? {} : { list }), noCache: options.noCache, deadlineAtMs: options.deadlineAtMs });
       if (result.ledgerDirectoryMissing) {
         recordDirectoryFailure('missing');
         continue;
@@ -2647,10 +2729,15 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
       cacheHits += result.cacheHits ?? 0;
       cacheMisses += result.cacheMisses ?? 0;
       indexHits += result.indexHits ?? 0;
+      if (result.timedOut) {
+        timedOut = true;
+        stalledStage = 'ledger-scan';
+      }
       entries.push(...result.entries.map((entry) => ({ ...entry, ledgerDirectory })));
     } catch (error) {
       recordDirectoryFailure(classifyFederatedLedgerDirectoryReadFailure(error));
     }
+    if (timedOut) break;
   }
   const unreadableLedgerDirectoryCount = missingLedgerDirectoryCount + unreadableLedgerDirectoryAccessCount + indeterminateLedgerDirectoryCount;
   // ⛔⭐⭐ 가로 대조 — 원장 «하나»만 보고 「미완」이라 말하지 않는다 (2026-08-11 · 🅣 71차 실측).
@@ -2660,20 +2747,28 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
   //   📏 실측(2026-08-11): 미완 57 중 ***7*** 이 다른 원장에 종결을 갖고 있었다.
   // ⛔ 판정 술어는 스캐너와 «같은 것»을 쓴다(`run-status` 또는 `terminal`) — 어휘를 새로 만들지 않는다.
   const terminatedElsewhere = new Set<string>();
+  const reconciledRunIds = new Set<string>();
   // Runs carrying a non-blocking request record never drop out of the union: their requestId
   // reason·next must survive restarts and cross-directory reconciliation alike.
   const unfinishedRunIds = requestedRunIds === undefined
     ? new Set(entries.filter((entry) => !entry.nonBlocking).map((entry) => entry.runId))
     : new Set([...requestedRunIds].filter((runId) => entries.some((entry) => entry.runId === runId && !entry.nonBlocking)));
-  for (const runId of unfinishedRunIds) {
+  for (const runId of timedOut ? [] : unfinishedRunIds) {
+    if (options.deadlineAtMs !== undefined && Date.now() >= options.deadlineAtMs) {
+      timedOut = true;
+      stalledStage = 'cross-directory-reconciliation';
+      break;
+    }
     for (const ledgerDirectory of ledgerDirectories) {
       try {
         const reconciliationIndex = options.noCache ? undefined : loadRunLedgerScanIndex(ledgerDirectory);
         if (readUnfinishedLedgerFacts(runId, ledgerDirectory, undefined, options.noCache, reconciliationIndex).facts.terminal) { terminatedElsewhere.add(runId); break; }
       } catch { /* An absent or unreadable sibling cannot establish termination. */ }
     }
+    reconciledRunIds.add(runId);
   }
-  const reconciledEntries = entries.filter((entry) => !terminatedElsewhere.has(entry.runId));
+  const reconciledEntries = entries.filter((entry) => !terminatedElsewhere.has(entry.runId)
+    && (stalledStage !== 'cross-directory-reconciliation' || reconciledRunIds.has(entry.runId)));
   const reconciledTerminatedElsewhereCount = entries.length - reconciledEntries.length;
   entries.length = 0;
   entries.push(...reconciledEntries);
@@ -2691,6 +2786,7 @@ export function queryFederatedUnfinishedRunLedgers(options: FederatedUnfinishedR
     cacheHits,
     cacheMisses,
     indexHits,
+    ...(timedOut ? { timedOut: true, stalledStage } : {}),
     ...(options.path === undefined ? {} : { pathFilter: options.path, matchingPathCount, unknownPathCount }),
     scope: 'self-implement-run-ledger-federated',
     note: FEDERATED_UNFINISHED_RUN_LEDGER_NOTE,

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

@@ -16,7 +16,7 @@ import type { PodChildEvidence } from '../task-orchestrator/surfaces/self-implem
 /** 닫힌 목록 — 못 고르면 `unclassified`. */
 export const RUN_STOP_CLASSES = [
   'env-unrelated', 'main-sync', 'pod-died', 'pod-vanished', 'review-repeat',
-  'review-out-of-scope', 'scope-escape', 'evidence-uncovered', 'fabric', 'launch-failed', 'gate-failed', 'unclassified',
+  'review-out-of-scope', 'review-budget-exhausted', 'scope-escape', 'evidence-uncovered', 'fabric', 'launch-failed', 'gate-failed', 'unclassified',
 ] as const;
 export type RunStopClass = typeof RUN_STOP_CLASSES[number];
 
@@ -40,6 +40,15 @@ export interface RunStopRecord {
 export const RUN_STOP_EVENT = 'stop';
 export const RUN_STOP_CAUSE_MAX = 120;
 
+type RunStopListener = (entry: RunLedgerEntry) => void;
+const runStopListeners = new Set<RunStopListener>();
+
+/** Subscribe to live terminal run-stop facts. The durable ledger remains the source of truth. */
+export function onRunStop(listener: RunStopListener): () => void {
+  runStopListeners.add(listener);
+  return () => { runStopListeners.delete(listener); };
+}
+
 export interface RunStopInput {
   runId: string;
   goalId?: string;
@@ -72,7 +81,8 @@ export function classifyMergeHoldStop(mergeReason: string | undefined): RunStopC
   const reason = mergeReason ?? '';
   if (reason.startsWith('main-sync') || reason === 'default-branch-unresolved') return 'main-sync';
   if (reason === 'required-evidence-uncovered') return 'evidence-uncovered';
-  if (reason === 'review-must-fix' || reason === 'review-warn-with-must-fix' || reason.startsWith('review-budget')) return 'review-repeat';
+  if (reason.startsWith('review-budget')) return 'review-budget-exhausted';
+  if (reason === 'review-must-fix' || reason === 'review-warn-with-must-fix') return 'review-repeat';
   if (reason.startsWith('review-diff') || reason === 'no-real-review') return 'review-out-of-scope';
   return 'unclassified';
 }
@@ -87,6 +97,24 @@ export function classifyPodExitStop(reason: string | undefined, stage?: string):
   }
 }
 
+/** Terminal implementation failures are classified only after the inner repair/round budget has ended. */
+export function classifyTerminalHarnessFailure(input: {
+  stage: string;
+  mergeReason?: string;
+  abandonedClassification?: string;
+  providerErrorCategory?: string;
+  supervisorVerdict?: string;
+}): RunStopClass {
+  if (input.mergeReason) return classifyMergeHoldStop(input.mergeReason);
+  if (input.providerErrorCategory === 'credential' || input.abandonedClassification === 'credential-failure') return 'launch-failed';
+  if (input.abandonedClassification === 'report-deficit') return 'pod-died';
+  if (input.stage === 'gate-failed') return 'gate-failed';
+  if (input.stage === 'review-blocked' || input.stage === 'no-changes' || input.supervisorVerdict === 'UNCONVERGEABLE') return 'review-repeat';
+  if (input.stage === 'merge-conflict') return 'main-sync';
+  if (input.stage === 'timed-out') return 'pod-died';
+  return 'unclassified';
+}
+
 /** 이 프로세스에서 stop 을 이미 쓴 런 — 한 런이 두 자리(예: draft PR 실패 ⊕ aborted)에서 두 줄을 쓰지 않게. */
 const recordedThisProcess = new Set<string>();
 const RECORDED_MAX = 4096;
@@ -121,6 +149,9 @@ export function recordRunStop(input: RunStopInput, write: RunLedgerWriter = appe
   write(entry);
   if (recordedThisProcess.size >= RECORDED_MAX) recordedThisProcess.clear();
   recordedThisProcess.add(input.runId);
+  for (const listener of runStopListeners) {
+    try { listener(entry); } catch { /* wake consumers cannot change run outcome */ }
+  }
   try {
     debug.log('self-implement.run-stop', 'recorded', { runId: input.runId, site: input.site ?? null, ...record, requestedClass: input.class ?? null });
   } catch { /* observation is fail-soft */ }

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

@@ -116,6 +116,8 @@ export interface RunningRunsResult {
   };
   /** Additive phase-store observability; queryRunningRuns always supplies this value. */
   readonly phases?: RunningRunsPhaseStoreObservation;
+  /** Present when a caller time budget stopped one observation stage before full coverage. */
+  readonly stalled?: { readonly stage: 'ledger-scan' | 'cross-directory-reconciliation' | 'pty-observation' | 'phase-observation' | 'launch-parent-classification'; readonly reason: 'deadline-exceeded' };
 }
 
 export interface QueriedRunningRunsResult extends RunningRunsResult {
@@ -263,7 +265,7 @@ export interface RunningRunsQueryObservation {
 }
 
 export interface RunningRunsQueryDeps {
-  readonly queryLedgers?: (options: { includeTest?: boolean; ledgerDirectories?: readonly string[]; runIds?: readonly string[]; noCache?: boolean }) => FederatedUnfinishedRunLedgerQuery;
+  readonly queryLedgers?: (options: { includeTest?: boolean; ledgerDirectories?: readonly string[]; runIds?: readonly string[]; noCache?: boolean; deadlineAtMs?: number }) => FederatedUnfinishedRunLedgerQuery;
   readonly ledgerDirectories?: (options: { includeTest?: boolean }) => readonly string[];
   readonly ptyTargets?: (options: { includeTest?: boolean }) => readonly { name: string; dbPath: string }[];
   readonly readPtyRows?: typeof listPtyManifestRowsAt;
@@ -303,6 +305,7 @@ export function assessLingeringLaunchParents(
   isProcessAlive: (pid: number) => boolean,
   processStartTime: (pid: number) => number | null,
   ledgerObservation?: Pick<RunningRunsLedgerObservation, 'unreadableLedgerCount' | 'unreadableLedgerDirectoryCount' | 'unreadableLedgerDirectoryAccessCount' | 'indeterminateLedgerDirectoryCount'>,
+  deadlineAtMs?: number,
 ): LingeringLaunchParentAssessment {
   if (!ledgerObservation || hasUnreadableLedgerObservation(ledgerObservation)) return { observation: 'indeterminate' };
 
@@ -316,6 +319,7 @@ export function assessLingeringLaunchParents(
   let reusedPidCount = 0;
   try {
     for (const [runId, ledgerDirectory] of terminatedRunDirectories) {
+      if (deadlineAtMs !== undefined && Date.now() >= deadlineAtMs) return { observation: 'indeterminate' };
       const run = loadRun(runId, ledgerDirectory);
       const pid = run?.pid;
       if (typeof pid !== 'number' || !Number.isInteger(pid) || pid <= 0) {
@@ -454,7 +458,7 @@ export function distinctPhysicalLedgerDirectories(
   return distinct;
 }
 
-export function queryRunningRuns(options: { includeTest?: boolean; runIds?: readonly string[]; caller?: string; noCache?: boolean } = {}, deps: RunningRunsQueryDeps = {}): QueriedRunningRunsResult {
+export function queryRunningRuns(options: { includeTest?: boolean; runIds?: readonly string[]; caller?: string; noCache?: boolean; timeBudgetMs?: number } = {}, deps: RunningRunsQueryDeps = {}): QueriedRunningRunsResult {
   const directoryFailures = new Map<string, ReturnType<typeof classifyFederatedLedgerDirectoryReadFailure>>();
   const queryLedgers = deps.queryLedgers ?? ((queryOptions: Parameters<typeof queryFederatedUnfinishedRunLedgers>[0]) => queryFederatedUnfinishedRunLedgers({
     ...queryOptions,
@@ -480,6 +484,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();
+  const deadlineAtMs = options.timeBudgetMs === undefined ? undefined : startedAt + Math.max(0, options.timeBudgetMs);
+  let stalled: RunningRunsResult['stalled'];
+  const deadlineExceeded = (): boolean => deadlineAtMs !== undefined && Date.now() >= deadlineAtMs;
   // ID 조회 배선 — src/index.ts의 `self running-runs [runId]` 액션이 넘겨준 options.runIds 를 이 조회가 소비한다:
   // 정의된 runIds 는 연합 원장 질의 전달·엔트리·pty 관측을 모두 그 runId 들로 한정한다.
   const requestedRunIdSet = options.runIds === undefined ? undefined : new Set(options.runIds);
@@ -509,20 +516,25 @@ export function queryRunningRuns(options: { includeTest?: boolean; runIds?: read
     try {
       const requestedRunIds = options.runIds === undefined ? {} : { runIds: options.runIds };
       const cacheOption = options.noCache === undefined ? {} : { noCache: options.noCache };
+      const deadlineOption = deadlineAtMs === undefined ? {} : { deadlineAtMs };
       ledger = collectLedgerDirectories
-        ? queryLedgers({ includeTest: options.includeTest, ledgerDirectories: collectedLedgerDirectories, ...requestedRunIds, ...cacheOption })
-        : queryLedgers({ includeTest: options.includeTest, ...requestedRunIds, ...cacheOption });
+        ? queryLedgers({ includeTest: options.includeTest, ledgerDirectories: collectedLedgerDirectories, ...requestedRunIds, ...cacheOption, ...deadlineOption })
+        : queryLedgers({ includeTest: options.includeTest, ...requestedRunIds, ...cacheOption, ...deadlineOption });
       ledgerDirectoryCount = ledger.ledgerDirectories.length;
       ledgerEntryCount = ledger.entries.length;
       cacheHits = ledger.cacheHits ?? 0;
       cacheMisses = ledger.cacheMisses ?? 0;
+      if (ledger.timedOut) stalled = { stage: ledger.stalledStage ?? 'ledger-scan', reason: 'deadline-exceeded' };
     } finally {
       ledgerReadElapsedMs = Date.now() - ledgerReadStartedAt;
     }
     const screenProcessReadStartedAt = Date.now();
     let pty: FederatedPtyListing;
     try {
-      pty = listPtyRefs(targets({ includeTest: options.includeTest }), readPtyRows);
+      if (deadlineExceeded()) {
+        stalled ??= { stage: 'pty-observation', reason: 'deadline-exceeded' };
+        pty = { refs: [], unreadable: ['<skipped:deadline-exceeded>'] };
+      } else pty = listPtyRefs(targets({ includeTest: options.includeTest }), readPtyRows);
     } finally {
       screenProcessReadElapsedMs = Date.now() - screenProcessReadStartedAt;
     }
@@ -538,7 +550,8 @@ export function queryRunningRuns(options: { includeTest?: boolean; runIds?: read
     let observedPhases: ObservedRunPhases = { events: [], targetCount: 0, unreadableTargets: [] };
     const stageStoreReadStartedAt = Date.now();
     try {
-      observedPhases = readRunPhases({ includeTest: options.includeTest }, runIds);
+      if (deadlineExceeded()) stalled ??= { stage: 'phase-observation', reason: 'deadline-exceeded' };
+      else observedPhases = readRunPhases({ includeTest: options.includeTest }, runIds);
     } catch {
       observedPhases = { events: [], targetCount: 1, unreadableTargets: ['phase-query'] };
     } finally {
@@ -583,13 +596,23 @@ export function queryRunningRuns(options: { includeTest?: boolean; runIds?: read
     const launchParentClassificationStartedAt = Date.now();
     let lingeringLaunchParents: LingeringLaunchParentAssessment;
     try {
-      lingeringLaunchParents = assessLingeringLaunchParents(
-        scopedLedgerEntries, loadRun, isProcessAlive, processStartTime, ledger,
-      );
+      if (deadlineExceeded()) {
+        stalled ??= { stage: 'launch-parent-classification', reason: 'deadline-exceeded' };
+        lingeringLaunchParents = { observation: 'indeterminate' };
+      } else {
+        lingeringLaunchParents = assessLingeringLaunchParents(
+          scopedLedgerEntries, loadRun, isProcessAlive, processStartTime, ledger, deadlineAtMs,
+        );
+        if (deadlineExceeded()) stalled ??= { stage: 'launch-parent-classification', reason: 'deadline-exceeded' };
+      }
     } finally {
       launchParentClassificationElapsedMs = Date.now() - launchParentClassificationStartedAt;
     }
-    return { ...result, completeness, unreadable, count, observation, quantities: quantitySummary({ ...result, observation }), lingeringLaunchParents: lingeringLaunchParents!, ledger: { ledgerDirectories: ledger.ledgerDirectories, unreadableLedgerCount: ledger.unreadableLedgerCount, unreadableLedgerDirectoryCount: ledger.unreadableLedgerDirectoryCount, missingLedgerDirectoryCount: ledger.missingLedgerDirectoryCount, unreadableLedgerDirectoryAccessCount: ledger.unreadableLedgerDirectoryAccessCount, indeterminateLedgerDirectoryCount: ledger.indeterminateLedgerDirectoryCount, cacheHits, cacheMisses }, phases: phaseStoreObservation(observedPhases) };
+    const finalCompleteness = hasUnreadableLedgerObservation(ledger) || stalled ? 'partial' : 'complete';
+    const finalCount: RunningRunsCount = finalCompleteness === 'partial'
+      ? { count: null, lowerBound: result.counts.running + result.counts['probable-running'], unreadable }
+      : result.counts.running + result.counts['probable-running'];
+    return { ...result, completeness: finalCompleteness, unreadable, count: finalCount, observation, quantities: quantitySummary({ ...result, observation }), lingeringLaunchParents: lingeringLaunchParents!, ledger: { ledgerDirectories: ledger.ledgerDirectories, unreadableLedgerCount: ledger.unreadableLedgerCount, unreadableLedgerDirectoryCount: ledger.unreadableLedgerDirectoryCount, missingLedgerDirectoryCount: ledger.missingLedgerDirectoryCount, unreadableLedgerDirectoryAccessCount: ledger.unreadableLedgerDirectoryAccessCount, indeterminateLedgerDirectoryCount: ledger.indeterminateLedgerDirectoryCount, cacheHits, cacheMisses }, phases: phaseStoreObservation(observedPhases), ...(stalled ? { stalled } : {}) };
   } finally {
     try {
       observeQuery({
@@ -614,7 +637,7 @@ export function queryRunningRuns(options: { includeTest?: boolean; runIds?: read
 
 export function isPartialRunningRuns(result: RunningRunsResult): boolean {
   return (result.count !== undefined && typeof result.count !== 'number' && result.count.count === null)
-    || result.completeness === 'partial' || hasUnreadableLedgerObservation(result.ledger) || (result.unreadable?.length ?? 0) > 0;
+    || result.completeness === 'partial' || result.stalled !== undefined || hasUnreadableLedgerObservation(result.ledger) || (result.unreadable?.length ?? 0) > 0;
 }
 
 function runningRunsLowerBound(result: RunningRunsResult): number {
@@ -670,7 +693,7 @@ function formatElapsed(ms: number): string {
 export function renderRunProgressTable(result: RunningRunsResult, nowMs: number = Date.now()): string {
   const partial = isPartialRunningRuns(result);
   const header = partial
-    ? `부분 관측 — 최소 ${runningRunsLowerBound(result)} (읽지 못한 원장: ${runningRunsUnreadable(result).map((item) => `${item.dir}:${item.reason}`).join(',') || '목록 미관측'})`
+    ? `부분 관측 — 최소 ${runningRunsLowerBound(result)} (${result.stalled ? `중단 단계 ${result.stalled.stage} · 사유 ${result.stalled.reason}` : `읽지 못한 원장: ${runningRunsUnreadable(result).map((item) => `${item.dir}:${item.reason}`).join(',') || '목록 미관측'}`})`
     : `도는 런 ${result.counts.running + result.counts['probable-running']} (확인 ${result.counts.running} · 추정 ${result.counts['probable-running']})`;
   const rows = buildRunProgressRows(result, nowMs).map((row) => {
     const phaseUnreadable = row.phaseObservation === 'unreadable' || row.phaseObservation === 'partially-unreadable';

package/src/self-implement/seams.ts

@@ -2236,7 +2236,10 @@ export function defaultSeams(o: DefaultSeamsOptions = {}): SelfImplementSeams {
       };
       if (failedTest) {
         const worktreeLog = failedTest.output ?? '';
-        const failedFiles = [...new Set(extractGateTestFailures(worktreeLog)
+        // A supplied gate runner can report a virtual checkout, just like gate-cli's injected runner.
+        const currentFileExists = o.runIntegrityGate ? undefined : (file: string) => existsSync(resolve(cwd, file));
+        const worktreeFailures = extractGateTestFailures(worktreeLog, currentFileExists);
+        const failedFiles = [...new Set(worktreeFailures
           .flatMap((failure) => failure.file ? [failure.file] : []))];
         // 워크트리와 같은 묶음으로 베이스라인을 돌려 파일 간 간섭을 재현한다. 스코프가 없으면 실패 파일로 폴백.
         const testArgs = gateOpts.testArgs;
@@ -2246,14 +2249,14 @@ export function defaultSeams(o: DefaultSeamsOptions = {}): SelfImplementSeams {
         const baseline = (o.runGateBaseline ?? runGateBaseline)(cwd, baselineFiles, baselineRefs.get(cwd));
         const rerun = (o.rerunBunTimeoutFailures ?? rerunBunTimeoutFailures)(
           cwd,
-          extractGateTestFailures(worktreeLog),
+          worktreeFailures,
           undefined,
           baseline.status === 'unknown' ? undefined : (baseline.output ?? ''),
           baseline.missingAtBase ?? [],
         );
         const rerunObservations = rerun instanceof Map ? rerun : rerun.observations;
         const rerunNotRun = rerun instanceof Map ? 0 : rerun.rerunNotRun;
-        const report = buildGateBaselineReport(worktreeLog, baseline, rerunObservations, rerunNotRun);
+        const report = buildGateBaselineReport(worktreeLog, baseline, rerunObservations, rerunNotRun, currentFileExists);
         baselineReport = report;
         baselineFailures = report.failures;
         const unknownReason = baseline.unknownReason;