@lmzhen/dsh-evolution-core 0.27.3 → 0.29.0

package/lib/subagent/index.js

@@ -56,8 +56,70 @@ function serviceOf(ctx, name) {
 function messageOf(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+function textOfValue(value) {
+	if (typeof value === "string") return value;
+	if (!Array.isArray(value)) return "";
+	return value.filter((block) => typeof block === "object" && block !== null && block.type === "text").map((block) => {
+		const text = block.text;
+		return typeof text === "string" ? text : "";
+	}).join("");
+}
+function abortLink(signal, timeoutMs) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => {
+		controller.abort(/* @__PURE__ */ new Error("subagent turn timeout"));
+	}, timeoutMs);
+	const onAbort = () => {
+		controller.abort(signal?.reason);
+	};
+	signal?.addEventListener("abort", onAbort, { once: true });
+	return {
+		controller,
+		cleanup: () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+		}
+	};
+}
+function waitForSubagentEnd(ctx, childId, signal, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const finish = (fn) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			fn();
+		};
+		const eventCtx = ctx;
+		const off = typeof eventCtx.on === "function" ? eventCtx.on("subagent/end", (info) => {
+			if (info.id !== childId) return;
+			finish(() => {
+				resolve(info);
+			});
+		}) : () => {};
+		const timer = setTimeout(() => {
+			finish(() => {
+				reject(/* @__PURE__ */ new Error("timed out waiting for subagent/end: " + childId));
+			});
+		}, timeoutMs);
+		const onAbort = () => {
+			finish(() => {
+				reject(signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("conversation turn aborted"));
+			});
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		function cleanup() {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+			off();
+		}
+		if (signal.aborted) onAbort();
+	});
+}
 function createSubagentChannel(ctx) {
 	let lastKind = "reviewer";
+	const active = /* @__PURE__ */ new Map();
+	const disposed = /* @__PURE__ */ new Set();
 	return {
 		get state() {
 			return probeChannelState(ctx, lastKind);
@@ -179,6 +241,184 @@ function createSubagentChannel(ctx) {
 					} catch {}
 				}
 			}
+		},
+		async open(spec) {
+			lastKind = spec.kind;
+			const probe = probeChannelState(ctx, spec.kind);
+			if (probe.kind === "unavailable") return probe;
+			if (spec.allow.length === 0) return {
+				kind: "unavailable",
+				code: "E-324",
+				reason: "allow set is empty"
+			};
+			const subagents = serviceOf(ctx, "subagents");
+			const presets = serviceOf(ctx, "agentPresets");
+			if (subagents === void 0 || presets === void 0) return {
+				kind: "unavailable",
+				code: "E-323",
+				reason: "subagents/agentPresets service unavailable"
+			};
+			const parentPresetId = presets.composedPreset(spec.parent.ctx);
+			if (parentPresetId === void 0) return {
+				kind: "unavailable",
+				code: "E-323",
+				reason: "parent preset could not be resolved"
+			};
+			const ensured = await ensureRestrictedPreset(ctx, {
+				kind: spec.kind,
+				parentPresetId,
+				allow: spec.allow
+			});
+			if (ensured.kind === "failed") return {
+				kind: "unavailable",
+				code: "E-324",
+				reason: ensured.reason
+			};
+			const link = abortLink(spec.signal, spec.timeoutMs);
+			let activation;
+			try {
+				activation = await subagents.startActivation({
+					provider: "spawn",
+					label: spec.label,
+					delivery: "caller",
+					request: {
+						parent: spec.parent,
+						prompt: [{
+							type: "text",
+							text: spec.promptText
+						}],
+						agentPreset: ensured.presetId,
+						...spec.cwd !== void 0 ? { cwd: spec.cwd } : {},
+						...spec.maxDepth !== void 0 ? { maxDepth: spec.maxDepth } : {},
+						...spec.agentOptions !== void 0 ? { agentOptions: spec.agentOptions } : {}
+					},
+					signal: link.controller.signal
+				});
+				const result = await activation.result;
+				if (result.stopReason === "aborted") {
+					try {
+						await activation.dispose();
+					} catch {}
+					return { kind: "aborted" };
+				}
+				if (result.stopReason !== "completed") {
+					try {
+						await activation.dispose();
+					} catch {}
+					return {
+						kind: "unavailable",
+						code: "E-323",
+						reason: "round 1 did not complete: " + result.stopReason
+					};
+				}
+				const turn = {
+					childId: activation.childId,
+					stopReason: result.stopReason,
+					text: textOfValue(result.output),
+					...result.structured !== void 0 ? { structured: result.structured } : {},
+					...result.diagnostic !== void 0 ? { diagnostic: result.diagnostic } : {}
+				};
+				active.set(activation.childId, {
+					childId: activation.childId,
+					parent: spec.parent,
+					activation,
+					disposed: false
+				});
+				disposed.delete(activation.childId);
+				return {
+					kind: "ok",
+					childId: activation.childId,
+					turn
+				};
+			} catch (error) {
+				if (activation !== void 0) try {
+					await activation.dispose();
+				} catch {}
+				if (link.controller.signal.aborted) return { kind: "aborted" };
+				return {
+					kind: "unavailable",
+					code: "E-323",
+					reason: messageOf(error)
+				};
+			} finally {
+				link.cleanup();
+			}
+		},
+		async continueTurn(childId, promptText, options) {
+			if (disposed.has(childId)) return {
+				kind: "unavailable",
+				code: "E-324",
+				reason: "conversation is disposed"
+			};
+			const current = active.get(childId);
+			if (current === void 0 || current.disposed) return {
+				kind: "unavailable",
+				code: "E-323",
+				reason: "no open conversation for " + childId
+			};
+			const subagents = serviceOf(ctx, "subagents");
+			if (subagents?.sendMessage === void 0) return {
+				kind: "unavailable",
+				code: "E-323",
+				reason: "subagents.sendMessage unavailable"
+			};
+			const link = abortLink(options?.signal, options?.timeoutMs ?? 12e4);
+			let pending;
+			try {
+				pending = waitForSubagentEnd(ctx, childId, link.controller.signal, options?.timeoutMs ?? 12e4);
+				await subagents.sendMessage(current.parent, childId, [{
+					type: "text",
+					text: promptText
+				}], { signal: link.controller.signal });
+			} catch (error) {
+				link.cleanup();
+				if (options?.signal?.aborted === true) return { kind: "aborted" };
+				return {
+					kind: "unavailable",
+					code: "E-323",
+					reason: messageOf(error)
+				};
+			}
+			try {
+				const info = await pending;
+				if (info.stopReason === "aborted") return { kind: "aborted" };
+				return {
+					kind: "ok",
+					childId,
+					turn: {
+						childId,
+						stopReason: info.stopReason ?? "completed",
+						text: textOfValue(info.lastAssistantMessage),
+						...info.diagnostic !== void 0 ? { diagnostic: info.diagnostic } : {}
+					}
+				};
+			} catch (error) {
+				if (options?.signal?.aborted === true) return { kind: "aborted" };
+				return {
+					kind: "unavailable",
+					code: "E-323",
+					reason: messageOf(error)
+				};
+			} finally {
+				link.cleanup();
+			}
+		},
+		async dispose(childId) {
+			const current = active.get(childId);
+			if (current === void 0 || current.disposed) {
+				disposed.add(childId);
+				return;
+			}
+			current.disposed = true;
+			active.delete(childId);
+			disposed.add(childId);
+			try {
+				await current.activation.dispose();
+			} catch (error) {
+				try {
+					ctx.logger.warn("subagent conversation: dispose failed: " + messageOf(error));
+				} catch {}
+			}
 		}
 	};
 }

