@lmzhen/dsh-evolution-merge 0.32.2 → 0.32.4

package/lib/index.js

@@ -1,7 +1,7 @@
 import { dirname, join } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { pairKeyOf, screen, selectCandidates } from "@lmzhen/dsh-evolution-merge-engine";
-import { DEFAULT_SKILL_LIMITS, SkillLibrary, UnitTransactions, authorityFrom, contentHash, createSubagentChannel, errorText, evolutionHome, evolutionIoAdapter, executeUnitUndo, isPresent, isProcessAlive, newRunRegistry, newSkillLibrary, parseFrontmatter, planUnitUndoAcross, policyStageLimits, probeAbsent, probeList, probePresent, probeText, probeUnknown, readTreeLock, readUnitEvidence, reportsSweepLockTarget, revisionAnchorOf, revisionFingerprint, revisionSupportDigest, runsFile, scanContentThreats, skillLibraryUnitBackend, supportRefs, sweepReports, transactIo, validateFrontmatter, validateSupportPath } from "@lmzhen/dsh-evolution-core";
+import { DEFAULT_SKILL_LIMITS, SkillLibrary, UnitTransactions, authorityFrom, contentHash, createSubagentChannel, errorText, evolutionHome, evolutionIoAdapter, executeUnitUndo, isPresent, isProcessAlive, newRunRegistry, newSkillLibrary, parseFrontmatter, planUnitUndoAcross, policyStageLimits, probeAbsent, probeList, probePresent, probeText, probeUnknown, readTreeLock, readUnitEvidence, readUnitJournal, reportsSweepLockTarget, revisionAnchorOf, revisionFingerprint, revisionSupportDigest, runsFile, scanContentThreats, skillLibraryUnitBackend, supportRefs, sweepReports, transactIo, validateFrontmatter, validateSupportPath } from "@lmzhen/dsh-evolution-core";
 import { HOST_ROUTES, json, methodNotAllowed, registerHostRoutes } from "@lmzhen/dsh-evolution-core/http-routes";
 import { createHash, randomUUID } from "node:crypto";
 import { chmod, mkdir, open, readFile, stat, unlink } from "node:fs/promises";
@@ -70,11 +70,12 @@ function createEngineScreening(deps) {
 	return async (cards, runId, signal) => {
 		const corpusDir = await snapshotCards(deps.io, deps.home, runId, cards);
 		const outDir = join(deps.home, "merge", "runs", runId, "engine");
+		const runner = deps.runner === void 0 ? void 0 : (prompt, cfg) => deps.runner(prompt, cfg, signal);
 		const result = await deps.engine.screen({
 			corpusDir,
 			outDir,
 			...deps.cfg === void 0 ? {} : { cfg: deps.cfg },
-			...deps.runner === void 0 ? {} : { runner: deps.runner },
+			...runner === void 0 ? {} : { runner },
 			signal
 		});
 		if (!result.ok) throw new Error("engine screen failed: " + result.error.code + (result.error.stage === void 0 ? "" : " @" + result.error.stage) + (result.error.detail === void 0 ? "" : ": " + result.error.detail));
@@ -110,8 +111,11 @@ function append(chunk, text) {
 	return text;
 }
 function createEngineRunner(llm, route) {
-	return async (prompt) => {
+	return async (prompt, cfg, runSignal) => {
 		const selection = route();
+		const timeout = Number(cfg?.timeoutMs);
+		const timeoutSignal = Number.isFinite(timeout) && timeout > 0 ? AbortSignal.timeout(timeout) : void 0;
+		const signal = runSignal === void 0 ? timeoutSignal : timeoutSignal === void 0 ? runSignal : typeof AbortSignal.any === "function" ? AbortSignal.any([runSignal, timeoutSignal]) : runSignal;
 		let text = "";
 		if (llm.stream !== void 0) {
 			for await (const chunk of llm.stream({
@@ -124,7 +128,8 @@ function createEngineRunner(llm, route) {
 						text: prompt
 					}]
 				}],
-				temperature: 0
+				temperature: 0,
+				...signal === void 0 ? {} : { signal }
 			})) text = append(chunk, text);
 			return text;
 		}
@@ -133,7 +138,7 @@ function createEngineRunner(llm, route) {
 			provider: normalizeProviderKey(selection.provider),
 			model: selection.model,
 			temperature: 0
-		});
+		}, signal);
 		for await (const chunk of call.stream({
 			...call.config,
 			messages: [{
@@ -142,7 +147,8 @@ function createEngineRunner(llm, route) {
 					type: "text",
 					text: prompt
 				}]
-			}]
+			}],
+			...signal === void 0 ? {} : { signal }
 		})) text = append(chunk, text);
 		return text;
 	};
