elanous 0.2.29 → 0.2.32

package/src/self-implement/goal-author.ts

@@ -480,6 +480,69 @@ export function linesOutsideFencedCode(document: string): GoalDocSourceLine[] {
   return outside;
 }
 
+/** TA 완료 경계는 기존 정식 절 안의 세 독립 행이다. 원문에 없는 값을 저작기가 만들지 않는다. */
+export const GOAL_DONE_BOUNDARY_LABELS = ['완료 경계 코드', '완료 경계 실물', '완료 경계 증거 명령'] as const;
+export type GoalDoneBoundaryLabel = typeof GOAL_DONE_BOUNDARY_LABELS[number];
+// This is a declaration check, not a judgement of whether the proposed work
+// is good. Remove only presentation marks before comparing known placeholders.
+const GOAL_DONE_EMPTY_VALUES = new Set(['', 'na', 'ok', 'yes', 'pass', 'done', '완료', '확인']);
+const GOAL_DONE_UNRESOLVED_PREFIXES = ['tbd', 'todo', 'unknown', 'notdeclared', 'notavailable', '미정', '추후', '없음'];
+
+function isGoalDonePlaceholder(value: string): boolean {
+  const normalized = value.normalize('NFKC').toLowerCase().replace(/[\p{P}\p{S}\s]+/gu, '');
+  return GOAL_DONE_EMPTY_VALUES.has(normalized)
+    || GOAL_DONE_UNRESOLVED_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+// Evidence must be an executable command line, not another prose acceptance
+// criterion. Keep this lexical: the preflight cannot safely run the command.
+// An explicit executable is required so prose such as "Check that tests pass"
+// does not become a false completion boundary.
+const GOAL_DONE_EVIDENCE_COMMAND = /^(?:[A-Za-z_][\w-]*=(?:"[^"]*"|'[^']*'|[^\s]+)\s+)*(eln|bun|git|gh|rg|test|npm|pnpm|yarn|node|python|python3|pytest|bash|sh|make|cargo|go|curl|jq|sqlite3|grep|sed|awk|cat|find|ssh|docker|kubectl|(?:\.\/|\/|~\/)[^\s]+)(?:\s+(.*))?$/;
+// The goal boundary parser never invokes commands, so compound shell lines are
+// outside its supported evidence grammar and must not be accepted as proof.
+const GOAL_DONE_UNSUPPORTED_SHELL_OPERATOR = /&&|\|\||[;|><`]|\$\(/;
+// Only the narrow, concrete file predicates are accepted for `test`; the
+// predicate also needs its operand, so `test -f` cannot claim proof.
+const GOAL_DONE_SHELL_TEST_ARGS = /^-(?:f|e)\s+\S+(?:\s|$)/;
+
+function isGoalDoneEvidenceCommand(value: string): boolean {
+  if (GOAL_DONE_UNSUPPORTED_SHELL_OPERATOR.test(value)) return false;
+  const match = GOAL_DONE_EVIDENCE_COMMAND.exec(value);
+  const args = match?.[2]?.trim() ?? '';
+  return !!match && args.length > 0 && (match[1] !== 'test' || GOAL_DONE_SHELL_TEST_ARGS.test(args));
+}
+
+function unwrapGoalDoneValue(value: string): string {
+  let result = value.trim();
+  const wrappers: Array<readonly [string, string]> = [['`', '`'], ['"', '"'], ["'", "'"], ['“', '”'], ['‘', '’']];
+  // Each pass removes two characters. Repeated wrappers cannot hide a marker.
+  while (result.length >= 2) {
+    const pair = wrappers.find(([open, close]) => result.startsWith(open) && result.endsWith(close));
+    if (!pair) break;
+    result = result.slice(pair[0].length, -pair[1].length).trim();
+  }
+  return result;
+}
+
+export function inspectGoalDoneBoundary(document: string): { values: Partial<Record<GoalDoneBoundaryLabel, string>>; missing: GoalDoneBoundaryLabel[] } {
+  const values: Partial<Record<GoalDoneBoundaryLabel, string>> = {};
+  for (const line of linesOutsideFencedCode(document)) {
+    const match = /^\s*(?:[-*]\s*)?(완료 경계 코드|완료 경계 실물|완료 경계 증거 명령)\s*:\s*(.*?)\s*$/.exec(line.text);
+    if (!match) continue;
+    const label = match[1] as GoalDoneBoundaryLabel;
+    const value = match[2]?.trim() ?? '';
+    const inspected = unwrapGoalDoneValue(value);
+    if (!isGoalDonePlaceholder(value)
+      && (label !== '완료 경계 증거 명령' || isGoalDoneEvidenceCommand(inspected))) values[label] = value;
+  }
+  return { values, missing: GOAL_DONE_BOUNDARY_LABELS.filter((label) => !values[label]) };
+}
+
+export function explicitGoalDoneBoundaryLines(ask: string): string[] {
+  const { values } = inspectGoalDoneBoundary(ask);
+  return GOAL_DONE_BOUNDARY_LABELS.flatMap((label) => values[label] ? [`- ${label}: ${values[label]}`] : []);
+}
+
 // CommonMark 펜스는 **한 종류의 문자**가 3개 이상 이어진 런이다 — `[`~]{3,}` 는 혼합(백틱+틸드)까지
 // 펜스로 인정해 진짜 진양성을 펜스 안으로 숨긴다(리뷰 must-fix). 열기/닫기 모두 이 하나를 쓴다.
 const FENCE_RUN = /^ {0,3}(`{3,}|~{3,})(.*)$/;
@@ -795,7 +858,7 @@ const SERVER_ENTRY_PATH = /(?:^|\/)server[^/]*\.(?:[cm]?[jt]sx?)$/i;
 const LOOPBACK_ADDRESS_WITH_PORT = /(?<![\p{L}\p{N}.-])(?:localhost|127\.0\.0\.1|\[::1\])(?::\d+)(?![\p{L}\p{N}_])/iu;
 
 function targetPathsInLabelPiece(piece: string): string[] {
-  return askPathTokens(piece).filter((path) => path.includes('/'));
+  return askPathTokens(piece).filter((path) => classifyTracedPathToken(path).kind === 'path');
 }
 
 function declaredTargetPaths(document: string): string[] {
@@ -1204,6 +1267,73 @@ interface TracedPathReference {
   endLine: number | null;
 }
 
+/** Every TRACED PATHS declaration token is one of these kinds. Nested repository paths are `path`. */
+export type TracedPathTokenKind = 'path' | 'bare' | 'residual' | 'repository-root' | 'empty-cover';
+
+export interface TracedPathTokenClassification {
+  readonly token: string;
+  readonly kind: TracedPathTokenKind;
+  /** Inspectable path when the token names one; null for an empty cover. */
+  readonly path: string | null;
+  /** Attached residual characters when `kind` is `residual` (for example `???` in `src/a.ts???`). */
+  readonly residual: string | null;
+}
+
+const EMPTY_COVER_TOKEN = '(빈 대상 경로)';
+/** Leftover punctuation after a complete file token (`src/a.ts???`). Must not steal extension letters. */
+const TRACED_PATH_RESIDUAL_TOKEN = /^((?:[A-Za-z0-9_.-]+\/)*[A-Za-z0-9_.-]+\.[A-Za-z0-9]+)([^A-Za-z0-9./\\:\s,;]+)$/;
+
+function isEmptyCoverToken(token: string): boolean {
+  const trimmed = token.trim();
+  return trimmed === '' || trimmed === EMPTY_COVER_TOKEN;
+}
+
+function repositoryRootFileExists(path: string, repositoryRoot: string): boolean {
+  if (path.includes('/') || path.includes('\\') || isAbsolute(path)) return false;
+  try {
+    const realRoot = realpathSync(resolve(repositoryRoot));
+    const absolutePath = resolve(realRoot, path);
+    if (dirname(absolutePath) !== realRoot || !isSameOrNestedPath(absolutePath, realRoot)) return false;
+    return lstatSync(absolutePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Classify one TRACED PATHS / 대상 경로 declaration token.
+ * Residual characters stay attached until this plate splits them; locators (`file.ts:line`) stay locators.
+ */
+export function classifyTracedPathToken(token: string, repositoryRoot?: string): TracedPathTokenClassification {
+  const trimmed = token.trim();
+  if (isEmptyCoverToken(trimmed)) {
+    return { token: trimmed, kind: 'empty-cover', path: null, residual: null };
+  }
+  const unwrapped = stripInlineCode(trimmed).replace(TRACED_PATH_LEADING_LIST_MARKERS, '').trim();
+  if (isEmptyCoverToken(unwrapped)) {
+    return { token: trimmed, kind: 'empty-cover', path: null, residual: null };
+  }
+  const residualMatch = TRACED_PATH_RESIDUAL_TOKEN.exec(unwrapped);
+  if (residualMatch?.[1] && residualMatch[2]) {
+    return { token: trimmed, kind: 'residual', path: residualMatch[1], residual: residualMatch[2] };
+  }
+  const normalized = unwrapped.replaceAll('\\', '/');
+  if (!normalized.includes('/')) {
+    if (repositoryRoot && repositoryRootFileExists(normalized, repositoryRoot)) {
+      return { token: trimmed, kind: 'repository-root', path: normalized, residual: null };
+    }
+    return { token: trimmed, kind: 'bare', path: normalized, residual: null };
+  }
+  return { token: trimmed, kind: 'path', path: normalized, residual: null };
+}
+
+/** Inspectable traced path: nested or repository-root files only. Residual, bare-only, and empty covers are not injected. */
+export function canonicalTracedPathToken(token: string, repositoryRoot?: string): string | null {
+  const classification = classifyTracedPathToken(token, repositoryRoot);
+  if (classification.kind === 'path' || classification.kind === 'repository-root') return classification.path;
+  return null;
+}
+
 /**
  * Count lines an editor would address. A file's terminating newline closes the last line rather
  * than opening a new one, so `"one\n"` is one addressable line — counting the split remainder
@@ -1377,6 +1507,8 @@ export function tracedPathReferences(document: string): TracedPathReference[] {
       // 두 번 벗긴다 — 줄번호가 백틱 **안**(`p:42`)일 수도 **밖**(`p`:42)일 수도 있다.
       const path = match ? stripInlineCode(match[1].trim()).replace(TRACED_PATH_LEADING_LIST_MARKERS, '') : undefined;
       if (!path) continue;
+      const classification = classifyTracedPathToken(path);
+      if (classification.kind === 'residual' || classification.kind === 'empty-cover') continue;
       references.push({ path, line: match?.[2] ? Number(match[2]) : null, endLine: match?.[3] ? Number(match[3]) : null });
     }
   }
@@ -2323,13 +2455,24 @@ function tracedPathsSection(facts: CodebaseGrounding | null, ask: string, reposi
   const unresolvedTargetPieces = targetLabels.flatMap((label) => label.split(/\s+[·,]\s*|[·,]\s+/))
     .flatMap((piece) => {
       const tokens = piece.trim().split(/\s+/).filter(Boolean);
-      return tokens.length === 0 ? ['(빈 대상 경로)'] : tokens.filter((token) => targetPathsInLabelPiece(token).length === 0);
+      return tokens.length === 0
+        ? ['(빈 대상 경로)']
+        : tokens.filter((token) => targetPathsInLabelPiece(token).length === 0
+          && classifyTracedPathToken(token, repositoryRoot).kind !== 'repository-root');
     });
   const labeledTargets = declaredTargetPaths(ask);
+  const labeledRootFiles = targetLabels.flatMap((label) => label.split(/\s+[·,]\s*|[·,]\s+/))
+    .flatMap((piece) => piece.trim().split(/\s+/).filter(Boolean))
+    .flatMap((token) => {
+      const classification = classifyTracedPathToken(token, repositoryRoot);
+      return classification.kind === 'repository-root' && classification.path ? [classification.path] : [];
+    });
   const scopedAskPaths = [...new Set(askPathTokens(targetScopedGoalText(ask)).filter((path) => path.includes('/')))];
   // A single repository path in an ask without a target label is still an explicit target.
   // Multiple mentions are ambiguous; do not turn background references into targets.
-  const requestedTargets = targetLabels.length ? labeledTargets : scopedAskPaths.length === 1 ? scopedAskPaths : [];
+  const requestedTargets = targetLabels.length
+    ? [...new Set([...labeledTargets, ...labeledRootFiles])]
+    : scopedAskPaths.length === 1 ? scopedAskPaths : [];
   const known = [...new Set([
     ...requestedTargets, ...scopedAskPaths, ...(facts?.files ?? []),
     ...evidence.flatMap((item) => Array.from(item.text.matchAll(SOURCE_PATH), (match) => match[0]).filter((path) => path.includes('/'))),
@@ -2338,8 +2481,9 @@ function tracedPathsSection(facts: CodebaseGrounding | null, ask: string, reposi
   try { root = repositoryRoot === undefined ? null : realpathSync(resolve(repositoryRoot)); }
   catch { root = null; }
   const valid = (path: string, allowDeclaredNew: boolean): boolean => {
-    if (!path.includes('/') || isAbsolute(path) || path.split('/').some((part) => part === '..' || part === '.')) return false;
+    if (isAbsolute(path) || path.split('/').some((part) => part === '..' || part === '.')) return false;
     if (root === null) return false;
+    if (!path.includes('/')) return classifyTracedPathToken(path, root).kind === 'repository-root';
     if (allowDeclaredNew && declaredNew.has(path) && isSafeNewTargetPath(path, root)) return true;
     try {
       const real = realpathSync(resolve(root, path));
@@ -2877,9 +3021,13 @@ interface AbsentFirstImplementationPath {
 }
 
 function askPathTokens(ask: string): string[] {
-  return ask.split(/\s+/)
-    .map((token) => token.replace(/^[`\p{P}]+|[`\p{P}]+$/gu, ''))
-    .filter((token) => token.includes('/') && /\.[^./]+$/.test(token));
+  return ask.split(/\s+/).flatMap((raw) => {
+    const withoutWrap = raw.replace(/^[`([{]+|[`)\]}]+$/g, '');
+    if (classifyTracedPathToken(raw).kind === 'residual' || classifyTracedPathToken(withoutWrap).kind === 'residual') return [];
+    const token = raw.replace(/^[`\p{P}]+|[`\p{P}]+$/gu, '');
+    if (classifyTracedPathToken(token).kind === 'residual') return [];
+    return token.includes('/') && /\.[^./]+$/.test(token) ? [token] : [];
+  });
 }
 
 const ASK_QUANTITY_WORDS = new Set(['모든', '무조건', '전부', '아래의']);
@@ -2958,7 +3106,9 @@ interface NewTargetFile {
 export function isAskPathLocatorToken(path: string): boolean {
   // Evidence (`file.ts:line`) and prefixed (`ref:path`) tokens are not file paths.
   // This plate discards them; it does not strip the colon and retry the remainder.
-  return path.split(/[\\/]/).some((component) => component.includes(':'));
+  if (path.split(/[\\/]/).some((component) => component.includes(':'))) return true;
+  const kind = classifyTracedPathToken(path).kind;
+  return kind === 'residual' || kind === 'empty-cover';
 }
 
 export function classifyAbsentFirstPathPresence(path: string, repositoryRoot?: string): AbsentFirstPathPresence {
@@ -5184,6 +5334,7 @@ async function authorGoalWithSupersededRootIntent(
       '',
       '## ACCEPTANCE CRITERIA',
       ...enhancement.checklist.map(requestedCriterionLine),
+      ...explicitGoalDoneBoundaryLines(ask),
       '',
       '## REQUIRED EVIDENCE',
       '- [requested] Verify the decision signal and the verbatim ask.',
@@ -5634,6 +5785,7 @@ async function authorGoalWithSupersededRootIntent(
       : ['## STEPS', ...(resolvedSteps.length ? resolvedSteps.map((step) => `- ${step}`) : ['- No externally injected steps.']), '']),
     '## ACCEPTANCE CRITERIA',
     ...acceptanceSection,
+    ...explicitGoalDoneBoundaryLines(ask),
     ...preservationAmbiguityCriteria(ambiguities, clarificationAnswers),
     ...preservationAmbiguityNotice(ambiguities),
     ...preservationAmbiguityClarification(clarificationQuestions, clarificationResponses),

package/src/self-implement/graph-authority.ts

@@ -17,6 +17,7 @@ import {
 import { applyGraphOverlays, selectOverlays, type GraphOverlaySpec, type OverlayRejection, type OverlaySelection, type OverlayStage } from './graph-overlay-yaml.js';
 import type { OverlayPatch } from './graph-overlay.js';
 import type { GraphTemplateSpec } from './graph-yaml.js';
+import { pickSupervisorHealOverlay, type SupervisorOverlayPick } from './heal-triage.js';
 
 /** 2026-09-26 설정 졸업 — 그래프 권위는 항상 켬. 관측 출처는 default로 고정한다. */
 export type GraphAuthoritySource = 'default';
@@ -282,7 +283,10 @@ export function graphAuthorityFields(authority: GraphAuthority, template: GraphT
 /** 오버레이 조건이 «읽을 수 있는» 상태 키. ⛔ 여기 없는 키는 원장에 값이 안 실린다.
  *  🔑 그래서 «떨어뜨리되 말은 한다» — 아래 `stateExtraKeys` 가 그 이름을 남긴다.
  *  ⭐ `author_grade` — 적응형 저작(GRAPH-AUTHOR-GRADE) 첫 조각: 저작 등급을 오버레이 상태의 «이름»으로 싣는다. */
-export const OVERLAY_STATE_KEYS = ['attempts', 'author_grade', 'goal_id'] as const;
+export const OVERLAY_STATE_KEYS = [
+  'attempts', 'author_grade', 'goal_id',
+  'substrate', 'freeze', 'docs_only', 'provider', 'quota', 'machines', 'seats',
+] as const;
 
 /** 저작 등급의 오버레이 어휘 — `goal-author` 의 `GoalAuthorGrade`(`full|lite`) 를 오버레이 등급(`normal`) 로 옮긴다.
  *  ⛔ 모르는 값(빈 값·오타)은 `undefined` — 등급을 «지어내지 않는다». */
@@ -303,7 +307,7 @@ export function normalizeAuthorGrade(value: unknown): 'lite' | 'normal' | 'compl
  *        여기서 «조용히» 떨어뜨리면 같은 병을 한 층 아래에서 다시 짓는 것이다. */
 export function overlayDecisionObservation<T extends Readonly<Record<string, unknown>>>(input: T & {
   readonly state: Readonly<Record<string, unknown>>;
-}): T & { readonly state: Readonly<Record<string, unknown>>; readonly stateExtraKeys?: readonly string[] } {
+}): Omit<T, 'state'> & { readonly state: Readonly<Record<string, unknown>>; readonly stateExtraKeys?: readonly string[] } {
   const state: Record<string, unknown> = {};
   for (const key of OVERLAY_STATE_KEYS) {
     if (!Object.hasOwn(input.state, key)) continue;
@@ -313,6 +317,14 @@ export function overlayDecisionObservation<T extends Readonly<Record<string, unk
   return { ...input, state, ...(extra.length > 0 ? { stateExtraKeys: extra } : {}) };
 }
 
+/** ⭐ 칸 GRAPH-SUPERVISOR-PICK(0.2.32) — `graph-overlay-decision` 원장에 실릴 슈퍼바이저 고르기 기록.
+ *  `overlayDecisionObservation` 을 그대로 거친다 — 판단(outcome)·근거(evidence 한 줄)와 함께
+ *  판정에 쓴 상태 칸(`state`/`stateExtraKeys`)이 같이 남는다(예: `stop_class`). */
+export type SupervisorPickRecord = SupervisorOverlayPick & {
+  readonly state: Readonly<Record<string, unknown>>;
+  readonly stateExtraKeys?: readonly string[];
+};
+
 export function decideTemplate(input: {
   readonly goalType: GoalType | undefined;
   readonly authority: GraphAuthority;
@@ -329,22 +341,42 @@ export function decideTemplate(input: {
   readonly rejections: readonly OverlayRejection[];
   readonly appliedIds: readonly string[];
   readonly appliedPatches: readonly OverlayPatch[];
+  /** ⭐ 칸 GRAPH-SUPERVISOR-PICK(0.2.32) — `stage: 'heal'` 판에만 싣는다: 슈퍼바이저가 «선언된»
+   *  오버레이 중에서 고른 판단·근거. 다른 단계는 이 칸이 없다(기본 동작 보존). */
+  readonly supervisorPick?: SupervisorPickRecord;
 } {
   const base = activeTemplate(input.goalType, input.authority);
   if (!input.authority.enabled) return { template: base, selections: [], rejections: [], appliedIds: [], appliedPatches: [] };
+  // ⭐ 칸 GRAPH-SUPERVISOR-PICK(0.2.32) — 슈퍼바이저가 «선언된» heal 오버레이 중 하나를 고른다(능력표 ③b).
+  //   ⛔ 고르기만 한다 — 새 노드를 짓지 않는다. 노드를 더하는 것은 선언의 patch 고, 그 적용은
+  //     아래 기존 selectOverlays/applyGraphOverlays 경로가 그대로 말한다.
+  //   ⛔ 후보는 graphs/overlays/ 선언(loadGraphOverlays) 중 `stage: heal` 뿐이다 — 호출부가 준
+  //     overlays 목록과 무관하게 «선언에서만» 고른다.
+  //   판단·근거는 overlayDecisionObservation(graph-overlay-decision 원장 칸)을 거쳐 기록 형태로 나간다.
+  let supervisorPick: SupervisorPickRecord | undefined;
+  if (input.stage === 'heal') {
+    const chosen = pickSupervisorHealOverlay({ state: input.state, graphId: base.graphId });
+    supervisorPick = overlayDecisionObservation({
+      outcome: chosen.outcome,
+      ...(chosen.overlayId !== undefined ? { overlayId: chosen.overlayId } : {}),
+      evidence: chosen.evidence,
+      state: input.state,
+    });
+  }
+  const pick: { supervisorPick?: SupervisorPickRecord } = supervisorPick === undefined ? {} : { supervisorPick };
   // ⛔ 「최초 결정」은 launch 단계다 — `runtime` 오버레이는 여기서 «후보가 아니다»(③ 다이나믹의 몫).
   const { applied, selections } = selectOverlays(input.overlays, {
     graphId: base.graphId, stage: input.stage, state: input.state,
   });
-  if (applied.length === 0) return { template: base, selections, rejections: [], appliedIds: [], appliedPatches: [] };
+  if (applied.length === 0) return { template: base, selections, rejections: [], appliedIds: [], appliedPatches: [], ...pick };
   const spec = (input.specs ?? GRAPH_SPECS)[base.graphId];
   // ⛔ spec 을 못 얻으면 «변형하지 않는다» — 얹은 척하지 않는다(내장 폴백으로 돌 때가 그렇다).
-  if (spec === undefined) return { template: base, selections, rejections: [], appliedIds: [], appliedPatches: [] };
+  if (spec === undefined) return { template: base, selections, rejections: [], appliedIds: [], appliedPatches: [], ...pick };
   const result = applyGraphOverlays(spec, applied);
   // ⛔ 전부 아니면 전무다 — 하나라도 거절되면 «기준 선언»으로 돈다(반쯤 얹힌 그래프를 만들지 않는다).
   return result.ok
-    ? { template: specToTemplate(result.template), selections, rejections: [], appliedIds: result.overlayIds, appliedPatches: result.patches }
-    : { template: base, selections, rejections: result.rejections, appliedIds: [], appliedPatches: [] };
+    ? { template: specToTemplate(result.template), selections, rejections: [], appliedIds: result.overlayIds, appliedPatches: result.patches, ...pick }
+    : { template: base, selections, rejections: result.rejections, appliedIds: [], appliedPatches: [], ...pick };
 }
 
 /** ⭐ RFC §5 — 노드 «방문 예산»(`max_visits`)을 실행이 «읽게» 한다.

package/src/self-implement/graph-overlay-condition.ts

@@ -1,4 +1,10 @@
 import type { RunStopClass } from './run-stop.js';
+import type { RunContract } from './graph-run-contract.js';
+import type { GateRoutingReason } from './graph-authority.js';
+import { landingFreezeState, type LandingFreeze } from '../release-loop/landing-freeze.js';
+import type { ActiveProviderInfo } from '../provider-summary.js';
+import type { ResourceView } from '../control-plane/ledger.js';
+import type { UserConfig } from '../user-config.js';
 
 /** ⭐ RFC §5 «4단계» — `applies_when` 을 «코드»가 판정한다.
  *
@@ -33,9 +39,29 @@ export function parseOverlayCondition(source: string): OverlayConditionParse {
   return { ok: true, condition: { key: key!, operator: operator as OverlayConditionOperator, literal } };
 }
 
+/** L1 values are producer observations; an unobserved field is absent, never a default. */
+export interface GraphRunState {
+  readonly attempts: number;
+  readonly goal_id?: string;
+  readonly stop_class?: RunStopClass;
+  readonly review_repeat?: number;
+  readonly sibling_overlap?: boolean;
+  readonly main_sync_conflict?: boolean;
+  readonly author_grade?: string;
+  readonly substrate?: 'local' | 'pod';
+  readonly freeze?: 'on' | 'off';
+  readonly docs_only?: boolean;
+  readonly provider?: string;
+  readonly quota?: 'ok' | 'low' | 'exhausted';
+  readonly machines?: number;
+  readonly seats?: 'on' | 'steward-only';
+}
+
 /** Inputs known at a runtime overlay decision. Every field except `attempts` may be unknown. */
 export interface RuntimeOverlayStateInput {
   readonly attempts: number;
+  /** Producer results captured for this decision; omitted in callers not yet wired to L1. */
+  readonly producers?: L1OverlayProducerReadings;
   readonly goalId?: string;
   readonly stopClass?: RunStopClass;
   readonly reviewRepeat?: number;
@@ -44,10 +70,68 @@ export interface RuntimeOverlayStateInput {
   readonly mainSyncConflict?: unknown;
   /** Only a non-empty string is a measurement. */
   readonly authorGrade?: unknown;
+  /** Pass resolved producer values, not configuration wishes or fallback guesses. */
+  readonly substrate?: unknown;
+  /** Derived from readLandingFreeze's validated, expiry-aware result. */
+  readonly freeze?: unknown;
+  readonly docsOnly?: unknown;
+  readonly provider?: unknown;
+  readonly quota?: unknown;
+  readonly machines?: unknown;
+  readonly seats?: unknown;
+}
+
+/** Producer outputs supplied at the decision boundary; omission means the producer was not read. */
+export interface L1OverlayProducerReadings {
+  readonly runContract?: Pick<RunContract, 'substrate'>;
+  readonly landingFreeze?: LandingFreeze | null;
+  /** routeGate's documents-only verdict is the known docs-only observation. */
+  readonly gateRoute?: { readonly reason: GateRoutingReason };
+  readonly activeProvider?: Pick<ActiveProviderInfo, 'provider'>;
+  /** Snapshot returned by assessQuotaExhaustion/readQuotaExhausted; only measured usage implies ok/low. */
+  readonly quotaAssessment?: { readonly exhausted: boolean | undefined; readonly accountAvailability: {
+    readonly currentUsedPercent?: number;
+    readonly thresholdPercent?: number;
+  } | undefined };
+  /** Result of listMachineResources (Nexus live membership), not fleet intent. */
+  readonly machineResources?: readonly Pick<ResourceView, 'machine' | 'expired'>[];
+  /** Resolved loop modes; do not pass an unreadable config as a default measurement. */
+  readonly seatConfig?: NonNullable<UserConfig['loops']>['seat'];
+  readonly stewardConfig?: NonNullable<UserConfig['loops']>['steward'];
+}
+
+/** Derive only observations from named producers. A missing producer never becomes false or zero. */
+export function l1OverlayStateInput(readings: L1OverlayProducerReadings): Omit<RuntimeOverlayStateInput, 'attempts'> {
+  const quota = readings.quotaAssessment;
+  const currentUsed = quota?.accountAvailability?.currentUsedPercent;
+  const threshold = quota?.accountAvailability?.thresholdPercent;
+  const seat = readings.seatConfig;
+  return {
+    ...(readings.runContract ? { substrate: readings.runContract.substrate } : {}),
+    ...(readings.landingFreeze !== undefined ? { freeze: landingFreezeState(readings.landingFreeze) } : {}),
+    ...(readings.gateRoute ? { docsOnly: readings.gateRoute.reason === 'documents-only' } : {}),
+    ...(readings.activeProvider ? { provider: readings.activeProvider.provider } : {}),
+    ...(quota?.exhausted === true ? { quota: 'exhausted' } :
+      quota?.exhausted === false && currentUsed !== undefined && threshold !== undefined
+        ? { quota: currentUsed >= threshold ? 'low' : 'ok' } : {}),
+    ...(readings.machineResources ? { machines: new Set(readings.machineResources.filter((row) => !row.expired).map((row) => row.machine)).size } : {}),
+    ...(seat && readings.stewardConfig?.mode === 'live'
+      ? { seats: seat.mode === 'on' || seat.mode === 'live-safe' ? 'on' : 'steward-only' }
+      : {}),
+  };
 }
 
 /** ⛔ 아는 값만 싣는다 — 모르면 키를 «뺀다». 0·false·빈 문자열을 지어내지 않는다. */
-export function buildRuntimeOverlayState(input: RuntimeOverlayStateInput): Record<string, unknown> {
+export function buildRuntimeOverlayState(input: RuntimeOverlayStateInput): GraphRunState & Record<string, unknown> {
+  const produced: Omit<RuntimeOverlayStateInput, 'attempts'> = input.producers === undefined ? {} : l1OverlayStateInput(input.producers);
+  // Once producers are supplied, even an omitted reading is unknown; direct legacy inputs cannot override it.
+  const substrate = input.producers === undefined ? input.substrate : produced.substrate;
+  const freeze = input.producers === undefined ? input.freeze : produced.freeze;
+  const docsOnly = input.producers === undefined ? input.docsOnly : produced.docsOnly;
+  const provider = input.producers === undefined ? input.provider : produced.provider;
+  const quota = input.producers === undefined ? input.quota : produced.quota;
+  const machines = input.producers === undefined ? input.machines : produced.machines;
+  const seats = input.producers === undefined ? input.seats : produced.seats;
   return {
     attempts: input.attempts,
     ...(input.goalId === undefined ? {} : { goal_id: input.goalId }),
@@ -56,6 +140,13 @@ export function buildRuntimeOverlayState(input: RuntimeOverlayStateInput): Recor
     ...(typeof input.siblingOverlap === 'boolean' ? { sibling_overlap: input.siblingOverlap } : {}),
     ...(typeof input.mainSyncConflict === 'boolean' ? { main_sync_conflict: input.mainSyncConflict } : {}),
     ...(typeof input.authorGrade === 'string' && input.authorGrade.length > 0 ? { author_grade: input.authorGrade } : {}),
+    ...(substrate === 'local' || substrate === 'pod' ? { substrate } : {}),
+    ...(freeze === 'on' || freeze === 'off' ? { freeze } : {}),
+    ...(typeof docsOnly === 'boolean' ? { docs_only: docsOnly } : {}),
+    ...(typeof provider === 'string' && provider.trim().length > 0 ? { provider } : {}),
+    ...(quota === 'ok' || quota === 'low' || quota === 'exhausted' ? { quota } : {}),
+    ...(typeof machines === 'number' && Number.isSafeInteger(machines) && machines >= 0 ? { machines } : {}),
+    ...(seats === 'on' || seats === 'steward-only' ? { seats } : {}),
   };
 }
 

package/src/self-implement/heal-triage.ts

@@ -1,5 +1,8 @@
 /** 결정론 트리아지 — 실패 서명과 이미 거친 역할만으로 다음 갈래를 고른다. */
 
+import { defaultOverlaysDir, loadGraphOverlays, selectOverlays, type GraphOverlaySpec } from './graph-overlay-yaml.js';
+import { GRAPH_SPECS } from './graph-templates.js';
+
 export type HealTriageOutcome =
   | 'environment-claimed'
   | 'untestable'
@@ -271,3 +274,79 @@ export function triageFailure(signature: HealFailureSignature, history?: HealTri
     evidence: ['observe-deeper 와 ground-external 을 둘 다 거쳤다', '더 올릴 해상도가 없다'],
   };
 }
+
+/** ═══ 슈퍼바이저 고르기(0.2.32 칸 GRAPH-SUPERVISOR-PICK) — «선언된» 오버레이 중에서 고른다 ═══
+ *
+ * 능력표 ③b: 고르기만 한다. ⛔ 새 그래프 노드를 «짓지 않는다» — 후보를 읽고 선언된 조건을
+ * 판정해 overlayId 하나를 고를 뿐, 템플릿을 만들거나 노드를 더하지 않는다.
+ *
+ * 후보의 실체: `graphs/overlays/`(loadGraphOverlays) 선언 중 `stage: heal` 인 것만.
+ * 조건의 값은 코드가 낸다 — 선언의 appliesWhen 을 selectOverlays(선언 조건 판정 기계)로 판정한다.
+ * 결정론: 같은 입력·같은 선언이면 언제나 같은 답 — 조건이 맞는 후보 중 «선언 순서가 가장 앞»인 것.
+ */
+
+/** 선언된 heal 오버레이 후보를 읽는 자리 — 시험이 갈아 끼운다. */
+export type DeclaredHealOverlayLoader = () => readonly GraphOverlaySpec[];
+
+export type SupervisorOverlayPickOutcome =
+  | 'picked'
+  | 'no-declared-candidate'
+  | 'no-applicable-candidate';
+
+export interface SupervisorOverlayPickInput {
+  /** 선언 조건(appliesWhen) 판정에 쓸 상태 — 예: `{ stop_class: 'pod-died' }`. */
+  readonly state: Readonly<Record<string, unknown>>;
+  /** 후보를 좁힐 그래프 id — 기본은 활성 self-implement 그래프. */
+  readonly graphId?: string;
+}
+
+/** 고르기 결과 — outcome+evidence 계약(triageFailure·classifyReworkCapExhaustion 과 같은 양식). */
+export interface SupervisorOverlayPick {
+  readonly outcome: SupervisorOverlayPickOutcome;
+  /** outcome='picked' 일 때 고른 선언 오버레이. */
+  readonly overlayId?: string;
+  readonly evidence: readonly string[];
+}
+
+/** `graphs/overlays/` 선언에서 `stage: heal` 인 것만 읽는다 — 고르기 후보의 실체. */
+export function loadDeclaredHealOverlays(): readonly GraphOverlaySpec[] {
+  return loadGraphOverlays(defaultOverlaysDir()).overlays.filter((spec) => spec.stage === 'heal');
+}
+
+/**
+ * 선언된 heal 오버레이 후보 중 하나를 고른다. 조건이 맞는 후보가 여럿이면 선언 순서가
+ * 가장 앞인 것을 고른다(결정론). 던지지 않는다 — 못 고르는 이유는 evidence 가 말한다.
+ */
+export function pickSupervisorHealOverlay(
+  input: SupervisorOverlayPickInput,
+  load: DeclaredHealOverlayLoader = loadDeclaredHealOverlays,
+): SupervisorOverlayPick {
+  let declared: readonly GraphOverlaySpec[];
+  try {
+    declared = load();
+  } catch (error) {
+    const why = error instanceof Error ? error.message : String(error);
+    return { outcome: 'no-declared-candidate', evidence: [`선언을 읽지 못했다: ${why}`] };
+  }
+  const healOnly = declared.filter((spec) => spec.stage === 'heal');
+  if (healOnly.length === 0) {
+    return { outcome: 'no-declared-candidate', evidence: ['선언된 heal 오버레이 후보가 없다'] };
+  }
+  const graphId = input.graphId ?? GRAPH_SPECS['self-implement']?.graphId;
+  if (!graphId) {
+    return { outcome: 'no-declared-candidate', evidence: ['활성 self-implement 그래프 선언이 없다'] };
+  }
+  let applied: readonly GraphOverlaySpec[];
+  try {
+    applied = selectOverlays(healOnly, { graphId, stage: 'heal', state: { ...input.state } }).applied;
+  } catch (error) {
+    const why = error instanceof Error ? error.message : String(error);
+    return { outcome: 'no-applicable-candidate', evidence: [`선언 조건 판정이 실패했다: ${why}`] };
+  }
+  const applicable = new Set(applied.map((spec) => spec.overlayId));
+  const first = healOnly.find((spec) => applicable.has(spec.overlayId));
+  if (!first) {
+    return { outcome: 'no-applicable-candidate', evidence: [`선언된 heal 후보 ${healOnly.length}개 중 조건이 맞는 것이 없다`] };
+  }
+  return { outcome: 'picked', overlayId: first.overlayId, evidence: [`선언된 heal 후보 ${healOnly.length}개 중 조건이 맞는 첫 선언: ${first.overlayId}`] };
+}