elanous 0.2.41 → 0.2.42

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

@@ -0,0 +1,119 @@
+import { debug } from '../debug/log.js';
+import { appendRunLedgerEntryChecked, loadRunLedger, type RunLedgerEntry } from './run-ledger.js';
+
+export const RUN_DOCTOR_HANDOFF_WAIT_THRESHOLD = 3;
+export const RUN_DOCTOR_HANDOFF_INPUT_PREFIX = '[run-chart handoff=doctor]';
+export const RUN_CHART_MAX_CELLS = 20;
+export const RUN_CHART_READ_CELLS = 5;
+export type RunChartDevice = 'run-supervisor' | 'macrophage' | 'run-doctor' | 'outer-supervisor';
+export interface RunChartCell {
+  runId: string; device: RunChartDevice | 'summary'; stopKey: string; observed: string; verdict: string; action: string;
+  handoff: string | null; why: string; readStopKeys: string[]; waitCount?: number; failureClass?: string;
+}
+export interface RunChartDecision extends Omit<RunChartCell, 'device'> { device: RunChartDevice; dir: string }
+export type RunChartWriteResult = 'recorded' | 'already-recorded' | 'conflicting-verdict' | 'missing-ledger' | 'ledger-write-refused';
+
+function chartEvents(entries: readonly RunLedgerEntry[]): RunLedgerEntry[] {
+  const all = entries.filter((e) => e.event === 'run-chart-cell');
+  const compactedAt = all.reduce((last, entry, index) => entry.data.compacted ? index : last, -1);
+  if (compactedAt < 0) return all;
+  const compacted = all[compactedAt]!;
+  const summaryData = compacted.data.compacted as Record<string, unknown>;
+  const cutoff = typeof summaryData.lastStopKey === 'string' ? summaryData.lastStopKey : '';
+  const cutoffDevice = typeof summaryData.lastDevice === 'string' ? summaryData.lastDevice : '';
+  const cutoffAt = all.findIndex((e) => e.data.device === cutoffDevice && e.data.stopKey === cutoff);
+  const summary: RunLedgerEntry = { ...compacted, data: { device: 'summary', stopKey: `summary:${String(compacted.data.stopKey)}`,
+    observed: `${String(summaryData.count)} earlier chart cells folded`, verdict: 'summary',
+    action: 'compact', handoff: null, why: String(summaryData.verdicts ?? ''), readStopKeys: [] } };
+  return [summary, ...all.slice(cutoffAt >= 0 ? cutoffAt + 1 : compactedAt)];
+}
+
+function toChartCell(runId: string, e: RunLedgerEntry): RunChartCell {
+  return {
+    runId, device: e.data.device as RunChartDevice | 'summary', stopKey: String(e.data.stopKey ?? ''),
+    observed: String(e.data.observed ?? ''), verdict: String(e.data.verdict ?? ''), action: String(e.data.action ?? ''),
+    handoff: typeof e.data.handoff === 'string' ? e.data.handoff : null, why: String(e.data.why ?? ''),
+    readStopKeys: Array.isArray(e.data.readStopKeys) ? e.data.readStopKeys.filter((x): x is string => typeof x === 'string') : [],
+    ...(typeof e.data.waitCount === 'number' ? { waitCount: e.data.waitCount } : {}),
+    ...(typeof e.data.failureClass === 'string' ? { failureClass: e.data.failureClass } : {}),
+  };
+}
+
+export function projectRunChart(runId: string, dir: string): RunChartCell[] {
+  return chartEvents(loadRunLedger(runId, dir) ?? []).map((entry) => toChartCell(runId, entry));
+}
+
+export function readRunChart(runId: string, device: RunChartDevice, dir: string): RunChartCell[] {
+  const entries = loadRunLedger(runId, dir) ?? [];
+  const cells = chartEvents(entries).slice(-RUN_CHART_READ_CELLS).map((e) => toChartCell(runId, e));
+  const metrics = runChartMetrics(entries);
+  try { debug.log('run-chart', 'read', { runId, device, count: cells.length, stopKeys: cells.map((c) => c.stopKey) });
+    debug.log('run-chart', 'metrics', { runId, ...metrics }); } catch { /* observation is fail-soft */ }
+  return cells;
+}
+
+export function runChartMetrics(entries: readonly RunLedgerEntry[]): { emptyHandoffs: number; unreadHandoffs: number; conflictingVerdicts: number } {
+  const cells = entries.filter((e) => e.event === 'run-chart-cell');
+  const emptyHandoffs = cells.filter((e) => !String(e.data.handoff ?? '').trim()).length;
+  const unreadHandoffs = cells.filter((e) => Boolean(e.data.handoff)
+    && !cells.some((next) => next.data.readStopKeys instanceof Array && next.data.readStopKeys.includes(String(e.data.stopKey)))).length;
+  const verdicts = new Map<string, Set<string>>();
+  for (const cell of cells) {
+    const key = `${String(cell.data.device)}\0${String(cell.data.stopKey)}`;
+    const values = verdicts.get(key) ?? new Set<string>(); values.add(String(cell.data.verdict)); verdicts.set(key, values);
+  }
+  const conflictingVerdicts = [...verdicts.values()].filter((values) => values.size > 1).length;
+  return { emptyHandoffs, unreadHandoffs, conflictingVerdicts };
+}
+
+export function recordRunChartDecision(input: RunChartDecision): RunChartWriteResult {
+  const result = appendRunLedgerEntryChecked(input.runId, (entries) => {
+    if (entries === null) return { append: false, result: 'missing-ledger' as const };
+    const existing = entries.find((entry) => entry.event === 'run-chart-cell'
+      && entry.data.device === input.device && entry.data.stopKey === input.stopKey);
+    if (existing) return { append: false, result: existing.data.verdict === input.verdict
+      ? 'already-recorded' as const : 'conflicting-verdict' as const };
+    const current = chartEvents(entries);
+    const overflow = current.length >= RUN_CHART_MAX_CELLS;
+    const foldCount = overflow ? current.length - (RUN_CHART_MAX_CELLS - 2) : 0;
+    const toFold = current.slice(0, foldCount);
+    const append: RunLedgerEntry[] = [];
+    if (toFold.length) {
+      const foldedCells = toFold.filter((e) => e.data.verdict !== 'summary');
+      const priorSummary = toFold.find((e) => e.data.verdict === 'summary');
+      const priorCount = Number(String(priorSummary?.data.observed ?? '').match(/^\d+/)?.[0] ?? 0);
+      const count = priorCount + foldedCells.length;
+      const lastFolded = foldedCells.at(-1);
+      append.push({ timestamp: new Date().toISOString(), runId: input.runId, event: 'run-chart-summary',
+        data: { count, firstStopKey: toFold[0]?.data.stopKey, lastStopKey: lastFolded?.data.stopKey,
+          verdicts: toFold.map((e) => `${String(e.data.device)}:${String(e.data.verdict)}`).join('; ').slice(0, 500) } });
+    }
+    append.push({ timestamp: new Date().toISOString(), runId: input.runId, event: 'run-chart-cell', data: {
+      device: input.device, stopKey: input.stopKey, observed: input.observed.slice(0, 240), verdict: input.verdict,
+      action: input.action, handoff: input.handoff, why: input.why.slice(0, 240), readStopKeys: input.readStopKeys.slice(-RUN_CHART_READ_CELLS),
+      ...(input.waitCount === undefined ? {} : { waitCount: input.waitCount }),
+      ...(input.failureClass === undefined ? {} : { failureClass: input.failureClass }),
+    } });
+    // appendRunLedgerEntryChecked writes one row. Store summary with the decision row as a compact payload.
+    return { append: true, entry: append.length === 1 ? append[0]! : { ...append[1]!, data: { ...append[1]!.data,
+      compacted: { count: append[0]!.data.count, firstStopKey: append[0]!.data.firstStopKey,
+        lastStopKey: append[0]!.data.lastStopKey, lastDevice: toFold.filter((e) => e.data.verdict !== 'summary').at(-1)?.data.device,
+        verdicts: append[0]!.data.verdicts } } } };
+  }, input.dir);
+  const status = result.appended ? 'recorded' : result.result ?? 'ledger-write-refused';
+  if (status === 'recorded') {
+    try { debug.log('run-chart', 'decision', { runId: input.runId, device: input.device, stopKey: input.stopKey,
+      handoff: input.handoff, why: input.why.slice(0, 120) }); } catch { /* observation is fail-soft */ }
+  }
+  return status;
+}
+
+export interface RunChartWaitHandoff { runId: string; stopKey: string; waitCount: number; dir: string; readStopKeys?: string[] }
+export type RunChartWaitHandoffResult = RunChartWriteResult;
+export function recordRunChartWaitHandoff(input: RunChartWaitHandoff): RunChartWaitHandoffResult {
+  const readStopKeys = input.readStopKeys ?? readRunChart(input.runId, 'run-supervisor', input.dir).map((cell) => cell.stopKey);
+  return recordRunChartDecision({ runId: input.runId, device: 'run-supervisor', stopKey: input.stopKey,
+    observed: `consecutive wait decisions=${input.waitCount}`, verdict: 'wait', action: 'wait', handoff: 'run-doctor',
+    why: 'wait streak reached run doctor handoff threshold', readStopKeys,
+    waitCount: input.waitCount, failureClass: 'implement-aborted', dir: input.dir });
+}

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

