elanous 0.2.40 → 0.2.42

package/src/self-dev/run-supervisor.ts

@@ -7,6 +7,8 @@ import { authorRepairGoal } from '../harness/helper-repair.js';
 export type { SupervisorStopReason } from './run-types.js';
 export { SUPERVISOR_STOP_REASONS } from './run-types.js';
 import { recordSelfDevRunSupervisorStop, selfDevRunsDir } from './run-store.js';
+import { readRunChart, recordRunChartDecision } from '../self-implement/run-chart.js';
+import { runLedgerDir } from '../self-implement/run-ledger.js';
 import { debug } from '../debug/log.js';
 import { sweepFrozenMerges } from '../self-implement/frozen-merges.js';
 import { selectKnowhowPack } from '../self-implement/knowhow-pack.js';
@@ -43,6 +45,11 @@ export interface SupervisorRound {
   mainSyncRelaunchFeatures?: string[];
   /** PR 없는 미분류 실패에 대해 실제 분해 실행기로 수복한 원래 골. 새 taskId에도 한 번 상한을 지킨다. */
   selfHealDecomposeFeatures?: string[];
+  /**
+   * NEEDS-HUMAN-REASON-REPAIR — 사유별 자가 수복 1회의 소진 기억(사유 → 그때 수복한 골 전문).
+   * 사유가 다르면 다른 시도다. 옛 원장엔 이 칸이 없다 = 「안 쟀다」이지 「시도했다」가 아니다.
+   */
+  selfHealRepairFeatures?: Partial<Record<NeedsHumanRepairReason, string[]>>;
   /**
    * Tasks of this round that ended `status=failed` without a PR. Omitted when there are none — and on older
    * history, which never measured it, so the no-PR streak guard reads it as «not measured» and stays off.
@@ -137,7 +144,96 @@ export interface SupervisorDecision {
   };
   oscillation?: { taskIds: string[]; helper: 'review-oscillation'; signature: string; repairGoals?: Record<string, string>; heldTaskIds?: string[] };
   pendingDecision?: 'attempt-care-escalation';
-  selfHeal?: { reason: 'supervisor-unclassified-decompose'; attempt: 1; taskIds: string[] };
+  selfHeal?: { reason: SelfHealReason; attempt: 1; taskIds: string[]; repairGoals?: Record<string, string> };
+}
+
+/**
+ * NEEDS-HUMAN-REASON-REPAIR — needs-human 으로 접히기 «전»에 한 번 수복해 볼 사유.
+ * 각 사유의 수복은 다르다: 없는 경로 → 재접지 · 범위 확장 → 좁히기 · 시간 초과 → 좁은 시험 · 조각 없음 → 조각 재걸기.
+ */
+export type NeedsHumanRepairReason = 'missing-path' | 'scope-expansion' | 'step-timeout' | 'no-piece';
+
+/** 선행 0.2.38 의 분해 수복 사유까지 포함한 자가 수복 사유 전체. */
+export type SelfHealReason = 'supervisor-unclassified-decompose' | `supervisor-${NeedsHumanRepairReason}`;
+
+const NEEDS_HUMAN_REPAIR_REASONS: readonly NeedsHumanRepairReason[] = ['missing-path', 'scope-expansion', 'step-timeout', 'no-piece'];
+
+/** 파일 부재의 두 코드 — 없는 경로(ENOENT)와 중간 성분이 파일인 경로(ENOTDIR). */
+const MISSING_PATH_ERROR_CODES: ReadonlySet<string> = new Set(['ENOENT', 'ENOTDIR']);
+
+const NEEDS_HUMAN_REPAIR_INSTRUCTION: Record<NeedsHumanRepairReason, string> = {
+  'missing-path': '없는 경로를 다시 접지한다 — 저장소에 있는 파일이나 골에 명시된 대상 경로만 고르고, 새 파일은 골이 신설을 요구할 때만 만든다',
+  'scope-expansion': '범위 확장을 좁힌다 — 대상 경로 밖으로 나간 변경을 되돌리고 골의 대상·완료 경계 안에서만 구현한다',
+  'step-timeout': '단계 예산을 넘겼다 — 좁은 시험 하나로 판정선을 먼저 세우고 나머지 실행은 그 뒤로 미룬다',
+  'no-piece': '조각 없이 실패했다 — 같은 골을 다시 걸되 완료 경계를 한 조각 분량으로 잘라 건다',
+};
+
+function normalizedRepairPath(path: string): string {
+  return path.replace(/^\.\//u, '').replace(/[),.;:]+$/u, '');
+}
+
+/** 경로가 범위 집합 안인가 — 정확 일치 · 디렉터리 접두 · (언급이 파일 이름뿐이면) 파일 이름 일치. */
+function pathWithinScope(path: string, scope: readonly string[]): boolean {
+  const p = normalizedRepairPath(path);
+  return scope.some((raw) => {
+    const s = normalizedRepairPath(raw);
+    if (s === p) return true;
+    if (s.endsWith('/') ? p.startsWith(s) : p.startsWith(`${s}/`)) return true;
+    return !p.includes('/') && s.split('/').at(-1) === p;
+  });
+}
+
+/**
+ * 범위 확장 — «밖»이라고 잰 변경 전부.
+ * ⛔ 대상 경로를 모르면 `changedFiles` 로는 «밖»을 단정하지 않는다(둘 다 쟀을 때만).
+ *    다만 실행 범위 가드가 «대상 밖»으로 직접 잰 값(`outsideTargetFiles`)은 그 자체가 측정이다.
+ */
+function expandedBeyondTargetPaths(result: SupervisorJobResult): string[] {
+  const measured = result.outsideTargetFiles ?? [];
+  const changed = result.changedFiles;
+  const targets = result.targetPaths;
+  const byScope = changed !== undefined && targets !== undefined && targets.length > 0
+    ? changed.filter((file) => !pathWithinScope(file, targets))
+    : [];
+  return [...new Set([...measured, ...byScope])];
+}
+
+/**
+ * needs-human 앞의 수복 사유 discriminator — 결과에 이미 실리는 판정 재료만 본다:
+ * 단계(`timed-out`) · 오류 코드(ENOENT/ENOTDIR) · 변경 파일 vs 골 대상 경로 · 분해 제안 조각 수.
+ * PR 이 있는 결과(사람이 볼 PR)와 재시도 재료가 있는 결과는 여기 대상이 아니다(undefined).
+ */
+export function needsHumanRepairReason(result: SupervisorJobResult): NeedsHumanRepairReason | undefined {
+  if (result.status !== 'failed' || result.prNumber !== undefined || result.prUrl) return undefined;
+  if (result.stage === 'timed-out') return 'step-timeout';
+  if (result.error?.code !== undefined && MISSING_PATH_ERROR_CODES.has(result.error.code)) return 'missing-path';
+  if (expandedBeyondTargetPaths(result).length > 0) return 'scope-expansion';
+  if ((result.decomposeProposal?.pieces.length ?? 0) < 2) return 'no-piece';
+  return undefined;
+}
+
+/** 사유별 수복 골 원문 — 사유의 수복 지시 + 골의 대상 경로 + 관측된 원인 + 원래 골. */
+export function needsHumanRepairGoal(result: SupervisorJobResult, reason: NeedsHumanRepairReason): string {
+  const outside = expandedBeyondTargetPaths(result);
+  const repairTargets = result.targetPaths?.length ? result.targetPaths : undefined;
+  return [
+    ...(repairTargets?.length ? [`대상 경로: ${repairTargets.join(', ')}`] : []),
+    `[supervisor-needs-human-repair:${reason}] ${NEEDS_HUMAN_REPAIR_INSTRUCTION[reason]}`,
+    ...(outside.length ? [`대상 경로 밖 변경: ${outside.join(', ')}`] : []),
+    ...(result.error?.message ? [`이전 실패: ${result.error.message.slice(0, 200)}`] : []),
+    result.feature,
+  ].join('\n');
+}
+
+/** 수복 사유가 붙은 자가 수복인가 — 선행 분해 수복('supervisor-unclassified-decompose')과 갈라낸다. */
+function needsHumanRepairDecisionReason(reason: SelfHealReason): NeedsHumanRepairReason | undefined {
+  return NEEDS_HUMAN_REPAIR_REASONS.find((candidate) => reason === `supervisor-${candidate}`);
+}
+
+/** 사유별 소진 기억에 이 조각이 이미 있는가 — 새 taskId 여도 골 전문으로 짝을 맞춘다. */
+function needsHumanRepairSpent(history: readonly SupervisorRound[], reason: NeedsHumanRepairReason, feature: string): boolean {
+  const key = resumeKey(feature);
+  return history.some((entry) => (entry.selfHealRepairFeatures?.[reason] ?? []).some((spent) => resumeKey(spent) === key));
 }
 
 export interface SupervisorLimits {
@@ -245,6 +341,11 @@ export type SupervisorJobResult = SelfDevJobResult & {
   reviewReason?: string;
   salvage?: 'launched' | 'parked';
   next?: SupervisorNext;
+  /**
+   * NEEDS-HUMAN-REASON-REPAIR — 실행 범위 가드가 «대상 경로 밖»으로 직접 잰 변경.
+   * 골이 대상 경로를 안 선언했어도 이 값은 측정이다 — `changedFiles` 와 달리 «밖»을 단정할 수 있다.
+   */
+  outsideTargetFiles?: readonly string[];
 };
 
 export function aggregateReviewTrend(results: readonly SelfDevJobResult[]): ReviewRework['trend'] | undefined {
@@ -348,7 +449,7 @@ function mustFixScopeDecision(
   return { byTask, ...(split.length ? { split } : {}), ...(askOwner.length ? { askOwner } : {}) };
 }
 
-export function decideNextRun(input: {
+type DecideNextRunInput = {
   results: readonly SupervisorJobResult[];
   history?: readonly SupervisorRound[];
   limits?: SupervisorLimits;
@@ -360,9 +461,15 @@ export function decideNextRun(input: {
   reviewMustFixTrend?: ReviewRework['trend'];
   /** True: the rerun consumes the authored goal. False: it cannot, so oscillation stops for a human. Undefined: pure decision. */
   repairGoalExecution?: boolean;
+  /** Separate opt-in for needs-human reason repairs; omitted keeps the new repair execution disabled. */
+  needsHumanReasonRepairExecution?: boolean;
   /** 분해 제안을 실제 조각 실행으로 승격할 수 있는 supervisor 경로에만 true. */
   decompositionExecution?: boolean;
-}): SupervisorDecision {
+  /** Chart context available to the outer-supervisor judgment; pulled from this same run only. */
+  runChart?: readonly { device: string; stopKey: string; observed: string; verdict: string; action: string; handoff: string | null; why: string; readStopKeys: readonly string[] }[];
+};
+
+function decideNextRunCore(input: DecideNextRunInput): SupervisorDecision {
   const results = [...input.results];
   const history = [...(input.history ?? [])];
   const maxRounds = input.limits?.maxRounds ?? DEFAULT_MAX_ROUNDS;
@@ -550,7 +657,52 @@ export function decideNextRun(input: {
         why: `supervisor-unclassified-decompose (attempt: 1/1) — PR 없는 미분류 조각 ${taskIds.length}개를 실증된 분해 제안으로 한 번 재걸기`,
       };
     }
+    // NEEDS-HUMAN-REASON-REPAIR — 사람에게 접기 «전»에 사유별로 한 번 수복한다. 수복 골은 rerun 이 그대로 실행한다.
+    //   ⛔ 실행기가 선언되지 않았으면(repairGoalExecution !== true) 수복 대신 지금처럼 사람에게 간다.
+    if (input.repairGoalExecution === true && input.needsHumanReasonRepairExecution === true && round + 1 <= maxRounds) {
+      const repairable = activeResults.flatMap((result) => {
+        if (!t.needsHuman.includes(result.taskId)) return [];
+        if (!t.classifications.some((classification) => classification.taskId === result.taskId && classification.kind === 'unclassified')) return [];
+        const reason = needsHumanRepairReason(result);
+        if (reason === undefined || (result.targetPaths?.length ?? 0) === 0) return [];
+        return needsHumanRepairSpent(history, reason, result.feature) ? [] : [{ result, reason }];
+      });
+      const first = repairable[0];
+      const single = first !== undefined && repairable.length === 1 && t.needsHuman.every((id) => id === first.result.taskId)
+        ? first : undefined;
+      if (single) {
+        const taskIds = [single.result.taskId];
+        return {
+          ...base,
+          action: 'relaunch',
+          needsHuman: t.needsHuman.filter((id) => !taskIds.includes(id)),
+          selfHeal: {
+            reason: `supervisor-${single.reason}`,
+            attempt: 1,
+            taskIds,
+            repairGoals: { [single.result.taskId]: needsHumanRepairGoal(single.result, single.reason) },
+          },
+          why: `supervisor-${single.reason} (attempt: 1/1) — ${NEEDS_HUMAN_REPAIR_INSTRUCTION[single.reason]}`,
+        };
+      }
+    }
     if (t.needsHuman.length > 0) {
+      // 이미 한 번 수복했는데 같은 사유로 다시 섰다 — 사유·시도를 원문으로 남기고 사람에게 넘긴다.
+      const exhausted = activeResults.flatMap((result) => {
+        if (!t.needsHuman.includes(result.taskId)) return [];
+        const reason = needsHumanRepairReason(result);
+        if (reason === undefined || !needsHumanRepairSpent(history, reason, result.feature)) return [];
+        return [{ result, reason }];
+      });
+      if (exhausted.length > 0) {
+        return {
+          ...base,
+          action: 'stop',
+          stopReason: 'needs-human',
+          why: withGoalPlanRevisionObservation(`${exhausted.map(({ result, reason }) =>
+            `supervisor-${reason} (attempt: 1/1) — ${NEEDS_HUMAN_REPAIR_INSTRUCTION[reason]} 을 한 번 시도했으나 같은 조각이 다시 실패했다(${result.taskId})`).join(' · ')} · 사람이 볼 것 ${t.needsHuman.length}`),
+        };
+      }
       return {
         ...base,
         action: 'stop',
@@ -777,6 +929,26 @@ export function decideNextRun(input: {
   };
 }
 
+/** Consume an unread doctor→reauthor chart handoff before returning a terminal exit. */
+export function decideNextRun(input: DecideNextRunInput): SupervisorDecision {
+  const decision = decideNextRunCore(input);
+  if (decision.action !== 'stop' || decision.stopReason === 'max-rounds') return decision;
+  const pendingReauthor = [...(input.runChart ?? [])].reverse().find((cell) => cell.handoff === 'reauthor'
+    && !input.runChart?.some((later) => later.device === 'outer-supervisor' && later.readStopKeys.includes(cell.stopKey)));
+  if (!pendingReauthor) return decision;
+  const eligible = input.results.filter((result) => decision.needsHuman.includes(result.taskId)
+    && result.status === 'failed' && result.feature.trim() && result.prNumber === undefined && !result.prUrl);
+  if (eligible.length === 0 || decision.round > (input.limits?.maxRounds ?? DEFAULT_MAX_ROUNDS)) return decision;
+  const taskIds = eligible.map((result) => result.taskId);
+  return { ...decision, action: 'relaunch', stopReason: undefined,
+    rerunnable: [...new Set([...decision.rerunnable, ...taskIds])],
+    needsHuman: decision.needsHuman.filter((taskId) => !taskIds.includes(taskId)),
+    classifications: decision.classifications.map((classification) => taskIds.includes(classification.taskId)
+      ? { ...classification, action: 'rerun' as const } : classification),
+    why: `run-chart handoff=reauthor consumed (${pendingReauthor.stopKey}) — needs-human 조각 ${taskIds.length}개를 재발사`,
+  };
+}
+
 export function appendRound(
   history: readonly SupervisorRound[],
   results: readonly SupervisorJobResult[],
@@ -802,6 +974,9 @@ export function appendRound(
     if (result.durationMs === undefined) { unknownTimeTaskIds.add(result.taskId); continue; }
     lostTimeMsByTask[result.taskId] = (lostTimeMsByTask[result.taskId] ?? 0) + result.durationMs;
   }
+  const selfHealRepairReason = decision?.action !== 'stop' && decision?.selfHeal
+    ? needsHumanRepairDecisionReason(decision.selfHeal.reason)
+    : undefined;
   return [...history, {
     round: history.length,
     landed: countLanded(results),
@@ -826,6 +1001,15 @@ export function appendRound(
         return feature === undefined ? [] : [feature];
       }),
     } : {}),
+    // NEEDS-HUMAN-REASON-REPAIR — 사유별 수복 1회 소진을 회차 원장에 남긴다(사유가 다르면 다른 시도).
+    ...(selfHealRepairReason !== undefined && decision?.selfHeal ? {
+      selfHealRepairFeatures: {
+        [selfHealRepairReason]: decision.selfHeal.taskIds.flatMap((id) => {
+          const feature = results.find((result) => result.taskId === id)?.feature;
+          return feature === undefined ? [] : [feature];
+        }),
+      },
+    } : {}),
     ...(decision?.action === 'add-repair-task' && decision.oscillation ? (() => {
       // Each repaired task is recorded under its original goal feature and, when a rerun runs the authored goal as
       // the piece's new feature (orchestrate), under that repair text too — so the repair's own oscillation stops.
@@ -1048,6 +1232,7 @@ export interface SuperviseRunOptions {
   sweepPendingMerges?: typeof sweepFrozenMerges;
   /** True only when rerun consumes `invocation.repairGoals`; omitted or false → a review oscillation stops for a human. */
   repairGoalExecution?: boolean;
+  needsHumanReasonRepairExecution?: boolean;
   /**
    * TASK-AGENT-SHADOW — 멈춤이 확정되면 판단부를 그림자로 부른다(기본 `recordTaskAgentShadowMove`).
    * `false` 면 끈다. 던져도 런의 결말은 바뀌지 않는다(fail-soft).
@@ -1097,6 +1282,7 @@ export async function rejudgeTerminalTaskCard(runId: string | null, deps: {
 export async function superviseRun(opts: SuperviseRunOptions): Promise<SupervisorJobResult[]> {
   let results = [...opts.initial];
   let history: SupervisorRound[] = [];
+  const maxRounds = opts.limits?.maxRounds ?? DEFAULT_MAX_ROUNDS;
 
   for (;;) {
     try {
@@ -1138,21 +1324,49 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
     const allUnreviewedAreNoDiff = unreviewed.length > 0
       && unreviewed.every((result) => result.reviewReason === 'no-diff');
 
+    const chartRunId = opts.runStore?.runId ?? results.find((result) => result.runId?.trim())?.runId ?? null;
+    const chartDir = opts.runStore?.dir ?? runLedgerDir();
+    const chartBeforeJudgment = chartRunId ? readRunChart(chartRunId, 'outer-supervisor', chartDir) : [];
+
     let decision = decideNextRun({
       results,
       history,
       decompositionExecution: opts.promoteDecomposition !== undefined,
       // Undeclared = cannot run the repair goal: an add-repair-task would otherwise be a same-strategy relaunch.
       repairGoalExecution: opts.repairGoalExecution === true,
+      ...(opts.needsHumanReasonRepairExecution === undefined ? {} : { needsHumanReasonRepairExecution: opts.needsHumanReasonRepairExecution }),
       ...(aggregateReviewTrend(results) ? { reviewMustFixTrend: aggregateReviewTrend(results) } : {}),
       ...(opts.limits ? { limits: opts.limits } : {}),
       ...(observed.deployFindings ? { deployFindings: observed.deployFindings } : {}),
       deliverableObservation: observed.state,
+      runChart: chartBeforeJudgment,
       ...(unreviewed.length > 0 ? {
         reviewed: false,
         ...(allUnreviewedAreNoDiff ? { reviewReason: 'no-diff' } : {}),
       } : {}),
     });
+    if (chartRunId) {
+      recordRunChartDecision({ runId: chartRunId, device: 'outer-supervisor',
+        stopKey: `${chartRunId}:outer-supervisor:${history.length + 1}`, observed: `results=${results.length}`,
+        verdict: decision.action, action: decision.action === 'stop' ? decision.stopReason ?? 'stop' : 'relaunch',
+        handoff: decision.action === 'stop' ? 'human' : 'macrophage', why: decision.why,
+        readStopKeys: chartBeforeJudgment.map((cell) => cell.stopKey), dir: chartDir });
+    }
+
+    const reasonRepairSkipped = decision.action !== 'stop' || decision.stopReason !== 'needs-human' || history.length + 1 > maxRounds
+      ? [] : results.flatMap((result) => {
+      if (!decision.needsHuman.includes(result.taskId) || needsHumanRepairReason(result) === undefined) return [];
+      if (!decision.classifications.some((classification) => classification.taskId === result.taskId && classification.kind === 'unclassified')) return [];
+      const repairReason = needsHumanRepairReason(result)!;
+      if (needsHumanRepairSpent(history, repairReason, result.feature)) return [];
+      const reason = opts.repairGoalExecution !== true || opts.needsHumanReasonRepairExecution !== true
+        ? 'disabled' : 'no-target-paths';
+      if (reason === 'no-target-paths' && (result.targetPaths?.length ?? 0) > 0) return [];
+      return [{ taskId: result.taskId, reason }];
+    });
+    for (const skipped of reasonRepairSkipped) {
+      try { opts.observe?.('supervisor.reason-repair-skipped', skipped); } catch { /* fail-soft */ }
+    }
 
     // The supervisor consumes knowhow when it judges a failed piece. Keep the child prompt untouched.
     const failedPiece = results.find((result) => result.status === 'failed' && result.feature.trim());
@@ -1166,7 +1380,7 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
       }
     }
 
-    const runId = opts.runStore?.runId ?? results.find((result) => result.runId?.trim())?.runId ?? null;
+    const runId = chartRunId;
 
     let decomposePromotion: DecomposePromotionObservation = decision.decomposable.length === 0
       ? { attempted: false, reason: 'no-decomposable-decision' }
@@ -1188,7 +1402,13 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
         decomposePromotion = { attempted: true, reason: `shim-failed: ${String(error)}` };
       }
     }
-    if (decision.selfHeal) {
+    if (decision.selfHeal && needsHumanRepairDecisionReason(decision.selfHeal.reason) !== undefined) {
+      // NEEDS-HUMAN-REASON-REPAIR — 수복 시도는 rerun 이 사유별 수복 골로 실행한다(아래 repairGoals).
+      //   여기서는 «한 번 시도했다»를 관측하고 relaunch 를 유지한다 — 실패는 다음 라운드 판정이 사유·시도 원문으로 접는다.
+      try { opts.observe?.('supervisor-self-heal', { runId, reason: decision.selfHeal.reason,
+        attempt: decision.selfHeal.attempt, taskIds: decision.selfHeal.taskIds,
+        outcome: 'relaunching', repairGoalTasks: Object.keys(decision.selfHeal.repairGoals ?? {}) }); } catch { /* fail-open */ }
+    } else if (decision.selfHeal) {
       const promoted = decomposePromotion.attempted && (decomposePromotion.pieceCount ?? 0) >= 2;
       try { opts.observe?.('supervisor-self-heal', { runId, reason: decision.selfHeal.reason,
         attempt: decision.selfHeal.attempt, taskIds: decision.selfHeal.taskIds,
@@ -1309,7 +1529,7 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
     // but their results stay in the round so the human hand-off (and the final review-oscillating stop) keeps them.
     const held = decision.oscillation?.heldTaskIds ?? [];
     const heldResults = results.filter((result) => held.includes(result.taskId));
-    const repairGoals = { ...decision.relaunchGoals, ...decision.oscillation?.repairGoals };
+    const repairGoals = { ...decision.relaunchGoals, ...decision.selfHeal?.repairGoals, ...decision.oscillation?.repairGoals };
     const rerunResults = await opts.rerun(held.length ? results.filter((result) => !held.includes(result.taskId)) : results,
       { relaunch: true, ...(Object.keys(repairGoals).length > 0 ? { repairGoals } : {}) });
     results = [...rerunResults, ...heldResults.filter((heldResult) => !rerunResults.some((result) => result.taskId === heldResult.taskId))];

package/src/self-dev/run-types.ts

@@ -27,6 +27,10 @@ export interface SelfDevGoal {
   kind?: JobKind;
   /** Decomposition intent; deliberately distinct from executable `kind`. */
   goalType?: SelfDevGoalType;
+  /** Required for default-LLM decomposition slices; included in the child task prompt. */
+  completionBoundary?: string;
+  /** Existing simulation evidence required to make a decomposed slice independently reviewable. */
+  mockScenario?: { id: string; injection: string; observation: string };
   /** Feature/goal text → `elanous self implement <feature>` for dev jobs. */
   feature: string;
   /** Pod lease predecessor goal ID or PR number. */
@@ -114,6 +118,9 @@ export interface SelfDevJobResult {
   completionDisposition?: string;
   /** Abandoned-run classification from the child. Independent of completionDisposition. */
   failureClassification?: AbandonedClassification;
+  /** Basis and explicit terminal reason are kept separate from the classification label. */
+  classificationBasis?: string;
+  terminationReason?: string;
   /** Provider failure evidence from the child result; absent when unobserved. */
   providerErrors?: { count: number; provider: string; category: 'quota' | 'credential' | 'request' | 'other' };
   /** Stable child run identity used to join its run-ledger proposal. */

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

@@ -1,6 +1,7 @@
 import { spawnSync } from 'node:child_process';
 import { SPAWN_SYNC_MAX_BUFFER } from '../util/spawn-sync-output.js';
 import { debug } from '../debug/log.js';
+import { readRunChart, recordRunChartDecision } from './run-chart.js';
 import { selectKnowhowPack } from './knowhow-pack.js';
 import { loadReviewRoundBrief, type ReviewRoundBrief } from './review-round-brief.js';
 import { findIncidentPrecedents, type IncidentPrecedent } from '../harness/harness-incidents.js';
@@ -15,6 +16,8 @@ import {
   type RunLedgerCheckedAppendOutcome,
   type RunLedgerLookupOptions,
 } from './run-ledger.js';
+import { pickAutohealAction, type AutohealAction } from './stop-autoheal.js';
+import { RUN_STOP_CLASSES, type RunStopClass } from './run-stop.js';
 /** 사고 원장 루트 기본값 — 운영/시험 우주 상태 디렉터리(없으면 빈 선례 · fail-soft). */
 export function doctorVisitIncidentRoot(): string {
   return elanousStateRoot();
@@ -250,6 +253,91 @@ export function recordParentNeedsOwnerVisit(input: {
 
 export type ReadDoctorVisitsOptions = RunLedgerLookupOptions;
 
+export interface RunDoctorHandoffResult {
+  status: 'acted' | 'already-acted' | 'needs-human' | 'missing-handoff';
+  action?: AutohealAction;
+  outcome?: string;
+  stopKey: string;
+}
+
+/** Consume one persisted run-supervisor handoff through PR1's graph-aware stop prescription. */
+export async function runDoctorHandoff(input: {
+  runId: string;
+  stopKey: string;
+  dir?: string;
+  dispatch: (action: AutohealAction, handoff: Record<string, unknown>) => Promise<{ outcome: string; detail?: string }> | { outcome: string; detail?: string };
+}): Promise<RunDoctorHandoffResult> {
+  const entries = loadRunLedger(input.runId, input.dir);
+  if (entries === null) return { status: 'missing-handoff', stopKey: input.stopKey };
+  const latestHandoff = [...entries].reverse().find((entry) => entry.event === 'run-chart-cell'
+    && entry.data.device === 'run-supervisor' && entry.data.handoff === 'run-doctor');
+  const handoff = latestHandoff?.data.stopKey === input.stopKey ? latestHandoff : undefined;
+  if (!handoff) return { status: 'missing-handoff', stopKey: input.stopKey };
+  const prior = entries.filter((entry) => entry.event === 'doctor-rx' && entry.data.stopKey === input.stopKey);
+  const completed = prior.find((entry) => entry.data.status === 'completed' || entry.data.status === 'needs-human');
+  if (completed) return { status: completed.data.status === 'completed' ? 'already-acted' : 'needs-human',
+    ...(typeof completed.data.action === 'string' ? { action: completed.data.action as AutohealAction } : {}),
+    ...(typeof completed.data.outcome === 'string' ? { outcome: completed.data.outcome } : {}), stopKey: input.stopKey };
+  if (prior.some((entry) => entry.data.status === 'started')) {
+    const outcome = 'needs-human: prior doctor action started without a recorded result';
+    return { status: 'needs-human', outcome, stopKey: input.stopKey };
+  }
+
+  const chartBefore = readRunChart(input.runId, 'run-doctor', input.dir ?? runLedgerDir());
+  const rawClass = handoff.data.failureClass ?? (handoff.data.verdict === 'wait' ? 'implement-aborted' : undefined);
+  const failureClass = typeof rawClass === 'string' && (RUN_STOP_CLASSES as readonly string[]).includes(rawClass)
+    ? rawClass as RunStopClass : 'unclassified';
+  const prescription = pickAutohealAction(failureClass);
+  const visitAppend = appendRunLedgerEntryChecked(input.runId, (current) => {
+    if (current === null) return { append: false, result: false };
+    if (current.some((entry) => entry.event === 'doctor-visit' && entry.data.stopKey === input.stopKey)) return { append: false, result: true };
+    return { append: true, entry: { timestamp: new Date().toISOString(), runId: input.runId,
+      event: 'doctor-visit', data: { from: 'supervisor', symptom: 'no-progress', stopKey: input.stopKey,
+        evidence: `consecutive wait decisions=${String(handoff.data.waitCount ?? 'unknown')}`, prescription: prescription.action } } };
+  }, input.dir);
+  if (!visitAppend.appended && visitAppend.result !== true) return { status: 'missing-handoff', stopKey: input.stopKey };
+  const claim = appendRunLedgerEntryChecked(input.runId, (current) => {
+    if (current === null) return { append: false, result: 'missing-ledger' as const };
+    const priorAction = current.find((entry) => entry.event === 'doctor-rx' && entry.data.stopKey === input.stopKey);
+    if (priorAction) return { append: false, result: priorAction.data.status === 'completed' ? 'completed' as const
+      : priorAction.data.status === 'needs-human' ? 'needs-human' as const : 'in-progress' as const };
+    return { append: true, entry: { timestamp: new Date().toISOString(), runId: input.runId, event: 'doctor-rx',
+      data: { device: 'run-doctor', stopKey: input.stopKey, status: 'started', action: prescription.action,
+        source: prescription.source, ...(prescription.overlayId ? { overlayId: prescription.overlayId } : {}), executed: false } } };
+  }, input.dir);
+  if (!claim.appended) {
+    if (claim.result === 'completed') return { status: 'already-acted', action: prescription.action, stopKey: input.stopKey };
+    return { status: 'needs-human', action: prescription.action,
+      outcome: claim.result === 'needs-human' ? 'needs-human: prior action requires a person'
+        : claim.result === 'missing-ledger' ? 'needs-human: run ledger missing' : 'needs-human: doctor action already in progress',
+      stopKey: input.stopKey };
+  }
+
+  let outcome: string;
+  let detail: string | undefined;
+  try {
+    const result = await input.dispatch(prescription.action, handoff.data);
+    outcome = result.outcome;
+    detail = result.detail;
+  } catch (error) {
+    outcome = 'needs-human';
+    detail = error instanceof Error ? error.message : String(error);
+  }
+  const needsHuman = outcome === 'needs-human' || outcome.startsWith('needs-human:');
+  appendRunLedgerEntry({ timestamp: new Date().toISOString(), runId: input.runId, event: 'doctor-rx',
+    data: { device: 'run-doctor', stopKey: input.stopKey, status: needsHuman ? 'needs-human' : 'completed',
+      action: prescription.action, source: prescription.source, outcome, executed: !needsHuman,
+      ...(detail ? { detail: detail.slice(0, 300) } : {}) } }, input.dir);
+  recordRunChartDecision({ runId: input.runId, device: 'run-doctor', stopKey: input.stopKey,
+    observed: String(handoff.data.observed ?? 'supervisor handoff'), verdict: needsHuman ? 'needs-human' : 'acted',
+    action: prescription.action, handoff: needsHuman ? 'outer-supervisor'
+      : prescription.action === 'reauthor-from-materialized' ? 'reauthor' : null,
+    why: detail ?? outcome, readStopKeys: chartBefore.map((cell) => cell.stopKey), dir: input.dir ?? runLedgerDir() });
+  debug.log('run-doctor', 'action', { runId: input.runId, stopKey: input.stopKey, action: prescription.action,
+    source: prescription.source, outcome, executed: !needsHuman });
+  return { status: needsHuman ? 'needs-human' : 'acted', action: prescription.action, outcome, stopKey: input.stopKey };
+}
+
 /** Project logged review briefs into status without changing the run-ledger schema. Keep the latest observation per PR. */
 export function doctorReviewVisits(events: readonly { timestamp?: string; sequence?: number; runId?: string; key?: string; evidence?: string }[]): (Omit<DoctorVisit, 'runId'> & { runId?: string })[] {
   const seenPrs = new Set<string>();

package/src/self-implement/gate-artifacts.ts

@@ -78,6 +78,8 @@ export interface GateArtifactSummary extends GateArtifactCounts {
   head40: string | null;
   base40: string | null;
   envKey: string;
+  /** Seat self-gate marker observed at process entry (true only for ELANOUS_TRAIN_GATE=1). */
+  trainGate?: boolean;
   shards: number;
   cohort: string[];
   shardsDetail: GateArtifactShard[];
@@ -128,6 +130,7 @@ export interface GateArtifactInput {
   head40: string | null;
   base40: string | null;
   envKey: string;
+  trainGate?: boolean;
   testFiles: readonly string[];
   verdict: string | null;
   verdictLine?: string;
@@ -218,6 +221,7 @@ export function writeGateArtifacts(input: GateArtifactInput): { summaryPath: str
     head40: input.head40,
     base40: input.base40,
     envKey: input.envKey,
+    ...(input.trainGate !== undefined ? { trainGate: input.trainGate } : {}),
     shards: input.sharded ? input.sharded.shards.length : 0,
     cohort: sorted(input.testFiles),
     shardsDetail,
@@ -251,12 +255,14 @@ export function writeRemoteUnavailableGateArtifacts(
   reason: 'remote-unsupported' | 'remote-fetch-failed',
   resolveRev: RevResolver = defaultRevResolver(cwd),
   envKey: () => string = defaultGateEnvKey,
+  trainGate?: boolean,
 ): { summaryPath: string; junitFiles: string[] } {
   return writeGateArtifacts({
     dir: resolveArtifactDir(dir, cwd),
     head40: resolveRev('HEAD'),
     base40: baseRef ? resolveRev(baseRef) : null,
     envKey: envKey(),
+    trainGate,
     testFiles: [],
     verdict: null,
     exitCode,
@@ -266,6 +272,13 @@ export function writeRemoteUnavailableGateArtifacts(
   });
 }
 
+/** The local train wrapper owns the receipt marker, including when artifacts came from a remote host. */
+export function recordGateTrainMarker(summaryPath: string, trainGate: boolean): void {
+  const summary = JSON.parse(readFileSync(summaryPath, 'utf8')) as Record<string, unknown>;
+  summary.trainGate = trainGate;
+  writeFileSync(summaryPath, `${JSON.stringify(summary, null, 2)}\n`);
+}
+
 // ── 원격 산출 회수 (SIDE-VERIFY-GATE-SHARDS ②) ──────────────────────────────
 // 원격 run 은 `$W` 임시 트리에서 돌고 끝나면 trap 이 `$W` 를 지운다(gate-remote.ts remoteScript). 그래서 원격 쪽
 // `--artifact-dir` 는 `$W` «밖»의 호스트 디스크 경로(/var/tmp/elanous-gate-artifacts-<nonce>)로 준다 — run 이 끝나도 남고, 회수