open-multi-agent-kit 0.91.0 → 0.93.0

package/examples/extensions/subagent/adaptive-agent-runtime.ts

@@ -0,0 +1,240 @@
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+	attemptOutcome,
+	createBaseResult,
+	finalizeResult,
+	mergeForUpdate,
+	mergeResult,
+	parseProviderModel,
+	resultOutput,
+} from "./adaptive-result.ts";
+import {
+	buildCheckpointTask,
+	checkpointMadeProgress,
+	createCheckpointWorkspace,
+	createEmptyCheckpoint,
+	readCheckpoint,
+	removeCheckpointWorkspace,
+	writeCheckpoint,
+} from "./checkpoint-runtime.ts";
+import {
+	allocateAttemptBudget,
+	type DeadlineProfile,
+	type ExecutionBudget,
+	estimateTaskDemand,
+	planTaskShards,
+	recommendAttemptCutoff,
+	remainingExecutionMs,
+} from "./deadline-budget.ts";
+import type { DeadlineProfileStore } from "./deadline-profile-store.ts";
+import type {
+	DeadlineAttemptMetadata,
+	DeadlineOutcome,
+	SingleResult,
+	SubagentAttemptResult,
+} from "./subagent-runtime-types.ts";
+
+export interface RunAttemptInput {
+	readonly logicalTask: string;
+	readonly task: string;
+	readonly cutoffMs: number;
+	readonly attempt: number;
+	readonly shardId: string;
+	readonly shardIndex: number;
+	readonly shardCount: number;
+	readonly checkpointFilePath: string;
+	readonly onUpdate?: (partial: SingleResult) => void;
+}
+
+interface AdaptiveRuntimePolicy {
+	readonly fallbackAttemptMs: number;
+	readonly minimumAttemptMs: number;
+	readonly maxTokensPerShard: number;
+}
+
+interface RunAdaptiveAgentOptions {
+	readonly agentName: string;
+	readonly agentSource: "user" | "project";
+	readonly logicalTask: string;
+	readonly model?: string;
+	readonly step?: number;
+	readonly signal?: AbortSignal;
+	readonly budget: ExecutionBudget;
+	readonly pendingSequentialTasks: number;
+	readonly checkpointPrefix?: string;
+	readonly profileStore: DeadlineProfileStore;
+	readonly policy: AdaptiveRuntimePolicy;
+	readonly onUpdate?: (partial: SingleResult) => void;
+	readonly runAttempt: (input: RunAttemptInput) => Promise<SubagentAttemptResult>;
+}
+
+export async function runAdaptiveAgent(options: RunAdaptiveAgentOptions): Promise<SingleResult> {
+	const startedAtMs = Date.now();
+	let identity = parseProviderModel(options.model);
+	let profile = await options.profileStore.profileFor(identity.provider, identity.model);
+	const initialCutoff = cutoffFor(profile, options, remainingExecutionMs(options.budget));
+	const demand = estimateTaskDemand(options.logicalTask);
+	const shards = planTaskShards(options.logicalTask, demand, {
+		attemptCutoffMs: initialCutoff,
+		maxTaskShards: options.budget.maxTaskShards,
+		maxTokensPerShard: options.policy.maxTokensPerShard,
+	});
+	const taskAllocation = allocateAttemptBudget({
+		budget: options.budget,
+		pendingSequentialTasks: options.pendingSequentialTasks,
+		pendingShards: 1,
+		recommendedCutoffMs: remainingExecutionMs(options.budget),
+		minimumAttemptMs: 1,
+	});
+	const taskBudget: ExecutionBudget = {
+		...options.budget,
+		hardDeadlineMs: Math.max(1, taskAllocation.taskDeadlineAtMs - startedAtMs),
+		deadlineAtMs: Math.min(options.budget.deadlineAtMs, taskAllocation.taskDeadlineAtMs),
+	};
+	const aggregate = createBaseResult(options);
+	const attempts: DeadlineAttemptMetadata[] = [];
+	const completedShardIds: string[] = [];
+	let resumeCount = 0;
+	let duplicateResumeBlocked = false;
+	let lastCheckpoint: Awaited<ReturnType<typeof readCheckpoint>> | undefined;
+	let terminalOutcome: DeadlineOutcome = "budget-exhausted";
+	const checkpointPrefix = options.checkpointPrefix ?? path.join(os.tmpdir(), "omk-subagent-checkpoint-");
+	const workspace = await createCheckpointWorkspace(checkpointPrefix);
+
+	try {
+		outer: for (const shard of shards) {
+			let shardAttempt = 0;
+			let shardMessageCount = 0;
+			let checkpoint: typeof lastCheckpoint;
+			while (true) {
+				const pendingShards = shards.length - completedShardIds.length;
+				const recommended = cutoffFor(profile, options, remainingExecutionMs(taskBudget));
+				const allocation = allocateAttemptBudget({
+					budget: taskBudget,
+					pendingSequentialTasks: 1,
+					pendingShards,
+					recommendedCutoffMs: recommended,
+					minimumAttemptMs: options.policy.minimumAttemptMs,
+				});
+				if (allocation.cutoffMs === 0 || options.signal?.aborted) {
+					terminalOutcome = options.signal?.aborted ? "aborted" : "budget-exhausted";
+					break outer;
+				}
+
+				const attemptNumber = shardAttempt + 1;
+				const task = buildCheckpointTask({
+					originalTask: options.logicalTask,
+					shardTask: shard.task,
+					shardId: shard.id,
+					shardIndex: shard.index,
+					shardCount: shards.length,
+					attempt: attemptNumber,
+					cutoffMs: allocation.cutoffMs,
+					checkpointFilePath: workspace.filePath,
+					...(checkpoint === undefined ? {} : { checkpoint }),
+				});
+				const attempt = await options.runAttempt({
+					logicalTask: options.logicalTask,
+					task,
+					cutoffMs: allocation.cutoffMs,
+					attempt: attemptNumber,
+					shardId: shard.id,
+					shardIndex: shard.index,
+					shardCount: shards.length,
+					checkpointFilePath: workspace.filePath,
+					onUpdate: options.onUpdate
+						? (partial) => options.onUpdate?.(mergeForUpdate(aggregate, partial))
+						: undefined,
+				});
+				mergeResult(aggregate, attempt.result);
+				shardMessageCount += attempt.result.messages.length;
+				const outcome = attemptOutcome(attempt);
+				const observedIdentity = parseProviderModel(attempt.result.model ?? options.model);
+				if (observedIdentity.provider !== identity.provider || observedIdentity.model !== identity.model) {
+					identity = observedIdentity;
+					profile = await options.profileStore.profileFor(identity.provider, identity.model);
+				}
+				try {
+					profile = await options.profileStore.record({
+						provider: identity.provider,
+						model: identity.model,
+						outcome,
+						elapsedMs: attempt.process.elapsedMs,
+						estimatedTokens: demand.estimatedTokens,
+						workUnits: demand.workUnits,
+					});
+				} catch {
+					profile = await options.profileStore.profileFor(identity.provider, identity.model);
+				}
+				lastCheckpoint = await readCheckpoint(workspace.filePath, {
+					messageCount: shardMessageCount,
+					outputTail: resultOutput(attempt.result),
+					lastEventAtMs: Date.now(),
+				});
+				attempts.push({
+					attempt: attemptNumber,
+					shardId: shard.id,
+					cutoffMs: allocation.cutoffMs,
+					elapsedMs: attempt.process.elapsedMs,
+					outcome,
+					exitCode: attempt.result.exitCode,
+					messageCount: attempt.result.messages.length,
+					processReason: attempt.process.reason,
+					cleanup: attempt.process.cleanup,
+				});
+
+				if (outcome === "completed") {
+					completedShardIds.push(shard.id);
+					terminalOutcome = "completed";
+					checkpoint = undefined;
+					await writeCheckpoint(workspace.filePath, createEmptyCheckpoint());
+					continue outer;
+				}
+				terminalOutcome = outcome;
+				if (outcome !== "cutoff" || resumeCount >= taskBudget.maxResumeAttempts) break outer;
+				if (!checkpointMadeProgress(checkpoint, lastCheckpoint)) {
+					duplicateResumeBlocked = true;
+					break outer;
+				}
+				checkpoint = lastCheckpoint;
+				shardAttempt += 1;
+				resumeCount += 1;
+			}
+		}
+	} finally {
+		await removeCheckpointWorkspace(workspace);
+	}
+
+	const remainingShardIds = shards.map((shard) => shard.id).filter((id) => !completedShardIds.includes(id));
+	if (remainingShardIds.length === 0) terminalOutcome = "completed";
+	finalizeResult(aggregate, terminalOutcome);
+	aggregate.deadline = {
+		outcome: terminalOutcome,
+		startedAtMs,
+		elapsedMs: Date.now() - startedAtMs,
+		hardDeadlineMs: taskBudget.hardDeadlineMs,
+		estimatedTokens: demand.estimatedTokens,
+		workUnits: demand.workUnits,
+		predictedMs: demand.predictedMs,
+		plannedShardIds: shards.map((shard) => shard.id),
+		completedShardIds,
+		remainingShardIds,
+		resumeCount,
+		duplicateResumeBlocked,
+		provider: identity.provider,
+		model: identity.model,
+		profileSamples: profile?.samples ?? 0,
+		attempts,
+		...(lastCheckpoint === undefined ? {} : { checkpoint: lastCheckpoint }),
+	};
+	return aggregate;
+}
+
+function cutoffFor(profile: DeadlineProfile | undefined, options: RunAdaptiveAgentOptions, maximumMs: number): number {
+	return recommendAttemptCutoff(profile, {
+		fallbackMs: options.policy.fallbackAttemptMs,
+		minimumMs: Math.min(options.policy.minimumAttemptMs, maximumMs),
+		maximumMs: Math.max(1, maximumMs),
+	});
+}

