elanous 0.2.40 → 0.2.42

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

@@ -10,13 +10,19 @@
  * ⭐ 이 스키마(`RunStopRecord`·`RUN_STOP_CLASSES`)는 STOP-AUTOHEAL 이 읽는다 — 칸 이름·닫힌 목록을 바꾸지 않는다(더하기만).
  */
 import { debug } from '../debug/log.js';
-import { appendRunLedgerEntry, type RunLedgerEntry, type RunLedgerWriter, type RunShardIdentity } from './run-ledger.js';
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { appendRunLedgerEntry, runLedgerDir, runLedgerPath, type RunLedgerEntry, type RunLedgerWriter, type RunShardIdentity } from './run-ledger.js';
 import type { PodChildEvidence } from '../task-orchestrator/surfaces/self-implement.js';
+import { defaultOverlaysDir, loadGraphOverlays } from './graph-overlay-yaml.js';
 
 /** 닫힌 목록 — 못 고르면 `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',
+  'implement-aborted', 'out-of-scope-held', 'provider-auth-missing', 'provider-unavailable',
+  'merge-held-release-path', 'pr-guard-failed', 'gate-unmeasured', 'unclassified',
 ] as const;
 export type RunStopClass = typeof RUN_STOP_CLASSES[number];
 
@@ -35,6 +41,32 @@ export interface RunStopRecord {
   childEvidence?: PodChildEvidence;
   /** Exact structured Pod error code, when the host received one. */
   terminationReason?: 'pod-job-failed';
+  /** Safe terminal-attempt facts and a digest-addressed artifact; raw provider/child text is excluded. */
+  terminalEvidence?: RunStopTerminalEvidence;
+}
+
+export type RunStopReasonCode = 'tdd-evidence-missing' | 'goal-only-same-cell' | 'decomposition-401-invalid-api-key' | 'provider-credential-failure' | 'unknown';
+export type RunStopFact = string | number | boolean | 'unknown';
+export interface RunStopChildAttempt {
+  childRunId: RunStopFact;
+  job: RunStopFact;
+  attempt: RunStopFact;
+  stage: RunStopFact;
+  outcome: RunStopFact;
+  exitCode: RunStopFact;
+  reasonCode: RunStopReasonCode;
+}
+export interface RunStopTerminalEvidence {
+  childRunId: RunStopFact;
+  job: RunStopFact;
+  attempt: RunStopFact;
+  stage: RunStopFact;
+  node: RunStopFact;
+  outcome: RunStopFact;
+  exitCode: RunStopFact;
+  reasonCode: RunStopReasonCode;
+  childAttempts: RunStopChildAttempt[];
+  detailArtifact: { path: RunStopFact; byteLength: RunStopFact; sha256: RunStopFact };
 }
 
 export const RUN_STOP_EVENT = 'stop';