@@ -1,4 +1,4 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { refuseProductionLedgerWriteInTest } from '../harness/ledger-write-guard.js';
@@ -17,6 +17,8 @@ import { withRunLedgerLock, restoreArchivedRunLedger } from './run-ledger-compac
 
 export interface RunLedgerEntry {
   timestamp?: string;
+  /** Monotonic per-run ordering for graph/traversal events. Legacy rows may omit it. */
+  seq?: number;
   runId: string;
   event: string;
   data: Record<string, unknown>;
@@ -30,6 +32,89 @@ export interface RunLedgerEntry {
   shardIdentityReadFailure?: RunShardIdentityReadFailure;
 }
 
+const RUN_GRAPH_STEP_EVENTS = new Set([
+  'node-enter', 'node-exit', 'edge-taken', 'node-skipped', 'node-added', 'edge-rerouted',
+  'unit-expanded', 'unit-collapsed', 'pipeline-node-entry', 'pipeline-node-exit', 'graph-edge-taken',
+]);
+
+function isRunGraphStepEvent(entry: RunLedgerEntry): boolean {
+  return RUN_GRAPH_STEP_EVENTS.has(entry.event)
+    || (entry.event === 'applied' && ['add-node', 'reroute', 'zoom-in', 'collapse'].includes(String(entry.data.op)));
+}
+
+/** Assign a monotonic sequence at the locked append boundary; never infer it later from timestamps. */
+function sequenceRunGraphEvent(entry: RunLedgerEntry, max: number): RunLedgerEntry {
+  if (!isRunGraphStepEvent(entry)) return entry;
+  const explicit = entry.seq ?? entry.data.seq;
+  if (typeof explicit === 'number' && Number.isSafeInteger(explicit) && explicit > max) {
+    return { ...entry, seq: explicit, ...(entry.data.seq === undefined ? {} : { data: { ...entry.data, seq: explicit } }) };
+  }
+  if (max >= Number.MAX_SAFE_INTEGER) throw new Error(`run graph event sequence exhausted: ${entry.runId}`);
+  const seq = max + 1;
+  return { ...entry, seq, ...(entry.data.seq === undefined ? {} : { data: { ...entry.data, seq } }) };
+}
+
+/** Read backward to the last sequenced graph step; repeated appends stay O(tail), not O(ledger²). */
+function lastRunGraphEventSequence(runId: string, dir: string): number {
+  const path = runLedgerPath(runId, dir);
+  if (!existsSync(path)) return 0;
+  const fd = openSync(path, 'r');
+  try {
+    const size = statSync(path).size;
+    const chunkSize = 8 * 1024;
+    let end = size;
+    let carry = '';
+    while (end > 0) {
+      const start = Math.max(0, end - chunkSize);
+      const bytes = Buffer.alloc(end - start);
+      readSync(fd, bytes, 0, bytes.length, start);
+      const text = `${bytes.toString('utf8')}${carry}`;
+      const lines = text.split(/\r?\n/);
+      carry = lines[0] ?? '';
+      for (let index = lines.length - 1; index > 0; index -= 1) {
+        const line = lines[index]?.trim();
+        if (!line) continue;
+        let row: RunLedgerEntry;
+        try { row = parseRunLedgerEntry(line, 0, runId); }
+        catch (error) {
+          if (index === lines.length - 1 && !text.endsWith('\n') && isIncompleteJsonPrefix(line)) {
+            throw new Error(`incomplete trailing run ledger entry: ${runId}`);
+          }
+          throw error;
+        }
+        if (!isRunGraphStepEvent(row)) continue;
+        const seq = row.seq ?? row.data.seq;
+        if (typeof seq === 'number' && Number.isSafeInteger(seq) && seq > 0) return seq;
+      }
+      end = start;
+    }
+    if (carry.trim()) {
+      let row: RunLedgerEntry;
+      try { row = parseRunLedgerEntry(carry, 0, runId); }
+      catch (error) {
+        if (isIncompleteJsonPrefix(carry)) throw new Error(`incomplete trailing run ledger entry: ${runId}`);
+        throw error;
+      }
+      if (!isRunGraphStepEvent(row)) return 0;
+      const seq = row.seq ?? row.data.seq;
+      if (typeof seq === 'number' && Number.isSafeInteger(seq) && seq > 0) return seq;
+    }
+    return 0;
+  } finally { closeSync(fd); }
+}
+
+function separateAppendedLedgerLine(path: string, line: string): string {
+  if (!existsSync(path)) return line;
+  const size = statSync(path).size;
+  if (size === 0) return line;
+  const fd = openSync(path, 'r');
+  try {
+    const lastByte = Buffer.alloc(1);
+    readSync(fd, lastByte, 0, 1, size - 1);
+    return lastByte[0] === 0x0a ? line : `\n${line}`;
+  } finally { closeSync(fd); }
+}
+
 export type RunShardIdentityReadFailure = 'malformed-structure' | 'invalid-values';
 
 export interface RunShardIdentity {
@@ -712,12 +797,21 @@ export function appendRunLedgerEntry(entry: RunLedgerEntry, dir = runLedgerDir()
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   const live = runLedgerPath(entry.runId, dir);
   const devProject = process.env.ELANOUS_DEV_PROJECT;
-  const row = entry.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
-    ? { ...entry, devProject }
-    : entry;
   withRunLedgerLock(dir, entry.runId, () => {
-    const line = `${JSON.stringify(row)}\n`;
-    if (!restoreArchivedRunLedger(dir, entry.runId, line)) appendFileSync(live, line, 'utf8');
+    let sequenced = entry;
+    if (isRunGraphStepEvent(entry)) {
+      // Restore a compacted ledger before choosing its next sequence so appends keep the
+      // same per-run order across the live/archive boundary.
+      restoreArchivedRunLedger(dir, entry.runId);
+      sequenced = sequenceRunGraphEvent(entry, lastRunGraphEventSequence(entry.runId, dir));
+    }
+    const sequencedRow = sequenced.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
+      ? { ...sequenced, devProject }
+      : sequenced;
+    const line = `${JSON.stringify(sequencedRow)}\n`;
+    const appendLine = isRunGraphStepEvent(entry) ? separateAppendedLedgerLine(live, line) : line;
+    if (!isRunGraphStepEvent(entry) && restoreArchivedRunLedger(dir, entry.runId, appendLine)) return;
+    appendFileSync(live, appendLine, 'utf8');
   });
   try {
     recordRunRequestVsEffectiveFromLedger(entry.runId, dir, entry);
@@ -790,7 +884,8 @@ export function appendRunLedgerEntryChecked<T>(
 ): RunLedgerCheckedAppendOutcome<T> {
   if (refuseProductionLedgerWriteInTest(dir, 'run-ledger')) return { appended: false, result: null, refusal: 'ledger-write-refused' as const };
   return withRunLedgerLock(dir, runId, () => {
-    const decision = decide(loadRunLedger(runId, dir));
+    const existing = loadRunLedger(runId, dir);
+    const decision = decide(existing);
     if (!decision.append) return { appended: false, result: decision.result, refusal: null };
     const entry = decision.entry;
     if (entry.runId !== runId) {
@@ -798,11 +893,16 @@ export function appendRunLedgerEntryChecked<T>(
     }
     const live = runLedgerPath(entry.runId, dir);
     const devProject = process.env.ELANOUS_DEV_PROJECT;
-    const row = entry.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
-      ? { ...entry, devProject }
-      : entry;
+    const isGraphStep = isRunGraphStepEvent(entry);
+    if (isGraphStep) restoreArchivedRunLedger(dir, runId);
+    const sequenced = isGraphStep ? sequenceRunGraphEvent(entry, lastRunGraphEventSequence(runId, dir)) : entry;
+    const row = sequenced.devProject === undefined && typeof devProject === 'string' && devProject.startsWith('prj-')
+      ? { ...sequenced, devProject }
+      : sequenced;
     const line = `${JSON.stringify(row)}\n`;
-    if (!restoreArchivedRunLedger(dir, entry.runId, line)) appendFileSync(live, line, 'utf8');
+    const appendLine = isGraphStep ? separateAppendedLedgerLine(live, line) : line;
+    if (!isGraphStep && restoreArchivedRunLedger(dir, entry.runId, appendLine)) return { appended: true, result: null, refusal: null };
+    appendFileSync(live, appendLine, 'utf8');
     return { appended: true, result: null, refusal: null };
   });
 }
@@ -925,6 +1025,7 @@ function parseRunLedgerEntry(line: string, lineNumber: number, expectedRunId: st
   }
   const entry = parsed as Partial<RunLedgerEntry>;
   if ((entry.timestamp !== undefined && typeof entry.timestamp !== 'string') || typeof entry.runId !== 'string' || typeof entry.event !== 'string'
+    || (entry.seq !== undefined && (!Number.isSafeInteger(entry.seq) || entry.seq < 1))
     || !entry.data || typeof entry.data !== 'object' || Array.isArray(entry.data)
     || (entry.goalId !== undefined && typeof entry.goalId !== 'string')
     || (entry.orchestrationId !== undefined && typeof entry.orchestrationId !== 'string')

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', 'review-budget-exhausted', '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,6 +232,8 @@ 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.startsWith('review-budget')) return 'review-budget-exhausted';
@@ -100,11 +255,21 @@ 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';
@@ -115,6 +280,21 @@ export function classifyTerminalHarnessFailure(input: {
   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;
@@ -131,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),
@@ -140,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 },
@@ -153,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;
@@ -166,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/stop-autoheal.ts

@@ -46,6 +46,11 @@ export type AutohealAction =
   | 'resume-from-salvage'
   | 'derive-evidence-rejudge'
   | 'review-round-reauthor'
+  | 'reauthor-from-materialized'
+  | 'switch-provider'
+  | 'retry-provider'
+  | 'wait-release'
+  | 'remeasure-gate'
   | 'needs-owner';
 
 /** 닫힌 목록 전체를 덮는다 — 새 class 가 생기면 여기서 타입 오류가 난다. */
@@ -64,11 +69,19 @@ export const AUTOHEAL_ACTION_BY_CLASS: Readonly<Record<RunStopClass, AutohealAct
   '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', 'review-round-reauthor',
+  'reauthor-from-materialized', 'switch-provider', 'retry-provider', 'wait-release', 'remeasure-gate',
 ]);
 
 /** 처방이 «어디서» 왔나 — `graph` = 그 갈래에 얹힌 오버레이가 더한 노드 · `code-default` = 위 표. */