elanous 0.2.23 → 0.2.25

package/src/self-implement/goal-new-paths.ts

@@ -0,0 +1,42 @@
+/**
+ * ⭐ AUTHOR-NEW-FILE-PATHS — 저작 골 문서가 «새로 만들 파일»로 선언한 경로.
+ *
+ * 저작(TRACED PATHS 존재 검사)과 실행(orchestrator 범위 검사)이 **같은 줄**을 읽어야
+ * 저작 통과·실행 보류가 다시 갈리지 않는다(TC 13:50). 줄 인식은 실행 쪽
+ * src/self-implement/orchestrator.ts 의 DECLARED_NEW_FILES_LINE 와 같은 꼴을 쓴다.
+ */
+
+// SCOPE-NEW-FILES-LINE — 칸 문면은 새로 만들 파일을 «신설:» 줄로 따로 적는다(OP D칸 규칙).
+//    orchestrator.ts 의 DECLARED_NEW_FILES_LINE 와 같은 정규식이다(한쪽만 읽으면 저작과 실행이 갈린다).
+export const DECLARED_NEW_FILES_LINE = /^\s*(?:신설|new\s*files?)\s*[:：]\s*(.*)$/i;
+
+/** 목록 기호 «- »·굵게 «**» 는 장식이다 — 그것만 벗기고 같은 정규식으로 문는다. */
+function bareDeclarationLine(line: string): string {
+  return line.replace(/^(?:\s*-\s+)+/, '').replace(/\*\*/g, '');
+}
+
+/** 저장소 상대 파일 경로(확장자 있음)만 남긴다 — 디렉토리·절대 경로·「..」는 버린다. */
+function isRepositoryFileCandidate(piece: string): boolean {
+  if (piece === '' || /\s/.test(piece)) return false;
+  if (piece.startsWith('/') || piece.startsWith('~') || /^[A-Za-z]:[\\/]/.test(piece)) return false;
+  if (piece.endsWith('/')) return false;
+  const segments = piece.split('/');
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) return false;
+  return /\.[^./]+$/.test(segments[segments.length - 1]!);
+}
+
+/** 문서 안 «신설:» 줄의 « · »·쉼표로 나뉜 경로를 모은다. «## NEW FILES» 같은 다른 형식은 읽지 않는다. */
+export function declaredNewFilePaths(document: string): string[] {
+  const paths: string[] = [];
+  for (const rawLine of document.split(/\r?\n/)) {
+    const match = DECLARED_NEW_FILES_LINE.exec(bareDeclarationLine(rawLine));
+    if (!match) continue;
+    for (const fragment of match[1]!.split(/[·,]/)) {
+      // 실행 쪽 범위 검사(parseDeclaredTargetPathsFromAsk)와 같은 정규화 — 등 코드, ./ 접두.
+      const piece = fragment.trim().replace(/^`+|`+$/g, '').replace(/\\/g, '/').replace(/^\.\//, '');
+      if (!isRepositoryFileCandidate(piece)) continue;
+      paths.push(piece);
+    }
+  }
+  return [...new Set(paths)];
+}

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

@@ -1,3 +1,5 @@
+import type { RunStopClass } from './run-stop.js';
+
 /** ⭐ RFC §5 «4단계» — `applies_when` 을 «코드»가 판정한다.
  *
  *  ⛔⭐ **표현식 엔진을 만들지 않는다.** 문법이 넓어지면 오버레이가 «작은 프로그램»이 되고,
@@ -31,6 +33,32 @@ export function parseOverlayCondition(source: string): OverlayConditionParse {
   return { ok: true, condition: { key: key!, operator: operator as OverlayConditionOperator, literal } };
 }
 
+/** Inputs known at a runtime overlay decision. Every field except `attempts` may be unknown. */
+export interface RuntimeOverlayStateInput {
+  readonly attempts: number;
+  readonly goalId?: string;
+  readonly stopClass?: RunStopClass;
+  readonly reviewRepeat?: number;
+  /** Only a real boolean is a measurement. */
+  readonly siblingOverlap?: unknown;
+  readonly mainSyncConflict?: unknown;
+  /** Only a non-empty string is a measurement. */
+  readonly authorGrade?: unknown;
+}
+
+/** ⛔ 아는 값만 싣는다 — 모르면 키를 «뺀다». 0·false·빈 문자열을 지어내지 않는다. */
+export function buildRuntimeOverlayState(input: RuntimeOverlayStateInput): Record<string, unknown> {
+  return {
+    attempts: input.attempts,
+    ...(input.goalId === undefined ? {} : { goal_id: input.goalId }),
+    ...(input.stopClass === undefined ? {} : { stop_class: input.stopClass }),
+    ...(typeof input.reviewRepeat === 'number' && Number.isFinite(input.reviewRepeat) ? { review_repeat: input.reviewRepeat } : {}),
+    ...(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 } : {}),
+  };
+}
+
 export type OverlayConditionVerdict =
   /** 조건이 참이다 — 얹는다. */
   | { readonly kind: 'applies' }

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