@@ -633,6 +639,11 @@ function transitionV4(row, event, expectedVersion, at = (/* @__PURE__ */ new Dat
 			};
 			return illegal("pending/" + event.type);
 		case "approved":
+			if (event.type === "run-attached") return {
+				ok: true,
+				row: advance(row, at, { runId: event.runId }),
+				version: expectedVersion + 1
+			};
 			if (event.type === "staged") return {
 				ok: true,
 				row: advance(row, at, {
@@ -672,6 +683,11 @@ function transitionV4(row, event, expectedVersion, at = (/* @__PURE__ */ new Dat
 			};
 			return illegal("approved/" + event.type);
 		case "fuse":
+			if (event.type === "run-attached") return {
+				ok: true,
+				row: advance(row, at, { runId: event.runId }),
+				version: expectedVersion + 1
+			};
 			if (event.type === "committed") return {
 				ok: true,
 				row: null,
@@ -2334,7 +2350,7 @@ async function cleanupStage(io, home, now, rows, limit = 100) {
 	const refs = /* @__PURE__ */ new Set();
 	const indexRoot = join(home, "merge", "staging-index");
 	const names = await io.exists(indexRoot) ? await listOrEmpty(io, indexRoot) : [];
-	for (const name of names.slice(0, limit)) {
+	for (const name of names) {
 		if (!name.endsWith(".json")) continue;
 		const raw = await readTextOrNull(io, join(indexRoot, name));
 		if (raw === null) continue;
@@ -3769,7 +3785,7 @@ function parseCursor(cursor, snapshot) {
 	}
 }
 function buildQueuePage(snapshot, queue, expiredOnly, cursor, limit = 50) {
-	const selected = snapshot.rows.filter((row) => row.queue === queue && (queue === "skipped" ? true : expiredOnly ? row.expired : !row.expired));
+	const selected = snapshot.rows.filter((row) => row.queue === queue && (expiredOnly ? row.expired : !row.expired));
 	const offset = cursor === void 0 ? 0 : parseCursor(cursor, snapshot);
 	const page = selected.slice(offset, offset + Math.max(0, Math.min(200, limit)));
 	const next = offset + page.length < selected.length ? encodeCursor(snapshot, offset + page.length) : void 0;
@@ -4168,9 +4184,6 @@ async function mergeDoctor(io, home, configuredRoot) {
 			for (const report of JSON.parse(raw)) if (report.ok === true && report.runId !== void 0) recoveryRuns.add(report.runId);
 		}
 	} catch {}
-	const receiptRuns = /* @__PURE__ */ new Set();
-	const receiptDir = await probeList(io, join(home, "merge", "receipts"));
-	if (receiptDir.kind === "present") for (const name of receiptDir.value) receiptRuns.add(name);
 	const invalid = [];
 	if (snapshot.blocked !== void 0) invalid.push({
 		id: "state",
@@ -4182,13 +4195,14 @@ async function mergeDoctor(io, home, configuredRoot) {
 		const artifactRow = row.state === "approved" ? "approved" : row.state === "fuse" ? "fuse" : row.state;
 		const run = runId === void 0 ? "none" : row.state === "pending" ? "awaiting-approval" : "running";
 		const staging = item.stage === null ? row.state === "fuse" ? "missing" : "none" : item.stage.state === "present" || item.stage.state === "reserved" ? "kept" : row.state === "fuse" ? "missing" : "none";
-		const phase = runId === void 0 ? null : await readJournal(io, home, runId);
+		const receipt = runId === void 0 ? null : await readCommitReceipt(io, home, runId);
+		const phase = receipt !== null ? await readUnitJournal(io, home, receipt.unitId) : runId === void 0 ? null : await readJournal(io, home, runId);
 		const result = validateArtifacts({
 			row: artifactRow,
 			run,
 			staging,
-			journal: phase === null ? "none" : phase.phase === "prepared" ? "prepared" : phase.phase === "target-written" || phase.phase === "sources-archived" ? "committing" : phase.phase === "committed" ? "committed" : phase.phase === "rolled-back" ? "rolled-back" : "failed",
-			evidence: runId !== void 0 && await readTextOrNull(io, join(home, "merge", "receipts", runId + ".json")) !== null ? "receipt" : "none",
+			journal: phase === null ? "none" : phase.phase === "prepared" || phase.phase === "target-pending" ? "prepared" : phase.phase === "target-written" || phase.phase === "sources-archived" || phase.phase === "support-pending" || phase.phase === "source-archiving" ? "committing" : phase.phase === "committed" ? "committed" : phase.phase === "rolled-back" ? "rolled-back" : "failed",
+			evidence: receipt === null ? "none" : "receipt",
 			activeRuns: run === "running" || run === "awaiting-approval" ? 1 : 0,
 			...runId !== void 0 && recoveryRuns.has(runId) ? { recovery: true } : {}
 		});
@@ -4628,6 +4642,18 @@ async function recoverCommitUnits(options) {
 			journal = null;
 		}
 		if (journal === null || typeof journal.unitId !== "string") continue;
+		if (journal.kind === "tree-change" || journal.kind === void 0 && journal.runId === journal.unitId) {
+			reports.push({
+				unitId: journal.unitId,
+				runId: journal.runId,
+				phase: journal.phase,
+				branch: branchOf(journal.phase),
+				action: "none",
+				ok: true,
+				code: "skill-unit-skipped"
+			});
+			continue;
+		}
 		if (options.isActive?.(journal.runId) === true) {
 			reports.push({
 				unitId: journal.unitId,
@@ -6213,6 +6239,24 @@ async function withMergeRun(options) {
 		createdAt: new Date(startedAt).toISOString(),
 		updatedAt: new Date(options.now()).toISOString()
 	});
+	const writeFailureMeta = async (stopReason) => {
+		try {
+			await writeRunMeta(options.io, options.home, {
+				version: 1,
+				runId: handle.id,
+				pid: process.pid,
+				...options.parentRunId === void 0 ? {} : { parentRunId: options.parentRunId },
+				...options.pairKey === void 0 ? {} : { pairKey: options.pairKey },
+				...options.stagingRef === void 0 ? {} : { stagingRef: options.stagingRef },
+				pairCount: options.pairCount ?? (options.pairKey === void 0 ? 0 : 1),
+				phase: "settled",
+				approval: "approved",
+				stopReason,
+				createdAt: new Date(startedAt).toISOString(),
+				updatedAt: new Date(options.now()).toISOString()
+			});
+		} catch {}
+	};
 	const finish = async () => {
 		let draft;
 		const runController = new AbortController();
@@ -6304,6 +6348,7 @@ async function withMergeRun(options) {
 				state: "failed",
 				failure: "report write failed: " + (error instanceof Error ? error.message : String(error))
 			});
+			await writeFailureMeta("failed");
 			return {
 				ok: false,
 				runId: handle.id,
@@ -6318,6 +6363,7 @@ async function withMergeRun(options) {
 				resultRef: reportPath,
 				failure: "post-report finalize failed: " + (error instanceof Error ? error.message : String(error))
 			});
+			await writeFailureMeta("failed");
 			return {
 				ok: false,
 				runId: handle.id,
@@ -6467,6 +6513,19 @@ async function rejectPending(io, home, now, id) {
 	return await act(io, home, now, id, "reject");
 }
 //#endregion
+//#region lib/types/domain/row-run.js
+/** Attach the in-flight child run to a row before its round2 starts (P1-8). */
+async function attachRunToRow(io, home, rowId, runId) {
+	if (!await pairLedger(io, home).transact((tx) => {
+		const current = tx.rows().find((row) => row.id === rowId);
+		if (current === void 0) return false;
+		return tx.transition(rowId, {
+			type: "run-attached",
+			runId
+		}, current.version).ok;
+	})) throw new Error("row is not attachable to run: " + rowId);
+}
+//#endregion
 //#region lib/types/domain/failure-route.js
 function casExpiredHook(code) {
 	if (code === "target-changed" || code === "target-taken") return {
@@ -6749,6 +6808,7 @@ async function runApproveCommand(options) {
 		now: options.now,
 		...options.detached === true ? { detached: true } : {},
 		async body(ctx) {
+			await attachRunToRow(options.io, options.home, row.id, ctx.runId);
 			const stage = (name) => ctx.stage(name, {
 				done: 0,
 				total: 1
@@ -6882,6 +6942,7 @@ async function runResumeCommand(options) {
 		now: options.now,
 		...options.detached === true ? { detached: true } : {},
 		async body(ctx) {
+			await attachRunToRow(options.io, options.home, row.id, ctx.runId);
 			await ctx.stage("author", {
 				done: 0,
 				total: 1
@@ -7927,12 +7988,6 @@ async function assembleStagedCommit(io, home, runId, port, options) {
 	});
 }
 //#endregion
-//#region lib/types/commit-snapshot.js
-/** Pre-commit snapshot: enough to restore the target and archived sources after a crash. */
-function snapshotPath(home, runId) {
-	return join(home, "merge", "snapshots", runId.replace(/[^A-Za-z0-9_-]+/g, "_") + ".json");
-}
-//#endregion
 //#region lib/types/commit-execute.js
 async function commitStagedRun(io, home, runId, port, options) {
 	const assembled = await assembleStagedCommit(io, home, runId, port, {
@@ -7973,7 +8028,7 @@ async function commitStagedRun(io, home, runId, port, options) {
 	{
 		const first = assembled.plan.sources[0] ?? assembled.plan.target;
 		const unitPlan = {
-			runId,
+			runId: options.parentRunId ?? runId,
 			pairKey: pairKey(assembled.plan.target, first),
 			target: assembled.plan.target,
 			targetExists: assembled.plan.targetExists,
@@ -8079,9 +8134,6 @@ async function commitStagedRun(io, home, runId, port, options) {
 	};
 	try {
 		await writeCommitReceipt(io, home, receipt);
-		try {
-			await io.remove(snapshotPath(home, runId));
-		} catch {}
 		return {
 			ok: true,
 			plan: assembled.plan,
@@ -8218,7 +8270,9 @@ function buildValidationPlan(input) {
 	const manifest = new Set(manifestFiles);
 	const forwardRefs = [...refs].filter((ref) => !staged.has(ref)).sort();
 	const reverseRefs = files.map((file) => file.path).filter((path) => path !== "SKILL.md" && !refs.has(path) && manifest.has(path)).sort();
-	const orphanFiles = [...new Set(input.existingSupport ?? [])].filter((path) => !staged.has(path)).sort();
+	const existing = new Set(input.existingSupport ?? []);
+	const orphanFiles = [...existing].filter((path) => !staged.has(path)).sort();
+	const undeclaredFiles = [...staged].filter((path) => path !== "SKILL.md" && !manifest.has(path) && !existing.has(path)).sort();
 	const byPath = /* @__PURE__ */ new Map();
 	const supportSources = input.supportSources ?? [];
 	for (const file of supportSources) {
@@ -8249,7 +8303,8 @@ function buildValidationPlan(input) {
 		q09: {
 			forwardRefs,
 			reverseRefs,
-			orphanFiles
+			orphanFiles,
+			undeclaredFiles
 		},
 		supportConflicts,
 		threat,
@@ -8276,6 +8331,12 @@ function buildValidationPlan(input) {
 		severity: "block",
 		message: "target tree support is not declared by plan"
 	});
+	if (undeclaredFiles.length > 0) findings.push({
+		rule: "q09-undeclared",
+		path: undeclaredFiles.join(","),
+		severity: "block",
+		message: "staged support file is not declared by the authoring manifest"
+	});
 	if (supportConflicts.length > 0) findings.push({
 		rule: "support-conflict",
 		path: supportConflicts.map((item) => item.path).join(","),
@@ -8317,7 +8378,8 @@ function buildValidationPlan(input) {
 		q09: {
 			forwardRefs,
 			reverseRefs,
-			orphanFiles
+			orphanFiles,
+			undeclaredFiles
 		},
 		supportConflicts,
 		threat,
@@ -8332,28 +8394,80 @@ function buildValidationPlan(input) {
 }
 //#endregion
 //#region lib/types/domain/authoring-manifest.js
+function asManifest(value) {
+	if (value === null || typeof value !== "object") return null;
+	const record = value;
+	if (!Array.isArray(record.files) || record.files.some((file) => typeof file !== "string")) return null;
+	if (record.target !== void 0 && typeof record.target !== "string") return null;
+	return {
+		...typeof record.target === "string" ? { target: record.target } : {},
+		files: record.files
+	};
+}
+/** Every balanced object literal in a prose/fenced answer (string-aware). */
+function balancedObjects(text) {
+	const found = [];
+	let depth = 0;
+	let start = -1;
+	let quoted = false;
+	let escaped = false;
+	for (let index = 0; index < text.length; index += 1) {
+		const char = text[index];
+		if (quoted) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") quoted = false;
+			continue;
+		}
+		if (char === "\"") {
+			quoted = true;
+			continue;
+		}
+		if (char === "{") {
+			if (depth === 0) start = index;
+			depth += 1;
+			continue;
+		}
+		if (char !== "}" || depth === 0) continue;
+		depth -= 1;
+		if (depth === 0 && start >= 0) {
+			found.push(text.slice(start, index + 1));
+			start = -1;
+		}
+	}
+	return found;
+}
 /**
-* Parse `{"target":..., "files":[...]}` from a child's final turn text.
-* @param text - the child's answer (JSON is expected; prose is tolerated).
-* @returns the manifest, or null when the turn carried no well-formed envelope.
+* Parse the authoring manifest from a child's final turn.
+*
+* P2-20: a child that wraps the envelope in a fenced code block or in one prose
+* sentence is the normal shape, not a malformed answer. A strict whole-text
+* JSON.parse returned null there, and null used to mean "every staged file was
+* declared" - the exact files the check exists to catch. Try the whole answer,
+* then every fenced body, then every balanced object literal.
+* @param text - the child's answer.
+* @returns the first valid envelope, or null when the turn really declared none.
 */
 function parseAuthoringManifest(text) {
+	if (typeof text !== "string") return null;
 	try {
-		const value = JSON.parse(text);
-		if (!Array.isArray(value.files) || value.files.some((file) => typeof file !== "string")) return null;
-		if (value.target !== void 0 && typeof value.target !== "string") return null;
-		return {
-			...typeof value.target === "string" ? { target: value.target } : {},
-			files: value.files
-		};
-	} catch {
-		return null;
-	}
+		const direct = asManifest(JSON.parse(text));
+		if (direct !== null) return direct;
+	} catch {}
+	for (const match of text.matchAll(/\x60\x60\x60(?:json)?\s*([\s\S]*?)\x60\x60\x60/g)) try {
+		const parsed = asManifest(JSON.parse(match[1] ?? ""));
+		if (parsed !== null) return parsed;
+	} catch {}
+	for (const candidate of balancedObjects(text)) try {
+		const parsed = asManifest(JSON.parse(candidate));
+		if (parsed !== null) return parsed;
+	} catch {}
+	return null;
 }
-/** Files a manifest promises for a staged tree (declared list, or the tree when undeclared). */
+/** Files a manifest promises for a staged tree. */
 function manifestFilesOf(manifest, stagedPaths) {
 	if (manifest !== null) return manifest.files;
-	return ["SKILL.md", ...stagedPaths];
+	return ["SKILL.md"];
 }
 /**
 * The first file the manifest promises but the staged tree does not contain.
@@ -8492,6 +8606,7 @@ async function runAuthoring(options) {
 		lengths
 	};
 	const commit = await commitStagedRun(options.io, options.home, stageKey, options.commitPort, {
+		parentRunId: options.runId,
 		origin: "foreground",
 		summary: options.summary,
 		now: options.now,

package/lib/types/adapters/engine-screen.d.ts

@@ -23,7 +23,7 @@ export interface EngineScreenPort {
             done?: number;
             total?: number;
         }) => void;
-        readonly runner?: (prompt: string, cfg?: Record<string, unknown>) => Promise<string>;
+        readonly runner?: (prompt: string, cfg?: Record<string, unknown>, signal?: AbortSignal | undefined) => Promise<string>;
     }): Promise<EngineScreenResult>;
 }
 export interface CandidateSelection {
@@ -46,7 +46,7 @@ export interface EngineScreeningDeps {
     readonly engine: EngineScreenPort;
     readonly select: (report: Record<string, unknown>) => CandidateSelection;
     readonly cfg?: Record<string, unknown>;
-    readonly runner?: (prompt: string, cfg?: Record<string, unknown>) => Promise<string>;
+    readonly runner?: (prompt: string, cfg?: Record<string, unknown>, signal?: AbortSignal | undefined) => Promise<string>;
     readonly onSelection?: (selection: CandidateSelection, runId: string, cards: readonly SkillCard[]) => Promise<void>;
 }
 /** Write the exact card bodies as a support-free corpus snapshot and return its root. */

package/lib/types/adapters/engine-screen.js

@@ -26,11 +26,12 @@ export function createEngineScreening(deps) {
     return async (cards, runId, signal) => {
         const corpusDir = await snapshotCards(deps.io, deps.home, runId, cards);
         const outDir = join(deps.home, 'merge', 'runs', runId, 'engine');
+        const runner = deps.runner === undefined ? undefined : (prompt, cfg) => deps.runner(prompt, cfg, signal);
         const result = await deps.engine.screen({
             corpusDir,
             outDir,
             ...(deps.cfg === undefined ? {} : { cfg: deps.cfg }),
-            ...(deps.runner === undefined ? {} : { runner: deps.runner }),
+            ...(runner === undefined ? {} : { runner }),
             signal,
         });
         if (!result.ok) {

package/lib/types/adapters/model-runner.d.ts

@@ -19,5 +19,5 @@ export interface LlmServiceLike {
         stream(input: Record<string, unknown>): AsyncIterable<LlmChunkLike>;
     }>;
 }
-export declare function createEngineRunner(llm: LlmServiceLike, route: () => ModelRoute): (prompt: string) => Promise<string>;
+export declare function createEngineRunner(llm: LlmServiceLike, route: () => ModelRoute): (prompt: string, cfg?: Record<string, unknown>, signal?: AbortSignal | undefined) => Promise<string>;
 //# sourceMappingURL=model-runner.d.ts.map

package/lib/types/adapters/model-runner.js

@@ -13,8 +13,11 @@ function append(chunk, text) {
     return text;
 }
 export function createEngineRunner(llm, route) {
-    return async (prompt) => {
+    return async (prompt, cfg, runSignal) => {
         const selection = route();
+        const timeout = Number(cfg?.timeoutMs);
+        const timeoutSignal = Number.isFinite(timeout) && timeout > 0 ? AbortSignal.timeout(timeout) : undefined;
+        const signal = runSignal === undefined ? timeoutSignal : timeoutSignal === undefined ? runSignal : (typeof AbortSignal.any === 'function' ? AbortSignal.any([runSignal, timeoutSignal]) : runSignal);
         let text = '';
         if (llm.stream !== undefined) {
             for await (const chunk of llm.stream({
@@ -22,16 +25,18 @@ export function createEngineRunner(llm, route) {
                 model: selection.model,
                 messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
                 temperature: 0,
+                ...(signal === undefined ? {} : { signal }),
             }))
                 text = append(chunk, text);
             return text;
         }
         if (llm.prepareCall === undefined)
             throw new Error('llm service has neither stream nor prepareCall');
-        const call = await llm.prepareCall({ provider: normalizeProviderKey(selection.provider), model: selection.model, temperature: 0 });
+        const call = await llm.prepareCall({ provider: normalizeProviderKey(selection.provider), model: selection.model, temperature: 0 }, signal);
         for await (const chunk of call.stream({
             ...call.config,
             messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
+            ...(signal === undefined ? {} : { signal }),
         }))
             text = append(chunk, text);
         return text;

package/lib/types/approve-command.js

@@ -9,6 +9,7 @@ import { presentStage } from "./domain/stage-aggregate.js";
 import { v4ToLegacy } from "./domain/row-v4.js";
 import { loadMergeState } from "./state.js";
 import { withMergeRun } from "./run-shell.js";
+import { attachRunToRow } from "./domain/row-run.js";
 import { recordRound2Outcome } from "./round2-outcome.js";
 import { failure } from "./domain/errors.js";
 export async function runApproveCommand(options) {
@@ -58,6 +59,7 @@ export async function runApproveCommand(options) {
         now: options.now,
         ...(options.detached === true ? { detached: true } : {}),
         async body(ctx) {
+            await attachRunToRow(options.io, options.home, row.id, ctx.runId);
             const stage = (name) => ctx.stage(name, { done: 0, total: 1 });
             await stage('author');
             let outcome;

package/lib/types/authoring-flow.js

@@ -71,6 +71,10 @@ export async function runAuthoring(options) {
     if (hasBlockingFinding(findings))
         return { ok: false, code: findings.some(finding => finding.rule === 'limit') ? 'merge-over-limit' : 'merge-validation', message: 'staged tree failed the rule gate', findings, lengths };
     const commit = await commitStagedRun(options.io, options.home, stageKey, options.commitPort, {
+        // P1-6: the staged key is `run-1/pairs/abc`; the ROW's run id is the parent.
+        // Without it the scan path writes its unit journal/receipt under the staged
+        // address, so crash recovery looks for a run that was never registered.
+        parentRunId: options.runId,
         origin: 'foreground',
         summary: options.summary,
         now: options.now,

package/lib/types/commit-execute.js

@@ -3,7 +3,6 @@ import { writeCommitReceipt } from "./commit-receipt.js";
 import { pairKey } from "./contracts.js";
 import { writeJournal } from "./domain/commit-journal-store.js";
 import { evidenceSha256 as digestEvidence } from "./domain/evidence-hash.js";
-import { snapshotPath } from "./commit-snapshot.js";
 export async function commitStagedRun(io, home, runId, port, options) {
     const assembled = await assembleStagedCommit(io, home, runId, port, {
         origin: options.origin,
@@ -27,7 +26,9 @@ export async function commitStagedRun(io, home, runId, port, options) {
         return { ok: false, message: 'commit port missing: UnitTransaction or commitMerge required', plan: assembled.plan };
     {
         const first = assembled.plan.sources[0] ?? assembled.plan.target;
-        const unitPlan = { runId, pairKey: pairKey(assembled.plan.target, first), target: assembled.plan.target, targetExists: assembled.plan.targetExists, sources: assembled.plan.sources, body: assembled.plan.body, supportFiles: assembled.plan.supportFiles, expectedTargetBody: assembled.plan.expectedTargetBody, expectedSourceBodies: assembled.plan.expectedSourceBodies, origin: options.origin, summary: options.summary, ...(options.limits === undefined ? {} : { skillLimits: options.limits }), ...(options.validationPlan === undefined ? {} : { validationPlan: options.validationPlan }), ...(options.targetRevision === undefined ? {} : { targetRevision: options.targetRevision }), ...(options.sourceRevisions === undefined ? {} : { sourceRevisions: options.sourceRevisions }), ...(options.supportDigest === undefined ? {} : { supportDigest: options.supportDigest }) };
+        // P1-6: the unit's run identity is the canonical parent run, not the stage key.
+        const unitRunId = options.parentRunId ?? runId;
+        const unitPlan = { runId: unitRunId, pairKey: pairKey(assembled.plan.target, first), target: assembled.plan.target, targetExists: assembled.plan.targetExists, sources: assembled.plan.sources, body: assembled.plan.body, supportFiles: assembled.plan.supportFiles, expectedTargetBody: assembled.plan.expectedTargetBody, expectedSourceBodies: assembled.plan.expectedSourceBodies, origin: options.origin, summary: options.summary, ...(options.limits === undefined ? {} : { skillLimits: options.limits }), ...(options.validationPlan === undefined ? {} : { validationPlan: options.validationPlan }), ...(options.targetRevision === undefined ? {} : { targetRevision: options.targetRevision }), ...(options.sourceRevisions === undefined ? {} : { sourceRevisions: options.sourceRevisions }), ...(options.supportDigest === undefined ? {} : { supportDigest: options.supportDigest }) };
         try {
             await writeJournal(io, home, journal);
         }
@@ -87,10 +88,6 @@ export async function commitStagedRun(io, home, runId, port, options) {
     };
     try {
         await writeCommitReceipt(io, home, receipt);
-        try {
-            await io.remove(snapshotPath(home, runId));
-        }
-        catch { /* committed journal is the record */ }
         return { ok: true, plan: assembled.plan, result, receipt, ...(warning === undefined ? {} : { warning }) };
     }
     catch (error) {

package/lib/types/commit-recovery.d.ts

@@ -8,7 +8,6 @@ export interface CommitRecoveryReport {
     readonly target?: string;
     readonly sources?: readonly string[];
     readonly journalPath?: string;
-    readonly snapshotPath?: string;
     readonly unitId?: string;
 }
 export declare function recoverCommitJournals(io: EvolutionIoLike, home: string, now: number, isActive?: (runId: string) => boolean): Promise<readonly CommitRecoveryReport[]>;

package/lib/types/commit-recovery.js

@@ -1,7 +1,6 @@
 /** Startup replay for non-terminal commit journals: report only, never write skills. */
 import { join } from 'node:path';
 import { writeJournal } from "./domain/commit-journal-store.js";
-import { snapshotPath } from "./commit-snapshot.js";
 import { readCommitReceipt } from "./commit-receipt.js";
 import { readUnitEvidence } from '@lmzhen/dsh-evolution-core';
 export async function recoverCommitJournals(io, home, now, isActive) {
@@ -52,7 +51,7 @@ export async function recoverCommitJournals(io, home, now, isActive) {
                 continue;
             reports.push({
                 runId: journal.runId, phase: journal.phase, action: 'manual-required', ok: false,
-                target: journal.target, sources: journal.sources, journalPath: path, snapshotPath: snapshotPath(home, journal.runId),
+                target: journal.target, sources: journal.sources, journalPath: path,
             });
         }
         catch (error) {

package/lib/types/doctor.js

@@ -7,11 +7,12 @@ import { readTextOrNull } from "./domain/read-probe.js";
 import { createHash } from 'node:crypto';
 import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { probeList, readTreeLock, runsFile } from '@lmzhen/dsh-evolution-core';
+import { probeList, readTreeLock, readUnitJournal, runsFile } from '@lmzhen/dsh-evolution-core';
 import { migrationJournalPath, migrationReportPath, v2BackupPath } from "./domain/state-bootstrap.js";
 import { readMergeSnapshot } from "./domain/merge-snapshot.js";
 import { validateArtifacts } from "./domain/consistency.js";
 import { readJournal } from "./domain/commit-journal-store.js";
+import { readCommitReceipt } from "./commit-receipt.js";
 import { stagingRoot } from "./staging.js";
 import { readReconcileReport } from "./domain/reconcile.js";
 export const MERGE_DOCTOR_SCHEMA_VERSION = 3;
@@ -72,11 +73,6 @@ export async function mergeDoctor(io, home, configuredRoot) {
                     recoveryRuns.add(report.runId);
     }
     catch { }
-    const receiptRuns = new Set();
-    const receiptDir = await probeList(io, join(home, 'merge', 'receipts'));
-    if (receiptDir.kind === 'present')
-        for (const name of receiptDir.value)
-            receiptRuns.add(name);
     const invalid = [];
     if (snapshot.blocked !== undefined)
         invalid.push({ id: 'state', reason: snapshot.blocked.code });
@@ -86,9 +82,10 @@ export async function mergeDoctor(io, home, configuredRoot) {
         const artifactRow = row.state === 'approved' ? 'approved' : row.state === 'fuse' ? 'fuse' : row.state;
         const run = runId === undefined ? 'none' : row.state === 'pending' ? 'awaiting-approval' : 'running';
         const staging = item.stage === null ? (row.state === 'fuse' ? 'missing' : 'none') : item.stage.state === 'present' || item.stage.state === 'reserved' ? 'kept' : row.state === 'fuse' ? 'missing' : 'none';
-        const phase = runId === undefined ? null : await readJournal(io, home, runId);
-        const journal = phase === null ? 'none' : phase.phase === 'prepared' ? 'prepared' : phase.phase === 'target-written' || phase.phase === 'sources-archived' ? 'committing' : phase.phase === 'committed' ? 'committed' : phase.phase === 'rolled-back' ? 'rolled-back' : 'failed';
-        const evidence = runId !== undefined && await readTextOrNull(io, join(home, 'merge', 'receipts', runId + '.json')) !== null ? 'receipt' : 'none';
+        const receipt = runId === undefined ? null : await readCommitReceipt(io, home, runId);
+        const phase = receipt !== null ? await readUnitJournal(io, home, receipt.unitId) : runId === undefined ? null : await readJournal(io, home, runId);
+        const journal = phase === null ? 'none' : phase.phase === 'prepared' || phase.phase === 'target-pending' ? 'prepared' : phase.phase === 'target-written' || phase.phase === 'sources-archived' || phase.phase === 'support-pending' || phase.phase === 'source-archiving' ? 'committing' : phase.phase === 'committed' ? 'committed' : phase.phase === 'rolled-back' ? 'rolled-back' : 'failed';
+        const evidence = receipt === null ? 'none' : 'receipt';
         const result = validateArtifacts({ row: artifactRow, run, staging, journal, evidence, activeRuns: run === 'running' || run === 'awaiting-approval' ? 1 : 0, ...(runId !== undefined && recoveryRuns.has(runId) ? { recovery: true } : {}) });
         if (!result.ok)
             invalid.push({ id: row.id, reason: result.reason ?? 'not-allowed' });

package/lib/types/domain/authoring-manifest.d.ts

@@ -8,12 +8,18 @@ export interface AuthoringManifest {
     readonly files: readonly string[];
 }
 /**
- * Parse `{"target":..., "files":[...]}` from a child's final turn text.
- * @param text - the child's answer (JSON is expected; prose is tolerated).
- * @returns the manifest, or null when the turn carried no well-formed envelope.
+ * Parse the authoring manifest from a child's final turn.
+ *
+ * P2-20: a child that wraps the envelope in a fenced code block or in one prose
+ * sentence is the normal shape, not a malformed answer. A strict whole-text
+ * JSON.parse returned null there, and null used to mean "every staged file was
+ * declared" - the exact files the check exists to catch. Try the whole answer,
+ * then every fenced body, then every balanced object literal.
+ * @param text - the child's answer.
+ * @returns the first valid envelope, or null when the turn really declared none.
  */
 export declare function parseAuthoringManifest(text: string): AuthoringManifest | null;
-/** Files a manifest promises for a staged tree (declared list, or the tree when undeclared). */
+/** Files a manifest promises for a staged tree. */
 export declare function manifestFilesOf(manifest: AuthoringManifest | null, stagedPaths: readonly string[]): readonly string[];
 /**
  * The first file the manifest promises but the staged tree does not contain.

package/lib/types/domain/authoring-manifest.js

@@ -1,26 +1,100 @@
+function asManifest(value) {
+    if (value === null || typeof value !== 'object')
+        return null;
+    const record = value;
+    if (!Array.isArray(record.files) || record.files.some(file => typeof file !== 'string'))
+        return null;
+    if (record.target !== undefined && typeof record.target !== 'string')
+        return null;
+    return { ...(typeof record.target === 'string' ? { target: record.target } : {}), files: record.files };
+}
+/** Every balanced object literal in a prose/fenced answer (string-aware). */
+function balancedObjects(text) {
+    const found = [];
+    let depth = 0;
+    let start = -1;
+    let quoted = false;
+    let escaped = false;
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (quoted) {
+            if (escaped)
+                escaped = false;
+            else if (char === '\\')
+                escaped = true;
+            else if (char === '"')
+                quoted = false;
+            continue;
+        }
+        if (char === '"') {
+            quoted = true;
+            continue;
+        }
+        if (char === '{') {
+            if (depth === 0)
+                start = index;
+            depth += 1;
+            continue;
+        }
+        if (char !== '}' || depth === 0)
+            continue;
+        depth -= 1;
+        if (depth === 0 && start >= 0) {
+            found.push(text.slice(start, index + 1));
+            start = -1;
+        }
+    }
+    return found;
+}
 /**
- * Parse `{"target":..., "files":[...]}` from a child's final turn text.
- * @param text - the child's answer (JSON is expected; prose is tolerated).
- * @returns the manifest, or null when the turn carried no well-formed envelope.
+ * Parse the authoring manifest from a child's final turn.
+ *
+ * P2-20: a child that wraps the envelope in a fenced code block or in one prose
+ * sentence is the normal shape, not a malformed answer. A strict whole-text
+ * JSON.parse returned null there, and null used to mean "every staged file was
+ * declared" - the exact files the check exists to catch. Try the whole answer,
+ * then every fenced body, then every balanced object literal.
+ * @param text - the child's answer.
+ * @returns the first valid envelope, or null when the turn really declared none.
  */
 export function parseAuthoringManifest(text) {
+    // Author callbacks in tests (and a bare void answer) can hand undefined;
+    // "no answer" is the same as "no envelope", not a crash.
+    if (typeof text !== 'string')
+        return null;
     try {
-        const value = JSON.parse(text);
-        if (!Array.isArray(value.files) || value.files.some(file => typeof file !== 'string'))
-            return null;
-        if (value.target !== undefined && typeof value.target !== 'string')
-            return null;
-        return { ...(typeof value.target === 'string' ? { target: value.target } : {}), files: value.files };
+        const direct = asManifest(JSON.parse(text));
+        if (direct !== null)
+            return direct;
     }
-    catch {
-        return null;
+    catch { /* not the whole answer */ }
+    for (const match of text.matchAll(/\x60\x60\x60(?:json)?\s*([\s\S]*?)\x60\x60\x60/g)) {
+        try {
+            const parsed = asManifest(JSON.parse(match[1] ?? ''));
+            if (parsed !== null)
+                return parsed;
+        }
+        catch { /* try the next fence/object */ }
+    }
+    for (const candidate of balancedObjects(text)) {
+        try {
+            const parsed = asManifest(JSON.parse(candidate));
+            if (parsed !== null)
+                return parsed;
+        }
+        catch { /* try the next candidate */ }
     }
+    return null;
 }
-/** Files a manifest promises for a staged tree (declared list, or the tree when undeclared). */
+/** Files a manifest promises for a staged tree. */
 export function manifestFilesOf(manifest, stagedPaths) {
+    // P2-20: an answer that declared nothing is NOT a declaration of every staged
+    // file. Only SKILL.md is inherently required; any other staged file must be
+    // named (or be an existing target support file) or q09-undeclared blocks it.
     if (manifest !== null)
         return manifest.files;
-    return ['SKILL.md', ...stagedPaths];
+    void stagedPaths;
+    return ['SKILL.md'];
 }
 /**
  * The first file the manifest promises but the staged tree does not contain.

package/lib/types/domain/row-run.d.ts

@@ -0,0 +1,4 @@
+import type { EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+/** Attach the in-flight child run to a row before its round2 starts (P1-8). */
+export declare function attachRunToRow(io: EvolutionIoLike, home: string, rowId: string, runId: string): Promise<void>;
+//# sourceMappingURL=row-run.d.ts.map

package/lib/types/domain/row-run.js

@@ -0,0 +1,14 @@
+import { pairLedger } from "./pair-ledger.js";
+/** Attach the in-flight child run to a row before its round2 starts (P1-8). */
+export async function attachRunToRow(io, home, rowId, runId) {
+    const attached = await pairLedger(io, home).transact(tx => {
+        const current = tx.rows().find(row => row.id === rowId);
+        if (current === undefined)
+            return false;
+        const moved = tx.transition(rowId, { type: 'run-attached', runId }, current.version);
+        return moved.ok;
+    });
+    if (!attached)
+        throw new Error('row is not attachable to run: ' + rowId);
+}
+//# sourceMappingURL=row-run.js.map

package/lib/types/domain/row-v4.d.ts

@@ -80,6 +80,9 @@ export type V4Event = {
     readonly type: 'staged';
     readonly stagingRef?: string;
     readonly stagingExpiresAt?: number;
+} | {
+    readonly type: 'run-attached';
+    readonly runId: string;
 } | {
     readonly type: 'committed';
     readonly unitId: CommitUnitRef;

package/lib/types/domain/row-v4.js

@@ -35,6 +35,8 @@ export function transitionV4(row, event, expectedVersion, at = new Date().toISOS
                 return { ok: true, row: null, version: expectedVersion + 1 };
             return illegal('pending/' + event.type);
         case 'approved':
+            if (event.type === 'run-attached')
+                return { ok: true, row: advance(row, at, { runId: event.runId }), version: expectedVersion + 1 };
             if (event.type === 'staged')
                 return { ok: true, row: advance(row, at, { state: 'fuse', ...(event.stagingRef === undefined ? {} : { stagingRef: event.stagingRef }), ...(event.stagingExpiresAt === undefined ? {} : { stagingExpiresAt: event.stagingExpiresAt }) }), version: expectedVersion + 1 };
             if (event.type === 'committed')
@@ -49,6 +51,8 @@ export function transitionV4(row, event, expectedVersion, at = new Date().toISOS
                 return { ok: true, row: null, version: expectedVersion + 1 };
             return illegal('approved/' + event.type);
         case 'fuse':
+            if (event.type === 'run-attached')
+                return { ok: true, row: advance(row, at, { runId: event.runId }), version: expectedVersion + 1 };
             if (event.type === 'committed')
                 return { ok: true, row: null, version: expectedVersion + 1 };
             if (event.type === 'skipped')

package/lib/types/domain/stage-aggregate.js

@@ -224,7 +224,9 @@ export async function cleanupStage(io, home, now, rows, limit = 100) {
     const refs = new Set();
     const indexRoot = join(home, 'merge', 'staging-index');
     const names = await io.exists(indexRoot) ? await listOrEmpty(io, indexRoot) : [];
-    for (const name of names.slice(0, limit)) {
+    // P1-7: refs must be collected from EVERY index before deleting run trees; the
+    // limit only bounds how many orphan run dirs one sweep removes, never the ref set.
+    for (const name of names) {
         if (!name.endsWith('.json'))
             continue;
         const raw = await readTextOrNull(io, join(indexRoot, name));

package/lib/types/domain/validation-plan.d.ts

@@ -23,6 +23,7 @@ export interface ValidationPlan {
         readonly forwardRefs: readonly string[];
         readonly reverseRefs: readonly string[];
         readonly orphanFiles: readonly string[];
+        readonly undeclaredFiles: readonly string[];
     };
     readonly supportConflicts: readonly {
         readonly path: string;

package/lib/types/domain/validation-plan.js

@@ -15,6 +15,9 @@ export function buildValidationPlan(input) {
     const reverseRefs = files.map(file => file.path).filter(path => path !== 'SKILL.md' && !refs.has(path) && manifest.has(path)).sort();
     const existing = new Set(input.existingSupport ?? []);
     const orphanFiles = [...existing].filter(path => !staged.has(path)).sort();
+    // P2-20: a clean JSON subset must not exempt the staged files it omitted.
+    // Existing target support files stay exempt (round 2 legitimately updates them).
+    const undeclaredFiles = [...staged].filter(path => path !== 'SKILL.md' && !manifest.has(path) && !existing.has(path)).sort();
     const byPath = new Map();
     // Conflict means TWO SKILLS contributing different bytes at one path. Staged edits and
     // the target's previous file are not conflicts: the target file is a CAS baseline that
@@ -32,7 +35,7 @@ export function buildValidationPlan(input) {
     const sourceThreatFiles = participantCards.flatMap(card => (card.files ?? []).filter(file => scanContentThreats(file.content) !== null).map(file => card.name + '/' + file.path));
     const threat = { body: scanContentThreats(input.tree.body) !== null || participantCards.some(card => scanContentThreats(card.body) !== null), files: [...files.filter(file => scanContentThreats(file.content) !== null).map(file => file.path), ...sourceThreatFiles] };
     const sourceRevisions = input.sourceRevisions ?? Object.fromEntries(participantCards.map(card => [card.name, digest(card.body)]));
-    const revision = digest(JSON.stringify({ target: input.target, body: digest(input.tree.body), files: files.map(file => [file.path, file.digest]), q09: { forwardRefs, reverseRefs, orphanFiles }, supportConflicts, threat, sourceRevisions, targetRevision: input.targetRevision ?? null }));
+    const revision = digest(JSON.stringify({ target: input.target, body: digest(input.tree.body), files: files.map(file => [file.path, file.digest]), q09: { forwardRefs, reverseRefs, orphanFiles, undeclaredFiles }, supportConflicts, threat, sourceRevisions, targetRevision: input.targetRevision ?? null }));
     const findings = [];
     const stageDigest = digest(JSON.stringify(files.map(file => [file.path, file.digest])));
     if (forwardRefs.length > 0)
@@ -41,6 +44,8 @@ export function buildValidationPlan(input) {
         findings.push({ rule: 'q09-reverse', path: reverseRefs.join(','), severity: 'block', message: 'staged manifest file is not referenced by body' });
     if (orphanFiles.length > 0)
         findings.push({ rule: 'q09-orphan', path: orphanFiles.join(','), severity: 'block', message: 'target tree support is not declared by plan' });
+    if (undeclaredFiles.length > 0)
+        findings.push({ rule: 'q09-undeclared', path: undeclaredFiles.join(','), severity: 'block', message: 'staged support file is not declared by the authoring manifest' });
     if (supportConflicts.length > 0)
         findings.push({ rule: 'support-conflict', path: supportConflicts.map(item => item.path).join(','), severity: 'block', message: 'same support path has different contents' });
     if (threat.body)
@@ -52,6 +57,6 @@ export function buildValidationPlan(input) {
     for (const file of files)
         if (file.bytes > input.limits.skillLimits.maxSkillFileBytes)
             findings.push({ rule: 'limit', path: file.path, severity: 'block', message: 'file exceeds maxSkillFileBytes' });
-    return { planVersion: 1, stageDigest, target: input.target, body: input.tree.body, files, supportFiles, manifestFiles, q09: { forwardRefs, reverseRefs, orphanFiles }, supportConflicts, threat, sourceRevisions, targetRevision: input.targetRevision ?? null, limitsDigest: input.limits.limitsDigest, ...(input.promptVersion === undefined ? {} : { promptVersion: input.promptVersion }), ...(input.promptHash === undefined ? {} : { promptHash: input.promptHash }), revision, findings };
+    return { planVersion: 1, stageDigest, target: input.target, body: input.tree.body, files, supportFiles, manifestFiles, q09: { forwardRefs, reverseRefs, orphanFiles, undeclaredFiles }, supportConflicts, threat, sourceRevisions, targetRevision: input.targetRevision ?? null, limitsDigest: input.limits.limitsDigest, ...(input.promptVersion === undefined ? {} : { promptVersion: input.promptVersion }), ...(input.promptHash === undefined ? {} : { promptHash: input.promptHash }), revision, findings };
 }
 //# sourceMappingURL=validation-plan.js.map

package/lib/types/recovery-coordinator.js

@@ -33,6 +33,12 @@ export async function recoverCommitUnits(options) {
         }
         if (journal === null || typeof journal.unitId !== 'string')
             continue;
+        // P1-4: legacy tree-change journals may still sit in the merge directory; they are ordinary
+        // skill units, never merge runs. Never finalize/rollback/project them as a merge.
+        if (journal.kind === 'tree-change' || (journal.kind === undefined && journal.runId === journal.unitId)) {
+            reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch: branchOf(journal.phase), action: 'none', ok: true, code: 'skill-unit-skipped' });
+            continue;
+        }
         if (options.isActive?.(journal.runId) === true) {
             reports.push({ unitId: journal.unitId, runId: journal.runId, phase: journal.phase, branch: branchOf(journal.phase), action: 'none', ok: true, code: 'skipped-active-run' });
             continue;

package/lib/types/resume-command.js

@@ -6,6 +6,7 @@ import { errorText } from '@lmzhen/dsh-evolution-core';
 import { loadMergeState } from "./state.js";
 import { runScanCommand } from "./scan-command.js";
 import { withMergeRun } from "./run-shell.js";
+import { attachRunToRow } from "./domain/row-run.js";
 import { recordRound2Outcome } from "./round2-outcome.js";
 import { pairLedger } from "./domain/pair-ledger.js";
 import { presentStage } from "./domain/stage-aggregate.js";
@@ -75,6 +76,7 @@ export async function runResumeCommand(options) {
         parentRunId, now: options.now,
         ...(options.detached === true ? { detached: true } : {}),
         async body(ctx) {
+            await attachRunToRow(options.io, options.home, row.id, ctx.runId);
             await ctx.stage('author', { done: 0, total: 1 });
             let outcome;
             try {

package/lib/types/run-shell.js

@@ -33,6 +33,20 @@ export async function withMergeRun(options) {
         phase: 'running', approval: options.approval.mergeApproval ? 'pending' : 'approved',
         createdAt: new Date(startedAt).toISOString(), updatedAt: new Date(options.now()).toISOString(),
     });
+    const writeFailureMeta = async (stopReason) => {
+        try {
+            await writeRunMeta(options.io, options.home, {
+                version: 1, runId: handle.id, pid: process.pid,
+                ...(options.parentRunId === undefined ? {} : { parentRunId: options.parentRunId }),
+                ...(options.pairKey === undefined ? {} : { pairKey: options.pairKey }),
+                ...(options.stagingRef === undefined ? {} : { stagingRef: options.stagingRef }),
+                pairCount: options.pairCount ?? (options.pairKey === undefined ? 0 : 1),
+                phase: 'settled', approval: 'approved', stopReason,
+                createdAt: new Date(startedAt).toISOString(), updatedAt: new Date(options.now()).toISOString(),
+            });
+        }
+        catch { /* best-effort: the registry settle below remains authoritative */ }
+    };
     const finish = async () => {
         let draft;
         const runController = new AbortController();
@@ -115,6 +129,7 @@ export async function withMergeRun(options) {
         }
         catch (error) {
             await options.registry.settle(handle.id, { state: 'failed', failure: 'report write failed: ' + (error instanceof Error ? error.message : String(error)) });
+            await writeFailureMeta('failed');
             return { ok: false, runId: handle.id, message: 'report write failed' };
         }
         try {
@@ -122,6 +137,7 @@ export async function withMergeRun(options) {
         }
         catch (error) {
             await options.registry.settle(handle.id, { state: 'failed', resultRef: reportPath, failure: 'post-report finalize failed: ' + (error instanceof Error ? error.message : String(error)) });
+            await writeFailureMeta('failed');
             return { ok: false, runId: handle.id, message: 'post-report finalize failed', reportPath };
         }
         const runState = report.stopReason === 'completed'

package/lib/types/surface/merge-view.js

@@ -107,7 +107,9 @@ export function parseCursor(cursor, snapshot) {
     }
 }
 export function buildQueuePage(snapshot, queue, expiredOnly, cursor, limit = 50) {
-    const selected = snapshot.rows.filter(row => row.queue === queue && (queue === 'skipped' ? true : expiredOnly ? row.expired : !row.expired));
+    // P2-17: skipped rows are a normal queue. Expired ones belong to the expired bucket
+    // (counts.expired); the default list must not show them beside an active badge.
+    const selected = snapshot.rows.filter(row => row.queue === queue && (expiredOnly ? row.expired : !row.expired));
     const offset = cursor === undefined ? 0 : parseCursor(cursor, snapshot);
     const page = selected.slice(offset, offset + Math.max(0, Math.min(200, limit)));
     const next = offset + page.length < selected.length ? encodeCursor(snapshot, offset + page.length) : undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-merge",
   "description": "Skill auto-merge domain: screening, two-round authoring, queues and commit orchestration (community build)",
-  "version": "0.32.2",
+  "version": "0.32.4",
   "publishConfig": {
     "access": "public"
   },
@@ -32,9 +32,9 @@
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.5",
-    "@lmzhen/dsh-evolution-core": "^0.32.2",
-    "@lmzhen/dsh-evolution-commands": "^0.32.2",
-    "@lmzhen/dsh-evolution-merge-engine": "0.32.2"
+    "@lmzhen/dsh-evolution-core": "^0.32.4",
+    "@lmzhen/dsh-evolution-commands": "^0.32.4",
+    "@lmzhen/dsh-evolution-merge-engine": "0.32.4"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5"

package/lib/types/commit-snapshot.d.ts

@@ -1,38 +0,0 @@
-import type { CommitMergePlan, EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
-export interface CommitSnapshot {
-    readonly runId: string;
-    readonly target: string;
-    readonly create: boolean;
-    readonly sources: readonly string[];
-    readonly targetBody: string | null;
-    readonly sourceBodies: readonly {
-        readonly name: string;
-        readonly body: string;
-    }[];
-    readonly targetSupport?: readonly {
-        readonly path: string;
-        readonly content: string;
-    }[];
-    readonly targetSupportAfter?: readonly {
-        readonly path: string;
-        readonly content: string;
-    }[];
-    readonly sourceSupport?: readonly {
-        readonly name: string;
-        readonly path: string;
-        readonly content: string;
-    }[];
-    readonly at: string;
-}
-export declare function snapshotPath(home: string, runId: string): string;
-export declare function writeCommitSnapshot(io: EvolutionIoLike, home: string, runId: string, plan: CommitMergePlan, now: number, port?: {
-    readSupportFiles?(name: string): Promise<readonly {
-        readonly path: string;
-        readonly content: string;
-    }[]>;
-}): Promise<CommitSnapshot>;
-export declare function readCommitSnapshot(io: EvolutionIoLike, home: string, runId: string): Promise<CommitSnapshot | null>;
-export declare function isSafeSkillName(name: string): boolean;
-export declare function skillFilePath(root: string, name: string, path: string): string;
-export declare function skillBodyPath(root: string, name: string): string;
-//# sourceMappingURL=commit-snapshot.d.ts.map

package/lib/types/commit-snapshot.js

@@ -1,65 +0,0 @@
-/** Pre-commit snapshot: enough to restore the target and archived sources after a crash. */
-import { join, resolve, sep } from 'node:path';
-export function snapshotPath(home, runId) {
-    return join(home, 'merge', 'snapshots', runId.replace(/[^A-Za-z0-9_-]+/g, '_') + '.json');
-}
-export async function writeCommitSnapshot(io, home, runId, plan, now, port) {
-    if (!isSafeSkillName(plan.target) || plan.sources.some(name => !isSafeSkillName(name))) {
-        throw new Error('unsafe skill name in commit plan: ' + plan.target);
-    }
-    const readSupport = port?.readSupportFiles === undefined
-        ? undefined
-        : (name) => port.readSupportFiles?.(name) ?? Promise.resolve([]);
-    const targetSupport = readSupport === undefined || !plan.targetExists ? [] : await readSupport(plan.target);
-    const sourceSupport = [];
-    if (readSupport !== undefined) {
-        for (const name of plan.sources) {
-            for (const file of await readSupport(name))
-                sourceSupport.push({ name, path: file.path, content: file.content });
-        }
-    }
-    const snapshot = {
-        runId, target: plan.target, create: !plan.targetExists, sources: plan.sources,
-        targetBody: plan.expectedTargetBody,
-        sourceBodies: plan.expectedSourceBodies.map(item => ({ name: item.name, body: item.body })),
-        ...(targetSupport.length === 0 ? {} : { targetSupport }),
-        ...(plan.supportFiles.length === 0 ? {} : { targetSupportAfter: plan.supportFiles }),
-        ...(sourceSupport.length === 0 ? {} : { sourceSupport }),
-        at: new Date(now).toISOString(),
-    };
-    await io.writeText(snapshotPath(home, runId), JSON.stringify(snapshot, null, 2));
-    return snapshot;
-}
-export async function readCommitSnapshot(io, home, runId) {
-    const raw = await io.readText(snapshotPath(home, runId));
-    if (raw === null)
-        return null;
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-export function isSafeSkillName(name) {
-    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) && name !== '.' && name !== '..';
-}
-export function skillFilePath(root, name, path) {
-    if (!isSafeSkillName(name) || path.startsWith('/') || path.split('/').includes('..'))
-        throw new Error('unsafe skill file: ' + name + '/' + path);
-    const base = resolve(root, name);
-    const file = resolve(base, path);
-    if (!file.startsWith(base + sep))
-        throw new Error('skill file escapes skill: ' + name + '/' + path);
-    return file;
-}
-export function skillBodyPath(root, name) {
-    if (!isSafeSkillName(name))
-        throw new Error('unsafe skill name: ' + name);
-    const base = resolve(root);
-    const path = resolve(base, name, 'SKILL.md');
-    if (!path.startsWith(base + sep))
-        throw new Error('skill path escapes root: ' + name);
-    return path;
-}
-//# sourceMappingURL=commit-snapshot.js.map