elanous 0.2.34 → 0.2.36

package/src/self-implement/device-first.ts

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DEVICE_FIRST_STEP = 'DEVICE-FIRST-STAGE';
+
+export interface DeviceFirstDecision {
+  required: boolean;
+  device: string;
+  deviceSource: 'goal' | 'planner-stage';
+  exists: boolean;
+  inventoryMeasured: boolean;
+  firstSliceKind: 'device-test' | 'none';
+}
+
+/** Board goals carry an executable boundary. Ordinary free-form plans retain their existing decomposition. */
+export function inspectDeviceFirstGoal(goal: string, root?: string): DeviceFirstDecision {
+  const required = /완료\s*경계\s*증거\s*명령\s*:|검증\s*계획\s*\(TDD\)|DEVICE-FIRST|장치\s*우선/iu.test(goal)
+    && /(?:src|test)\/[\w./-]+\.[cm]?[jt]sx?/u.test(goal);
+  if (!required) return { required: false, device: '', deviceSource: 'goal', exists: false, inventoryMeasured: root !== undefined, firstSliceKind: 'none' };
+  const explicit = /(?:쓸\s*장치|필요한\s*장치|mock\s*장치)\s*:\s*`?([\w./-]+)/iu.exec(goal)?.[1];
+  const named = explicit ?? [...goal.matchAll(/src\/ux-sim\/([\w-]+)\.ts/gu)].map((match) => match[1]).find((name) => name !== 'event-monkey');
+  // A generic TDD boundary says nothing about which device is needed. Do not
+  // invent <feature>-device.ts from a production path.
+  if (!named) return { required: false, device: '', deviceSource: 'goal', exists: false,
+    inventoryMeasured: root !== undefined, firstSliceKind: 'none' };
+  const stem = named.replace(/^src\/ux-sim\//u, '').replace(/\.ts$/u, '');
+  const safeStem = stem.replace(/[^a-z0-9-]/giu, '-').replace(/^-+|-+$/gu, '') || 'goal-device';
+  const device = `src/ux-sim/${safeStem}.ts`;
+  return { required: true, device, deviceSource: 'goal', exists: root !== undefined && existsSync(join(root, device)),
+    inventoryMeasured: root !== undefined, firstSliceKind: 'device-test' };
+}
+
+export function ensureDeviceFirstSteps(goal: string, steps: readonly string[], root?: string): { steps: string[]; decision: DeviceFirstDecision } {
+  let decision = inspectDeviceFirstGoal(goal, root);
+  if (steps.length === 0) return { steps: [...steps], decision };
+  const existingStage = steps.findIndex((step) => step.includes(`동작: ${DEVICE_FIRST_STEP}`));
+  let rejectedStagedPath: string | undefined;
+  if (existingStage >= 0) {
+    const declaredPaths = steps[existingStage]!.split(/동작:/u)[0]!;
+    const stagedAction = steps[existingStage]!.split(/\n완료 경계/u)[0]!;
+    const declaredPath = /신설:\s*(src\/ux-sim\/[\w/-]+\.ts)/u.exec(steps[existingStage]!)?.[1]
+      ?? /src\/ux-sim\/[\w/-]+(?:\.test)?\.ts(?![\w.])/u.exec(stagedAction)?.[0]
+      ?? /(?:src|test)\/[\w./-]+\.[cm]?[jt]sx?(?![\w.])/u.exec(declaredPaths)?.[0];
+    const stagedPath = declaredPath?.replace(/\.test\.ts$/u, '.ts');
+    if (stagedPath && /^src\/ux-sim\/[\w/-]+\.ts$/u.test(stagedPath)) {
+      decision = { ...decision, required: true, device: stagedPath, deviceSource: 'planner-stage',
+        exists: root !== undefined && existsSync(join(root, stagedPath)), firstSliceKind: 'device-test' };
+    } else if (declaredPath) rejectedStagedPath = declaredPath;
+  }
+  // Without a repository root we cannot verify an existing device or declare
+  // its missing paths. Keep the feature plan and defer device inventory.
+  if (root === undefined && decision.required) decision = { ...decision, required: false, firstSliceKind: 'none' };
+  if (!decision.required) return { steps: existingStage < 0 ? [...steps]
+    : steps.filter((_, index) => index !== existingStage)
+      .map(step => step.replace(/\n?선행: DEVICE-FIRST-STAGE 조각 착지 뒤 발사/gu, '')), decision };
+  const predecessor = `선행: ${DEVICE_FIRST_STEP} 조각 착지 뒤 발사`;
+  const test = decision.device.replace(/\.ts$/u, '.test.ts');
+  // The parent goal's feature test is not evidence that the device itself works.
+  const deviceBoundary = [
+    `완료 경계 코드: ${decision.device}와 ${test}에서 mock 입력을 생산 호출에 주입하고 관측 가능한 결과를 단언한다. 운영 코드 변경 0.`,
+    '완료 경계 실물: 대상 저장소에서 mock 입력으로 실제 생산 호출을 통과시켜 입력·출력 또는 사건 원문을 남긴다. RED 실패 뒤 GREEN 통과를 같은 시험으로 확인한다.',
+    `완료 경계 증거 명령: bun test ${test}`,
+  ].join('\n');
+  const completeDeviceStage = (stage: string): string => {
+    // A planner may have copied the feature boundary onto this stage. Give the device one unambiguous boundary.
+    const body = stage.split('\n')
+      .filter((line) => !/^\s*(?:[-*]\s*)?완료 경계 (?:코드|실물|증거 명령):/u.test(line))
+      .map((line) => line.replace(/\s*·\s*완료 경계 (?:코드|실물|증거 명령):[^·]*/gu, ''))
+      .join('\n');
+    return `${body}\n${deviceBoundary}`;
+  };
+  const evidenceCommand = /완료\s*경계\s*증거\s*명령\s*[:：]\s*([^\r\n]+)/u.exec(goal)?.[1] ?? '';
+  const goalFeatureTest = [evidenceCommand, goal].flatMap((text) => [...text.matchAll(/(?:src|test)\/[\w./-]+\.test\.[cm]?[jt]sx?/gu)]
+    .map((match) => match[0])).find((path) => path !== test && !path.startsWith('src/ux-sim/'));
+  const completeFeatureStage = (stage: string, index: number): string => {
+    const withPredecessor = stage.includes(predecessor) ? stage : `${stage}\n${predecessor}`;
+    const declaredGoalTest = index === 0 ? goalFeatureTest : undefined;
+    const priorPlan = /검증 계획\(TDD\):[^\n]*/u.exec(withPredecessor)?.[0];
+    // An explicit goal command replaces the whole inherited plan. Merely
+    // containing that command is insufficient when a stale command remains.
+    if (priorPlan && !declaredGoalTest) return withPredecessor;
+    const withoutWrongPlan = priorPlan ? withPredecessor.replace(priorPlan, '').trimEnd() : withPredecessor;
+    const stagePaths = stage.split(/동작:/u)[0]!;
+    const stageTest = /(?:src|test)\/[\w./-]+\.test\.[cm]?[jt]sx?/u.exec(stagePaths)?.[0];
+    const stageSource = /(?:src|test)\/[\w./-]+\.[cm]?[jt]sx?/u.exec(stagePaths)?.[0];
+    const existingSiblingTest = stageSource?.endsWith('.ts') && root !== undefined
+      ? stageSource.replace(/\.ts$/u, '.test.ts') : undefined;
+    const featureTest = declaredGoalTest ?? stageTest
+      ?? (existingSiblingTest && existsSync(join(root!, existingSiblingTest)) ? existingSiblingTest : undefined);
+    if (!featureTest) return `${withoutWrongPlan}\n검증 계획(TDD): 시험 경로 미확정(${stageSource ? `${stageSource}의 시험 확장자 미정` : '조각 대상 경로 없음'}) · 이 조각에서 시험 경로를 먼저 정하고 RED 실패 뒤 같은 명령으로 GREEN을 확인한다.`;
+    const inventory = root === undefined ? '시험 재고 미측정(대상 루트 미상)'
+      : existsSync(join(root, featureTest)) ? '기존 시험' : '신규 시험(이 조각에서 먼저 신설)';
+    return `${withoutWrongPlan}\n검증 계획(TDD): ${inventory} ${featureTest} · 피처 시험 bun test ${featureTest}를 구현 전에 RED로 확인하고 생산 경로를 구현한 뒤 같은 명령으로 GREEN을 확인한다.`;
+  };
+  const targetPaths = [decision.device, test].filter((path) => root !== undefined && existsSync(join(root, path)));
+  const newPaths = [decision.device, test].filter((path) => !targetPaths.includes(path));
+  const firstTarget = targetPaths[0];
+  const first = `${firstTarget ? `대상 경로: ${firstTarget}\n` : ''}${newPaths.length ? `신설: ${newPaths.join(' · ')}\n` : ''}`
+    + `· 동작: ${DEVICE_FIRST_STEP} ${!decision.inventoryMeasured ? `${decision.device} 재고를 먼저 확인하고 기존이면 재사용하고 없으면 신설: 경로를 선언해` : decision.exists ? `기존 ${decision.device}를 사용해` : '필요한 mock 장치와 그 시험을 먼저 만들어'} mock 무대 시험 RED를 기록한다. 운영 코드 변경 0.`
+    + (!decision.inventoryMeasured ? '\n장치 재고: 미측정(대상 루트 미상).' : '');
+  if (existingStage >= 0) {
+    const oldStage = steps[existingStage]!;
+    // Replace copied completion boundaries, but retain planner instructions
+    // about the actual injection and verification of this named device.
+    const actionTail = oldStage.split(`동작: ${DEVICE_FIRST_STEP}`)[1]?.split('\n')[0] ?? '';
+    const actionClauses = actionTail.split(/\s+·\s+/u).map((clause) => clause.trim());
+    const retained = [...actionClauses, ...oldStage.split('\n').slice(1)]
+      .map((line) => line.trim())
+      .filter((line) => line && !/^(?:대상 경로|신설|[·*-]?\s*동작: DEVICE-FIRST-STAGE|장치 재고:|완료 경계 (?:코드|실물|증거 명령)|선행:)/u.test(line)
+        && !/^(?:필요한 mock 장치와 그 시험을 먼저 만들어|기존 src\/ux-sim\/[\w/-]+\.ts를 사용해|src\/ux-sim\/[\w/-]+\.ts 재고를 먼저 확인하고 기존이면 재사용하고 없으면 신설: 경로를 선언해) mock 무대 시험 RED를 기록한다\. 운영 코드 변경 0\.$/u.test(line));
+    const stage = `${first}${retained.length ? `\n${retained.join('\n')}` : ''}`
+      + (rejectedStagedPath ? `\n플래너 장치 경로 ${rejectedStagedPath}는 src/ux-sim/*.ts 규약 밖 — 골의 장치 후보로 복구.` : '');
+    return { decision, steps: [completeDeviceStage(stage), ...steps.filter((_, index) => index !== existingStage).map(completeFeatureStage)] };
+  }
+  return { decision, steps: [completeDeviceStage(first), ...steps.map(completeFeatureStage)] };
+}

package/src/self-implement/doctor-visit.ts

@@ -1,11 +1,20 @@
 import { debug } from '../debug/log.js';
+import { findIncidentPrecedents, type IncidentPrecedent } from '../harness/harness-incidents.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
 import {
   appendRunLedgerEntry,
+  appendRunLedgerEntryChecked,
   listRunLedgers,
   loadRunLedger,
   lookupRunLedger,
+  RunLedgerCheckedAppendRunIdMismatchError,
+  type RunLedgerCheckedAppendOutcome,
   type RunLedgerLookupOptions,
 } from './run-ledger.js';
+/** 사고 원장 루트 기본값 — 운영/시험 우주 상태 디렉터리(없으면 빈 선례 · fail-soft). */
+export function doctorVisitIncidentRoot(): string {
+  return elanousStateRoot();
+}
 
 /** DOCTOR-VISIT 증상 닫힌 목록 — 이 밖의 값은 기록·조회 모두 거부한다. */
 export const DOCTOR_SYMPTOMS = [
@@ -22,12 +31,14 @@ export const DOCTOR_SYMPTOMS = [
   'review-loop',
   'knowledge-gap',
   'too-big',
+  'long-run',
+  'needs-owner',
 ] as const;
 
 export type DoctorSymptom = (typeof DOCTOR_SYMPTOMS)[number];
 
 /** 진료 요청을 보낸 쪽 닫힌 목록. */
-export const DOCTOR_VISIT_SOURCES = ['supervisor', 'parent', 'child', 'judge', 'seat'] as const;
+export const DOCTOR_VISIT_SOURCES = ['supervisor', 'parent', 'child', 'judge', 'seat', 'auto', 'task-agent'] as const;
 
 export type DoctorVisitSource = (typeof DOCTOR_VISIT_SOURCES)[number];
 
@@ -49,6 +60,8 @@ export interface RecordDoctorVisitInput {
   evidence?: string;
   /** 원장 디렉터리(시험 seam) — 기본 = `runLedgerDir()`. */
   dir?: string;
+  /** 사고 원장 루트(시험 seam) — 기본 = `doctorVisitIncidentRoot()`. `null` 이면 선례 연결을 건너뛴다. */
+  incidentRoot?: string | null;
 }
 
 export interface DoctorVisit {
@@ -57,6 +70,8 @@ export interface DoctorVisit {
   symptom: DoctorSymptom;
   evidence?: string;
   timestamp?: string;
+  /** 사고 선례 연결 — 같은 reason 으로 이전에 기록된 실제 exit(기록 없으면 빈 배열). */
+  incidentPrecedents?: IncidentPrecedent[];
 }
 
 /**
@@ -74,19 +89,97 @@ export function recordDoctorVisit(visit: RecordDoctorVisitInput): DoctorVisit {
     throw new Error(`없음: 런 원장이 없습니다 (runId=${visit.runId}) — 새 원장을 만들지 않습니다`);
   }
   const timestamp = new Date().toISOString();
+  // 사고 선례 연결 — 기록된 실제 exit 만(지어내기 금지). 원장이 없으면 빈 배열(fail-soft).
+  const incidentRoot = 'incidentRoot' in visit ? visit.incidentRoot ?? null : doctorVisitIncidentRoot();
+  const incidentPrecedents = incidentRoot === null
+    ? []
+    : findIncidentPrecedents({ reason: visit.symptom, at: timestamp, runId: visit.runId }, incidentRoot);
   const data: Record<string, unknown> = { from: visit.from, symptom: visit.symptom };
   if (typeof visit.evidence === 'string' && visit.evidence.length > 0) data.evidence = visit.evidence;
+  if (incidentPrecedents.length > 0) data.incidentPrecedents = incidentPrecedents;
   appendRunLedgerEntry({ timestamp, runId: visit.runId, event: 'doctor-visit', data }, visit.dir);
-  debug.log('run-doctor', 'visit', { runId: visit.runId, from: visit.from, symptom: visit.symptom });
+  debug.log('run-doctor', 'visit', { runId: visit.runId, from: visit.from, symptom: visit.symptom, incidentPrecedents: incidentPrecedents.length });
   return {
     runId: visit.runId,
     from: visit.from,
     symptom: visit.symptom,
     ...(typeof visit.evidence === 'string' && visit.evidence.length > 0 ? { evidence: visit.evidence } : {}),
+    ...(incidentPrecedents.length > 0 ? { incidentPrecedents } : {}),
     timestamp,
   };
 }
 
+const AUTO_LONG_RUN_THRESHOLD_MS = 60 * 60 * 1000;
+const AUTO_LONG_RUN_WINDOW = '60m';
+
+/** A running Pod crossing 60 minutes records one visit per run and threshold window. */
+export function recordAutoLongRunVisit(input: {
+  runId: string;
+  startedAt: string;
+  now?: string;
+  dir?: string;
+}): { status: 'below-threshold' | 'recorded' | 'already-recorded' } {
+  const startedMs = Date.parse(input.startedAt);
+  const nowMs = input.now === undefined ? Date.now() : Date.parse(input.now);
+  if (!Number.isFinite(startedMs) || !Number.isFinite(nowMs)) {
+    throw new Error('invalid-long-run-time: startedAt/now must be ISO timestamps');
+  }
+  if (loadRunLedger(input.runId, input.dir) === null) throw new Error(`run-ledger-missing: ${input.runId}`);
+  const ageMs = nowMs - startedMs;
+  if (ageMs < AUTO_LONG_RUN_THRESHOLD_MS) return { status: 'below-threshold' };
+  const timestamp = new Date(nowMs).toISOString();
+  const outcome = appendRunLedgerEntryChecked(input.runId, (entries) => {
+    if (entries === null) throw new Error(`run-ledger-missing: ${input.runId}`);
+    const seen = entries.some((entry) => entry.event === 'doctor-visit'
+      && entry.data.from === 'auto' && entry.data.symptom === 'long-run'
+      && entry.data.thresholdWindow === AUTO_LONG_RUN_WINDOW);
+    if (seen) return { append: false, result: 'already-recorded' as const };
+    return { append: true, entry: {
+      timestamp,
+      runId: input.runId,
+      event: 'doctor-visit',
+      data: { from: 'auto', symptom: 'long-run', thresholdMs: AUTO_LONG_RUN_THRESHOLD_MS,
+        thresholdWindow: AUTO_LONG_RUN_WINDOW, startedAt: input.startedAt, ageMs },
+    } };
+  }, input.dir);
+  if (outcome.appended) {
+    debug.log('run-doctor', 'visit', { runId: input.runId, from: 'auto', symptom: 'long-run', thresholdWindow: AUTO_LONG_RUN_WINDOW });
+    return { status: 'recorded' };
+  }
+  if (outcome.result === null) throw new Error(`run-ledger-write-refused: ${input.runId}`);
+  return { status: outcome.result };
+}
+
+/** A TA card's specific needs-owner transition creates one visit only if its run ledger exists. */
+export function recordTaskAgentNeedsOwnerVisit(input: {
+  runId: string;
+  cardId: string;
+  at: string;
+  reason: string;
+  transitionIndex: number;
+  dir?: string;
+}): { status: 'missing-ledger' | 'recorded' | 'already-recorded' } {
+  if (!input.reason.startsWith('failed/needs-owner')) throw new Error(`not-needs-owner: ${input.reason}`);
+  const key = JSON.stringify([input.cardId, input.transitionIndex, input.at, input.reason]);
+  const outcome = appendRunLedgerEntryChecked(input.runId, (entries) => {
+    if (entries === null) return { append: false, result: 'missing-ledger' as const };
+    if (entries.some((row) => row.event === 'doctor-visit' && row.data.from === 'task-agent'
+      && row.data.transitionKey === key)) return { append: false, result: 'already-recorded' as const };
+    return { append: true, entry: {
+      runId: input.runId,
+      timestamp: new Date().toISOString(),
+      event: 'doctor-visit',
+      data: { from: 'task-agent', symptom: 'needs-owner', evidence: input.reason,
+        cardId: input.cardId, transitionAt: input.at, transitionIndex: input.transitionIndex, transitionKey: key },
+    } };
+  }, input.dir);
+  if (outcome.appended) {
+    debug.log('run-doctor', 'visit', { runId: input.runId, from: 'task-agent', symptom: 'needs-owner', cardId: input.cardId });
+    return { status: 'recorded' };
+  }
+  return { status: outcome.result ?? 'missing-ledger' };
+}
+
 export type ReadDoctorVisitsOptions = RunLedgerLookupOptions;
 
 /** `runId` 원장이 조회 범위 안에 있는가 — `doctor status --run` 이 없는 런을 «0건»으로 삼키지 않게 한다. */
@@ -116,3 +209,165 @@ export function readDoctorVisits(runId?: string, options: ReadDoctorVisitsOption
   return visits.sort((left, right) =>
     (left.timestamp ?? '').localeCompare(right.timestamp ?? '') || left.runId.localeCompare(right.runId));
 }
+
+/** First RUN-DOCTOR-LOOP shadow prescription. It records advice and never dispatches it. */
+export function recordShadowDoctorReevaluation(runId: string, dir?: string): {
+  status: 'recorded' | 'already-recorded' | 'no-visit';
+  rx?: 're-evaluate-member';
+  outcome?: 'shadow-recorded' | 'needs-evidence';
+  visitIndex?: number;
+} {
+  const entries = loadRunLedger(runId, dir);
+  if (entries === null) throw new Error(`없음: 런 원장이 없습니다 (runId=${runId})`);
+  let visitIndex = -1;
+  let lastVisitIndex = -1;
+  for (let index = 0; index < entries.length; index++) {
+    if (entries[index]?.event !== 'doctor-visit' || entries[index]?.data.symptom !== 'admit-starved') continue;
+    lastVisitIndex = index;
+    if (!entries.some((entry) => entry.event === 'doctor-rx'
+      && entry.data.shadow === true && entry.data.visitIndex === index)) {
+      visitIndex = index;
+      break;
+    }
+  }
+  if (visitIndex < 0) return lastVisitIndex < 0
+    ? { status: 'no-visit' }
+    : { status: 'already-recorded', visitIndex: lastVisitIndex };
+  const visit = entries[visitIndex]!;
+
+  const evidence = typeof visit.data.evidence === 'string' ? visit.data.evidence.trim() : '';
+  const rx = evidence ? 're-evaluate-member' as const : null;
+  const outcome = evidence ? 'shadow-recorded' as const : 'needs-evidence' as const;
+  const data: Record<string, unknown> = {
+    shadow: true,
+    visitIndex,
+    visit: { runId, from: visit.data.from, symptom: 'admit-starved', timestamp: visit.timestamp, evidence: evidence || null },
+    diagnosis: evidence ? 'admit-starved-reported' : 'evidence-unmeasured',
+    rx,
+    cost: { estimatedTokens: 0, usedTokens: 0 },
+    outcome,
+    execution: 'none',
+    handoff: evidence ? 'parent-re-evaluate-member' : 'visit-owner-provide-admission-evidence',
+  };
+  appendRunLedgerEntry({ timestamp: new Date().toISOString(), runId, event: 'doctor-rx', data }, dir);
+  debug.log('run-doctor', 'rx', { runId, visitIndex, rx, outcome, shadow: true, executed: false });
+  return { status: 'recorded', ...(rx ? { rx } : {}), outcome, visitIndex };
+}
+
+/** OP 손판정 한 건 — 시각과 결과만 받는다(그 밖의 입력은 받지 않는다). */
+export interface DoctorOpJudgment {
+  /** 손판정 시각(ISO). */
+  timestamp: string;
+  /** 손판정 결과 — 예: 'agree' | 'disagree'. */
+  result: string;
+}
+
+export interface RecordDoctorComparisonInput {
+  runId: string;
+  judgment: DoctorOpJudgment;
+  /** 원장 디렉터리(시험 seam) — 기본 = `runLedgerDir()`. */
+  dir?: string;
+}
+
+export interface DoctorComparisonRecord {
+  status: 'recorded' | 'already-recorded';
+  visitIndex: number;
+  shadowRxIndex: number;
+  rx: string | null;
+  outcome: string | null;
+  opResult: string;
+}
+
+/**
+ * RUN-DOCTOR-LIVE 0.2.36 첫 비교 슬라이스 — 그 정확한 runId 의 OP 손판정 1건(timestamp·result)을
+ * 이미 기록된 shadow doctor-rx/visit 에 결속해 원장에 `doctor-compare` 한 행을 남긴다.
+ * 행에는 양쪽 판단 시각(visit·shadowRx·OP), 원본 shadow rx/outcome, OP 판정 결과,
+ * 안정적 원본 인덱스(visitIndex·shadowRxIndex)를 담는다. 존재 판정과 단일 append 는
+ * appendRunLedgerEntryChecked 로 같은 per-run lock 안에서 원자적으로 이뤄진다(#30403).
+ * 명명된 실패 — invalid-op-judgment · run-ledger-missing · shadow-rx-missing · runId-mismatch ·
+ * visit-missing. 어떤 경우도 shadow 결과를 지어내지 않는다. 같은 shadow rx 에 대한 재시도는
+ * already-recorded 로 원장에 한 행만 남긴다(멱등).
+ *
+ * 배선 경계(의도적): 이 슬라이스의 호출자는 시험 경로뿐이다 — live dispatch·stall-watch retirement
+ * 은 후속 cross-judgment 증거 슬라이스에서 붙는다(현행 `eln doctor status --json` = total 0
+ * operating visits 이므로 live outcome 을 주장하지 않는다).
+ */
+export function recordDoctorComparison(input: RecordDoctorComparisonInput): DoctorComparisonRecord {
+  const runId = input.runId;
+  const judgment = input.judgment;
+  if (typeof judgment !== 'object' || judgment === null
+    || typeof judgment.timestamp !== 'string' || judgment.timestamp.length === 0
+    || typeof judgment.result !== 'string' || judgment.result.length === 0) {
+    throw new Error(`invalid-op-judgment: OP 손판정은 timestamp·result 문자열이 필요합니다 (runId=${runId})`);
+  }
+  const holder: { recorded?: DoctorComparisonRecord } = {};
+  let outcome: RunLedgerCheckedAppendOutcome<DoctorComparisonRecord>;
+  try {
+    // 단일 per-run lock 안에서 비교 행 존재 판정과 단일 append를 원자적으로 수행한다(#30403 동시 중복 결함).
+    // lock 안에서 appendRunLedgerEntry 를 다시 부르지 않는다(중첩 lock 시간초과).
+    outcome = appendRunLedgerEntryChecked<DoctorComparisonRecord>(runId, (entries) => {
+      if (entries === null) {
+        throw new Error(`run-ledger-missing: 런 원장이 없습니다 (runId=${runId}) — 새 원장을 만들지 않습니다`);
+      }
+      let shadowRxIndex = -1;
+      for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index]!;
+        if (entry.event === 'doctor-rx' && entry.data.shadow === true) shadowRxIndex = index;
+      }
+      if (shadowRxIndex < 0) {
+        throw new Error(`shadow-rx-missing: 이 runId 의 shadow doctor-rx 가 없습니다 (runId=${runId}) — shadow 결과를 지어내지 않습니다`);
+      }
+      const shadowRx = entries[shadowRxIndex]!;
+      const rx = typeof shadowRx.data.rx === 'string' ? shadowRx.data.rx : null;
+      const shadowOutcome = typeof shadowRx.data.outcome === 'string' ? shadowRx.data.outcome : null;
+      const visitIndex = typeof shadowRx.data.visitIndex === 'number' ? shadowRx.data.visitIndex : -1;
+      const visit = visitIndex >= 0 && visitIndex < entries.length ? entries[visitIndex] : undefined;
+      if (visit === undefined || visit.event !== 'doctor-visit' || visit.runId !== runId) {
+        throw new Error(`visit-missing: shadow doctor-rx 가 가리키는 doctor-visit 행이 없습니다 (runId=${runId}, visitIndex=${visitIndex})`);
+      }
+      const existing = entries.find((entry) => entry.event === 'doctor-compare' && entry.data.shadowRxIndex === shadowRxIndex);
+      if (existing !== undefined) {
+        const stored = existing.data.opJudgment as { timestamp?: unknown; result?: unknown };
+        if (typeof stored?.timestamp !== 'string' || stored.timestamp.length === 0
+          || typeof stored?.result !== 'string' || stored.result.length === 0) {
+          throw new Error(`comparison-corrupt: 이미 기록된 doctor-compare 의 저장 판단이 손상됐습니다 (runId=${runId}, shadowRxIndex=${shadowRxIndex}, stored=${JSON.stringify(stored)}) — 거짓 already-recorded 를 승인하지 않습니다`);
+        }
+        if (stored.timestamp !== judgment.timestamp || stored.result !== judgment.result) {
+          throw new Error(`comparison-conflict: 이미 기록된 doctor-compare 와 손판정이 다릅니다 (runId=${runId}, shadowRxIndex=${shadowRxIndex}, stored=${JSON.stringify(stored)}, received=${JSON.stringify(judgment)}) — 기존 행을 유지합니다`);
+        }
+        return { append: false as const, result: { status: 'already-recorded' as const, visitIndex, shadowRxIndex, rx, outcome: shadowOutcome, opResult: judgment.result } };
+      }
+      const data: Record<string, unknown> = {
+        shadow: true,
+        visitIndex,
+        shadowRxIndex,
+        visit: { runId, from: visit.data.from, symptom: visit.data.symptom, timestamp: visit.timestamp },
+        shadowRx: { timestamp: shadowRx.timestamp, rx, outcome: shadowOutcome },
+        opJudgment: { timestamp: judgment.timestamp, result: judgment.result },
+      };
+      holder.recorded = { status: 'recorded', visitIndex, shadowRxIndex, rx, outcome: shadowOutcome, opResult: judgment.result };
+      return { append: true as const, entry: { timestamp: new Date().toISOString(), runId, event: 'doctor-compare', data } };
+    }, input.dir);
+  } catch (error) {
+    if (error instanceof RunLedgerCheckedAppendRunIdMismatchError) {
+      throw new Error(`runId-mismatch: 원장 항목의 runId 가 요청 runId 와 다릅니다 (runId=${runId}) — ${error.message}`);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('runId does not match')) {
+      throw new Error(`runId-mismatch: 원장 항목의 runId 가 요청 runId 와 다릅니다 (runId=${runId}) — ${message}`);
+    }
+    throw error;
+  }
+  if (outcome.refusal === 'ledger-write-refused') {
+    throw new Error(`ledger-write-refused: 테스트 우주가 운영 원장 쓰기를 거부했습니다 (runId=${runId}) — 운영 원장에 쓰지 않았습니다`);
+  }
+  if (outcome.result !== null) {
+    return outcome.result;
+  }
+  if (holder.recorded === undefined) {
+    throw new Error(`run-ledger-missing: 런 원장이 없습니다 (runId=${runId}) — 새 원장을 만들지 않습니다`);
+  }
+  const record = holder.recorded;
+  debug.log('run-doctor', 'compare', { runId, visitIndex: record.visitIndex, shadowRxIndex: record.shadowRxIndex, opResult: judgment.result, executed: false });
+  return record;
+}

package/src/self-implement/evidence-command-budget.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, resolve, sep } from 'node:path';
+import ts from 'typescript';
+import { siblingTestPath } from '../self-dev/launch-preflight-text.js';
+
+// A generated evidence check is a smoke test. Large integration files belong in the
+// changed gate, where they have a separate budget and failure attribution.
+export const EVIDENCE_TEST_MAX_BYTES = 64 * 1024;
+
+/** An empty seam value is unresolved and must use the real HEAD reader. */
+export function resolveEvidenceHeadCommit(seamHead: string | undefined, readHead: () => string | undefined): string | undefined {
+  return seamHead?.trim() || readHead()?.trim() || undefined;
+}
+
+function directlyImportsTarget(path: string, source: string, targetSpecifiers: ReadonlySet<string>): boolean {
+  const ast = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, false);
+  let found = false;
+  const visit = (node: ts.Node): void => {
+    if (found) return;
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)
+      && !node.importClause?.isTypeOnly
+      && !(node.importClause?.namedBindings && ts.isNamedImports(node.importClause.namedBindings)
+        && !node.importClause.name && node.importClause.namedBindings.elements.every((element) => element.isTypeOnly))) {
+      found = targetSpecifiers.has(node.moduleSpecifier.text);
+    } else if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword
+      && node.arguments.length === 1 && ts.isStringLiteral(node.arguments[0])) {
+      found = targetSpecifiers.has(node.arguments[0].text);
+    }
+    if (!found) ts.forEachChild(node, visit);
+  };
+  visit(ast);
+  return found;
+}
+
+/** Pick a small test that directly imports the target; never substitute an unrelated test. */
+export function focusedEvidenceTestPath(target: string, repositoryRoot?: string): string | null {
+  const sibling = siblingTestPath(target);
+  if (!sibling) return null;
+  if (!repositoryRoot) return sibling;
+  const root = resolve(repositoryRoot);
+  const absolute = resolve(root, sibling);
+  if (!absolute.startsWith(`${root}${sep}`)) return null;
+  try {
+    // Authoring can precede creation of its declared test file. Preserve that
+    // existing command contract; the size budget only applies to a measured file.
+    if (!existsSync(absolute)) return sibling;
+    // Follow a symlink so its target's measured size, not link text length, sets the budget.
+    const siblingStat = statSync(absolute);
+    if (siblingStat.isFile() && siblingStat.size <= EVIDENCE_TEST_MAX_BYTES) return sibling;
+    const stem = basename(target, '.ts');
+    const importName = `./${stem}`;
+    const targetSpecifiers = new Set([`${importName}.js`, `${importName}.ts`, importName]);
+    const candidates = readdirSync(dirname(absolute))
+      .filter((name) => name.startsWith(`${stem}-`) && name.endsWith('.test.ts') && !/['\\]/u.test(name))
+      .map((name) => ({ name, absolute: resolve(dirname(absolute), name) }))
+      .flatMap(({ name, absolute: path }) => {
+        // Match the sibling rule: a linked test is measured by its target.
+        const stat = statSync(path);
+        if (!stat.isFile() || stat.size > EVIDENCE_TEST_MAX_BYTES) return [];
+        const source = readFileSync(path, 'utf8');
+        return directlyImportsTarget(path, source, targetSpecifiers) ? [{ name, size: stat.size }] : [];
+      })
+      .sort((a, b) => a.size - b.size || a.name.localeCompare(b.name));
+    return candidates.length ? `${dirname(sibling)}/${candidates[0]!.name}` : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Only rewrite a single, safely quoted generated Bun test command. */
+export function narrowerEvidenceCommand(command: string, repositoryRoot: string): string | null {
+  const match = /^bun test -- '([^']+)'$/u.exec(command);
+  // Generated paths with shell quote escapes are deliberately left untouched here.
+  if (!match || match[1]!.includes('\\')) return null;
+  const testPath = match[1]!;
+  if (!testPath.endsWith('.test.ts')) return null;
+  const target = `${testPath.slice(0, -'.test.ts'.length)}.ts`;
+  const focused = focusedEvidenceTestPath(target, repositoryRoot);
+  return focused && focused !== testPath && !/['\\]/u.test(focused) ? `bun test -- '${focused}'` : null;
+}