package/examples/extensions/subagent/adaptive-result.ts

@@ -0,0 +1,112 @@
+import type { Message } from "omk-ai";
+import {
+	type DeadlineOutcome,
+	emptyUsage,
+	type SingleResult,
+	type SubagentAttemptResult,
+	type UsageStats,
+} from "./subagent-runtime-types.ts";
+
+interface BaseResultOptions {
+	readonly agentName: string;
+	readonly agentSource: "user" | "project";
+	readonly logicalTask: string;
+	readonly model?: string;
+	readonly step?: number;
+}
+
+export function createBaseResult(options: BaseResultOptions): SingleResult {
+	return {
+		agent: options.agentName,
+		agentSource: options.agentSource,
+		task: options.logicalTask,
+		exitCode: 0,
+		messages: [],
+		stderr: "",
+		usage: emptyUsage(),
+		model: options.model,
+		step: options.step,
+	};
+}
+
+export function attemptOutcome(attempt: SubagentAttemptResult): Exclude<DeadlineOutcome, "budget-exhausted"> {
+	if (attempt.process.reason === "cutoff") return "cutoff";
+	if (attempt.process.reason === "aborted") return "aborted";
+	return attempt.result.exitCode === 0 && attempt.result.stopReason !== "error" ? "completed" : "failed";
+}
+
+export function mergeResult(target: SingleResult, source: SingleResult): void {
+	target.messages.push(...source.messages);
+	target.stderr = [target.stderr, source.stderr].filter(Boolean).join("\n");
+	target.usage = mergeUsage(target.usage, source.usage);
+	target.output = mergeOutput(target.output ?? "", resultOutput(source));
+	target.exitCode = source.exitCode;
+	target.stopReason = source.stopReason;
+	target.errorMessage = source.errorMessage;
+	target.model = source.model ?? target.model;
+}
+
+export function mergeForUpdate(base: SingleResult, partial: SingleResult): SingleResult {
+	const merged: SingleResult = { ...base, messages: [...base.messages], usage: { ...base.usage } };
+	mergeResult(merged, partial);
+	return merged;
+}
+
+export function resultOutput(result: SingleResult): string {
+	if (result.output !== undefined) return result.output;
+	for (let index = result.messages.length - 1; index >= 0; index--) {
+		const message: Message = result.messages[index];
+		if (message.role !== "assistant") continue;
+		for (const part of message.content) if (part.type === "text") return part.text;
+	}
+	return "";
+}
+
+export function finalizeResult(result: SingleResult, outcome: DeadlineOutcome): void {
+	if (outcome === "completed") {
+		result.exitCode = 0;
+		result.stopReason = "end";
+		result.errorMessage = undefined;
+		return;
+	}
+	if (outcome === "failed") {
+		result.exitCode = Math.max(1, result.exitCode);
+		result.stopReason = "error";
+		result.errorMessage ??= "Subagent process failed";
+		return;
+	}
+	result.exitCode = outcome === "aborted" ? 130 : 124;
+	result.stopReason = outcome === "aborted" ? "aborted" : "deadline";
+	result.errorMessage ??=
+		outcome === "budget-exhausted" ? "Subagent execution budget exhausted" : "Subagent deadline cutoff";
+}
+
+export function parseProviderModel(value: string | undefined): { provider: string; model: string } {
+	if (!value) return { provider: "unknown", model: "default" };
+	const separator = value.indexOf("/");
+	return separator < 1
+		? { provider: "unknown", model: value }
+		: { provider: value.slice(0, separator), model: value.slice(separator + 1) || "default" };
+}
+
+function mergeUsage(left: UsageStats, right: UsageStats): UsageStats {
+	return {
+		input: left.input + right.input,
+		output: left.output + right.output,
+		cacheRead: left.cacheRead + right.cacheRead,
+		cacheWrite: left.cacheWrite + right.cacheWrite,
+		cost: left.cost + right.cost,
+		contextTokens: Math.max(left.contextTokens, right.contextTokens),
+		turns: left.turns + right.turns,
+	};
+}
+
+function mergeOutput(left: string, right: string): string {
+	if (right === "" || left === right || left.endsWith(right)) return left;
+	if (left === "") return right;
+	const maxOverlap = Math.min(left.length, right.length, 4_096);
+	for (let overlap = maxOverlap; overlap > 0; overlap--) {
+		if (left.endsWith(right.slice(0, overlap))) return `${left}${right.slice(overlap)}`;
+	}
+	return `${left}\n\n${right}`;
+}

