@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/cli/index.ts

@@ -57,14 +57,15 @@ Usage:
   clio-coder uninstall            remove all Clio Coder state; --remove-binary also unlinks the launcher
   clio-coder upgrade              upgrade Clio Coder and run pending migrations
   clio-coder agents               list discovered agent recipes
-  clio-coder fleet list|run|status|drain|resume  fleet contracts, status, and admission control
+  clio-coder fleet new|validate|graph|commands|run|status|drain|resume  fleet authoring, execution, status, and admission control
   clio-coder evidence             build, list, or inspect evidence artifacts
   clio-coder eval                 run, report, or compare local eval task files
-  clio-coder memory               list, propose, approve, reject, or prune memory
+  clio-coder memory               list, propose, promote, approve, reject, or prune memory
   clio-coder usage report         cross-session usage facts and opportunities (experimental)
   clio-coder trace                query or view the durable dispatch trace mirror
   clio-coder extensions           install, list, enable, disable, or remove extension packages
   clio-coder skills               list, inspect, validate, or install skills
+  clio-coder library              list, search, add, or sync agents, prompts, fleets, and skills from catalogs
   clio-coder verifiers            discover, author, validate, edit, or dry-run project checks
   clio-coder docs [topic]         serve the HTML docs of a source checkout on 127.0.0.1 (--no-open to skip browser)
   clio-coder dev <command>        harness instruments; run 'clio-coder dev' for the list