@@ -1,7 +1,7 @@
 import { readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parse as parseYaml } from 'yaml';
+import { parse as parseYaml, parseAllDocuments } from 'yaml';
 import { inspectPipelineGraph, type PipelineGraphDefect } from './pipeline-shape.js';
 import { edgeMapOf, type GraphParseIssue, type GraphTemplateSpec } from './graph-yaml.js';
 import { evaluateOverlayCondition } from './graph-overlay-condition.js';
@@ -15,7 +15,8 @@ import type { OverlayPatch } from './graph-overlay.js';
  *    ⑴ 얹은 «결과»에 위상 검사를 다시 건다 — 노드 집합이 그대로여도 도달 가능성은 바뀐다
  *    ⑵ 계약이 빠진 노드를 «거부»한다 — 권한 없는 노드가 조용히 들어오는 것을 막는다
  *    ⑶ 무엇을 얹었는지를 «값»으로 낸다 — 사후에 「왜 이 걸음인가」를 답하려면 필요하다 */
-export type OverlayStage = 'launch' | 'runtime';
+/** `heal` = 멈춤 갈래 사다리 전용 — `stop-autoheal.ts` 만 고른다. 실행기의 launch·runtime 선택에는 «안» 잡힌다. */
+export type OverlayStage = 'launch' | 'runtime' | 'heal';
 
 export interface OverlayPatchOp {
   readonly op: 'add' | 'replace' | 'remove';
@@ -33,19 +34,52 @@ export interface GraphOverlaySpec {
 }
 
 export interface OverlayParseResult {
+  /** 첫 오버레이 — 한 파일에 하나만 둔 기존 선언의 읽기 자리. */
   readonly overlay?: GraphOverlaySpec;
+  /** 파일이 선언한 오버레이 전부. `---` 로 문서를 나누면 한 파일에 여럿이다. 오류가 하나라도 있으면 비어 있다. */
+  readonly overlays: readonly GraphOverlaySpec[];
   readonly errors: readonly GraphParseIssue[];
 }
 
-const STAGES = new Set<OverlayStage>(['launch', 'runtime']);
+const STAGES = new Set<OverlayStage>(['launch', 'runtime', 'heal']);
 const OPS = new Set(['add', 'replace', 'remove']);
 
-/** ⛔ 던지지 않는다 — 파서 계약은 `graph-yaml.ts` 와 같다. */
+/** ⛔ 던지지 않는다 — 파서 계약은 `graph-yaml.ts` 와 같다.
+ *  한 파일 = 문서 하나가 기본이다. `---` 로 나눈 여러 문서는 문서마다 오버레이 하나로 읽는다
+ *  (오류 경로는 `<label>#<문서 번호>`). 문서가 하나면 읽는 법도 오류 문면도 예전과 같다. */
 export function parseGraphOverlayYaml(source: string, label = '<inline>'): OverlayParseResult {
-  const errors: GraphParseIssue[] = [];
   let raw: unknown;
   try { raw = parseYaml(source); }
-  catch (error) { return { errors: [{ path: label, message: `YAML 파싱 실패: ${error instanceof Error ? error.message : String(error)}` }] }; }
+  catch (error) {
+    const documents = parseAllDocuments(source);
+    if (documents.length > 1 && documents.every((document) => document.errors.length === 0)) {
+      return overlaysFromDocuments(documents.map((document) => document.toJS() as unknown), label);
+    }
+    return { overlays: [], errors: [{ path: label, message: `YAML 파싱 실패: ${error instanceof Error ? error.message : String(error)}` }] };
+  }
+  const parsed = overlayFromRaw(raw, label);
+  return { ...(parsed.overlay ? { overlay: parsed.overlay } : {}), overlays: parsed.overlay ? [parsed.overlay] : [], errors: parsed.errors };
+}
+
+function overlaysFromDocuments(raws: readonly unknown[], label: string): OverlayParseResult {
+  const errors: GraphParseIssue[] = [];
+  const overlays: GraphOverlaySpec[] = [];
+  for (const [index, raw] of raws.entries()) {
+    const parsed = overlayFromRaw(raw, `${label}#${index}`);
+    errors.push(...parsed.errors);
+    if (parsed.overlay) overlays.push(parsed.overlay);
+  }
+  const seen = new Set<string>();
+  for (const overlay of overlays) {
+    if (seen.has(overlay.overlayId)) errors.push({ path: `${label}/overlay_id`, message: `overlay_id '${overlay.overlayId}' 가 한 파일에서 중복이다` });
+    seen.add(overlay.overlayId);
+  }
+  if (errors.length > 0) return { overlays: [], errors };
+  return { overlay: overlays[0]!, overlays, errors };
+}
+
+function overlayFromRaw(raw: unknown, label: string): { overlay?: GraphOverlaySpec; errors: GraphParseIssue[] } {
+  const errors: GraphParseIssue[] = [];
   if (raw === null || typeof raw !== 'object') return { errors: [{ path: label, message: 'YAML 최상위가 맵이 아니다' }] };
   const doc = raw as Record<string, unknown>;
 
@@ -198,7 +232,7 @@ export function loadGraphOverlays(dir: string): OverlayLoadResult {
     catch (error) { errors.push({ path: file, message: `읽기 실패: ${error instanceof Error ? error.message : String(error)}` }); continue; }
     const result = parseGraphOverlayYaml(source, file);
     errors.push(...result.errors);
-    if (result.overlay) overlays.push(result.overlay);
+    overlays.push(...result.overlays);
   }
   return { overlays, errors, scannedFiles: files.length };
 }

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

@@ -23,6 +23,7 @@ export interface GraphTemplateNode {
   readonly kind: GraphNodeSpec['kind'];
   /** 그 노드의 재방문 상한. ⛔ 지금의 rework 상한이 «여기로 올라올» 자리다(RFC §4.1). */
   readonly maxVisits: number;
+  readonly journeyStage?: string;
   /** YAML recipe identifier; existing orchestrator does not execute it. */
   readonly recipe?: string;
   /** YAML이 선언한 선택 계약. 관측용이며 실행 권한을 강제하지 않는다. */
@@ -34,6 +35,7 @@ export interface GraphTemplate {
   readonly version: string;
   readonly entryNode: string;
   readonly terminalNodes: readonly string[];
+  readonly journeyStages?: readonly string[];
   /** YAML 템플릿이 선언한 문서 전용 변경의 gate 건너뛰기 정책. */
   readonly docsOnlyGateSkip?: boolean;
   /** 선언된 런 계약(선택) — 런 시작 때 발사 인자·부모 계약과 함께 한 번 해석된다. */
@@ -104,7 +106,7 @@ export function defaultGraphsDir(): string {
   return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'graphs');
 }
 
-export type DiscardedGraphNodeField = Exclude<keyof GraphNodeSpec, 'nodeId' | 'kind' | 'maxVisits' | 'recipe' | 'contract'>;
+export type DiscardedGraphNodeField = Exclude<keyof GraphNodeSpec, 'nodeId' | 'kind' | 'maxVisits' | 'journeyStage' | 'recipe' | 'contract'>;
 
 export interface GraphTemplateCompilation {
   readonly template: GraphTemplate;
@@ -129,12 +131,14 @@ export function compileGraphTemplate(spec: GraphTemplateSpec): GraphTemplateComp
       version: String(spec.version),
       entryNode: spec.entryNode,
       terminalNodes: spec.terminalNodes,
+      ...(spec.journeyStages === undefined ? {} : { journeyStages: spec.journeyStages }),
       ...(spec.docsOnlyGateSkip !== undefined ? { docsOnlyGateSkip: spec.docsOnlyGateSkip } : {}),
       ...(spec.runContract !== undefined ? { runContract: spec.runContract } : {}),
       nodes: spec.nodes.map((n) => ({
         nodeId: n.nodeId,
         kind: n.kind,
         maxVisits: n.maxVisits,
+        ...(n.journeyStage === undefined ? {} : { journeyStage: n.journeyStage }),
         ...(n.recipe === undefined ? {} : { recipe: n.recipe }),
         ...(n.contract === undefined ? {} : { contract: n.contract }),
       })),
@@ -324,6 +328,34 @@ export function inspectAllTemplates(): Array<{ graphId: string; defects: Pipelin
     .map((t) => ({ graphId: t.graphId, defects: inspectPipelineGraph(t.edges, t.entryNode) }));
 }
 
+/** L0 ratios are distinct: stages represented by nodes, and nodes accounted for by this run. */
+export function measureL0Coverage(
+  template: GraphTemplate,
+  enteredNodes: Iterable<string>,
+  skippedNodes: Iterable<string>,
+): {
+  declarationCoverage: number | null;
+  traversalCoverage: number | null;
+  declaredStageCount: number;
+  listedStageCount: number;
+  accountedNodeCount: number;
+  declaredNodeCount: number;
+} {
+  const stages = template.journeyStages ?? [];
+  const declaredStages = new Set(template.nodes.map((node) => node.journeyStage).filter((stage): stage is string => stage !== undefined && stages.includes(stage)));
+  const accounted = new Set([...enteredNodes, ...skippedNodes]);
+  const declaredNodeCount = template.nodes.length;
+  const accountedNodeCount = template.nodes.filter((node) => accounted.has(node.nodeId)).length;
+  return {
+    declarationCoverage: stages.length ? declaredStages.size / stages.length : null,
+    traversalCoverage: declaredNodeCount ? accountedNodeCount / declaredNodeCount : null,
+    declaredStageCount: declaredStages.size,
+    listedStageCount: stages.length,
+    accountedNodeCount,
+    declaredNodeCount,
+  };
+}
+
 /** ⭐ 원장에 실을 «그래프 신원» — ⛔ 옛 TS 상수가 아니라 «지금 도는 템플릿»을 따른다.
  *
  *  🩸 계기(2026-09-08): 승격을 켠 research 런이 `investigate` 를 밟았는데 원장의

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

@@ -24,12 +24,16 @@ export interface GraphNodeSpec {
   readonly kind: GraphNodeKind | (string & {});
   readonly recipe: string;
   readonly maxVisits: number;
+  /** L0 journey-stage declaration (optional for other graph templates). */
+  readonly journeyStage?: string;
   readonly progress?: readonly string[];
   readonly phases?: readonly string[];
   readonly terminalStages?: readonly string[];
   /** ⭐ 「아크마다 한 번」처럼 «한 노드가 여럿 돈다」를 값으로. 없으면 한 번이다. */
   readonly fanOut?: string;
   readonly contract?: GraphNodeContract;
+  readonly call?: string;
+  readonly budget?: { readonly innerSteps: number };
 }
 
 export interface GraphEdgeSpec {
@@ -50,11 +54,13 @@ export interface GraphTemplateSpec {
   readonly version: number;
   readonly entryNode: string;
   readonly terminalNodes: readonly string[];
+  readonly journeyStages?: readonly string[];
   /** 문서 전용 변경이면 gate 노드를 건너뛸 수 있다는 템플릿 정책. */
   readonly docsOnlyGateSkip?: boolean;
   readonly state?: readonly string[];
   /** ⭐ 런 계약(선택) — 이 그래프가 «기본으로» 요구하는 실행 칸 등. 발사 인자가 덮는다(graph-run-contract.ts). */
   readonly runContract?: GraphRunContractSpec;
+  readonly unit?: { readonly inputs: readonly string[]; readonly outputs: readonly string[]; readonly exits: readonly string[] };
   readonly nodes: readonly GraphNodeSpec[];
   readonly edges: readonly GraphEdgeSpec[];
 }
@@ -102,6 +108,12 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
   const terminalNodes = asArray(doc.terminal_nodes).filter((v): v is string => typeof v === 'string');
   if (terminalNodes.length === 0) errors.push({ path: `${label}/terminal_nodes`, message: 'terminal_nodes 가 비었다 — 끝날 수 없는 그래프다' });
 
+  const journeyStages = doc.journey_stages;
+  if (journeyStages !== undefined && (!Array.isArray(journeyStages) || journeyStages.length === 0
+    || !journeyStages.every((stage) => typeof stage === 'string' && stage.trim())
+    || new Set(journeyStages).size !== journeyStages.length)) {
+    errors.push({ path: `${label}/journey_stages`, message: 'journey_stages 는 중복 없는 비어 있지 않은 문자열 목록이어야 한다' });
+  }
   const nodes: GraphNodeSpec[] = [];
   for (const [index, entry] of asArray(doc.nodes).entries()) {
     const at = `${label}/nodes/${index}`;
@@ -126,6 +138,13 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
       errors.push({ path: `${at}/max_visits`, message: 'max_visits 는 1 이상의 정수여야 한다' });
       continue;
     }
+    if (n.journey_stage !== undefined && (typeof n.journey_stage !== 'string' || !n.journey_stage.trim()
+      || (Array.isArray(journeyStages) && !journeyStages.includes(n.journey_stage)))) {
+      errors.push({ path: `${at}/journey_stage`, message: typeof n.journey_stage === 'string' && n.journey_stage.trim()
+        ? `journey_stage '${n.journey_stage}' 가 journey_stages 목록에 없다`
+        : 'journey_stage 는 비어 있지 않은 문자열이어야 한다' });
+      continue;
+    }
     const contractRaw = n.contract as Record<string, unknown> | undefined;
     const contract: GraphNodeContract | undefined = contractRaw && typeof contractRaw === 'object'
       ? {
@@ -134,17 +153,38 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
           outputs: asArray(contractRaw.outputs).filter((v): v is string => typeof v === 'string'),
         }
       : undefined;
+    // A subgraph node becomes a unit call only when it names `call:`; without it the node keeps the
+    // pre-unit meaning (catalog role / recipe node), so existing declarations stay valid.
+    if (kind === 'subgraph' && (n.call !== undefined || n.budget !== undefined)) {
+      if (typeof n.call !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*@(?:\^?[1-9]\d*)$/.test(n.call))
+        errors.push({ path: `${at}/call`, message: 'call 은 id@정수판 또는 id@^주판이어야 한다' });
+      const budget = n.budget as Record<string, unknown> | undefined;
+      if (!budget || typeof budget !== 'object' || Array.isArray(budget) ||
+          !Number.isSafeInteger(budget.inner_steps) || (budget.inner_steps as number) < 1 || Object.keys(budget).some(key => key !== 'inner_steps'))
+        errors.push({ path: `${at}/budget/inner_steps`, message: 'inner_steps 는 1 이상의 안전한 정수여야 한다' });
+      if (!contractRaw || !Array.isArray(contractRaw.inputs) || !contractRaw.inputs.every(v => typeof v === 'string') ||
+          !Array.isArray(contractRaw.outputs) || !contractRaw.outputs.every(v => typeof v === 'string'))
+        errors.push({ path: `${at}/contract`, message: 'subgraph 에는 inputs·outputs 계약이 필요하다' });
+      if (recipe !== 'none') errors.push({ path: `${at}/recipe`, message: 'subgraph 는 recipe 를 실행하지 않는다' });
+    } else if (kind !== 'subgraph' && (n.call !== undefined || n.budget !== undefined)) {
+      errors.push({ path: at, message: 'call·budget 은 subgraph 전용이다' });
+    }
     // ⛔ 계약이 없으면 「이 노드가 무엇을 할 수 있나」를 답할 수 없다 — 경고로 남긴다(거절은 오버레이 쪽).
     if (contract === undefined) warnings.push({ path: `${at}/contract`, message: '계약(inputs·tools·outputs)이 없다 — 권한을 코드에서만 알 수 있다' });
     else if (contract.tools === '') warnings.push({ path: `${at}/contract/tools`, message: 'tools 가 비었다' });
 
     nodes.push({
       nodeId, kind, recipe, maxVisits,
+      ...(typeof n.journey_stage === 'string' ? { journeyStage: n.journey_stage } : {}),
       ...(Array.isArray(n.progress) ? { progress: n.progress.filter((v): v is string => typeof v === 'string') } : {}),
       ...(Array.isArray(n.phases) ? { phases: n.phases.filter((v): v is string => typeof v === 'string') } : {}),
       ...(Array.isArray(n.terminal_stages) ? { terminalStages: n.terminal_stages.filter((v): v is string => typeof v === 'string') } : {}),
       ...(typeof n.fan_out === 'string' ? { fanOut: n.fan_out } : {}),
       ...(contract ? { contract } : {}),
+      ...(kind === 'subgraph' && typeof n.call === 'string' ? { call: n.call } : {}),
+      ...(kind === 'subgraph' && n.budget && typeof n.budget === 'object' && !Array.isArray(n.budget) &&
+        typeof (n.budget as Record<string, unknown>).inner_steps === 'number'
+        ? { budget: { innerSteps: (n.budget as { inner_steps: number }).inner_steps } } : {}),
     });
   }
   if (nodes.length === 0) errors.push({ path: `${label}/nodes`, message: '노드가 하나도 없다' });
@@ -198,6 +238,20 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
   if (entryNode !== undefined && !known.has(entryNode)) errors.push({ path: `${label}/entry_node`, message: `'${entryNode}' 는 선언된 노드가 아니다` });
   for (const t of terminalNodes) if (!known.has(t)) errors.push({ path: `${label}/terminal_nodes`, message: `'${t}' 는 선언된 노드가 아니다` });
 
+  let unit: GraphTemplateSpec['unit'];
+  if (doc.unit !== undefined) {
+    const rawUnit = doc.unit as Record<string, unknown>;
+    if (!rawUnit || typeof rawUnit !== 'object' || Array.isArray(rawUnit) ||
+        Object.keys(rawUnit).some(key => !['inputs', 'outputs', 'exits'].includes(key)) ||
+        !['inputs', 'outputs', 'exits'].every(key => Array.isArray(rawUnit[key]) &&
+          (rawUnit[key] as unknown[]).every(v => typeof v === 'string' && v.length > 0) &&
+          new Set(rawUnit[key] as string[]).size === (rawUnit[key] as string[]).length) ||
+        !(rawUnit.exits as string[]).length ||
+        (rawUnit.exits as string[]).some(exit => !terminalNodes.includes(exit)) ||
+        terminalNodes.some(exit => !(rawUnit.exits as string[]).includes(exit))) {
+      errors.push({ path: `${label}/unit`, message: 'unit 의 inputs·outputs·exits 및 terminal_nodes 가 일치해야 한다' });
+    } else unit = { inputs: rawUnit.inputs as string[], outputs: rawUnit.outputs as string[], exits: rawUnit.exits as string[] };
+  }
   const runContract = parseGraphRunContract(doc.run_contract);
   if (runContract.error) errors.push({ path: `${label}/run_contract`, message: runContract.error });
   let loop: GraphTemplateSpec['loop'];
@@ -225,6 +279,8 @@ export function parseGraphTemplateYaml(source: string, label = '<inline>'): Grap
   return {
     template: {
       graphId: graphId!, version: version!, entryNode: entryNode!, terminalNodes, nodes, edges,
+      ...(unit ? { unit } : {}),
+      ...(Array.isArray(journeyStages) ? { journeyStages: journeyStages as string[] } : {}),
       ...(loop ? { loop } : {}),
       ...(typeof doc.docs_only_gate_skip === 'boolean' ? { docsOnlyGateSkip: doc.docs_only_gate_skip } : {}),
       ...(Array.isArray(doc.state) ? { state: doc.state.filter((v): v is string => typeof v === 'string') } : {}),

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

@@ -170,7 +170,11 @@ function withInboxLock<T>(file: string, work: () => T): T {
   finally { rmdirSync(lock); }
 }
 
-/** One durable JSON line per failure; repeat source+ref within an hour is folded. */
+/** One durable JSON line per failure; repeat source+ref within an hour is folded.
+ *  POD-HEAL-HOST — the loop start itself is refused inside a Pod (`startHealLoop` → `skipped-in-pod`):
+ *  a loop started there dies with the Pod. The line stays in the inbox, and the host re-records the
+ *  recovered Pod ledger failure into the HOST universe (`pod-ledger-collect.ts` → `intakeCollectedFailure`),
+ *  so the host heal loop triages it (harvest + narrowed relaunch). */
 export function recordFailureEvent(event: FailureEvent, root = effectiveInstanceRoot(), startLoop: StartHealLoop = startHealLoop): { folded: boolean } {
   if (!['release-run', 'harness-run', 'loop-tick', 'cron'].includes(event.source) ||
       !event.kind || !event.ref || !event.summary || !Number.isFinite(Date.parse(event.at))) {