elanous 0.2.38 → 0.2.41

package/src/self-dev/dev-pipeline.ts

@@ -709,16 +709,16 @@ export function buildAgentMissionDevSpec(o: {
 export async function executeAgentMissionReroute(
   spec: DevPipelineSpec,
   agentBackend: AgentBackend,
-  deps?: { runDevPipeline?: typeof runDevPipeline },
+  deps?: { runDevPipeline?: typeof runDevPipeline; signal?: AbortSignal },
 ): Promise<{ result: AgentMissionResult; exitCode: number }> {
   const run = deps?.runDevPipeline ?? runDevPipeline;
-  const r = await run(spec, { resolveBackend: () => agentBackend });
+  const r = await run(spec, { resolveBackend: () => agentBackend, ...(deps?.signal ? { signal: deps.signal } : {}) });
   // ★ 잘못된 라우팅 즉시 표면화 — spec 이 external+pty 가 아니면 kind 불일치(무조건 캐스팅 금지).
   if (r.kind !== 'agent-mission') {
     throw new DevPipelineError(`executeAgentMissionReroute: 예상 밖 dispatch(kind=${r.kind}) — external+pty spec 이어야`);
   }
   const result = r.result;
-  return { result, exitCode: result.ok ? 0 : 2 };
+  return { result, exitCode: result.reason === 'aborted' ? 130 : result.ok ? 0 : 2 };
 }
 
 // ── U4b: self implement 재라우팅 seam(테스트 가능) ──
@@ -2234,6 +2234,7 @@ async function runDevPipelineDispatch(
     const result = await run({
       ...toSelfImplementOptions(text, plan, seams),
       ...(spec.runId ? { runId: spec.runId } : {}),
+      ...(deps.signal ? { signal: deps.signal } : {}),
       onNodeEntry: (node, round) => { walk.push({ node, round }); },
     });
     // ⛔ 「걸음이 비었다」와 「안 걸었다」를 가른다 — 빈 배열은 «싣지 않는다».
@@ -2252,5 +2253,8 @@ async function runDevPipelineDispatch(
   // agent-mission-pty
   const run = deps.runAgentMission ?? (await import('../agent-mission/driver.js')).runAgentMission;
   const resolveBackend = deps.resolveBackend ?? (await import('../agent-mission/driver.js')).resolveBackend;
-  return { plan, kind: 'agent-mission', result: await run(toAgentMissionSpec(text, plan, resolveBackend)) };
+  return { plan, kind: 'agent-mission', result: await run({
+    ...toAgentMissionSpec(text, plan, resolveBackend),
+    ...(deps.signal ? { signal: deps.signal } : {}),
+  }) };
 }

package/src/self-dev/graph-front-nodes.ts

@@ -55,6 +55,19 @@ export function resetFrontVisitCountsForTesting(now?: () => number): void {
   lastFrontVisitPruneMs = Number.NEGATIVE_INFINITY;
 }
 
+/** Explicit context carried by a front-node handler. The same object can grow to
+ *  hold authoring evidence and budget/checkpoint data without changing handlers. */
+export interface FrontNodeUnitContext {
+  readonly runId?: string;
+  readonly goalType?: GoalType;
+}
+
+/** A front-half processing unit with an explicit input, context, and output. */
+export interface FrontNodeUnit<Input, Output> {
+  readonly node: FrontNodeId;
+  readonly execute: (input: Input, context: FrontNodeUnitContext) => Promise<Output>;
+}
+
 /** Record the actual front-half execution boundary, without controlling the stage. */
 export async function observeFrontNodeUnit<T>(node: FrontNodeId, runId: string | undefined, goalType: GoalType | undefined, execute: () => Promise<T>): Promise<T> {
   const emit = (phase: 'enter' | 'exit'): void => {
@@ -74,6 +87,16 @@ export async function observeFrontNodeUnit<T>(node: FrontNodeId, runId: string |
   finally { emit('exit'); }
 }
 
+/** Execute one typed front-node unit while preserving the caller's context and
+ *  the fail-soft graph.unit observation contract. */
+export function runFrontNodeUnit<Input, Output>(
+  unit: FrontNodeUnit<Input, Output>,
+  input: Input,
+  context: FrontNodeUnitContext,
+): Promise<Output> {
+  return observeFrontNodeUnit(unit.node, context.runId, context.goalType, () => unit.execute(input, context));
+}
+
 function pruneIdleFrontVisitRuns(nowMs: number): void {
   if (nowMs - lastFrontVisitPruneMs < FRONT_VISIT_PRUNE_INTERVAL_MS) return;
   lastFrontVisitPruneMs = nowMs;

package/src/self-dev/graph-journey-route.ts

@@ -122,6 +122,10 @@ export function readJourneyEdge(
  *  그 밖의 칸은 그 간선에 결속할 근거(예: 착지 거부 원문·cardId · LAND-REFUSAL-EDGES) — 간선 칸(from·to·taken…)을 덮지 못한다. */
 export interface JourneyEdgeFields {
   readonly moveId?: string;
+  readonly runId?: string;
+  readonly card?: string;
+  readonly pr?: number;
+  readonly head?: string;
   readonly [key: string]: unknown;
 }
 
@@ -140,11 +144,15 @@ export function recordJourneyEdge(route: JourneyRoute, taken: string, reason?: s
       graphId: 'self-implement', node: skipped.node, reason: 'condition', condition: skipped.condition,
       ...journeyJoinFields(),
     });
-    // Evidence never overrides an edge field: the later spread wins, and `reason`/join keys are reserved.
-    const { reason: _reservedReason, journeyKey: _reservedJourney, queueLaunchId: _reservedLaunch, ...evidence } = data ?? {};
+    // Evidence never overrides an edge field: the later spread wins. Explicit repair join keys win over ambient context.
+    const { reason: _reservedReason, journeyKey: _reservedJourney, queueLaunchId: _reservedLaunch,
+      runId, card, pr, head, moveId, ...evidence } = data ?? {};
     debug.log('self-implement', 'graph-edge-taken', {
       ...evidence, graphId: 'self-implement', ...route, taken, honored: route.to === null || route.to === taken,
       ...(reason === undefined ? {} : { reason }), ...journeyJoinFields(),
+      ...(runId === undefined ? {} : { runId }), ...(card === undefined ? {} : { card }),
+      ...(pr === undefined ? {} : { pr }), ...(head === undefined ? {} : { head }),
+      ...(moveId === undefined ? {} : { moveId }),
     });
   } catch { /* 관측은 fail-soft */ }
 }

package/src/self-dev/launch-preflight-text.ts

@@ -22,8 +22,8 @@ export interface LaunchPreflightBlocker {
   readonly name: string;
   /** 왜 막혔는지 한 줄 — 경로와 수를 포함한다. */
   readonly detail: string;
-  /** 골 판독 실패(`goal-unreadable`)와 traced-path 오류(`missing-traced-path`)를 가르는 사유 코드. */
-  readonly reasonCode?: 'goal-unreadable' | 'missing-traced-path';
+  /** 골 판독 실패(`goal-unreadable`) · 골 해석 실패(`goal-parse`) · traced-path 오류(`missing-traced-path`)를 가르는 사유 코드. */
+  readonly reasonCode?: 'goal-unreadable' | 'goal-parse' | 'missing-traced-path';
   /** 어느 검사인지 — 경로를 접지 않은 검사 이름. */
   readonly checkName?: string;
   /** 잘리지 않은 대상 경로. 경로 없는 검사(빈 traced paths)는 생략한다. */

package/src/self-dev/launch-preflight.ts

@@ -695,7 +695,7 @@ export interface AskPreflightDeps {
   /** 던지면 그 축은 `unknown` 이 된다. */
   readonly listUnfinishedRuns: (path?: string) => readonly PreflightUnfinishedRun[];
   /** 실제 실행 확신 판정. 기본은 테스트 우주까지 포함한 `queryRunningRuns`이며, 실패는 경고 한 줄로만 남긴다. */
-  readonly queryRunningRuns?: (options: { includeTest: true }) => RunningRunsResult;
+  readonly queryRunningRuns?: (options: { includeTest: true; timeBudgetMs?: number }) => RunningRunsResult;
   /** 이미 완료된 런 조회. `plannedPaths`는 원장 정규화 결과라 경로 겹침 판정에 재사용한다. */
   readonly listCompletedRuns?: (limit: number, paths?: string | readonly string[]) => PreflightCompletedRunsQuery;
   /** 이미 종료된 중단 런 조회. `plannedPaths`는 원장 정규화 결과라 경로 겹침 판정에 재사용한다. */
@@ -1019,9 +1019,14 @@ export type RunningRunsConfidenceAssessment =
     readonly includesTest: true;
   };
 
-export function assessRunningRunsConfidence(query: (options: { includeTest: true }) => RunningRunsResult, nowMs: number = Date.now()): RunningRunsConfidenceAssessment {
+const LAUNCH_PREFLIGHT_RUNNING_RUNS_BUDGET_MS = 3_000;
+
+export function assessRunningRunsConfidence(query: (options: { includeTest: true; timeBudgetMs?: number }) => RunningRunsResult, nowMs: number = Date.now()): RunningRunsConfidenceAssessment {
   try {
-    const running = query({ includeTest: true });
+    const running = query({ includeTest: true, timeBudgetMs: LAUNCH_PREFLIGHT_RUNNING_RUNS_BUDGET_MS });
+    if (running.stalled) {
+      throw new Error(`조회 예산 초과(${running.stalled.stage}: ${running.stalled.reason})`);
+    }
     const confirmedCount = running.counts.running;
     const probableCount = running.counts['probable-running'];
     if (!Number.isSafeInteger(confirmedCount) || confirmedCount < 0 || !Number.isSafeInteger(probableCount) || probableCount < 0) {
@@ -1055,7 +1060,7 @@ export function assessRunningRunsConfidence(query: (options: { includeTest: true
 }
 
 /** 나이 기반 기존 집계와 별도로 실제 PTY·원장을 교차한 확신 판정을 사람이 읽는 한 줄로 만든다. */
-export function renderRunningRunsConfidenceAppendix(query: (options: { includeTest: true }) => RunningRunsResult, nowMs: number = Date.now()): string {
+export function renderRunningRunsConfidenceAppendix(query: (options: { includeTest: true; timeBudgetMs?: number }) => RunningRunsResult, nowMs: number = Date.now()): string {
   return assessRunningRunsConfidence(query, nowMs).appendix;
 }
 
@@ -1112,14 +1117,31 @@ export function decideAskPreflight(
   const inspectionRoot = goalDocument === null || !hasAuthoredGoal
     ? undefined
     : opts.declaredPathsRoot?.trim() || process.cwd();
-  const authoredTracedPaths = goalDocument === null
-    ? []
-    : inspectableAuthoredTracedPaths(deps.tracedPaths(goalDocument), inspectionRoot);
+  // ⛔ 골 «판독»(읽기) 실패와 골 «해석» 실패는 고칠 곳이 다르다 — 파서가 던진 예외를 사유 코드로 바꿔
+  //   원장에 «어느 검사가» 막았는지 남긴다(AUT-PREFLIGHT-REASON-OPAQUE: 두 갈래가 한 문장으로 뭉개졌다).
+  let goalParseFailure: { readonly checkName: string; readonly message: string } | undefined;
+  const authoredTracedPaths = (() => {
+    if (goalDocument === null) return [];
+    try {
+      return inspectableAuthoredTracedPaths(deps.tracedPaths(goalDocument), inspectionRoot);
+    } catch (error) {
+      goalParseFailure = { checkName: 'goal-parse', message: oneLineConfidenceFailureDetail(error) };
+      return [];
+    }
+  })();
   const tracedPathsRaw = opts.pathsOverride ?? authoredTracedPaths;
   const tracedPaths = inspectionRoot && !opts.pathsOverride
     ? tracedPathsRaw.filter((path) => tracedPathExists(path, inspectionRoot) || isFileShapedTracedPath(path))
     : tracedPathsRaw;
-  const declaredNewPaths = goalDocument === null ? new Set<string>() : new Set(declaredNewFilePaths(goalDocument));
+  const declaredNewPaths = (() => {
+    if (goalDocument === null) return new Set<string>();
+    try {
+      return new Set(declaredNewFilePaths(goalDocument));
+    } catch (error) {
+      goalParseFailure ??= { checkName: 'goal-new-paths', message: oneLineConfidenceFailureDetail(error) };
+      return new Set<string>();
+    }
+  })();
   const invalidTracedPaths: Array<{ path: string; reason: 'occupied-new' | 'not-file' | 'missing' | 'inaccessible' }> = inspectionRoot
     ? authoredTracedPaths.flatMap<{ path: string; reason: 'occupied-new' | 'not-file' | 'missing' | 'inaccessible' }>((path) => {
       const occupation = tracedPathOccupation(path, inspectionRoot);
@@ -1315,7 +1337,8 @@ export function decideAskPreflight(
     ...(recentChangesUnknownReason ? { recentChangesUnknownReason } : {}),
   });
   const missingTracedPathBlockers: LaunchPreflightBlocker[] = [
-    ...(hasAuthoredGoal && authoredTracedPaths.length === 0 ? [{
+    // ⛔ 해석 실패를 「traced path 0」으로 한 번 더 뭉개지 않는다 — 그건 다른 갈래다.
+    ...(hasAuthoredGoal && authoredTracedPaths.length === 0 && goalParseFailure === undefined ? [{
       kind: 'missing-traced-path' as const,
       name: '최종 골의 TRACED PATHS 경로 0',
       detail: '정리 후 보존된 traced 경로가 없다 — 실제 파일 또는 유효한 신설: 파일 경로를 골에 선언해야 발사할 수 있다',
@@ -1347,16 +1370,29 @@ export function decideAskPreflight(
     checkName: 'goal-read',
     targetPath: resolvedGoalFile,
   }] : [];
+  const goalParseBlockers: LaunchPreflightBlocker[] = goalParseFailure ? [{
+    kind: 'goal-unreadable',
+    name: `골 문서 해석 실패: ${opts.goalFile}`,
+    detail: `${goalParseFailure.checkName} 검사가 골 문서를 해석하지 못했다(${goalParseFailure.message}) — 골 판독 실패(goal-unreadable)도 traced path 오류(missing-traced-path)도 아닌 별개 갈래다 · 어느 검사가 막았는지는 checkName 이 가른다 — 골의 TRACED PATHS · 신설: 문면을 바로잡아야 한다`,
+    reasonCode: 'goal-parse' as const,
+    checkName: goalParseFailure.checkName,
+    targetPath: resolvedGoalFile,
+  }] : [];
   const decisionResult = {
     ...result,
-    blockers: [...result.blockers, ...missingTracedPathBlockers, ...goalReadBlockers],
+    // ⛔ 해석 실패를 「대상 경로 0」 문면으로 덮지 않는다 — 사유 코드가 이미 그 자리를 말한다.
+    blockers: [
+      ...result.blockers.filter((blocker) => goalParseFailure === undefined || blocker.kind !== 'no-target-paths'),
+      ...missingTracedPathBlockers, ...goalParseBlockers, ...goalReadBlockers,
+    ],
     warnings: [...result.warnings, ...askMarkerWarnings],
     runningRunsConfidenceAppendix: runningRunsConfidence.appendix,
   };
   emittedAskMarkerObservations.add(decisionResult);
   return {
     result: decisionResult,
-    shouldLaunch: missingTracedPathBlockers.length === 0 && goalReadBlockers.length === 0 && (result.blockers.length === 0 || force),
+    shouldLaunch: missingTracedPathBlockers.length === 0 && goalParseBlockers.length === 0 && goalReadBlockers.length === 0
+      && (result.blockers.length === 0 || force),
     plannedBranchResolution,
   };
 }

package/src/self-dev/orchestrate-cli.ts

@@ -451,6 +451,7 @@ export async function runSelfOrchestrateCliCommand(
       await recordRoundPrs(results);
       results = await superviseRun({
         initial: results,
+        knowhowRepo: deps.repositoryRoot ?? process.cwd(),
         // The add-repair-task branch below runs each authored review-oscillation repair goal as that goal's new
         // feature (a fresh piece, same goal id) — the supervisor records the repair text, so a second oscillation stops.
         repairGoalExecution: true,

package/src/self-dev/orchestrate.ts

@@ -1529,6 +1529,9 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
           ...(!cancelling && disp?.stopReason ? { stopReason: disp.stopReason } : {}),
           ...(disp?.completionDisposition ? { completionDisposition: disp.completionDisposition } : {}),
           ...(disp?.failureClassification ? { failureClassification: disp.failureClassification } : {}),
+          ...(disp?.childEvidence?.classificationBasis ? { classificationBasis: disp.childEvidence.classificationBasis } : {}),
+          ...(typeof disp?.childEvidence?.terminationReason === 'string'
+            ? { terminationReason: disp.childEvidence.terminationReason } : {}),
           ...(disp?.providerErrors ? { providerErrors: disp.providerErrors } : {}),
           ...(disp?.rework ? { rework: disp.rework } : {}),
           ...(disp?.mustFix ? { reviewMustFix: disp.mustFix } : {}),
@@ -1542,7 +1545,17 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
     };
 
     // S3 — persist a resumable checkpoint after each job settles (fail-soft).
+    let checkpointRound = 0;
     const doCheckpoint = (): void => {
+      checkpointRound++;
+      const progressResults = buildResults();
+      const progress = summarizeResults(progressResults);
+      const remaining = Math.max(0, progressResults.length - progress.done - progress.failed - progress.cancelled);
+      try { debug.log('self-dev.orchestrate', 'progress', {
+        runId: runId ?? null, round: checkpointRound, total: progressResults.length,
+        done: progress.done, failed: progress.failed, cancelled: progress.cancelled,
+        landed: progress.landed, remaining,
+      }); } catch { /* progress observation must not change orchestration */ }
       if (opts.checkpoint) { try { opts.checkpoint(buildResults()); } catch { /* fail-soft */ } }
       if (opts.onSnapshot) { try { opts.onSnapshot(graph.snapshot().tasks); } catch { /* fail-soft */ } }
     };
@@ -1559,6 +1572,8 @@ export function orchestrateSelfDev(opts: OrchestrateSelfDevOptions): Promise<Sel
             stage: result.stage ?? null,
             mergeReason: result.mergeReason ?? null,
             failureClassification: result.failureClassification ?? null,
+            classificationBasis: result.classificationBasis ?? null,
+            terminationReason: result.terminationReason ?? null,
             prNumber: result.prNumber ?? null,
           });
         } catch { /* terminal observation must not change the result */ }

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

@@ -9,6 +9,7 @@ export { SUPERVISOR_STOP_REASONS } from './run-types.js';
 import { recordSelfDevRunSupervisorStop, selfDevRunsDir } from './run-store.js';
 import { debug } from '../debug/log.js';
 import { sweepFrozenMerges } from '../self-implement/frozen-merges.js';
+import { selectKnowhowPack } from '../self-implement/knowhow-pack.js';
 import { routeSupervisorVerdict } from './supervisor-verdict-edges.js';
 import type { TaskAgentShadowInput } from '../task-agent/shadow.js';
 import { cardPrNumber, taskAgentStatePath } from '../task-agent/task-hand.js';
@@ -42,6 +43,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.
@@ -101,6 +107,10 @@ export interface SupervisorDecision {
   action: 'relaunch' | 'add-repair-task' | 'stop';
   stopReason?: SupervisorStopReason;
   why: string;
+  /** Repository lessons pulled at this decision, never appended to a child's goal. */
+  knowhowPackSliceIds?: string[];
+  /** Bounded reference for the supervisor handoff. It is evidence, not an executable child instruction. */
+  knowhowPackReference?: string;
   round: number;
   rerunnable: string[];
   reworkable: string[];
@@ -132,7 +142,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 [
+    `[supervisor-needs-human-repair:${reason}] ${NEEDS_HUMAN_REPAIR_INSTRUCTION[reason]}`,
+    ...(repairTargets?.length ? [`대상 경로: ${repairTargets.join(', ')}`] : []),
+    ...(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 {
@@ -240,6 +339,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 {
@@ -355,6 +459,8 @@ 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 {
@@ -545,7 +651,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',
@@ -797,6 +948,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),
@@ -821,6 +975,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.
@@ -1027,6 +1190,8 @@ export function patternMineSignaturesFromDecision(decision: SupervisorDecision):
 
 export interface SuperviseRunOptions {
   initial: readonly SupervisorJobResult[];
+  /** Stable repository source for decision-time knowhow; falls back to a result worktree if omitted. */
+  knowhowRepo?: string;
   rerun: (previous: readonly SupervisorJobResult[], invocation: { relaunch: true; repairGoals?: Record<string, string> }) => Promise<readonly SupervisorJobResult[]>;
   limits?: SupervisorLimits;
   enrich?: (results: readonly SupervisorJobResult[]) => readonly SupervisorJobResult[];
@@ -1041,6 +1206,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).
@@ -1090,6 +1256,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 {
@@ -1137,6 +1304,7 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
       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 } : {}),
@@ -1147,6 +1315,33 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
       } : {}),
     });
 
+    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());
+    if (failedPiece) {
+      const repo = opts.knowhowRepo ?? failedPiece.worktreePath;
+      if (repo) {
+        const pulled = selectKnowhowPack(repo, failedPiece.feature);
+        try { opts.observe?.('knowhow-pack-decision', { taskId: failedPiece.taskId, ids: pulled.ids, reason: pulled.reason, action: decision.action }); } catch { /* fail-soft */ }
+        if (pulled.ids.length) decision = { ...decision, knowhowPackSliceIds: pulled.ids, knowhowPackReference: pulled.text,
+          why: `${decision.why} · 판단 참고 노하우 ${pulled.ids.join(',')}` };
+      }
+    }
+
     const runId = opts.runStore?.runId ?? results.find((result) => result.runId?.trim())?.runId ?? null;
 
     let decomposePromotion: DecomposePromotionObservation = decision.decomposable.length === 0
@@ -1169,7 +1364,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,
@@ -1290,7 +1491,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

@@ -114,6 +114,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/device-first.ts

@@ -72,6 +72,12 @@ export function ensureDeviceFirstSteps(goal: string, steps: readonly string[], r
   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/'));
+  // ⭐ TDD 를 로직으로(S4) — 문면이 아니라 로직 판정에 필요한 RED→GREEN 기록 필드를 조각 계획에 실어
+  //   넘긴다. 오케스트레이터가 [tdd-red]/[tdd-green] 기록의 태그·같은 명령·결과를 판정한다(문면 유지).
+  const tddRecordFields = 'TDD 기록 필드: 첫 조각 커밋에 피처 시험을 먼저 쓰고 구현 전 실행 RED 기록을 남긴다'
+    + " — 'EVIDENCE: [tdd-red] <무엇을 확인했나> || <증거 명령>' 다음 줄 'RESULT: <실패 요약 한 줄>'"
+    + " · 구현 뒤 같은 명령의 GREEN 기록을 남긴다 — 'EVIDENCE: [tdd-green] <무엇을 확인했나> || <같은 증거 명령>' 다음 줄 'RESULT: <통과 요약 한 줄>'"
+    + ' · 오케스트레이터가 두 기록의 태그·같은 명령·결과를 로직으로 판정하고 없으면 수리 라운드를 돌린다';
   const completeFeatureStage = (stage: string, index: number): string => {
     const withPredecessor = stage.includes(predecessor) ? stage : `${stage}\n${predecessor}`;
     const declaredGoalTest = index === 0 ? goalFeatureTest : undefined;
@@ -87,10 +93,10 @@ export function ensureDeviceFirstSteps(goal: string, steps: readonly string[], r
       ? 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을 확인한다.`;
+    if (!featureTest) return `${withoutWrongPlan}\n검증 계획(TDD): 시험 경로 미확정(${stageSource ? `${stageSource}의 시험 확장자 미정` : '조각 대상 경로 없음'}) · 이 조각에서 시험 경로를 먼저 정하고 RED 실패 뒤 같은 명령으로 GREEN을 확인한다. ${tddRecordFields}`;
     const inventory = root === undefined ? '시험 재고 미측정(대상 루트 미상)'
       : existsSync(join(root, featureTest)) ? '기존 시험' : '신규 시험(이 조각에서 먼저 신설)';
-    return `${withoutWrongPlan}\n검증 계획(TDD): ${inventory} ${featureTest} · 피처 시험 bun test ${featureTest}를 구현 전에 RED로 확인하고 생산 경로를 구현한 뒤 같은 명령으로 GREEN을 확인한다.`;
+    return `${withoutWrongPlan}\n검증 계획(TDD): ${inventory} ${featureTest} · 피처 시험 bun test ${featureTest}를 구현 전에 RED로 확인하고 생산 경로를 구현한 뒤 같은 명령으로 GREEN을 확인한다. ${tddRecordFields}`;
   };
   const targetPaths = [decision.device, test].filter((path) => root !== undefined && existsSync(join(root, path)));
   const newPaths = [decision.device, test].filter((path) => !targetPaths.includes(path));