@agentconnect.md/daemon 1.0.0-rc.37 → 1.0.0-rc.39

package/dist/index.js

@@ -9,7 +9,7 @@ import process$1 from "node:process";
 import { stripVTControlCharacters } from "node:util";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline";
-import { freemem, homedir, hostname, loadavg, totalmem, type } from "node:os";
+import { cpus, freemem, homedir, hostname, totalmem, type } from "node:os";
 import { spawn as spawn$1 } from "child_process";
 import { Readable, Writable } from "node:stream";
 import { randomBytes, randomUUID } from "node:crypto";
@@ -7376,11 +7376,17 @@ const ConfigSchema = object({
 		maxAgents: number().int().default(8),
 		maxConcurrentSessions: number().int().default(32),
 		agentIdleTimeoutMs: number().int().default(9e5),
+		idleSweepMs: number().int().default(6e4),
+		shutdownDrainMs: number().int().default(25e3),
+		cancelBackstopMs: number().int().default(3e4),
 		maxAttachmentBytes: number().int().default(8 * 1024 * 1024)
 	}).default({
 		maxAgents: 8,
 		maxConcurrentSessions: 32,
 		agentIdleTimeoutMs: 9e5,
+		idleSweepMs: 6e4,
+		shutdownDrainMs: 25e3,
+		cancelBackstopMs: 3e4,
 		maxAttachmentBytes: 8 * 1024 * 1024
 	})
 });
@@ -7587,6 +7593,19 @@ function cachedRuntimeNames(root) {
 	for (const [id, entry] of Object.entries(doc.agents)) if (entry.name) out[id] = entry.name;
 	return out;
 }
