@byok-sdk/client 0.2.0 → 0.3.0

package/dist/bin/byok-agent.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { execFile, spawn, spawnSync } from 'child_process';
-import { randomUUID, createHash, randomBytes, timingSafeEqual, createPrivateKey, generateKeyPairSync, sign, createHmac } from 'crypto';
+import { randomUUID, createHash, randomBytes, timingSafeEqual, createHmac, createPrivateKey, generateKeyPairSync, sign } from 'crypto';
 import { readFileSync, promises, linkSync, fstatSync, lstatSync, unlinkSync, constants, readSync, openSync, writeFileSync, fchmodSync, fsyncSync, closeSync, opendirSync, existsSync, realpathSync, mkdirSync, renameSync, chmodSync, statSync, readdirSync } from 'fs';
-import path20, { join, isAbsolute } from 'path';
+import path20, { isAbsolute, join } from 'path';
 import os from 'os';
-import { TASK_STATES, partitionAgentEvents, TASK_TRANSITIONS, encodeEnvelope, createEnvelope, MAX_MESSAGES_PER_BATCH, RuntimeIdSchema, PROTOCOL_VERSION, decodeEnvelope, MessagesSendResponseSchema, parseMessage, UnknownMessageTypeError } from '@byok-sdk/protocol';
+import { DEVICE_ASSERTION_AUDIENCE_MAX_BYTES, DEVICE_ASSERTION_DEFAULT_TTL_MS, DEVICE_ASSERTION_MAX_TTL_MS, nonceSigningBytes, CapabilityDeclarationSchema, hasCapability, DeviceAssertionClaimsSchema, deviceAssertionSigningInput, DEVICE_ASSERTION_SCHEMA_ID } from '@byok-sdk/core';
+import { TASK_STATES, ToolsetIdSchema, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, partitionAgentEvents, TASK_TRANSITIONS, encodeEnvelope, createEnvelope, byokBlobUrlPath, BYOK_BLOBS_PATH, byokBlobFinalizePath, checkResultDocument, MAX_MESSAGES_PER_BATCH, BYOK_CAPABILITIES_PATH, BYOK_PRESENCE_PATH, RuntimeIdSchema, RESULT_DOCUMENT_MAX_BYTES, PROTOCOL_VERSION, decodeEnvelope, BYOK_MESSAGES_PATH, MessagesSendResponseSchema, BYOK_EVENTS_PATH, parseMessage, UnknownMessageTypeError, BYOK_WS_PATH } from '@byok-sdk/protocol';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import 'readline';
@@ -1118,13 +1119,8 @@ var PiRpcClient = class {
   }
 };
 
