@iowarp/clio-coder 0.3.6 → 0.3.7

package/src/domains/observability/cost.ts

@@ -111,6 +111,13 @@ export interface UsageBreakdown {
 	apiCalls?: number;
 }
 
+/**
+ * What produced a priced call, when it was not an ordinary turn. `/cost` and
+ * the usage surfaces separate these out so an operator can see that money was
+ * spent beside the session rather than inside it.
+ */
+export type CostEntryLabel = "side-question" | "handoff";
+
 export interface CostEntry {
 	providerId: string;
 	attributedModelId: string;
@@ -125,6 +132,8 @@ export interface CostEntry {
 	cacheWrite: number;
 	reasoningTokens: number;
 	apiCalls?: number;
+	/** Absent on an ordinary turn's call. */
+	label?: CostEntryLabel;
 }
 
 export interface CostTracker {
@@ -139,6 +148,7 @@ export interface CostTracker {
 			requestedModelIds: ReadonlyArray<string>;
 			responseModelIdObservationCounts: Readonly<ResponseModelIdObservationCounts>;
 		},
+		label?: CostEntryLabel,
 	): number;
 	sessionTotal(): number;
 	sessionCost(): CostAggregate;
@@ -156,7 +166,7 @@ export function createCostTracker(): CostTracker {
 	let total = 0;
 	const totals = emptyBreakdown();
 	return {
-		accumulate(providerId, attributedModelId, tokens, usd, breakdown, costProvenance, modelIdFacts) {
+		accumulate(providerId, attributedModelId, tokens, usd, breakdown, costProvenance, modelIdFacts, label) {
 			const resolvedUsd = usd ?? 0;
 			const provenance = normalizeCostProvenance(costProvenance);
 			const input = breakdown?.input ?? 0;
@@ -186,6 +196,7 @@ export function createCostTracker(): CostTracker {
 				cacheWrite,
 				reasoningTokens,
 				...(apiCalls !== undefined ? { apiCalls } : {}),
+				...(label !== undefined ? { label } : {}),
 			});
 			total += resolvedUsd;
 			totals.input += input;

package/src/domains/observability/extension.ts

@@ -259,9 +259,9 @@ export function createObservabilityBundle(
 			latestThroughput = null;
 			projection.refresh();
 		},
-		recordTokens(providerId, attributedModelId, tokens, costUsd, breakdown, costProvenance, modelIdFacts) {
+		recordTokens(providerId, attributedModelId, tokens, costUsd, breakdown, costProvenance, modelIdFacts, label) {
 			telemetry.record("counter", "tokens.total", tokens);
-			cost.accumulate(providerId, attributedModelId, tokens, costUsd, breakdown, costProvenance, modelIdFacts);
+			cost.accumulate(providerId, attributedModelId, tokens, costUsd, breakdown, costProvenance, modelIdFacts, label);
 			projection.refresh();
 		},
 		recordSessionTurn(sessionTurn) {

package/src/domains/observability/index.ts

@@ -30,6 +30,7 @@ export {
 	type CostAggregate,
 	type CostAmount,
 	type CostEntry,
+	type CostEntryLabel,
 	costAggregateForAmount,
 	costWasMeasured,
 	emptyCostAggregate,
@@ -40,6 +41,15 @@ export type { EvidenceIndexRow } from "./evidence-index.js";
 export { EVIDENCE_INDEX_FILE, MAX_EVIDENCE_INDEX_ROWS, readEvidenceIndex } from "./evidence-index.js";
 export { ObservabilityManifest } from "./manifest.js";
 export type { MetricsView } from "./metrics.js";
+export type { OutOfTurnUsage, OutOfTurnUsageReadResult, OutOfTurnUsageRow } from "./out-of-turn-usage.js";
+export {
+	appendOutOfTurnUsageRow,
+	MAX_OUT_OF_TURN_USAGE_ROWS,
+	OUT_OF_TURN_USAGE_DIR,
+	OUT_OF_TURN_USAGE_FILE,
+	outOfTurnUsagePath,
+	readOutOfTurnUsageRows,
+} from "./out-of-turn-usage.js";
 export type { ObservabilityProjection, ProjectionReadModel } from "./projection.js";
 export {
 	createObservabilityProjection,

package/src/domains/observability/out-of-turn-usage.ts

@@ -0,0 +1,223 @@
+/**
+ * Durable record of the model calls that were billed beside a session rather
+ * than inside it: `/btw` side questions and `/handoff` extraction rounds.
+ *
+ * These rounds deliberately append nothing to the session JSONL. A fleet run
+ * briefs its workers from the transcript, so a question the operator asked to
+ * orient themselves must not become context those workers inherit, and
+ * `src/interactive/side-question.ts` states that promise as a contract. The
+ * money was still spent, though, and until this store existed the only record
+ * of it was the in-process cost tracker: `/cost` showed it for as long as the
+ * process lived, and `clio-coder usage report`, which reads the archive on
+ * disk, could not see it at all.
+ *
+ * So the spend gets its own file. One JSON line per priced out-of-turn call
+ * under `<stateDir>/usage/out-of-turn.jsonl`, carrying the label, the session
+ * it sat beside, the repo identity the session ledger is filed under (so
+ * `usage report --repo` filters these rows the same way it filters ledgers),
+ * the target and attributed model, and the provider-reported usage.
+ *
+ * Writes follow the audit-row conventions: one append-mode `writeSync` per
+ * row, so a line lands whole even with concurrent writers, and a failure is
+ * logged to stderr rather than thrown back into the interactive path. The file
+ * is a bounded ring: once it grows past {@link MAX_OUT_OF_TURN_USAGE_ROWS} the
+ * newest rows are rewritten atomically under the shared state-file lock and
+ * the oldest are dropped. Reads are tolerant; a malformed line is reported and
+ * skipped, never fatal.
+ */
+
+import { closeSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { safeResourceWrite } from "../../core/safe-resource-write.js";
+import { withStateFileLockSync } from "../../core/state-file-lock.js";
+import type { CostProvenance } from "../providers/index.js";
+import type { CostEntryLabel } from "./cost.js";
+
+/** Directory under the state dir that holds cross-session usage side-cars. */
+export const OUT_OF_TURN_USAGE_DIR = "usage";
+
+/** Filename of the out-of-turn usage ledger inside {@link OUT_OF_TURN_USAGE_DIR}. */
+export const OUT_OF_TURN_USAGE_FILE = "out-of-turn.jsonl";
+
+/** Cap on retained rows. Matches the dispatch runs ledger and evidence index default. */
+export const MAX_OUT_OF_TURN_USAGE_ROWS = 1000;
+
+/**
+ * How many appends this process makes between bound checks. Counting rows means
+ * reading the file, and an out-of-turn round is rare enough that paying that on
+ * the first append of a process and periodically after it keeps the ring bounded
+ * without reading a megabyte per side question.
+ */
+const BOUND_CHECK_INTERVAL = 64;
+
+/** Provider-reported usage for one out-of-turn call. */
+export interface OutOfTurnUsage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	reasoning: number;
+	totalTokens: number;
+	costUsd: number;
+	costProvenance: CostProvenance;
+}
+
+/** One priced model call that was billed beside a session rather than inside it. */
+export interface OutOfTurnUsageRow {
+	label: CostEntryLabel;
+	/** Session the round sat beside, or null when no session was current. */
+	sessionId: string | null;
+	/** The cwd hash the session ledger is filed under, so `--repo` can filter these rows. */
+	repoIdentity: string | null;
+	/** ISO-8601 timestamp of the call. */
+	timestamp: string;
+	/** Target id the round ran against. */
+	target: string;
+	attributedModelId: string;
+	usage: OutOfTurnUsage;
+}
+
+export interface OutOfTurnUsageReadResult {
+	rows: OutOfTurnUsageRow[];
+	errors: string[];
+}
+
+export function outOfTurnUsagePath(stateDir: string): string {
+	return join(stateDir, OUT_OF_TURN_USAGE_DIR, OUT_OF_TURN_USAGE_FILE);
+}
+
+let appendsSinceBoundCheck = BOUND_CHECK_INTERVAL;
+
+/**
+ * Append one priced out-of-turn call. Never throws: this runs on the same path
+ * that answers an operator's side question, and a failed bookkeeping write must
+ * not take the answer down with it.
+ */
+export function appendOutOfTurnUsageRow(stateDir: string, row: OutOfTurnUsageRow): void {
+	const path = outOfTurnUsagePath(stateDir);
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		const fd = openSync(path, "a");
+		try {
+			writeSync(fd, `${JSON.stringify(row)}\n`);
+		} finally {
+			closeSync(fd);
+		}
+	} catch (error) {
+		process.stderr.write(`[clio:usage] out-of-turn usage row not written: ${messageOf(error)}\n`);
+		return;
+	}
+	appendsSinceBoundCheck += 1;
+	if (appendsSinceBoundCheck < BOUND_CHECK_INTERVAL) return;
+	appendsSinceBoundCheck = 0;
+	try {
+		boundOutOfTurnUsageFile(path);
+	} catch (error) {
+		process.stderr.write(`[clio:usage] out-of-turn usage ring not bounded: ${messageOf(error)}\n`);
+	}
+}
+
+/**
+ * Rewrite the file down to the newest {@link MAX_OUT_OF_TURN_USAGE_ROWS} lines
+ * when it has grown past the cap. Held under the state-file lock so a concurrent
+ * appender cannot lose a row into the rename, and written through
+ * `safeResourceWrite` so a crash mid-rewrite leaves the previous file intact.
+ */
+function boundOutOfTurnUsageFile(path: string): void {
+	withStateFileLockSync(path, () => {
+		let raw: string;
+		try {
+			raw = readFileSync(path, "utf8");
+		} catch {
+			return;
+		}
+		const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+		if (lines.length <= MAX_OUT_OF_TURN_USAGE_ROWS) return;
+		const kept = lines.slice(-MAX_OUT_OF_TURN_USAGE_ROWS);
+		safeResourceWrite(path, `${kept.join("\n")}\n`, { encoding: "utf8" });
+	});
+}
+
+/**
+ * Read every recorded out-of-turn call. A missing file is an empty read rather
+ * than an error: a machine where nobody has ever run `/btw` has nothing to
+ * report, and that is a different thing from a store that failed to open.
+ */
+export function readOutOfTurnUsageRows(stateDir: string): OutOfTurnUsageReadResult {
+	const path = outOfTurnUsagePath(stateDir);
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT" || err.code === "ENOTDIR") return { rows: [], errors: [] };
+		return { rows: [], errors: [`out-of-turn usage store unreadable: ${messageOf(error)}`] };
+	}
+	const rows: OutOfTurnUsageRow[] = [];
+	const errors: string[] = [];
+	const lines = raw.split("\n");
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (line === undefined || line.trim().length === 0) continue;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line) as unknown;
+		} catch (error) {
+			errors.push(`${path}:${index + 1}: invalid JSON: ${messageOf(error)}`);
+			continue;
+		}
+		const row = asOutOfTurnUsageRow(parsed);
+		if (row === null) {
+			errors.push(`${path}:${index + 1}: not an out-of-turn usage row`);
+			continue;
+		}
+		rows.push(row);
+	}
+	return { rows, errors };
+}
+
+function asOutOfTurnUsageRow(value: unknown): OutOfTurnUsageRow | null {
+	if (!isRecord(value)) return null;
+	const label = value.label;
+	if (label !== "side-question" && label !== "handoff") return null;
+	if (typeof value.timestamp !== "string" || value.timestamp.length === 0) return null;
+	if (!isRecord(value.usage)) return null;
+	const usage = value.usage;
+	return {
+		label,
+		sessionId: typeof value.sessionId === "string" ? value.sessionId : null,
+		repoIdentity: typeof value.repoIdentity === "string" ? value.repoIdentity : null,
+		timestamp: value.timestamp,
+		target: typeof value.target === "string" && value.target.length > 0 ? value.target : "unknown",
+		attributedModelId:
+			typeof value.attributedModelId === "string" && value.attributedModelId.length > 0
+				? value.attributedModelId
+				: "unknown",
+		usage: {
+			input: numberOr0(usage.input),
+			output: numberOr0(usage.output),
+			cacheRead: numberOr0(usage.cacheRead),
+			cacheWrite: numberOr0(usage.cacheWrite),
+			reasoning: numberOr0(usage.reasoning),
+			totalTokens: numberOr0(usage.totalTokens),
+			costUsd: numberOr0(usage.costUsd),
+			costProvenance: asCostProvenance(usage.costProvenance),
+		},
+	};
+}
+
+function asCostProvenance(value: unknown): CostProvenance {
+	return value === "known" || value === "known_free" || value === "estimated" ? value : "unknown";
+}
+
+function numberOr0(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function messageOf(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/domains/resources/index.ts

@@ -18,6 +18,24 @@ export function createResourcesDomainModule(options: ResourceLoaderOptions = {})
 export type { ResourceDiagnostic, ResourceScope, ResourceSourceInfo } from "./collision.js";
 export { resolveResourceCollisions } from "./collision.js";
 export type { ResourceList, ResourcesContract } from "./contract.js";
+export {
+	classifyLibraryRequirements,
+	confirmLibraryRemote,
+	discoverLibrary,
+	installLibraryPlan,
+	type LibraryCommandRunner,
+	type LibraryDiscoveryResult,
+	type LibraryEntry,
+	type LibraryInstallPlan,
+	type LibraryRequirementStatus,
+	libraryEntryInstalled,
+	libraryEntryPin,
+	libraryEntryRef,
+	libraryInstallPath,
+	planLibraryInstall,
+	resolveLibraryRequirements,
+	syncLibrary,
+} from "./library.js";
 export { createResourcesLoader, type ResourceLoaderOptions } from "./loader.js";
 export { ResourcesManifest } from "./manifest.js";
 export {
@@ -61,6 +79,8 @@ export {
 	discoverMarketplaceSkills,
 	getMarketplaceSkills,
 	installSkill,
+	type LibraryEntryKind,
+	type LibraryRequirementRef,
 	MARKETPLACE_UNCONFIGURED,
 	type MarketplaceDiscoveryResult,
 	type MarketplaceSkill,

package/src/domains/resources/library.ts

@@ -0,0 +1,326 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { readSettings, updateSettings } from "../../core/config.js";
+import { runCommandVector, type SafeCommandResult } from "../../core/safe-exec.js";
+import { safeResourceWrite } from "../../core/safe-resource-write.js";
+import { clioConfigDir } from "../../core/xdg.js";
+import { parseFrontmatter } from "../agents/frontmatter.js";
+import {
+	assertAgentSpecPolicy,
+	normalizeAgentSpec,
+	parseAgentRecipeSchema,
+	parseFleetContract,
+} from "../agents/index.js";
+import { loadPromptTemplates } from "./prompts/loader.js";
+import { normalizedSkillHash } from "./skills/install.js";
+import {
+	type DiscoverMarketplaceOptions,
+	discoverMarketplaceSkills,
+	installSkill,
+	type LibraryEntryKind,
+	type LibraryRequirementRef,
+	type MarketplaceSkill,
+} from "./skills/marketplace.js";
+
+export type LibraryEntry = MarketplaceSkill;
+
+export interface LibraryDiscoveryResult {
+	entries: LibraryEntry[];
+	diagnostics: string[];
+	refusals: Readonly<Record<string, string>>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function catalogPath(): string {
+	const configured = readSettings().library.catalog;
+	return path.resolve(configured ?? path.join(clioConfigDir(), "library.yaml"));
+}
+
+function parseCatalog(filePath: string, diagnostics: string[]): LibraryEntry[] {
+	if (!existsSync(filePath)) return [];
+	try {
+		const raw = readFileSync(filePath, "utf8");
+		const parsed = filePath.endsWith(".json") ? JSON.parse(raw) : parseYaml(raw);
+		const rows = Array.isArray(parsed) ? parsed : isRecord(parsed) && Array.isArray(parsed.skills) ? parsed.skills : [];
+		return rows.flatMap((value): LibraryEntry[] => {
+			if (
+				!isRecord(value) ||
+				typeof value.name !== "string" ||
+				typeof value.description !== "string" ||
+				typeof value.sourceUrl !== "string"
+			) {
+				diagnostics.push(`library catalog entry malformed: ${filePath}`);
+				return [];
+			}
+			const kind: LibraryEntryKind =
+				value.kind === undefined || value.kind === "skill"
+					? "skill"
+					: value.kind === "agent" || value.kind === "prompt" || value.kind === "fleet"
+						? value.kind
+						: "skill";
+			if (value.kind !== undefined && !["skill", "agent", "prompt", "fleet"].includes(String(value.kind))) {
+				diagnostics.push(`library catalog entry has unsupported kind: ${value.name}`);
+				return [];
+			}
+			if (
+				value.requires !== undefined &&
+				(!Array.isArray(value.requires) || value.requires.some((item) => typeof item !== "string"))
+			) {
+				diagnostics.push(`library_requirement_malformed: ${value.name}`);
+				return [];
+			}
+			const sourceUrl = /^(?:https?:\/\/|git@)/.test(value.sourceUrl)
+				? value.sourceUrl
+				: path.resolve(path.dirname(filePath), value.sourceUrl);
+			const requires = Array.isArray(value.requires)
+				? value.requires.filter((item): item is LibraryRequirementRef => typeof item === "string")
+				: undefined;
+			return [
+				{
+					kind,
+					name: value.name.trim(),
+					description: value.description.trim(),
+					sourceUrl,
+					origin: "index",
+					...(typeof value.version === "string" ? { version: value.version } : {}),
+					...(requires ? { requires } : {}),
+				},
+			];
+		});
+	} catch (error) {
+		diagnostics.push(`library catalog unreadable: ${error instanceof Error ? error.message : String(error)}`);
+		return [];
+	}
+}
+
+export function libraryEntryRef(entry: Pick<LibraryEntry, "kind" | "name">): LibraryRequirementRef {
+	return `${entry.kind}:${entry.name}`;
+}
+
+export function discoverLibrary(
+	options: { catalog?: string; cwd?: string; marketplace?: DiscoverMarketplaceOptions } = {},
+): LibraryDiscoveryResult {
+	const marketplace = discoverMarketplaceSkills({
+		...(options.marketplace ?? {}),
+		...(options.cwd ? { cwd: options.cwd } : {}),
+	});
+	const diagnostics = [...marketplace.diagnostics.filter((item) => !item.includes("no local skill marketplace"))];
+	const privatePath = catalogPath();
+	const primary = options.catalog ? parseCatalog(path.resolve(options.catalog), diagnostics) : [];
+	const privateEntries = parseCatalog(privatePath, diagnostics);
+	const byRef = new Map<string, LibraryEntry>();
+	for (const entry of [...marketplace.skills, ...primary, ...privateEntries]) byRef.set(libraryEntryRef(entry), entry);
+	const refusals: Record<string, string> = {};
+	const entries = [...byRef.values()].filter((entry) => {
+		try {
+			resolveLibraryRequirements(entry, [...byRef.values()]);
+			return true;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			refusals[libraryEntryRef(entry)] = message;
+			if (!diagnostics.includes(message)) diagnostics.push(message);
+			return false;
+		}
+	});
+	return {
+		entries: entries.sort((a, b) => libraryEntryRef(a).localeCompare(libraryEntryRef(b))),
+		diagnostics,
+		refusals,
+	};
+}
+
+const REQUIREMENT_PATTERN = /^(skill|agent|prompt|fleet):([A-Za-z0-9][A-Za-z0-9._-]*)$/;
+
+export function resolveLibraryRequirements(entry: LibraryEntry, catalog: ReadonlyArray<LibraryEntry>): LibraryEntry[] {
+	const byRef = new Map(catalog.map((item) => [libraryEntryRef(item), item]));
+	const ordered: LibraryEntry[] = [];
+	const visiting: string[] = [];
+	const visited = new Set<string>();
+	const visit = (current: LibraryEntry): void => {
+		const currentRef = libraryEntryRef(current);
+		if (visited.has(currentRef)) return;
+		const cycleAt = visiting.indexOf(currentRef);
+		if (cycleAt >= 0)
+			throw new Error(`library_requirement_cycle: ${[...visiting.slice(cycleAt), currentRef].join(" -> ")}`);
+		visiting.push(currentRef);
+		for (const requirement of current.requires ?? []) {
+			if (!REQUIREMENT_PATTERN.test(requirement)) throw new Error("library_requirement_malformed");
+			const dependency = byRef.get(requirement);
+			if (!dependency) throw new Error(`library_requirement_missing: ${requirement}`);
+			visit(dependency);
+		}
+		visiting.pop();
+		visited.add(currentRef);
+		ordered.push(current);
+	};
+	visit(entry);
+	return ordered;
+}
+
+function sourceFile(entry: LibraryEntry): string {
+	const source = path.resolve(entry.sourceUrl);
+	if (entry.kind === "skill") return source;
+	if (!existsSync(source)) throw new Error(`library source path does not exist: ${source}`);
+	return source;
+}
+
+function validateEntry(entry: LibraryEntry, raw: string, filePath: string): void {
+	if (entry.kind === "fleet") {
+		parseFleetContract(raw, filePath);
+		return;
+	}
+	if (entry.kind === "agent") {
+		const parsed = parseFrontmatter(raw, filePath);
+		const recipe = parseAgentRecipeSchema({ id: entry.name, source: "user", filepath: filePath, ...parsed });
+		assertAgentSpecPolicy(normalizeAgentSpec(recipe));
+		return;
+	}
+	if (entry.kind === "prompt") {
+		const loaded = loadPromptTemplates({ roots: [{ path: path.dirname(filePath), scope: "user", source: "library" }] });
+		if (!loaded.items.some((item) => item.filePath === filePath))
+			throw new Error(`prompt template is malformed: ${filePath}`);
+	}
+}
+
+export interface LibraryInstallPlan {
+	entry: LibraryEntry;
+	path: string;
+	sha256: string;
+}
+
+export function libraryInstallPath(entry: Pick<LibraryEntry, "kind" | "name">): string {
+	if (entry.kind === "skill") return path.join(clioConfigDir(), "skills", entry.name, "SKILL.md");
+	const root = entry.kind === "agent" ? "agents" : entry.kind === "fleet" ? "fleets" : "prompts";
+	return path.join(clioConfigDir(), root, `${entry.name}.md`);
+}
+
+function readLibraryPins(): Record<string, { sha256: string; sourceUrl: string }> {
+	const pinPath = path.join(clioConfigDir(), "library-pins.yaml");
+	if (!existsSync(pinPath)) return {};
+	const parsed = parseYaml(readFileSync(pinPath, "utf8"));
+	return isRecord(parsed) ? (parsed as Record<string, { sha256: string; sourceUrl: string }>) : {};
+}
+
+export interface LibraryRequirementStatus {
+	ordered: LibraryEntry[];
+	satisfied: LibraryEntry[];
+	unsatisfied: LibraryEntry[];
+}
+
+/**
+ * Whether this entry is already on disk for this operator. A kind-qualified pin
+ * and a kind-specific destination are each sufficient, which is the same rule
+ * the requirement classifier applies, so a surface that draws an installed or
+ * available column never disagrees with the gate that refuses an install.
+ */
+export function libraryEntryInstalled(entry: Pick<LibraryEntry, "kind" | "name">): boolean {
+	return readLibraryPins()[libraryEntryRef(entry)] !== undefined || existsSync(libraryInstallPath(entry));
+}
+
+/**
+ * The pin recorded for this entry, or undefined when nothing pinned it. A
+ * destination can exist without a pin, which is why this is a separate question
+ * from `libraryEntryInstalled`.
+ */
+export function libraryEntryPin(
+	entry: Pick<LibraryEntry, "kind" | "name">,
+): { sha256: string; sourceUrl: string } | undefined {
+	return readLibraryPins()[libraryEntryRef(entry)];
+}
+
+export function classifyLibraryRequirements(
+	entry: LibraryEntry,
+	catalog: ReadonlyArray<LibraryEntry>,
+): LibraryRequirementStatus {
+	const ordered = resolveLibraryRequirements(entry, catalog).slice(0, -1);
+	const satisfied = ordered.filter((requirement) => libraryEntryInstalled(requirement));
+	const satisfiedRefs = new Set(satisfied.map(libraryEntryRef));
+	return {
+		ordered,
+		satisfied,
+		unsatisfied: ordered.filter((requirement) => !satisfiedRefs.has(libraryEntryRef(requirement))),
+	};
+}
+
+export function planLibraryInstall(entry: LibraryEntry): LibraryInstallPlan {
+	if (entry.kind === "skill") {
+		const source = sourceFile(entry);
+		const file = statSync(source).isDirectory() ? path.join(source, "SKILL.md") : source;
+		const raw = readFileSync(file);
+		return {
+			entry,
+			path: libraryInstallPath(entry),
+			sha256: normalizedSkillHash(raw.toString("utf8")),
+		};
+	}
+	const source = sourceFile(entry);
+	const raw = readFileSync(source, "utf8");
+	validateEntry(entry, raw, source);
+	return {
+		entry,
+		path: libraryInstallPath(entry),
+		sha256: createHash("sha256").update(raw).digest("hex"),
+	};
+}
+
+function recordPin(plan: LibraryInstallPlan): void {
+	const pinPath = path.join(clioConfigDir(), "library-pins.yaml");
+	const pins = readLibraryPins();
+	pins[libraryEntryRef(plan.entry)] = { sha256: plan.sha256, sourceUrl: plan.entry.sourceUrl };
+	safeResourceWrite(pinPath, stringifyYaml(Object.fromEntries(Object.entries(pins).sort())), { encoding: "utf8" });
+}
+
+export function installLibraryPlan(plan: LibraryInstallPlan): void {
+	if (existsSync(plan.path)) throw new Error(`library destination already exists: ${plan.path}`);
+	if (plan.entry.kind === "skill") installSkill({ source: plan.entry.sourceUrl, scope: "user", name: plan.entry.name });
+	else safeResourceWrite(plan.path, readFileSync(sourceFile(plan.entry)));
+	recordPin(plan);
+}
+
+function confirmedRemote(): string {
+	const settings = readSettings().library;
+	if (!settings.remote || settings.remote !== settings.confirmedRemote) throw new Error("library_remote_unconfirmed");
+	return settings.remote;
+}
+
+export function confirmLibraryRemote(url: string): void {
+	const current = readSettings().library.remote;
+	if (current !== null && current !== url) throw new Error("library_remote_mismatch");
+	updateSettings((settings) => {
+		if (settings.library.remote === null) settings.library.remote = url;
+		settings.library.confirmedRemote = url;
+	});
+}
+
+export type LibraryCommandRunner = (
+	file: string,
+	args: ReadonlyArray<string>,
+	options: { cwd: string; workspaceRoot: string },
+) => Promise<SafeCommandResult>;
+
+export async function syncLibrary(
+	direction: "sync" | "push",
+	runner: LibraryCommandRunner = runCommandVector,
+): Promise<void> {
+	const settings = readSettings().library;
+	if (!settings.sync) throw new Error("library_sync_disabled");
+	const remote = confirmedRemote();
+	const cwd = path.dirname(catalogPath());
+	const remoteResult = await runner("git", ["remote", "get-url", "library"], { cwd, workspaceRoot: cwd });
+	if (remoteResult.exitCode !== 0 || remoteResult.stdout.trim() !== remote)
+		throw new Error("library_remote_unconfirmed");
+	if (direction === "sync") {
+		const fetched = await runner("git", ["fetch", "library"], { cwd, workspaceRoot: cwd });
+		if (fetched.exitCode !== 0) throw new Error(fetched.stderr.trim() || "library sync failed");
+		const advanced = await runner("git", ["merge", "--ff-only", "FETCH_HEAD"], { cwd, workspaceRoot: cwd });
+		if (advanced.exitCode !== 0) throw new Error(advanced.stderr.trim() || "library sync failed");
+		return;
+	}
+	const result = await runner("git", ["push", "library"], { cwd, workspaceRoot: cwd });
+	if (result.exitCode !== 0) throw new Error(result.stderr.trim() || `library ${direction} failed`);
+}