@@ -246,6 +247,7 @@ const COMMAND_HANDLERS = new Map<string, CommandHandler>([
 	["ext", extensionsCommand],
 	["fleet", async (subArgs) => (await import("./fleet.js")).runFleetCommand(subArgs)],
 	["skills", async (subArgs) => (await import("./skills.js")).runSkillsCommand(subArgs)],
+	["library", async (subArgs) => (await import("./library.js")).runLibraryCommand(subArgs)],
 	["verifiers", async (subArgs) => (await import("./verifiers.js")).runVerifiersCommand(subArgs)],
 	["docs", async (subArgs) => (await import("./docs.js")).runDocsCommand(subArgs)],
 	["share", async (subArgs) => (await import("./share.js")).runShareCommand(subArgs)],

package/src/cli/library.ts

@@ -0,0 +1,190 @@
+import {
+	classifyLibraryRequirements,
+	confirmLibraryRemote,
+	discoverLibrary,
+	installLibraryPlan,
+	type LibraryEntry,
+	type LibraryEntryKind,
+	libraryEntryRef,
+	libraryInstallPath,
+	planLibraryInstall,
+	syncLibrary,
+} from "../domains/resources/index.js";
+import { printError, printOk } from "./shared.js";
+
+const KINDS = new Set<LibraryEntryKind>(["skill", "agent", "prompt", "fleet"]);
+const HELP = `clio-coder library <command>
+
+Commands:
+  clio-coder library list [--kind <kind>] [--json]
+  clio-coder library search <query> [--kind <kind>] [--json]
+  clio-coder library add <ref> [--from <catalog|path>] [--with-requirements] [--yes] [--json]
+  clio-coder library use <kind> <name>
+  clio-coder library sync
+  clio-coder library push
+  clio-coder library remote confirm <url>
+`;
+
+interface Parsed {
+	command?: string;
+	positional: string[];
+	kind?: LibraryEntryKind;
+	from?: string;
+	json: boolean;
+	yes: boolean;
+	withRequirements: boolean;
+	help: boolean;
+}
+
+function parse(argv: ReadonlyArray<string>): Parsed {
+	const out: Parsed = { positional: [], json: false, yes: false, withRequirements: false, help: false };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (!arg) continue;
+		if (!out.command && !arg.startsWith("-")) {
+			out.command = arg;
+			continue;
+		}
+		if (arg === "--json") out.json = true;
+		else if (arg === "--yes") out.yes = true;
+		else if (arg === "--with-requirements") out.withRequirements = true;
+		else if (arg === "--help" || arg === "-h") out.help = true;
+		else if (arg === "--kind") {
+			const value = argv[++i];
+			if (!value || !KINDS.has(value as LibraryEntryKind))
+				throw new Error("--kind requires skill, agent, prompt, or fleet");
+			out.kind = value as LibraryEntryKind;
+		} else if (arg === "--from") {
+			const value = argv[++i];
+			if (!value) throw new Error("--from requires a value");
+			out.from = value;
+		} else if (arg.startsWith("-")) throw new Error(`unknown flag: ${arg}`);
+		else out.positional.push(arg);
+	}
+	return out;
+}
+
+function selectEntry(entries: ReadonlyArray<LibraryEntry>, ref: string): LibraryEntry {
+	const matches = ref.includes(":")
+		? entries.filter((entry) => libraryEntryRef(entry) === ref)
+		: entries.filter((entry) => entry.name === ref);
+	if (matches.length === 0) throw new Error(`library entry not found: ${ref}`);
+	if (matches.length > 1)
+		throw new Error(`library entry is ambiguous; use a typed reference: ${matches.map(libraryEntryRef).join(", ")}`);
+	return matches[0] as LibraryEntry;
+}
+
+function filtered(entries: ReadonlyArray<LibraryEntry>, kind?: LibraryEntryKind): LibraryEntry[] {
+	return entries.filter((entry) => kind === undefined || entry.kind === kind);
+}
+
+export async function runLibraryCommand(argv: ReadonlyArray<string>): Promise<number> {
+	let parsed: Parsed;
+	try {
+		parsed = parse(argv);
+	} catch (error) {
+		printError(error instanceof Error ? error.message : String(error));
+		return 2;
+	}
+	if (!parsed.command || parsed.help) {
+		process.stdout.write(HELP);
+		return parsed.help ? 0 : 2;
+	}
+	try {
+		if (parsed.command === "list" || parsed.command === "search") {
+			const discovery = discoverLibrary();
+			const query = parsed.command === "search" ? parsed.positional.join(" ").trim().toLowerCase() : "";
+			if (parsed.command === "search" && !query) throw new Error("library search requires a query");
+			const entries = filtered(discovery.entries, parsed.kind).filter(
+				(entry) => !query || entry.name.toLowerCase().includes(query) || entry.description.toLowerCase().includes(query),
+			);
+			if (parsed.json)
+				process.stdout.write(`${JSON.stringify({ entries, diagnostics: discovery.diagnostics }, null, 2)}\n`);
+			else
+				for (const entry of entries) process.stdout.write(`${libraryEntryRef(entry).padEnd(28)} ${entry.description}\n`);
+			return 0;
+		}
+		if (parsed.command === "add") {
+			const ref = parsed.positional[0];
+			if (!ref || parsed.positional.length !== 1) throw new Error("library add requires one reference");
+			const catalog = parsed.from && parsed.from !== "catalog" ? parsed.from : undefined;
+			const discovery = discoverLibrary(catalog ? { catalog } : {});
+			let entry: LibraryEntry;
+			try {
+				entry = selectEntry(discovery.entries, ref);
+			} catch (error) {
+				const refusal = ref.includes(":")
+					? discovery.refusals[ref]
+					: Object.entries(discovery.refusals).find(([key]) => key.endsWith(`:${ref}`))?.[1];
+				if (refusal) throw new Error(refusal);
+				throw error;
+			}
+			const requirements = classifyLibraryRequirements(entry, discovery.entries);
+			if (requirements.unsatisfied.length > 0 && !parsed.withRequirements) {
+				const refs = requirements.unsatisfied.map(libraryEntryRef);
+				if (parsed.json)
+					process.stdout.write(
+						`${JSON.stringify({ ok: false, entry: libraryEntryRef(entry), satisfiedRequirements: requirements.satisfied.map(libraryEntryRef), unresolvedRequirements: refs }, null, 2)}\n`,
+					);
+				else
+					process.stderr.write(
+						`satisfied requirements: ${requirements.satisfied.length > 0 ? requirements.satisfied.map(libraryEntryRef).join(", ") : "none"}\nunresolved requirements: ${refs.join(", ")}\npass --with-requirements to install them in dependency order\n`,
+					);
+				return 1;
+			}
+			const plans = [...(parsed.withRequirements ? requirements.unsatisfied : []), entry].map(planLibraryInstall);
+			if (parsed.json)
+				process.stdout.write(
+					`${JSON.stringify({ ok: true, confirmed: parsed.yes, satisfiedRequirements: requirements.satisfied.map(libraryEntryRef), writes: plans.map((plan) => ({ ref: libraryEntryRef(plan.entry), path: plan.path, sha256: plan.sha256 })) }, null, 2)}\n`,
+				);
+			else {
+				process.stdout.write("library add plan:\n");
+				process.stdout.write(
+					`  satisfied requirements: ${requirements.satisfied.length > 0 ? requirements.satisfied.map(libraryEntryRef).join(", ") : "none"}\n`,
+				);
+				for (const plan of plans)
+					process.stdout.write(`  ${libraryEntryRef(plan.entry)} -> ${plan.path} sha256 ${plan.sha256}\n`);
+			}
+			if (!parsed.yes) return 0;
+			for (const plan of plans) installLibraryPlan(plan);
+			if (!parsed.json) printOk(`installed ${plans.length} library entry or entries`);
+			return 0;
+		}
+		if (parsed.command === "use") {
+			const kind = parsed.positional[0] as LibraryEntryKind | undefined;
+			const name = parsed.positional[1];
+			if (!kind || !KINDS.has(kind) || !name || parsed.positional.length !== 2)
+				throw new Error("library use requires a kind and name");
+			// A skill is loaded by the operator from the Skills Hub, never by a CLI
+			// verb, so the honest answer names where it lives and how to load it.
+			const output =
+				kind === "fleet"
+					? `clio-coder fleet run ${name}`
+					: kind === "agent"
+						? `/run ${name}`
+						: kind === "skill"
+							? `${libraryInstallPath({ kind, name })}\nload it from /skill in the TUI, or ask the model to call context(scope="skills")`
+							: name;
+			process.stdout.write(`${output}\n`);
+			return 0;
+		}
+		if (parsed.command === "remote") {
+			if (parsed.positional[0] !== "confirm" || !parsed.positional[1] || parsed.positional.length !== 2)
+				throw new Error("library remote confirm requires a URL");
+			confirmLibraryRemote(parsed.positional[1]);
+			printOk("confirmed library remote");
+			return 0;
+		}
+		if (parsed.command === "sync" || parsed.command === "push") {
+			await syncLibrary(parsed.command);
+			printOk(`library ${parsed.command} complete`);
+			return 0;
+		}
+		throw new Error(`unknown library command: ${parsed.command}`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		printError(message);
+		if (parsed.json) process.stdout.write(`${JSON.stringify({ ok: false, error: message }, null, 2)}\n`);
+		return 1;
+	}
+}

package/src/cli/memory.ts

@@ -1,36 +1,62 @@
+import { readFile, stat } from "node:fs/promises";
 import { clioDataDir } from "../core/xdg.js";
 import {
 	approveMemoryRecord,
+	canonicalMemoryRepositoryIdentity,
 	loadMemoryRecords,
 	type MemoryRecord,
+	type MemoryScopeSelection,
+	memoryAgentIdentity,
+	memoryRuntimeIdentity,
 	memoryStatus,
+	parseTaskMemoryHandoffSnapshot,
 	proposeMemoryFromEvidence,
+	proposeMemoryPromotion,
 	pruneStaleMemory,
+	type ReviewedTaskMemoryHandoffSnapshot,
 	rejectMemoryRecord,
+	type TaskMemoryHandoffEntry,
 } from "../domains/memory/index.js";
 import { printError, printOk } from "./shared.js";
 
 const HELP = `clio-coder memory list
-clio-coder memory propose --from-evidence <evidenceId>
+clio-coder memory propose --from-evidence <evidenceId> [scope options]
+clio-coder memory promote --from-handoff <path> [--entry <id>...] --scope <scope> [scope options]
 clio-coder memory approve <memoryId>
 clio-coder memory reject <memoryId>
 clio-coder memory prune --stale
 
 Manage scoped, approved, evidence-linked local memory records.
+
+Scope options:
+  --scope repo --repository <canonical-absolute-path>
+  --scope global --acknowledge-global
+  --scope runtime --runtime <source-runtime-id>
+  --scope agent --agent <source-agent-id>
+
+Omit scope options from propose to preserve evidence-inferred scope. Promotion
+always requires an explicit scope and creates unapproved records for review.
 `;
 
-type MemoryCommand = "list" | "propose" | "approve" | "reject" | "prune";
+type MemoryCommand = "list" | "propose" | "promote" | "approve" | "reject" | "prune";
 
 interface ParsedMemoryArgs {
 	command?: MemoryCommand;
 	evidenceId?: string;
+	handoffPath?: string;
+	entryIds: string[];
 	memoryId?: string;
+	scope?: "repo" | "global" | "runtime" | "agent";
+	repositoryPath?: string;
+	acknowledgeGlobal: boolean;
+	runtimeId?: string;
+	agentId?: string;
 	stale: boolean;
 	help: boolean;
 }
 
 function parseMemoryArgs(args: ReadonlyArray<string>): ParsedMemoryArgs {
-	const parsed: ParsedMemoryArgs = { stale: false, help: false };
+	const parsed: ParsedMemoryArgs = { entryIds: [], acknowledgeGlobal: false, stale: false, help: false };
 	for (let index = 0; index < args.length; index += 1) {
 		const arg = args[index];
 		if (arg === undefined) continue;
@@ -39,21 +65,70 @@ function parseMemoryArgs(args: ReadonlyArray<string>): ParsedMemoryArgs {
 			continue;
 		}
 		if (parsed.command === undefined) {
-			if (arg === "list" || arg === "propose" || arg === "approve" || arg === "reject" || arg === "prune") {
+			if (
+				arg === "list" ||
+				arg === "propose" ||
+				arg === "promote" ||
+				arg === "approve" ||
+				arg === "reject" ||
+				arg === "prune"
+			) {
 				parsed.command = arg;
 				continue;
 			}
 			throw new Error(`unknown memory command: ${arg}`);
 		}
-		if (parsed.command === "propose") {
+		if (parsed.command === "propose" || parsed.command === "promote") {
 			if (arg === "--from-evidence") {
+				if (parsed.command !== "propose") throw new Error("--from-evidence is valid only for memory propose");
 				const value = args[index + 1];
 				if (value === undefined || value.startsWith("-")) throw new Error("--from-evidence requires an evidence id");
 				parsed.evidenceId = value;
 				index += 1;
 				continue;
 			}
-			throw new Error(`unknown memory propose argument: ${arg}`);
+			if (arg === "--from-handoff") {
+				if (parsed.command !== "promote") throw new Error("--from-handoff is valid only for memory promote");
+				const value = requireOptionValue(args, index, "--from-handoff", "a path");
+				parsed.handoffPath = value;
+				index += 1;
+				continue;
+			}
+			if (arg === "--entry") {
+				if (parsed.command !== "promote") throw new Error("--entry is valid only for memory promote");
+				parsed.entryIds.push(requireOptionValue(args, index, "--entry", "an entry id"));
+				index += 1;
+				continue;
+			}
+			if (arg === "--scope") {
+				const value = requireOptionValue(args, index, "--scope", "repo, global, runtime, or agent");
+				if (value !== "repo" && value !== "global" && value !== "runtime" && value !== "agent") {
+					throw new Error("--scope requires repo, global, runtime, or agent");
+				}
+				parsed.scope = value;
+				index += 1;
+				continue;
+			}
+			if (arg === "--repository") {
+				parsed.repositoryPath = requireOptionValue(args, index, "--repository", "a canonical absolute path");
+				index += 1;
+				continue;
+			}
+			if (arg === "--acknowledge-global") {
+				parsed.acknowledgeGlobal = true;
+				continue;
+			}
+			if (arg === "--runtime") {
+				parsed.runtimeId = requireOptionValue(args, index, "--runtime", "a runtime id");
+				index += 1;
+				continue;
+			}
+			if (arg === "--agent") {
+				parsed.agentId = requireOptionValue(args, index, "--agent", "an agent id");
+				index += 1;
+				continue;
+			}
+			throw new Error(`unknown memory ${parsed.command} argument: ${arg}`);
 		}
 		if (parsed.command === "approve" || parsed.command === "reject") {
 			if (parsed.memoryId === undefined && !arg.startsWith("-")) {
@@ -72,20 +147,79 @@ function parseMemoryArgs(args: ReadonlyArray<string>): ParsedMemoryArgs {
 		throw new Error(`unexpected memory argument: ${arg}`);
 	}
 	if (parsed.help) return parsed;
-	if (parsed.command === undefined) throw new Error("memory requires list, propose, approve, reject, or prune");
+	if (parsed.command === undefined) throw new Error("memory requires list, propose, promote, approve, reject, or prune");
 	if (parsed.command === "propose" && parsed.evidenceId === undefined) {
 		throw new Error("propose requires --from-evidence <evidenceId>");
 	}
+	if (parsed.command === "promote" && parsed.handoffPath === undefined) {
+		throw new Error("promote requires --from-handoff <path>");
+	}
 	if ((parsed.command === "approve" || parsed.command === "reject") && parsed.memoryId === undefined) {
 		throw new Error(`${parsed.command} requires a memory id`);
 	}
 	if (parsed.command === "prune" && !parsed.stale) throw new Error("prune requires --stale");
-	if (parsed.command === "list" && (parsed.evidenceId !== undefined || parsed.memoryId !== undefined || parsed.stale)) {
+	if (parsed.command === "promote" && parsed.scope === undefined) {
+		throw new Error("promote requires --scope <repo|global|runtime|agent>");
+	}
+	validateScopeArguments(parsed);
+	if (
+		parsed.command === "list" &&
+		(parsed.evidenceId !== undefined ||
+			parsed.handoffPath !== undefined ||
+			parsed.entryIds.length > 0 ||
+			parsed.memoryId !== undefined ||
+			parsed.stale ||
+			parsed.scope !== undefined)
+	) {
 		throw new Error("list does not accept extra arguments");
 	}
 	return parsed;
 }
 
+function requireOptionValue(args: ReadonlyArray<string>, index: number, option: string, expected: string): string {
+	const value = args[index + 1];
+	if (value === undefined || value.startsWith("-")) throw new Error(`${option} requires ${expected}`);
+	return value;
+}
+
+function validateScopeArguments(parsed: ParsedMemoryArgs): void {
+	const hasIdentityOption =
+		parsed.repositoryPath !== undefined ||
+		parsed.acknowledgeGlobal ||
+		parsed.runtimeId !== undefined ||
+		parsed.agentId !== undefined;
+	if (parsed.scope === undefined) {
+		if (hasIdentityOption) throw new Error("scope identity options require --scope");
+		return;
+	}
+	if (parsed.scope === "repo") {
+		if (parsed.repositoryPath === undefined)
+			throw new Error("repo scope requires --repository <canonical-absolute-path>");
+		if (parsed.acknowledgeGlobal || parsed.runtimeId !== undefined || parsed.agentId !== undefined) {
+			throw new Error("repo scope accepts only --repository");
+		}
+		return;
+	}
+	if (parsed.scope === "global") {
+		if (!parsed.acknowledgeGlobal) throw new Error("global scope requires --acknowledge-global");
+		if (parsed.repositoryPath !== undefined || parsed.runtimeId !== undefined || parsed.agentId !== undefined) {
+			throw new Error("global scope accepts only --acknowledge-global");
+		}
+		return;
+	}
+	if (parsed.scope === "runtime") {
+		if (parsed.runtimeId === undefined) throw new Error("runtime scope requires --runtime <source-runtime-id>");
+		if (parsed.repositoryPath !== undefined || parsed.acknowledgeGlobal || parsed.agentId !== undefined) {
+			throw new Error("runtime scope accepts only --runtime");
+		}
+		return;
+	}
+	if (parsed.agentId === undefined) throw new Error("agent scope requires --agent <source-agent-id>");
+	if (parsed.repositoryPath !== undefined || parsed.acknowledgeGlobal || parsed.runtimeId !== undefined) {
+		throw new Error("agent scope accepts only --agent");
+	}
+}
+
 export async function runMemoryCommand(args: ReadonlyArray<string>): Promise<number> {
 	let parsed: ParsedMemoryArgs;
 	try {
@@ -114,10 +248,40 @@ export async function runMemoryCommand(args: ReadonlyArray<string>): Promise<num
 				printError("propose requires --from-evidence <evidenceId>");
 				return 2;
 			}
-			const result = await proposeMemoryFromEvidence(dataDir, evidenceId);
+			const result = await proposeMemoryFromEvidence(dataDir, evidenceId, scopeSelection(parsed));
 			renderProposal(result.record, result.created);
 			return 0;
 		}
+		if (parsed.command === "promote") {
+			const handoffPath = parsed.handoffPath;
+			const selection = scopeSelection(parsed);
+			if (handoffPath === undefined || selection === undefined) {
+				printError("promote requires a handoff and explicit scope");
+				return 2;
+			}
+			const snapshot = await readReviewedHandoff(handoffPath);
+			const entries = selectHandoffEntries(snapshot, parsed.entryIds);
+			for (const entry of entries) {
+				const result = await proposeMemoryPromotion(
+					dataDir,
+					{
+						kind: "handoff-snapshot",
+						sessionId: snapshot.source.sessionId,
+						evidenceRefs: snapshot.source.evidenceRefs,
+						runtimeIds: snapshot.source.runtimeIds,
+						agentIds: snapshot.source.agentIds,
+						entry: handoffTaskEntry(entry),
+						redaction: {
+							replacementCount: snapshot.redaction.replacementCount,
+							sourceFields: snapshot.redaction.sourceFields,
+						},
+					},
+					selection,
+				);
+				renderProposal(result.record, result.created);
+			}
+			return 0;
+		}
 		if (parsed.command === "approve") {
 			const memoryId = parsed.memoryId;
 			if (memoryId === undefined) {
@@ -143,7 +307,7 @@ export async function runMemoryCommand(args: ReadonlyArray<string>): Promise<num
 			printOk(`pruned ${pruned.length} stale memory record${pruned.length === 1 ? "" : "s"}`);
 			return 0;
 		}
-		printError("memory requires list, propose, approve, reject, or prune");
+		printError("memory requires list, propose, promote, approve, reject, or prune");
 		return 2;
 	} catch (error) {
 		printError(error instanceof Error ? error.message : String(error));
@@ -151,14 +315,112 @@ export async function runMemoryCommand(args: ReadonlyArray<string>): Promise<num
 	}
 }
 
+function scopeSelection(parsed: ParsedMemoryArgs): MemoryScopeSelection | undefined {
+	if (parsed.scope === undefined) return undefined;
+	if (parsed.scope === "repo") {
+		const repositoryPath = parsed.repositoryPath;
+		if (repositoryPath === undefined) throw new Error("repo scope requires --repository");
+		const repository = canonicalMemoryRepositoryIdentity(repositoryPath);
+		if (repository === null || repository.key !== repositoryPath) {
+			throw new Error("--repository must be an existing canonical absolute repository path");
+		}
+		return { scope: "repo", repository };
+	}
+	if (parsed.scope === "global") {
+		if (!parsed.acknowledgeGlobal) throw new Error("global scope requires --acknowledge-global");
+		return { scope: "global", acknowledgeGlobal: true };
+	}
+	if (parsed.scope === "runtime") {
+		if (parsed.runtimeId === undefined) throw new Error("runtime scope requires --runtime");
+		return { scope: "runtime", runtime: memoryRuntimeIdentity(parsed.runtimeId) };
+	}
+	if (parsed.agentId === undefined) throw new Error("agent scope requires --agent");
+	return { scope: "agent", agent: memoryAgentIdentity(parsed.agentId) };
+}
+
+async function readReviewedHandoff(path: string): Promise<ReviewedTaskMemoryHandoffSnapshot> {
+	const info = await stat(path);
+	if (!info.isFile()) throw new Error(`task-memory handoff is not a file: ${path}`);
+	if (info.size > 1_000_000) throw new Error(`task-memory handoff exceeds 1000000 bytes: ${path}`);
+	const snapshot = parseTaskMemoryHandoffSnapshot(await readFile(path, "utf8"));
+	if (snapshot === null) throw new Error(`task-memory handoff is invalid: ${path}`);
+	if (snapshot.version !== 2) {
+		throw new Error("task-memory handoff lacks source session and evidence provenance; create a new redacted handoff");
+	}
+	return snapshot;
+}
+
+interface SelectedHandoffEntry {
+	kind: "knowledge" | "procedural";
+	entry: TaskMemoryHandoffEntry;
+}
+
+function selectHandoffEntries(
+	snapshot: ReviewedTaskMemoryHandoffSnapshot,
+	entryIds: ReadonlyArray<string>,
+): SelectedHandoffEntry[] {
+	const entries: SelectedHandoffEntry[] = [
+		...snapshot.knowledge.map((entry) => ({ kind: "knowledge" as const, entry })),
+		...snapshot.procedural.map((entry) => ({ kind: "procedural" as const, entry })),
+	];
+	if (entries.length === 0) throw new Error("task-memory handoff contains no promotable entries");
+	if (entryIds.length === 0) return entries;
+	const requested = new Set(entryIds);
+	const selected = entries.filter(({ entry }) => requested.has(entry.id));
+	const missing = [...requested].filter((id) => !selected.some(({ entry }) => entry.id === id));
+	if (missing.length > 0) throw new Error(`task-memory handoff entry not found: ${missing.join(", ")}`);
+	return selected;
+}
+
+function handoffTaskEntry(selected: SelectedHandoffEntry): {
+	id: string;
+	kind: "knowledge" | "procedural";
+	content: string;
+	createdAt: string;
+	lastTouchedAt: string;
+	injectionCount: number;
+} {
+	const createdAt = selected.entry.createdAt;
+	const lastTouchedAt = selected.entry.lastTouchedAt;
+	if (createdAt === undefined || lastTouchedAt === undefined) {
+		throw new Error(`task-memory handoff entry lacks timestamps: ${selected.entry.id}`);
+	}
+	return {
+		id: selected.entry.id,
+		kind: selected.kind,
+		content: selected.entry.content,
+		createdAt,
+		lastTouchedAt,
+		injectionCount: selected.entry.injectionCount,
+	};
+}
+
 function renderProposal(record: MemoryRecord, created: boolean): void {
 	process.stdout.write(`memory: ${record.id}\n`);
 	process.stdout.write(`status: ${created ? "proposed" : memoryStatus(record)}\n`);
 	process.stdout.write(`scope: ${record.scope}\n`);
+	if (record.repository !== undefined) process.stdout.write(`repository: ${record.repository.key}\n`);
+	if (record.runtime !== undefined) process.stdout.write(`runtime: ${record.runtime.key}\n`);
+	if (record.agent !== undefined) process.stdout.write(`agent: ${record.agent.key}\n`);
 	process.stdout.write(`key: ${record.key}\n`);
 	process.stdout.write(`evidence: ${record.evidenceRefs.join(", ")}\n`);
 	process.stdout.write(`confidence: ${record.confidence.toFixed(2)}\n`);
 	process.stdout.write(`lesson: ${record.lesson}\n`);
+	if (record.provenance !== undefined) {
+		process.stdout.write(`source: ${record.provenance.sourceKind}\n`);
+		if (record.provenance.sourceSessionId !== undefined) {
+			process.stdout.write(`source-session: ${record.provenance.sourceSessionId}\n`);
+		}
+		if (record.provenance.sourceEntryId !== undefined) {
+			process.stdout.write(`source-entry: ${record.provenance.sourceEntryId}\n`);
+		}
+		if (record.provenance.redaction !== undefined) {
+			process.stdout.write(
+				`redaction: ${record.provenance.redaction.replacementCount} replacement${record.provenance.redaction.replacementCount === 1 ? "" : "s"}; fields=${record.provenance.redaction.sourceFields.join(",") || "none"}\n`,
+			);
+		}
+	}
+	process.stdout.write(`review: clio-coder memory approve ${record.id}\n`);
 }
 
 function renderMemoryList(records: ReadonlyArray<MemoryRecord>): void {

package/src/cli/modes/json-stream.ts

@@ -4,8 +4,8 @@
  * The stream is append-oriented: it carries each piece of content exactly
  * once, as an increment while it streams and as one completed message when it
  * lands. It never repeats the growing snapshot of an in-progress message,
- * because that is quadratic in a long turn. One tool-heavy SciCode sub-step
- * wrote 802 MB of stdout, 99.3% of it `message_update` snapshots of a message
+ * because that is quadratic in a long turn. One tool-heavy headless turn wrote
+ * 802 MB of stdout, 99.3% of it `message_update` snapshots of a message
  * whose final form is 44 KB.
  *
  * The rules, in one place:

package/src/cli/modes/print.ts

@@ -1,4 +1,8 @@
 import { readClioVersion, readPiMonoVersion } from "../../core/package-root.js";
+import {
+	addResponseModelIdObservationCounts,
+	emptyResponseModelIdObservationCounts,
+} from "../../core/response-model-id.js";
 import { withRunOverrides } from "../../core/run-overrides.js";
 import {
 	type PendingSkillRequest,
@@ -187,6 +191,10 @@ function recordToolEnd(stats: HeadlessMainAgentReceiptStats, event: ChatLoopEven
 }
 
 function addRunUsage(left: RunUsageSummary, right: RunUsageSummary): RunUsageSummary {
+	const responseModelIdObservationCounts = emptyResponseModelIdObservationCounts();
+	addResponseModelIdObservationCounts(responseModelIdObservationCounts, left.responseModelIdObservationCounts);
+	addResponseModelIdObservationCounts(responseModelIdObservationCounts, right.responseModelIdObservationCounts);
+	const last = right.hadUsage ? right : left;
 	return {
 		tokens: left.tokens + right.tokens,
 		costUsd: left.costUsd + right.costUsd,
@@ -197,7 +205,10 @@ function addRunUsage(left: RunUsageSummary, right: RunUsageSummary): RunUsageSum
 		reasoning: left.reasoning + right.reasoning,
 		apiCalls: left.apiCalls + right.apiCalls,
 		hadReasoning: left.hadReasoning || right.hadReasoning,
-		hadUsage: true,
+		hadUsage: left.hadUsage || right.hadUsage,
+		responseModelIdObservationCounts,
+		lastResponseModelIdObservation: last.lastResponseModelIdObservation,
+		lastDifferingResponseModelId: last.lastDifferingResponseModelId,
 	};
 }