package/examples/extensions/subagent/agents.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Unit tests for `parseEnforceFlag` coercion in agents discovery.
+ *
+ * Regression: 2026-07-26 — YAML boolean `enforceCapabilities: true` was
+ * silently ignored because the parser only accepted the string "true". These
+ * tests pin coercion behavior for boolean/number/string/garbage inputs via
+ * real `discoverAgents` against a temp agents dir (no I/O mocks, no LLM).
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { discoverAgents } from "./agents.ts";
+
+const tmpDirs: string[] = [];
+
+function agent(name: string, fm: string): string {
+	return `---\nname: ${name}\ndescription: test agent\ntools: read\n${fm}\n---\nbody\n`;
+}
+
+// discoverAgents(cwd, scope) resolves the user dir from OMK_CODING_AGENT_DIR.
+// Point it at our temp dir via env so no real agent tree is touched.
+function withAgentDir(dir: string, fn: () => ReturnType<typeof discoverAgents>) {
+	const prev = process.env.OMK_CODING_AGENT_DIR;
+	process.env.OMK_CODING_AGENT_DIR = path.dirname(dir); // parent contains "agents"
+	try {
+		return fn();
+	} finally {
+		if (prev === undefined) delete process.env.OMK_CODING_AGENT_DIR;
+		else process.env.OMK_CODING_AGENT_DIR = prev;
+	}
+}
+
+afterEach(() => {
+	for (const dir of tmpDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe("parseEnforceFlag coercion (via discoverAgents)", () => {
+	const cases: Array<[string, string, boolean | undefined]> = [
+		["yaml-bool-true", "enforceCapabilities: true", true],
+		["yaml-bool-false", "enforceCapabilities: false", false],
+		["num-1", "enforceCapabilities: 1", true],
+		["num-0", "enforceCapabilities: 0", false],
+		["str-yes", "enforceCapabilities: yes", true],
+		["str-on", "enforceCapabilities: on", true],
+		["str-no", "enforceCapabilities: no", false],
+		["str-off", "enforceCapabilities: off", false],
+		["str-quoted-true", 'enforceCapabilities: "true"', true],
+		["str-quoted-false", 'enforceCapabilities: "false"', false],
+		["str-True-spaced", "enforceCapabilities: ' True '", true],
+		["garbage-num-2", "enforceCapabilities: 2", undefined],
+		["garbage-word", "enforceCapabilities: treu", undefined],
+		["garbage-empty", 'enforceCapabilities: ""', undefined],
+		["absent-key", "", undefined],
+	];
+
+	for (const [id, fm, expected] of cases) {
+		it(`${id} → ${String(expected)}`, () => {
+			const parent = fs.mkdtempSync(path.join(os.tmpdir(), "omk-agent-dir-"));
+			tmpDirs.push(parent);
+			const agentsDir = path.join(parent, "agents");
+			fs.mkdirSync(agentsDir);
+			fs.writeFileSync(path.join(agentsDir, `${id}.md`), agent(id, fm), "utf-8");
+
+			const result = withAgentDir(agentsDir, () => discoverAgents(process.cwd(), "user"));
+			const found = result.agents.find((a) => a.name === id);
+			expect(found, `agent ${id} discovered`).toBeDefined();
+			expect(found?.enforceCapabilities).toBe(expected);
+		});
+	}
+
+	it("fail-closed: garbage input never enables enforcement", () => {
+		const parent = fs.mkdtempSync(path.join(os.tmpdir(), "omk-agent-dir-"));
+		tmpDirs.push(parent);
+		const agentsDir = path.join(parent, "agents");
+		fs.mkdirSync(agentsDir);
+		for (const bad of ["treu", "2", '"  "', "[true]", "~"]) {
+			const name = `bad-${bad.replace(/[^a-z0-9]/gi, "")}`;
+			fs.writeFileSync(path.join(agentsDir, `${name}.md`), agent(name, `enforceCapabilities: ${bad}`), "utf-8");
+		}
+		const result = withAgentDir(agentsDir, () => discoverAgents(process.cwd(), "user"));
+		for (const a of result.agents) {
+			expect(a.enforceCapabilities, `${a.name} must not enable on garbage`).not.toBe(true);
+		}
+	});
+});

package/examples/extensions/subagent/agents.ts

@@ -29,6 +29,23 @@ export interface AgentDiscoveryResult {
 	projectAgentsDir: string | null;
 }
 
+/** Coerce frontmatter enforceCapabilities (boolean | string | unknown) to boolean|undefined. */
+function parseEnforceFlag(value: unknown): boolean | undefined {
+	if (typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (value === 1) return true;
+		if (value === 0) return false;
+		return undefined;
+	}
+	if (typeof value === "string") {
+		const v = value.trim().toLowerCase();
+		if (v === "true" || v === "1" || v === "yes" || v === "on") return true;
+		if (v === "false" || v === "0" || v === "no" || v === "off") return false;
+		return undefined;
+	}
+	return undefined;
+}
+
 function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
@@ -67,10 +84,7 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			.filter(Boolean);
 
 		const capabilities = parseCapabilities(frontmatter);
-		const enforceCapabilities =
-			typeof frontmatter.enforceCapabilities === "string"
-				? frontmatter.enforceCapabilities.trim().toLowerCase() === "true"
-				: undefined;
+		const enforceCapabilities = parseEnforceFlag(frontmatter.enforceCapabilities);
 
 		agents.push({
 			name: frontmatter.name,

package/examples/extensions/subagent/capabilities.ts

@@ -69,16 +69,19 @@ export const VALID_HOOKS: readonly string[] = [
 ];
 
 /**
- * Compiled-in MCP server set — the 18 configured servers sourced from the MCP
+ * Compiled-in MCP server set — live OMK MCP ids (mcp.json + known optional servers) sourced from the MCP
  * configuration. This list MUST be updated if the runtime MCP set changes.
  */
 export const VALID_MCP: readonly string[] = [
 	"adaptorch",
+	"adaptorch-mcp",
+	"blender-mcp",
 	"chrome-devtools",
 	"context7",
 	"fetch",
 	"filesystem",
 	"firecrawl",
+	"ghidra",
 	"github",
 	"lean-ctx",
 	"memory",
@@ -88,6 +91,7 @@ export const VALID_MCP: readonly string[] = [
 	"serena",
 	"supermemory",
 	"understand-anything",
+	"unity-mcp",
 	"zai-reader",
 	"zai-vision",
 	"zai-zread",
@@ -180,6 +184,16 @@ function addSkillsFromRoot(root: string, skills: Map<string, string>): void {
 	entries.sort();
 	for (const rel of entries) {
 		if (path.basename(rel) !== SKILL_FILE_NAME) continue;
+		// Skip archived/corpus trees — they collide with real skill names (e.g. code-review).
+		const relPosix = rel.split(path.sep).join("/");
+		if (
+			relPosix.includes("system-prompts-leaks/") ||
+			relPosix.includes("/corpus/") ||
+			relPosix.includes("node_modules/") ||
+			relPosix.includes("/.git/")
+		) {
+			continue;
+		}
 		const abs = path.resolve(root, rel);
 		let stat: fs.Stats;
 		try {

package/examples/extensions/subagent/checkpoint-runtime.test.ts

@@ -0,0 +1,125 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	buildCheckpointTask,
+	checkpointMadeProgress,
+	createCheckpointWorkspace,
+	readCheckpoint,
+	removeCheckpointWorkspace,
+} from "./checkpoint-runtime.ts";
+
+const cleanupPaths: string[] = [];
+
+afterEach(async () => {
+	await Promise.all(cleanupPaths.splice(0).map((entry) => fs.promises.rm(entry, { force: true, recursive: true })));
+});
+
+describe("subagent checkpoint runtime", () => {
+	it("loads a bounded, typed checkpoint written by a child", async () => {
+		const workspace = await createCheckpointWorkspace(path.join(os.tmpdir(), "omk-checkpoint-test-"));
+		cleanupPaths.push(workspace.dir);
+		await fs.promises.writeFile(
+			workspace.filePath,
+			JSON.stringify({
+				version: 1,
+				completed: ["inspect boundary"],
+				remaining: ["add tests"],
+				summary: "boundary inspected",
+				artifacts: ["src/runtime.ts"],
+			}),
+			"utf8",
+		);
+
+		const checkpoint = await readCheckpoint(workspace.filePath, {
+			messageCount: 3,
+			outputTail: "stream tail",
+			lastEventAtMs: 123,
+		});
+
+		expect(checkpoint).toMatchObject({
+			completed: ["inspect boundary"],
+			remaining: ["add tests"],
+			summary: "boundary inspected",
+			artifacts: ["src/runtime.ts"],
+			messageCount: 3,
+			outputTail: "stream tail",
+			lastEventAtMs: 123,
+		});
+	});
+
+	it("rejects a checkpoint path replaced with a symbolic link", async () => {
+		const workspace = await createCheckpointWorkspace(path.join(os.tmpdir(), "omk-checkpoint-symlink-"));
+		cleanupPaths.push(workspace.dir);
+		const targetPath = path.join(workspace.dir, "target.json");
+		await fs.promises.writeFile(
+			targetPath,
+			JSON.stringify({ version: 1, completed: ["untrusted target"], remaining: [], summary: "leak", artifacts: [] }),
+			"utf8",
+		);
+		await fs.promises.rm(workspace.filePath);
+		await fs.promises.symlink(targetPath, workspace.filePath);
+
+		const checkpoint = await readCheckpoint(workspace.filePath, {
+			messageCount: 0,
+			outputTail: "",
+			lastEventAtMs: 0,
+		});
+
+		expect(checkpoint.completed).toEqual([]);
+		expect(checkpoint.summary).toBe("");
+	});
+
+	it("builds a bounded resume prompt that forbids replaying completed side effects", () => {
+		const hugeTail = `old-output-${"x".repeat(20_000)}`;
+		const prompt = buildCheckpointTask({
+			originalTask: "Implement the deadline runtime.",
+			shardTask: "Add the process cleanup path.",
+			shardId: "shard-2",
+			shardIndex: 1,
+			shardCount: 3,
+			attempt: 2,
+			cutoffMs: 30_000,
+			checkpointFilePath: "/tmp/checkpoint.json",
+			checkpoint: {
+				version: 1,
+				completed: ["sent SIGTERM"],
+				remaining: ["verify SIGKILL"],
+				summary: "graceful termination implemented",
+				artifacts: ["process-runtime.ts"],
+				messageCount: 4,
+				outputTail: hugeTail,
+				lastEventAtMs: 100,
+			},
+		});
+
+		expect(prompt).toContain("Do not repeat completed side effects");
+		expect(prompt).toContain("sent SIGTERM");
+		expect(prompt).toContain("verify SIGKILL");
+		expect(prompt).toContain("Only unresolved checkpoint units");
+		expect(prompt).not.toContain("Add the process cleanup path.");
+		expect(prompt.length).toBeLessThan(12_000);
+	});
+
+	it("blocks duplicate resume when neither checkpoint nor streamed evidence advanced", () => {
+		const before = {
+			version: 1 as const,
+			completed: ["a"],
+			remaining: ["b"],
+			summary: "same",
+			artifacts: [],
+			messageCount: 2,
+			outputTail: "same tail",
+			lastEventAtMs: 10,
+		};
+		expect(checkpointMadeProgress(before, { ...before })).toBe(false);
+		expect(checkpointMadeProgress(before, { ...before, messageCount: 3 })).toBe(true);
+	});
+
+	it("removes checkpoint artifacts after the logical task settles", async () => {
+		const workspace = await createCheckpointWorkspace(path.join(os.tmpdir(), "omk-checkpoint-cleanup-"));
+		await removeCheckpointWorkspace(workspace);
+		expect(fs.existsSync(workspace.dir)).toBe(false);
+	});
+});