package/lib/types/http-routes.d.ts

@@ -53,6 +53,12 @@ export declare const HOST_ROUTES: {
     readonly skillHealth: {
         readonly rows: "/api/dsh-evolution/skill-health/rows";
     };
+    readonly merge: {
+        readonly view: "/api/dsh-evolution/merge/view";
+        readonly rows: "/api/dsh-evolution/merge/rows";
+        readonly run: "/api/dsh-evolution/merge/run";
+        readonly runs: "/api/dsh-evolution/merge/runs";
+    };
     readonly diagnostics: {
         readonly view: "/api/dsh-evolution/diagnostics";
     };

package/lib/types/http-routes.js

@@ -50,6 +50,12 @@ export const HOST_ROUTES = {
     skillHealth: {
         rows: '/api/dsh-evolution/skill-health/rows',
     },
+    merge: {
+        view: '/api/dsh-evolution/merge/view',
+        rows: '/api/dsh-evolution/merge/rows',
+        run: '/api/dsh-evolution/merge/run',
+        runs: '/api/dsh-evolution/merge/runs',
+    },
     diagnostics: {
         view: '/api/dsh-evolution/diagnostics',
     },

package/lib/types/index.d.ts

@@ -58,6 +58,9 @@ export * from './quality.ts';
 export * from './redact.ts';
 export * from './review-channel.ts';
 export * from './run-registry.ts';
+export * from './tree-lock.ts';
+export * from './unit-undo-plan.ts';
+export * from './unit-undo.ts';
 export * from './reports.ts';
 export * from './long-runs.ts';
 export * from './serial.ts';

package/lib/types/index.js

@@ -59,6 +59,9 @@ export * from "./quality.js";
 export * from "./redact.js";
 export * from "./review-channel.js";
 export * from "./run-registry.js";
+export * from "./tree-lock.js";
+export * from "./unit-undo-plan.js";
+export * from "./unit-undo.js";
 export * from "./reports.js";
 export * from "./long-runs.js";
 export * from "./serial.js";

package/lib/types/params.d.ts

@@ -48,7 +48,7 @@ export declare function readParam(carrier: object | undefined, id: string): unkn
  * belongs to, the tier says who may change it. `internal` here is a group id with no rows today;
  * the `why: 'internal'` a non-E3 row carries is a different value on the other axis (the reason it
  * has no settings card) — the shared spelling is a coincidence, not a routing rule. */
-export type ParamGroup = 'library' | 'write-caps' | 'review' | 'memory' | 'curator' | 'deployment' | 'internal';
+export type ParamGroup = 'library' | 'write-caps' | 'review' | 'memory' | 'curator' | 'deployment' | 'merge' | 'internal';
 /**
  * Chinese display name per group, one entry per line (the scripts read this block
  * by text, the same way they read PARAM_NAMESPACES). The raw group id is what

package/lib/types/params.js

@@ -91,6 +91,7 @@ export const PARAM_GROUP_LABELS = Object.freeze({
     memory: '记忆',
     curator: '技能整理',
     deployment: '安装配置',
+    merge: '技能合并',
     internal: '内部',
 });
 /**
@@ -203,6 +204,11 @@ export const PARAM_EXPOSURE = Object.freeze([
     { id: 'install.presetRowOverrides', group: 'deployment', tier: 'E4', authority: 'install', owner: 'scripts', applies: 'restart', docAnchor: 'PARAMETERS.md#deployment', summary: 'Preset row overrides the installer injects (row-overrides.json).', why: 'install' },
     { id: 'timeout.gateDefault', group: 'deployment', tier: 'E2', authority: 'install', owner: 'scripts', applies: 'none', docAnchor: 'PARAMETERS.md#deployment', summary: 'Gate budget: the vitest --testTimeout the gate table and the CI step carry (the number lives in testing-policy.timeouts).', why: 'internal' },
     { id: 'timeout.specDefault', group: 'deployment', tier: 'E2', authority: 'install', owner: 'scripts', applies: 'none', docAnchor: 'PARAMETERS.md#deployment', summary: 'Local spec budget: the vitest testTimeout the family config generates per leaf tier (the number lives in testing-policy.timeouts).', why: 'internal' },
+    { id: 'mergeApproval', group: 'merge', tier: 'E3', authority: 'cordis', owner: 'evolution-merge', applies: 'live', docAnchor: 'PARAMETERS.md#merge', summary: 'Pause after round 1 and put the pair in the pending queue instead of authoring round 2 automatically.', label: '合并审批', hint: '开启后，第一轮判定完先停下、进入待批准清单；关闭则直接进入第二轮合并。', control: 'switch', unit: '', values: '', card: 'evolution-merge' },
+    { id: 'mergeSkippedTtlDays', group: 'merge', tier: 'E3', authority: 'cordis', owner: 'evolution-merge', applies: 'live', docAnchor: 'PARAMETERS.md#merge', summary: 'Days a skipped pair stays out of screening; 0 means it never expires.', label: '无需合并保留天数', hint: '判定无需合并的对，多少天内不再参与筛选；0 表示一直保留。', control: 'number', unit: '天', values: '', card: 'evolution-merge' },
+    { id: 'mergeRunTimeoutMinutes', group: 'merge', tier: 'E3', authority: 'cordis', owner: 'evolution-merge', applies: 'live', docAnchor: 'PARAMETERS.md#merge', summary: 'Wall-clock budget of one merge run; 0 means no limit.', label: '单次运行上限', hint: '一次合并运行最多持续多少分钟；0 表示不设上限。', control: 'number', unit: '分钟', values: '', card: 'evolution-merge' },
+    { id: 'mergePairTimeoutMinutes', group: 'merge', tier: 'E2', authority: 'cordis', owner: 'evolution-merge', applies: 'none', docAnchor: 'PARAMETERS.md#merge', summary: 'Wall-clock budget of one pair round (a stuck child guard).', why: 'internal' },
+    { id: 'mergeModelsRoot', group: 'merge', tier: 'E2', authority: 'cordis', owner: 'evolution-merge', applies: 'none', docAnchor: 'PARAMETERS.md#merge', summary: 'Local model root containing the int8 and pca64 model directories; empty falls back to SKILL_MERGE_MODELS_ROOT. No auto provisioning.', why: 'path' },
 ]);
 /** The settings namespace each OWNER PACKAGE registers (design §7.2).
  *
@@ -223,6 +229,7 @@ export const PARAM_NAMESPACES = Object.freeze({
     // 0.21.0 (G3): the commands row's handoff switch is E3 — same reason as the entry above: the card
     // and `/evolution params set` both resolve their settings namespace through this map.
     'evolution-commands': 'evolution-commands',
+    'evolution-merge': 'evolution-merge',
 });
 /**
  * The rows whose settings namespace CHANGED with the platform-line move (G3): the

package/lib/types/platform-services.d.ts

@@ -20,7 +20,7 @@ export interface PlatformServiceProbe {
     /** Where the probe runs. */
     readonly side: 'host' | 'client';
 }
-/** The 25 probes, in service-name order (the guard checks this list against the tree). */
+/** The 26 probes, in service-name order (the guard checks this list against the tree). */
 export declare const PLATFORM_SERVICE_PROBES: readonly PlatformServiceProbe[];
 /**
  * The HOST-side probes that do not resolve in this runtime — what `/evolution doctor` prints as

package/lib/types/platform-services.js

@@ -11,7 +11,7 @@
  * `client` probes run in the browser half, where the host has no view of the seats.
  * @module @lmzhen/dsh-evolution-core
  */
-/** The 25 probes, in service-name order (the guard checks this list against the tree). */
+/** The 26 probes, in service-name order (the guard checks this list against the tree). */
 export const PLATFORM_SERVICE_PROBES = Object.freeze([
     { service: 'agents', feature: 'review and curator subagent wake-ups', side: 'host' },
     { service: 'approval', feature: 'the platform approval policy the approval row shadows', side: 'host' },
@@ -22,6 +22,7 @@ export const PLATFORM_SERVICE_PROBES = Object.freeze([
     { service: 'evolutionIo', feature: 'every durable read and write (the IO seam)', side: 'host' },
     { service: 'hmr', feature: 'the preset install read-merge-write commit (the platform HMR lock serializes it)', side: 'host' },
     { service: 'evolutionMemoryBudget', feature: 'the memory-budget divergence section of this report', side: 'host' },
+    { service: 'evolutionMerge', feature: 'the merge command and its read-only panel routes', side: 'host' },
     { service: 'evolutionPolicy', feature: 'the policy snapshot that shadows row knobs', side: 'host' },
     { service: 'evolutionReplay', feature: '/evolution replay', side: 'host' },
     { service: 'evolutionState', feature: 'the state facade behind activity and replay', side: 'host' },

package/lib/types/run-registry.d.ts

@@ -1,7 +1,7 @@
 /**
  * 0.19.0 (S2) / 0.19.3 (restructure): the family's run-lifecycle owner.
  *
- * A "run" is work that can outlive one interaction — today the maintenance scan.
+ * A "run" is work that can outlive one interaction — the maintenance scan and merge workflows.
  * Before this module the only record of such work was the requesting invocation:
  * `lastMaintainAt` / `lastMaintainRunId` / `maintainInFlightSince` were
  * module-scope globals in evolution-commands, and the plan text existed ONLY in
@@ -38,8 +38,17 @@
  * @module
  */
 import type { EvolutionIoLike } from './io.ts';
-/** The kinds of long-running work the registry tracks. Extend as rows gain runs. */
-export type RunKind = 'maintain';
+/** The kinds of long-running work the registry tracks. */
+export type RunKind = 'maintain' | 'merge';
+/** Which merge command opened a run. `kind` stays the work family; this is the command. */
+export type RunCommand = 'scan' | 'pair' | 'approve' | 'resume';
+/** Coarse, user-visible stage of a run. */
+export type RunStage = 'screening' | 'decide' | 'author' | 'commit' | 'settle';
+/** Progress of a run's current stage. */
+export interface RunProgress {
+    readonly done: number;
+    readonly total: number;
+}
 /** The four terminal-or-live states of a run. */
 export type RunState = 'running' | 'succeeded' | 'failed' | 'cancelled';
 /** One tracked run. `resultRef` is a path to the run's report, never its content. */
@@ -48,6 +57,11 @@ export interface RunRecord {
     kind: RunKind;
     state: RunState;
     startedAt: number;
+    /** The merge command that opened this run, when the kind is merge. */
+    command?: RunCommand | undefined;
+    /** The stage the owner last reported. */
+    stage?: RunStage | undefined;
+    progress?: RunProgress | undefined;
     /** The process that owns a RUNNING record. Required to tell an in-flight run of
      * another plane (both planes share one DSH_HOME) from the orphan of a dead one;
      * absent means the owner cannot be named, which is treated as gone. */
@@ -57,6 +71,10 @@ export interface RunRecord {
     resultRef?: string | undefined;
     /** Why the run did not succeed (an abort reason, a validation failure). */
     failure?: string | undefined;
+    /** Set when a tree restore made this run's effects un-undoable. */
+    supersededAt?: number | undefined;
+    /** The run this run was spawned from (approve/resume after an earlier command). */
+    parentRunId?: string | undefined;
 }
 /** What a started run gets: its id and the signal its work must honour. */
 export interface RunHandle {
@@ -65,6 +83,8 @@ export interface RunHandle {
     readonly signal: AbortSignal;
     /** When the run was registered — the same instant the record carries. */
     readonly startedAt: number;
+    readonly command?: RunCommand | undefined;
+    readonly parentRunId?: string | undefined;
 }
 /** How a run ended, as reported by its owner. */
 export interface RunOutcome {
@@ -90,15 +110,25 @@ export interface RunRegistry {
      * lifetime starts when the caller answers "started", so a plane that reads that answer
      * must find the run. The cost is one local index write on the ack path (milliseconds).
      */
-    begin(kind: RunKind): Promise<RunHandle>;
+    begin(kind: RunKind, seed?: {
+        command?: RunCommand;
+        total?: number;
+        parentRunId?: string;
+    }): Promise<RunHandle>;
     /** Record a run's terminal state (first writer wins). */
     settle(id: string, outcome: RunOutcome): Promise<void>;
-    /** The live run, when there is one (one kind today — see the implementation note). */
-    inFlight(): RunRecord | undefined;
-    /** When the newest terminal run ended (`undefined` when none). */
-    lastSettledAt(): number | undefined;
+    /** Record the current stage/progress of a running run. */
+    stage(id: string, stage: RunStage, progress?: RunProgress): Promise<void>;
+    /** Mark runs as superseded by a tree restore; idempotent. */
+    supersede(ids: readonly string[]): Promise<void>;
+    /** Mark every run of a kind in the SHARED index (including foreign rows); returns the count. */
+    supersedeKind(kind: RunKind): Promise<number>;
+    /** The live run, optionally filtered by kind. */
+    inFlight(kind?: RunKind): RunRecord | undefined;
+    /** When the newest terminal run of a kind ended (`undefined` when none). */
+    lastSettledAt(kind?: RunKind): number | undefined;
     /** Every tracked run, newest first (retained history: cap applied). */
-    runs(): readonly RunRecord[];
+    runs(kind?: RunKind): readonly RunRecord[];
     /** One run by id, converged view included. */
     find(id: string): RunRecord | undefined;
     /** Ask a running run to stop; it settles as `cancelled`. @returns whether it was running. */
@@ -119,7 +149,7 @@ export interface RunRegistryOptions {
     maxRecords?: number;
 }
 /** Current index schema. Bump only for a structural change. */
-export declare const RUNS_SCHEMA_VERSION = 1;
+export declare const RUNS_SCHEMA_VERSION = 2;
 /** Retained run records, newest first. */
 export declare const DEFAULT_RUN_RECORDS = 50;
 /** Index path for a home. */

package/lib/types/run-registry.js

@@ -1,7 +1,7 @@
 /**
  * 0.19.0 (S2) / 0.19.3 (restructure): the family's run-lifecycle owner.
  *
- * A "run" is work that can outlive one interaction — today the maintenance scan.
+ * A "run" is work that can outlive one interaction — the maintenance scan and merge workflows.
  * Before this module the only record of such work was the requesting invocation:
  * `lastMaintainAt` / `lastMaintainRunId` / `maintainInFlightSince` were
  * module-scope globals in evolution-commands, and the plan text existed ONLY in
@@ -42,7 +42,7 @@ import { join } from 'node:path';
 import { clampedNumber } from "./numeric.js";
 import { isProcessAlive, transactIo } from "./io.js";
 /** Current index schema. Bump only for a structural change. */
-export const RUNS_SCHEMA_VERSION = 1;
+export const RUNS_SCHEMA_VERSION = 2;
 /** Retained run records, newest first. */
 export const DEFAULT_RUN_RECORDS = 50;
 /** Index path for a home. */
@@ -99,10 +99,17 @@ function parseIndex(raw) {
             kind: record.kind,
             state: record.state,
             startedAt: record.startedAt,
+            ...(record.command === undefined ? {} : { command: record.command }),
+            ...(record.stage === undefined ? {} : { stage: record.stage }),
+            ...(record.progress === undefined
+                ? {}
+                : { progress: { done: record.progress.done, total: record.progress.total } }),
             ...(typeof record.pid === 'number' ? { pid: record.pid } : {}),
             ...(typeof record.endedAt === 'number' ? { endedAt: record.endedAt } : {}),
             ...(typeof record.resultRef === 'string' ? { resultRef: record.resultRef } : {}),
             ...(typeof record.failure === 'string' ? { failure: record.failure } : {}),
+            ...(typeof record.supersededAt === 'number' ? { supersededAt: record.supersededAt } : {}),
+            ...(typeof record.parentRunId === 'string' ? { parentRunId: record.parentRunId } : {}),
         });
     }
     return { ok: true, records, foreign, ...(notes.length > 0 ? { note: notes.join('; ') } : {}) };
@@ -131,14 +138,20 @@ export function newRunRegistry(options) {
     const orphanOf = (row) => ({ ...row, state: 'failed', endedAt: now(), failure: ORPHAN_FAILURE });
     /** Every row this process knows, newest first. ALL reads go through here. */
     const view = () => [...owned.values(), ...foreign.values()].sort((a, b) => b.startedAt - a.startedAt);
-    /** Retained history: every running row plus the newest terminal ones (one cap, both planes). */
+    /** Retained history: every running row plus the newest terminal rows per kind. */
     const capped = (rows) => {
         const live = rows.filter(row => row.state === 'running');
         const done = rows
             .filter(row => TERMINAL.has(row.state))
-            .sort((a, b) => (b.endedAt ?? b.startedAt) - (a.endedAt ?? a.startedAt))
-            .slice(0, maxRecords);
-        return [...live, ...done].sort((a, b) => b.startedAt - a.startedAt);
+            .sort((a, b) => (b.endedAt ?? b.startedAt) - (a.endedAt ?? a.startedAt));
+        const perKind = new Map();
+        for (const row of done) {
+            const kept = perKind.get(row.kind) ?? [];
+            if (kept.length < maxRecords)
+                kept.push(row);
+            perKind.set(row.kind, kept);
+        }
+        return [...live, ...[...perKind.values()].flat()].sort((a, b) => b.startedAt - a.startedAt);
     };
     /**
      * Update a surviving foreign row in place (identity stable), or add it.
@@ -159,9 +172,14 @@ export function newRunRegistry(options) {
         if (TERMINAL.has(existing.state) && !TERMINAL.has(row.state))
             return true;
         // Clear what the new row dropped, so nothing is inherited from the previous view.
+        delete existing.command;
+        delete existing.stage;
+        delete existing.progress;
         delete existing.endedAt;
         delete existing.resultRef;
         delete existing.failure;
+        delete existing.supersededAt;
+        delete existing.parentRunId;
         Object.assign(existing, row);
         return false;
     };
@@ -269,18 +287,77 @@ export function newRunRegistry(options) {
             ].filter((note) => note !== undefined);
             return { ok: true, ...(notes.length > 0 ? { note: notes.join('; ') } : {}) };
         },
-        async begin(kind) {
+        async begin(kind, seed) {
             const id = randomUUID();
             const startedAt = now();
             const controller = new AbortController();
             controllers.set(id, controller);
             // The pid is what lets ANOTHER process tell this live run from an orphan.
-            owned.set(id, { id, kind, state: 'running', startedAt, pid: process.pid });
+            owned.set(id, {
+                id,
+                kind,
+                state: 'running',
+                startedAt,
+                pid: process.pid,
+                ...(seed?.command !== undefined ? { command: seed.command } : {}),
+                ...(seed?.parentRunId !== undefined ? { parentRunId: seed.parentRunId } : {}),
+                ...(seed?.total !== undefined ? { progress: { done: 0, total: seed.total } } : {}),
+            });
             // Write-through (0.19.1, review P2): answering "started" promises a run another
             // plane can read, so the row reaches the index before this resolves. `persist()`
             // warns instead of throwing, so an unwritable home cannot withhold the handle.
             await persist();
-            return { id, kind, signal: controller.signal, startedAt };
+            return {
+                id,
+                kind,
+                signal: controller.signal,
+                startedAt,
+                ...(seed?.command !== undefined ? { command: seed.command } : {}),
+                ...(seed?.parentRunId !== undefined ? { parentRunId: seed.parentRunId } : {}),
+            };
+        },
+        async stage(id, stage, progress) {
+            const row = owned.get(id);
+            if (row === undefined || row.state !== 'running')
+                return;
+            row.stage = stage;
+            if (progress !== undefined)
+                row.progress = { done: progress.done, total: progress.total };
+            await persist();
+        },
+        async supersede(ids) {
+            let changed = false;
+            for (const id of new Set(ids)) {
+                const row = owned.get(id);
+                if (row === undefined || row.supersededAt !== undefined)
+                    continue;
+                row.supersededAt = now();
+                changed = true;
+            }
+            if (changed)
+                await persist();
+        },
+        async supersedeKind(kind) {
+            let marked = 0;
+            await transactIo(options.io, path, (current) => {
+                const onDisk = parseIndex(current);
+                const merged = new Map();
+                for (const row of onDisk.records)
+                    merged.set(row.id, row);
+                for (const [id, row] of owned)
+                    merged.set(id, row);
+                for (const row of merged.values()) {
+                    if (row.kind !== kind || row.supersededAt !== undefined)
+                        continue;
+                    row.supersededAt = now();
+                    marked += 1;
+                }
+                const kept = capped([...merged.values()]);
+                const live = kept.filter(row => row.state === 'running');
+                const done = kept.filter(row => TERMINAL.has(row.state));
+                return JSON.stringify({ schemaVersion: RUNS_SCHEMA_VERSION, runs: [...live, ...done, ...onDisk.foreign] }, null, 2);
+            });
+            return marked;
         },
         async settle(id, outcome) {
             const row = owned.get(id);
@@ -297,17 +374,14 @@ export function newRunRegistry(options) {
             controllers.delete(id);
             await persist();
         },
-        // The registry tracks ONE kind today (`RunKind` = 'maintain'), so these reads take no
-        // kind filter — a comparison the type system already knows is true. Re-add the
-        // parameter (and the filter) together with the second `RunKind` member.
-        inFlight() {
-            return view().find(row => row.state === 'running');
+        inFlight(kind) {
+            return view().find(row => row.state === 'running' && (kind === undefined || row.kind === kind));
         },
-        lastSettledAt() {
-            return view().find(row => TERMINAL.has(row.state))?.endedAt;
+        lastSettledAt(kind) {
+            return view().find(row => TERMINAL.has(row.state) && (kind === undefined || row.kind === kind))?.endedAt;
         },
-        runs() {
-            return capped(view());
+        runs(kind) {
+            return kind === undefined ? capped(view()) : capped(view().filter(row => row.kind === kind));
         },
         find(id) {
             return owned.get(id) ?? foreign.get(id);

package/lib/types/skill-history.d.ts

@@ -296,7 +296,7 @@ export declare function loadVersionContent(root: string, io: EvolutionIoLike, na
  */
 export declare function recordVersions(root: string, io: EvolutionIoLike, input: VersionRecordInput, keep: number): Promise<RecordedVersions | null>;
 /** What kind of change one recorded version carries, as a CLOSED set. */
-export type VersionActionKind = 'baseline' | 'create' | 'patch' | 'update' | 'restore' | 'delete' | 'archive' | 'consolidate' | 'restructure' | 'support-write' | 'support-remove' | 'other';
+export type VersionActionKind = 'baseline' | 'create' | 'patch' | 'update' | 'restore' | 'delete' | 'archive' | 'consolidate' | 'restructure' | 'merge' | 'support-write' | 'support-remove' | 'other';
 /**
  * Classify one version action for display. Fail-closed like {@link versionTarget}: an action this
  * module does not know reads as `other` rather than being guessed, and `tests/skill-history.spec.ts`