-// src/adapters/pi/pi-adapter.ts
-var execFileAsync = promisify(execFile);
-var DETECT_TIMEOUT_MS = 5e3;
-function errorMessage(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-var KNOWN_PROVIDER_ENV_VARS = [
+// src/adapters/provider-credential-environment.ts
+var PROVIDER_CREDENTIAL_ENV_NAMES = [
   "ANTHROPIC_API_KEY",
   "ANTHROPIC_OAUTH_TOKEN",
   "OPENAI_API_KEY",
@@ -1135,24 +1131,66 @@ var KNOWN_PROVIDER_ENV_VARS = [
   "MISTRAL_API_KEY",
   "OPENROUTER_API_KEY",
   "XAI_API_KEY",
-  // Confirmed against the installed pi's own docs/providers.md ("ZAI |
-  // `ZAI_API_KEY` | `zai`") and exercised live against real GLM traffic
-  // during this task's acceptance run — omitting it made `authPresent`
-  // silently false for a perfectly valid, working z.ai/GLM setup.
   "ZAI_API_KEY"
 ];
+var PROVIDER_CREDENTIAL_ENV_DENY_NAMES = [
+  ...PROVIDER_CREDENTIAL_ENV_NAMES,
+  "ANT_LING_API_KEY",
+  "NVIDIA_API_KEY",
+  "CEREBRAS_API_KEY",
+  "CLOUDFLARE_API_KEY",
+  "AI_GATEWAY_API_KEY",
+  "ZAI_CODING_CN_API_KEY",
+  "OPENCODE_API_KEY",
+  "RADIUS_API_KEY",
+  "FIREWORKS_API_KEY",
+  "TOGETHER_API_KEY",
+  "BASETEN_API_KEY",
+  "KIMI_API_KEY",
+  "MINIMAX_API_KEY",
+  "MINIMAX_CN_API_KEY",
+  "QWEN_TOKEN_PLAN_API_KEY",
+  "QWEN_TOKEN_PLAN_CN_API_KEY",
+  "XIAOMI_API_KEY",
+  "XIAOMI_TOKEN_PLAN_CN_API_KEY",
+  "XIAOMI_TOKEN_PLAN_AMS_API_KEY",
+  "XIAOMI_TOKEN_PLAN_SGP_API_KEY",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_SESSION_TOKEN",
+  "GOOGLE_APPLICATION_CREDENTIALS",
+  // Reserved by the keys-owned Pi projection. It must never be inherited
+  // from the daemon; the launcher deletes any ambient copy and injects only
+  // the exact credential it just resolved from OS custody.
+  "PI_PROVIDER_API_KEY"
+];
+function withoutProviderCredentials(env) {
+  const sanitized = { ...env };
+  for (const name of PROVIDER_CREDENTIAL_ENV_DENY_NAMES) {
+    delete sanitized[name];
+  }
+  return sanitized;
+}
+
+// src/adapters/pi/pi-adapter.ts
+var execFileAsync = promisify(execFile);
+var DETECT_TIMEOUT_MS = 5e3;
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 var PiAdapter = class {
   constructor(options = {}) {
     this.options = options;
   }
   options;
   id = "pi";
+  supportsDispatchSelection = true;
   async detect() {
     try {
       const bin = this.resolveBin();
       const { stdout, stderr } = await execFileAsync(bin.command, ["--version"], { timeout: DETECT_TIMEOUT_MS });
       const version = stdout.trim() || stderr.trim();
-      const authPresent = KNOWN_PROVIDER_ENV_VARS.some((name) => process.env[name] !== void 0);
+      const authPresent = PROVIDER_CREDENTIAL_ENV_NAMES.some((name) => process.env[name] !== void 0);
       return { present: true, version, authPresent };
     } catch {
       return { present: false };
@@ -1171,7 +1209,7 @@ var PiAdapter = class {
    * variable beyond the platform baseline (`daemon/environment.ts`).
    */
   environmentRequirements() {
-    return { credentialNames: KNOWN_PROVIDER_ENV_VARS };
+    return { credentialNames: PROVIDER_CREDENTIAL_ENV_NAMES };
   }
   async start(task, ctx) {
     if (typeof task.instruction !== "string") {
@@ -1183,12 +1221,45 @@ var PiAdapter = class {
     }
     const bin = this.resolveBin();
     const resumeSessionId = task.sessionRef;
-    const args = ["--mode", "rpc", ...resumeSessionId ? ["--session", resumeSessionId] : [], ...mapping.args];
+    const piArgs = ["--mode", "rpc", ...resumeSessionId ? ["--session", resumeSessionId] : [], ...mapping.args];
+    const selection = task.dispatchSelection;
+    let command = bin.command;
+    let args = piArgs;
+    if (selection !== void 0) {
+      if (selection.lane !== "byok" || selection.runtimeId !== "pi") {
+        throw new PolicyUnsupportedError(
+          `pi adapter cannot execute ${selection.lane} selection for runtime ${selection.runtimeId}`
+        );
+      }
+      const launcher = this.options.byokLauncher;
+      if (launcher === void 0) {
+        throw new PolicyUnsupportedError(
+          "pi BYOK selection requires a configured credential-custody launcher"
+        );
+      }
+      command = launcher.command;
+      args = [
+        ...launcher.args ?? [],
+        "--pi-bin",
+        bin.command,
+        "--profile-db",
+        launcher.profileDbPath,
+        "--session-dir",
+        launcher.sessionDir,
+        ...launcher.secretServicePrefix ? ["--secret-service-prefix", launcher.secretServicePrefix] : [],
+        "--provider",
+        selection.providerId,
+        "--model",
+        selection.modelId,
+        "--",
+        ...piArgs
+      ];
+    }
     const rpc = new PiRpcClient({
-      command: bin.command,
+      command,
       args,
       cwd: ctx.workspaceDir,
-      env: ctx.env,
+      env: selection === void 0 ? ctx.env : withoutProviderCredentials(ctx.env),
       spawnFn: this.options.spawnFn
     });
     const response = await rpc.send({ type: "prompt", message: task.instruction });
@@ -1207,7 +1278,7 @@ var PiAdapter = class {
         throw err;
       }
     }
-    return new PiSession(sessionRef, rpc);
+    return new PiSession(sessionRef, rpc, selection);
   }
   resolveBin() {
     return (this.options.resolveBin ?? resolvePiBin)();
@@ -1235,12 +1306,14 @@ async function resolveFreshSessionId(rpc) {
   );
 }
 var PiSession = class {
-  constructor(sessionRef, rpc) {
+  constructor(sessionRef, rpc, selection) {
     this.sessionRef = sessionRef;
     this.rpc = rpc;
+    this.selection = selection;
   }
   sessionRef;
   rpc;
+  selection;
   get events() {
     const rpc = this.rpc;
     return {
@@ -1269,6 +1342,12 @@ var PiSession = class {
     if (typeof task.instruction !== "string") {
       throw new PolicyUnsupportedError("pi adapter only supports string instructions in M0 (no blob-ref fetch yet)");
     }
+    const requestedSelection = task.dispatchSelection;
+    if (requestedSelection !== void 0 && (this.selection?.lane !== "byok" || requestedSelection.lane !== "byok" || requestedSelection.runtimeId !== "pi" || requestedSelection.providerId !== this.selection.providerId || requestedSelection.modelId !== this.selection.modelId)) {
+      throw new PolicyUnsupportedError(
+        "pi persistent session cannot change its authoritative BYOK provider/model selection"
+      );
+    }
     await this.rpc.send({ type: "prompt", message: task.instruction, streamingBehavior: "followUp" });
   }
   async interrupt() {
@@ -1693,7 +1772,7 @@ var APPROVAL_TOOL_NAME = "approval_prompt";
 var APPROVAL_MCP_SERVER_NAME = "byokapproval";
 var execFileAsync2 = promisify(execFile);
 var DETECT_TIMEOUT_MS2 = 5e3;
-async function cleanupApprovalMcpConfigDir(dir) {
+async function cleanupMcpConfigDir(dir) {
   if (!dir) return;
   await promises.rm(dir, { recursive: true, force: true }).catch(() => {
   });
@@ -1703,6 +1782,7 @@ var ClaudeAdapter = class {
     this.options = options;
   }
   options;
+  supportsDispatchSelection = true;
   id = "claude";
   async detect() {
     const bin = this.resolveBin();
@@ -1716,7 +1796,13 @@ var ClaudeAdapter = class {
     }
   }
   capabilities() {
-    return { steer: false, resume: true, approvalInteractive: true, permissionModes: ["auto", "readonly", "plan", "confirm"] };
+    return {
+      steer: false,
+      resume: true,
+      approvalInteractive: true,
+      mcpToolsets: true,
+      permissionModes: ["auto", "readonly", "plan", "confirm"]
+    };
   }
   /**
    * M5: deliberate product-boundary decision, not an oversight — byok's
@@ -1742,42 +1828,51 @@ var ClaudeAdapter = class {
     if (!mapping.ok) {
       throw new PolicyUnsupportedError(mapping.reason ?? "policy rejected by claude adapter");
     }
-    let approvalMcpConfigDir;
+    const modelId = subscriptionModel(task, "claude");
+    let mcpConfigDir;
+    const taskMcpServers = ctx.mcpServers ?? {};
+    const needsMcpConfig = mapping.needsApprovalMcp || Object.keys(taskMcpServers).length > 0;
     if (mapping.needsApprovalMcp) {
       if (!ctx.approvalChannel) {
         throw new PolicyUnsupportedError(
           'claude adapter requires policy.mode "confirm" to be started with an approval channel (TaskContext.approvalChannel) \u2014 none was provided'
         );
       }
-      const approvalMcpBin = (this.options.resolveApprovalMcpBin ?? resolveApprovalMcpBin)();
-      approvalMcpConfigDir = await promises.mkdtemp(path20.join(os.tmpdir(), "byok-approval-mcp-"));
-      await promises.chmod(approvalMcpConfigDir, 448).catch(() => {
+      if (Object.prototype.hasOwnProperty.call(taskMcpServers, APPROVAL_MCP_SERVER_NAME)) {
+        throw new PolicyUnsupportedError(
+          `MCP server name "${APPROVAL_MCP_SERVER_NAME}" is reserved by the claude approval channel`
+        );
+      }
+    }
+    if (needsMcpConfig) {
+      mcpConfigDir = await promises.mkdtemp(path20.join(os.tmpdir(), "byok-mcp-"));
+      await promises.chmod(mcpConfigDir, 448).catch(() => {
       });
-      const mcpConfigPath = path20.join(approvalMcpConfigDir, "mcp-config.json");
-      const mcpConfig = {
-        mcpServers: {
-          [APPROVAL_MCP_SERVER_NAME]: {
-            command: approvalMcpBin.command,
-            args: approvalMcpBin.args,
-            env: {
-              BYOK_STORE_DIR: ctx.approvalChannel.storeDir,
-              BYOK_PRODUCT_ID: ctx.approvalChannel.productId,
-              BYOK_TASK_ID: ctx.approvalChannel.taskId,
-              BYOK_APPROVAL_TIMEOUT_MS: String(ctx.approvalChannel.timeoutMs)
-            }
+      const mcpConfigPath = path20.join(mcpConfigDir, "mcp-config.json");
+      const mcpServers = { ...taskMcpServers };
+      if (mapping.needsApprovalMcp) {
+        const approvalChannel = ctx.approvalChannel;
+        if (!approvalChannel) throw new Error("unreachable: approval channel checked above");
+        const approvalMcpBin = (this.options.resolveApprovalMcpBin ?? resolveApprovalMcpBin)();
+        mcpServers[APPROVAL_MCP_SERVER_NAME] = {
+          command: approvalMcpBin.command,
+          args: approvalMcpBin.args,
+          env: {
+            BYOK_STORE_DIR: approvalChannel.storeDir,
+            BYOK_PRODUCT_ID: approvalChannel.productId,
+            BYOK_TASK_ID: approvalChannel.taskId,
+            BYOK_APPROVAL_TIMEOUT_MS: String(approvalChannel.timeoutMs)
           }
-        }
-      };
-      await promises.writeFile(mcpConfigPath, JSON.stringify(mcpConfig), { mode: 384 });
+        };
+      }
+      await promises.writeFile(mcpConfigPath, JSON.stringify({ mcpServers }), { mode: 384 });
       mapping.args = [
         ...mapping.args,
-        "--permission-prompt-tool",
-        `mcp__${APPROVAL_MCP_SERVER_NAME}__${APPROVAL_TOOL_NAME}`,
+        ...mapping.needsApprovalMcp ? ["--permission-prompt-tool", `mcp__${APPROVAL_MCP_SERVER_NAME}__${APPROVAL_TOOL_NAME}`] : [],
         "--mcp-config",
         mcpConfigPath,
-        // Never let this task's confirm-mode run pick up some OTHER MCP
-        // server from ambient project/user config — the approval channel is
-        // the only MCP server this invocation should ever see.
+        // The generated file is the complete task-scoped MCP authority.
+        // Never merge ambient user/project MCP configuration into it.
         "--strict-mcp-config"
       ];
     }
@@ -1794,6 +1889,7 @@ var ClaudeAdapter = class {
       // "Error: When using --print, --output-format=stream-json requires
       // --verbose", before spawning any model call.
       "--verbose",
+      ...modelId ? ["--model", modelId] : [],
       ...resumeSessionId ? ["--resume", resumeSessionId] : [],
       ...mapping.args
     ];
@@ -1801,7 +1897,7 @@ var ClaudeAdapter = class {
       command: bin.command,
       args,
       cwd: ctx.workspaceDir,
-      env: ctx.env,
+      env: withoutProviderCredentials(ctx.env),
       spawnFn: this.options.spawnFn
     });
     client.writeUserMessage(task.instruction);
@@ -1810,17 +1906,24 @@ var ClaudeAdapter = class {
       sessionRef = await client.waitForInit();
     } catch (err) {
       client.kill();
-      await cleanupApprovalMcpConfigDir(approvalMcpConfigDir);
+      await cleanupMcpConfigDir(mcpConfigDir);
       throw err;
     }
     if (resumeSessionId !== void 0 && sessionRef !== resumeSessionId) {
       client.kill();
-      await cleanupApprovalMcpConfigDir(approvalMcpConfigDir);
+      await cleanupMcpConfigDir(mcpConfigDir);
       throw new Error(
         `claude --resume echoed a different session id than requested (requested ${resumeSessionId}, got ${sessionRef}) \u2014 refusing to continue in a possibly-wrong session (fail-closed)`
       );
     }
-    return new ClaudeSession(sessionRef, client, ctx.workspaceDir, ctx.approvalChannel, approvalMcpConfigDir);
+    return new ClaudeSession(
+      sessionRef,
+      client,
+      ctx.workspaceDir,
+      ctx.approvalChannel,
+      mcpConfigDir,
+      modelId
+    );
   }
   /**
    * `claude auth status --json` is claude's OWN non-secret login-state
@@ -1854,19 +1957,31 @@ var ClaudeAdapter = class {
     return (this.options.resolveBin ?? resolveClaudeBin)();
   }
 };
+function subscriptionModel(task, runtimeId) {
+  const selection = task.dispatchSelection;
+  if (selection === void 0) return void 0;
+  if (selection.lane !== "subscription" || selection.runtimeId !== runtimeId) {
+    throw new PolicyUnsupportedError(
+      `claude adapter cannot execute ${selection.lane} selection for runtime ${selection.runtimeId}`
+    );
+  }
+  return selection.modelId;
+}
 var ClaudeSession = class {
-  constructor(sessionRef, client, workspaceDir, approvalChannel, approvalMcpConfigDir) {
+  constructor(sessionRef, client, workspaceDir, approvalChannel, mcpConfigDir, modelId) {
     this.sessionRef = sessionRef;
     this.client = client;
     this.workspaceDir = workspaceDir;
     this.approvalChannel = approvalChannel;
-    this.approvalMcpConfigDir = approvalMcpConfigDir;
+    this.mcpConfigDir = mcpConfigDir;
+    this.modelId = modelId;
   }
   sessionRef;
   client;
   workspaceDir;
   approvalChannel;
-  approvalMcpConfigDir;
+  mcpConfigDir;
+  modelId;
   correlation = createToolUseCorrelation();
   get events() {
     const client = this.client;
@@ -1917,6 +2032,12 @@ var ClaudeSession = class {
     if (typeof task.instruction !== "string") {
       throw new PolicyUnsupportedError("claude adapter only supports string instructions in M2 (no blob-ref fetch yet)");
     }
+    const requestedModel = subscriptionModel(task, "claude");
+    if (requestedModel !== void 0 && requestedModel !== this.modelId) {
+      throw new PolicyUnsupportedError(
+        `claude persistent session cannot change model from ${this.modelId ?? "(legacy default)"} to ${requestedModel}`
+      );
+    }
     this.client.writeUserMessage(task.instruction);
   }
   /**
@@ -1936,7 +2057,7 @@ var ClaudeSession = class {
   }
   async close() {
     this.client.kill();
-    await cleanupApprovalMcpConfigDir(this.approvalMcpConfigDir);
+    await cleanupMcpConfigDir(this.mcpConfigDir);
   }
   /**
    * M4 Phase 3: routes into the out-of-band approval channel `start()`
@@ -2260,6 +2381,7 @@ var CodexAdapter = class {
     this.options = options;
   }
   options;
+  supportsDispatchSelection = true;
   id = "codex";
   async detect() {
     const bin = this.resolveBin();
@@ -2332,17 +2454,20 @@ ${withStreams.stderr ?? ""}`);
     if (!mapping.ok) {
       throw new PolicyUnsupportedError(mapping.reason ?? "policy rejected by codex adapter");
     }
+    const modelId = subscriptionModel2(task);
     const bin = this.resolveBin();
     const queue = new AsyncQueue();
     const recordUnmapped = makeUnmappedFrameRecorder(/* @__PURE__ */ new Map());
     const workspaceDir = await resolveRealWorkspaceDir(ctx.workspaceDir);
+    const runtimeEnv = withoutProviderCredentials(ctx.env);
     const { sessionRef, runner } = await runCodexTurn({
       command: bin.command,
       resumeRef: task.sessionRef,
       instruction: task.instruction,
+      modelId,
       policyArgs: mapping.args,
       cwd: ctx.workspaceDir,
-      env: ctx.env,
+      env: runtimeEnv,
       spawnFn: this.options.spawnFn,
       workspaceDir,
       queue,
@@ -2359,7 +2484,8 @@ ${withStreams.stderr ?? ""}`);
       queue,
       recordUnmapped,
       initialRunner: runner,
-      preparedGit: ctx.gitWorkspace !== void 0
+      preparedGit: ctx.gitWorkspace !== void 0,
+      modelId
     });
   }
   resolveBin() {
@@ -2380,12 +2506,25 @@ function makeUnmappedFrameRecorder(counts) {
     }
   };
 }
-function buildArgv(resumeRef, policyArgs, instruction, preparedGit = false) {
+function buildArgv(resumeRef, policyArgs, instruction, modelId, preparedGit = false) {
   const base = resumeRef !== void 0 ? ["exec", "resume", resumeRef] : ["exec"];
-  return [...base, "--json", ...preparedGit ? [] : ["--skip-git-repo-check"], ...policyArgs, instruction];
+  return [
+    ...base,
+    "--json",
+    ...modelId ? ["--model", modelId] : [],
+    ...preparedGit ? [] : ["--skip-git-repo-check"],
+    ...policyArgs,
+    instruction
+  ];
 }
 async function runCodexTurn(params) {
-  const argv = buildArgv(params.resumeRef, params.policyArgs, params.instruction, params.preparedGit);
+  const argv = buildArgv(
+    params.resumeRef,
+    params.policyArgs,
+    params.instruction,
+    params.modelId,
+    params.preparedGit
+  );
   let firstLineSettled = false;
   let resolveFirstLine;
   let rejectFirstLine;
@@ -2486,6 +2625,7 @@ var CodexSession = class {
   queue;
   recordUnmapped;
   preparedGit;
+  modelId;
   currentRunner;
   closed = false;
   constructor(options) {
@@ -2497,6 +2637,7 @@ var CodexSession = class {
     this.queue = options.queue;
     this.recordUnmapped = options.recordUnmapped;
     this.preparedGit = options.preparedGit;
+    this.modelId = options.modelId;
     this.currentRunner = options.initialRunner;
     void this.forgetRunnerOnceClosed(options.initialRunner);
   }
@@ -2557,6 +2698,13 @@ var CodexSession = class {
     if (!mapping.ok) {
       throw new PolicyUnsupportedError(mapping.reason ?? "policy rejected by codex adapter");
     }
+    const requestedModel = subscriptionModel2(task);
+    if (requestedModel !== void 0 && requestedModel !== this.modelId) {
+      throw new PolicyUnsupportedError(
+        `codex persistent session cannot change model from ${this.modelId ?? "(legacy default)"} to ${requestedModel}`
+      );
+    }
+    const modelId = this.modelId;
     const resumeRef = this.sessionRef;
     let sessionRef;
     let runner;
@@ -2565,9 +2713,10 @@ var CodexSession = class {
         command: this.command,
         resumeRef,
         instruction: task.instruction,
+        modelId,
         policyArgs: mapping.args,
         cwd: this.workspaceDir,
-        env: this.env,
+        env: withoutProviderCredentials(this.env),
         spawnFn: this.spawnFn,
         workspaceDir: this.workspaceDir,
         queue: this.queue,
@@ -2627,6 +2776,16 @@ var CodexSession = class {
     );
   }
 };
+function subscriptionModel2(task) {
+  const selection = task.dispatchSelection;
+  if (selection === void 0) return void 0;
+  if (selection.lane !== "subscription" || selection.runtimeId !== "codex") {
+    throw new PolicyUnsupportedError(
+      `codex adapter cannot execute ${selection.lane} selection for runtime ${selection.runtimeId}`
+    );
+  }
+  return selection.modelId;
+}
 
 // src/daemon/approvals.ts
 var ApprovalNotFoundError = class extends Error {
@@ -2851,13 +3010,10 @@ function exportPrivateKeyPem(privateKey) {
 function importPrivateKeyPem(pem) {
   return createPrivateKey(pem);
 }
-var NONCE_SIGNING_DOMAIN = "byok-nonce-v1\n";
 function signNonce(privateKey, nonce) {
-  const signature = sign(null, Buffer.from(NONCE_SIGNING_DOMAIN + nonce, "utf8"), privateKey);
+  const signature = sign(null, nonceSigningBytes(nonce), privateKey);
   return signature.toString("base64url");
 }
-
-// src/daemon/url.ts
 function toHttpBase(serverUrl) {
   const url = new URL(serverUrl);
   if (url.protocol === "ws:") url.protocol = "http:";
@@ -2867,7 +3023,7 @@ function toHttpBase(serverUrl) {
   return url.toString();
 }
 function toWsUrl(serverUrl) {
-  const url = new URL("/byok/ws", toHttpBase(serverUrl));
+  const url = new URL(BYOK_WS_PATH, toHttpBase(serverUrl));
   url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
   return url.toString();
 }
@@ -2955,7 +3111,7 @@ var AuthManager = class {
       return await this.runCredentialMutation(async () => {
         const existing = this.record ?? await this.opts.store.load();
         const keyPair = existing ? { privateKey: importPrivateKeyPem(existing.devicePrivateKeyPem), publicKeyBase64Url: existing.devicePublicKey } : generateDeviceKeyPair();
-        const url = new URL("/byok/pair", toHttpBase(this.opts.serverUrl));
+        const url = new URL(BYOK_PAIR_PATH, toHttpBase(this.opts.serverUrl));
         const res = await fetch(url, {
           method: "POST",
           headers: { "content-type": "application/json" },
@@ -2989,6 +3145,7 @@ var AuthManager = class {
   async getValidAccessToken() {
     if (!this.record) throw new Error("device is not paired yet; call pair(pairingCode) first");
     if (this.revoked) throw new DeviceRevokedError();
+    if (this.renewing) return this.renewing;
     if (msUntilExpiry(this.record.expiresAt) > RENEW_MARGIN_MS) return this.record.accessToken;
     return this.renew();
   }
@@ -3017,7 +3174,7 @@ var AuthManager = class {
     const record = this.record;
     const base = toHttpBase(this.opts.serverUrl);
     const privateKey = importPrivateKeyPem(record.devicePrivateKeyPem);
-    const challengeRes = await fetch(new URL("/byok/challenge", base), {
+    const challengeRes = await fetch(new URL(BYOK_CHALLENGE_PATH, base), {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ deviceId: record.deviceId })
@@ -3030,7 +3187,7 @@ var AuthManager = class {
     }
     const { nonce } = await challengeRes.json();
     const signature = signNonce(privateKey, nonce);
-    const tokenRes = await fetch(new URL("/byok/token", base), {
+    const tokenRes = await fetch(new URL(BYOK_TOKEN_PATH, base), {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ deviceId: record.deviceId, nonce, signature })
@@ -3128,7 +3285,7 @@ var BlobClient = class {
   async resolveInstruction(blobRef) {
     const base = toHttpBase(this.serverUrl);
     const urlRes = await authedFetch(
-      new URL(`/byok/blobs/${encodeURIComponent(blobRef.blobId)}/url`, base),
+      new URL(byokBlobUrlPath(blobRef.blobId), base),
       { method: "GET" },
       this.auth
     );
@@ -3156,7 +3313,7 @@ var BlobClient = class {
     const base = toHttpBase(this.serverUrl);
     const reservationId = `blob_${randomUUID()}`;
     const createRes = await authedFetch(
-      new URL("/byok/blobs", base),
+      new URL(BYOK_BLOBS_PATH, base),
       {
         method: "POST",
         headers: {
@@ -3188,7 +3345,7 @@ var BlobClient = class {
       let response;
       try {
         response = await authedFetch(
-          new URL(`/byok/blobs/${encodeURIComponent(blobId)}/finalize`, base),
+          new URL(byokBlobFinalizePath(blobId), base),
           {
             method: "POST",
             headers: { "idempotency-key": reservationId }
@@ -3211,16 +3368,177 @@ var BlobClient = class {
     throw lastFailure;
   }
 };
+var PRESENCE_HINTS_CAPABILITY = "presence.hints";
+var CapabilityDiscoveryError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CapabilityDiscoveryError";
+  }
+};
+async function fetchCapabilityDeclaration(serverUrl, options = {}) {
+  const url = new URL(BYOK_CAPABILITIES_PATH, toHttpBase(serverUrl));
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "GET",
+      ...options.signal === void 0 ? {} : { signal: options.signal }
+    });
+  } catch (err) {
+    throw new CapabilityDiscoveryError(
+      `failed to read the capability declaration from ${url.toString()}: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
+    );
+  }
+  if (!response.ok) {
+    throw new CapabilityDiscoveryError(
+      `failed to read the capability declaration from ${url.toString()}: HTTP ${response.status}`
+    );
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new CapabilityDiscoveryError(
+      `the capability declaration at ${url.toString()} is not JSON: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
+    );
+  }
+  const parsed = CapabilityDeclarationSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new CapabilityDiscoveryError(
+      `the capability declaration at ${url.toString()} is not a valid ADR-010 declaration: ${parsed.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ")}`,
+      { cause: parsed.error }
+    );
+  }
+  return parsed.data;
+}
+function declares(declaration, capability) {
+  return hasCapability(declaration, capability);
+}
+var DEFAULT_PRESENCE_HEARTBEAT_INTERVAL_MS = 3e4;
+var DEFAULT_PRESENCE_TTL_MS = 9e4;
+var DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS = 5e3;
+function assertPresenceHeartbeatCadence(cadence) {
+  const { intervalMs, ttlMs, minimumIntervalMs } = cadence;
+  if (!(minimumIntervalMs < intervalMs && intervalMs < ttlMs)) {
+    throw new Error(
+      `presence heartbeat interval must satisfy minimumIntervalMs < intervalMs < ttlMs \u2014 got ${minimumIntervalMs} < ${intervalMs} < ${ttlMs}`
+    );
+  }
+}
+var PresencePublisher = class {
+  constructor(opts) {
+    this.opts = opts;
+    const intervalMs = opts.intervalMs ?? DEFAULT_PRESENCE_HEARTBEAT_INTERVAL_MS;
+    const ttlMs = opts.ttlMs ?? DEFAULT_PRESENCE_TTL_MS;
+    const minimumIntervalMs = opts.minimumIntervalMs ?? DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS;
+    assertPresenceHeartbeatCadence({ intervalMs, ttlMs, minimumIntervalMs });
+    this.intervalMs = intervalMs;
+    this.url = new URL(BYOK_PRESENCE_PATH, toHttpBase(opts.serverUrl));
+  }
+  opts;
+  url;
+  intervalMs;
+  timer;
+  running = false;
+  /** Set once a revoked device is observed. Terminal: `start()` will not restart this instance. */
+  stoppedPermanently = false;
+  /** Publishes immediately, then every `intervalMs`. Idempotent; a no-op after a permanent stop. */
+  start() {
+    if (this.running || this.stoppedPermanently) return;
+    this.running = true;
+    void this.beat();
+  }
+  /** Stops the cadence. Idempotent, and the only "offline" signal this producer emits — the hint's TTL does the rest. */
+  stop() {
+    this.running = false;
+    if (this.timer !== void 0) {
+      clearTimeout(this.timer);
+      this.timer = void 0;
+    }
+  }
+  schedule() {
+    if (!this.running) return;
+    this.timer = setTimeout(() => {
+      this.timer = void 0;
+      void this.beat();
+    }, this.intervalMs);
+    this.timer.unref?.();
+  }
+  async beat() {
+    if (!this.running) return;
+    try {
+      const response = await authedFetch(
+        this.url,
+        {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ level: "online" })
+        },
+        this.opts.auth
+      );
+      if (!response.ok) {
+        if (response.status === 401) {
+          this.stopPermanently(`presence heartbeat unauthorized after token renewal (HTTP 401)`);
+          return;
+        }
+        this.opts.onDegraded?.(`presence heartbeat failed: HTTP ${response.status}`);
+      }
+    } catch (err) {
+      if (err instanceof DeviceRevokedError) {
+        this.stopPermanently("presence heartbeat stopped: device has been revoked; re-pair required");
+        return;
+      }
+      this.opts.onDegraded?.(`presence heartbeat failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    this.schedule();
+  }
+  stopPermanently(reason) {
+    this.stoppedPermanently = true;
+    this.stop();
+    this.opts.onDegraded?.(reason);
+  }
+};
+function freshJti() {
+  return randomBytes(16).toString("base64url");
+}
+function mintDeviceAssertion(input) {
+  const issuedAtMs = input.now.getTime();
+  const expiresAt = new Date(issuedAtMs + input.ttlMs).toISOString();
+  const claims = DeviceAssertionClaimsSchema.parse({
+    version: 1,
+    issuer: input.issuer,
+    productId: input.productId,
+    deviceId: input.record.deviceId,
+    audience: input.audience,
+    jti: freshJti(),
+    issuedAt: new Date(issuedAtMs).toISOString(),
+    expiresAt
+  });
+  const privateKey = importPrivateKeyPem(input.record.devicePrivateKeyPem);
+  const signature = sign(null, deviceAssertionSigningInput(claims), privateKey).toString("base64url");
+  return {
+    envelope: {
+      schema: DEVICE_ASSERTION_SCHEMA_ID,
+      algorithm: "ed25519",
+      protected: claims,
+      signature
+    },
+    claims,
+    expiresAt
+  };
+}
 var CONTROL_PROTOCOL_VERSION = 1;
 var HANDSHAKE_TIMEOUT_MS = 3e3;
 var UNIX_SOCKET_PATH_SOFT_LIMIT = 100;
+var CONTROL_SOCKET_FALLBACK_ROOT = "/tmp";
 function shortHash(input) {
   return createHash("sha256").update(input, "utf8").digest("hex").slice(0, 16);
 }
 function controlSocketPath(storeDir) {
   const candidate = path20.join(storeDir, "control.sock");
   if (Buffer.byteLength(candidate, "utf8") <= UNIX_SOCKET_PATH_SOFT_LIMIT) return candidate;
-  return path20.join(os.tmpdir(), `byok-${shortHash(storeDir)}`, "sock");
+  return path20.join(CONTROL_SOCKET_FALLBACK_ROOT, `byok-${shortHash(storeDir)}`, "sock");
 }
 function controlPipeName(productId, storeDir) {
   const id = shortHash(`${productId}|${path20.resolve(storeDir)}`);
@@ -3326,6 +3644,16 @@ function parseApprovalsRequestParams(value) {
   if (typeof value.summary !== "string") return void 0;
   return { taskId: value.taskId, summary: value.summary };
 }
+var ASSERTION_AUDIENCE_MAX_BYTES = 256;
+function parseAssertionIssueParams(value) {
+  if (!isRecord2(value)) return void 0;
+  const keys = Object.keys(value);
+  if (keys.length !== 1 || keys[0] !== "audience") return void 0;
+  const { audience } = value;
+  if (typeof audience !== "string" || audience.length === 0) return void 0;
+  if (Buffer.byteLength(audience, "utf8") > ASSERTION_AUDIENCE_MAX_BYTES) return void 0;
+  return { audience };
+}
 function parseShutdownParams(value) {
   if (!isRecord2(value)) return {};
   return value.reason === "unpair" || value.reason === "operator" ? { reason: value.reason } : {};
@@ -3658,7 +3986,7 @@ var LongPollClient = class {
     try {
       const base = toHttpBase(this.opts.serverUrl);
       const res = await authedFetch(
-        new URL("/byok/messages", base),
+        new URL(BYOK_MESSAGES_PATH, base),
         {
           method: "POST",
           headers: { "content-type": "application/json" },
@@ -3682,7 +4010,7 @@ var LongPollClient = class {
     while (this.running) {
       try {
         const base = toHttpBase(this.opts.serverUrl);
-        const url = new URL("/byok/events", base);
+        const url = new URL(BYOK_EVENTS_PATH, base);
         const cursor = this.opts.getCursor();
         if (cursor !== void 0) url.searchParams.set("cursor", String(cursor));
         const res = await authedFetch(url, { method: "GET" }, this.opts.auth);
@@ -4945,19 +5273,19 @@ var RECLAIM_FILENAME = `${DAEMON_OWNER_FILENAME}.reclaim`;
 var MAX_OWNER_BYTES = 4096;
 var RECLAIM_MALFORMED_GRACE_MS = 3e4;
 var SELF_PROCESS_STARTED_AT = new Date(Date.now() - process.uptime() * 1e3).toISOString();
-var STORE_MUTEX_PORT_BASE = 1e4;
-var STORE_MUTEX_PORT_COUNT = 2e4;
-var STORE_MUTEX_PORT_CANDIDATES = 32;
 var STORE_MUTEX_ID_PREFIX = "byok-store-mutex-v1:";
 var STORE_MUTEX_PROBE_TIMEOUT_MS = 1e3;
+var STORE_MUTEX_SOCKET_FILENAME = "mutex.sock";
+var UNIX_SOCKET_PATH_SOFT_LIMIT2 = 100;
+var STORE_MUTEX_FALLBACK_ROOT = "/tmp";
 function storeMutexIdentity(canonicalStoreDir) {
   return createHash("sha256").update(canonicalStoreDir).digest("hex");
 }
-function storeMutexPort(identity, attempt) {
-  const digest = Buffer.from(identity, "hex");
-  const start = digest.readUInt32BE(0) % STORE_MUTEX_PORT_COUNT;
-  const step = 1 + digest.readUInt32BE(4) % (STORE_MUTEX_PORT_COUNT - 1);
-  return STORE_MUTEX_PORT_BASE + (start + attempt * step) % STORE_MUTEX_PORT_COUNT;
+function storeMutexEndpoint(canonicalStoreDir, identity, platform = process.platform) {
+  if (platform === "win32") return `\\\\.\\pipe\\byok-store-mutex-${identity.slice(0, 16)}`;
+  const candidate = path20.join(canonicalStoreDir, STORE_MUTEX_SOCKET_FILENAME);
+  if (Buffer.byteLength(candidate, "utf8") <= UNIX_SOCKET_PATH_SOFT_LIMIT2) return candidate;
+  return path20.join(STORE_MUTEX_FALLBACK_ROOT, `byok-store-mutex-${identity.slice(0, 16)}`, "sock");
 }
 var DaemonOwnerActiveError = class extends Error {
   constructor(role) {
@@ -5078,70 +5406,90 @@ async function createLivenessListener() {
     })
   };
 }
-async function probeStoreMutex(port) {
+async function probeStoreMutex(endpoint, identity) {
   return new Promise((resolve) => {
-    const socket = createConnection({ host: "127.0.0.1", port });
+    const socket = createConnection(endpoint);
     let settled = false;
     let raw = "";
     const finish = (result) => {
       if (settled) return;
       settled = true;
+      clearTimeout(timer);
+      socket.removeAllListeners();
       socket.destroy();
       resolve(result);
     };
+    const timer = setTimeout(() => finish({ kind: "occupied" }), STORE_MUTEX_PROBE_TIMEOUT_MS);
     socket.setEncoding("utf8");
-    socket.setTimeout(STORE_MUTEX_PROBE_TIMEOUT_MS, () => finish({ kind: "uncertain" }));
     socket.on("data", (chunk) => {
       raw += chunk;
-      if (raw.length > STORE_MUTEX_ID_PREFIX.length + 64 + 1) finish({ kind: "foreign-or-gone" });
+      if (raw.length > STORE_MUTEX_ID_PREFIX.length + 64 + 1) finish({ kind: "occupied" });
     });
-    socket.once("end", () => {
-      const line = raw.trimEnd();
-      const identity = line.startsWith(STORE_MUTEX_ID_PREFIX) ? line.slice(STORE_MUTEX_ID_PREFIX.length) : void 0;
-      finish(
-        identity && /^[a-f0-9]{64}$/.test(identity) ? { kind: "identity", identity } : { kind: "foreign-or-gone" }
-      );
-    });
-    socket.once("error", () => finish({ kind: "foreign-or-gone" }));
+    socket.once("end", () => finish(raw.trimEnd() === `${STORE_MUTEX_ID_PREFIX}${identity}` ? { kind: "holder" } : { kind: "occupied" }));
+    socket.once(
+      "error",
+      (err) => finish(err.code === "ECONNREFUSED" || err.code === "ENOENT" ? { kind: "unbound" } : { kind: "occupied" })
+    );
   });
 }
+async function clearStaleStoreMutexSocket(endpoint, identity) {
+  let stat;
+  try {
+    stat = await promises.lstat(endpoint);
+  } catch (err) {
+    if (err.code === "ENOENT") return;
+    throw err;
+  }
+  if (!stat.isSocket()) throw new Error("store mutation lock path exists but is not a socket");
+  if ((await probeStoreMutex(endpoint, identity)).kind !== "unbound") throw new DaemonOwnerActiveError("unknown");
+  await promises.rm(endpoint, { force: true });
+}
+async function assertOwnedPrivateDir2(dir) {
+  const uid = process.getuid?.();
+  if (uid === void 0) return;
+  const stat = await promises.lstat(dir);
+  if (stat.isSymbolicLink() || stat.uid !== uid) {
+    throw new Error(`refusing to bind the store mutation lock under "${dir}": not a real directory owned by this process's own uid`);
+  }
+}
 async function acquireStoreMutex(canonicalStoreDir) {
   const identity = storeMutexIdentity(canonicalStoreDir);
-  for (let attempt = 0; attempt < STORE_MUTEX_PORT_CANDIDATES; attempt += 1) {
-    const server = createServer((socket) => socket.end(`${STORE_MUTEX_ID_PREFIX}${identity}
+  const endpoint = storeMutexEndpoint(canonicalStoreDir, identity);
+  const isPipe = process.platform === "win32";
+  if (!isPipe) {
+    const endpointDir = path20.dirname(endpoint);
+    if (endpointDir !== canonicalStoreDir) {
+      await ensureSecureDir(endpointDir);
+      await assertOwnedPrivateDir2(endpointDir);
+    }
+    await clearStaleStoreMutexSocket(endpoint, identity);
+  }
+  const server = createServer((socket) => socket.end(`${STORE_MUTEX_ID_PREFIX}${identity}
 `));
-    const port = storeMutexPort(identity, attempt);
-    try {
-      await new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen({ host: "127.0.0.1", port, exclusive: true }, () => {
-          server.removeListener("error", reject);
-          resolve();
-        });
+  try {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(endpoint, () => {
+        server.removeListener("error", reject);
+        resolve();
       });
-    } catch (err) {
-      if (err.code !== "EADDRINUSE") throw err;
-      const probe = await probeStoreMutex(port);
-      if (probe.kind === "uncertain" || probe.kind === "identity" && probe.identity === identity) {
-        throw new DaemonOwnerActiveError("unknown");
-      }
-      continue;
-    }
-    server.unref();
-    let closed = false;
-    return {
-      port,
-      close: () => new Promise((resolve, reject) => {
-        if (closed) {
-          resolve();
-          return;
-        }
-        closed = true;
-        server.close((err) => err ? reject(err) : resolve());
-      })
-    };
+    });
+  } catch (err) {
+    if (err.code === "EADDRINUSE") throw new DaemonOwnerActiveError("unknown");
+    throw err;
   }
-  throw new DaemonOwnerActiveError("unknown");
+  if (!isPipe) await promises.chmod(endpoint, 384).catch(() => void 0);
+  server.unref();
+  let closed = false;
+  return {
+    endpoint,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      await new Promise((resolve, reject) => server.close((err) => err ? reject(err) : resolve()));
+      if (!isPipe) await promises.rm(endpoint, { force: true }).catch(() => void 0);
+    }
+  };
 }
 async function reclaimExistsAndIsActive(reclaimPath) {
   let stat;
@@ -5257,6 +5605,7 @@ function toRuntimeInfoCapabilities(caps) {
     steer: caps.steer,
     resume: caps.resume,
     approvalInteractive: caps.approvalInteractive,
+    ...caps.mcpToolsets === void 0 ? {} : { mcpToolsets: caps.mcpToolsets },
     permissionModes: caps.permissionModes
   };
 }
@@ -5330,7 +5679,7 @@ var DaemonObserver = class {
   }
   /**
    * Feed a raw INBOUND (server -> daemon) envelope. Deliberately narrow: only
-   * `task.offer` produces a local event here — every other inbound type
+   * either offer variant produces a local event here — every other inbound type
    * (`task.cancel`/`task.steer`/`task.approve`/`task.reject`) is a
    * best-effort notification whose OWN observable effect already surfaces
    * through the daemon's outbound envelopes (`task.cancelled`, `task.progress`
@@ -5338,7 +5687,7 @@ var DaemonObserver = class {
    * where those are actually reported from.
    */
   handleInboundEnvelope(envelope) {
-    if (envelope.type !== "task.offer") return;
+    if (envelope.type !== "task.offer" && envelope.type !== "task.offer_with_toolsets") return;
     const taskId = envelope.task_id;
     if (this.taskInfo.has(taskId)) return;
     this.upsertTask(taskId, { state: "Offered", runtime: envelope.payload.runtime });
@@ -5459,6 +5808,37 @@ var DaemonObserver = class {
   noteShutdownComplete(reason, undeliveredOutboxCount) {
     this.emit({ kind: "shutdown-complete", ts: nowIso(), reason, undeliveredOutboxCount });
   }
+  /**
+   * Plan `device-assertion-broker`: see the `device-assertion` `DaemonEvent`
+   * variant's own doc comment. The parameter type is what keeps the signature
+   * out — there is no field to pass one through.
+   *
+   * codex round-2 F4: the DENIED caller can pass its raw `audience` here, but
+   * it is converted to a byte SIZE the instant the event is constructed and the
+   * raw string is dropped — it is never placed on the emitted `DaemonEvent`, so
+   * it cannot reach a subscriber, `format.ts`, stdout, or the audit file. The
+   * ISSUED `audience` came from the allowlist and is kept verbatim.
+   */
+  noteDeviceAssertion(event) {
+    if (event.result === "issued") {
+      this.emit({
+        kind: "device-assertion",
+        ts: nowIso(),
+        result: "issued",
+        audience: event.audience,
+        jti: event.jti,
+        expiresAt: event.expiresAt
+      });
+      return;
+    }
+    this.emit({
+      kind: "device-assertion",
+      ts: nowIso(),
+      result: "denied",
+      reason: event.reason,
+      audienceSize: event.audience === void 0 ? void 0 : Buffer.byteLength(event.audience, "utf8")
+    });
+  }
   /** M4 Phase 3 hardening: see the `stale-approval-decision` `DaemonEvent` variant's own doc comment. */
   noteStaleApprovalDecision(taskId, decision, reason) {
     this.emit({ kind: "stale-approval-decision", ts: nowIso(), taskId, decision, reason });
@@ -7097,6 +7477,21 @@ var MAX_INLINE_ARTIFACT_BYTES = 64 * 1024;
 var MAX_TRACKED_TASK_IDS = 2e3;
 var MAX_DURATION_EXCEEDED_REASON_PREFIX = "resource limit exceeded: maxDurationMs";
 var MAX_OUTPUT_BYTES_EXCEEDED_REASON_PREFIX = "resource limit exceeded: maxTaskOutputBytes";
+var RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX = "result document undeliverable";
+function resultDocumentRejectionDetail(check) {
+  switch (check.reason) {
+    case "over-cap":
+      return `${check.bytes} bytes as canonical JSON, over the ${RESULT_DOCUMENT_MAX_BYTES}-byte limit (it is never truncated \u2014 a truncated JSON document is not valid JSON; use artifactRefs for a result this size)`;
+    case "not-serializable":
+      return "not JSON-serializable (JSON.stringify threw, or produced no output at all)";
+    case "not-plain-json":
+      return "not plain JSON data: it does not equal its own JSON round trip, so serializing it would silently change it (an undefined-valued key, NaN, a function or symbol value, a Date, a toJSON that rewrites the value, or a getter that answers differently on a second read)";
+    default: {
+      const exhaustive = check;
+      throw new Error(`unhandled result document rejection: ${JSON.stringify(exhaustive)}`);
+    }
+  }
+}
 var DEFAULT_MAX_TASK_OUTPUT_BYTES = 64 * 1024 * 1024;
 function isKnownRuntimeId(id) {
   return RuntimeIdSchema.safeParse(id).success;
@@ -7109,6 +7504,14 @@ function orderByPreference(candidates, preference) {
 function adapterSupportsMode(adapter, mode) {
   return adapter.capabilities().permissionModes.includes(mode);
 }
+function adapterSupportsMcpToolsets(adapter) {
+  return adapter.capabilities().mcpToolsets === true;
+}
+function withoutRequiredToolsets(payload) {
+  if (!("requiredToolsets" in payload)) return payload;
+  const { requiredToolsets, ...offer } = payload;
+  return offer;
+}
 function errorMessage3(err) {
   return err instanceof Error ? err.message : String(err);
 }
@@ -7464,6 +7867,9 @@ var TaskRunner = class {
       case "task.offer":
         await this.handleOffer(envelope.task_id, envelope.payload);
         return;
+      case "task.offer_with_toolsets":
+        await this.handleOffer(envelope.task_id, envelope.payload);
+        return;
       case "task.cancel":
         await this.handleCancel(envelope.task_id, envelope.payload.reason);
         return;
@@ -7517,7 +7923,22 @@ var TaskRunner = class {
         );
         return;
       }
-      const pick = await this.pickAdapter(payload.runtime, payload.policy.mode);
+      if (payload.dispatchSelection !== void 0 && payload.runtime !== void 0 && payload.runtime !== payload.dispatchSelection.runtimeId) {
+        this.decline(
+          taskId,
+          `offer runtime ${payload.runtime} does not match dispatchSelection.runtimeId ${payload.dispatchSelection.runtimeId}`,
+          false
+        );
+        return;
+      }
+      const requiredToolsets = "requiredToolsets" in payload ? payload.requiredToolsets : void 0;
+      const resolvedMcp = requiredToolsets ? this.resolveMcpServers(requiredToolsets) : void 0;
+      if (resolvedMcp && !resolvedMcp.ok) {
+        this.decline(taskId, resolvedMcp.reason, true);
+        return;
+      }
+      const requestedRuntime = payload.dispatchSelection?.runtimeId ?? payload.runtime;
+      const pick = await this.pickAdapter(requestedRuntime, payload.policy.mode, requiredToolsets !== void 0);
       if (!pick.ok) {
         this.decline(taskId, pick.reason, pick.retryable);
         return;
@@ -7680,6 +8101,7 @@ var TaskRunner = class {
       const ctx = {
         workspaceDir,
         policy: decision.policy,
+        ...resolvedMcp?.ok ? { mcpServers: resolvedMcp.servers } : {},
         ...gitWorkspaceId ? { gitWorkspace: { workspaceId: gitWorkspaceId, baseline: gitBaseline } } : {},
         // M5: no longer `process.env` verbatim (see `environment.ts`'s own
         // module doc comment for the credential-leak gap that closed) —
@@ -7716,7 +8138,7 @@ var TaskRunner = class {
         }
       };
       const effectiveOffer = {
-        ...payload,
+        ...withoutRequiredToolsets(payload),
         instruction: gitWorkspaceId ? prependGitWorkspaceGuidance(resolvedInstruction) : resolvedInstruction,
         // Never forward a sessionRef this device has no recorded workspace
         // for (stale, from another device, or simply made up) — an adapter
@@ -7794,6 +8216,36 @@ var TaskRunner = class {
     if (typeof instruction === "string") return instruction;
     return this.deps.blobClient.resolveInstruction(instruction.blobRef);
   }
+  /** Resolve every requested logical id locally and reject missing/colliding server authority before claim. */
+  resolveMcpServers(requiredToolsets) {
+    const registry = this.deps.mcpToolsets;
+    if (!registry) {
+      return { ok: false, reason: "offer requires MCP toolsets, but this device has no local mcpToolsets registry" };
+    }
+    const servers = /* @__PURE__ */ Object.create(null);
+    for (const toolsetId of requiredToolsets) {
+      const toolset = registry.get(toolsetId);
+      if (!toolset) {
+        return { ok: false, reason: `required MCP toolset "${toolsetId}" is not configured on this device` };
+      }
+      for (const [serverName, server] of Object.entries(toolset.mcpServers)) {
+        if (Object.prototype.hasOwnProperty.call(servers, serverName)) {
+          return {
+            ok: false,
+            reason: `required MCP toolsets collide on server name "${serverName}"; refusing ambiguous projection`
+          };
+        }
+        servers[serverName] = Object.freeze({
+          command: server.command,
+          ...server.args ? { args: Object.freeze([...server.args]) } : {}
+        });
+      }
+    }
+    if (Object.keys(servers).length === 0) {
+      return { ok: false, reason: "required MCP toolsets resolved to no servers; refusing to run without tools" };
+    }
+    return { ok: true, servers: Object.freeze(servers) };
+  }
   async pump(active) {
     try {
       for await (const event of active.session.events) {
@@ -7827,11 +8279,38 @@ var TaskRunner = class {
         if (event.type === "turn_end") {
           active.batcher.push(event);
           active.batcher.flush();
+          const finalOutput = active.summaryParts.join("");
+          const outcome = await this.resolveResultDocument(active, finalOutput);
+          if (!outcome.deliver) return;
           await this.observeGit(active, "completed");
+          if (outcome.document !== void 0 && !this.hasResultDocumentCapability()) {
+            await this.fail(
+              active.taskId,
+              `${RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX}: the connected server stopped advertising the result-document capability before this completion could be sent (a reconnect to an older server), so it would silently discard this document`,
+              false
+            );
+            return;
+          }
           this.deps.send(
             createEnvelope(
               "task.complete",
-              { summary: active.summaryParts.join(""), sessionRef: active.session.sessionRef },
+              {
+                summary: finalOutput,
+                sessionRef: active.session.sessionRef,
+                // Spread rather than `document: outcome.document`, so a
+                // completion with no document is the exact same payload it
+                // was before this field existed — not one carrying an
+                // explicit `document: undefined` key.
+                //
+                // `outcome.document` is the protocol's CANONICAL SNAPSHOT
+                // (`checkResultDocument`), never the object the extractor
+                // returned: pure data serializes identically at the root
+                // (where it was measured) and nested inside this payload
+                // (where the codec actually serializes it), so a contextual
+                // `toJSON(key)` or an unstable getter cannot make the wire
+                // bytes differ from what the cap gate approved.
+                ...outcome.document !== void 0 ? { document: outcome.document } : {}
+              },
               { taskId: active.taskId, sessionRef: active.session.sessionRef }
             )
           );
@@ -8369,6 +8848,102 @@ var TaskRunner = class {
     this.deps.send(createEnvelope("task.fail", { reason, retryable }, { taskId }));
     await this.finish(taskId);
   }
+  /**
+   * additive-minor (`task.complete.document`): the whole daemon-side gate
+   * between a configured {@link ResultDocumentExtractor} and the wire —
+   * called once, from the `turn_end` completion path, immediately before
+   * `task.complete` is built.
+   *
+   * `{deliver: true}` means "go on and send `task.complete`", carrying the
+   * document when there is one. `{deliver: false}` means this method has
+   * ALREADY reported `task.fail` and finished the task; the caller must
+   * return without sending anything further.
+   *
+   * Four fail-closed branches, all `retryable: false` (see
+   * {@link RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX} for why none of them
+   * can succeed on a retry):
+   *
+   *   1. The extractor threw — its error is surfaced, never swallowed.
+   *   2. The extractor returned a thenable, violating the synchronous
+   *      contract in the one way that would otherwise ship a wrong answer.
+   *   3. The document is over the cap, not JSON-serializable, or not plain
+   *      JSON data, per `checkResultDocument` — the protocol's OWN check,
+   *      imported rather than reimplemented, so this gate and the server's
+   *      schema validation can never disagree about what is legal.
+   *   4. The connected server never advertised `result-document`. Its
+   *      tolerant `z.object()` would silently strip the field on arrival
+   *      (`version.ts`'s own flag doc comment), so "send anyway" is not a
+   *      degraded-but-working path — it is the task's primary structured
+   *      result being deleted in transit with nothing reported anywhere.
+   *
+   * The capability is checked LAST, deliberately: a document that is itself
+   * invalid is the host's own bug and is worth reporting as such even when
+   * the connected server could not have accepted any document at all. It is
+   * then re-checked once more by the caller after its own last await, since
+   * a reconnect can invalidate this answer in between (F3).
+   *
+   * **Residual window (bounded, deliberately not hacked around).** Even the
+   * caller's re-check happens before `ConnectionManager.send` hands the
+   * envelope to a transport, and a queued envelope can outlive the
+   * connection it was queued for: a reconnect between `send()` and the
+   * outbox actually draining could still deliver this `task.complete` to a
+   * rolled-back N-1 server that strips the document. Closing that would
+   * mean teaching the transport outbox to inspect payload semantics and
+   * mint a substitute `task.fail` for a task this runner already finished —
+   * a second authority over terminal outcomes living in the queue, which is
+   * worse than the window it closes. Documented instead, here and in
+   * docs/protocol.md §7.2.
+   */
+  async resolveResultDocument(active, finalOutput) {
+    const extract = this.deps.resultDocument?.extract;
+    if (!extract) return { deliver: true };
+    let document;
+    try {
+      document = extract(finalOutput, { taskId: active.taskId, sessionRef: active.session.sessionRef });
+    } catch (err) {
+      await this.fail(
+        active.taskId,
+        `${RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX}: the configured resultDocument.extract threw: ${errorMessage3(err)}`,
+        false
+      );
+      return { deliver: false };
+    }
+    if (typeof document?.then === "function") {
+      await this.fail(
+        active.taskId,
+        `${RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX}: the configured resultDocument.extract returned a promise; the contract is synchronous (an awaited value is never read, and a promise encodes to an empty document)`,
+        false
+      );
+      return { deliver: false };
+    }
+    if (document === void 0) return { deliver: true };
+    const check = checkResultDocument(document);
+    if (!check.ok) {
+      const detail = resultDocumentRejectionDetail(check);
+      await this.fail(active.taskId, `${RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX}: ${detail}`, false);
+      return { deliver: false };
+    }
+    if (!this.hasResultDocumentCapability()) {
+      await this.fail(
+        active.taskId,
+        `${RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX}: the connected server did not advertise the result-document capability, so it would silently discard this ${check.bytes}-byte document`,
+        false
+      );
+      return { deliver: false };
+    }
+    return { deliver: true, document: check.canonical };
+  }
+  /**
+   * Whether the CURRENTLY connected server advertised `result-document` —
+   * read fresh on every call, never captured, because the answer changes
+   * across a reconnect (`ConnectionManager.getServerCapabilities` returns
+   * `[]` from the moment an acked connection closes until a fresh
+   * `conn.ack` repopulates it). An absent `getServerCapabilities` seam is
+   * "no capabilities", the fail-closed reading.
+   */
+  hasResultDocumentCapability() {
+    return (this.deps.getServerCapabilities?.() ?? []).includes("result-document");
+  }
   async observeGit(active, phase) {
     if (!active.gitWorkspaceId || !this.deps.gitWorkspaceManager || !this.deps.gitWorkspaceStore) return;
     try {
@@ -8471,7 +9046,7 @@ var TaskRunner = class {
    * is device-specific (which runtimes happen to be installed here), so a
    * different device's installed runtime set might satisfy it.
    */
-  async pickAdapter(requestedRuntime, policyMode) {
+  async pickAdapter(requestedRuntime, policyMode, requiresMcpToolsets) {
     const allowlist = this.deps.runtimeAllowlist;
     if (requestedRuntime) {
       if (allowlist && !allowlist.includes(requestedRuntime)) {
@@ -8492,6 +9067,13 @@ var TaskRunner = class {
           retryable: false
         };
       }
+      if (requiresMcpToolsets && !adapterSupportsMcpToolsets(adapter)) {
+        return {
+          ok: false,
+          reason: `runtime "${requestedRuntime}" cannot project required MCP toolsets`,
+          retryable: false
+        };
+      }
       const detected = await adapter.detect();
       if (!detected.present) {
         return {
@@ -8506,12 +9088,13 @@ var TaskRunner = class {
     const candidates = orderByPreference(eligible, this.deps.runtimePreference ?? DEFAULT_RUNTIME_PREFERENCE);
     for (const adapter of candidates) {
       if (!adapterSupportsMode(adapter, policyMode)) continue;
+      if (requiresMcpToolsets && !adapterSupportsMcpToolsets(adapter)) continue;
       const detected = await adapter.detect();
       if (detected.present) return { ok: true, adapter };
     }
     return {
       ok: false,
-      reason: `no available runtime on this device can express permission mode "${policyMode}"`,
+      reason: requiresMcpToolsets ? `no available runtime on this device can express permission mode "${policyMode}" with required MCP toolsets` : `no available runtime on this device can express permission mode "${policyMode}"`,
       retryable: true
     };
   }
@@ -8542,7 +9125,7 @@ function toJournalEnvelopeRecord(envelope, identity) {
     bytes,
     bytesHash: journalHash(bytes),
     receivedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    opensTask: envelope.type === "task.offer"
+    opensTask: envelope.type === "task.offer" || envelope.type === "task.offer_with_toolsets"
   };
 }
 function isRuntimeId(id) {
@@ -8566,53 +9149,240 @@ function computeCapabilities(adapters) {
   if (adapters.some((adapter) => adapter.capabilities().steer)) flags.push("steer");
   flags.push("blob-upload");
   flags.push("approval-targeting");
+  const selectionAdapters = adapters.filter(
+    (adapter) => ALL_RUNTIME_IDS.includes(adapter.id)
+  );
+  if (selectionAdapters.length > 0 && selectionAdapters.every((adapter) => adapter.supportsDispatchSelection === true)) {
+    flags.push("dispatch-selection");
+  }
+  if (adapters.some((adapter) => adapter.capabilities().mcpToolsets === true)) {
+    flags.push("toolset-selection");
+  }
   return flags;
 }
 var ALL_RUNTIME_IDS = ["pi", "claude", "codex"];
-function buildAdapter(id) {
+function buildAdapter(id, config) {
   switch (id) {
     case "pi":
-      return new PiAdapter();
+      return new PiAdapter({ byokLauncher: config.piByokLauncher });
     case "claude":
       return new ClaudeAdapter();
     case "codex":
       return new CodexAdapter();
   }
 }
-function buildDefaultAdapters(runtimeAllowlist) {
-  const ids = runtimeAllowlist ? ALL_RUNTIME_IDS.filter((id) => runtimeAllowlist.includes(id)) : ALL_RUNTIME_IDS;
-  return ids.map(buildAdapter);
+function buildDefaultAdapters(config) {
+  const ids = config.runtimeAllowlist ? ALL_RUNTIME_IDS.filter((id) => config.runtimeAllowlist?.includes(id)) : ALL_RUNTIME_IDS;
+  return ids.map((id) => buildAdapter(id, config));
 }
-function createDaemonWithAdapters(config, adapters, overrides = {}) {
-  if (config.maxTaskOutputBytes !== void 0 && !(config.maxTaskOutputBytes > 0)) {
+function validatePiByokLauncherConfig(launcher) {
+  for (const [field, value] of [
+    ["command", launcher.command],
+    ["profileDbPath", launcher.profileDbPath],
+    ["sessionDir", launcher.sessionDir]
+  ]) {
+    if (value.trim().length === 0 || /[\u0000\r\n]/u.test(value)) {
+      throw new Error(`DaemonConfig.piByokLauncher.${field} must be a non-empty single-line string`);
+    }
+  }
+  if (!isAbsolute(launcher.profileDbPath) || !isAbsolute(launcher.sessionDir)) {
     throw new Error(
-      `DaemonConfig.maxTaskOutputBytes must be a positive number (or omitted to use the ${DEFAULT_MAX_TASK_OUTPUT_BYTES}-byte default) \u2014 got ${config.maxTaskOutputBytes}. Pass Number.POSITIVE_INFINITY to explicitly disable the cap; 0 or a negative number is rejected rather than silently treated as "disabled".`
+      "DaemonConfig.piByokLauncher profileDbPath and sessionDir must be absolute paths"
     );
   }
-  const storeDir = DeviceStore.resolveDir(config.productId, config.storeDir);
-  const store = new DeviceStore(storeDir);
-  const operationalHealth = new OperationalHealthTracker(storeDir);
-  let fleetJitter;
-  let maintenanceSequence = 0;
-  const cursorStore = new CursorStore(storeDir);
-  const sessionWorkspaces = new SessionWorkspaceStore(storeDir);
-  const gitWorkspaceManager = config.gitWorkspace ? overrides.gitWorkspace?.manager ?? new GitWorkspaceManager(config.workspaceRoot, { ownerId: stableGitWorkspaceOwnerId(storeDir, config.productId) }) : void 0;
-  const gitWorkspaceStore = config.gitWorkspace ? overrides.gitWorkspace?.store ?? new GitWorkspaceStore(storeDir) : void 0;
-  let resolvedStoragePolicy;
-  if (config.hostedJournal) {
-    if (config.hostedJournal.mode !== "sqlite") {
-      throw new Error(`DaemonConfig.hostedJournal.mode must be "sqlite" \u2014 got ${JSON.stringify(config.hostedJournal.mode)}`);
-    }
-    if (typeof config.hostedJournal.tenantId !== "string" || config.hostedJournal.tenantId.trim() === "") {
-      throw new Error(
-        "DaemonConfig.hostedJournal.tenantId must be a non-empty tenant id \u2014 a hosted journal row with no tenant is durable evidence nobody can act on"
-      );
-    }
-    if (config.hostedJournal.storagePolicy) {
-      resolvedStoragePolicy = resolveLocalStoragePolicy(config.hostedJournal.storagePolicy);
-    }
+  if (launcher.secretServicePrefix !== void 0 && (launcher.secretServicePrefix.trim().length === 0 || /[\u0000\r\n]/u.test(launcher.secretServicePrefix))) {
+    throw new Error(
+      "DaemonConfig.piByokLauncher.secretServicePrefix must be a non-empty single-line string"
+    );
   }
-  if (config.hostedJournal && overrides.hostedJournal?.journal === void 0 && !isSqliteAvailable()) {
+  const reserved = /* @__PURE__ */ new Set([
+    "--",
+    "--pi-bin",
+    "--profile-db",
+    "--session-dir",
+    "--secret-service-prefix",
+    "--provider",
+    "--model"
+  ]);
+  const conflicting = launcher.args?.find((arg) => reserved.has(arg));
+  if (conflicting !== void 0) {
+    throw new Error(
+      `DaemonConfig.piByokLauncher.args must not override reserved launcher argument ${conflicting}`
+    );
+  }
+  const invalidArg = launcher.args?.find((arg) => arg.length === 0 || /[\u0000\r\n]/u.test(arg));
+  if (invalidArg !== void 0) {
+    throw new Error("DaemonConfig.piByokLauncher.args must contain only non-empty single-line strings");
+  }
+}
+var MAX_LOCAL_MCP_TOOLSETS = 64;
+var MAX_LOCAL_MCP_SERVERS_PER_TOOLSET = 16;
+var MAX_LOCAL_MCP_ARGS = 64;
+var MAX_LOCAL_MCP_TOKEN_CHARS = 4096;
+function isNonEmptySingleLine(value) {
+  return typeof value === "string" && value.trim().length > 0 && value.length <= MAX_LOCAL_MCP_TOKEN_CHARS && !/[\u0000\r\n]/u.test(value);
+}
+function resolveMcpToolsets(configured) {
+  if (configured === void 0) return void 0;
+  if (configured === null || typeof configured !== "object" || Array.isArray(configured)) {
+    throw new Error("DaemonConfig.mcpToolsets must be an object keyed by logical toolset id");
+  }
+  const toolsetEntries = Object.entries(configured);
+  if (toolsetEntries.length > MAX_LOCAL_MCP_TOOLSETS) {
+    throw new Error(`DaemonConfig.mcpToolsets may contain at most ${MAX_LOCAL_MCP_TOOLSETS} toolsets`);
+  }
+  const resolved = /* @__PURE__ */ new Map();
+  for (const [toolsetId, rawToolset] of toolsetEntries) {
+    const parsedId = ToolsetIdSchema.safeParse(toolsetId);
+    if (!parsedId.success) {
+      throw new Error(`DaemonConfig.mcpToolsets contains invalid toolset id ${JSON.stringify(toolsetId)}`);
+    }
+    if (rawToolset === null || typeof rawToolset !== "object" || Array.isArray(rawToolset)) {
+      throw new Error(`DaemonConfig.mcpToolsets.${toolsetId} must be an object`);
+    }
+    const toolsetKeys = Object.keys(rawToolset);
+    if (toolsetKeys.some((key) => key !== "mcpServers")) {
+      throw new Error(`DaemonConfig.mcpToolsets.${toolsetId} accepts only the mcpServers field`);
+    }
+    const rawServers = rawToolset.mcpServers;
+    if (rawServers === null || typeof rawServers !== "object" || Array.isArray(rawServers)) {
+      throw new Error(`DaemonConfig.mcpToolsets.${toolsetId}.mcpServers must be an object`);
+    }
+    const serverEntries = Object.entries(rawServers);
+    if (serverEntries.length === 0 || serverEntries.length > MAX_LOCAL_MCP_SERVERS_PER_TOOLSET) {
+      throw new Error(
+        `DaemonConfig.mcpToolsets.${toolsetId}.mcpServers must contain 1-${MAX_LOCAL_MCP_SERVERS_PER_TOOLSET} servers`
+      );
+    }
+    const servers = {};
+    for (const [serverName, rawServer] of serverEntries) {
+      if (!ToolsetIdSchema.safeParse(serverName).success) {
+        throw new Error(
+          `DaemonConfig.mcpToolsets.${toolsetId}.mcpServers contains invalid server name ${JSON.stringify(serverName)}`
+        );
+      }
+      if (serverName === APPROVAL_MCP_SERVER_NAME) {
+        throw new Error(
+          `DaemonConfig.mcpToolsets.${toolsetId}.mcpServers.${serverName} uses a server name reserved by the daemon`
+        );
+      }
+      if (rawServer === null || typeof rawServer !== "object" || Array.isArray(rawServer)) {
+        throw new Error(`DaemonConfig.mcpToolsets.${toolsetId}.mcpServers.${serverName} must be an object`);
+      }
+      const serverKeys = Object.keys(rawServer);
+      if (serverKeys.some((key) => key !== "command" && key !== "args")) {
+        throw new Error(
+          `DaemonConfig.mcpToolsets.${toolsetId}.mcpServers.${serverName} accepts only command and args; env, headers, and remote task data are not supported`
+        );
+      }
+      const server = rawServer;
+      if (!isNonEmptySingleLine(server.command)) {
+        throw new Error(
+          `DaemonConfig.mcpToolsets.${toolsetId}.mcpServers.${serverName}.command must be a non-empty single-line string no longer than ${MAX_LOCAL_MCP_TOKEN_CHARS} characters`
+        );
+      }
+      if (server.args !== void 0 && !Array.isArray(server.args)) {
+        throw new Error(`DaemonConfig.mcpToolsets.${toolsetId}.mcpServers.${serverName}.args must be an array`);
+      }
+      const args = server.args ?? [];
+      if (args.length > MAX_LOCAL_MCP_ARGS || args.some((arg) => !isNonEmptySingleLine(arg))) {
+        throw new Error(
+          `DaemonConfig.mcpToolsets.${toolsetId}.mcpServers.${serverName}.args must contain at most ${MAX_LOCAL_MCP_ARGS} non-empty single-line strings`
+        );
+      }
+      servers[serverName] = Object.freeze({
+        command: server.command,
+        ...args.length > 0 ? { args: Object.freeze([...args]) } : {}
+      });
+    }
+    resolved.set(toolsetId, Object.freeze({ mcpServers: Object.freeze(servers) }));
+  }
+  return resolved;
+}
+function resolveDeviceAssertionAudiences(config) {
+  if (config === void 0) return void 0;
+  if (!Array.isArray(config.audiences)) {
+    throw new Error(
+      `DaemonConfig.deviceAssertion.audiences must be an array of exact audience strings \u2014 got ${JSON.stringify(config.audiences)}. Omit the deviceAssertion section (or pass an empty array) to leave the assertion broker disabled.`
+    );
+  }
+  if (config.audiences.length === 0) return void 0;
+  const audiences = /* @__PURE__ */ new Set();
+  for (const audience of config.audiences) {
+    if (typeof audience !== "string" || audience.length === 0) {
+      throw new Error(
+        `DaemonConfig.deviceAssertion.audiences entries must be non-empty strings \u2014 got ${JSON.stringify(audience)}`
+      );
+    }
+    if (Buffer.byteLength(audience, "utf8") > DEVICE_ASSERTION_AUDIENCE_MAX_BYTES) {
+      throw new Error(
+        `DaemonConfig.deviceAssertion.audiences entry ${JSON.stringify(audience)} exceeds ${DEVICE_ASSERTION_AUDIENCE_MAX_BYTES} UTF-8 bytes`
+      );
+    }
+    if (audiences.has(audience)) {
+      throw new Error(
+        `DaemonConfig.deviceAssertion.audiences contains ${JSON.stringify(audience)} twice \u2014 rejected rather than de-duplicated, because a duplicate is usually a copy-paste that hid a typo in the entry that was meant to be different`
+      );
+    }
+    audiences.add(audience);
+  }
+  return audiences;
+}
+function resolveDeviceAssertionTtlMs(config) {
+  const ttlMs = config?.ttlMs ?? DEVICE_ASSERTION_DEFAULT_TTL_MS;
+  if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0 || ttlMs > DEVICE_ASSERTION_MAX_TTL_MS) {
+    throw new Error(
+      `DaemonConfig.deviceAssertion.ttlMs must be a positive integer no greater than ${DEVICE_ASSERTION_MAX_TTL_MS} ms \u2014 got ${JSON.stringify(config?.ttlMs)}`
+    );
+  }
+  return ttlMs;
+}
+function createDaemonWithAdapters(config, adapters, overrides = {}) {
+  return buildDaemonWithAdapters(config, adapters, overrides);
+}
+function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProbe) {
+  const mcpToolsets = resolveMcpToolsets(config.mcpToolsets);
+  if (config.piByokLauncher !== void 0) {
+    validatePiByokLauncherConfig(config.piByokLauncher);
+  }
+  if (config.maxTaskOutputBytes !== void 0 && !(config.maxTaskOutputBytes > 0)) {
+    throw new Error(
+      `DaemonConfig.maxTaskOutputBytes must be a positive number (or omitted to use the ${DEFAULT_MAX_TASK_OUTPUT_BYTES}-byte default) \u2014 got ${config.maxTaskOutputBytes}. Pass Number.POSITIVE_INFINITY to explicitly disable the cap; 0 or a negative number is rejected rather than silently treated as "disabled".`
+    );
+  }
+  const presenceCadence = {
+    intervalMs: config.presence?.intervalMs ?? DEFAULT_PRESENCE_HEARTBEAT_INTERVAL_MS,
+    ttlMs: config.presence?.ttlMs ?? DEFAULT_PRESENCE_TTL_MS,
+    minimumIntervalMs: config.presence?.minimumIntervalMs ?? DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS
+  };
+  assertPresenceHeartbeatCadence(presenceCadence);
+  const deviceAssertionAudiences = resolveDeviceAssertionAudiences(config.deviceAssertion);
+  const deviceAssertionTtlMs = resolveDeviceAssertionTtlMs(config.deviceAssertion);
+  let shuttingDown = false;
+  const storeDir = DeviceStore.resolveDir(config.productId, config.storeDir);
+  const store = new DeviceStore(storeDir);
+  const operationalHealth = new OperationalHealthTracker(storeDir);
+  let fleetJitter;
+  let maintenanceSequence = 0;
+  const cursorStore = new CursorStore(storeDir);
+  const sessionWorkspaces = new SessionWorkspaceStore(storeDir);
+  const gitWorkspaceManager = config.gitWorkspace ? overrides.gitWorkspace?.manager ?? new GitWorkspaceManager(config.workspaceRoot, { ownerId: stableGitWorkspaceOwnerId(storeDir, config.productId) }) : void 0;
+  const gitWorkspaceStore = config.gitWorkspace ? overrides.gitWorkspace?.store ?? new GitWorkspaceStore(storeDir) : void 0;
+  let resolvedStoragePolicy;
+  if (config.hostedJournal) {
+    if (config.hostedJournal.mode !== "sqlite") {
+      throw new Error(`DaemonConfig.hostedJournal.mode must be "sqlite" \u2014 got ${JSON.stringify(config.hostedJournal.mode)}`);
+    }
+    if (typeof config.hostedJournal.tenantId !== "string" || config.hostedJournal.tenantId.trim() === "") {
+      throw new Error(
+        "DaemonConfig.hostedJournal.tenantId must be a non-empty tenant id \u2014 a hosted journal row with no tenant is durable evidence nobody can act on"
+      );
+    }
+    if (config.hostedJournal.storagePolicy) {
+      resolvedStoragePolicy = resolveLocalStoragePolicy(config.hostedJournal.storagePolicy);
+    }
+  }
+  if (config.hostedJournal && overrides.hostedJournal?.journal === void 0 && !isSqliteAvailable()) {
     throw new JournalUnavailableError(`node:sqlite could not be loaded on Node ${process.versions.node}`);
   }
   let ownedJournal;
@@ -8679,6 +9449,9 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
   let runner;
   let controlServerHandle;
   let daemonOwnerLease;
+  let presencePublisher;
+  let presenceDiscovery;
+  let presenceDiscoveryInFlight = false;
   let shutdownPromise;
   const pendingLateMutationBarriers = /* @__PURE__ */ new Set();
   let startedAt;
@@ -8851,6 +9624,7 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
         deviceId: record.deviceId,
         // M5: see `DaemonConfig.runtimeEnvironment`'s own doc comment above.
         runtimeEnvironment: config.runtimeEnvironment,
+        ...mcpToolsets ? { mcpToolsets } : {},
         // M3-2a: `send` is already this file's OWN closure (not something
         // `TaskRunner` builds) — every `task.claim`/`task.started`/
         // `task.progress`/`task.artifact`/`task.await_approval`/
@@ -8890,6 +9664,11 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
         shutdownInterruptTimeoutMs: overrides.shutdown?.taskInterruptTimeoutMs,
         // M5 batch-3 (workstream 2): see DaemonConfig.maxTaskOutputBytes's own doc comment — already validated above.
         maxTaskOutputBytes: config.maxTaskOutputBytes,
+        // additive-minor (`task.complete.document`): passed through verbatim,
+        // absent when unconfigured — see `DaemonConfig.resultDocument`'s own
+        // doc comment. Spread rather than assigned so an unconfigured daemon
+        // builds the exact `deps` object it did before this seam existed.
+        ...config.resultDocument ? { resultDocument: config.resultDocument } : {},
         // M4 Phase 3 hardening: bridges TaskRunner's stale-approval-race
         // finding out to the SAME local observability seam every other
         // daemon-local event already uses (see observer.ts's own module doc
@@ -8965,8 +9744,10 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
           return runner?.handleEnvelope(envelope) ?? Promise.resolve();
         },
         onStateChange: (state) => {
+          const wasSettled = connectionState === "open" || connectionState === "degraded";
           connectionState = state;
           observer.noteConnectionState(state);
+          if (!wasSettled && (state === "open" || state === "degraded")) runPresenceDiscovery();
         },
         backoff: overrides.backoff,
         liveness: overrides.liveness,
@@ -8984,6 +9765,7 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
       });
       await connection.start();
       await connection.waitForAck();
+      startPresenceProducer();
     } catch (err) {
       try {
         await runShutdownSequence("startup failed", { drainTimeoutMs: 0 });
@@ -8993,7 +9775,41 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
       throw err;
     }
   }
+  function startPresenceProducer() {
+    presenceDiscovery = new AbortController();
+    runPresenceDiscovery();
+  }
+  function runPresenceDiscovery() {
+    const discovery = presenceDiscovery;
+    if (!discovery || presenceDiscoveryInFlight) return;
+    presenceDiscoveryInFlight = true;
+    void (async () => {
+      try {
+        const declaration = await fetchCapabilityDeclaration(config.serverUrl, { signal: discovery.signal });
+        if (discovery.signal.aborted) return;
+        if (declares(declaration, PRESENCE_HINTS_CAPABILITY)) {
+          presencePublisher ??= new PresencePublisher({
+            serverUrl: config.serverUrl,
+            auth,
+            ...presenceCadence,
+            onDegraded: (reason) => console.warn(`[byok/client] ${reason}`)
+          });
+          presencePublisher.start();
+        } else {
+          presencePublisher?.stop();
+        }
+      } catch (err) {
+        if (discovery.signal.aborted) return;
+        console.warn(
+          `[byok/client] capability discovery failed; presence publishing stays off until the next reconnect: ${err instanceof Error ? err.message : String(err)}`
+        );
+      } finally {
+        presenceDiscoveryInFlight = false;
+      }
+    })();
+  }
   async function runShutdownSequence(reason, opts = {}) {
+    shuttingDown = true;
     const errors = [];
     let mutationBarrierComplete = hostedStorageInitializationBarrierComplete;
     if (!hostedStorageInitializationBarrierComplete) {
@@ -9022,6 +9838,11 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
         errors.push(new Error("a prior active task teardown remains unsettled; ownership lease retained"));
       }
     }
+    presenceDiscovery?.abort();
+    presenceDiscovery = void 0;
+    presenceDiscoveryInFlight = false;
+    presencePublisher?.stop();
+    presencePublisher = void 0;
     const stoppingOwnedPressureEngine = ownedPressureEngine;
     const stoppingOwnedJournal = ownedJournal;
     const maintenanceStopped = stoppingOwnedPressureEngine?.stop() ?? Promise.resolve();
@@ -9082,6 +9903,7 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
     }
   }
   async function stop(opts = {}) {
+    shuttingDown = true;
     await requestShutdown(opts.reason ?? "operator", { drainTimeoutMs: opts.drainTimeoutMs });
   }
   function requestShutdown(reason, opts = {}) {
@@ -9094,6 +9916,7 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
     return current;
   }
   async function unpair() {
+    shuttingDown = true;
     await runLifecycleMutation(unpairUnderLease);
   }
   async function unpairUnderLease() {
@@ -9172,6 +9995,7 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
   }
   async function performControlShutdown(reason) {
     const effectiveReason = reason ?? "operator";
+    shuttingDown = true;
     observer.noteShutdownRequested(effectiveReason);
     try {
       await requestShutdown(`control socket shutdown (${effectiveReason})`);
@@ -9209,7 +10033,107 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
         if (!runner) throw new ControlError("not_found", "daemon is not started");
         return runner.requestApproval(parsed.taskId, parsed.summary);
       },
+      /**
+       * Plan `device-assertion-broker`: mint one short-lived, audience-scoped
+       * device assertion for a sibling local process.
+       *
+       * SIX fail-closed gates, in this exact order, none of which signs
+       * anything on the way out. The order is part of the contract, not an
+       * implementation detail:
+       *
+       * 1. `assertion_disabled` — before anything else, because a daemon that
+       *    was never configured for this must not reveal, by answering
+       *    differently for different inputs, that it even validates params.
+       * 2. `bad_request` — shape/length, checked before the allowlist so a
+       *    malformed request cannot be used to probe membership.
+       * 3. `audience_denied` — EXACT `Set.has`, never a prefix/suffix rule
+       *    (`salesko-api.evil.com` and `salesko-ap` both fail against an entry
+       *    of `salesko-api`). The message deliberately does not echo the
+       *    allowlist: a refusal must not be an enumeration oracle.
+       * 4. `shutting_down` — see `performControlShutdown`'s own comment for
+       *    the minting window this closes.
+       * 5. `revoked` — the server-side revocation this daemon already knows
+       *    about.
+       * 6. `not_paired` — the on-disk record, re-read on EVERY call (never
+       *    cached), so clearing `device.json` removes local signing authority
+       *    immediately.
+       *
+       * Only after all six does the private key get imported, used once, and
+       * dropped (`device-assertion-signer.ts`).
+       *
+       * Honest limit, and it must stay in the docs as well as here: gates 4-6
+       * are only HALF of revocation. They make this daemon stop minting
+       * promptly, but an assertion already in a caller's hands is not recalled
+       * by any of them. The other half is the host's own recheck at exchange
+       * time, which is why core's `verifyDeviceAssertion` makes the device
+       * row's `revoked` state a REQUIRED parameter. Nothing here entitles
+       * anyone to claim this daemon delivers synchronous invalidation on its
+       * own.
+       */
+      "assertion.issue": async (params) => {
+        if (deviceAssertionAudiences === void 0) {
+          observer.noteDeviceAssertion({ result: "denied", reason: "assertion_disabled" });
+          throw new ControlError(
+            "assertion_disabled",
+            "this daemon is not configured to issue device assertions (DaemonConfig.deviceAssertion.audiences is absent or empty)"
+          );
+        }
+        const parsed = parseAssertionIssueParams(params);
+        if (!parsed) {
+          const rawAudience = typeof params === "object" && params !== null && typeof params.audience === "string" ? params.audience : void 0;
+          observer.noteDeviceAssertion({ result: "denied", reason: "bad_request", audience: rawAudience });
+          throw new ControlError(
+            "bad_request",
+            `assertion.issue requires exactly {audience} where audience is a non-empty string of at most ${DEVICE_ASSERTION_AUDIENCE_MAX_BYTES} UTF-8 bytes`
+          );
+        }
+        if (!deviceAssertionAudiences.has(parsed.audience)) {
+          observer.noteDeviceAssertion({ result: "denied", reason: "audience_denied", audience: parsed.audience });
+          throw new ControlError("audience_denied", "the requested audience is not allowed by this daemon");
+        }
+        if (shuttingDown) {
+          observer.noteDeviceAssertion({ result: "denied", reason: "shutting_down", audience: parsed.audience });
+          throw new ControlError("shutting_down", "this daemon is shutting down and will not issue new assertions");
+        }
+        if (auth.isRevoked()) {
+          observer.noteDeviceAssertion({ result: "denied", reason: "revoked", audience: parsed.audience });
+          throw new ControlError("revoked", "this device has been revoked by the server; re-pair required");
+        }
+        const record = await store.load();
+        if (record === void 0) {
+          observer.noteDeviceAssertion({ result: "denied", reason: "not_paired", audience: parsed.audience });
+          throw new ControlError("not_paired", "this device is not paired; nothing can be asserted about it");
+        }
+        if (shuttingDown) {
+          observer.noteDeviceAssertion({ result: "denied", reason: "shutting_down", audience: parsed.audience });
+          throw new ControlError("shutting_down", "this daemon is shutting down and will not issue new assertions");
+        }
+        if (auth.isRevoked()) {
+          observer.noteDeviceAssertion({ result: "denied", reason: "revoked", audience: parsed.audience });
+          throw new ControlError("revoked", "this device has been revoked by the server; re-pair required");
+        }
+        const minted = mintDeviceAssertion({
+          record,
+          // `toHttpBase` is the one place a configured serverUrl is normalized
+          // (ws:->http:, wss:->https:, path stripped), so an operator who
+          // configured the websocket spelling and one who configured the HTTP
+          // spelling of the same deployment produce the same issuer.
+          issuer: new URL(toHttpBase(config.serverUrl)).origin,
+          productId: config.productId,
+          audience: parsed.audience,
+          ttlMs: deviceAssertionTtlMs,
+          now: /* @__PURE__ */ new Date()
+        });
+        observer.noteDeviceAssertion({
+          result: "issued",
+          audience: minted.claims.audience,
+          jti: minted.claims.jti,
+          expiresAt: minted.expiresAt
+        });
+        return { assertion: minted.envelope, expiresAt: minted.expiresAt };
+      },
       shutdown: (params) => {
+        shuttingDown = true;
         const { reason } = parseShutdownParams(params);
         setImmediate(() => {
           void performControlShutdown(reason).catch((err) => {
@@ -9254,299 +10178,350 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
   return { pair, start, stop, status, subscribe, tasks, unpair, approve, reject };
 }
 function createDaemon(config) {
-  return createDaemonWithAdapters(config, buildDefaultAdapters(config.runtimeAllowlist));
-}
-
-// src/lifecycle/service-types.ts
-function nodeAgentProgram(opts) {
-  const program = {
-    command: opts.nodeBin ?? process.execPath,
-    args: [opts.agentBin, "start", "--config", opts.configPath]
-  };
-  if (opts.cwd !== void 0) program.cwd = opts.cwd;
-  return program;
-}
-function sanitizeServiceName(name) {
-  const cleaned = name.trim().replace(/[^A-Za-z0-9._-]+/g, "-");
-  const safe = cleaned.replace(/^-+/, "");
-  if (!safe) {
-    throw new Error(`service name "${name}" has no valid characters left after sanitizing (allowed: letters, digits, ".", "-", "_"; cannot consist only of leading "-")`);
-  }
-  return safe;
-}
-
-// src/lifecycle/launchd.ts
-var LAUNCHD_CONNECTIVITY_OR_PERMISSION_FAILURE = [
-  /operation not permitted/i,
-  /could not find domain/i,
-  /permission denied/i,
-  /access denied/i
-];
-var LAUNCHD_NOT_LOADED = {
-  patterns: [/no such process/i, /could not find (specified )?service/i, /not loaded/i],
-  neverAbsence: LAUNCHD_CONNECTIVITY_OR_PERMISSION_FAILURE
-};
-function escapeXml(value) {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+  return createDaemonWithAdapters(config, buildDefaultAdapters(config));
 }
-function plistString(value) {
-  return `<string>${escapeXml(value)}</string>`;
+var MAX_CONTROL_TOKEN_BYTES = 256;
+function errorMessage4(err) {
+  return err instanceof Error ? err.message : String(err);
 }
-function generateLaunchdPlist(def) {
-  const { label, program, logDir } = def;
-  const args = [program.command, ...program.args];
-  const cwd = program.cwd ?? os.homedir();
-  const outLog = path20.join(logDir, `${label}.out.log`);
-  const errLog = path20.join(logDir, `${label}.err.log`);
-  return `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key>
-  ${plistString(label)}
-  <key>ProgramArguments</key>
-  <array>
-${args.map((a) => `    ${plistString(a)}`).join("\n")}
-  </array>
-  <key>WorkingDirectory</key>
-  ${plistString(cwd)}
-  <key>RunAtLoad</key>
-  <true/>
-  <key>KeepAlive</key>
-  <dict>
-    <key>SuccessfulExit</key>
-    <false/>
-  </dict>
-  <key>ThrottleInterval</key>
-  <integer>10</integer>
-  <key>StandardOutPath</key>
-  ${plistString(outLog)}
-  <key>StandardErrorPath</key>
-  ${plistString(errLog)}
-</dict>
-</plist>
-`;
+function sameFileState3(left, right) {
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
 }
-function createLaunchdLifecycle(def, deps = {}) {
-  const run = deps.run ?? defaultRunner;
-  const fs19 = deps.fs ?? promises;
-  const homedir = deps.homedir ?? (() => os.homedir());
-  const getuid = deps.getuid ?? (() => {
-    if (typeof process.getuid !== "function") {
-      throw new Error("launchd lifecycle requires a POSIX uid (process.getuid unavailable) \u2014 this module only runs on macOS");
-    }
-    return process.getuid();
-  });
-  const label = sanitizeServiceName(def.name);
-  const plistPath = () => path20.join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
-  const domainTarget = () => `gui/${getuid()}`;
-  const serviceTarget = () => `${domainTarget()}/${label}`;
-  async function fileExists(p) {
-    try {
-      await fs19.stat(p);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  async function writePlist(program) {
-    const xml = generateLaunchdPlist({ label, program, logDir: def.logDir });
-    await fs19.mkdir(path20.dirname(plistPath()), { recursive: true });
-    await fs19.mkdir(def.logDir, { recursive: true });
-    await fs19.writeFile(plistPath(), xml, "utf8");
-  }
-  async function install(opts = {}) {
-    await writePlist(opts.program ?? def.program);
-    await run("launchctl", ["bootout", serviceTarget()]);
-    await runOrThrow(run, "launchctl", ["bootstrap", domainTarget(), plistPath()], "launchctl bootstrap");
-    await runOrThrow(run, "launchctl", ["enable", serviceTarget()], "launchctl enable");
-    await run("launchctl", ["kickstart", "-k", serviceTarget()]);
+async function readControlToken(tokenPath) {
+  let namedBefore;
+  try {
+    namedBefore = await promises.lstat(tokenPath, { bigint: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return void 0;
+    throw err;
   }
-  async function uninstall() {
-    await runIdempotent(run, "launchctl", ["bootout", serviceTarget()], "launchctl bootout", LAUNCHD_NOT_LOADED);
-    await fs19.rm(plistPath(), { force: true });
+  if (!namedBefore.isFile() || namedBefore.isSymbolicLink()) {
+    throw new Error("control token is not a real regular file");
   }
-  async function start() {
-    if (!await fileExists(plistPath())) {
-      throw new Error(`service "${label}" is not installed (no plist at ${plistPath()}) \u2014 call install() first`);
+  const handle = await promises.open(
+    tokenPath,
+    constants.O_RDONLY | (constants.O_NONBLOCK ?? 0) | (constants.O_NOFOLLOW ?? 0)
+  );
+  try {
+    const opened = await handle.stat({ bigint: true });
+    const namedAfterOpen = await promises.lstat(tokenPath, { bigint: true });
+    if (!opened.isFile() || !namedAfterOpen.isFile() || namedAfterOpen.isSymbolicLink() || !sameFileState3(namedBefore, opened) || !sameFileState3(opened, namedAfterOpen)) {
+      throw new Error("control token pathname changed before safe open");
     }
-    await run("launchctl", ["bootstrap", domainTarget(), plistPath()]);
-    await runOrThrow(run, "launchctl", ["kickstart", "-k", serviceTarget()], "launchctl kickstart");
-  }
-  async function stop() {
-    await runIdempotent(run, "launchctl", ["bootout", serviceTarget()], "launchctl bootout", LAUNCHD_NOT_LOADED);
-  }
-  async function status() {
-    const installed = await fileExists(plistPath());
-    const result = await run("launchctl", ["print", serviceTarget()]);
-    const detail = result.stdout || result.stderr;
-    const running = result.code === 0 && /\bstate\s*=\s*running\b/i.test(detail);
-    const determinate = running || !LAUNCHD_CONNECTIVITY_OR_PERMISSION_FAILURE.some((pattern) => pattern.test(detail));
-    return { installed, running, determinate, detail };
+    if (opened.size < 0 || opened.size > BigInt(MAX_CONTROL_TOKEN_BYTES)) {
+      throw new Error("control token exceeds the bounded read limit");
+    }
+    const size = Number(opened.size);
+    const bytes = Buffer.alloc(size);
+    const { bytesRead } = await handle.read(bytes, 0, size, 0);
+    const afterRead = await handle.stat({ bigint: true });
+    const namedAfterRead = await promises.lstat(tokenPath, { bigint: true });
+    if (bytesRead !== size || namedAfterRead.isSymbolicLink() || !sameFileState3(opened, afterRead) || !sameFileState3(afterRead, namedAfterRead)) {
+      throw new Error("control token changed during bounded read");
+    }
+    return bytes.toString("utf8").trim();
+  } finally {
+    await handle.close();
   }
-  return { install, uninstall, start, stop, status };
 }
-var SYSTEMD_CONNECTIVITY_OR_PERMISSION_FAILURE = [
-  /failed to connect to.*bus/i,
-  /connection refused/i,
-  /access denied/i,
-  /permission denied/i,
-  /interactive authentication required/i
-];
-var SYSTEMD_NOT_LOADED = {
-  patterns: [/not loaded/i, /does not exist/i],
-  neverAbsence: SYSTEMD_CONNECTIVITY_OR_PERMISSION_FAILURE
-};
-function hasControlChar(value) {
-  for (let i = 0; i < value.length; i += 1) {
-    const code = value.charCodeAt(i);
-    if (code < 32 || code === 127) return true;
+async function connectControlClient(opts) {
+  const tokenPath = controlTokenPath(opts.storeDir);
+  let token;
+  try {
+    const read = await readControlToken(tokenPath);
+    if (read === void 0) {
+      return { ok: false, reason: "daemon is not running (no control.token found)" };
+    }
+    token = read;
+  } catch (err) {
+    return { ok: false, reason: `could not read the control token: ${errorMessage4(err)}` };
   }
-  return false;
-}
-function assertNoControlChars(value, field) {
-  if (hasControlChar(value)) {
-    throw new Error(
-      `systemd unit ${field} must not contain control characters (newline/CR/etc.) \u2014 refusing to generate a unit file that could inject an unintended directive (got ${JSON.stringify(value)})`
-    );
+  if (!token) {
+    return { ok: false, reason: "control token file is empty" };
+  }
+  const endpoint = controlEndpointPath(opts.productId, opts.storeDir);
+  try {
+    const client = await connectAndHandshake(endpoint, token, opts);
+    return { ok: true, client };
+  } catch (err) {
+    return { ok: false, reason: `daemon control socket not reachable: ${errorMessage4(err)}` };
   }
 }
-function escapeSystemdPercent(value) {
-  return value.replace(/%/g, "%%");
-}
-function quoteSystemdArg(value) {
-  assertNoControlChars(value, "program.command/program.args entry");
-  const escaped = escapeSystemdPercent(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, () => "$$");
-  return `"${escaped}"`;
+function connectAndHandshake(endpoint, token, opts) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(endpoint);
+    const reader = new NdjsonLineReader();
+    let phase = "server-hello";
+    let settled = false;
+    const clientNonce = randomNonceHex();
+    const timer = setTimeout(() => {
+      fail(new Error("handshake timed out"));
+    }, opts.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_MS);
+    timer.unref?.();
+    function fail(err) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.removeAllListeners();
+      socket.destroy();
+      reject(err instanceof Error ? err : new Error(String(err)));
+    }
+    function succeed() {
+      settled = true;
+      clearTimeout(timer);
+      socket.removeListener("error", onError);
+      socket.removeListener("data", onData);
+      resolve(createControlClient(socket, reader, opts));
+    }
+    function onData(chunk) {
+      let lines;
+      try {
+        lines = reader.push(chunk);
+      } catch (err) {
+        fail(err);
+        return;
+      }
+      for (const line of lines) {
+        let parsed;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          fail(new Error("malformed handshake frame"));
+          return;
+        }
+        if (phase === "server-hello") {
+          const hello = parseServerHello(parsed);
+          if (!hello) {
+            fail(new Error("malformed or unexpected server hello"));
+            return;
+          }
+          if (!timingSafeEqualHex(hello.proof, computeServerProof(token, clientNonce))) {
+            fail(new Error("server failed to prove it holds the control token"));
+            return;
+          }
+          socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, auth: computeClientAuth(token, hello.nonce) }));
+          phase = "ready";
+          continue;
+        }
+        if (!parseServerReady(parsed)) {
+          fail(new Error("server did not confirm readiness"));
+          return;
+        }
+        succeed();
+        return;
+      }
+    }
+    function onError(err) {
+      fail(err);
+    }
+    socket.once("error", onError);
+    socket.once("connect", () => {
+      socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, hello: "client", nonce: clientNonce }));
+      socket.on("data", onData);
+    });
+  });
 }
-function generateSystemdUnit(def) {
-  const { name, displayName, program, logDir } = def;
-  assertNoControlChars(name, "name");
-  assertNoControlChars(displayName, "displayName");
-  const cwd = program.cwd ?? os.homedir();
-  assertNoControlChars(cwd, "program.cwd");
-  const outLog = path20.join(logDir, `${name}.out.log`);
-  const errLog = path20.join(logDir, `${name}.err.log`);
-  assertNoControlChars(outLog, "logDir");
-  assertNoControlChars(errLog, "logDir");
-  const execStart = [program.command, ...program.args].map(quoteSystemdArg).join(" ");
-  return `[Unit]
-Description=${escapeSystemdPercent(displayName)}
-
-[Service]
-Type=simple
-ExecStart=${execStart}
-WorkingDirectory=${escapeSystemdPercent(cwd)}
-Restart=on-failure
-RestartSec=10
-StandardOutput=append:${escapeSystemdPercent(outLog)}
-StandardError=append:${escapeSystemdPercent(errLog)}
-
-[Install]
-WantedBy=default.target
-`;
+function withTimeout(promise, ms, message) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(message)), ms);
+    timer.unref?.();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
 }
-function createSystemdLifecycle(def, deps = {}) {
-  const run = deps.run ?? defaultRunner;
-  const fs19 = deps.fs ?? promises;
-  const homedir = deps.homedir ?? (() => os.homedir());
-  const name = sanitizeServiceName(def.name);
-  const unitName = `${name}.service`;
-  const unitPath = () => path20.join(homedir(), ".config", "systemd", "user", unitName);
-  async function fileExists(p) {
+function createControlClient(socket, reader, opts) {
+  const pending = /* @__PURE__ */ new Map();
+  let idSeq = 0;
+  let closed = false;
+  function handleFrame(parsed) {
+    if (!isRecord2(parsed) || typeof parsed.id !== "string") return;
+    const entry = pending.get(parsed.id);
+    if (!entry) return;
+    if ("event" in parsed) {
+      entry.onEvent?.(parsed.event);
+      return;
+    }
+    if (parsed.ok === true) {
+      pending.delete(parsed.id);
+      entry.resolve(parsed.done === true ? void 0 : parsed.result);
+      return;
+    }
+    pending.delete(parsed.id);
+    const shape = parsed.error;
+    entry.reject(
+      new ControlError(
+        typeof shape?.code === "string" ? shape.code : "internal_error",
+        typeof shape?.message === "string" ? shape.message : "unknown control error"
+      )
+    );
+  }
+  socket.on("data", (chunk) => {
+    let lines;
     try {
-      await fs19.stat(p);
-      return true;
+      lines = reader.push(chunk);
     } catch {
-      return false;
+      socket.destroy();
+      return;
     }
-  }
-  async function writeUnit(program) {
-    const unit = generateSystemdUnit({ name, displayName: def.displayName ?? def.name, program, logDir: def.logDir });
-    await fs19.mkdir(path20.dirname(unitPath()), { recursive: true });
-    await fs19.mkdir(def.logDir, { recursive: true });
-    await fs19.writeFile(unitPath(), unit, "utf8");
-  }
-  async function install(opts = {}) {
-    await writeUnit(opts.program ?? def.program);
-    await runOrThrow(run, "systemctl", ["--user", "daemon-reload"], "systemctl daemon-reload");
-    await runOrThrow(run, "systemctl", ["--user", "enable", "--now", unitName], "systemctl enable --now");
-  }
-  async function uninstall() {
-    await runIdempotent(run, "systemctl", ["--user", "disable", "--now", unitName], "systemctl disable --now", SYSTEMD_NOT_LOADED);
-    await fs19.rm(unitPath(), { force: true });
-    await run("systemctl", ["--user", "daemon-reload"]);
-  }
-  async function start() {
-    if (!await fileExists(unitPath())) {
-      throw new Error(`service "${name}" is not installed (no unit file at ${unitPath()}) \u2014 call install() first`);
+    for (const line of lines) {
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      handleFrame(parsed);
     }
-    await runOrThrow(run, "systemctl", ["--user", "start", unitName], "systemctl start");
-  }
-  async function stop() {
-    await runIdempotent(run, "systemctl", ["--user", "stop", unitName], "systemctl stop", SYSTEMD_NOT_LOADED);
+  });
+  socket.on("close", () => {
+    closed = true;
+    for (const entry of pending.values()) entry.reject(new Error("control connection closed"));
+    pending.clear();
+  });
+  socket.on("error", () => {
+  });
+  function send(method, params, onEvent) {
+    const id = `c${++idSeq}`;
+    const promise = new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject, onEvent });
+    });
+    socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, id, method, params }));
+    return { id, promise };
   }
-  async function status() {
-    const installed = await fileExists(unitPath());
-    const result = await run("systemctl", ["--user", "is-active", unitName]);
-    const detail = (result.stdout || result.stderr).trim();
-    const running = result.code === 0 && detail === "active";
-    const determinate = running || !SYSTEMD_CONNECTIVITY_OR_PERMISSION_FAILURE.some((pattern) => pattern.test(detail));
-    return { installed, running, determinate, detail };
+  return {
+    async request(method, params) {
+      if (closed) throw new Error("control connection is closed");
+      const { promise } = send(method, params);
+      const result = await withTimeout(promise, opts.requestTimeoutMs ?? 1e4, `control request "${method}" timed out`);
+      return result;
+    },
+    subscribe(method, params, onEvent) {
+      const { id, promise } = send(method, params, onEvent);
+      promise.catch(() => {
+      });
+      return {
+        close: () => {
+          pending.delete(id);
+          socket.destroy();
+        }
+      };
+    },
+    close() {
+      socket.destroy();
+    }
+  };
+}
+async function isControlDaemonGone(storeDir, productId) {
+  const tokenGone = await promises.stat(controlTokenPath(storeDir)).then(
+    () => false,
+    (err) => err.code === "ENOENT"
+  );
+  if (!tokenGone) return false;
+  const endpoint = controlEndpointPath(productId, storeDir);
+  return new Promise((resolve) => {
+    const socket = net.createConnection(endpoint);
+    const finish = (gone) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(gone);
+    };
+    socket.once("connect", () => finish(false));
+    socket.once("error", (err) => finish(err.code === "ECONNREFUSED" || err.code === "ENOENT"));
+  });
+}
+
+// src/lifecycle/service-types.ts
+function nodeAgentProgram(opts) {
+  const program = {
+    command: opts.nodeBin ?? process.execPath,
+    args: [opts.agentBin, "start", "--config", opts.configPath]
+  };
+  if (opts.cwd !== void 0) program.cwd = opts.cwd;
+  return program;
+}
+function sanitizeServiceName(name) {
+  const cleaned = name.trim().replace(/[^A-Za-z0-9._-]+/g, "-");
+  const safe = cleaned.replace(/^-+/, "");
+  if (!safe) {
+    throw new Error(`service name "${name}" has no valid characters left after sanitizing (allowed: letters, digits, ".", "-", "_"; cannot consist only of leading "-")`);
   }
-  return { install, uninstall, start, stop, status };
+  return safe;
 }
-var WINSW_CONNECTIVITY_OR_PERMISSION_FAILURE = [
-  /access is denied/i,
-  /access denied/i,
+
+// src/lifecycle/launchd.ts
+var LAUNCHD_CONNECTIVITY_OR_PERMISSION_FAILURE = [
+  /operation not permitted/i,
+  /could not find domain/i,
   /permission denied/i,
-  /being used by another process/i
+  /access denied/i
 ];
-var WINSW_NOT_INSTALLED = {
-  codes: [1060],
-  patterns: [/does not exist/i, /non-existent service/i],
-  neverAbsence: WINSW_CONNECTIVITY_OR_PERMISSION_FAILURE
-};
-var WINSW_ALREADY_STOPPED = {
-  codes: [1062, ...WINSW_NOT_INSTALLED.codes ?? []],
-  patterns: [/not running/i, /has not been started/i, ...WINSW_NOT_INSTALLED.patterns],
-  neverAbsence: WINSW_CONNECTIVITY_OR_PERMISSION_FAILURE
+var LAUNCHD_NOT_LOADED = {
+  patterns: [/no such process/i, /could not find (specified )?service/i, /not loaded/i],
+  neverAbsence: LAUNCHD_CONNECTIVITY_OR_PERMISSION_FAILURE
 };
-function xmlEscape(value) {
+function escapeXml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
-function generateWinswXml(def) {
-  const { id, displayName, program, logDir } = def;
-  const argXml = program.args.map((a) => `  <argument>${xmlEscape(a)}</argument>`).join("\n");
-  const cwdXml = program.cwd ? `
-  <workingdirectory>${xmlEscape(program.cwd)}</workingdirectory>` : "";
-  return `<service>
-  <id>${xmlEscape(id)}</id>
-  <name>${xmlEscape(displayName)}</name>
-  <description>${xmlEscape(displayName)} (managed by byok-agent; see templates/service/winsw/README.md)</description>
-  <executable>${xmlEscape(program.command)}</executable>
-${argXml}${cwdXml}
-  <logpath>${xmlEscape(logDir)}</logpath>
-  <log mode="roll"></log>
-  <startmode>Automatic</startmode>
-  <onfailure action="restart" delay="10 sec"/>
-  <onfailure action="restart" delay="30 sec"/>
-  <resetfailure>1 hour</resetfailure>
-</service>
+function plistString(value) {
+  return `<string>${escapeXml(value)}</string>`;
+}
+function generateLaunchdPlist(def) {
+  const { label, program, logDir } = def;
+  const args = [program.command, ...program.args];
+  const cwd = program.cwd ?? os.homedir();
+  const outLog = path20.join(logDir, `${label}.out.log`);
+  const errLog = path20.join(logDir, `${label}.err.log`);
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  ${plistString(label)}
+  <key>ProgramArguments</key>
+  <array>
+${args.map((a) => `    ${plistString(a)}`).join("\n")}
+  </array>
+  <key>WorkingDirectory</key>
+  ${plistString(cwd)}
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>StandardOutPath</key>
+  ${plistString(outLog)}
+  <key>StandardErrorPath</key>
+  ${plistString(errLog)}
+</dict>
+</plist>
 `;
 }
-function createWinswLifecycle(def, deps = {}) {
+function createLaunchdLifecycle(def, deps = {}) {
   const run = deps.run ?? defaultRunner;
   const fs19 = deps.fs ?? promises;
-  const windows = def.windows;
-  if (!windows) {
-    throw new Error("WinSW service lifecycle requires `ServiceDefinition.windows.winswBin` (the product-bundled WinSW executable path)");
-  }
-  const winswBin = windows.winswBin;
-  const id = sanitizeServiceName(def.name);
-  const installDir = windows.installDir ?? def.logDir;
-  const exePath = path20.join(installDir, `${id}.exe`);
-  const xmlPath = path20.join(installDir, `${id}.xml`);
+  const homedir = deps.homedir ?? (() => os.homedir());
+  const getuid = deps.getuid ?? (() => {
+    if (typeof process.getuid !== "function") {
+      throw new Error("launchd lifecycle requires a POSIX uid (process.getuid unavailable) \u2014 this module only runs on macOS");
+    }
+    return process.getuid();
+  });
+  const label = sanitizeServiceName(def.name);
+  const plistPath = () => path20.join(homedir(), "Library", "LaunchAgents", `${label}.plist`);
+  const domainTarget = () => `gui/${getuid()}`;
+  const serviceTarget = () => `${domainTarget()}/${label}`;
   async function fileExists(p) {
     try {
       await fs19.stat(p);
@@ -9555,381 +10530,330 @@ function createWinswLifecycle(def, deps = {}) {
       return false;
     }
   }
-  async function writeFiles(program) {
-    const xml = generateWinswXml({ id, displayName: def.displayName ?? def.name, program, logDir: def.logDir });
-    await fs19.mkdir(installDir, { recursive: true });
+  async function writePlist(program) {
+    const xml = generateLaunchdPlist({ label, program, logDir: def.logDir });
+    await fs19.mkdir(path20.dirname(plistPath()), { recursive: true });
     await fs19.mkdir(def.logDir, { recursive: true });
-    await fs19.copyFile(winswBin, exePath);
-    await fs19.writeFile(xmlPath, xml, "utf8");
+    await fs19.writeFile(plistPath(), xml, "utf8");
   }
   async function install(opts = {}) {
-    await writeFiles(opts.program ?? def.program);
-    await runOrThrow(run, exePath, ["install"], "winsw install");
-    await runOrThrow(run, exePath, ["start"], "winsw start");
+    await writePlist(opts.program ?? def.program);
+    await run("launchctl", ["bootout", serviceTarget()]);
+    await runOrThrow(run, "launchctl", ["bootstrap", domainTarget(), plistPath()], "launchctl bootstrap");
+    await runOrThrow(run, "launchctl", ["enable", serviceTarget()], "launchctl enable");
+    await run("launchctl", ["kickstart", "-k", serviceTarget()]);
   }
   async function uninstall() {
-    await runIdempotent(run, exePath, ["stop"], "winsw stop", WINSW_NOT_INSTALLED);
-    await runIdempotent(run, exePath, ["uninstall"], "winsw uninstall", WINSW_NOT_INSTALLED);
-    await fs19.rm(exePath, { force: true });
-    await fs19.rm(xmlPath, { force: true });
+    await runIdempotent(run, "launchctl", ["bootout", serviceTarget()], "launchctl bootout", LAUNCHD_NOT_LOADED);
+    await fs19.rm(plistPath(), { force: true });
   }
   async function start() {
-    if (!await fileExists(xmlPath)) {
-      throw new Error(`service "${id}" is not installed (no config at ${xmlPath}) \u2014 call install() first`);
+    if (!await fileExists(plistPath())) {
+      throw new Error(`service "${label}" is not installed (no plist at ${plistPath()}) \u2014 call install() first`);
     }
-    await runOrThrow(run, exePath, ["start"], "winsw start");
+    await run("launchctl", ["bootstrap", domainTarget(), plistPath()]);
+    await runOrThrow(run, "launchctl", ["kickstart", "-k", serviceTarget()], "launchctl kickstart");
   }
   async function stop() {
-    await runIdempotent(run, exePath, ["stop"], "winsw stop", WINSW_ALREADY_STOPPED);
+    await runIdempotent(run, "launchctl", ["bootout", serviceTarget()], "launchctl bootout", LAUNCHD_NOT_LOADED);
   }
   async function status() {
-    const installed = await fileExists(xmlPath);
-    const result = await run("sc.exe", ["query", id]);
-    const detail = (result.stdout || result.stderr).trim();
-    const running = result.code === 0 && /\bSTATE\b.*\bRUNNING\b/i.test(detail);
-    const determinate = running || !WINSW_CONNECTIVITY_OR_PERMISSION_FAILURE.some((pattern) => pattern.test(detail));
+    const installed = await fileExists(plistPath());
+    const result = await run("launchctl", ["print", serviceTarget()]);
+    const detail = result.stdout || result.stderr;
+    const running = result.code === 0 && /\bstate\s*=\s*running\b/i.test(detail);
+    const determinate = running || !LAUNCHD_CONNECTIVITY_OR_PERMISSION_FAILURE.some((pattern) => pattern.test(detail));
     return { installed, running, determinate, detail };
   }
   return { install, uninstall, start, stop, status };
 }
-
-// src/lifecycle/create-service-lifecycle.ts
-var UnsupportedServicePlatformError = class extends Error {
-  constructor(platform) {
-    super(`no OS service lifecycle for platform "${platform}" \u2014 supported: darwin (launchd), linux (systemd --user), win32 (WinSW)`);
-    this.name = "UnsupportedServicePlatformError";
-  }
-};
-function createServiceLifecycle(def, opts = {}) {
-  const platform = opts.platform ?? process.platform;
-  switch (platform) {
-    case "darwin":
-      return createLaunchdLifecycle(def, opts.deps);
-    case "linux":
-      return createSystemdLifecycle(def, opts.deps);
-    case "win32":
-      return createWinswLifecycle(def, opts.deps);
-    default:
-      throw new UnsupportedServicePlatformError(platform);
-  }
-}
-var REQUIRED_FIELDS = ["productName", "productId", "serverUrl", "workspaceRoot"];
-var ConfigError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ConfigError";
-  }
+var SYSTEMD_CONNECTIVITY_OR_PERMISSION_FAILURE = [
+  /failed to connect to.*bus/i,
+  /connection refused/i,
+  /access denied/i,
+  /permission denied/i,
+  /interactive authentication required/i
+];
+var SYSTEMD_NOT_LOADED = {
+  patterns: [/not loaded/i, /does not exist/i],
+  neverAbsence: SYSTEMD_CONNECTIVITY_OR_PERMISSION_FAILURE
 };
-function loadConfig(configPath, overrides = {}) {
-  let base = {};
-  if (configPath) {
-    let raw;
-    try {
-      raw = readFileSync(configPath, "utf8");
-    } catch (err) {
-      throw new ConfigError(`could not read config at "${configPath}": ${err instanceof Error ? err.message : String(err)}`);
-    }
-    try {
-      base = JSON.parse(raw);
-    } catch (err) {
-      throw new ConfigError(`config at "${configPath}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
-  const merged = { ...base, ...overrides };
-  if (merged.gitWorkspace !== void 0) {
-    try {
-      GitWorkspaceManager.validateConfig(merged.gitWorkspace);
-    } catch (error) {
-      throw new ConfigError(error instanceof Error ? error.message : "invalid gitWorkspace configuration");
-    }
+function hasControlChar(value) {
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    if (code < 32 || code === 127) return true;
   }
-  for (const field of REQUIRED_FIELDS) {
-    if (!merged[field]) {
-      throw new ConfigError(`config is missing required field "${field}"`);
-    }
+  return false;
+}
+function assertNoControlChars(value, field) {
+  if (hasControlChar(value)) {
+    throw new Error(
+      `systemd unit ${field} must not contain control characters (newline/CR/etc.) \u2014 refusing to generate a unit file that could inject an unintended directive (got ${JSON.stringify(value)})`
+    );
   }
-  return merged;
 }
-function resolveStoreDir(config) {
-  return DeviceStore.resolveDir(config.productId, config.storeDir);
+function escapeSystemdPercent(value) {
+  return value.replace(/%/g, "%%");
 }
-function argValue(args, flag) {
-  const idx = args.indexOf(flag);
-  const value = idx >= 0 ? args[idx + 1] : void 0;
-  return value !== void 0 && !value.startsWith("--") ? value : void 0;
+function quoteSystemdArg(value) {
+  assertNoControlChars(value, "program.command/program.args entry");
+  const escaped = escapeSystemdPercent(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, () => "$$");
+  return `"${escaped}"`;
 }
-function hasFlag(args, flag) {
-  return args.includes(flag);
+function generateSystemdUnit(def) {
+  const { name, displayName, program, logDir } = def;
+  assertNoControlChars(name, "name");
+  assertNoControlChars(displayName, "displayName");
+  const cwd = program.cwd ?? os.homedir();
+  assertNoControlChars(cwd, "program.cwd");
+  const outLog = path20.join(logDir, `${name}.out.log`);
+  const errLog = path20.join(logDir, `${name}.err.log`);
+  assertNoControlChars(outLog, "logDir");
+  assertNoControlChars(errLog, "logDir");
+  const execStart = [program.command, ...program.args].map(quoteSystemdArg).join(" ");
+  return `[Unit]
+Description=${escapeSystemdPercent(displayName)}
+
+[Service]
+Type=simple
+ExecStart=${execStart}
+WorkingDirectory=${escapeSystemdPercent(cwd)}
+Restart=on-failure
+RestartSec=10
+StandardOutput=append:${escapeSystemdPercent(outLog)}
+StandardError=append:${escapeSystemdPercent(errLog)}
+
+[Install]
+WantedBy=default.target
+`;
 }
-function positionalArgs(args, valueFlags = []) {
-  const result = [];
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === void 0) continue;
-    if (valueFlags.includes(arg)) {
-      i++;
-      continue;
+function createSystemdLifecycle(def, deps = {}) {
+  const run = deps.run ?? defaultRunner;
+  const fs19 = deps.fs ?? promises;
+  const homedir = deps.homedir ?? (() => os.homedir());
+  const name = sanitizeServiceName(def.name);
+  const unitName = `${name}.service`;
+  const unitPath = () => path20.join(homedir(), ".config", "systemd", "user", unitName);
+  async function fileExists(p) {
+    try {
+      await fs19.stat(p);
+      return true;
+    } catch {
+      return false;
     }
-    result.push(arg);
   }
-  return result;
-}
-var MAX_CONTROL_TOKEN_BYTES = 256;
-function errorMessage4(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-function sameFileState3(left, right) {
-  return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
-}
-async function readControlToken(tokenPath) {
-  let namedBefore;
-  try {
-    namedBefore = await promises.lstat(tokenPath, { bigint: true });
-  } catch (err) {
-    if (err.code === "ENOENT") return void 0;
-    throw err;
+  async function writeUnit(program) {
+    const unit = generateSystemdUnit({ name, displayName: def.displayName ?? def.name, program, logDir: def.logDir });
+    await fs19.mkdir(path20.dirname(unitPath()), { recursive: true });
+    await fs19.mkdir(def.logDir, { recursive: true });
+    await fs19.writeFile(unitPath(), unit, "utf8");
   }
-  if (!namedBefore.isFile() || namedBefore.isSymbolicLink()) {
-    throw new Error("control token is not a real regular file");
+  async function install(opts = {}) {
+    await writeUnit(opts.program ?? def.program);
+    await runOrThrow(run, "systemctl", ["--user", "daemon-reload"], "systemctl daemon-reload");
+    await runOrThrow(run, "systemctl", ["--user", "enable", "--now", unitName], "systemctl enable --now");
   }
-  const handle = await promises.open(
-    tokenPath,
-    constants.O_RDONLY | (constants.O_NONBLOCK ?? 0) | (constants.O_NOFOLLOW ?? 0)
-  );
-  try {
-    const opened = await handle.stat({ bigint: true });
-    const namedAfterOpen = await promises.lstat(tokenPath, { bigint: true });
-    if (!opened.isFile() || !namedAfterOpen.isFile() || namedAfterOpen.isSymbolicLink() || !sameFileState3(namedBefore, opened) || !sameFileState3(opened, namedAfterOpen)) {
-      throw new Error("control token pathname changed before safe open");
-    }
-    if (opened.size < 0 || opened.size > BigInt(MAX_CONTROL_TOKEN_BYTES)) {
-      throw new Error("control token exceeds the bounded read limit");
-    }
-    const size = Number(opened.size);
-    const bytes = Buffer.alloc(size);
-    const { bytesRead } = await handle.read(bytes, 0, size, 0);
-    const afterRead = await handle.stat({ bigint: true });
-    const namedAfterRead = await promises.lstat(tokenPath, { bigint: true });
-    if (bytesRead !== size || namedAfterRead.isSymbolicLink() || !sameFileState3(opened, afterRead) || !sameFileState3(afterRead, namedAfterRead)) {
-      throw new Error("control token changed during bounded read");
-    }
-    return bytes.toString("utf8").trim();
-  } finally {
-    await handle.close();
+  async function uninstall() {
+    await runIdempotent(run, "systemctl", ["--user", "disable", "--now", unitName], "systemctl disable --now", SYSTEMD_NOT_LOADED);
+    await fs19.rm(unitPath(), { force: true });
+    await run("systemctl", ["--user", "daemon-reload"]);
   }
-}
-async function connectControlClient(opts) {
-  const tokenPath = controlTokenPath(opts.storeDir);
-  let token;
-  try {
-    const read = await readControlToken(tokenPath);
-    if (read === void 0) {
-      return { ok: false, reason: "daemon is not running (no control.token found)" };
+  async function start() {
+    if (!await fileExists(unitPath())) {
+      throw new Error(`service "${name}" is not installed (no unit file at ${unitPath()}) \u2014 call install() first`);
     }
-    token = read;
-  } catch (err) {
-    return { ok: false, reason: `could not read the control token: ${errorMessage4(err)}` };
+    await runOrThrow(run, "systemctl", ["--user", "start", unitName], "systemctl start");
   }
-  if (!token) {
-    return { ok: false, reason: "control token file is empty" };
+  async function stop() {
+    await runIdempotent(run, "systemctl", ["--user", "stop", unitName], "systemctl stop", SYSTEMD_NOT_LOADED);
   }
-  const endpoint = controlEndpointPath(opts.productId, opts.storeDir);
-  try {
-    const client = await connectAndHandshake(endpoint, token, opts);
-    return { ok: true, client };
-  } catch (err) {
-    return { ok: false, reason: `daemon control socket not reachable: ${errorMessage4(err)}` };
+  async function status() {
+    const installed = await fileExists(unitPath());
+    const result = await run("systemctl", ["--user", "is-active", unitName]);
+    const detail = (result.stdout || result.stderr).trim();
+    const running = result.code === 0 && detail === "active";
+    const determinate = running || !SYSTEMD_CONNECTIVITY_OR_PERMISSION_FAILURE.some((pattern) => pattern.test(detail));
+    return { installed, running, determinate, detail };
   }
+  return { install, uninstall, start, stop, status };
 }
-function connectAndHandshake(endpoint, token, opts) {
-  return new Promise((resolve, reject) => {
-    const socket = net.createConnection(endpoint);
-    const reader = new NdjsonLineReader();
-    let phase = "server-hello";
-    let settled = false;
-    const clientNonce = randomNonceHex();
-    const timer = setTimeout(() => {
-      fail(new Error("handshake timed out"));
-    }, opts.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_MS);
-    timer.unref?.();
-    function fail(err) {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      socket.removeAllListeners();
-      socket.destroy();
-      reject(err instanceof Error ? err : new Error(String(err)));
-    }
-    function succeed() {
-      settled = true;
-      clearTimeout(timer);
-      socket.removeListener("error", onError);
-      socket.removeListener("data", onData);
-      resolve(createControlClient(socket, reader, opts));
-    }
-    function onData(chunk) {
-      let lines;
-      try {
-        lines = reader.push(chunk);
-      } catch (err) {
-        fail(err);
-        return;
-      }
-      for (const line of lines) {
-        let parsed;
-        try {
-          parsed = JSON.parse(line);
-        } catch {
-          fail(new Error("malformed handshake frame"));
-          return;
-        }
-        if (phase === "server-hello") {
-          const hello = parseServerHello(parsed);
-          if (!hello) {
-            fail(new Error("malformed or unexpected server hello"));
-            return;
-          }
-          if (!timingSafeEqualHex(hello.proof, computeServerProof(token, clientNonce))) {
-            fail(new Error("server failed to prove it holds the control token"));
-            return;
-          }
-          socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, auth: computeClientAuth(token, hello.nonce) }));
-          phase = "ready";
-          continue;
-        }
-        if (!parseServerReady(parsed)) {
-          fail(new Error("server did not confirm readiness"));
-          return;
-        }
-        succeed();
-        return;
-      }
+var WINSW_CONNECTIVITY_OR_PERMISSION_FAILURE = [
+  /access is denied/i,
+  /access denied/i,
+  /permission denied/i,
+  /being used by another process/i
+];
+var WINSW_NOT_INSTALLED = {
+  codes: [1060],
+  patterns: [/does not exist/i, /non-existent service/i],
+  neverAbsence: WINSW_CONNECTIVITY_OR_PERMISSION_FAILURE
+};
+var WINSW_ALREADY_STOPPED = {
+  codes: [1062, ...WINSW_NOT_INSTALLED.codes ?? []],
+  patterns: [/not running/i, /has not been started/i, ...WINSW_NOT_INSTALLED.patterns],
+  neverAbsence: WINSW_CONNECTIVITY_OR_PERMISSION_FAILURE
+};
+function xmlEscape(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function generateWinswXml(def) {
+  const { id, displayName, program, logDir } = def;
+  const argXml = program.args.map((a) => `  <argument>${xmlEscape(a)}</argument>`).join("\n");
+  const cwdXml = program.cwd ? `
+  <workingdirectory>${xmlEscape(program.cwd)}</workingdirectory>` : "";
+  return `<service>
+  <id>${xmlEscape(id)}</id>
+  <name>${xmlEscape(displayName)}</name>
+  <description>${xmlEscape(displayName)} (managed by byok-agent; see templates/service/winsw/README.md)</description>
+  <executable>${xmlEscape(program.command)}</executable>
+${argXml}${cwdXml}
+  <logpath>${xmlEscape(logDir)}</logpath>
+  <log mode="roll"></log>
+  <startmode>Automatic</startmode>
+  <onfailure action="restart" delay="10 sec"/>
+  <onfailure action="restart" delay="30 sec"/>
+  <resetfailure>1 hour</resetfailure>
+</service>
+`;
+}
+function createWinswLifecycle(def, deps = {}) {
+  const run = deps.run ?? defaultRunner;
+  const fs19 = deps.fs ?? promises;
+  const windows = def.windows;
+  if (!windows) {
+    throw new Error("WinSW service lifecycle requires `ServiceDefinition.windows.winswBin` (the product-bundled WinSW executable path)");
+  }
+  const winswBin = windows.winswBin;
+  const id = sanitizeServiceName(def.name);
+  const installDir = windows.installDir ?? def.logDir;
+  const exePath = path20.join(installDir, `${id}.exe`);
+  const xmlPath = path20.join(installDir, `${id}.xml`);
+  async function fileExists(p) {
+    try {
+      await fs19.stat(p);
+      return true;
+    } catch {
+      return false;
     }
-    function onError(err) {
-      fail(err);
+  }
+  async function writeFiles(program) {
+    const xml = generateWinswXml({ id, displayName: def.displayName ?? def.name, program, logDir: def.logDir });
+    await fs19.mkdir(installDir, { recursive: true });
+    await fs19.mkdir(def.logDir, { recursive: true });
+    await fs19.copyFile(winswBin, exePath);
+    await fs19.writeFile(xmlPath, xml, "utf8");
+  }
+  async function install(opts = {}) {
+    await writeFiles(opts.program ?? def.program);
+    await runOrThrow(run, exePath, ["install"], "winsw install");
+    await runOrThrow(run, exePath, ["start"], "winsw start");
+  }
+  async function uninstall() {
+    await runIdempotent(run, exePath, ["stop"], "winsw stop", WINSW_NOT_INSTALLED);
+    await runIdempotent(run, exePath, ["uninstall"], "winsw uninstall", WINSW_NOT_INSTALLED);
+    await fs19.rm(exePath, { force: true });
+    await fs19.rm(xmlPath, { force: true });
+  }
+  async function start() {
+    if (!await fileExists(xmlPath)) {
+      throw new Error(`service "${id}" is not installed (no config at ${xmlPath}) \u2014 call install() first`);
     }
-    socket.once("error", onError);
-    socket.once("connect", () => {
-      socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, hello: "client", nonce: clientNonce }));
-      socket.on("data", onData);
-    });
-  });
+    await runOrThrow(run, exePath, ["start"], "winsw start");
+  }
+  async function stop() {
+    await runIdempotent(run, exePath, ["stop"], "winsw stop", WINSW_ALREADY_STOPPED);
+  }
+  async function status() {
+    const installed = await fileExists(xmlPath);
+    const result = await run("sc.exe", ["query", id]);
+    const detail = (result.stdout || result.stderr).trim();
+    const running = result.code === 0 && /\bSTATE\b.*\bRUNNING\b/i.test(detail);
+    const determinate = running || !WINSW_CONNECTIVITY_OR_PERMISSION_FAILURE.some((pattern) => pattern.test(detail));
+    return { installed, running, determinate, detail };
+  }
+  return { install, uninstall, start, stop, status };
 }
-function withTimeout(promise, ms, message) {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new Error(message)), ms);
-    timer.unref?.();
-    promise.then(
-      (value) => {
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (err) => {
-        clearTimeout(timer);
-        reject(err);
-      }
-    );
-  });
+
+// src/lifecycle/create-service-lifecycle.ts
+var UnsupportedServicePlatformError = class extends Error {
+  constructor(platform) {
+    super(`no OS service lifecycle for platform "${platform}" \u2014 supported: darwin (launchd), linux (systemd --user), win32 (WinSW)`);
+    this.name = "UnsupportedServicePlatformError";
+  }
+};
+function createServiceLifecycle(def, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  switch (platform) {
+    case "darwin":
+      return createLaunchdLifecycle(def, opts.deps);
+    case "linux":
+      return createSystemdLifecycle(def, opts.deps);
+    case "win32":
+      return createWinswLifecycle(def, opts.deps);
+    default:
+      throw new UnsupportedServicePlatformError(platform);
+  }
 }
-function createControlClient(socket, reader, opts) {
-  const pending = /* @__PURE__ */ new Map();
-  let idSeq = 0;
-  let closed = false;
-  function handleFrame(parsed) {
-    if (!isRecord2(parsed) || typeof parsed.id !== "string") return;
-    const entry = pending.get(parsed.id);
-    if (!entry) return;
-    if ("event" in parsed) {
-      entry.onEvent?.(parsed.event);
-      return;
+var REQUIRED_FIELDS = ["productName", "productId", "serverUrl", "workspaceRoot"];
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+function loadConfig(configPath, overrides = {}) {
+  let base = {};
+  if (configPath) {
+    let raw;
+    try {
+      raw = readFileSync(configPath, "utf8");
+    } catch (err) {
+      throw new ConfigError(`could not read config at "${configPath}": ${err instanceof Error ? err.message : String(err)}`);
     }
-    if (parsed.ok === true) {
-      pending.delete(parsed.id);
-      entry.resolve(parsed.done === true ? void 0 : parsed.result);
-      return;
+    try {
+      base = JSON.parse(raw);
+    } catch (err) {
+      throw new ConfigError(`config at "${configPath}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
     }
-    pending.delete(parsed.id);
-    const shape = parsed.error;
-    entry.reject(
-      new ControlError(
-        typeof shape?.code === "string" ? shape.code : "internal_error",
-        typeof shape?.message === "string" ? shape.message : "unknown control error"
-      )
-    );
   }
-  socket.on("data", (chunk) => {
-    let lines;
+  const merged = { ...base, ...overrides };
+  if (merged.gitWorkspace !== void 0) {
     try {
-      lines = reader.push(chunk);
-    } catch {
-      socket.destroy();
-      return;
-    }
-    for (const line of lines) {
-      let parsed;
-      try {
-        parsed = JSON.parse(line);
-      } catch {
-        continue;
-      }
-      handleFrame(parsed);
+      GitWorkspaceManager.validateConfig(merged.gitWorkspace);
+    } catch (error) {
+      throw new ConfigError(error instanceof Error ? error.message : "invalid gitWorkspace configuration");
     }
-  });
-  socket.on("close", () => {
-    closed = true;
-    for (const entry of pending.values()) entry.reject(new Error("control connection closed"));
-    pending.clear();
-  });
-  socket.on("error", () => {
-  });
-  function send(method, params, onEvent) {
-    const id = `c${++idSeq}`;
-    const promise = new Promise((resolve, reject) => {
-      pending.set(id, { resolve, reject, onEvent });
-    });
-    socket.write(encodeFrame({ v: CONTROL_PROTOCOL_VERSION, id, method, params }));
-    return { id, promise };
   }
-  return {
-    async request(method, params) {
-      if (closed) throw new Error("control connection is closed");
-      const { promise } = send(method, params);
-      const result = await withTimeout(promise, opts.requestTimeoutMs ?? 1e4, `control request "${method}" timed out`);
-      return result;
-    },
-    subscribe(method, params, onEvent) {
-      const { id, promise } = send(method, params, onEvent);
-      promise.catch(() => {
-      });
-      return {
-        close: () => {
-          pending.delete(id);
-          socket.destroy();
-        }
-      };
-    },
-    close() {
-      socket.destroy();
+  for (const field of REQUIRED_FIELDS) {
+    if (!merged[field]) {
+      throw new ConfigError(`config is missing required field "${field}"`);
     }
-  };
+  }
+  return merged;
 }
-async function isControlDaemonGone(storeDir, productId) {
-  const tokenGone = await promises.stat(controlTokenPath(storeDir)).then(
-    () => false,
-    (err) => err.code === "ENOENT"
-  );
-  if (!tokenGone) return false;
-  const endpoint = controlEndpointPath(productId, storeDir);
-  return new Promise((resolve) => {
-    const socket = net.createConnection(endpoint);
-    const finish = (gone) => {
-      socket.removeAllListeners();
-      socket.destroy();
-      resolve(gone);
-    };
-    socket.once("connect", () => finish(false));
-    socket.once("error", (err) => finish(err.code === "ECONNREFUSED" || err.code === "ENOENT"));
-  });
+function resolveStoreDir(config) {
+  return DeviceStore.resolveDir(config.productId, config.storeDir);
+}
+function argValue(args, flag) {
+  const idx = args.indexOf(flag);
+  const value = idx >= 0 ? args[idx + 1] : void 0;
+  return value !== void 0 && !value.startsWith("--") ? value : void 0;
+}
+function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+function positionalArgs(args, valueFlags = []) {
+  const result = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === void 0) continue;
+    if (valueFlags.includes(arg)) {
+      i++;
+      continue;
+    }
+    result.push(arg);
+  }
+  return result;
 }
 
 // src/bin/format.ts
@@ -10029,6 +10953,19 @@ function formatDaemonEventLine(event, options = {}) {
       ].filter((part) => part !== void 0);
       return parts.join(" ");
     }
+    case "device-assertion": {
+      const parts = event.result === "issued" ? [
+        `${prefix} device-assertion result=issued`,
+        `audience=${quote(event.audience)}`,
+        `jti=${event.jti}`,
+        `expiresAt=${event.expiresAt}`
+      ] : [
+        `${prefix} device-assertion result=denied`,
+        `reason=${event.reason}`,
+        event.audienceSize !== void 0 ? `audienceSize=${event.audienceSize}` : void 0
+      ].filter((part) => part !== void 0);
+      return parts.join(" ");
+    }
   }
 }
 function formatTaskLine(task) {
@@ -11259,6 +12196,14 @@ function redactForAudit(event) {
       return { ...base, reason: event.reason, undeliveredOutboxCount: event.undeliveredOutboxCount };
     case "stale-approval-decision":
       return { ...base, taskId: event.taskId, decision: event.decision, reasonSize: byteSize(event.reason) };
+    case "device-assertion":
+      return event.result === "issued" ? {
+        ...base,
+        result: "issued",
+        audience: event.audience,
+        jti: event.jti,
+        expiresAt: event.expiresAt
+      } : { ...base, result: "denied", reason: event.reason, audienceSize: event.audienceSize };
     case "git-workspace":
       return {
         ...base,
@@ -11399,6 +12344,26 @@ function reconstructDaemonEvent(raw) {
         reason: reasonSize === void 0 ? void 0 : placeholderFor(reasonSize)
       };
     }
+    case "device-assertion": {
+      if (raw.result === "issued") {
+        return {
+          kind: "device-assertion",
+          ts,
+          result: "issued",
+          audience: typeof raw.audience === "string" ? raw.audience : "",
+          jti: typeof raw.jti === "string" ? raw.jti : "",
+          expiresAt: typeof raw.expiresAt === "string" ? raw.expiresAt : ""
+        };
+      }
+      const audienceSize = num(raw.audienceSize);
+      return {
+        kind: "device-assertion",
+        ts,
+        result: "denied",
+        reason: typeof raw.reason === "string" ? raw.reason : "",
+        ...audienceSize === void 0 ? {} : { audienceSize }
+      };
+    }
     case "git-workspace": {
       const commitsSinceBaseline = gitCount(raw.commitsSinceBaseline);
       const dirty = gitDirty(raw.dirty);