@agentconnect.md/cli 0.0.0 → 1.13.0-rc.11

package/dist/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import fs, { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import path, { dirname, join, resolve } from "node:path";
+import fs, { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import path, { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { EventEmitter } from "node:events";
-import childProcess, { execFile, spawn } from "node:child_process";
+import childProcess, { execFile, execFileSync, spawn } from "node:child_process";
 import process$1 from "node:process";
 import { stripVTControlCharacters } from "node:util";
 import { homedir } from "node:os";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
@@ -3004,6 +3004,14 @@ function logsDir(root) {
 function daemonLogPath(root) {
 	return join(root, "logs", "daemon.log");
 }
+/** `<root>/versions` — parent of every installed daemon version directory. */
+function versionsDir(root) {
+	return join(root, "versions");
+}
+/** `<root>/versions/<v>` — one extracted, self-contained daemon bundle. */
+function versionDir(root, version) {
+	return join(versionsDir(root), version);
+}
 /** `<root>/current` — the symlink that names the active version. */
 function currentLink(root) {
 	return join(root, "current");
@@ -3024,6 +3032,14 @@ function currentDistEntry(root) {
 function currentEntry(root) {
 	return process.env.AGENTCONNECT_DAEMON_ENTRY ?? currentDistEntry(root);
 }
+/** `<root>/versions.json` — CLI-private metadata (channel, previous, history). */
+function versionsJsonPath(root) {
+	return join(root, "versions.json");
+}
+/** `<root>/versions.lock` — inter-process writer mutex for the version store (§5.5). */
+function versionsLockPath(root) {
+	return join(root, "versions.lock");
+}
 /**
 * `<root>/cli-entry` — a pointer file holding the absolute path to the CLI's own
 * dist entry, so a service/foreground daemon can locate the CLI to run an
@@ -8274,7 +8290,11 @@ const AgentActivate = object({
 	crons: array(CronUpsert),
 	/** Prove the requested workspace can be materialized before activation ACK.
 	*  Used by scratch→GitHub conversion so a failed clone can be rolled back. */
-	prepareWorkspace: boolean().optional()
+	prepareWorkspace: boolean().optional(),
+	/** Reconcile the daemon-local workspace to the authoritative mode/repo/branch.
+	*  The daemon preserves the checkout when that materialization is unchanged,
+	*  and replaces its contents when it changed. */
+	reconcileWorkspace: boolean().optional()
 });
 const AgentLaunched = object({
 	agentId: string().uuid(),
@@ -11941,7 +11961,7 @@ var require_websocket = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	const http$1 = __require("http");
 	const net = __require("net");
 	const tls = __require("tls");
-	const { randomBytes, createHash: createHash$1 } = __require("crypto");
+	const { randomBytes, createHash: createHash$2 } = __require("crypto");
 	const { Duplex: Duplex$2, Readable } = __require("stream");
 	const { URL: URL$1 } = __require("url");
 	const PerMessageDeflate = require_permessage_deflate();
@@ -12609,7 +12629,7 @@ var require_websocket = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 				abortHandshake(websocket, socket, "Invalid Upgrade header");
 				return;
 			}
-			const digest = createHash$1("sha1").update(key + GUID).digest("base64");
+			const digest = createHash$2("sha1").update(key + GUID).digest("base64");
 			if (res.headers["sec-websocket-accept"] !== digest) {
 				abortHandshake(websocket, socket, "Invalid Sec-WebSocket-Accept header");
 				return;
@@ -13083,7 +13103,7 @@ var require_websocket_server = /* @__PURE__ */ __commonJSMin(((exports, module)
 	const EventEmitter$1 = __require("events");
 	const http = __require("http");
 	const { Duplex } = __require("stream");
-	const { createHash } = __require("crypto");
+	const { createHash: createHash$1 } = __require("crypto");
 	const extension = require_extension();
 	const PerMessageDeflate = require_permessage_deflate();
 	const subprotocol = require_subprotocol();
@@ -13352,7 +13372,7 @@ var require_websocket_server = /* @__PURE__ */ __commonJSMin(((exports, module)
 				"HTTP/1.1 101 Switching Protocols",
 				"Upgrade: websocket",
 				"Connection: Upgrade",
-				`Sec-WebSocket-Accept: ${createHash("sha1").update(key + GUID).digest("base64")}`
+				`Sec-WebSocket-Accept: ${createHash$1("sha1").update(key + GUID).digest("base64")}`
 			];
 			const ws = new this.options.WebSocket(null, void 0, this.options);
 			if (protocols.size) {
@@ -14040,6 +14060,562 @@ async function runLogin(opts, partial = {}) {
 	await deps.runForeground();
 }
 //#endregion
+//#region src/node-engines.ts
+/**
+* Minimal `engines.node` range check (cli-daemon-split.md §5.1 step 3) — enough
+* for the simple ranges npm packages actually use (`>=24`, `>=24.0.0`, `24 || 25`)
+* without pulling in a full semver dependency. Comparators within a group are
+* ANDed; `||` separates OR groups. Pre-release tags on the Node version are
+* ignored. An unparseable range returns `true` (accept) rather than blocking on
+* an exotic spec the caller never emits.
+*/
+function parseVersion(v) {
+	const m = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(v.trim());
+	if (!m) return null;
+	return [
+		Number(m[1]),
+		Number(m[2] ?? 0),
+		Number(m[3] ?? 0)
+	];
+}
+function cmp(a, b) {
+	for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+	return 0;
+}
+function satisfiesComparator(comparator, version) {
+	const m = /^(>=|<=|>|<|=|\^|~)?\s*(.+)$/.exec(comparator.trim());
+	if (!m) return true;
+	const op = m[1] ?? "=";
+	const target = parseVersion(m[2]);
+	if (!target) return true;
+	const c = cmp(version, target);
+	switch (op) {
+		case ">=": return c >= 0;
+		case ">": return c > 0;
+		case "<=": return c <= 0;
+		case "<": return c < 0;
+		case "^": return version[0] === target[0] && c >= 0;
+		case "~": return version[0] === target[0] && version[1] === target[1] && c >= 0;
+		default: return c === 0;
+	}
+}
+/** Whether `nodeVersion` satisfies the `engines.node` `range`. */
+function nodeSatisfies(range, nodeVersion) {
+	if (!range || range.trim() === "" || range.trim() === "*") return true;
+	const version = parseVersion(nodeVersion);
+	if (!version) return true;
+	return range.split("||").some((group) => {
+		const comparators = group.trim().split(/\s+/).filter(Boolean);
+		if (comparators.length === 0) return true;
+		return comparators.every((c) => satisfiesComparator(c, version));
+	});
+}
+//#endregion
+//#region src/registry.ts
+/**
+* npm registry client for daemon version resolution + download (cli-daemon-split.md
+* §5.1, §9). Security boundary: the CLI only ever fetches the ONE fixed package
+* name from its configured registry — never a CP-supplied URL/name/tarball. The
+* registry base is CLI-local config (`AGENTCONNECT_NPM_REGISTRY`), defaulting to
+* npmjs.org; it is deliberately NOT sourced from the Control Plane.
+*/
+const DAEMON_PKG = "@agentconnect.md/daemon";
+function registryBase() {
+	return (process.env.AGENTCONNECT_NPM_REGISTRY ?? "https://registry.npmjs.org").replace(/\/+$/, "");
+}
+async function fetchPackument(pkg) {
+	const url = `${registryBase()}/${pkg.replace("/", "%2F")}`;
+	const res = await fetch(url, { headers: { accept: "application/json" } });
+	if (!res.ok) throw new Error(`registry lookup failed for ${pkg}: HTTP ${res.status} ${res.statusText} (${url})`);
+	return await res.json();
+}
+/**
+* Resolve which daemon version to install: an explicit `--to <version>` (must
+* exist), otherwise the channel's dist-tag (stable → `latest`, rc → `rc`).
+*/
+async function resolveDaemonTarget(opts) {
+	const pkg = await fetchPackument(DAEMON_PKG);
+	const versions = pkg.versions ?? {};
+	let version;
+	if (opts.to) {
+		if (!versions[opts.to]) throw new Error(`${DAEMON_PKG}@${opts.to} does not exist in the registry`);
+		version = opts.to;
+	} else {
+		const tag = opts.channel === "rc" ? "rc" : "latest";
+		const tagged = pkg["dist-tags"]?.[tag];
+		if (!tagged) throw new Error(`${DAEMON_PKG} has no '${tag}' dist-tag in the registry`);
+		version = tagged;
+	}
+	const entry = versions[version];
+	if (!entry?.dist?.tarball) throw new Error(`${DAEMON_PKG}@${version} has no downloadable tarball`);
+	return {
+		version,
+		tarball: entry.dist.tarball,
+		integrity: entry.dist.integrity,
+		shasum: entry.dist.shasum,
+		enginesNode: entry.engines?.node
+	};
+}
+async function downloadTarball(url) {
+	const res = await fetch(url);
+	if (!res.ok) throw new Error(`tarball download failed: HTTP ${res.status} ${res.statusText} (${url})`);
+	return Buffer.from(await res.arrayBuffer());
+}
+/**
+* Verify a downloaded tarball against the registry's `dist.integrity` (SSRI,
+* `sha512-<base64>`), falling back to the legacy `dist.shasum` (sha1 hex). Throws
+* on mismatch or when neither is available (never install unverified bytes).
+*/
+function verifyTarball(buf, target) {
+	if (target.integrity) {
+		const [algo, expected] = target.integrity.split("-", 2);
+		if (!algo || !expected) throw new Error(`malformed integrity string: ${target.integrity}`);
+		const actual = createHash(algo).update(buf).digest("base64");
+		if (actual !== expected) throw new Error(`integrity check failed (${algo}): expected ${expected}, got ${actual}`);
+		return;
+	}
+	if (target.shasum) {
+		const actual = createHash("sha1").update(buf).digest("hex");
+		if (actual !== target.shasum) throw new Error(`shasum check failed: expected ${target.shasum}, got ${actual}`);
+		return;
+	}
+	throw new Error("registry entry has neither integrity nor shasum — refusing to install unverified bytes");
+}
+//#endregion
+//#region src/version-store.ts
+/**
+* The on-disk daemon version store (cli-daemon-split.md §3/§5). Layout under
+* `<root>`:
+*   versions/<v>/        — one extracted, self-contained daemon bundle
+*   current -> versions/<v>  — the active version (atomic symlink)
+*   versions.json        — CLI-private metadata (channel + rollback target)
+*
+* All MUTATING operations here must run inside the version lock (version-lock.ts);
+* the read helpers (`listInstalled`, `currentVersion`, `readMeta`) do not lock —
+* symlink/rename atomicity is enough for readers.
+*/
+const DEFAULT_META = {
+	channel: "stable",
+	previous: null
+};
+function readMeta(root) {
+	const file = versionsJsonPath(root);
+	if (!existsSync(file)) return { ...DEFAULT_META };
+	try {
+		const raw = JSON.parse(readFileSync(file, "utf8"));
+		return {
+			channel: raw.channel === "rc" ? "rc" : "stable",
+			previous: typeof raw.previous === "string" ? raw.previous : null
+		};
+	} catch {
+		return { ...DEFAULT_META };
+	}
+}
+/** Persist metadata atomically (tmp + rename). Call inside the version lock. */
+function writeMeta(root, meta) {
+	const file = versionsJsonPath(root);
+	mkdirSync(dirname(file), { recursive: true });
+	const tmp = `${file}.tmp`;
+	writeFileSync(tmp, JSON.stringify(meta, null, 2) + "\n");
+	renameSync(tmp, file);
+}
+/** Installed version directory names, newest-mtime-irrelevant (sorted for stable output). */
+function listInstalled(root) {
+	const dir = versionsDir(root);
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.endsWith(".tmp")).map((e) => e.name).sort();
+}
+/** The active version (basename of the `current` symlink target), or null. */
+function currentVersion(root) {
+	const link = currentLink(root);
+	try {
+		return basename(readlinkSync(link));
+	} catch {
+		return null;
+	}
+}
+function isInstalled(root, version) {
+	return listInstalled(root).includes(version);
+}
+//#endregion
+//#region src/install.ts
+/**
+* Install a daemon version into the store (cli-daemon-split.md §5.1): resolve from
+* the registry → verify integrity → engines check → extract to `versions/<v>.tmp`
+* → atomic rename to `versions/<v>`. Idempotent: an already-installed version is a
+* no-op success. Must run inside the version lock (version-lock.ts).
+*/
+/** Resolve the version to install/upgrade to, without downloading. */
+function resolveTarget(opts) {
+	return resolveDaemonTarget(opts);
+}
+/**
+* Ensure `target.version` is installed under `versions/<v>`. Returns the version.
+* If already present, returns immediately (idempotent). `onLog` surfaces progress.
+*/
+async function installTarget(root, target, onLog = () => {}) {
+	if (isInstalled(root, target.version)) {
+		onLog(`daemon ${target.version} already installed`);
+		return target.version;
+	}
+	if (!nodeSatisfies(target.enginesNode, process.versions.node)) throw new Error(`daemon ${target.version} requires Node ${target.enginesNode} but this CLI runs on ${process.versions.node} — upgrade Node first`);
+	onLog(`downloading daemon ${target.version}…`);
+	const buf = await downloadTarball(target.tarball);
+	verifyTarball(buf, target);
+	const dest = versionDir(root, target.version);
+	const tmp = `${dest}.tmp`;
+	mkdirSync(versionsDir(root), { recursive: true });
+	rmSync(tmp, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(tmp, { recursive: true });
+	try {
+		execFileSync("tar", [
+			"-xzf",
+			"-",
+			"-C",
+			tmp,
+			"--strip-components=1"
+		], { input: buf });
+		const manifest = JSON.parse(readFileSync(`${tmp}/package.json`, "utf8"));
+		if (!nodeSatisfies(manifest.engines?.node, process.versions.node)) throw new Error(`daemon ${target.version} requires Node ${manifest.engines?.node} but this CLI runs on ${process.versions.node}`);
+		if (!existsSync(`${tmp}/dist/index.js`)) throw new Error(`daemon ${target.version} tarball has no dist/index.js — refusing to install`);
+		if (existsSync(dest)) rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+		else renameSync(tmp, dest);
+	} catch (err) {
+		rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+		throw err;
+	}
+	onLog(`installed daemon ${target.version}`);
+	return target.version;
+}
+//#endregion
+//#region src/health.ts
+const defaultDelay = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+* Sample the service status a few times over `settleMs`; healthy iff it is running
+* with a single stable PID throughout. Injectable `status`/`delay` keep it testable.
+*/
+async function checkServiceHealthy(status, opts = {}) {
+	const samples = Math.max(2, opts.samples ?? 3);
+	const settleMs = opts.settleMs ?? 6e3;
+	const delay = opts.delay ?? defaultDelay;
+	const gap = Math.max(0, Math.floor(settleMs / samples));
+	let firstPid;
+	for (let i = 0; i < samples; i++) {
+		if (i > 0) await delay(gap);
+		const s = await status();
+		if (!s.running) return {
+			healthy: false,
+			reason: `service not running (${s.label})`
+		};
+		if (!s.pid) return {
+			healthy: false,
+			reason: "service running but reported no pid"
+		};
+		if (firstPid === void 0) firstPid = s.pid;
+		else if (s.pid !== firstPid) return {
+			healthy: false,
+			reason: `pid changed ${firstPid} → ${s.pid} (crash-looping)`
+		};
+	}
+	return {
+		healthy: true,
+		reason: `stable pid ${firstPid}`
+	};
+}
+//#endregion
+//#region src/version-ops.ts
+/**
+* Activation + cleanup for the version store (cli-daemon-split.md §5). Both MUTATE
+* and must run inside the version lock (version-lock.ts).
+*/
+/**
+* Atomically point `current` at an installed version (symlink + rename). Records
+* the version it replaced as `previous` (the rollback target). No-op if already
+* current. §5 / §5.4.
+*/
+function useVersion(root, version) {
+	if (!isInstalled(root, version)) throw new Error(`daemon ${version} is not installed — run \`agentconnect version install ${version}\` first`);
+	const prev = currentVersion(root);
+	if (prev === version) return;
+	const link = currentLink(root);
+	const tmp = `${link}.tmp`;
+	rmSync(tmp, { force: true });
+	symlinkSync(`versions/${version}`, tmp);
+	renameSync(tmp, link);
+	if (prev && prev !== version) writeMeta(root, {
+		...readMeta(root),
+		previous: prev
+	});
+}
+/**
+* Remove old installed versions, keeping the newest `keep` prunable ones. `current`
+* and `previous` (the rollback target) are NEVER removed. §5.4.
+*/
+function pruneVersions(root, keep = 2) {
+	const meta = readMeta(root);
+	const cur = currentVersion(root);
+	const protectedSet = new Set([cur, meta.previous].filter((v) => Boolean(v)));
+	const toRemove = listInstalled(root).filter((v) => !protectedSet.has(v)).map((v) => ({
+		v,
+		mtime: statSync(versionDir(root, v)).mtimeMs
+	})).sort((a, b) => b.mtime - a.mtime).slice(keep).map((x) => x.v);
+	for (const v of toRemove) rmSync(versionDir(root, v), {
+		recursive: true,
+		force: true
+	});
+	return toRemove;
+}
+//#endregion
+//#region src/upgrade.ts
+/**
+* `agentconnect upgrade` orchestration (cli-daemon-split.md §5.2): install the
+* target → flip `current` → optionally restart → health-check → auto-rollback on
+* failure. The caller wraps this in the version lock; the steps here assume it is
+* held. Dependencies are injected so the control flow (esp. rollback) is testable
+* without a registry or a real service.
+*/
+function realUpgradeDeps(root, log) {
+	return {
+		resolve: resolveTarget,
+		install: installTarget,
+		serviceInstalled: () => resolveController({ root }).isInstalled(),
+		restartService: async () => {
+			const c = resolveController({ root });
+			await c.down();
+			await c.up();
+		},
+		health: () => checkServiceHealthy(() => resolveController({ root }).status()),
+		log
+	};
+}
+async function upgrade(root, opts, deps) {
+	const meta = readMeta(root);
+	const channel = opts.channel ?? meta.channel;
+	const target = await deps.resolve({
+		to: opts.to,
+		channel
+	});
+	await deps.install(root, target, deps.log);
+	const before = currentVersion(root);
+	if (before === target.version && !opts.restart) {
+		deps.log(`already on ${target.version}`);
+		return;
+	}
+	useVersion(root, target.version);
+	if (opts.channel && opts.channel !== meta.channel) writeMeta(root, {
+		...readMeta(root),
+		channel: opts.channel
+	});
+	deps.log(`current → ${target.version}`);
+	if (!opts.restart) {
+		deps.log("not restarting (pass --restart to apply now); the new version takes effect on the next daemon restart");
+		return;
+	}
+	if (!deps.serviceInstalled()) {
+		deps.log("no OS service installed — current switched, but nothing to restart (foreground run applies it on relaunch)");
+		return;
+	}
+	await deps.restartService();
+	const h = await deps.health();
+	if (h.healthy) {
+		deps.log(`upgraded to ${target.version} — healthy (${h.reason})`);
+		return;
+	}
+	deps.log(`health check failed (${h.reason}) — rolling back`);
+	if (!before) throw new Error(`upgrade to ${target.version} failed its health check and there is no previous version to roll back to`);
+	useVersion(root, before);
+	await deps.restartService();
+	throw new Error(`upgrade to ${target.version} failed its health check — rolled back to ${before}`);
+}
+//#endregion
+//#region src/version-lock.ts
+/**
+* Root-scoped inter-process writer lock for the version store (cli-daemon-split.md
+* §5.5). Every MUTATING version command (install / use / prune / upgrade), whether
+* a local invocation or the CLI a daemon spawns for a remote upgrade, holds this
+* lock across its whole transaction so they can't corrupt `current` /
+* `versions.json` by interleaving.
+*
+* Distinct from the daemon singleton lock (packages/daemon/src/lock.ts): that one
+* is held by a running daemon (and is held during a remote upgrade), whereas this
+* guards the version store — different resources, different locks.
+*
+* Stale recovery: holder LIVENESS is the only preemption criterion — never lock
+* age. `kill(pid, 0)` → ESRCH means dead; any other errno means alive. A recorded
+* process start time guards against PID reuse (a live PID whose start time no
+* longer matches is a different process, so the lock is stale).
+*/
+/** Best-effort process start time, to distinguish a reused PID. Empty on failure. */
+function procStartTime(pid) {
+	try {
+		return execFileSync("ps", [
+			"-o",
+			"lstart=",
+			"-p",
+			String(pid)
+		], { encoding: "utf8" }).trim();
+	} catch {
+		return "";
+	}
+}
+/** True if the PID is a live process. ESRCH ⇒ dead; EPERM/other ⇒ alive. */
+function isAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err.code !== "ESRCH";
+	}
+}
+/** A held lock is stale (safe to preempt) only if its holder process is gone or
+*  its PID has been reused by a different process. */
+function isStale(holder) {
+	if (!isAlive(holder.pid)) return true;
+	const now = procStartTime(holder.pid);
+	if (holder.procStart && now && holder.procStart !== now) return true;
+	return false;
+}
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+const POLL_MS = 500;
+const DEFAULT_WAIT_MS = 15 * 6e4;
+const STALE_WARN_MS = 30 * 6e4;
+function tryClaim(path, op) {
+	let fd;
+	try {
+		fd = openSync(path, "wx");
+	} catch (err) {
+		if (err.code === "EEXIST") return false;
+		throw err;
+	}
+	const content = {
+		pid: process.pid,
+		op,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		procStart: procStartTime(process.pid)
+	};
+	try {
+		writeSync(fd, JSON.stringify(content));
+	} finally {
+		closeSync(fd);
+	}
+	return true;
+}
+function readHolder(path) {
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof raw.pid !== "number") return null;
+		return {
+			pid: raw.pid,
+			op: typeof raw.op === "string" ? raw.op : "unknown",
+			startedAt: typeof raw.startedAt === "string" ? raw.startedAt : "",
+			procStart: typeof raw.procStart === "string" ? raw.procStart : ""
+		};
+	} catch {
+		return null;
+	}
+}
+/** Atomically move a stale lock aside so a fresh claim can be made. Racing
+*  preemptors are fine: the rename or the subsequent O_EXCL claim decides one winner. */
+function preempt(path) {
+	try {
+		renameSync(path, `${path}.stale`);
+	} catch {}
+}
+/**
+* Run `fn` while holding the version-store lock. `wait: true` blocks (polling)
+* until the lock frees or `waitMs` elapses; `wait: false` fails fast if a live
+* process holds it. The lock is always released if we own it.
+*/
+async function withVersionLock(root, op, fn, opts = {}) {
+	const path = versionsLockPath(root);
+	const wait = opts.wait ?? false;
+	const deadline = Date.now() + (opts.waitMs ?? DEFAULT_WAIT_MS);
+	let warned = false;
+	for (;;) {
+		if (tryClaim(path, op)) break;
+		const holder = readHolder(path);
+		if (!holder || isStale(holder)) {
+			preempt(path);
+			continue;
+		}
+		if (!wait) throw new Error(`another version operation is in progress (pid ${holder.pid}, op ${holder.op}, since ${holder.startedAt}) — retry once it finishes`);
+		if (!warned && Date.now() - new Date(holder.startedAt).getTime() > STALE_WARN_MS) {
+			console.error(`agentconnect: waiting on a long-running version lock (pid ${holder.pid}, op ${holder.op})`);
+			warned = true;
+		}
+		if (Date.now() > deadline) throw new Error(`timed out waiting for the version lock held by pid ${holder.pid} (op ${holder.op})`);
+		await delay(POLL_MS);
+	}
+	try {
+		return await fn();
+	} finally {
+		if (readHolder(path)?.pid === process.pid) try {
+			unlinkSync(path);
+		} catch {}
+	}
+}
+//#endregion
+//#region src/version-commands.ts
+/**
+* Command handlers for `agentconnect version …` + `upgrade` (cli-daemon-split.md
+* §5). Every mutating handler runs its whole transaction inside the version lock
+* (§5.5); `list` reads without locking. These are thin over the version-store /
+* install / upgrade modules and are what index.ts wires to commander.
+*/
+const note = (m) => console.log(m);
+function versionList(root) {
+	const meta = readMeta(root);
+	const installed = listInstalled(root);
+	const cur = currentVersion(root);
+	console.log(`channel: ${meta.channel}`);
+	if (installed.length === 0) {
+		console.log("installed: none — run `agentconnect version install --channel stable`");
+		return;
+	}
+	console.log("installed:");
+	for (const v of installed) {
+		const tags = [v === cur ? "current" : "", v === meta.previous ? "previous" : ""].filter(Boolean).join(", ");
+		console.log(`  ${v}${tags ? `  (${tags})` : ""}`);
+	}
+}
+async function versionInstall(root, opts) {
+	await withVersionLock(root, "install", async () => {
+		const channel = opts.channel ?? readMeta(root).channel;
+		await installTarget(root, await resolveTarget({
+			to: opts.to,
+			channel
+		}), note);
+		if (opts.channel) writeMeta(root, {
+			...readMeta(root),
+			channel: opts.channel
+		});
+	});
+}
+async function versionUse(root, version) {
+	await withVersionLock(root, "use", () => {
+		useVersion(root, version);
+		note(`current → ${version}`);
+	});
+}
+async function versionPrune(root, keep) {
+	await withVersionLock(root, "prune", () => {
+		const removed = pruneVersions(root, keep);
+		note(removed.length ? `pruned ${removed.length}: ${removed.join(", ")}` : "nothing to prune");
+	}, { wait: true });
+}
+async function runUpgrade(root, opts) {
+	await withVersionLock(root, "upgrade", () => upgrade(root, opts, realUpgradeDeps(root, note)), { wait: true });
+}
+//#endregion
 //#region src/index.ts
 /** Light scan for the global `--root` flag before commander parses — needed by
 *  the delegation/run paths (which never build a commander program) and by the
@@ -14166,16 +14742,45 @@ async function main() {
 			fail("login", err);
 		}
 	});
-	const notYet = (name) => {
-		console.error(`agentconnect ${name}: daemon version management arrives in P2 (not yet implemented)`);
-		return process.exit(1);
-	};
-	const version = program.command("version").description("Manage installed daemon versions (P2)");
-	version.command("list").description("List installed daemon versions (P2)").action(() => notYet("version list"));
-	version.command("install <version>").description("Download and unpack a daemon version (P2)").action(() => notYet("version install"));
-	version.command("use <version>").description("Activate an installed daemon version (P2)").action(() => notYet("version use"));
-	version.command("prune").description("Remove old daemon versions (P2)").action(() => notYet("version prune"));
-	program.command("upgrade").description("Install the latest daemon version and restart (P2)").action(() => notYet("upgrade"));
+	const asChannel = (c) => c === "stable" || c === "rc" ? c : c === void 0 ? void 0 : fail("version", /* @__PURE__ */ new Error(`unknown channel '${c}' (use stable|rc)`));
+	const version = program.command("version").description("Manage installed daemon versions");
+	version.action(() => versionList(root));
+	version.command("list").description("List installed daemon versions and the active one").action(() => versionList(root));
+	version.command("install [version]").description("Download and unpack a daemon version (defaults to the channel dist-tag)").option("--channel <channel>", "stable|rc (default: the stored channel)").action(async (v, o) => {
+		try {
+			await versionInstall(root, {
+				to: v,
+				channel: asChannel(o.channel)
+			});
+		} catch (err) {
+			fail("version install", err);
+		}
+	});
+	version.command("use <version>").description("Activate an installed daemon version (does not restart)").action(async (v) => {
+		try {
+			await versionUse(root, v);
+		} catch (err) {
+			fail("version use", err);
+		}
+	});
+	version.command("prune").description("Remove old daemon versions, keeping the newest N (current/previous always kept)").option("--keep <n>", "how many prunable versions to keep", "2").action(async (o) => {
+		try {
+			await versionPrune(root, Math.max(0, Number(o.keep) || 0));
+		} catch (err) {
+			fail("version prune", err);
+		}
+	});
+	program.command("upgrade").description("Install the latest daemon version, switch to it, and (with --restart) restart + health-check").option("--to <version>", "upgrade to a specific version instead of the channel latest").option("--channel <channel>", "stable|rc (default: the stored channel)").option("--restart", "restart the service now and roll back if it fails its health check").action(async (o) => {
+		try {
+			await runUpgrade(root, {
+				to: o.to,
+				channel: asChannel(o.channel),
+				restart: Boolean(o.restart)
+			});
+		} catch (err) {
+			fail("upgrade", err);
+		}
+	});
 	await program.parseAsync();
 }
 try {