@themoltnet/agent-daemon 0.47.0 → 0.48.0

package/dist/cli.js

@@ -6,15 +6,15 @@ import "multiformats/cid";
 import "multiformats/codecs/json";
 import "multiformats/hashes/sha2";
 import "typebox/value";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { parseArgs, promisify } from "node:util";
 import { AgentRuntime, ApiTaskReporter, ApiTaskSource, PollingApiTaskSource, createLocalSeedSigner, resolveAgentIdentity, resolveProfileWarmSessionTtlSec, resolveRuntimeProfile, resolveRuntimeProfiles, validateRuntimeProfilePrerequisites } from "@themoltnet/agent-runtime";
-import { GuestEnvironmentBoundaryError, assertGuestEnvironmentBoundary, createPiRetryTriage, findMainWorktree, isResolvedPathInsideRoot, normalizeRetryTriageResult, redactRetryTriageSecrets } from "@themoltnet/pi-runtime";
-import { connect, createNodeSecretProviderRegistry } from "@themoltnet/sdk/node";
-import { execFile, execFileSync } from "node:child_process";
-import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, realpathSync, rmSync } from "node:fs";
-import { AuthenticationError, MoltNetError, createExecutorAttestor, readConfig, resolveEnvSecretReference, resolveIdentitySeed } from "@themoltnet/sdk";
-import { createHash, randomUUID } from "node:crypto";
+import { GuestEnvironmentBoundaryError, assertGuestEnvironmentBoundary, createPiRetryTriage, findMainWorktree, isResolvedPathInsideRoot, normalizeRetryTriageResult, redactRetryTriageSecrets, resolveRuntimeProfileModel } from "@themoltnet/pi-runtime";
+import { FILE_SECRET_PROVIDER, FileSecretProvider, connect, createNodeSecretProviderRegistry } from "@themoltnet/sdk/node";
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { constants, createReadStream, createWriteStream, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { AuthenticationError, MoltNetError, agentKeyKey, assertTrustedConfigApiUrl, createExecutorAttestor, deriveMcpUrl, formatSecretReferenceString, identitySeedKey, parseSecretReferenceString, readConfig, register, requireSecureCredentialApiUrl, resolveAgentKey, resolveEnvSecretReference, resolveIdentitySeed, resolveOAuth2ClientSecret } from "@themoltnet/sdk";
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { once } from "node:events";
 import { pino, transport } from "pino";
 import { metrics } from "@opentelemetry/api";
@@ -26,10 +26,17 @@ import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { getModel } from "@earendil-works/pi-ai";
-import { mkdir, realpath, stat } from "node:fs/promises";
+import { mkdir, open, realpath, stat } from "node:fs/promises";
 import { pipeline } from "node:stream/promises";
-import { Writable } from "node:stream";
+import cors from "@fastify/cors";
+import helmet from "@fastify/helmet";
+import { Transform, Writable } from "node:stream";
+import { writePiConfig } from "@themoltnet/pi-runtime/pi-config";
+import { homedir } from "node:os";
+import { lock } from "proper-lockfile";
+import { StringDecoder } from "node:string_decoder";
+import rateLimit from "@fastify/rate-limit";
+import Fastify from "fastify";
 import { createGzip } from "node:zlib";
 //#region ../../libs/tasks/src/rubric.ts
 /**
@@ -3417,6 +3424,9 @@ Commands:
   once      Claim and execute one specific queued task by id, then exit.
   drain     Poll until the queue has nothing claimable, then exit.
             Useful for batch eval runs and demos.
+  serve     Loopback supervisor for console-managed runs: pairing,
+            agent/provider config store, and start/stop of poll/drain
+            child processes. Binds 127.0.0.1 only.
   sync-sessions
             Repair durable runtime-session checkpoints from local slot files.
 
@@ -3549,6 +3559,39 @@ Example:
 function isHelpFlag(args) {
 	return args.includes("--help") || args.includes("-h");
 }
+var SERVE_HELP = `\
+agent-daemon serve — loopback supervisor for console-managed runs.
+
+Binds 127.0.0.1 only. A paired Console origin configures agents and
+providers (secret references only) and starts/stops poll/drain runs as
+child processes of this supervisor.
+
+Options:
+  --port <n>                  Loopback port. Default: 17374.
+                              Env: MOLTNET_SERVE_PORT.
+  --allowed-origins <csv>     Exact Console origins allowed to pair.
+                              Default: https://console.themolt.net.
+                              Env: MOLTNET_SERVE_ALLOWED_ORIGINS.
+  --root <path>               Config root. Default: ~/.config/moltnet
+                              (or MOLTNET_SERVE_ROOT).
+  --api-url <url>             Default MoltNet API for new managed agents.
+                              Default: https://api.themolt.net.
+`;
+//#endregion
+//#region src/lib/identity-pin.ts
+/** Compare every pinned field without choosing a caller-specific error type. */
+function assessIdentityPin(current, expected) {
+	for (const [field, label] of [
+		["identityId", "identity id"],
+		["publicKey", "public key"],
+		["fingerprint", "fingerprint"]
+	]) if (!current[field] || current[field] !== expected[field]) return {
+		ok: false,
+		field,
+		label
+	};
+	return { ok: true };
+}
 //#endregion
 //#region src/lib/agent-context.ts
 /**
@@ -3612,6 +3655,8 @@ async function validateStartupBinding(options) {
 	}
 	const assessment = assessStartupBinding(whoami, options.teamId);
 	if (!assessment.ok) throw new Error(`Daemon startup validation failed: ${assessment.reason}`);
+	const expected = options.expectedIdentity;
+	if (expected && !assessIdentityPin(whoami, expected).ok) throw new Error("Daemon startup validation failed: authenticated identity does not match the serve activation.");
 	return whoami;
 }
 /**
@@ -3690,6 +3735,7 @@ function resolveCredentialRoots(agentRootDir) {
 function loadConfig() {
 	assertSingleCredentialForm("MOLTNET_AGENT_KEY", "MOLTNET_AGENT_KEY_REF");
 	assertSingleCredentialForm("MOLTNET_PRIVATE_KEY", "MOLTNET_PRIVATE_KEY_REF");
+	const expectedIdentity = readExpectedIdentity();
 	return {
 		otelEndpoint: process.env["MOLTNET_OTEL_ENDPOINT"] ?? "",
 		logLevel: process.env["LOG_LEVEL"] ?? "",
@@ -3703,7 +3749,25 @@ function loadConfig() {
 		profileCredentialRequirements: process.env["MOLTNET_PROFILE_CREDENTIAL_REQUIREMENTS"] ?? "",
 		credentialBindings: process.env["MOLTNET_CREDENTIAL_BINDINGS"] ?? "",
 		credentialEnforcement: process.env["MOLTNET_CREDENTIAL_ENFORCEMENT"] ?? "",
-		traceIdlePolling: readBoolean("MOLTNET_TRACE_IDLE_POLLING", process.env["MOLTNET_TRACE_IDLE_POLLING"])
+		traceIdlePolling: readBoolean("MOLTNET_TRACE_IDLE_POLLING", process.env["MOLTNET_TRACE_IDLE_POLLING"]),
+		...expectedIdentity ? { expectedIdentity } : {}
+	};
+}
+function readExpectedIdentity() {
+	const identityId = process.env["MOLTNET_EXPECTED_IDENTITY_ID"]?.trim() ?? "";
+	const publicKey = process.env["MOLTNET_EXPECTED_PUBLIC_KEY"]?.trim() ?? "";
+	const fingerprint = process.env["MOLTNET_EXPECTED_FINGERPRINT"]?.trim() ?? "";
+	const present = [
+		identityId,
+		publicKey,
+		fingerprint
+	].filter(Boolean).length;
+	if (present === 0) return void 0;
+	if (present !== 3) throw new Error("MOLTNET_EXPECTED_IDENTITY_ID, MOLTNET_EXPECTED_PUBLIC_KEY, and MOLTNET_EXPECTED_FINGERPRINT must be set together");
+	return {
+		identityId,
+		publicKey,
+		fingerprint
 	};
 }
 function assertSingleCredentialForm(valueName, refName) {
@@ -3718,6 +3782,20 @@ function readBoolean(name, value) {
 function activatePiCodingAgentDir(path) {
 	process.env["PI_CODING_AGENT_DIR"] = path;
 }
+function loadServeEnvConfig() {
+	return {
+		port: process.env["MOLTNET_SERVE_PORT"] ?? "",
+		allowedOrigins: process.env["MOLTNET_SERVE_ALLOWED_ORIGINS"] ?? "",
+		root: process.env["MOLTNET_SERVE_ROOT"] ?? "",
+		xdgConfigHome: process.env["XDG_CONFIG_HOME"] ?? "",
+		apiUrl: process.env["MOLTNET_API_URL"] ?? "",
+		logLevel: process.env["LOG_LEVEL"] ?? ""
+	};
+}
+/** Full process environment for spawned serve run children. */
+function processEnvSnapshot() {
+	return process.env;
+}
 //#endregion
 //#region src/lib/abort-active-attempt.ts
 /** Best-effort signal cleanup; lease expiry remains the final backstop. */
@@ -5170,13 +5248,17 @@ function runWithDaemonRuntimeContext(context, callback) {
 //#endregion
 //#region src/lib/runtime-profile-retry-triage.ts
 function createRuntimeProfileRetryTriage(options) {
-	return createPiRetryTriage({
-		model: getModel(options.runtimeProfile.provider, options.runtimeProfile.model),
-		thinkingLevel: options.runtimeProfile.thinkingLevel,
-		piAgentDir: options.piAgentDir,
-		timeoutMs: options.timeoutMs,
-		cwd: options.cwd
-	});
+	return async (input) => {
+		const { modelHandle, modelRuntime } = await resolveRuntimeProfileModel(options.piAgentDir, options.runtimeProfile.provider, options.runtimeProfile.model);
+		return createPiRetryTriage({
+			model: modelHandle,
+			modelRuntime,
+			thinkingLevel: options.runtimeProfile.thinkingLevel,
+			piAgentDir: options.piAgentDir,
+			timeoutMs: options.timeoutMs,
+			cwd: options.cwd
+		})(input);
+	};
 }
 //#endregion
 //#region src/lib/runtime-resource-reaper.ts
@@ -5790,7 +5872,8 @@ async function runPolling(opts) {
 			gate = "authenticate_and_bind";
 			const whoami = await validateStartupBinding({
 				agent: resolvedContext.agent,
-				teamId
+				teamId,
+				expectedIdentity: cfg.expectedIdentity
 			});
 			gate = "resolve_signing_material";
 			const privateKey = await resolveExecutorSigningPrivateKey({
@@ -6443,7 +6526,8 @@ async function runOnce(argv, runtimeAdapter = defaultPiDaemonAdapter) {
 			gate = "authenticate_and_bind";
 			const whoami = await validateStartupBinding({
 				agent: resolvedContext.agent,
-				teamId: values.team
+				teamId: values.team,
+				expectedIdentity: cfg.expectedIdentity
 			});
 			gate = "resolve_signing_material";
 			const privateKey = await resolveExecutorSigningPrivateKey({
@@ -6854,6 +6938,2169 @@ function runPoll(argv, runtimeAdapter) {
 	});
 }
 //#endregion
+//#region ../../libs/loopback-companion/src/errors.ts
+var LoopbackViolationError = class extends Error {
+	name = "LoopbackViolationError";
+	constructor(kind, message, options) {
+		super(message, options);
+		this.kind = kind;
+	}
+};
+function isLoopbackViolation(error) {
+	return error instanceof LoopbackViolationError;
+}
+//#endregion
+//#region ../../libs/loopback-companion/src/origin.ts
+/** Hostnames accepted as loopback for companion servers and origins. */
+function isLoopbackHostname(hostname) {
+	return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/**
+* Normalize and validate a browser origin. Accepts exact `https:` origins,
+* or `http:` origins whose host is loopback. Rejects values that carry a
+* path, trailing slash, credentials, or any other non-origin decoration
+* (`url.origin !== value` catches all of those).
+*/
+function normalizeOrigin(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch (cause) {
+		throw new LoopbackViolationError("origin_invalid", "Origin is not valid", { cause });
+	}
+	if (url.origin !== value || url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHostname(url.hostname))) throw new LoopbackViolationError("origin_invalid", "Origin is not valid");
+	return url.origin;
+}
+/** Parse a comma-separated origin list (config format shared by companions). */
+function parseAllowedOrigins(csv) {
+	return csv.split(",").map((origin) => origin.trim()).filter(Boolean);
+}
+/**
+* Exact-origin allowlist. Every configured origin is normalized eagerly so a
+* misconfigured allowlist fails at startup, not at request time.
+*/
+var OriginAllowlist = class {
+	origins;
+	constructor(allowedOrigins) {
+		if (allowedOrigins.length === 0) throw new Error("OriginAllowlist requires at least one origin");
+		this.origins = new Set(allowedOrigins.map((origin) => normalizeOrigin(origin)));
+	}
+	has(origin) {
+		try {
+			return this.origins.has(normalizeOrigin(origin));
+		} catch {
+			return false;
+		}
+	}
+	/** Return the normalized origin or throw `origin_not_allowed`. */
+	assert(value) {
+		let origin;
+		try {
+			origin = normalizeOrigin(value);
+		} catch {
+			throw new LoopbackViolationError("origin_not_allowed", "Origin is not allowed");
+		}
+		if (!this.origins.has(origin)) throw new LoopbackViolationError("origin_not_allowed", "Origin is not allowed");
+		return origin;
+	}
+};
+/** Extract and require the `Origin` header value. */
+function requireOriginHeader(headers) {
+	const origin = headers.origin;
+	if (typeof origin !== "string" || origin.length === 0) throw new LoopbackViolationError("origin_required", "Origin is required");
+	return origin;
+}
+//#endregion
+//#region ../../libs/loopback-companion/src/fastify.ts
+var CORS_PREFLIGHT_MAX_AGE_SECONDS = 600;
+/**
+* Enforce that the `Host` header identifies loopback. Blocks DNS-rebinding
+* setups where a public hostname resolves to 127.0.0.1: the browser then
+* sends that hostname as `Host`, and the request is refused here even
+* though the socket is loopback.
+*/
+function requireLoopbackHost(request) {
+	const host = request.headers.host;
+	if (!host) throw new LoopbackViolationError("host_required", "Host header is required");
+	let hostname;
+	try {
+		hostname = new URL(`http://${host}`).hostname;
+	} catch {
+		throw new LoopbackViolationError("host_not_loopback", "Host header must identify loopback");
+	}
+	if (!isLoopbackHostname(hostname === "::1" ? "[::1]" : hostname)) throw new LoopbackViolationError("host_not_loopback", "Host header must identify loopback");
+}
+/**
+* Register the loopback-companion security profile on a Fastify app:
+*
+* - loopback `Host` enforcement on every request;
+* - `cache-control: no-store` on every response;
+* - strict UTF-8 JSON body parsing (invalid bodies raise a typed violation);
+* - exact-origin CORS (opaque/`null` origins get no CORS response but are
+*   not rejected here — route-level controls stay mandatory);
+* - hardened helmet defaults.
+*
+*/
+function registerLoopbackSecurity(app, options) {
+	if (!options.allowedOrigins && !options.isOriginAllowed) throw new Error("registerLoopbackSecurity requires allowedOrigins or isOriginAllowed");
+	const primaryAllowlist = options.allowedOrigins ? new OriginAllowlist(options.allowedOrigins) : null;
+	const selfAllowlist = options.selfOrigins && options.selfOrigins.length > 0 ? new OriginAllowlist(options.selfOrigins) : null;
+	const isOriginAllowed = (origin) => selfAllowlist?.has(origin) === true || primaryAllowlist?.has(origin) === true || options.isOriginAllowed?.(origin) === true;
+	app.addHook("onRequest", (request, _reply, done) => {
+		requireLoopbackHost(request);
+		done();
+	});
+	app.addHook("onSend", async (_request, reply, payload) => {
+		reply.header("cache-control", "no-store");
+		return payload;
+	});
+	app.removeContentTypeParser("application/json");
+	app.addContentTypeParser("application/json", { parseAs: "buffer" }, (_request, body, done) => {
+		try {
+			const json = new TextDecoder("utf-8", { fatal: true }).decode(typeof body === "string" ? Buffer.from(body) : body);
+			done(null, JSON.parse(json));
+		} catch (cause) {
+			done(new LoopbackViolationError("body_not_utf8_json", "Request body must be valid UTF-8 JSON", { cause }), void 0);
+		}
+	});
+	app.register(cors, {
+		allowedHeaders: ["content-type", ...options.allowedHeaders ?? []],
+		maxAge: CORS_PREFLIGHT_MAX_AGE_SECONDS,
+		methods: [...options.methods ?? [
+			"GET",
+			"POST",
+			"OPTIONS"
+		]],
+		origin: (origin, callback) => {
+			if (!origin || origin === "null") {
+				callback(null, false);
+				return;
+			}
+			if (isOriginAllowed(origin)) {
+				callback(null, true);
+				return;
+			}
+			callback(new LoopbackViolationError("origin_not_allowed", "Origin is not allowed"), false);
+		}
+	});
+	app.register(helmet, {
+		contentSecurityPolicy: {
+			useDefaults: false,
+			directives: options.contentSecurityPolicyDirectives ?? {
+				baseUri: ["'none'"],
+				defaultSrc: ["'none'"],
+				formAction: ["'self'"],
+				frameAncestors: ["'none'"],
+				styleSrc: ["'unsafe-inline'"]
+			}
+		},
+		crossOriginEmbedderPolicy: false,
+		crossOriginOpenerPolicy: false,
+		crossOriginResourcePolicy: { policy: "same-origin" },
+		hsts: false,
+		referrerPolicy: { policy: "no-referrer" }
+	});
+}
+//#endregion
+//#region ../../libs/loopback-companion/src/fetch-metadata.ts
+function headerValue(headers, name) {
+	const value = headers[name];
+	return typeof value === "string" ? value : void 0;
+}
+/**
+* Require that a request is a top-level browser navigation (used by local
+* approval pages that must be opened as a document, never fetched).
+*/
+function assertNavigationRequest(headers) {
+	const site = headerValue(headers, "sec-fetch-site");
+	const mode = headerValue(headers, "sec-fetch-mode");
+	const destination = headerValue(headers, "sec-fetch-dest");
+	if (site !== "cross-site" && site !== "same-origin" && site !== "none" || mode !== "navigate" || destination !== "document") throw new LoopbackViolationError("navigation_required", "Request must be opened as a browser navigation");
+}
+/**
+* Reject an explicit cross-site Fetch-Metadata signal. Only the explicit
+* `cross-site` value is rejected: Safari may omit Fetch Metadata on
+* same-origin form submissions, so the absence of the header is not treated
+* as a violation — callers keep their one-time token as the primary control.
+*/
+function rejectExplicitCrossSite(headers) {
+	if (headerValue(headers, "sec-fetch-site") === "cross-site") throw new LoopbackViolationError("cross_site_rejected", "Request must not originate cross-site");
+}
+//#endregion
+//#region src/lib/serve/pairing.ts
+/**
+* One-click pairing ceremony for the serve supervisor, mirroring the signer's
+* session/ceremony pattern (#2062 design):
+*
+*   1. Console (allowed origin) POSTs `/v1/pairings` → pending pairing bound
+*      to that origin, with a one-time confirmation token.
+*   2. Console opens `http://127.0.0.1:<port>/pairings/<id>` in a new tab —
+*      a navigation-gated local approval page naming the origin.
+*   3. One click POSTs the confirmation form (explicit cross-site rejected;
+*      the one-time token is the primary CSRF control).
+*   4. Console claims `/v1/pairings/<id>/claim` from the same origin and
+*      receives the bearer token exactly once; only its SHA-256 remains in
+*      this supervisor process.
+*
+* The token exists for shared-machine cross-user protection and to bind
+* "this console session is the operator" — browser-vs-browser isolation is
+* already covered by the loopback-companion origin checks. Grants are
+* deliberately process-scoped: after the listening socket changes owners, a
+* token disclosed to an impostor on that port cannot authenticate to a later
+* supervisor process.
+*/
+var PENDING_TTL_MS = 600 * 1e3;
+var ServePairingError = class extends Error {
+	name = "ServePairingError";
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+function sha256Hex(value) {
+	return createHash("sha256").update(value, "utf8").digest("hex");
+}
+function safeEqual(a, b) {
+	const left = Buffer.from(a, "utf8");
+	const right = Buffer.from(b, "utf8");
+	return left.length === right.length && timingSafeEqual(left, right);
+}
+var PairingService = class {
+	pending = /* @__PURE__ */ new Map();
+	paired = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.options = options;
+	}
+	now() {
+		return this.options.now?.() ?? Date.now();
+	}
+	token() {
+		return this.options.randomToken?.() ?? randomBytes(32).toString("base64url");
+	}
+	sweep() {
+		const now = this.now();
+		for (const [id, pairing] of this.pending) if (pairing.expiresAt <= now) this.pending.delete(id);
+	}
+	start(origin) {
+		this.sweep();
+		const pairingId = randomBytes(12).toString("hex");
+		this.pending.set(pairingId, {
+			origin,
+			confirmToken: this.token(),
+			expiresAt: this.now() + PENDING_TTL_MS,
+			approved: false,
+			bearerToken: null
+		});
+		return {
+			pairingId,
+			approvalPath: `/pairings/${pairingId}`
+		};
+	}
+	/** Data for the local approval page. */
+	approval(pairingId) {
+		const pairing = this.require(pairingId);
+		if (pairing.approved) throw new ServePairingError("pairing_invalid", "Pairing is already approved");
+		return {
+			origin: pairing.origin,
+			confirmToken: pairing.confirmToken
+		};
+	}
+	confirm(pairingId, confirmToken) {
+		const pairing = this.require(pairingId);
+		if (pairing.approved || !safeEqual(pairing.confirmToken, confirmToken)) throw new ServePairingError("pairing_invalid", "Confirmation token is not valid");
+		pairing.approved = true;
+		pairing.bearerToken = this.token();
+		return { origin: pairing.origin };
+	}
+	claim(pairingId, origin) {
+		const pairing = this.require(pairingId);
+		if (pairing.origin !== origin) throw new ServePairingError("pairing_origin_mismatch", "Pairing belongs to a different origin");
+		if (!pairing.approved || !pairing.bearerToken) throw new ServePairingError("pairing_not_approved", "Pairing has not been approved yet");
+		const token = pairing.bearerToken;
+		this.pending.delete(pairingId);
+		this.paired.set(origin, sha256Hex(token));
+		return { token };
+	}
+	verify(origin, token) {
+		const tokenHash = this.paired.get(origin);
+		if (!tokenHash || !safeEqual(tokenHash, sha256Hex(token))) throw new ServePairingError("pairing_token_invalid", "Pairing token is not valid for this origin");
+	}
+	require(pairingId) {
+		this.sweep();
+		const pairing = this.pending.get(pairingId);
+		if (!pairing) throw new ServePairingError("pairing_not_found", "Pairing was not found or has expired");
+		return pairing;
+	}
+};
+function escapeHtml(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+/** Minimal, dependency-free local approval page. */
+function renderPairingApprovalPage(input) {
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>MoltNet Agent — approve connection</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; font: 16px/1.5 system-ui, sans-serif; display: grid; place-items: center; min-height: 100vh; background: Canvas; color: CanvasText; }
+  main { max-width: 26rem; padding: 2rem; border: 1px solid color-mix(in srgb, CanvasText 20%, transparent); border-radius: 12px; }
+  h1 { font-size: 1.2rem; margin: 0 0 0.5rem; }
+  code { font-size: 0.95em; word-break: break-all; }
+  button { margin-top: 1.25rem; font: inherit; padding: 0.6rem 1.4rem; border-radius: 8px; border: 1px solid color-mix(in srgb, CanvasText 30%, transparent); cursor: pointer; }
+  p.small { font-size: 0.85rem; opacity: 0.75; }
+</style>
+</head>
+<body>
+<main>
+<h1>Allow this site to manage local MoltNet agents?</h1>
+<p><code>${escapeHtml(input.origin)}</code> asks to configure agents and start or stop local daemon runs on this machine.</p>
+<p class="small">Approve only if you opened that page yourself. This grant lasts until the local supervisor stops.</p>
+<form method="post" action="/pairings/${escapeHtml(input.pairingId)}/confirm">
+<input type="hidden" name="confirmToken" value="${escapeHtml(input.confirmToken)}" />
+<button type="submit">Approve</button>
+</form>
+</main>
+</body>
+</html>
+`;
+}
+function renderPairingResultPage(input) {
+	return `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>${escapeHtml(input.title)}</title>
+<style>:root{color-scheme:light dark}body{margin:0;font:16px/1.5 system-ui,sans-serif;display:grid;place-items:center;min-height:100vh;background:Canvas;color:CanvasText}main{max-width:26rem;padding:2rem}</style>
+</head>
+<body><main role="status"><h1>${escapeHtml(input.title)}</h1><p>${escapeHtml(input.message)}</p><p>You can close this tab.</p></main></body>
+</html>
+`;
+}
+var NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+var PROVIDER_ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+function assertStoreName(kind, value) {
+	if (!NAME_RE.test(value)) throw new ServeStoreError("invalid_name", `${kind} must match ${NAME_RE.source}`);
+	return value;
+}
+function assertProviderId(value) {
+	if (!PROVIDER_ID_RE.test(value)) throw new ServeStoreError("invalid_name", `provider id must match ${PROVIDER_ID_RE.source}`);
+	return value;
+}
+var ServeStoreError = class extends Error {
+	name = "ServeStoreError";
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+	}
+};
+/** `MOLTNET_SERVE_ROOT` override, else `$XDG_CONFIG_HOME/moltnet`, else `~/.config/moltnet`. */
+function resolveServeRoot(input) {
+	const override = input.root?.trim();
+	if (override) return override;
+	const xdg = input.xdgConfigHome?.trim();
+	return join(xdg || join(homedir(), ".config"), "moltnet");
+}
+function providerEnvName(providerId) {
+	return `MOLTNET_PROVIDER_${assertProviderId(providerId).replaceAll("-", "_").toUpperCase()}_API_KEY`;
+}
+function assertProviderEnvName(providerId, value) {
+	const expected = providerEnvName(providerId);
+	if (value !== expected) throw new ServeStoreError("invalid_state", `provider envName must be ${expected}`);
+	return value;
+}
+function readJson(path) {
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (cause) {
+		if (cause.code === "ENOENT") return null;
+		throw new ServeStoreError("io_error", `could not read state at ${path}`, { cause });
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (cause) {
+		throw new ServeStoreError("invalid_state", `corrupt JSON at ${path}`, { cause });
+	}
+}
+function writeJsonAtomic(path, value) {
+	const temp = `${path}.${randomBytes(6).toString("hex")}.tmp`;
+	try {
+		writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 384 });
+		renameSync(temp, path);
+	} catch (cause) {
+		try {
+			rmSync(temp, { force: true });
+		} catch {}
+		throw cause;
+	}
+}
+var ServeStore = class {
+	root;
+	agentsDir;
+	runsDir;
+	secretsDir;
+	constructor(root) {
+		this.root = root;
+		this.agentsDir = join(root, "agents");
+		this.runsDir = join(root, "runs");
+		this.secretsDir = join(root, "secrets");
+	}
+	/** Create the directory layout (0700) if missing. Idempotent. */
+	ensure() {
+		for (const dir of [
+			this.root,
+			this.agentsDir,
+			this.runsDir,
+			this.secretsDir
+		]) mkdirSync(dir, {
+			recursive: true,
+			mode: 448
+		});
+		return this;
+	}
+	get servePath() {
+		return join(this.root, "serve.json");
+	}
+	readServeState() {
+		const state = readJson(this.servePath);
+		if (!state) return {
+			version: 1,
+			pendingRegistrations: {},
+			activations: {}
+		};
+		if (!isRecord(state) || state.version !== 1) throw new ServeStoreError("invalid_state", `serve.json version ${String(isRecord(state) ? state.version : void 0)} is not supported`);
+		if ("pairedOrigins" in state) throw new ServeStoreError("invalid_state", "serve.json uses the obsolete pairing format; clear the unreleased serve store and reconfigure it");
+		if (!isRecord(state.pendingRegistrations) || !isRecord(state.activations)) throw new ServeStoreError("invalid_state", "serve.json is missing the version 1 activation map; clear the unreleased serve store and reconfigure it");
+		for (const [alias, activation] of Object.entries(state.activations)) validateActivation(alias, activation);
+		for (const [alias, registration] of Object.entries(state.pendingRegistrations)) {
+			assertStoreName("agent name", alias);
+			if (!isRecord(registration) || typeof registration.apiUrl !== "string" || registration.apiUrl.length === 0 || typeof registration.createdAt !== "string" || registration.createdAt.length === 0) throw new ServeStoreError("invalid_state", `pending registration "${alias}" is not valid`);
+		}
+		return {
+			version: 1,
+			pendingRegistrations: state.pendingRegistrations,
+			activations: state.activations
+		};
+	}
+	writeServeState(state) {
+		writeJsonAtomic(this.servePath, state);
+	}
+	agentPath(name) {
+		return storeChildPath(this.agentsDir, "agent name", name, ".json");
+	}
+	readAgentConfig(alias) {
+		return readJson(this.agentPath(alias));
+	}
+	writeAgentConfig(alias, config) {
+		writeJsonAtomic(this.agentPath(alias), config);
+	}
+	removeAgentConfig(alias) {
+		rmSync(this.agentPath(alias), { force: true });
+	}
+	readActivation(alias) {
+		return this.readServeState().activations[assertStoreName("agent name", alias)] ?? null;
+	}
+	hasPendingRegistration(alias) {
+		return Boolean(this.readServeState().pendingRegistrations[assertStoreName("agent name", alias)]);
+	}
+	reserveRegistration(alias, apiUrl) {
+		const name = assertStoreName("agent name", alias);
+		const state = this.readServeState();
+		if (state.activations[name] || state.pendingRegistrations[name]) throw new ServeStoreError("already_exists", `agent "${name}" already exists in the serve store`);
+		state.pendingRegistrations[name] = {
+			apiUrl,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		this.writeServeState(state);
+	}
+	clearPendingRegistration(alias) {
+		const name = assertStoreName("agent name", alias);
+		const state = this.readServeState();
+		delete state.pendingRegistrations[name];
+		this.writeServeState(state);
+	}
+	writeActivation(activation) {
+		const alias = assertStoreName("agent name", activation.alias);
+		validateActivation(alias, activation);
+		const state = this.readServeState();
+		state.activations[alias] = activation;
+		if (activation.source === "managed") delete state.pendingRegistrations[alias];
+		this.writeServeState(state);
+	}
+	listActivations() {
+		return Object.values(this.readServeState().activations).sort((a, b) => a.alias.localeCompare(b.alias));
+	}
+	get providersPath() {
+		return join(this.root, "providers.json");
+	}
+	readProviders() {
+		const state = readJson(this.providersPath) ?? {};
+		this.validateProviders(state);
+		return state;
+	}
+	writeProviders(state) {
+		this.validateProviders(state);
+		writeJsonAtomic(this.providersPath, state);
+	}
+	validateProviders(state) {
+		for (const [id, provider] of Object.entries(state)) {
+			assertProviderId(id);
+			assertProviderEnvName(id, provider.envName);
+		}
+	}
+	runDir(id) {
+		return storeChildPath(this.runsDir, "run id", id);
+	}
+	resolveRunLogPath(id) {
+		let root;
+		let runDir;
+		try {
+			root = realpathSync(this.runsDir);
+			runDir = realpathSync(this.runDir(id));
+		} catch (cause) {
+			throw new ServeStoreError("io_error", "could not resolve run directory", { cause });
+		}
+		if (!isStrictDescendant(root, runDir)) throw new ServeStoreError("invalid_state", "run directory escapes its store");
+		const logPath = join(runDir, "daemon.log");
+		try {
+			if (lstatSync(logPath).isSymbolicLink()) throw new ServeStoreError("invalid_state", "run log must not be a symbolic link");
+			const resolvedLog = realpathSync(logPath);
+			if (!isStrictDescendant(runDir, resolvedLog)) throw new ServeStoreError("invalid_state", "run log escapes its store");
+		} catch (cause) {
+			if (cause instanceof ServeStoreError) throw cause;
+			if (cause.code !== "ENOENT") throw new ServeStoreError("io_error", "could not resolve run log", { cause });
+		}
+		return logPath;
+	}
+	createRunDir(id) {
+		const dir = this.runDir(id);
+		const piDir = join(dir, "pi");
+		mkdirSync(piDir, {
+			recursive: true,
+			mode: 448
+		});
+		return {
+			dir,
+			piDir,
+			logPath: join(dir, "daemon.log")
+		};
+	}
+	readRun(id) {
+		return readJson(join(this.runDir(id), "run.json"));
+	}
+	writeRun(record) {
+		writeJsonAtomic(join(this.runDir(record.id), "run.json"), record);
+	}
+	listRuns(limit = Number.POSITIVE_INFINITY) {
+		let ids;
+		try {
+			ids = readdirSync(this.runsDir);
+		} catch {
+			return [];
+		}
+		const sortedIds = ids.filter((id) => NAME_RE.test(id)).sort().reverse();
+		const selectedIds = Number.isFinite(limit) ? sortedIds.slice(0, Math.max(0, limit)) : sortedIds;
+		const records = [];
+		for (const id of selectedIds) {
+			const record = this.readRun(id);
+			if (record) records.push(record);
+		}
+		return records.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+	}
+	/** Remove only completed run directories outside the configured budget. */
+	pruneCompletedRuns(options) {
+		const now = (options.now ?? /* @__PURE__ */ new Date()).getTime();
+		let retainedBytes = 0;
+		let retainedCount = 0;
+		const removed = [];
+		for (const record of this.listRuns()) {
+			if (record.status === "running") continue;
+			const dir = this.runDir(record.id);
+			const bytes = directoryBytes(dir);
+			const endedAt = Date.parse(record.endedAt ?? record.startedAt);
+			const expired = !Number.isFinite(endedAt) || now - endedAt > options.maxAgeMs;
+			const overCount = retainedCount >= options.maxCount;
+			const overBytes = retainedBytes + bytes > options.maxBytes;
+			if (expired || overCount || overBytes) {
+				rmSync(dir, {
+					recursive: true,
+					force: true
+				});
+				removed.push(record.id);
+				continue;
+			}
+			retainedCount += 1;
+			retainedBytes += bytes;
+		}
+		return removed;
+	}
+};
+function directoryBytes(path) {
+	let info;
+	try {
+		info = lstatSync(path);
+	} catch {
+		return 0;
+	}
+	if (info.isSymbolicLink()) return 0;
+	if (!info.isDirectory()) return info.size;
+	let total = 0;
+	for (const entry of readdirSync(path, { withFileTypes: true })) total += directoryBytes(join(path, entry.name));
+	return total;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function storeChildPath(root, kind, value, suffix = "") {
+	const name = assertStoreName(kind, value);
+	const normalizedRoot = resolve(root);
+	const candidate = resolve(normalizedRoot, `${name}${suffix}`);
+	if (!isStrictDescendant(normalizedRoot, candidate)) throw new ServeStoreError("invalid_name", `${kind} escapes its store`);
+	return candidate;
+}
+function isStrictDescendant(root, candidate) {
+	const rootPrefix = root.endsWith(sep) ? root : `${root}${sep}`;
+	return candidate !== root && candidate.startsWith(rootPrefix);
+}
+function validateActivation(alias, value) {
+	const invalid = () => {
+		throw new ServeStoreError("invalid_state", `activation "${alias}" is not a valid version 1 activation`);
+	};
+	if (!isRecord(value)) invalid();
+	const activation = value;
+	if (activation.alias !== alias) invalid();
+	if (![
+		"identityId",
+		"publicKey",
+		"fingerprint",
+		"createdAt"
+	].every((field) => typeof activation[field] === "string" && activation[field].length > 0)) invalid();
+	if (activation.source === "managed") {
+		if (typeof activation.apiUrl !== "string" || activation.apiUrl.length === 0 || activation.configPath !== void 0 || activation.configApiUrl !== void 0) invalid();
+		return;
+	}
+	if (activation.source !== "external" || typeof activation.configPath !== "string" || activation.configPath.length === 0 || typeof activation.configApiUrl !== "string" || activation.configApiUrl.length === 0 || activation.apiUrl !== void 0 && typeof activation.apiUrl !== "string") invalid();
+}
+//#endregion
+//#region src/lib/serve/identity.ts
+/**
+* Serve identity activation (#2061/#1834 boundary).
+*
+* Managed agent files are canonical `MoltNetConfig` documents. Alias,
+* provenance, pinned identity material, and external config paths live only
+* in the versioned activation map in `serve.json`. Every attach and run loads
+* the current config and verifies it with authenticated `whoami` before use.
+*/
+var MAX_CONFIG_BYTES = 64 * 1024;
+var IDENTITY_OPERATION_TIMEOUT_MS = 15e3;
+var pendingAliases = /* @__PURE__ */ new WeakMap();
+var ServeIdentityError = class extends Error {
+	name = "ServeIdentityError";
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+	}
+};
+function reserveAlias(store, alias) {
+	let pending = pendingAliases.get(store);
+	if (!pending) {
+		pending = /* @__PURE__ */ new Set();
+		pendingAliases.set(store, pending);
+	}
+	if (pending.has(alias) || store.hasPendingRegistration(alias) || store.readActivation(alias) || store.readAgentConfig(alias)) throw new ServeIdentityError("agent_exists", `agent "${alias}" already exists in the serve store`);
+	pending.add(alias);
+	return () => pending.delete(alias);
+}
+async function createManagedAgent(store, secrets, input) {
+	const alias = assertStoreName("agent name", input.name);
+	const releaseAlias = reserveAlias(store, alias);
+	let registeredIdentityId;
+	try {
+		let apiUrl;
+		try {
+			apiUrl = requireSecureCredentialApiUrl(input.apiUrl);
+		} catch (cause) {
+			throw new ServeIdentityError("registration_failed", "registration API URL must use HTTPS or HTTP loopback", { cause });
+		}
+		store.reserveRegistration(alias, apiUrl);
+		const result = await register({
+			credentialType: "agent_key",
+			apiUrl,
+			...input.enrollmentToken ? { enrollmentToken: input.enrollmentToken } : {},
+			signal: boundedIdentitySignal(input.signal)
+		});
+		if (result.credentials.type !== "agent_key") throw new ServeIdentityError("unsupported_credential", `registration returned credential type "${result.credentials.type}"; serve manages agent-key credentials only`);
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		const { identityId, fingerprint, publicKey, privateKey } = result.identity;
+		registeredIdentityId = identityId;
+		const agentKeyReference = {
+			provider: FILE_SECRET_PROVIDER,
+			key: agentKeyKey(identityId)
+		};
+		const seedReference = {
+			provider: FILE_SECRET_PROVIDER,
+			key: identitySeedKey(fingerprint)
+		};
+		const config = {
+			identity_id: identityId,
+			registered_at: now,
+			agent_key_ref: agentKeyReference,
+			keys: {
+				public_key: publicKey,
+				fingerprint,
+				private_key_ref: seedReference
+			},
+			endpoints: {
+				api: result.apiUrl,
+				mcp: deriveMcpUrl(result.apiUrl)
+			}
+		};
+		const activation = {
+			alias,
+			source: "managed",
+			identityId,
+			publicKey,
+			fingerprint,
+			createdAt: now,
+			apiUrl: result.apiUrl
+		};
+		store.writeAgentConfig(alias, config);
+		await secrets.write(agentKeyReference.key, result.credentials.secret);
+		await secrets.write(seedReference.key, privateKey);
+		store.writeActivation(activation);
+		return {
+			activation,
+			config
+		};
+	} catch (cause) {
+		if (!registeredIdentityId && cause instanceof MoltNetError && cause.statusCode !== void 0 && cause.statusCode >= 400 && cause.statusCode < 500) {
+			store.clearPendingRegistration(alias);
+			throw new ServeIdentityError("registration_failed", `registration for "${alias}" was rejected`, { cause });
+		}
+		if (store.hasPendingRegistration(alias)) throw new ServeIdentityError("registration_incomplete", registeredIdentityId ? `identity "${registeredIdentityId}" was registered but local activation is incomplete; reconcile or clear its pending serve record before retrying` : `registration for "${alias}" may be incomplete; inspect the remote API before changing its pending serve record`, { cause });
+		throw cause;
+	} finally {
+		releaseAlias();
+	}
+}
+/** Resume a fully persisted registration or explicitly abandon local recovery. */
+async function reconcileManagedRegistration(store, secrets, aliasInput, action, connectAgent = connect, signal) {
+	const alias = assertStoreName("agent name", aliasInput);
+	const activation = store.readActivation(alias);
+	if (activation) {
+		const config = store.readAgentConfig(alias);
+		if (!config) throw new ServeIdentityError("registration_incomplete", `managed activation for "${alias}" is missing its canonical config`);
+		return {
+			activation,
+			config
+		};
+	}
+	if (!store.hasPendingRegistration(alias)) throw new ServeIdentityError("config_not_found", `agent "${alias}" has no pending registration to reconcile`);
+	const config = store.readAgentConfig(alias);
+	if (action === "abandon") {
+		store.removeAgentConfig(alias);
+		store.clearPendingRegistration(alias);
+		return null;
+	}
+	if (!config?.agent_key_ref || config.agent_key_ref.provider !== FILE_SECRET_PROVIDER || config.keys.private_key_ref?.provider !== FILE_SECRET_PROVIDER) throw new ServeIdentityError("registration_incomplete", `pending registration for "${alias}" does not have complete managed references`);
+	const [agentKey, privateKeyState] = await Promise.all([secrets.read(config.agent_key_ref.key), secrets.probe(config.keys.private_key_ref.key)]);
+	if (!agentKey || privateKeyState !== "present") throw new ServeIdentityError("registration_incomplete", `pending registration for "${alias}" is missing persisted secret material`);
+	const identity = identityFromConfig(config);
+	const apiUrl = requireConfigApiUrl(config, store.agentPath(alias));
+	assertIdentityMatches(await callWhoami(connectAgent, {
+		agentKey,
+		apiUrl
+	}, store.agentPath(alias), signal), identity, "authenticated whoami", `pending registration "${alias}" config`);
+	const recovered = {
+		alias,
+		source: "managed",
+		...identity,
+		createdAt: config.registered_at,
+		apiUrl
+	};
+	store.writeActivation(recovered);
+	return {
+		activation: recovered,
+		config
+	};
+}
+async function attachExternalAgent(store, secretProviders, input, connectAgent = connect) {
+	const alias = assertStoreName("agent name", input.name);
+	const releaseAlias = reserveAlias(store, alias);
+	try {
+		if (!isAbsolute(input.configDir)) throw new ServeIdentityError("config_not_found", "external configDir must be an absolute path");
+		const configPath = join(input.configDir, "moltnet.json");
+		externalAgentLocation(configPath);
+		const config = await readCurrentConfig(configPath);
+		const configApiUrl = requireTrustedConfigApiUrl(config, configPath);
+		const effectiveApiUrl = requireTrustedApiOverride(input.apiUrl, configApiUrl, configPath);
+		const whoami = await authenticateConfig(input.configDir, effectiveApiUrl, secretProviders, connectAgent, input.signal);
+		const identity = identityFromConfig(config);
+		assertIdentityMatches(identity, whoami, `external config ${configPath}`, "authenticated whoami");
+		const activation = {
+			alias,
+			source: "external",
+			...identity,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			configPath,
+			configApiUrl,
+			...input.apiUrl ? { apiUrl: input.apiUrl } : {}
+		};
+		store.writeActivation(activation);
+		return {
+			activation,
+			config
+		};
+	} finally {
+		releaseAlias();
+	}
+}
+/** Load and authenticate the current config, then compare all pinned fields. */
+async function verifyAgentActivation(store, alias, managedSecretProviders, externalSecretProviders, connectAgent = connect, signal) {
+	const activation = requireActivation(store, alias);
+	const verified = activation.source === "managed" ? await verifyManagedActivation(store, activation, managedSecretProviders, connectAgent, signal) : await verifyExternalActivation(activation, externalSecretProviders, connectAgent, signal);
+	assertIdentityMatches(verified.whoami, activation, "authenticated whoami", `agent "${activation.alias}" pinned activation`);
+	return {
+		activation,
+		config: verified.config
+	};
+}
+async function verifyManagedActivation(store, activation, secretProviders, connectAgent, signal) {
+	const configPath = store.agentPath(activation.alias);
+	const config = await readCurrentConfig(configPath);
+	assertActivatedConfig(config, activation, configPath, requireConfigApiUrl(config, configPath), activation.apiUrl);
+	let agentKey;
+	try {
+		agentKey = await resolveAgentKey(config, secretProviders);
+	} catch (cause) {
+		throw verificationError(`could not resolve the managed agent key for "${activation.alias}"`, cause);
+	}
+	if (!agentKey) throw new ServeIdentityError("verification_failed", `managed config for "${activation.alias}" has no agent_key_ref`);
+	return {
+		config,
+		whoami: await callWhoami(connectAgent, {
+			agentKey,
+			apiUrl: activation.apiUrl
+		}, configPath, signal)
+	};
+}
+async function verifyExternalActivation(activation, secretProviders, connectAgent, signal) {
+	externalAgentLocation(activation.configPath);
+	assertTrustedConfigApiUrl(activation.configApiUrl);
+	const config = await readCurrentConfig(activation.configPath);
+	assertActivatedConfig(config, activation, activation.configPath, requireTrustedConfigApiUrl(config, activation.configPath), activation.configApiUrl);
+	const effectiveApiUrl = requireTrustedApiOverride(activation.apiUrl, activation.configApiUrl, activation.configPath);
+	return {
+		config,
+		whoami: await authenticateConfig(dirname(activation.configPath), effectiveApiUrl, secretProviders, connectAgent, signal)
+	};
+}
+/** Never let request or activation metadata redirect persisted credentials. */
+function requireTrustedApiOverride(override, configApiUrl, configPath) {
+	if (!override) return configApiUrl;
+	if (override !== configApiUrl) throw new ServeIdentityError("verification_failed", `API override for ${configPath} does not match its configured endpoint`);
+	return configApiUrl;
+}
+function assertActivatedConfig(config, activation, configPath, currentApiUrl, pinnedApiUrl) {
+	if (currentApiUrl !== pinnedApiUrl) throw new ServeIdentityError("verification_failed", `agent config at ${configPath} API endpoint does not match its pinned activation`);
+	assertIdentityMatches(identityFromConfig(config), activation, configPath, `agent "${activation.alias}" pinned activation`);
+}
+function requireConfigApiUrl(config, configPath) {
+	const apiUrl = config?.endpoints?.api?.trim();
+	if (!apiUrl) throw new ServeIdentityError("verification_failed", `agent config at ${configPath} is missing endpoints.api`);
+	return apiUrl;
+}
+function requireTrustedConfigApiUrl(config, configPath) {
+	const apiUrl = requireConfigApiUrl(config, configPath);
+	try {
+		assertTrustedConfigApiUrl(apiUrl);
+		return apiUrl;
+	} catch (cause) {
+		throw verificationError(`agent config at ${configPath} has an untrusted endpoints.api`, cause);
+	}
+}
+async function readCurrentConfig(configPath) {
+	let file;
+	try {
+		file = await open(configPath, "r");
+	} catch (cause) {
+		throw new ServeIdentityError("config_not_found", `agent config is missing at ${configPath}`, { cause });
+	}
+	let raw;
+	try {
+		if (!(await file.stat()).isFile()) throw new ServeIdentityError("verification_failed", `agent config at ${configPath} must be a regular file no larger than ${MAX_CONFIG_BYTES} bytes`);
+		const buffer = Buffer.alloc(MAX_CONFIG_BYTES + 1);
+		const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+		if (bytesRead > MAX_CONFIG_BYTES) throw new ServeIdentityError("verification_failed", `agent config at ${configPath} must be a regular file no larger than ${MAX_CONFIG_BYTES} bytes`);
+		raw = buffer.toString("utf8", 0, bytesRead);
+	} finally {
+		await file.close();
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (cause) {
+		throw verificationError(`agent config is not valid JSON at ${configPath}`, cause);
+	}
+}
+/** Resolve the unchanged daemon CLI's root/name pair for an external config. */
+function externalAgentLocation(configPath) {
+	const configDir = dirname(configPath);
+	const moltnetDir = dirname(configDir);
+	if (!isAbsolute(configPath) || basename(configPath) !== "moltnet.json" || basename(moltnetDir) !== ".moltnet") throw new ServeIdentityError("config_not_found", `external config must be at an absolute <agent-root>/.moltnet/<agent>/moltnet.json path`);
+	return {
+		agentName: assertStoreName("external config agent name", basename(configDir)),
+		agentRoot: dirname(moltnetDir)
+	};
+}
+async function authenticateConfig(configDir, apiUrl, secretProviders, connectAgent, signal) {
+	return callWhoami(connectAgent, {
+		configDir,
+		...apiUrl ? { apiUrl } : {},
+		secretProviders
+	}, configDir, signal);
+}
+async function callWhoami(connectAgent, options, source, signal) {
+	try {
+		const boundedSignal = boundedIdentitySignal(signal);
+		return await (await connectAgent({
+			...options,
+			signal: boundedSignal
+		})).agents.whoami({ signal: boundedSignal });
+	} catch (cause) {
+		throw verificationError(`could not authenticate ${source} against the API`, cause);
+	}
+}
+function boundedIdentitySignal(signal) {
+	const timeout = AbortSignal.timeout(IDENTITY_OPERATION_TIMEOUT_MS);
+	return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+function identityFromConfig(config) {
+	const identityId = config?.identity_id?.trim();
+	const publicKey = config?.keys?.public_key?.trim();
+	const fingerprint = config?.keys?.fingerprint?.trim();
+	if (!identityId || !publicKey || !fingerprint) throw new ServeIdentityError("verification_failed", "agent config is missing canonical identity_id, keys.public_key, or keys.fingerprint");
+	return {
+		identityId,
+		publicKey,
+		fingerprint
+	};
+}
+function assertIdentityMatches(current, expected, currentLabel, expectedLabel) {
+	const assessment = assessIdentityPin(current, expected);
+	if (!assessment.ok) throw new ServeIdentityError("verification_failed", `${currentLabel} ${assessment.label} does not match ${expectedLabel}`);
+}
+function verificationError(message, cause) {
+	return new ServeIdentityError("verification_failed", message, { cause });
+}
+/** Non-secret projection preserving the existing `/v1` response shape. */
+function publicAgentView(store, activation) {
+	if (activation.source === "managed") {
+		const config = store.readAgentConfig(activation.alias);
+		return {
+			kind: "managed",
+			agentName: activation.alias,
+			identityId: activation.identityId,
+			fingerprint: activation.fingerprint,
+			apiUrl: activation.apiUrl,
+			createdAt: activation.createdAt,
+			hasAgentKey: Boolean(config?.agent_key_ref),
+			hasPrivateKey: Boolean(config?.keys.private_key_ref)
+		};
+	}
+	return {
+		kind: "external",
+		agentName: activation.alias,
+		configDir: dirname(activation.configPath),
+		...activation.apiUrl ? { apiUrl: activation.apiUrl } : {},
+		identityId: activation.identityId,
+		fingerprint: activation.fingerprint,
+		createdAt: activation.createdAt
+	};
+}
+function requireActivation(store, alias) {
+	const activation = store.readActivation(alias);
+	if (!activation) throw new ServeStoreError("not_found", `agent "${alias}" is not configured`);
+	return activation;
+}
+//#endregion
+//#region src/lib/serve/runs.ts
+var STOP_GRACE_MS = 1e4;
+var STOP_FORCE_MS = 2e3;
+var DEFAULT_MAX_LOG_BYTES = 10 * 1024 * 1024;
+var DEFAULT_MAX_COMPLETED_RUNS = 100;
+var DEFAULT_MAX_RUN_AGE_MS = 720 * 60 * 60 * 1e3;
+var DEFAULT_MAX_RUN_STORAGE_BYTES = 512 * 1024 * 1024;
+var DEFAULT_MAX_ACTIVE_RUNS = 16;
+var DEFAULT_MAX_ACTIVE_RUNS_PER_AGENT = 4;
+var LOG_TRUNCATION_MARKER = Buffer.from("[truncated]\n");
+var INHERITED_ENV_NAMES = new Set([
+	"COLORTERM",
+	"FORCE_COLOR",
+	"LANG",
+	"LC_ALL",
+	"LC_CTYPE",
+	"LOG_LEVEL",
+	"NO_COLOR",
+	"PATH",
+	"SSL_CERT_DIR",
+	"SSL_CERT_FILE",
+	"TEMP",
+	"TERM",
+	"TMP",
+	"TMPDIR",
+	"TZ"
+]);
+var INHERITED_MOLTNET_ENV_NAMES = new Set([
+	"MOLTNET_CLI_LINUX_BINARY",
+	"MOLTNET_CREDENTIAL_BINDINGS",
+	"MOLTNET_CREDENTIAL_ENFORCEMENT",
+	"MOLTNET_DIARY_ID",
+	"MOLTNET_GIT_AUTHOR",
+	"MOLTNET_OTEL_ENDPOINT",
+	"MOLTNET_PI_VM_INTEGRATION",
+	"MOLTNET_PROFILE_CREDENTIAL_REQUIREMENTS",
+	"MOLTNET_SIGNER_URL",
+	"MOLTNET_TRACE_IDLE_POLLING"
+]);
+var ServeRunError = class extends Error {
+	name = "ServeRunError";
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+	}
+};
+function validateRunSpec(spec) {
+	if (spec.mode !== "poll" && spec.mode !== "drain") throw new ServeRunError("invalid_spec", "mode must be poll or drain");
+	if (!spec.agent) throw new ServeRunError("invalid_spec", "agent is required");
+	if (!spec.teamId) throw new ServeRunError("invalid_spec", "teamId is required");
+	if (!Array.isArray(spec.profiles) || spec.profiles.length === 0) throw new ServeRunError("invalid_spec", "at least one profile is required");
+	if (!Array.isArray(spec.taskTypes) || spec.taskTypes.length === 0) throw new ServeRunError("invalid_spec", "at least one task type is required");
+}
+var RunManager = class {
+	active = /* @__PURE__ */ new Map();
+	startingByAgent = /* @__PURE__ */ new Map();
+	starting = 0;
+	closing = false;
+	constructor(options) {
+		this.options = options;
+		this.reconcileInterruptedRuns();
+		this.pruneCompletedRuns();
+	}
+	get store() {
+		return this.options.store;
+	}
+	entrypoint() {
+		return this.options.entrypoint ?? {
+			execPath: process.execPath,
+			execArgv: process.execArgv,
+			scriptPath: process.argv[1] ?? ""
+		};
+	}
+	/** Assemble child env + args for a run. Exposed for tests. */
+	async prepare(spec, agent, piDir, providers = this.store.readProviders()) {
+		const { activation, config } = agent;
+		const homeDir = join(dirname(piDir), "home");
+		const env = {
+			HOME: homeDir,
+			PI_CODING_AGENT_DIR: piDir,
+			XDG_CACHE_HOME: join(homeDir, ".cache"),
+			XDG_CONFIG_HOME: join(homeDir, ".config"),
+			XDG_DATA_HOME: join(homeDir, ".local", "share"),
+			MOLTNET_TEAM_ID: spec.teamId
+		};
+		const target = activation.source === "managed" ? {
+			agentName: activation.alias,
+			cwd: dirname(piDir),
+			extraArgs: []
+		} : (() => {
+			const { agentName, agentRoot } = externalAgentLocation(activation.configPath);
+			return {
+				agentName,
+				cwd: agentRoot,
+				extraArgs: ["--agent-root", agentRoot]
+			};
+		})();
+		const args = [
+			spec.mode,
+			"--agent",
+			target.agentName,
+			"--team",
+			spec.teamId,
+			...spec.profiles.flatMap((profile) => ["--profile", profile]),
+			"--task-types",
+			spec.taskTypes.join(","),
+			...target.extraArgs
+		];
+		if (activation.source === "managed") {
+			if (!config.agent_key_ref || !config.keys.private_key_ref) throw new ServeRunError("invalid_spec", `managed config for "${activation.alias}" is missing canonical secret references`);
+			env["MOLTNET_API_URL"] = activation.apiUrl;
+			env["MOLTNET_AGENT_KEY_REF"] = formatSecretReferenceString(config.agent_key_ref);
+			env["MOLTNET_PRIVATE_KEY_REF"] = formatSecretReferenceString(config.keys.private_key_ref);
+			env["MOLTNET_SECRET_ROOT"] = this.store.secretsDir;
+		} else {
+			env["MOLTNET_API_URL"] = activation.apiUrl ?? activation.configApiUrl;
+			try {
+				const agentKey = await resolveAgentKey(config, this.options.externalSecretProviders);
+				if (agentKey) {
+					env["MOLTNET_AGENT_KEY"] = agentKey;
+					env["MOLTNET_PRIVATE_KEY"] = await resolveIdentitySeed(config, this.options.externalSecretProviders);
+				} else if (config.oauth2?.client_secret_ref) {
+					env["MOLTNET_CLIENT_ID"] = config.oauth2.client_id;
+					env["MOLTNET_CLIENT_SECRET"] = await resolveOAuth2ClientSecret(config, this.options.externalSecretProviders);
+				}
+				if (!agentKey && config.keys.private_key_ref) env["MOLTNET_PRIVATE_KEY"] = await resolveIdentitySeed(config, this.options.externalSecretProviders);
+			} catch {
+				throw new ServeRunError("invalid_spec", `external credentials for "${activation.alias}" could not be projected`);
+			}
+		}
+		env["MOLTNET_EXPECTED_IDENTITY_ID"] = activation.identityId;
+		env["MOLTNET_EXPECTED_PUBLIC_KEY"] = activation.publicKey;
+		env["MOLTNET_EXPECTED_FINGERPRINT"] = activation.fingerprint;
+		env["MOLTNET_SUPERVISED_RUN"] = "1";
+		for (const [providerId, provider] of Object.entries(providers)) {
+			if (!provider.apiKeyRef) continue;
+			let value;
+			try {
+				value = await this.options.secretProviders.resolve(parseSecretReferenceString(provider.apiKeyRef));
+			} catch {
+				throw new ServeRunError("invalid_spec", `provider "${providerId}" API key could not be resolved`);
+			}
+			env[provider.envName] = value;
+		}
+		return {
+			args,
+			env,
+			cwd: target.cwd
+		};
+	}
+	async start(spec, signal) {
+		validateRunSpec(spec);
+		const releaseStart = this.reserveStart(spec.agent);
+		try {
+			return await this.startReserved(spec, signal);
+		} finally {
+			releaseStart();
+		}
+	}
+	async startReserved(spec, signal) {
+		this.assertStartOpen(signal);
+		const agent = await (this.options.verifyActivationImpl ?? verifyAgentActivation)(this.store, spec.agent, this.options.secretProviders, this.options.externalSecretProviders, void 0, signal);
+		this.assertStartOpen(signal);
+		const id = `${Date.now().toString(36)}-${randomBytes(4).toString("hex")}`;
+		const runDir = this.store.runDir(id);
+		const piDir = join(runDir, "pi");
+		const providers = this.store.readProviders();
+		const { args, env, cwd } = await this.prepare(spec, agent, piDir, providers);
+		this.assertStartOpen(signal);
+		let child;
+		let logStream;
+		let logLimiter;
+		try {
+			const { logPath } = this.store.createRunDir(id);
+			for (const dir of [
+				env.HOME,
+				env.XDG_CACHE_HOME,
+				env.XDG_CONFIG_HOME,
+				env.XDG_DATA_HOME
+			]) mkdirSync(dir, {
+				recursive: true,
+				mode: 448
+			});
+			writePiConfig({
+				piDir,
+				providers: Object.fromEntries(Object.entries(providers).map(([providerId, provider]) => [providerId, {
+					api: provider.api,
+					...provider.apiKeyRef ? { apiKeyEnvRef: `$${provider.envName}` } : {},
+					baseUrl: provider.baseUrl,
+					models: provider.models
+				}]))
+			});
+			const entry = this.entrypoint();
+			logStream = createWriteStream(logPath, {
+				fd: openSync(logPath, "a", 384),
+				autoClose: true
+			});
+			logLimiter = createByteLimitTransform(this.options.maxLogBytes ?? DEFAULT_MAX_LOG_BYTES, () => this.log("warn", "serve run log output truncated", {
+				...runContext(id, spec.agent, child),
+				transition: "log_truncated"
+			}));
+			logLimiter.pipe(logStream);
+			logStream.on("error", (error) => {
+				this.log("error", "serve run log stream failed", {
+					...runContext(id, spec.agent, child),
+					transition: "log_failed",
+					...safeRunError(error)
+				});
+				child?.kill("SIGKILL");
+			});
+			const spawnImpl = this.options.spawnImpl ?? spawn;
+			this.assertStartOpen(signal);
+			child = spawnImpl(entry.execPath, [
+				...entry.execArgv,
+				entry.scriptPath,
+				...args
+			], {
+				cwd,
+				env: {
+					...sanitizeChildBaseEnv(this.options.baseEnv),
+					...env
+				},
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe",
+					"ipc"
+				],
+				detached: false
+			});
+			this.active.set(id, {
+				agent: spec.agent,
+				child,
+				stopRequested: false
+			});
+			child.stdout?.pipe(logLimiter, { end: false });
+			child.stderr?.pipe(logLimiter, { end: false });
+			const record = {
+				...spec,
+				id,
+				status: "running",
+				pid: child.pid,
+				startedAt: (this.options.now?.() ?? /* @__PURE__ */ new Date()).toISOString()
+			};
+			child.once("exit", (code, signal) => {
+				const activeRun = this.active.get(id);
+				this.active.delete(id);
+				logLimiter?.end();
+				const status = activeRun?.stopRequested ? "stopped" : code === 0 ? "exited" : "failed";
+				this.log(status === "failed" ? "error" : "info", "serve run exited", {
+					...runContext(id, spec.agent, child),
+					transition: status,
+					exitCode: code,
+					signal
+				});
+				this.persistRunCompletion(id, spec.agent, {
+					status,
+					exitCode: code
+				});
+			});
+			child.once("error", (error) => {
+				this.active.delete(id);
+				logLimiter?.end();
+				this.log("error", "serve run child process failed", {
+					...runContext(id, spec.agent, child),
+					transition: "spawn_failed",
+					...safeRunError(error)
+				});
+				this.persistRunCompletion(id, spec.agent, { status: "failed" });
+			});
+			this.store.writeRun(record);
+			this.log("info", "serve run started", {
+				...runContext(id, spec.agent, child),
+				transition: "running"
+			});
+			return record;
+		} catch (cause) {
+			logLimiter?.destroy();
+			logStream?.destroy();
+			if (child && !await terminateChild(child)) throw new AggregateError([cause], `run "${id}" failed to start and its child did not exit after SIGKILL`);
+			this.active.delete(id);
+			rmSync(runDir, {
+				recursive: true,
+				force: true
+			});
+			this.log("error", "serve run failed to start", {
+				...runContext(id, spec.agent, child),
+				transition: "start_failed",
+				...safeRunError(cause)
+			});
+			throw cause;
+		}
+	}
+	stop(id) {
+		const record = this.store.readRun(id);
+		if (!record) throw new ServeRunError("run_not_found", `run "${id}" was not found`);
+		const activeRun = this.active.get(id);
+		if (!activeRun) throw new ServeRunError("run_not_active", `run "${id}" is not running`);
+		activeRun.stopRequested = true;
+		this.log("info", "serve run stop requested", {
+			...runContext(id, record.agent, activeRun.child),
+			transition: "stopping",
+			signal: "SIGTERM"
+		});
+		activeRun.child.kill("SIGTERM");
+		setTimeout(() => {
+			if (this.active.has(id)) activeRun.child.kill("SIGKILL");
+		}, STOP_GRACE_MS).unref();
+		return record;
+	}
+	/** Live status merged over the persisted record. */
+	status(id) {
+		const record = this.store.readRun(id);
+		if (!record) throw new ServeStoreError("not_found", `run "${id}" was not found`);
+		return record;
+	}
+	list(limit = Number.POSITIVE_INFINITY) {
+		if (!Number.isFinite(limit)) return this.store.listRuns();
+		const active = [...this.active.keys()].map((id) => this.store.readRun(id)).filter((record) => record !== null).sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+		const activeIds = new Set(active.map((record) => record.id));
+		const history = this.store.listRuns(limit + active.length).filter((record) => !activeIds.has(record.id)).slice(0, limit);
+		return [...active, ...history];
+	}
+	isActive(id) {
+		return this.active.has(id);
+	}
+	async stopAll() {
+		this.closing = true;
+		const waits = [];
+		for (const [id, activeRun] of this.active) {
+			activeRun.stopRequested = true;
+			waits.push(new Promise((resolvePromise, rejectPromise) => {
+				let settled = false;
+				const finish = () => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(killTimer);
+					clearTimeout(forceTimer);
+					resolvePromise();
+				};
+				activeRun.child.once("exit", finish);
+				activeRun.child.kill("SIGTERM");
+				const killTimer = setTimeout(() => {
+					activeRun.child.kill("SIGKILL");
+				}, STOP_GRACE_MS);
+				killTimer.unref();
+				const forceTimer = setTimeout(() => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(killTimer);
+					rejectPromise(/* @__PURE__ */ new Error(`run "${id}" did not exit after SIGKILL`));
+				}, STOP_GRACE_MS + STOP_FORCE_MS);
+				forceTimer.unref();
+			}));
+		}
+		await Promise.all(waits);
+	}
+	forceStopAll() {
+		this.closing = true;
+		for (const [id, activeRun] of this.active) {
+			activeRun.stopRequested = true;
+			this.log("warn", "serve run force stop requested", {
+				...runContext(id, this.store.readRun(id)?.agent ?? "unknown", activeRun.child),
+				transition: "force_stopping",
+				signal: "SIGKILL"
+			});
+			activeRun.child.kill("SIGKILL");
+		}
+	}
+	reconcileInterruptedRuns() {
+		const endedAt = (this.options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
+		for (const record of this.store.listRuns()) {
+			if (record.status !== "running") continue;
+			this.store.writeRun({
+				...record,
+				status: "failed",
+				exitCode: null,
+				endedAt
+			});
+			this.log("warn", "serve run interrupted by supervisor replacement", {
+				runId: record.id,
+				agent: record.agent,
+				pid: record.pid,
+				transition: "interrupted"
+			});
+		}
+	}
+	reserveStart(agent) {
+		if (this.closing) throw new ServeRunError("invalid_spec", "serve is shutting down");
+		const agentStarting = this.startingByAgent.get(agent) ?? 0;
+		const agentActive = [...this.active.values()].filter((run) => run.agent === agent).length;
+		if (this.active.size + this.starting >= (this.options.maxActiveRuns ?? DEFAULT_MAX_ACTIVE_RUNS) || agentActive + agentStarting >= (this.options.maxActiveRunsPerAgent ?? DEFAULT_MAX_ACTIVE_RUNS_PER_AGENT)) throw new ServeRunError("invalid_spec", `active run limit reached for agent "${agent}"`);
+		this.starting += 1;
+		this.startingByAgent.set(agent, agentStarting + 1);
+		return () => {
+			this.starting -= 1;
+			const remaining = (this.startingByAgent.get(agent) ?? 1) - 1;
+			if (remaining > 0) this.startingByAgent.set(agent, remaining);
+			else this.startingByAgent.delete(agent);
+		};
+	}
+	assertStartOpen(signal) {
+		if (this.closing || signal?.aborted) throw new ServeRunError("invalid_spec", "serve is shutting down");
+	}
+	pruneCompletedRuns() {
+		const removed = this.store.pruneCompletedRuns({
+			maxCount: this.options.maxCompletedRuns ?? DEFAULT_MAX_COMPLETED_RUNS,
+			maxAgeMs: this.options.maxRunAgeMs ?? DEFAULT_MAX_RUN_AGE_MS,
+			maxBytes: this.options.maxRunStorageBytes ?? DEFAULT_MAX_RUN_STORAGE_BYTES,
+			now: this.options.now?.() ?? /* @__PURE__ */ new Date()
+		});
+		if (removed.length > 0) this.log("info", "serve run retention removed completed artifacts", {
+			transition: "pruned",
+			removedCount: removed.length
+		});
+	}
+	persistRunCompletion(id, agent, update) {
+		try {
+			const current = this.store.readRun(id);
+			if (current) this.store.writeRun({
+				...current,
+				...update,
+				endedAt: (this.options.now?.() ?? /* @__PURE__ */ new Date()).toISOString()
+			});
+			this.pruneCompletedRuns();
+		} catch (error) {
+			this.log("error", "serve run completion persistence failed", {
+				runId: id,
+				agent,
+				transition: "persistence_failed",
+				...safeRunError(error)
+			});
+		}
+	}
+	log(level, message, context) {
+		this.options.logger?.[level](context, message);
+	}
+};
+function createByteLimitTransform(limit, onTruncated) {
+	const byteLimit = Math.max(0, Math.floor(limit));
+	const contentLimit = Math.max(0, byteLimit - LOG_TRUNCATION_MARKER.length);
+	let emitted = 0;
+	let truncated = false;
+	return new Transform({ transform(chunk, _encoding, callback) {
+		const remaining = Math.max(0, contentLimit - emitted);
+		const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		if (remaining > 0) {
+			const selected = bytes.subarray(0, remaining);
+			emitted += selected.length;
+			this.push(selected);
+		}
+		if (!truncated && bytes.length > remaining) {
+			truncated = true;
+			const marker = LOG_TRUNCATION_MARKER.subarray(0, byteLimit - emitted);
+			emitted += marker.length;
+			this.push(marker);
+			onTruncated();
+		}
+		callback();
+	} });
+}
+function runContext(runId, agent, child) {
+	return {
+		runId,
+		agent,
+		pid: child?.pid
+	};
+}
+function safeRunError(error) {
+	const code = error?.code;
+	return {
+		errorType: error instanceof Error ? error.name : typeof error,
+		...typeof code === "string" ? { errorCode: code } : {}
+	};
+}
+function sanitizeChildBaseEnv(baseEnv) {
+	return Object.fromEntries(Object.entries(baseEnv).filter(([name]) => INHERITED_ENV_NAMES.has(name) || INHERITED_MOLTNET_ENV_NAMES.has(name)));
+}
+async function terminateChild(child) {
+	if (child.exitCode !== null && child.exitCode !== void 0) return true;
+	return new Promise((resolvePromise) => {
+		const timer = setTimeout(() => resolvePromise(false), STOP_FORCE_MS);
+		timer.unref();
+		child.once("exit", () => {
+			clearTimeout(timer);
+			resolvePromise(true);
+		});
+		child.kill("SIGKILL");
+	});
+}
+//#endregion
+//#region src/lib/serve/serve-lock.ts
+var ServeLockError = class extends Error {
+	name = "ServeLockError";
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+	}
+};
+/**
+* Acquire the per-root singleton lock. `proper-lockfile` uses an atomic lock
+* directory at exactly `<root>/serve.lock`, recovers stale owners, and keeps
+* the mtime fresh while the supervisor is alive.
+*/
+async function acquireServeLock(root, options = {}) {
+	const path = join(root, "serve.lock");
+	let releaseLock;
+	try {
+		releaseLock = await lock(root, {
+			lockfilePath: path,
+			realpath: false,
+			retries: 0,
+			...options.staleMs === void 0 ? {} : { stale: options.staleMs },
+			...options.updateMs === void 0 ? {} : { update: options.updateMs },
+			onCompromised: (cause) => {
+				const error = new ServeLockError("compromised", `serve lock ${path} was compromised: ${cause.message}`, { cause });
+				if (options.onCompromised) {
+					options.onCompromised(error);
+					return;
+				}
+				throw error;
+			}
+		});
+	} catch (cause) {
+		if (cause.code === "ELOCKED") throw new ServeLockError("held", `another moltnet-agent serve process already owns ${path}`, { cause });
+		throw new ServeLockError("failed", `could not acquire serve lock ${path}: ${cause.message}`, { cause });
+	}
+	let released = false;
+	return {
+		path,
+		async release() {
+			if (released) return;
+			released = true;
+			await releaseLock();
+		}
+	};
+}
+/** Always release after normal completion or startup/runtime failure. */
+async function withServeLock(root, work, options) {
+	const held = await acquireServeLock(root, options);
+	try {
+		return await work();
+	} finally {
+		await held.release();
+	}
+}
+//#endregion
+//#region src/lib/serve/server.ts
+/**
+* HTTP surface of `moltnet-agent serve` (#2061), built on the shared
+* loopback-companion security profile (#2066): loopback Host enforcement,
+* exact-origin CORS, Fetch-Metadata guards, strict JSON parsing.
+*
+* Everything under `/v1` except the pairing bootstrap requires a paired
+* origin: the `x-moltnet-serve-token` header must verify against the
+* origin-bound token issued by the one-click pairing ceremony.
+*/
+var SERVE_TOKEN_HEADER = "x-moltnet-serve-token";
+var BODY_LIMIT = 64 * 1024;
+var LOG_POLL_INTERVAL_MS = 500;
+var LOG_STREAM_MAX_DURATION_MS = 3600 * 1e3;
+var MAX_LOG_STREAMS = 32;
+var LOG_READ_LIMIT_BYTES = 256 * 1024;
+var RUN_HISTORY_LIMIT = 100;
+var RATE_LIMIT_MAX = 120;
+var RATE_LIMIT_WINDOW_MS = 6e4;
+async function readServeLogDelta(handle, state, limit = LOG_READ_LIMIT_BYTES) {
+	const info = await handle.stat();
+	if (!info.isFile() || info.size <= state.offset) return {
+		lines: [],
+		omitted: false
+	};
+	const size = info.size;
+	const start = Math.max(state.offset, size - limit);
+	let omitted = start > state.offset;
+	const buffer = Buffer.alloc(size - start);
+	let totalRead = 0;
+	while (totalRead < buffer.length) {
+		const { bytesRead } = await handle.read(buffer, totalRead, buffer.length - totalRead, start + totalRead);
+		if (bytesRead === 0) break;
+		totalRead += bytesRead;
+	}
+	state.offset = start + totalRead;
+	if (omitted) {
+		state.fragment = "";
+		state.decoder = new StringDecoder("utf8");
+		state.discardingLine = true;
+	}
+	state.decoder ??= new StringDecoder("utf8");
+	let text = state.fragment + state.decoder.write(buffer.subarray(0, totalRead));
+	state.fragment = "";
+	if (state.discardingLine) {
+		const boundary = text.indexOf("\n");
+		if (boundary === -1) return {
+			lines: [],
+			omitted
+		};
+		text = text.slice(boundary + 1);
+		state.discardingLine = false;
+	}
+	const parts = text.split("\n");
+	const fragment = parts.pop() ?? "";
+	const lines = [];
+	for (const line of parts) if (line.length > limit) omitted = true;
+	else if (line.length > 0) lines.push(line);
+	if (fragment.length > limit) {
+		state.discardingLine = true;
+		omitted = true;
+	} else state.fragment = fragment;
+	return {
+		lines,
+		omitted
+	};
+}
+var ServeHttpError = class extends Error {
+	name = "ServeHttpError";
+	constructor(statusCode, code, message) {
+		super(message);
+		this.statusCode = statusCode;
+		this.code = code;
+	}
+};
+function requireBody(request) {
+	const body = request.body;
+	if (typeof body !== "object" || body === null || Array.isArray(body)) throw new ServeHttpError(400, "invalid_body", "JSON object body required");
+	return body;
+}
+function requireString(body, field) {
+	const value = body[field];
+	if (typeof value !== "string" || value.trim().length === 0) throw new ServeHttpError(400, "invalid_body", `"${field}" must be a non-empty string`);
+	return value.trim();
+}
+function optionalString(body, field) {
+	const value = body[field];
+	if (value === void 0 || value === null) return void 0;
+	if (typeof value !== "string" || value.trim().length === 0) throw new ServeHttpError(400, "invalid_body", `"${field}" must be a non-empty string when present`);
+	return value.trim();
+}
+function stringArray(body, field) {
+	const value = body[field];
+	if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || item.length === 0)) throw new ServeHttpError(400, "invalid_body", `"${field}" must be a non-empty string array`);
+	return value;
+}
+function requestOperationSignal(request, shutdownSignal) {
+	const disconnected = new AbortController();
+	if (request.raw.aborted) disconnected.abort();
+	else request.raw.once("aborted", () => disconnected.abort());
+	return shutdownSignal ? AbortSignal.any([disconnected.signal, shutdownSignal]) : disconnected.signal;
+}
+function buildServeServer(options) {
+	const { pairing } = options;
+	const app = options.logger ? Fastify({
+		bodyLimit: BODY_LIMIT,
+		loggerInstance: options.logger
+	}) : Fastify({ bodyLimit: BODY_LIMIT });
+	registerLoopbackSecurity(app, {
+		allowedOrigins: options.allowedOrigins,
+		...options.selfOrigin ? { selfOrigins: [options.selfOrigin] } : {},
+		allowedHeaders: [SERVE_TOKEN_HEADER],
+		methods: [
+			"GET",
+			"POST",
+			"PUT",
+			"DELETE",
+			"OPTIONS"
+		]
+	});
+	app.register(rateLimit, {
+		global: false,
+		max: options.rateLimitMax ?? RATE_LIMIT_MAX,
+		timeWindow: RATE_LIMIT_WINDOW_MS,
+		errorResponseBuilder: () => new ServeHttpError(429, "rate_limited", "Too many requests"),
+		keyGenerator: (request) => {
+			const origin = request.headers.origin;
+			return isConfiguredOrigin(origin, options) ? `origin:${origin}` : `ip:${request.ip}`;
+		}
+	});
+	app.after(() => app.addHook("onRequest", app.rateLimit()));
+	app.addContentTypeParser("application/x-www-form-urlencoded", { parseAs: "buffer" }, (_request, body, done) => {
+		try {
+			const form = new TextDecoder("utf-8", { fatal: true }).decode(typeof body === "string" ? Buffer.from(body) : body);
+			done(null, new URLSearchParams(form));
+		} catch {
+			done(new ServeHttpError(400, "invalid_body", "Form body is invalid"), void 0);
+		}
+	});
+	const requirePairedOrigin = (request) => {
+		const origin = requireOriginHeader(request.headers);
+		const token = request.headers[SERVE_TOKEN_HEADER];
+		if (typeof token !== "string" || token.length === 0) throw new ServeHttpError(401, "pairing_required", "Pairing token is required");
+		pairing.verify(origin, token);
+		return origin;
+	};
+	app.get("/health", async () => ({ status: "ok" }));
+	registerPairingRoutes(app, pairing);
+	registerStatusRoute(app, options, requirePairedOrigin);
+	registerAgentRoutes(app, options, requirePairedOrigin);
+	registerProviderRoutes(app, options, requirePairedOrigin);
+	registerRunRoutes(app, options, requirePairedOrigin);
+	app.setNotFoundHandler(async (_request, reply) => reply.code(404).send({
+		code: "not_found",
+		message: "Route is not available"
+	}));
+	app.setErrorHandler(async (error, request, reply) => {
+		const { statusCode, code, message } = normalizeServeError(error);
+		if (statusCode === 500) request.log.error({
+			...safeErrorContext(error),
+			code: "serve_request_failed",
+			method: request.method,
+			route: request.routeOptions.url
+		}, "Serve request failed");
+		return reply.code(statusCode).send({
+			code,
+			message
+		});
+	});
+	return app;
+}
+function registerPairingRoutes(app, pairing) {
+	app.post("/v1/pairings", async (request, reply) => {
+		const origin = requireOriginHeader(request.headers);
+		return reply.code(201).send(pairing.start(origin));
+	});
+	app.get("/pairings/:pairingId", async (request, reply) => {
+		assertNavigationRequest(request.headers);
+		const { pairingId } = request.params;
+		const approval = pairing.approval(pairingId);
+		return reply.type("text/html; charset=utf-8").send(renderPairingApprovalPage({
+			pairingId,
+			origin: approval.origin,
+			confirmToken: approval.confirmToken
+		}));
+	});
+	app.post("/pairings/:pairingId/confirm", async (request, reply) => {
+		rejectExplicitCrossSite(request.headers);
+		const { pairingId } = request.params;
+		if (!(request.body instanceof URLSearchParams)) throw new ServeHttpError(400, "invalid_body", "Confirmation form is invalid");
+		const { origin } = pairing.confirm(pairingId, request.body.get("confirmToken") ?? "");
+		return reply.type("text/html; charset=utf-8").send(renderPairingResultPage({
+			title: "Connection approved",
+			message: `${origin} can now manage local MoltNet agents on this machine.`
+		}));
+	});
+	app.post("/v1/pairings/:pairingId/claim", async (request) => {
+		const origin = requireOriginHeader(request.headers);
+		const { pairingId } = request.params;
+		return pairing.claim(pairingId, origin);
+	});
+}
+function registerStatusRoute(app, options, requirePairedOrigin) {
+	const { store, runs } = options;
+	app.get("/v1/status", async (request) => {
+		requirePairedOrigin(request);
+		return {
+			version: options.version,
+			platform: process.platform,
+			agents: store.listActivations().map((activation) => publicAgentView(store, activation)),
+			providers: Object.fromEntries(Object.entries(store.readProviders()).map(([id, provider]) => [id, providerView(provider)])),
+			runs: runViews(runs)
+		};
+	});
+}
+function registerAgentRoutes(app, options, requirePairedOrigin) {
+	const { store } = options;
+	app.get("/v1/agents", async (request) => {
+		requirePairedOrigin(request);
+		return store.listActivations().map((activation) => publicAgentView(store, activation));
+	});
+	app.post("/v1/agents", async (request, reply) => {
+		requirePairedOrigin(request);
+		const body = requireBody(request);
+		const signal = requestOperationSignal(request, options.shutdownSignal);
+		const kind = requireString(body, "kind");
+		if (kind === "managed") {
+			const enrollmentToken = optionalString(body, "enrollmentToken");
+			const entry = await createManagedAgent(store, options.secrets, {
+				name: requireString(body, "name"),
+				apiUrl: options.defaultApiUrl,
+				...enrollmentToken ? { enrollmentToken } : {},
+				signal
+			});
+			return reply.code(201).send(publicAgentView(store, entry.activation));
+		}
+		if (kind === "external") {
+			const apiUrl = optionalString(body, "apiUrl");
+			const entry = await attachExternalAgent(store, options.externalSecretProviders, {
+				name: requireString(body, "name"),
+				configDir: requireString(body, "configDir"),
+				...apiUrl ? { apiUrl } : {},
+				signal
+			});
+			return reply.code(201).send(publicAgentView(store, entry.activation));
+		}
+		throw new ServeHttpError(400, "invalid_body", "\"kind\" must be \"managed\" or \"external\"");
+	});
+	app.post("/v1/agents/:agentName/reconcile", async (request) => {
+		requirePairedOrigin(request);
+		const { agentName } = request.params;
+		const action = requireString(requireBody(request), "action");
+		if (action !== "resume" && action !== "abandon") throw new ServeHttpError(400, "invalid_body", "\"action\" must be \"resume\" or \"abandon\"");
+		const reconciled = await reconcileManagedRegistration(store, options.secrets, agentName, action, void 0, requestOperationSignal(request, options.shutdownSignal));
+		return reconciled ? publicAgentView(store, reconciled.activation) : { abandoned: true };
+	});
+}
+function registerProviderRoutes(app, options, requirePairedOrigin) {
+	const { store } = options;
+	let mutationQueue = Promise.resolve();
+	const serialize = (mutation) => {
+		const result = mutationQueue.then(mutation, mutation);
+		mutationQueue = result.then(() => void 0, () => void 0);
+		return result;
+	};
+	app.get("/v1/providers", async (request) => {
+		requirePairedOrigin(request);
+		return Object.fromEntries(Object.entries(store.readProviders()).map(([id, provider]) => [id, providerView(provider)]));
+	});
+	app.put("/v1/providers/:providerId", async (request, reply) => {
+		requirePairedOrigin(request);
+		const { providerId: rawProviderId } = request.params;
+		const providerId = assertProviderId(rawProviderId);
+		const body = requireBody(request);
+		const entry = {
+			api: requireString(body, "api"),
+			baseUrl: requireString(body, "baseUrl"),
+			envName: assertProviderEnvName(providerId, requireString(body, "envName")),
+			models: stringArray(body, "models")
+		};
+		const apiKey = optionalString(body, "apiKey");
+		await serialize(async () => {
+			const providers = store.readProviders();
+			if (apiKey) {
+				const key = `pi-provider/${providerId}`;
+				await options.secrets.write(key, apiKey);
+				entry.apiKeyRef = formatSecretReferenceString({
+					provider: FILE_SECRET_PROVIDER,
+					key
+				});
+			} else if (providers[providerId]?.apiKeyRef && providers[providerId].baseUrl === entry.baseUrl) entry.apiKeyRef = providers[providerId].apiKeyRef;
+			providers[providerId] = entry;
+			store.writeProviders(providers);
+		});
+		return reply.code(200).send(providerView(entry));
+	});
+}
+function runViews(runs) {
+	return runs.list(RUN_HISTORY_LIMIT).map((record) => ({
+		...record,
+		active: runs.isActive(record.id)
+	}));
+}
+function registerRunRoutes(app, options, requirePairedOrigin) {
+	const { runs } = options;
+	app.get("/v1/runs", async (request) => {
+		requirePairedOrigin(request);
+		return runViews(runs);
+	});
+	app.post("/v1/runs", async (request, reply) => {
+		requirePairedOrigin(request);
+		const body = requireBody(request);
+		const record = await runs.start({
+			agent: requireString(body, "agent"),
+			teamId: requireString(body, "teamId"),
+			profiles: stringArray(body, "profiles"),
+			taskTypes: stringArray(body, "taskTypes"),
+			mode: requireString(body, "mode")
+		}, requestOperationSignal(request, options.shutdownSignal));
+		return reply.code(201).send(record);
+	});
+	app.delete("/v1/runs/:runId", async (request) => {
+		requirePairedOrigin(request);
+		const { runId } = request.params;
+		return runs.stop(runId);
+	});
+	registerRunLogRoute(app, options, requirePairedOrigin);
+}
+function registerRunLogRoute(app, options, requirePairedOrigin) {
+	const { runs, store } = options;
+	let openStreams = 0;
+	app.get("/v1/runs/:runId/logs", async (request, reply) => {
+		requirePairedOrigin(request);
+		const { runId } = request.params;
+		const record = runs.status(runId);
+		store.resolveRunLogPath(record.id);
+		if (openStreams >= MAX_LOG_STREAMS) throw new ServeHttpError(429, "rate_limited", "Too many concurrent log streams");
+		openStreams += 1;
+		reply.raw.writeHead(200, {
+			"content-type": "text/event-stream",
+			"cache-control": "no-store",
+			connection: "keep-alive",
+			...corsHeadersFor(request, options)
+		});
+		const readState = {
+			offset: 0,
+			fragment: ""
+		};
+		let closed = false;
+		let pollTimer;
+		const durationTimer = setTimeout(() => finish(), LOG_STREAM_MAX_DURATION_MS);
+		durationTimer.unref();
+		function finish(destroy = false) {
+			if (closed) return;
+			closed = true;
+			openStreams -= 1;
+			if (pollTimer) clearTimeout(pollTimer);
+			clearTimeout(durationTimer);
+			if (destroy) reply.raw.destroy();
+			else reply.raw.end();
+		}
+		const writeData = async (line) => {
+			if (closed || reply.raw.write(`data: ${line}\n\n`)) return;
+			await new Promise((resolvePromise) => {
+				const done = () => {
+					reply.raw.off("drain", done);
+					reply.raw.off("close", done);
+					resolvePromise();
+				};
+				reply.raw.once("drain", done);
+				reply.raw.once("close", done);
+			});
+		};
+		const push = async () => {
+			const handle = await open(store.resolveRunLogPath(record.id), constants.O_RDONLY | constants.O_NOFOLLOW);
+			try {
+				const { lines, omitted } = await readServeLogDelta(handle, readState);
+				if (omitted) await writeData("[older log output omitted]");
+				for (const line of lines) await writeData(line);
+			} finally {
+				await handle.close();
+			}
+		};
+		const fail = (error) => {
+			if (closed) return;
+			request.log.warn({
+				...safeErrorContext(error),
+				code: "serve_log_tail_failed",
+				runId
+			}, "serve log tail failed");
+			finish(true);
+		};
+		const schedule = () => {
+			if (closed) return;
+			pollTimer = setTimeout(() => {
+				push().then(() => {
+					if (runs.isActive(record.id)) schedule();
+					else finish();
+				}).catch(fail);
+			}, LOG_POLL_INTERVAL_MS);
+			pollTimer.unref();
+		};
+		request.raw.on("close", () => finish());
+		try {
+			await push();
+			if (runs.isActive(record.id)) schedule();
+			else finish();
+		} catch (error) {
+			fail(error);
+		}
+		return reply;
+	});
+}
+function safeErrorContext(error) {
+	const context = { errorType: error instanceof Error ? error.name : typeof error };
+	const applicationCode = safeErrorToken(error?.code);
+	if (applicationCode) context["applicationCode"] = applicationCode;
+	const cause = error instanceof Error ? error.cause : void 0;
+	const fsCode = safeErrorToken(cause?.code);
+	const syscall = safeErrorToken(cause?.syscall);
+	if (fsCode) context["fsCode"] = fsCode;
+	if (syscall) context["syscall"] = syscall;
+	return context;
+}
+function safeErrorToken(value) {
+	return typeof value === "string" && /^[a-z0-9_:-]{1,64}$/iu.test(value) ? value : void 0;
+}
+function providerView(provider) {
+	return {
+		api: provider.api,
+		baseUrl: provider.baseUrl,
+		envName: provider.envName,
+		models: provider.models,
+		hasApiKey: Boolean(provider.apiKeyRef)
+	};
+}
+function corsHeadersFor(request, options) {
+	const origin = request.headers.origin;
+	if (isConfiguredOrigin(origin, options)) return {
+		"access-control-allow-origin": origin,
+		vary: "origin"
+	};
+	return {};
+}
+function isConfiguredOrigin(origin, options) {
+	return typeof origin === "string" && (options.allowedOrigins.includes(origin) || origin === options.selfOrigin);
+}
+function normalizeServeError(error) {
+	if (error instanceof ServeHttpError) return {
+		statusCode: error.statusCode,
+		code: error.code,
+		message: error.message
+	};
+	if (isLoopbackViolation(error)) return {
+		statusCode: error.kind === "origin_required" || error.kind === "origin_invalid" || error.kind === "origin_not_allowed" ? 403 : 400,
+		code: error.kind,
+		message: error.message
+	};
+	if (error instanceof ServePairingError) return {
+		statusCode: error.code === "pairing_not_found" ? 404 : error.code === "pairing_token_invalid" || error.code === "pairing_not_approved" ? 401 : 403,
+		code: error.code,
+		message: error.message
+	};
+	if (error instanceof ServeStoreError) return {
+		statusCode: error.code === "not_found" ? 404 : error.code === "io_error" ? 500 : 400,
+		code: error.code,
+		message: error.message
+	};
+	if (error instanceof ServeRunError) return {
+		statusCode: error.code === "run_not_found" ? 404 : 400,
+		code: error.code,
+		message: error.message
+	};
+	if (error instanceof ServeIdentityError) return {
+		statusCode: error.code === "agent_exists" ? 409 : 400,
+		code: error.code,
+		message: error.message
+	};
+	return {
+		statusCode: 500,
+		code: "internal_error",
+		message: "Request failed"
+	};
+}
+//#endregion
+//#region src/cli/serve.ts
+/**
+* `moltnet-agent serve` — per-user loopback supervisor (#2061).
+*
+* Starts nothing on its own: it binds 127.0.0.1 and waits for a paired
+* Console origin to configure agents/providers and start/stop runs.
+*/
+var DEFAULT_PORT = 17374;
+var DEFAULT_ALLOWED_ORIGINS = "https://console.themolt.net";
+var DEFAULT_API_URL = "https://api.themolt.net";
+var SHUTDOWN_TIMEOUT_MS = 15e3;
+async function runServe(argv) {
+	if (isHelpFlag(argv)) {
+		console.log(SERVE_HELP);
+		return 0;
+	}
+	const envConfig = loadServeEnvConfig();
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			port: { type: "string" },
+			"allowed-origins": { type: "string" },
+			root: { type: "string" },
+			"api-url": { type: "string" }
+		}
+	});
+	const port = Number.parseInt(values.port ?? (envConfig.port || `${DEFAULT_PORT}`), 10);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) {
+		console.error(`Invalid --port: ${String(values.port)}`);
+		return 1;
+	}
+	const allowedOrigins = parseAllowedOrigins(values["allowed-origins"] ?? (envConfig.allowedOrigins || DEFAULT_ALLOWED_ORIGINS));
+	const root = values.root ?? resolveServeRoot({
+		root: envConfig.root,
+		xdgConfigHome: envConfig.xdgConfigHome
+	});
+	const defaultApiUrl = values["api-url"] ?? (envConfig.apiUrl || DEFAULT_API_URL);
+	const store = new ServeStore(root).ensure();
+	const { logger, shutdown: shutdownLogger } = createRootLogger({
+		name: "agent-daemon.serve",
+		level: envConfig.logLevel || "info"
+	});
+	try {
+		try {
+			return await withServeLock(root, async () => {
+				const secrets = new FileSecretProvider({
+					root: store.secretsDir,
+					writable: true
+				});
+				const secretProviders = createNodeSecretProviderRegistry().register(secrets);
+				const externalSecretProviders = createNodeSecretProviderRegistry();
+				const pairing = new PairingService();
+				const shutdownController = new AbortController();
+				const runs = new RunManager({
+					store,
+					secretProviders,
+					externalSecretProviders,
+					baseEnv: processEnvSnapshot(),
+					logger
+				});
+				const app = buildServeServer({
+					store,
+					secrets,
+					externalSecretProviders,
+					pairing,
+					runs,
+					allowedOrigins,
+					selfOrigin: `http://127.0.0.1:${port}`,
+					defaultApiUrl,
+					version: "dev",
+					logger,
+					shutdownSignal: shutdownController.signal
+				});
+				try {
+					const address = await app.listen({
+						host: "127.0.0.1",
+						port
+					});
+					console.error(`moltnet-agent serve listening on ${address}`);
+					console.error(`config root: ${root}`);
+					console.error(`allowed origins: ${allowedOrigins.join(", ")}`);
+					console.error("Pair from the Console \"Local runtime\" page; approve the one-click prompt this server opens.");
+					return await waitForServeShutdown(runs, app, shutdownController);
+				} catch (cause) {
+					await app.close().catch(() => void 0);
+					throw cause;
+				}
+			}, { onCompromised: (error) => {
+				console.error(error.message);
+				process.exitCode = 1;
+				process.kill(process.pid, "SIGTERM");
+			} });
+		} catch (cause) {
+			if (cause instanceof ServeLockError) {
+				console.error(cause.message);
+				return 1;
+			}
+			throw cause;
+		}
+	} finally {
+		await shutdownLogger();
+	}
+}
+function waitForServeShutdown(runs, app, shutdownController) {
+	return new Promise((resolvePromise) => {
+		let shuttingDown = false;
+		const shutdown = () => {
+			if (shuttingDown) return;
+			shuttingDown = true;
+			shutdownController.abort();
+			(async () => {
+				app.server.closeAllConnections();
+				const cleanupPromise = Promise.allSettled([runs.stopAll(), app.close()]);
+				let timedOut = false;
+				let deadlineTimer;
+				await Promise.race([cleanupPromise, new Promise((resolveDeadline) => {
+					deadlineTimer = setTimeout(() => {
+						timedOut = true;
+						resolveDeadline();
+					}, SHUTDOWN_TIMEOUT_MS);
+				})]);
+				if (deadlineTimer) clearTimeout(deadlineTimer);
+				let forcedExitTimer;
+				if (timedOut) {
+					console.error("shutdown cleanup exceeded its 15 second deadline; force-stopping runs");
+					runs.forceStopAll();
+					app.server.closeAllConnections();
+					forcedExitTimer = setTimeout(() => process.exit(1), 2e3);
+				}
+				const results = await cleanupPromise;
+				if (forcedExitTimer) clearTimeout(forcedExitTimer);
+				const failures = results.filter((result) => result.status === "rejected");
+				for (const failure of failures) console.error(`shutdown cleanup failed: ${failure.reason.message}`);
+				handlers.dispose();
+				const exitCode = typeof process.exitCode === "number" ? process.exitCode : 0;
+				resolvePromise(failures.length > 0 ? 1 : exitCode);
+			})();
+		};
+		const handlers = installShutdownSignalHandlers({
+			logDrain: () => console.error("shutting down: stopping runs…"),
+			drain: shutdown
+		});
+	});
+}
+//#endregion
 //#region src/lib/runtime-session-sync.ts
 async function syncRuntimeSessions(deps, input) {
 	const result = {
@@ -7037,6 +9284,7 @@ async function runAgentDaemonCli(options) {
 		case "poll": return runPoll(rest, options.runtime);
 		case "once": return runOnce(rest, options.runtime);
 		case "drain": return runDrain(rest, options.runtime);
+		case "serve": return runServe(rest);
 		case "sync-sessions": return runSyncSessions(rest);
 		case "-h":
 		case "--help":