elanous 0.2.40 → 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;
 }
 
 /**
@@ -1811,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;
 }
@@ -1824,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.';
@@ -2470,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;
@@ -2555,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'
@@ -2583,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,
   };
@@ -2619,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;
@@ -2640,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.';
@@ -2659,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
@@ -2673,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;
@@ -2685,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차 실측).
@@ -2698,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);
@@ -2729,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];
 
@@ -81,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';
 }
@@ -96,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;

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/self-implement-cli.ts

@@ -20,6 +20,7 @@ import { resolveObserveOnlyDecision } from './observe-only.js';
 import { getUserConfig } from '../user-config.js';
 import { resolveAutoReview } from './context-capsule.js';
 import { readDecomposeProposals } from '../self-dev/decompose-proposal.js';
+import { tracedPathReferences } from './goal-author.js';
 
 /** self implement CLI 옵션(commander) — `--no-draft` 는 draft:false 로, `--max-wait` 는 문자열로 도착. */
 export interface SelfImplementCliOpts {
@@ -65,6 +66,12 @@ export interface SelfImplementCliDeps {
   resolveWantAutoReview?: (flag: boolean) => boolean | Promise<boolean>;
   /** reroute 실행(테스트 주입). 기본 executeSelfImplementReroute. */
   executeReroute?: typeof executeSelfImplementReroute;
+  /** Capability seam: false disables reason-repair reruns; omitted means available because this CLI has a production rerouter. */
+  reasonRepairExecutionAvailable?: boolean;
+  /** Supervisor side-effect seams for focused runtime tests. */
+  taskAgentShadow?: false;
+  taskAgentRejudge?: false;
+  sweepPendingMerges?: typeof import('./frozen-merges.js').sweepFrozenMerges;
   /** ⭐ 산출물의 «눈» 심(테스트 주입). 기본은 실제 브라우저 검증(`observeDeliverables`).
    *  ⛔ 심이 «없으면» 이 배선을 시험으로 재현할 수 없고, 그러면 「손으로 돌려 봤다」만 남는다
    *  — 그것은 「그때 됐다」이지 「앞으로도 된다」가 아니다(리뷰 #10556 must-fix). */
@@ -124,11 +131,25 @@ export interface SingleRunSuperviseOptions {
 type SelfImplementResultWithProposalMetadata = SelfImplementResult
   & Pick<SelfDevJobResult, 'decomposeProposal' | 'goalPlanRevision'>;
 
-export function singleRunAsJobResult(feature: string, r: SelfImplementResultWithProposalMetadata): SupervisorJobResult {
+/**
+ * NEEDS-HUMAN-REASON-REPAIR — 실행 범위 가드가 «대상 밖»으로 잰 변경을 감독 판정 재료로 옮긴다.
+ * ⛔ 가드가 잰 이름만 쓴다 — 결과에 없으면 빈 배열이고, 「없다」를 지어내지 않는다.
+ */
+function measuredOutsideTargetFiles(r: SelfImplementResult): string[] {
+  return [...new Set([
+    ...(r.outOfScopeEdits ?? []),
+    ...(r.scopeExpansion?.files.map((file) => file.path) ?? []),
+  ])];
+}
+
+export function singleRunAsJobResult(feature: string, r: SelfImplementResultWithProposalMetadata, includeDeclaredTargets = false): SupervisorJobResult {
+  const outsideTargetFiles = measuredOutsideTargetFiles(r);
+  const targetPaths = includeDeclaredTargets ? tracedPathReferences(feature).map(({ path }) => path) : [];
   return {
     taskId: r.runId,
     runId: r.runId,
     feature,
+    ...(targetPaths.length ? { targetPaths } : {}),
     status: r.ok ? 'done' : 'failed',
     stage: r.stage,
     ...(!r.ok && r.detail ? { error: { message: r.detail } } : {}),
@@ -145,6 +166,7 @@ export function singleRunAsJobResult(feature: string, r: SelfImplementResultWith
     ...(r.abandonedClassification?.classification
       ? { failureClassification: r.abandonedClassification.classification } : {}),
     ...(r.decomposeProposal ? { decomposeProposal: r.decomposeProposal } : {}),
+    ...(outsideTargetFiles.length > 0 ? { outsideTargetFiles } : {}),
     ...(r.rework ? { rework: r.rework } : {}),
     ...(r.review?.reviewed && r.review.mustFix?.length ? { reviewMustFix: r.review.mustFix } : {}),
     ...(r.goalPlanRevision ? { goalPlanRevision: r.goalPlanRevision } : {}),
@@ -268,10 +290,20 @@ export async function runSelfImplementCliCommand(
           }
         : undefined;
 
-      const initialJob = singleRunAsJobResult(feature, result);
+      const reasonRepairEnabled = getUserConfig().tools.selfImplement.supervisor?.reasonRepair === true
+        && (deps.reasonRepairExecutionAvailable ?? true);
+      const initialJob = singleRunAsJobResult(feature, result, reasonRepairEnabled);
+      // NEEDS-HUMAN-REASON-REPAIR — 사유별 수복 골을 «실행하는» 경로인가.
+      //   ⛔ 아래 rerun 이 invocation.repairGoals[taskId] 를 spec.input.text 로 그대로 실행하므로 «그렇다».
+      //   ⇒ 그래서 이 감독 경로는 사유별 수복(needs-human 전 1회)을 연다.
+      const repairGoalExecution = true;
       await superviseRun({
         initial: [initialJob],
-        repairGoalExecution: true,
+        ...(deps.taskAgentShadow === false ? { taskAgentShadow: false } : {}),
+        ...(deps.taskAgentRejudge === false ? { taskAgentRejudge: false } : {}),
+        ...(deps.sweepPendingMerges ? { sweepPendingMerges: deps.sweepPendingMerges } : {}),
+        repairGoalExecution,
+        needsHumanReasonRepairExecution: reasonRepairEnabled,
         limits,
         ...(deliverableEye ? { observeDeliverables: deliverableEye } : {}),
         ...(opts.supervise.onDecision ? { onDecision: opts.supervise.onDecision } : {}),
@@ -285,7 +317,7 @@ export async function runSelfImplementCliCommand(
           const next = await exec(repairGoal ? { ...spec, input: { ...spec.input, text: repairGoal } } : spec, pipelineDeps ? { pipelineDeps } : undefined);
           result = attachGoalPlanRevisionObservation(next.result, deps);
           exitCode = next.exitCode;
-          return [{ ...singleRunAsJobResult(feature, result), taskId: initialJob.taskId }];
+          return [{ ...singleRunAsJobResult(feature, result, reasonRepairEnabled), taskId: initialJob.taskId }];
         },
       });
     }

package/src/self-implement/stop-autoheal-operational.ts

@@ -0,0 +1,43 @@
+/** Production STOP-AUTOHEAL actions. A missing prerequisite is a failed action, never a healed run. */
+import { spawnSync } from 'node:child_process';
+import { SPAWN_SYNC_MAX_BUFFER } from '../util/spawn-sync-output.js';
+import { runHostRegate, type HostRegateInput, type HostRegateResult } from './host-regate.js';
+import type { AutohealActions, AutohealContext } from './stop-autoheal.js';
+
+type PrHead = { headRefOid?: string; state?: string; isDraft?: boolean };
+export interface OperationalAutohealDeps {
+  repoRoot: string;
+  readPr?: (number: number, repoRoot: string) => PrHead | null;
+  regate?: (input: HostRegateInput) => Promise<HostRegateResult>;
+}
+
+function prFromEvidence(ctx: AutohealContext): number | null {
+  const match = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/([1-9]\d*)\/?$/.exec(ctx.record.evidenceRef);
+  return match ? Number(match[1]) : null;
+}
+
+function readPr(number: number, repoRoot: string): PrHead | null {
+  const result = spawnSync('gh', ['pr', 'view', String(number), '--json', 'headRefOid,state,isDraft'], {
+    cwd: repoRoot, encoding: 'utf8', timeout: 30_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER,
+  });
+  if (result.status !== 0) return null;
+  try { return JSON.parse(result.stdout) as PrHead; } catch { return null; }
+}
+
+/** Re-gate an existing PR in a clean checkout against current main; never merge from the healer. */
+export function operationalAutohealActions(deps: OperationalAutohealDeps): AutohealActions {
+  return {
+    'clean-workspace-regate': async (ctx) => {
+      const number = prFromEvidence(ctx);
+      if (!number) return { ok: false, detail: 'PR URL absent from stop evidence' };
+      const pr = (deps.readPr ?? readPr)(number, deps.repoRoot);
+      if (!pr?.headRefOid || pr.state !== 'OPEN' || typeof pr.isDraft !== 'boolean')
+        return { ok: false, detail: `PR #${number} is not an open PR with a measured head and draft state` };
+      const result = await (deps.regate ?? runHostRegate)({
+        prNumber: number, headCommit: pr.headRefOid, repoRoot: deps.repoRoot, verifyOnly: true,
+        ...(pr.isDraft ? { allowDraft: true } : {}),
+      });
+      return { ok: result.passed, detail: `PR #${number} head ${pr.headRefOid} clean regate ${result.status ?? (result.passed ? 'passed' : 'failed')}${result.failures.length ? `: ${result.failures.map((failure) => failure.step).join(',')}` : ''}` };
+    },
+  };
+}

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

@@ -13,11 +13,12 @@
  *   main-sync          → rebase-regate            리베이스(MERGE-INTENT-RESOLVE 의도 해석) 뒤 재게이트
  *   pod-died           → resume-from-salvage      `salvage/run-<6hex>/<leaf>` 가지에서 resume(DRAFT-NOT-ARCHIVE)
  *   evidence-uncovered → derive-evidence-rejudge  런 출력·시험·배선에서 증거를 끌어내 1회 재판정
+ *   review-budget-exhausted → needs-owner (code fallback; reauthor is an optional graph exit)
  *   review-repeat · review-out-of-scope · scope-escape · fabric · launch-failed · gate-failed · unclassified → needs-owner(새 라운드 없음)
  *
  * 사다리의 «출처»: `graphs/overlays/stop-heal-ladder.yaml` 이 갈래마다 처방 노드(id = 처방 이름)를 선언한다.
  *    그 갈래에 얹힌 오버레이가 더한 노드 id 가 처방이다(source='graph'). 선언이 없거나 못 읽으면
- *    위 표(`AUTOHEAL_ACTION_BY_CLASS`)로 간다(source='code-default'). 둘이 같은 답을 내는지는 시험이 문다.
+ *    위 표(`AUTOHEAL_ACTION_BY_CLASS`)로 간다(source='code-default'). 선택된 노드가 실제 실행 가능한지는 별도 경계다.
  *
  * 모드 `tools.selfImplement.autoheal.mode` = `shadow`(기본: 할 일을 원장에만 적고 손대지 않는다) | `live`.
  * ⛔ live 에서도 행동은 주입 seam 으로만 한다 — seam 이 없는 행동은 `needs-owner`(action-unwired)로 떨어진다.
@@ -44,6 +45,7 @@ export type AutohealAction =
   | 'rebase-regate'
   | 'resume-from-salvage'
   | 'derive-evidence-rejudge'
+  | 'review-round-reauthor'
   | 'needs-owner';
 
 /** 닫힌 목록 전체를 덮는다 — 새 class 가 생기면 여기서 타입 오류가 난다. */
@@ -55,6 +57,8 @@ export const AUTOHEAL_ACTION_BY_CLASS: Readonly<Record<RunStopClass, AutohealAct
   'evidence-uncovered': 'derive-evidence-rejudge',
   'review-repeat': 'needs-owner',
   'review-out-of-scope': 'needs-owner',
+  // Reauthoring is an optional graph exit, not a code-level guarantee.
+  'review-budget-exhausted': 'needs-owner',
   'scope-escape': 'needs-owner',
   fabric: 'needs-owner',
   'launch-failed': 'needs-owner',
@@ -64,7 +68,7 @@ export const AUTOHEAL_ACTION_BY_CLASS: Readonly<Record<RunStopClass, AutohealAct
 
 /** 처방 노드 id 로 인정하는 이름 — 오버레이가 더한 노드 중 이 넷만 처방으로 읽는다. */
 const HEAL_ACTION_NODE_IDS: ReadonlySet<string> = new Set<Exclude<AutohealAction, 'needs-owner'>>([
-  'clean-workspace-regate', 'rebase-regate', 'resume-from-salvage', 'derive-evidence-rejudge',
+  'clean-workspace-regate', 'rebase-regate', 'resume-from-salvage', 'derive-evidence-rejudge', 'review-round-reauthor',
 ]);
 
 /** 처방이 «어디서» 왔나 — `graph` = 그 갈래에 얹힌 오버레이가 더한 노드 · `code-default` = 위 표. */
@@ -75,6 +79,8 @@ export interface AutohealPick {
   source: AutohealActionSource;
   /** source='graph' 일 때 그 처방 노드를 더한 오버레이. */
   overlayId?: string;
+  /** Code fallback when an optional graph exit is not declared. */
+  fallbackReason?: string;
 }
 
 /** 사다리를 읽어 오는 자리 — 활성 템플릿 선언 ⊕ 오버레이 목록. 시험이 갈아 끼운다. */
@@ -93,7 +99,10 @@ function loadDefaultLadder(): AutohealLadder {
  *    «조용히» 코드 표로 간다 — 그 사실은 `source` 가 말한다. 던지지 않는다.
  */
 export function pickAutohealAction(cls: RunStopClass, loadLadder: () => AutohealLadder = loadDefaultLadder): AutohealPick {
-  const codeDefault: AutohealPick = { action: AUTOHEAL_ACTION_BY_CLASS[cls] ?? 'needs-owner', source: 'code-default' };
+  const codeDefault: AutohealPick = {
+    action: AUTOHEAL_ACTION_BY_CLASS[cls] ?? 'needs-owner', source: 'code-default',
+    ...(cls === 'review-budget-exhausted' ? { fallbackReason: 'declared-node-unavailable: review-round-reauthor' } : {}),
+  };
   try {
     const { template, overlays } = loadLadder();
     if (!template) return codeDefault;
@@ -297,8 +306,8 @@ export async function autohealFromStop(ctx: AutohealContext, deps: AutohealDeps
   }
   const mode = deps.mode ?? DEFAULT_AUTOHEAL_MODE;
   const cls = ctx.record.class;
-  const { action, source, overlayId } = pickAutohealAction(cls, deps.loadLadder);
-  const base = { runId: ctx.runId, class: cls, action, source, ...(overlayId ? { overlayId } : {}), mode };
+  const { action, source, overlayId, fallbackReason } = pickAutohealAction(cls, deps.loadLadder);
+  const base = { runId: ctx.runId, class: cls, action, source, ...(overlayId ? { overlayId } : {}), ...(fallbackReason ? { fallbackReason } : {}), mode };
 
   if (repeatedStop(deps.priorStops, ctx.record)) {
     // ⛔ 같은 골에서 같은 갈래의 멈춤이 반복되면 자동 재시도를 하지 않는다 — 사유를 골 되먹임 대상으로 넘긴다.
@@ -329,7 +338,7 @@ export async function autohealFromStop(ctx: AutohealContext, deps: AutohealDeps
   let detail: string | undefined;
   if (action === 'needs-owner') {
     outcome = 'needs-owner';
-    reason = `stop ${cls}: ${ctx.record.cause}`;
+    reason = `${fallbackReason ? `${fallbackReason}; ` : ''}stop ${cls}: ${ctx.record.cause}`;
   } else if (mode === 'shadow') {
     outcome = 'would-act';
   } else {