+/**
+* Runtime versions (registry id -> `version`) read from the local cache. Used to
+* stamp the `facts/runtime-profile` the daemon reports per installed runtime.
+* Entries with no `version` are omitted (callers fall back to ''). `{}` when no
+* cached registry doc exists.
+*/
+function cachedRuntimeVersions(root) {
+	const doc = readCachedDoc(root);
+	if (!doc) return {};
+	const out = {};
+	for (const [id, entry] of Object.entries(doc.agents)) if (entry.version) out[id] = entry.version;
+	return out;
+}
 async function defaultRuntimes(root, opts = {}) {
 	const cached = (opts.mode ?? "blocking") === "cache-first" ? readCachedDoc(root) : null;
 	let doc;
@@ -16975,10 +16994,29 @@ var AcpHost = class {
 	async cancel(sessionId) {
 		await this.conn.agent.notify(methods.agent.session.cancel, { sessionId });
 	}
-	async stop() {
-		if (!this.child) return;
-		this.child.kill("SIGTERM");
-		await new Promise((resolve) => this.child.once("exit", () => resolve()));
+	/** Stop the adapter child: SIGTERM, then escalate to SIGKILL if it hasn't exited
+	*  within `deadlineMs` (a buggy/hung agent must never block daemon shutdown or an
+	*  idle reap). Idempotent — the child handle is cleared up front so a concurrent
+	*  stop (drain + reconcile racing) is a no-op rather than a double-kill. */
+	async stop(deadlineMs = 5e3) {
+		const child = this.child;
+		if (!child) return;
+		this.child = void 0;
+		child.kill("SIGTERM");
+		await new Promise((resolve) => {
+			let settled = false;
+			const done = () => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				resolve();
+			};
+			const timer = setTimeout(() => {
+				this.opts.log?.warn(`acp: child ignored SIGTERM after ${deadlineMs}ms — sending SIGKILL`);
+				child.kill("SIGKILL");
+			}, deadlineMs);
+			child.once("exit", done);
+		});
 	}
 };
 //#endregion
@@ -23361,6 +23399,27 @@ var LocalStore = class {
            acpSessionId=excluded.acpSessionId, state=excluded.state,
            lastDeliveredTs=excluded.lastDeliveredTs, updatedAt=excluded.updatedAt`).run(rec);
 	}
+	/** Targeted state transition for an existing session (§7.3), stamping `updatedAt`
+	*  so the change counts as activity for the TTL/idle clocks. No-op if the key is
+	*  unknown (the row is created by the SessionManager on first turn). */
+	setSessionState(key, state, updatedAt) {
+		this.db.prepare("UPDATE sessions SET state = ?, updatedAt = ? WHERE key = ?").run(state, updatedAt, key);
+	}
+	/** Most-recent activity across an agent's non-closed sessions (epoch ms), or null
+	*  if it has none. Drives idle-host reaping (#111): a host with no recent session
+	*  activity AND no in-flight turn is past its idle window. */
+	agentLastActivityTs(agentId) {
+		return this.db.prepare("SELECT MAX(updatedAt) AS ts FROM sessions WHERE agentId = ? AND state != 'closed'").get(agentId)?.ts ?? null;
+	}
+	/** §7.3 TTL close: move every `idle` session untouched since `now - ttlMs` to
+	*  `closed`, returning the rows closed (for logging). `prompting`/`cancelling`
+	*  sessions are never closed — a live turn keeps the thread open. */
+	closeIdleSessions(now, ttlMs) {
+		const cutoff = now - ttlMs;
+		const rows = this.db.prepare("SELECT key, channel, thread, agentId FROM sessions WHERE state = 'idle' AND updatedAt < ?").all(cutoff);
+		if (rows.length) this.db.prepare("UPDATE sessions SET state = 'closed' WHERE state = 'idle' AND updatedAt < ?").run(cutoff);
+		return rows;
+	}
 	appendTranscript(e) {
 		this.db.prepare("INSERT OR IGNORE INTO transcript (channel, thread, ts, sender, kind, text) VALUES (@channel, @thread, @ts, @sender, @kind, @text)").run(e);
 	}
@@ -23512,10 +23571,13 @@ var SessionManager = class {
 		} else if (host.hasSession?.(rec.acpSessionId) === false) {
 			const cwd = await prepareWorkspace(agent);
 			let resumed = false;
-			if (host.loadSupported?.()) try {
-				await host.loadSession(rec.acpSessionId, cwd);
-				resumed = true;
-			} catch {}
+			if (host.loadSupported?.()) {
+				this.deps.store.setSessionState(key, "resuming", Date.now());
+				try {
+					await host.loadSession(rec.acpSessionId, cwd);
+					resumed = true;
+				} catch {}
+			}
 			if (!resumed) {
 				const mcpServers = this.deps.mcpServersFor?.({
 					agent,
@@ -81643,6 +81705,7 @@ var CpClient = class {
 		this.heartbeatMs = ok.heartbeatSec > 0 ? ok.heartbeatSec * 1e3 : this.deps.heartbeatDefaultMs;
 		this.armHeartbeat();
 		this.deps.log.info(`cp: READY (epoch=${this.sessionEpoch}, routingEpoch=${this.routingEpoch})`);
+		for (const profile of this.deps.runtimeProfiles()) this.transport?.send(encode(buildEnvelope("facts/runtime-profile", profile)));
 	}
 	request(type, payload) {
 		const frame = buildEnvelope(type, payload);
@@ -81697,14 +81760,13 @@ var CpClient = class {
 	}
 	armHeartbeat() {
 		this.heartbeatTimer = this.deps.clock.setTimeout(() => {
-			if (this.state !== "READY") return;
-			this.transport?.send(encode(buildEnvelope("heartbeat", {
+			if (this.state === "READY") this.transport?.send(encode(buildEnvelope("heartbeat", {
 				load: this.deps.loadSnapshot(),
 				health: "ok",
 				activeSessions: this.deps.activeSessions(),
 				degradedScopes: this.deps.degradedScopes?.() ?? []
 			})));
-			this.armHeartbeat();
+			if (this.state === "READY" || this.state === "DRAINING") this.armHeartbeat();
 		}, this.heartbeatMs);
 	}
 	stopHeartbeat() {
@@ -81751,13 +81813,36 @@ var CpClient = class {
 			case "agent/remove":
 				this.deps.configApply.applyAgentRemove(frame.payload.agentId);
 				return;
-			case "agent/launch":
-			case "agent/stop":
-			case "agent/prompt":
-			case "daemon/drain":
+			case "agent/launch": {
+				const launch = frame.payload;
+				this.deps.configApply.applyAgentLaunch(launch).then((launched) => this.reply(frame, "agent/launched", launched)).catch((err) => this.sendError(frame.id, "INTERNAL", `agent/launch failed: ${err.message}`, false));
+				return;
+			}
+			case "agent/stop": {
+				const stop = frame.payload;
+				this.deps.configApply.applyAgentStop(stop).then((ack) => this.reply(frame, "ack", ack)).catch((err) => this.sendError(frame.id, "INTERNAL", `agent/stop failed: ${err.message}`, false));
+				return;
+			}
+			case "daemon/drain": {
+				const drain = frame.payload;
+				this.state = "DRAINING";
+				this.deps.configApply.applyDaemonDrain(drain, (p) => this.emit("drain/progress", p)).then((done) => {
+					this.reply(frame, "drain/done", done);
+					if (this.state === "DRAINING") this.state = "READY";
+				}).catch((err) => {
+					this.sendError(frame.id, "INTERNAL", `drain failed: ${err.message}`, false);
+					if (this.state === "DRAINING") this.state = "READY";
+				});
+				return;
+			}
 			case "daemon/restart":
+				this.reply(frame, "daemon/control/ack", this.deps.configApply.applyDaemonRestart(frame.payload));
+				return;
 			case "daemon/upgrade":
-				this.sendError(frame.id, "INTERNAL", `${frame.type} not implemented`, false);
+				this.reply(frame, "daemon/control/ack", this.deps.configApply.applyDaemonUpgrade(frame.payload));
+				return;
+			case "agent/prompt":
+				this.sendError(frame.id, "INTERNAL", "agent/prompt not implemented", false);
 				return;
 			default:
 				this.deps.log.debug(`cp: ignoring ${frame.type}`);
@@ -81767,6 +81852,10 @@ var CpClient = class {
 	reply(req, type, payload) {
 		this.transport?.send(encode(buildEnvelope(type, payload, { corr: req.id })));
 	}
+	/** Emit an uncorrelated EVT (e.g. `drain/progress`). */
+	emit(type, payload) {
+		this.transport?.send(encode(buildEnvelope(type, payload)));
+	}
 };
 //#endregion
 //#region src/cp/cp-cron.ts
@@ -82047,6 +82136,37 @@ function formatErr(err) {
 }
 const MAX_QUEUED_PER_SESSION = 10;
 const IDLE_FLUSH_MS = 2e3;
+/** Build the wire SessionKey (protocol §5) for a pending turn — what `drain/done`
+*  reports as released so the CP may reassign it. Uses the real `thread` (absent for
+*  a channel-root message), NOT `statusThread` (which falls back to msgId): the CP
+*  keys assignments by `thread ?? "-"`, so reporting the msgId would miss the match. */
+function pendingSessionKey(p) {
+	const platform = p.platform;
+	return p.thread !== void 0 ? {
+		platform,
+		channel: p.channel,
+		thread: p.thread
+	} : {
+		platform,
+		channel: p.channel
+	};
+}
+/** Aggregate CPU time across all cores — busy vs idle jiffies. CPU utilization is the
+*  ratio of busy-time DELTAS between two of these samples (a single sample is meaningless;
+*  it's cumulative since boot). This is real utilization, NOT the run-queue load average. */
+function cpuTotals() {
+	let idle = 0;
+	let busy = 0;
+	for (const c of cpus()) {
+		const t = c.times;
+		idle += t.idle;
+		busy += t.user + t.nice + t.sys + t.irq;
+	}
+	return {
+		idle,
+		busy
+	};
+}
 var Daemon = class {
 	opts;
 	store;
@@ -82065,15 +82185,26 @@ var Daemon = class {
 	cfg;
 	log = makeLogger("info");
 	root = "";
+	lastCpu = cpuTotals();
 	runtimes = {};
 	runtimeNames = {};
+	runtimeVersions = {};
 	cpClient;
 	cpCrons;
 	cpAgents;
 	botUserIds = {};
 	cpRouting;
+	clock;
+	requestExit;
+	draining = false;
+	drainingAgents = /* @__PURE__ */ new Set();
+	hostStopping = /* @__PURE__ */ new Map();
+	idleSweepTimer;
+	cancelTimers = /* @__PURE__ */ new Map();
 	constructor(opts = {}) {
 		this.opts = opts;
+		this.clock = opts.clock ?? systemClock;
+		this.requestExit = opts.requestExit ?? ((code) => process.exit(code));
 	}
 	async start() {
 		const root = resolveRoot(this.opts.root);
@@ -82103,6 +82234,7 @@ var Daemon = class {
 		});
 		this.runtimes = installedRuntimes(resolvedRuntimes);
 		this.runtimeNames = cachedRuntimeNames(root);
+		this.runtimeVersions = cachedRuntimeVersions(root);
 		this.log.info(`runtimes ready: ${Object.keys(this.runtimes).join(", ") || "(none)"}`);
 		const skipped = Object.keys(resolvedRuntimes).filter((id) => !this.runtimes[id]);
 		if (skipped.length) this.log.info(`runtimes not installed (skipped): ${skipped.join(", ")}`);
@@ -82213,6 +82345,7 @@ var Daemon = class {
 		this.watcher.on("add", debounced).on("change", debounced).on("unlink", debounced);
 		this.log.info(`watching ${this.agentsDir} for agent changes`);
 		this.startCpClient(root);
+		this.armIdleSweep();
 		this.log.info("daemon ready");
 	}
 	loadAgentList() {
@@ -82385,6 +82518,10 @@ var Daemon = class {
 	}
 	seenMsgIds = /* @__PURE__ */ new Set();
 	onInbound(msg) {
+		if (this.draining) {
+			this.log.debug(`routing: dropping inbound ${msg.msgId} (daemon draining)`);
+			return;
+		}
 		if (this.seenMsgIds.has(msg.msgId)) {
 			this.log.debug(`routing: duplicate ${msg.msgId} ignored`);
 			return;
@@ -82402,6 +82539,10 @@ var Daemon = class {
 			this.log.debug(`routing: dropped message in ch=${msg.channel} (no agent matched — not a mention of a known bot, not a subscribed 'all' channel, not a thread/DM hit)`);
 			return;
 		}
+		if (this.drainingAgents.has(result.agentId)) {
+			this.log.debug(`routing: dropping ${msg.msgId} for agent "${result.agentId}" (draining)`);
+			return;
+		}
 		this.log.info(`routing: ch=${msg.channel} → agent "${result.agentId}" (integration ${result.integrationId})`);
 		this.dispatch(result.agentId, msg, result.integrationId).catch((err) => this.log.error(`dispatch failed for agent "${result.agentId}": ${formatErr(err)}`));
 	}
@@ -82471,7 +82612,8 @@ var Daemon = class {
 		}
 		const conn = this.replyConnFor(target.agentId, target.integrationId);
 		const thread = msg.thread ?? msg.msgId;
-		const acpSessionId = this.store.getSession(sessionKey(msg.platform, msg.channel, thread, target.agentId))?.acpSessionId;
+		const key = sessionKey(msg.platform, msg.channel, thread, target.agentId);
+		const acpSessionId = this.store.getSession(key)?.acpSessionId;
 		const inflight = !!(acpSessionId && this.pending.has(acpSessionId));
 		if (command.kind === "stop") {
 			if (!inflight) {
@@ -82480,7 +82622,9 @@ var Daemon = class {
 			}
 			this.queued.delete(acpSessionId);
 			this.log.info(`command: stop → agent "${target.agentId}" session ${acpSessionId}`);
+			this.store.setSessionState(key, "cancelling", this.clock.now());
 			this.hosts.get(target.agentId)?.cancel(acpSessionId).catch((err) => this.log.error(`command stop: cancel failed: ${err.message}`));
+			this.armCancelBackstop(target.agentId, acpSessionId, key);
 			conn?.postMessage(msg.channel, "🛑 Stopped.", thread);
 			return;
 		}
@@ -82543,22 +82687,40 @@ var Daemon = class {
 		return [...out];
 	}
 	async dispatch(agentId, msg, integrationId) {
+		if (this.draining || this.drainingAgents.has(agentId)) {
+			this.log.debug(`dispatch: skipped for agent "${agentId}" (draining)`);
+			return;
+		}
 		const conv = new OutputConverger(this.agents.get(agentId).output.mode);
 		const rec = new TranscriptRecorder();
 		const replyConn = this.replyConnFor(agentId, integrationId);
 		const wasRunning = this.hostStarts.has(agentId);
 		const statusThread = msg.thread ?? msg.msgId;
+		const key = sessionKey(msg.platform, msg.channel, statusThread, agentId);
 		replyConn?.setStatus(msg.channel, statusThread, wasRunning ? "is thinking…" : "is starting up…");
-		const { sessionId, blocks } = await this.sessions.handle(agentId, msg);
+		let handled;
+		try {
+			handled = await this.sessions.handle(agentId, msg);
+		} catch (err) {
+			this.store.setSessionState(key, "idle", this.clock.now());
+			throw err;
+		}
+		const { sessionId, blocks } = handled;
+		let resolveDone;
+		const done = new Promise((r) => resolveDone = r);
 		const p = {
 			conv,
 			rec,
 			agentId,
+			platform: msg.platform,
+			sessionKey: key,
 			channel: msg.channel,
 			thread: msg.thread,
 			statusThread,
 			conn: replyConn,
-			applyChain: Promise.resolve()
+			applyChain: Promise.resolve(),
+			done,
+			resolveDone
 		};
 		this.pending.set(sessionId, p);
 		try {
@@ -82573,9 +82735,35 @@ var Daemon = class {
 		} finally {
 			this.clearIdle(p);
 			this.pending.delete(sessionId);
+			this.store.setSessionState(key, "idle", this.clock.now());
+			this.clearCancelBackstop(sessionId);
+			p.resolveDone();
 		}
 		this.flushQueued(agentId, sessionId, integrationId);
 	}
+	/** After `!stop` sends session/cancel, give the agent `cancelBackstopMs` to yield.
+	*  If the turn is still in flight when the timer fires, the agent ignored the
+	*  cancel — force-stop its host (the only hard kill available) so the session
+	*  can't be stuck in `cancelling` forever. dispatch's finally clears this timer
+	*  the moment the turn yields on its own. */
+	armCancelBackstop(agentId, acpSessionId, key) {
+		this.clearCancelBackstop(acpSessionId);
+		const ms = this.cfg.limits.cancelBackstopMs;
+		this.cancelTimers.set(acpSessionId, this.clock.setTimeout(() => {
+			this.cancelTimers.delete(acpSessionId);
+			if (!this.pending.has(acpSessionId)) return;
+			this.log.warn(`command stop: agent "${agentId}" ignored session/cancel for ${ms}ms — force-stopping host (session ${acpSessionId})`);
+			this.stopHost(agentId, 0);
+			this.store.setSessionState(key, "idle", this.clock.now());
+		}, ms));
+	}
+	clearCancelBackstop(acpSessionId) {
+		const t = this.cancelTimers.get(acpSessionId);
+		if (t !== void 0) {
+			this.clock.clearTimeout(t);
+			this.cancelTimers.delete(acpSessionId);
+		}
+	}
 	/**
 	* Apply one converger action against the session's Slack connection:
 	*  - set-status → assistant.threads.setStatus (best-effort; '' clears)
@@ -82664,6 +82852,8 @@ var Daemon = class {
 		});
 	}
 	async ensureHostAsync(agentId) {
+		const stopping = this.hostStopping.get(agentId);
+		if (stopping) await stopping;
 		const host = this.ensureHost(agentId, this.cfg);
 		let p = this.hostStarts.get(agentId);
 		if (!p) {
@@ -82677,6 +82867,171 @@ var Daemon = class {
 		const intId = integrationId ?? this.agents.get(agentId)?.integrations[0]?.id;
 		return intId ? this.connByIntegration.get(intId) : void 0;
 	}
+	/** Stop and evict an ACP adapter child, returning the agent to `provisioned`
+	*  (config kept; the next message lazily re-spawns it). Idempotent. The teardown
+	*  is registered in `hostStopping` so a concurrent ensureHostAsync waits for it
+	*  instead of spawning a second live child. */
+	async stopHost(agentId, deadlineMs) {
+		const host = this.hosts.get(agentId);
+		this.hosts.delete(agentId);
+		this.hostStarts.delete(agentId);
+		if (!host) return;
+		const stop = host.stop(deadlineMs).finally(() => {
+			if (this.hostStopping.get(agentId) === stop) this.hostStopping.delete(agentId);
+		});
+		this.hostStopping.set(agentId, stop);
+		await stop;
+	}
+	/** Recurring idle sweep (§7.2/§7.3): reap idle adapter children and TTL-close
+	*  idle sessions. Driven by the injected Clock so a FakeClock advances it in tests. */
+	armIdleSweep() {
+		const interval = this.cfg.limits.idleSweepMs;
+		if (interval <= 0) return;
+		this.idleSweepTimer = this.clock.setTimeout(() => {
+			this.idleSweepTimer = void 0;
+			try {
+				this.sweepIdle();
+			} catch (err) {
+				this.log.error(`idle sweep failed: ${formatErr(err)}`);
+			}
+			if (!this.draining) this.armIdleSweep();
+		}, interval);
+	}
+	sweepIdle() {
+		const now = this.clock.now();
+		const ttl = this.cfg.limits.agentIdleTimeoutMs;
+		const closed = this.store.closeIdleSessions(now, ttl);
+		if (closed.length) this.log.info(`idle: TTL-closed ${closed.length} session(s) (>${Math.round(ttl / 1e3)}s)`);
+		for (const [agentId] of [...this.hosts]) {
+			if (this.drainingAgents.has(agentId)) continue;
+			if ([...this.pending.values()].some((p) => p.agentId === agentId)) continue;
+			const last = this.store.agentLastActivityTs(agentId) ?? 0;
+			if (now - last <= ttl) continue;
+			this.log.info(`idle: reclaiming host "${agentId}" (idle ${Math.round((now - last) / 1e3)}s) → provisioned`);
+			this.stopHost(agentId).catch((err) => this.log.error(`idle: stop host "${agentId}" failed: ${formatErr(err)}`));
+		}
+	}
+	/** Race `work` against a Clock-driven deadline, always clearing the timer so a
+	*  finished drain never leaves a dangling timer holding the process open. */
+	async raceDeadline(work, ms) {
+		const delay = Math.min(Math.max(0, ms), 2147483647);
+		let handle;
+		const timeout = new Promise((resolve) => {
+			handle = this.clock.setTimeout(() => resolve("timeout"), delay);
+		});
+		try {
+			return await Promise.race([work.then(() => "done"), timeout]);
+		} finally {
+			if (handle !== void 0) this.clock.clearTimeout(handle);
+		}
+	}
+	/**
+	* §5.3 drain: gate new turns for the scope, await in-flight turns up to
+	* `deadlineMs` (emitting `drain/progress` as each yields), then cancel any
+	* straggler past the deadline. Returns BOTH the in-scope set (`matched`) and the
+	* subset that actually finished (`drained`). The caller decides which to report
+	* as released: a session is only safe to release once it is genuinely no longer
+	* being served — either it drained, or the caller force-stops its host. Reporting
+	* a still-running straggler would let the CP reassign it and double-serve.
+	*/
+	async drainScope(scope, deadlineMs, onProgress) {
+		const match = (p) => {
+			if (scope.kind === "daemon") return true;
+			if (scope.kind === "agent") return p.agentId === scope.agentId;
+			const k = scope.sessionKey;
+			return p.platform === k.platform && p.channel === k.channel && (k.thread === void 0 || p.statusThread === k.thread);
+		};
+		if (scope.kind === "daemon") this.draining = true;
+		else if (scope.kind === "agent") this.drainingAgents.add(scope.agentId);
+		const keyOf = (sk) => `${sk.platform}:${sk.channel}:${sk.thread ?? "-"}`;
+		const targets = [...this.pending.entries()].filter(([, p]) => match(p));
+		const matched = /* @__PURE__ */ new Map();
+		for (const [, p] of targets) matched.set(keyOf(pendingSessionKey(p)), pendingSessionKey(p));
+		if (targets.length) this.log.info(`drain[${scope.kind}]: awaiting ${targets.length} turn(s) (deadline ${Math.round(deadlineMs / 1e3)}s)`);
+		let settled = false;
+		const drained = /* @__PURE__ */ new Map();
+		let remaining = targets.length;
+		const work = Promise.all(targets.map(([, p]) => p.done.then(() => {
+			const sk = pendingSessionKey(p);
+			drained.set(keyOf(sk), sk);
+			remaining--;
+			if (!settled) onProgress?.({
+				remaining,
+				drained: [...drained.values()]
+			});
+		})));
+		const res = await this.raceDeadline(work, deadlineMs);
+		settled = true;
+		if (res === "timeout") for (const [sid, p] of this.pending) {
+			if (!match(p)) continue;
+			this.log.warn(`drain[${scope.kind}]: cancelling straggler turn (session ${sid})`);
+			await this.hosts.get(p.agentId)?.cancel(sid).catch(() => {});
+		}
+		return {
+			matched: [...matched.values()],
+			drained: [...drained.values()]
+		};
+	}
+	/** Handle a CP `daemon/drain` (§5.3). A bare drain is a rebalance: after
+	*  releasing sessions the daemon reclaims hosts and re-opens its gate (a teardown
+	*  arrives separately via daemon/restart). */
+	async runDrain(drain, onProgress) {
+		const deadlineMs = Math.max(0, new Date(drain.deadline).getTime() - this.clock.now());
+		const { matched, drained } = await this.drainScope(drain.scope, deadlineMs, onProgress);
+		let released;
+		if (drain.scope.kind === "daemon") {
+			for (const id of [...this.hosts.keys()]) await this.stopHost(id);
+			this.draining = false;
+			released = matched;
+		} else if (drain.scope.kind === "agent") {
+			await this.stopHost(drain.scope.agentId);
+			this.drainingAgents.delete(drain.scope.agentId);
+			released = matched;
+		} else released = drained;
+		this.log.info(`drain[${drain.scope.kind}]: done — released ${released.length} session(s)`);
+		return { released };
+	}
+	/** `agent/stop` (§8.2): drain the agent's in-flight turns, stop its host, and
+	*  leave it gated so it stays down until a matching `agent/launch` revives it. */
+	async stopAgent(agentId) {
+		await this.drainScope({
+			kind: "agent",
+			agentId
+		}, this.cfg.limits.shutdownDrainMs);
+		await this.stopHost(agentId);
+	}
+	/** §2.5 SIGTERM / daemon shutdown: gate new turns, then await in-flight turns up
+	*  to `shutdownDrainMs`, cancelling stragglers. Safe to call repeatedly. */
+	async drainForShutdown() {
+		this.draining = true;
+		const live = [...this.pending.values()];
+		if (live.length === 0) return;
+		const deadlineMs = this.cfg.limits.shutdownDrainMs;
+		this.log.info(`shutdown: draining ${live.length} in-flight turn(s) (deadline ${Math.round(deadlineMs / 1e3)}s)`);
+		if (await this.raceDeadline(Promise.all(live.map((p) => p.done)), deadlineMs) === "timeout") {
+			this.log.warn(`shutdown: deadline hit with ${this.pending.size} turn(s) still in flight — cancelling`);
+			for (const [sid, p] of this.pending) await this.hosts.get(p.agentId)?.cancel(sid).catch(() => {});
+		}
+	}
+	/** daemon/restart + daemon/upgrade (§8.3): ack now, then drain + stop + exit so
+	*  the supervisor relaunches (the new binary, for upgrade). */
+	scheduleFleetExit(kind, targetVersion) {
+		const willDrainUntil = new Date(this.clock.now() + this.cfg.limits.shutdownDrainMs).toISOString();
+		this.log.info(`cp: ${kind}${targetVersion ? ` → ${targetVersion}` : ""} requested — draining then exiting`);
+		(async () => {
+			try {
+				await this.stop();
+			} catch (err) {
+				this.log.error(`cp: ${kind} shutdown failed: ${formatErr(err)}`);
+			} finally {
+				this.requestExit(0);
+			}
+		})();
+		return {
+			accepted: true,
+			willDrainUntil
+		};
+	}
 	cpConfigApply() {
 		return {
 			applyConfigPush: (keys) => {
@@ -82702,7 +83057,26 @@ var Daemon = class {
 			upsertCron: (cron) => this.cpCrons.upsert(cron),
 			removeCron: (cronId) => this.cpCrons.remove(cronId),
 			applyRouteAssign: (a) => this.cpRouting?.upsertAssign(a),
-			applyRouteUpdate: (u) => this.cpRouting?.applyUpdate(u)
+			applyRouteUpdate: (u) => this.cpRouting?.applyUpdate(u),
+			applyAgentLaunch: async (launch) => {
+				const agent = this.agents.get(launch.agentId);
+				if (!agent) throw new Error(`agent/launch: unknown agent ${launch.agentId}`);
+				this.drainingAgents.delete(launch.agentId);
+				await this.ensureHostAsync(launch.agentId);
+				return {
+					agentId: launch.agentId,
+					launchId: randomUUID(),
+					startedAt: new Date(this.clock.now()).toISOString(),
+					runtime: agent.runtime
+				};
+			},
+			applyAgentStop: async (stop) => {
+				await this.stopAgent(stop.agentId);
+				return { ok: true };
+			},
+			applyDaemonDrain: (drain, onProgress) => this.runDrain(drain, onProgress),
+			applyDaemonRestart: (_req) => this.scheduleFleetExit("restart"),
+			applyDaemonUpgrade: (req) => this.scheduleFleetExit("upgrade", req.targetVersion)
 		};
 	}
 	/** A CP cron fired: build a synthetic message and run it through the normal routing path. */
@@ -82726,6 +83100,17 @@ var Daemon = class {
 		};
 		this.onInbound(msg);
 	}
+	/** Real CPU utilization (0..1) across all cores since the previous call — the busy
+	*  fraction of the time delta. Called once per heartbeat, so it reflects load over the
+	*  heartbeat interval (like a system monitor), not the run-queue load average. */
+	cpuUtilization() {
+		const now = cpuTotals();
+		const idle = now.idle - this.lastCpu.idle;
+		const busy = now.busy - this.lastCpu.busy;
+		this.lastCpu = now;
+		const total = idle + busy;
+		return total > 0 ? Math.min(1, Math.max(0, busy / total)) : 0;
+	}
 	startCpClient(root) {
 		const cp = this.cfg.controlPlane;
 		if (!cp?.enabled || !cp.url || !cp.key) {
@@ -82754,13 +83139,20 @@ var Daemon = class {
 				acp: true,
 				features: []
 			}),
+			runtimeProfiles: () => Object.keys(this.runtimes).map((id) => ({
+				runtime: id,
+				version: this.runtimeVersions[id] ?? "",
+				models: [],
+				acpSupport: "full",
+				toolCalling: true
+			})),
 			localState: () => ({
 				assignments: [],
 				crons: this.cpCrons?.ids() ?? [],
 				leases: []
 			}),
 			loadSnapshot: () => ({
-				cpu: loadavg()[0] ?? 0,
+				cpu: this.cpuUtilization(),
 				mem: totalmem() > 0 ? 1 - freemem() / totalmem() : 0,
 				agents: this.hosts.size
 			}),
@@ -82775,8 +83167,16 @@ var Daemon = class {
 		this.log.info(`cp: connecting to ${url}…`);
 	}
 	async stop() {
+		this.draining = true;
 		clearTimeout(this.debounceTimer);
+		if (this.idleSweepTimer !== void 0) {
+			this.clock.clearTimeout(this.idleSweepTimer);
+			this.idleSweepTimer = void 0;
+		}
+		for (const t of this.cancelTimers.values()) this.clock.clearTimeout(t);
+		this.cancelTimers.clear();
 		await this.watcher?.close();
+		await this.drainForShutdown();
 		const errors = [];
 		this.scheduler?.stop();
 		await Promise.resolve(this.cpClient?.stop()).catch((e) => errors.push(e));