@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/domains/toolchain/remove.ts

@@ -0,0 +1,218 @@
+import { readdirSync, rmdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { toolchainRoot } from "./paths.js";
+import { findPinnedTool } from "./registry.js";
+
+/**
+ * Deleting vendored installs, and pruning the versions a pin bump superseded.
+ *
+ * Everything here only ever unlinks inside `<data>/tools/<id>/`, a directory
+ * Clio created by downloading it, so nothing an operator wrote is reachable
+ * from this file. That is what makes removal safe without a confirmation
+ * prompt: the worst outcome is a re-download of bytes the registry pins by
+ * checksum anyway.
+ *
+ * Version directories are the only thing considered. A name starting with `.`
+ * is an installer's staging or retired directory (`.<version>.incomplete-`,
+ * `.<version>.replaced-`), and a prune that raced an install and deleted one
+ * would corrupt that install. A full remove is different: it takes the whole
+ * `<id>` tree because no install of that tool is meant to survive it.
+ *
+ * A staging directory old enough to be dead is swept anyway. A killed install
+ * used to leave one behind permanently, invisible to every verb and reachable
+ * only by an operator who went reading under the data root.
+ */
+
+export interface ToolRemoveOptions {
+	/** Vendor root override. Defaults to the data root's `tools` directory. */
+	root?: string;
+	/**
+	 * How old a staging directory must be before it counts as abandoned.
+	 * Defaults to `STALE_STAGING_MS`. Tests set it; nothing else should need to.
+	 */
+	staleStagingMs?: number;
+}
+
+/**
+ * How long a staging directory may sit before a sweep treats it as dead.
+ *
+ * The window is far shorter than it looks. `installPinnedTool` downloads every
+ * asset and verifies every checksum *before* it creates the staging directory,
+ * so that directory's whole life is a handful of local file writes and two
+ * renames: sub-second normally, seconds on a struggling disk. An hour is twelve
+ * times the installer's own per-asset download timeout and orders of magnitude
+ * past the writes, which leaves no plausible live install inside it.
+ *
+ * The pid in the name is deliberately not consulted. Pids are reused, a pid
+ * belonging to another user answers a liveness probe with EPERM rather than an
+ * honest yes or no, and a data root shared over a network filesystem makes the
+ * number meaningless. Age is the one signal that means the same thing
+ * everywhere.
+ */
+export const STALE_STAGING_MS = 3_600_000;
+
+/** What one sweep of a tool's directory deleted, and what it could not. */
+export interface ToolRemoveResult {
+	ok: boolean;
+	id: string;
+	/** `<root>/<id>`, whether or not it exists. */
+	dir: string;
+	/** Version directories this sweep deleted, oldest name first. */
+	removed: string[];
+	/** Version directories that survived a delete attempt, with the reason. */
+	failed: ReadonlyArray<{ version: string; error: string }>;
+	/** Abandoned staging directories this sweep collected, by name. */
+	staleStaging: string[];
+	message: string;
+}
+
+/** Version directories currently installed for a tool, sorted. */
+export function installedToolVersions(id: string, options: ToolRemoveOptions = {}): string[] {
+	const dir = join(options.root ?? toolchainRoot(), id);
+	let names: string[];
+	try {
+		names = readdirSync(dir);
+	} catch {
+		// A tool nobody ever installed has no directory, which is not an error:
+		// the answer to "which versions are installed" is none.
+		return [];
+	}
+	return names
+		.filter((name) => !name.startsWith(".") && isDirectory(join(dir, name)))
+		.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Delete every vendored version of a tool, then the tool's own directory.
+ *
+ * A tool with nothing installed is a no-op that reports success: the operator
+ * asked for a state ("this tool is not vendored") that already holds, and
+ * failing them for it would make the verb unusable in a script.
+ */
+export function removeTool(id: string, options: ToolRemoveOptions = {}): ToolRemoveResult {
+	if (findPinnedTool(id) === null) {
+		const dir = join(options.root ?? toolchainRoot(), id);
+		return { ok: false, id, dir, removed: [], failed: [], staleStaging: [], message: `unknown tool: ${id}` };
+	}
+	return removeVersions(id, null, options);
+}
+
+/**
+ * Delete every vendored version of a tool except `keep`.
+ *
+ * Called by the installer once a version is in place, so a pin bump leaves one
+ * version directory behind rather than one per version the machine ever ran.
+ * The kept version is not required to exist: pruning to a version that is not
+ * installed empties the tool, which is what `--force` recovery wants.
+ */
+export function pruneSupersededVersions(id: string, keep: string, options: ToolRemoveOptions = {}): ToolRemoveResult {
+	return removeVersions(id, keep, options);
+}
+
+function removeVersions(id: string, keep: string | null, options: ToolRemoveOptions): ToolRemoveResult {
+	const root = options.root ?? toolchainRoot();
+	const dir = join(root, id);
+	const versions = installedToolVersions(id, { root }).filter((version) => version !== keep);
+	const removed: string[] = [];
+	const failed: { version: string; error: string }[] = [];
+	for (const version of versions) {
+		try {
+			rmSync(join(dir, version), { recursive: true, force: true });
+			removed.push(version);
+		} catch (error) {
+			failed.push({ version, error: error instanceof Error ? error.message : String(error) });
+		}
+	}
+	// Before the rmdir below, so an install killed weeks ago cannot keep the tool
+	// directory alive after every version of it is gone.
+	const staleStaging = sweepStaleStaging(dir, options.staleStagingMs ?? STALE_STAGING_MS);
+	if (keep === null && failed.length === 0) {
+		// The tool is gone, so its directory is litter. `rmdir` takes it only when
+		// it is empty, so a staging directory young enough to belong to a running
+		// installer makes this fail instead of destroying that install.
+		try {
+			rmdirSync(dir);
+		} catch {
+			// Either it was never there or something still lives in it. Neither
+			// changes what this call promised: no version of the tool remains.
+		}
+	}
+	return {
+		ok: failed.length === 0,
+		id,
+		dir,
+		removed,
+		failed,
+		staleStaging,
+		message: describeRemoval(id, dir, keep, removed, failed, staleStaging),
+	};
+}
+
+/**
+ * Delete the abandoned staging directories under one tool.
+ *
+ * Only names the installer produces are considered, so an operator who parked
+ * something of their own under `<data>/tools/<id>` with a leading dot keeps it.
+ * A directory whose age cannot be read is left alone: an unreadable stat is not
+ * evidence of death.
+ */
+function sweepStaleStaging(dir: string, staleMs: number): string[] {
+	let names: string[];
+	try {
+		names = readdirSync(dir);
+	} catch {
+		return [];
+	}
+	const cutoff = Date.now() - staleMs;
+	const swept: string[] = [];
+	for (const name of names.sort((a, b) => a.localeCompare(b))) {
+		if (!STAGING_NAME.test(name)) continue;
+		const stat = statSync(join(dir, name), { throwIfNoEntry: false });
+		if (stat === undefined || !stat.isDirectory() || stat.mtimeMs > cutoff) continue;
+		try {
+			rmSync(join(dir, name), { recursive: true, force: true });
+			swept.push(name);
+		} catch {
+			// A staging directory that resists deletion is litter, not a failure:
+			// nothing resolves it, and reporting it would turn a successful install
+			// into a failed one over a directory the ladder never looks at.
+		}
+	}
+	return swept;
+}
+
+/** `.<version>.incomplete-<pid>-<t>` and `.<version>.replaced-<pid>-<t>`. */
+const STAGING_NAME = /^\.[^/]+\.(?:incomplete|replaced)-\d+-[a-z0-9]+$/;
+
+function describeRemoval(
+	id: string,
+	dir: string,
+	keep: string | null,
+	removed: ReadonlyArray<string>,
+	failed: ReadonlyArray<{ version: string; error: string }>,
+	staleStaging: ReadonlyArray<string>,
+): string {
+	// Reported as a suffix rather than as the headline: an abandoned staging
+	// directory is housekeeping, and the operator asked about versions.
+	const swept =
+		staleStaging.length === 0
+			? ""
+			: `; swept ${staleStaging.length} abandoned install ${staleStaging.length === 1 ? "directory" : "directories"}`;
+	const trouble = failed.map((entry) => `${entry.version} (${entry.error})`).join(", ");
+	if (failed.length > 0) {
+		const done = removed.length > 0 ? `removed ${removed.join(", ")}; ` : "";
+		return `${done}could not remove ${id} ${trouble} under ${dir}${swept}`;
+	}
+	if (removed.length === 0) {
+		return keep === null
+			? `${id} is not installed under ${dir}; nothing to remove${swept}`
+			: `${id} has no superseded versions under ${dir}${swept}`;
+	}
+	const what = `${id} ${removed.join(", ")}`;
+	const headline = keep === null ? `removed ${what} from ${dir}` : `pruned ${what} from ${dir}, keeping ${keep}`;
+	return `${headline}${swept}`;
+}
+
+function isDirectory(path: string): boolean {
+	return statSync(path, { throwIfNoEntry: false })?.isDirectory() === true;
+}

package/src/domains/toolchain/resolve.ts

@@ -0,0 +1,182 @@
+import { statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { toolVersionDir, vendoredBinaryPath } from "./paths.js";
+import { currentToolPlatform, findPinnedTool, findPinnedToolByBinary, PINNED_TOOLS } from "./registry.js";
+import type { PinnedTool, ToolPathCandidate, ToolResolution, ToolStatus } from "./types.js";
+import { probeBinaryVersion, satisfiesMinimum } from "./version.js";
+
+/**
+ * The shared resolution ladder: PATH, then the vendored pin, then nothing.
+ *
+ * PATH comes first because a tool the operator installed themselves is the one
+ * they maintain, and Clio downloading a second copy of a program already on the
+ * machine is a surprise. It only wins when its version clears the registry's
+ * floor, because the alternative is Clio driving a surface that release does not
+ * have and reporting the resulting failure as a bug in the feature.
+ *
+ * Nothing here downloads, spawns a server, or writes to disk. It is safe on the
+ * interactive startup path and inside doctor, both of which promise to create
+ * nothing.
+ */
+
+/** First executable named `name` on PATH, or null. */
+export function findExecutableOnPath(name: string): string | null {
+	const pathEnv = process.env.PATH;
+	if (!pathEnv) return null;
+	const candidates = process.platform === "win32" ? [`${name}.exe`, name] : [name];
+	for (const dir of pathEnv.split(delimiter)) {
+		if (!dir) continue;
+		for (const candidate of candidates) {
+			const full = join(dir, candidate);
+			const stat = statSync(full, { throwIfNoEntry: false });
+			if (stat?.isFile() && (process.platform === "win32" || (stat.mode & 0o111) !== 0)) return full;
+		}
+	}
+	return null;
+}
+
+/**
+ * Resolve one executable name through the ladder.
+ *
+ * A name that is not in the registry gets a plain PATH lookup: there is no pin
+ * to compare against and nothing vendored to fall back to, so the answer is
+ * whatever PATH says.
+ */
+export function resolveToolBinary(name: string): ToolResolution {
+	const entry = findPinnedToolByBinary(name) ?? findPinnedTool(name);
+	if (entry === null) {
+		const found = findExecutableOnPath(name);
+		return {
+			source: found === null ? "none" : "path",
+			binaryPath: found,
+			version: null,
+			entry: null,
+			pathCandidate: found === null ? null : { path: found, version: null, satisfiesMinimum: true },
+			vendoredPath: null,
+		};
+	}
+	// An entry asked for by tool id resolves its primary binary; asked for by
+	// binary name it resolves that binary, so `ya` does not silently become `yazi`.
+	const binary = entry.binaries.includes(name) ? name : entry.primaryBinary;
+	return resolveEntryBinary(entry, binary);
+}
+
+/** The ladder for a known registry row and one of its binaries. */
+export function resolveEntryBinary(entry: PinnedTool, binary: string): ToolResolution {
+	const pathCandidate = probePathCandidate(entry, binary);
+	const vendored = vendoredBinaryPath(entry.id, entry.version, binary);
+	const vendoredStat = statSync(vendored, { throwIfNoEntry: false });
+	const vendoredPath = vendoredStat?.isFile() ? vendored : null;
+
+	if (pathCandidate?.satisfiesMinimum) {
+		return {
+			source: "path",
+			binaryPath: pathCandidate.path,
+			version: pathCandidate.version,
+			entry,
+			pathCandidate,
+			vendoredPath,
+		};
+	}
+	if (vendoredPath !== null) {
+		return {
+			source: "vendored",
+			binaryPath: vendoredPath,
+			version: entry.version,
+			entry,
+			pathCandidate,
+			vendoredPath,
+		};
+	}
+	return { source: "none", binaryPath: null, version: null, entry, pathCandidate, vendoredPath: null };
+}
+
+/** Per-entry state for the CLI and doctor. */
+export function toolStatus(entry: PinnedTool): ToolStatus {
+	const platform = currentToolPlatform();
+	const supported = platform !== null && entry.downloads[platform] !== undefined;
+	const resolution = resolveEntryBinary(entry, entry.primaryBinary);
+	return {
+		id: entry.id,
+		version: entry.version,
+		license: entry.license,
+		platform,
+		supported,
+		installed: resolution.vendoredPath !== null,
+		installDir: toolVersionDir(entry.id, entry.version),
+		resolution,
+	};
+}
+
+/** Per-entry state for every row, in registry order. */
+export function toolStatuses(): ToolStatus[] {
+	return PINNED_TOOLS.map((entry) => toolStatus(entry));
+}
+
+/** The one command that fixes a tool Clio cannot resolve. */
+export function installRemedy(id: string): string {
+	return `clio-coder tools install ${id}`;
+}
+
+/**
+ * What a rejected PATH copy was, and which floor it failed. Null when there is
+ * no PATH copy or when the one there was accepted.
+ *
+ * The floors are deliberately conservative: they sit at the pin for herdr and
+ * yazi because Clio drives socket and plugin surfaces verified against only
+ * that release. That is a defensible choice and a costly one, since it rejects
+ * binaries an operator installed themselves and that mostly work. The cost is
+ * only payable if the rejection is legible, so every renderer of a rejection
+ * names the path, the version found, and the floor it missed, and never reports
+ * a rejected copy as an absent one.
+ */
+export function describeFloorRejection(status: ToolStatus): string | null {
+	const candidate = status.resolution.pathCandidate;
+	if (candidate === null || candidate.satisfiesMinimum) return null;
+	const floor = status.resolution.entry?.minimumVersion ?? status.version;
+	const found = candidate.version === null ? "an unreadable version" : candidate.version;
+	return `PATH copy ${candidate.path} is ${found}, below the ${floor} floor`;
+}
+
+/**
+ * One sentence describing where a tool resolved and how its version compares to
+ * the pin. Shared by `clio-coder tools status` and the doctor rows so the two
+ * cannot drift into describing the same machine differently.
+ */
+export function describeResolution(status: ToolStatus): string {
+	const { resolution } = status;
+	const rejection = describeFloorRejection(status);
+	if (resolution.source === "path") {
+		const version = resolution.version ?? "unreadable version";
+		return `PATH ${resolution.binaryPath} (${version}, pin ${status.version})`;
+	}
+	if (resolution.source === "vendored") {
+		// The remedy is deliberately absent here. The rejection cost the operator
+		// nothing: Clio has a copy at the pin and is running it, and printing an
+		// install command that would change nothing is its own kind of dishonesty.
+		const rejected = rejection === null ? "" : `; ${rejection}, so Clio runs the vendored copy`;
+		return `vendored ${resolution.binaryPath} (${status.version})${rejected}`;
+	}
+	if (!status.supported) {
+		const platform = status.platform ?? `${process.platform}-${process.arch}`;
+		// No remedy either: there is no asset to install on this machine, so the
+		// rejection is the whole story and naming a command would be a dead end.
+		const rejected = rejection === null ? "" : `; ${rejection}`;
+		return `not installed and no pinned asset for this platform (${platform})${rejected}`;
+	}
+	if (rejection !== null) {
+		return `${rejection}, and nothing is vendored (install with \`${installRemedy(status.id)}\`)`;
+	}
+	return `not found (install with \`${installRemedy(status.id)}\`)`;
+}
+
+function probePathCandidate(entry: PinnedTool, binary: string): ToolPathCandidate | null {
+	const found = findExecutableOnPath(binary);
+	if (found === null) return null;
+	// The floor is a property of the tool, and only the primary binary is asked
+	// for its version, so a secondary binary inherits the primary's verdict from
+	// the same install root rather than being probed with flags it may not have.
+	const probeTarget = binary === entry.primaryBinary ? found : (findExecutableOnPath(entry.primaryBinary) ?? found);
+	const version = probeBinaryVersion(probeTarget, entry.versionArgs);
+	return { path: found, version, satisfiesMinimum: satisfiesMinimum(version, entry.minimumVersion) };
+}

package/src/domains/toolchain/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Shapes for the pinned external-tool registry.
+ *
+ * Clio uses a handful of third-party terminal programs (a pane multiplexer, a
+ * file manager, a transfer tool). None of them is a dependency of the product:
+ * every consumer degrades when the tool is absent. What the registry adds is a
+ * single place where each tool's exact version, download location, checksum,
+ * license, and acceptable PATH floor are written down, so an install is
+ * reproducible and an operator can see which copy Clio would actually run.
+ */
+
+/** Platforms the registry can describe a download for. */
+export type ToolPlatform = "linux-x64" | "linux-arm64" | "darwin-x64" | "darwin-arm64" | "win32-x64";
+
+/** How a downloaded asset is packed. `raw` is a bare executable. */
+export type ToolArchiveKind = "raw" | "zip" | "tar.gz";
+
+/**
+ * One platform's asset for one pinned tool.
+ *
+ * `sha256` is the hash of the asset exactly as downloaded, before any
+ * unpacking, so the verification happens on the bytes that crossed the network
+ * rather than on whatever an extractor produced from them.
+ */
+export interface PinnedToolDownload {
+	url: string;
+	sha256: string;
+	archive: ToolArchiveKind;
+	/**
+	 * Binary name to its path inside the archive. A `raw` download has exactly
+	 * one entry whose value is the empty string: the asset is the binary.
+	 */
+	binaryMembers: Readonly<Record<string, string>>;
+	/**
+	 * Files copied beside the binaries, given as paths inside the archive. This
+	 * is where a tool's own LICENSE comes from when upstream ships it in the
+	 * release asset. Each lands under its basename in the version directory.
+	 */
+	documentMembers: ReadonlyArray<string>;
+}
+
+/**
+ * A document fetched separately from the asset, for tools whose release asset
+ * is a bare binary carrying no license text. Pinned by checksum like the asset.
+ */
+export interface PinnedToolDocument {
+	name: string;
+	url: string;
+	sha256: string;
+}
+
+/** One row of the pinned table. */
+export interface PinnedTool {
+	id: string;
+	version: string;
+	summary: string;
+	homepage: string;
+	/** SPDX identifier of the upstream license. */
+	license: string;
+	/** Every executable the install places, in the order they are reported. */
+	binaries: ReadonlyArray<string>;
+	/** The executable whose `--version` answers for the whole tool. */
+	primaryBinary: string;
+	/**
+	 * Lowest version Clio accepts from a copy already on PATH. Below this the
+	 * resolution ladder falls through to the vendored copy, because the surface
+	 * Clio drives is only known to exist at or above this version.
+	 */
+	minimumVersion: string;
+	/** Arguments that make the primary binary print its version. */
+	versionArgs: ReadonlyArray<string>;
+	downloads: Readonly<Partial<Record<ToolPlatform, PinnedToolDownload>>>;
+	/** Documents fetched alongside the asset. Usually empty. */
+	documents: ReadonlyArray<PinnedToolDocument>;
+}
+
+/** Where a resolved binary came from. */
+export type ToolSource = "path" | "vendored" | "none";
+
+/** What a PATH candidate looked like, kept even when it was rejected. */
+export interface ToolPathCandidate {
+	path: string;
+	version: string | null;
+	satisfiesMinimum: boolean;
+}
+
+/** The answer of one trip down the resolution ladder. */
+export interface ToolResolution {
+	source: ToolSource;
+	/** Absolute path of the binary Clio would run, or null when unresolved. */
+	binaryPath: string | null;
+	/** Version of the resolved binary when it could be read. */
+	version: string | null;
+	/** The registry row this resolution used, when the name is a pinned tool. */
+	entry: PinnedTool | null;
+	/** A PATH copy that was found, whether or not it was accepted. */
+	pathCandidate: ToolPathCandidate | null;
+	/** The vendored copy's path when the pinned version is installed. */
+	vendoredPath: string | null;
+}
+
+/** Per-entry state, the shape the CLI and doctor both render. */
+export interface ToolStatus {
+	id: string;
+	version: string;
+	license: string;
+	platform: ToolPlatform | null;
+	/** False when the registry has no asset for the running platform. */
+	supported: boolean;
+	installed: boolean;
+	installDir: string;
+	resolution: ToolResolution;
+}

package/src/domains/toolchain/version.ts

@@ -0,0 +1,88 @@
+import { spawnSync } from "node:child_process";
+
+/**
+ * Version reading and comparison for third-party binaries.
+ *
+ * Every tool in the registry answers `--version` with something different:
+ * `herdr 0.8.2` on one line, `croc version 11.3.6`, and a six-line block from
+ * yazi whose version sits on the second line after a label. Nothing here tries
+ * to know those formats. The first dotted triple in the output is the version,
+ * which is true of all three and of every convention they might move to.
+ */
+
+const VERSION_PATTERN = /(\d+)\.(\d+)\.(\d+)/;
+
+/** How long a version probe may take before the binary is treated as unusable. */
+const PROBE_TIMEOUT_MS = 2000;
+
+/** The first dotted triple in some `--version` output. */
+export function parseVersion(output: string): string | null {
+	const match = VERSION_PATTERN.exec(output);
+	if (!match) return null;
+	return `${match[1]}.${match[2]}.${match[3]}`;
+}
+
+/**
+ * Negative when `a` is older than `b`, zero when equal, positive when newer.
+ * Unparseable input sorts oldest, so an unreadable version never satisfies a
+ * minimum.
+ */
+export function compareVersions(a: string, b: string): number {
+	const left = numericParts(a);
+	const right = numericParts(b);
+	for (let i = 0; i < 3; i += 1) {
+		const diff = (left[i] ?? 0) - (right[i] ?? 0);
+		if (diff !== 0) return diff;
+	}
+	return 0;
+}
+
+/** True when `found` is at least `minimum`. A null `found` never satisfies. */
+export function satisfiesMinimum(found: string | null, minimum: string): boolean {
+	if (found === null) return false;
+	return compareVersions(found, minimum) >= 0;
+}
+
+/**
+ * Run a binary's version command and read the version out of it.
+ *
+ * Results are memoized per absolute path for the life of the process. The
+ * resolution ladder is consulted every time a pane preset or a doctor row wants
+ * a tool, and each miss would otherwise be a process spawn on the interactive
+ * path. A binary replaced under a running Clio keeps its first answer until
+ * restart, which is the same staleness every other PATH lookup here carries.
+ */
+export function probeBinaryVersion(binaryPath: string, args: ReadonlyArray<string>): string | null {
+	const cached = probeCache.get(binaryPath);
+	if (cached !== undefined) return cached;
+	let version: string | null = null;
+	try {
+		const result = spawnSync(binaryPath, [...args], {
+			timeout: PROBE_TIMEOUT_MS,
+			encoding: "utf8",
+			// A version probe must never inherit a terminal or wait on input: some
+			// of these binaries are full-screen programs when given a tty.
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		if (result.error === undefined) {
+			version = parseVersion(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
+		}
+	} catch {
+		version = null;
+	}
+	probeCache.set(binaryPath, version);
+	return version;
+}
+
+/** Drop memoized probe results. Tests that swap binaries under a path need it. */
+export function resetVersionProbeCache(): void {
+	probeCache.clear();
+}
+
+const probeCache = new Map<string, string | null>();
+
+function numericParts(value: string): number[] {
+	const match = VERSION_PATTERN.exec(value);
+	if (!match) return [0, 0, 0];
+	return [Number(match[1]), Number(match[2]), Number(match[3])];
+}

package/src/engine/acp/adapter.ts

@@ -1,8 +1,10 @@
+import { performance } from "node:perf_hooks";
 import {
 	DEFAULT_DELEGATION_CONNECT_TIMEOUT_MS,
 	DEFAULT_DELEGATION_TURN_TIMEOUT_MS,
 	type DelegationAgentConfig,
 } from "../../core/defaults.js";
+import type { HeartbeatStamp } from "../../domains/dispatch/heartbeat.js";
 import type { AutonomyLevel } from "../../domains/safety/autonomy.js";
 import type { SafetyContract } from "../../domains/safety/contract.js";
 import type { AgentEvent } from "../types.js";
@@ -40,6 +42,10 @@ export interface AcpDelegationRunInput {
 	terminationWaitMs?: number;
 	/** Grace for session/cancel before abort escalates into hard termination. */
 	cancelGraceMs?: number;
+	/** Wall clock for the persisted heartbeat anchor. */
+	now?: () => number;
+	/** Monotonic clock for event-inactivity spans. */
+	monotonicNow?: () => number;
 }
 
 export interface AcpDelegationRunHandle {
@@ -54,7 +60,7 @@ export interface AcpDelegationRunHandle {
 	 * final observation bound expires.
 	 */
 	kill(): void;
-	heartbeatAt: { current: number };
+	heartbeatAt: HeartbeatStamp;
 	toolCallLog(): ReturnType<AcpToolMediator["snapshot"]>["toolCallLog"];
 }
 
@@ -176,7 +182,14 @@ export function startAcpDelegationRun(input: AcpDelegationRunInput): AcpDelegati
 	// peer into an unbounded request.
 	const connectTimeoutMs = input.agent.connectTimeoutMs ?? DEFAULT_DELEGATION_CONNECT_TIMEOUT_MS;
 	const turnTimeoutMs = input.agent.turnTimeoutMs ?? DEFAULT_DELEGATION_TURN_TIMEOUT_MS;
-	const heartbeatAt = { current: Date.now() };
+	const now = input.now ?? Date.now;
+	const monotonicNow = input.monotonicNow ?? (() => performance.now());
+	const heartbeatWallAnchor = now();
+	const heartbeatMonotonicAnchor = monotonicNow();
+	const heartbeatAt: HeartbeatStamp = {
+		current: heartbeatWallAnchor,
+		monotonic: heartbeatMonotonicAnchor,
+	};
 	const queue = new AsyncEventQueue<AcpRunEvent>();
 	const usage = emptyUsage();
 	const mapper = new AcpEventMapper();
@@ -202,7 +215,9 @@ export function startAcpDelegationRun(input: AcpDelegationRunInput): AcpDelegati
 		cancelTimer = null;
 	};
 	const emit = (event: AcpRunEvent): void => {
-		heartbeatAt.current = Date.now();
+		const stamp = monotonicNow();
+		heartbeatAt.monotonic = stamp;
+		heartbeatAt.current = heartbeatWallAnchor + (stamp - heartbeatMonotonicAnchor);
 		queue.push(event);
 	};
 	const mediator = new AcpToolMediator({