@agentconnect.md/daemon 1.0.0-rc.36 → 1.0.0-rc.38

package/dist/index.js

@@ -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
 	})
 });
@@ -16975,10 +16981,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
@@ -17338,6 +17363,91 @@ const AgentScopeDenied = object({
 	capability: string()
 });
 //#endregion
+//#region ../protocol/dist/frames/register.js
+/**
+* Capability upload + the reconcile snapshot — protocol §3.3.
+*
+* `register/ok` is the authoritative source of truth: the daemon converges its
+* local cache to it. CP wins all conflicts, so re-issuing the same snapshot is
+* idempotent.
+*/
+const RegisterReq = object({
+	host: string(),
+	capabilities: object({
+		platforms: array(Platform),
+		runtimes: array(string()),
+		acp: boolean(),
+		features: array(string()).default([])
+	}),
+	maxAgents: number().int(),
+	localState: object({
+		assignments: array(string()),
+		crons: array(string()),
+		leases: array(string())
+	})
+});
+const RegisterOk = object({
+	routingEpoch: number().int(),
+	assignments: array(RouteAssign),
+	agents: array(AgentSpec.extend({ agentId: string().uuid() })).default([]),
+	crons: array(CronUpsert),
+	leases: array(SecretsGrant),
+	drop: object({
+		assignments: array(string()),
+		crons: array(string())
+	})
+});
+//#endregion
+//#region ../protocol/dist/frames/session.js
+/**
+* Session read-back (C→D REQ → REP) — the console's on-demand pulls.
+*
+* The CP stores NO session data — neither the list nor the bodies. Sessions are
+* created on the Slack→daemon path and live solely in the daemon's local store
+* (body-locality, §1/§12). So both the session **list** and a session's chat
+* **history** are pulled live from the owning daemon(s) and proxied to the
+* console — never persisted on the CP, never on the orchestration hot path.
+*
+* - `session/list`: the daemon's live sessions (CP fans this out to all the org's
+*   online daemons and merges, for "all sessions across the workspace").
+* - `session/history`: one cursor-paginated page of a session's transcript.
+*/
+/** One row in the session list (metadata + console metrics; NOT the transcript). */
+const SessionListItem = object({
+	sessionId: string().uuid(),
+	sessionKey: SessionKey,
+	agentId: string().uuid(),
+	title: string().optional(),
+	status: string().optional(),
+	lastActivityAt: string().optional(),
+	tokenUsage: number().int().optional(),
+	triggeredBy: string().optional()
+});
+/** C→D REQ: list the daemon's sessions (optionally just one agent's). */
+const SessionListReq = object({ agentId: string().uuid().optional() });
+/** D→C REP (corr = req id): the daemon's current sessions. */
+const SessionListPage = object({ sessions: array(SessionListItem) });
+/** One message in a session transcript page (a body — returned only for display). */
+const SessionMessage = object({
+	seq: number().int(),
+	sender: string(),
+	ts: string(),
+	kind: string(),
+	text: string()
+});
+/** C→D REQ: fetch one page of a session's history from the owning daemon. */
+const SessionHistoryReq = object({
+	sessionId: string().uuid(),
+	cursor: string().optional(),
+	limit: number().int().positive().max(200).default(50)
+});
+/** D→C REP (corr = the req id): a page of messages + the cursor for the next page. */
+const SessionHistoryPage = object({
+	sessionId: string().uuid(),
+	messages: array(SessionMessage),
+	nextCursor: string().optional()
+});
+//#endregion
 //#region ../protocol/dist/frame.js
 /**
 * The single source of truth for the wire: `type` string → payload zod schema.
@@ -17353,32 +17463,8 @@ const AgentScopeDenied = object({
 const FRAME_SCHEMAS = {
 	auth: AuthReq,
 	"auth/ok": AuthOk,
-	register: object({
-		host: string(),
-		capabilities: object({
-			platforms: array(Platform),
-			runtimes: array(string()),
-			acp: boolean(),
-			features: array(string()).default([])
-		}),
-		maxAgents: number().int(),
-		localState: object({
-			assignments: array(string()),
-			crons: array(string()),
-			leases: array(string())
-		})
-	}),
-	"register/ok": object({
-		routingEpoch: number().int(),
-		assignments: array(RouteAssign),
-		agents: array(AgentSpec.extend({ agentId: string().uuid() })).default([]),
-		crons: array(CronUpsert),
-		leases: array(SecretsGrant),
-		drop: object({
-			assignments: array(string()),
-			crons: array(string())
-		})
-	}),
+	register: RegisterReq,
+	"register/ok": RegisterOk,
 	heartbeat: object({
 		load: object({
 			cpu: number(),
@@ -17437,6 +17523,10 @@ const FRAME_SCHEMAS = {
 		]),
 		toolCalling: boolean()
 	}),
+	"session/list": SessionListReq,
+	"session/list/page": SessionListPage,
+	"session/history": SessionHistoryReq,
+	"session/history/page": SessionHistoryPage,
 	"config/push": object({ keys: record(string(), unknown()) }),
 	"daemon/restart": object({
 		reason: string(),
@@ -17523,6 +17613,10 @@ discriminatedUnion("type", [
 	frame("scope-attestation", FRAME_SCHEMAS["scope-attestation"]),
 	frame("event/session", FRAME_SCHEMAS["event/session"]),
 	frame("facts/runtime-profile", FRAME_SCHEMAS["facts/runtime-profile"]),
+	frame("session/list", FRAME_SCHEMAS["session/list"]),
+	frame("session/list/page", FRAME_SCHEMAS["session/list/page"]),
+	frame("session/history", FRAME_SCHEMAS["session/history"]),
+	frame("session/history/page", FRAME_SCHEMAS["session/history/page"]),
 	frame("config/push", FRAME_SCHEMAS["config/push"]),
 	frame("daemon/restart", FRAME_SCHEMAS["daemon/restart"]),
 	frame("daemon/upgrade", FRAME_SCHEMAS["daemon/upgrade"]),
@@ -23292,6 +23386,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);
 	}
@@ -23443,10 +23558,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,
@@ -81628,14 +81746,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() {
@@ -81682,13 +81799,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}`);
@@ -81698,6 +81838,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
@@ -81978,6 +82122,21 @@ 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
+	};
+}
 var Daemon = class {
 	opts;
 	store;
@@ -82003,8 +82162,17 @@ var Daemon = class {
 	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);
@@ -82144,6 +82312,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() {
@@ -82316,6 +82485,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;
@@ -82333,6 +82506,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)}`));
 	}
@@ -82402,7 +82579,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) {
@@ -82411,7 +82589,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;
 		}
@@ -82474,22 +82654,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 {
@@ -82504,9 +82702,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)
@@ -82595,6 +82819,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) {
@@ -82608,6 +82834,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) => {
@@ -82633,7 +83024,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. */
@@ -82706,8 +83116,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));