@@ -62,6 +94,127 @@ export interface RunStopInput {
   site?: string;
   childEvidence?: PodChildEvidence;
   terminationReason?: 'pod-job-failed';
+  terminalEvidence?: Omit<RunStopTerminalEvidence, 'detailArtifact'>;
+  /** Test seam; production persists only the sanitized structured artifact. */
+  writeEvidenceArtifact?: (path: string, bytes: Buffer) => void;
+}
+
+const UNKNOWN: RunStopFact = 'unknown';
+const SAFE_TOKEN = /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,159}$/u;
+const RUN_STOP_REASON_CODES: readonly RunStopReasonCode[] = ['tdd-evidence-missing', 'goal-only-same-cell', 'decomposition-401-invalid-api-key', 'provider-credential-failure', 'unknown'];
+
+function safeRunStopFact(value: unknown): RunStopFact {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isSafeInteger(value) ? value : UNKNOWN;
+  if (typeof value !== 'string' || !value.trim() || !SAFE_TOKEN.test(value.trim())) return UNKNOWN;
+  return value.trim();
+}
+
+function safeRunStopReasonCode(value: unknown): RunStopReasonCode {
+  return typeof value === 'string' && (RUN_STOP_REASON_CODES as readonly string[]).includes(value) ? value as RunStopReasonCode : 'unknown';
+}
+
+function writeTerminalEvidenceArtifact(input: RunStopInput, record: Omit<RunStopRecord, 'terminalEvidence'>): RunStopTerminalEvidence | undefined {
+  if (!input.terminalEvidence) return undefined;
+  const facts = input.terminalEvidence;
+  const safeEvidence = {
+    childRunId: safeRunStopFact(facts.childRunId), job: safeRunStopFact(facts.job), attempt: safeRunStopFact(facts.attempt),
+    stage: safeRunStopFact(facts.stage), node: safeRunStopFact(facts.node), outcome: safeRunStopFact(facts.outcome),
+    exitCode: safeRunStopFact(facts.exitCode), reasonCode: safeRunStopReasonCode(facts.reasonCode),
+    childAttempts: facts.childAttempts.slice(-8).map((item) => ({
+      childRunId: safeRunStopFact(item.childRunId), job: safeRunStopFact(item.job), attempt: safeRunStopFact(item.attempt),
+      stage: safeRunStopFact(item.stage), outcome: safeRunStopFact(item.outcome), exitCode: safeRunStopFact(item.exitCode),
+      reasonCode: safeRunStopReasonCode(item.reasonCode),
+    })),
+  };
+  const bytes = Buffer.from(`${JSON.stringify({ runId: input.runId, site: safeRunStopFact(input.site), class: record.class, terminalEvidence: safeEvidence }, null, 2)}\n`, 'utf8');
+  try {
+    // Validate the run id through the canonical ledger contract before using it in a path.
+    runLedgerPath(input.runId);
+    const path = join(runLedgerDir(), 'stop-cause-evidence', `${input.runId}.json`);
+    if (input.writeEvidenceArtifact) input.writeEvidenceArtifact(path, bytes);
+    else {
+      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+      writeFileSync(path, bytes, { mode: 0o600 });
+    }
+    return { ...safeEvidence, detailArtifact: { path, byteLength: bytes.byteLength, sha256: createHash('sha256').update(bytes).digest('hex') } };
+  } catch {
+    return { ...safeEvidence, detailArtifact: { path: UNKNOWN, byteLength: UNKNOWN, sha256: UNKNOWN } };
+  }
+}
+
+/** Classify only named failure markers. Free-form strings are inspected, never copied to durable evidence. */
+export function classifyRunStopReason(input: { detail?: unknown; terminationReason?: unknown; providerErrorCategory?: unknown; observedText?: readonly unknown[] }): RunStopReasonCode {
+  const text = [input.detail, ...(input.observedText ?? [])].filter((value): value is string => typeof value === 'string').join('\n').toLowerCase();
+  if (input.terminationReason === 'goal-only-rework-exhausted') return 'goal-only-same-cell';
+  if (/goal-only-rework-exhausted/u.test(text)) return 'goal-only-same-cell';
+  if (/tdd-evidence-missing/u.test(text)) return 'tdd-evidence-missing';
+  // Require a decomposition context as well as both credential markers; generic 401s are not this diagnosis.
+  if (/decompos.{0,256}\b401\b.{0,256}invalid api key|decompos.{0,256}invalid api key.{0,256}\b401\b|decomposition-401-invalid-api-key/u.test(text)) return 'decomposition-401-invalid-api-key';
+  if (input.providerErrorCategory === 'credential') return 'provider-credential-failure';
+  return 'unknown';
+}
+
+/** Extract child attempt metadata without carrying untrusted child/provider text into the stop artifact. */
+export function runStopChildAttempts(entries: readonly RunLedgerEntry[], classify: (values: readonly unknown[]) => RunStopReasonCode = () => 'unknown'): RunStopChildAttempt[] {
+  const attempts: RunStopChildAttempt[] = [];
+  const attemptByJob = new Map<string, number>();
+  for (const entry of entries) {
+    const data = entry.data;
+    if (entry.event === 'pod-oom-retry-intent') {
+      if (typeof data.job === 'string' && Number.isSafeInteger(data.attempt) && typeof data.attempt === 'number') attemptByJob.set(data.job, data.attempt);
+      continue;
+    }
+    if (entry.event !== 'pod-child-evidence') continue;
+    const childRunId = safeRunStopFact(data.childRunId);
+    const childResult = data.childResult && typeof data.childResult === 'object' && !Array.isArray(data.childResult) ? data.childResult as Record<string, unknown> : {};
+    const pod = data.podTermination && typeof data.podTermination === 'object' && !Array.isArray(data.podTermination) ? data.podTermination as Record<string, unknown> : {};
+    const text = [childResult.error, data.childEvidence, entry.data].filter((value) => value !== undefined);
+    const stage = safeRunStopFact(childResult.stage);
+    const exitCode = safeRunStopFact(pod.exitCode);
+    const childOutcome = typeof childResult.ok === 'boolean' ? (childResult.ok ? 'completed' : 'failed')
+      : typeof exitCode === 'number' ? (exitCode === 0 ? 'completed' : 'failed') : UNKNOWN;
+    const job = safeRunStopFact(data.job);
+    attempts.push({ childRunId, job, attempt: typeof job === 'string' ? attemptByJob.get(job) ?? UNKNOWN : UNKNOWN,
+      stage, outcome: childOutcome, exitCode, reasonCode: classify(text) });
+  }
+  return attempts.slice(-8);
+}
+
+/** Join the final outcome to the latest recorded child attempt; missing fields stay explicit unknowns. */
+export function buildRunStopTerminalEvidence(input: {
+  stage: unknown;
+  node: unknown;
+  outcome: unknown;
+  detail?: unknown;
+  terminationReason?: unknown;
+  providerErrorCategory?: unknown;
+  entries: readonly RunLedgerEntry[];
+}): Omit<RunStopTerminalEvidence, 'detailArtifact'> {
+  const observedText = input.entries
+    .filter((entry) => entry.event === 'pod-child-evidence' || entry.event.includes('decomposition'))
+    .map((entry) => {
+      try { return `${entry.event} ${JSON.stringify(entry.data)}`.slice(0, 24_000); } catch { return ''; }
+    }).filter(Boolean);
+  const classify = (values: readonly unknown[]) => classifyRunStopReason({
+    observedText: values.map((value) => typeof value === 'string' ? value : (() => { try { return JSON.stringify(value); } catch { return ''; } })()),
+  });
+  const childAttempts = runStopChildAttempts(input.entries, classify);
+  const current = childAttempts.at(-1);
+  const classified = classifyRunStopReason({ detail: input.detail, terminationReason: input.terminationReason,
+    providerErrorCategory: input.providerErrorCategory, observedText: observedText.slice(-1) });
+  const reasonCode = classified !== 'unknown' ? classified : current?.reasonCode ?? 'unknown';
+  return {
+    childRunId: current?.childRunId ?? UNKNOWN,
+    job: current?.job ?? UNKNOWN,
+    attempt: current?.attempt ?? UNKNOWN,
+    stage: safeRunStopFact(input.stage),
+    node: safeRunStopFact(input.node),
+    outcome: safeRunStopFact(input.outcome),
+    exitCode: current?.exitCode ?? UNKNOWN,
+    reasonCode,
+    childAttempts,
+  };
 }
 
 export function isRunStopClass(value: unknown): value is RunStopClass {
@@ -79,9 +232,12 @@ export function boundRunStopCause(raw: string): string {
 /** 병합 보류 사유 → 닫힌 목록. 모르면 `unclassified`. */
 export function classifyMergeHoldStop(mergeReason: string | undefined): RunStopClass {
   const reason = mergeReason ?? '';
+  const graphClass = classifyStopReasonFromGraph(reason);
+  if (graphClass) return graphClass;
   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 +252,49 @@ 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;
+  cause?: string;
+  mergeReason?: string;
+  abandonedClassification?: string;
+  providerErrorCategory?: string;
+  supervisorVerdict?: string;
+}): RunStopClass {
+  const graphClass = classifyStopReasonFromGraph(input.cause ?? input.mergeReason ?? '');
+  if (graphClass) return graphClass;
+  if (input.abandonedClassification === 'implement-aborted') return 'implement-aborted';
+  if (input.abandonedClassification === 'out-of-scope-held') return 'out-of-scope-held';
+  if (input.providerErrorCategory === 'credential' || input.providerErrorCategory === 'provider-auth-missing') return 'provider-auth-missing';
+  if (input.providerErrorCategory === 'provider-unavailable') return 'provider-unavailable';
+  if (input.mergeReason === 'release-path-hold') return 'merge-held-release-path';
+  if (input.mergeReason === 'pr-guard-failed') return 'pr-guard-failed';
+  if (input.mergeReason === 'gate-unmeasured') return 'gate-unmeasured';
+  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';
+}
+
+/** Exact reason vocabulary declared by heal graph overlays; unknown phrases remain unclassified. */
+export function classifyStopReasonFromGraph(reason: string): RunStopClass | undefined {
+  const normalized = reason.trim().toLowerCase();
+  if (!normalized) return undefined;
+  try {
+    for (const overlay of loadGraphOverlays(defaultOverlaysDir()).overlays) {
+      for (const [phrase, cls] of Object.entries(overlay.reasonMap ?? {})) {
+        const escaped = phrase.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        if (new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`).test(normalized) && isRunStopClass(cls)) return cls;
+      }
+    }
+  } catch { /* malformed or unavailable graph declarations are not classifier evidence */ }
+  return undefined;
+}
+
 /** 이 프로세스에서 stop 을 이미 쓴 런 — 한 런이 두 자리(예: draft PR 실패 ⊕ aborted)에서 두 줄을 쓰지 않게. */
 const recordedThisProcess = new Set<string>();
 const RECORDED_MAX = 4096;
@@ -112,7 +311,7 @@ export function forgetRunStop(runId: string): void {
 
 /** 멈춘 런에 stop 한 줄을 더한다 — 기존 관측은 바꾸지 않는다. 쓴 줄을 돌려준다. */
 export function recordRunStop(input: RunStopInput, write: RunLedgerWriter = appendRunLedgerEntry): RunLedgerEntry {
-  const record: RunStopRecord = {
+  const base: Omit<RunStopRecord, 'terminalEvidence'> = {
     class: isRunStopClass(input.class) ? input.class : 'unclassified',
     ...(input.site ? { site: input.site } : {}),
     cause: boundRunStopCause(input.cause),
@@ -121,6 +320,8 @@ export function recordRunStop(input: RunStopInput, write: RunLedgerWriter = appe
     ...(input.childEvidence ? { childEvidence: input.childEvidence } : {}),
     ...(input.terminationReason ? { terminationReason: input.terminationReason } : {}),
   };
+  const terminalEvidence = writeTerminalEvidenceArtifact(input, base);
+  const record: RunStopRecord = { ...base, ...(terminalEvidence ? { terminalEvidence } : {}) };
   const entry: RunLedgerEntry = {
     timestamp: new Date().toISOString(), runId: input.runId, event: RUN_STOP_EVENT,
     data: { ...record },
@@ -134,6 +335,7 @@ export function recordRunStop(input: RunStopInput, write: RunLedgerWriter = appe
     try { listener(entry); } catch { /* wake consumers cannot change run outcome */ }
   }
   try {
+    debug.log('self-implement.run-stop', 'cause-classified', { runId: input.runId, terminalEvidence });
     debug.log('self-implement.run-stop', 'recorded', { runId: input.runId, site: input.site ?? null, ...record, requestedClass: input.class ?? null });
   } catch { /* observation is fail-soft */ }
   return entry;
@@ -147,5 +349,6 @@ export function readRunStopRecord(entry: RunLedgerEntry): RunStopRecord | undefi
   return { class: isRunStopClass(data.class) ? data.class : 'unclassified', cause: data.cause, evidenceRef: data.evidenceRef, nextMove: data.nextMove,
     ...(typeof data.site === 'string' ? { site: data.site } : {}),
     ...(data.childEvidence ? { childEvidence: data.childEvidence } : {}),
-    ...(data.terminationReason === 'pod-job-failed' ? { terminationReason: data.terminationReason } : {}) };
+    ...(data.terminationReason === 'pod-job-failed' ? { terminationReason: data.terminationReason } : {}),
+    ...(data.terminalEvidence && typeof data.terminalEvidence === 'object' ? { terminalEvidence: data.terminalEvidence as RunStopTerminalEvidence } : {}) };
 }

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,12 @@ export type AutohealAction =
   | 'rebase-regate'
   | 'resume-from-salvage'
   | 'derive-evidence-rejudge'
+  | 'review-round-reauthor'
+  | 'reauthor-from-materialized'
+  | 'switch-provider'
+  | 'retry-provider'
+  | 'wait-release'
+  | 'remeasure-gate'
   | 'needs-owner';
 
 /** 닫힌 목록 전체를 덮는다 — 새 class 가 생기면 여기서 타입 오류가 난다. */
@@ -55,16 +62,26 @@ 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',
   'gate-failed': 'needs-owner',
   unclassified: 'needs-owner',
+  'implement-aborted': 'reauthor-from-materialized',
+  'out-of-scope-held': 'reauthor-from-materialized',
+  'provider-auth-missing': 'switch-provider',
+  'provider-unavailable': 'retry-provider',
+  'merge-held-release-path': 'wait-release',
+  'pr-guard-failed': 'reauthor-from-materialized',
+  'gate-unmeasured': 'remeasure-gate',
 };
 
 /** 처방 노드 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',
+  'reauthor-from-materialized', 'switch-provider', 'retry-provider', 'wait-release', 'remeasure-gate',
 ]);
 
 /** 처방이 «어디서» 왔나 — `graph` = 그 갈래에 얹힌 오버레이가 더한 노드 · `code-default` = 위 표. */
@@ -75,6 +92,8 @@ export interface AutohealPick {
   source: AutohealActionSource;
   /** source='graph' 일 때 그 처방 노드를 더한 오버레이. */
   overlayId?: string;
+  /** Code fallback when an optional graph exit is not declared. */
+  fallbackReason?: string;
 }
 
 /** 사다리를 읽어 오는 자리 — 활성 템플릿 선언 ⊕ 오버레이 목록. 시험이 갈아 끼운다. */
@@ -93,7 +112,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 +319,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 +351,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 {