@agentproto/runtime 0.5.0 → 0.6.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { randomBytes, randomUUID, createHash } from 'crypto';
+import { randomBytes, randomUUID, createHash, createHmac, timingSafeEqual } from 'crypto';
 import { existsSync, mkdirSync, writeFileSync, renameSync, readFileSync, promises, createReadStream, createWriteStream, openSync, closeSync } from 'fs';
-import { mkdir, writeFile, unlink, readdir, readFile, stat, appendFile, chmod, rm, mkdtemp, access } from 'fs/promises';
+import { mkdir, writeFile, unlink, readdir, readFile, stat, chmod, rename, appendFile, rm, mkdtemp, access } from 'fs/promises';
 import { resolve, join, dirname, isAbsolute, normalize, relative, basename } from 'path';
 import { createMcpServer } from '@agentproto/mcp-server';
 import { homedir, tmpdir } from 'os';
@@ -8,9 +8,10 @@ import { execFile, spawn } from 'child_process';
 import { z } from 'zod';
 import { EventEmitter } from 'events';
 import { createInterface } from 'readline';
+import { getModelProvider, resolvePricing } from '@agentproto/model-catalog/llm';
+import * as providers_store_star from '@agentproto/providers-store';
 import { makeAdapterLister, makeAdapterResolver, makeCredsStore, discoverAdapterPackages, makeSetupLedger, makeListTool, makeSetupTool } from '@agentproto/provider-kit';
 import { SandboxSpecSchema, resolveLifecyclePolicy, createSandboxAgentSessionHost } from '@agentproto/sandbox';
-import { resolvePricing } from '@agentproto/model-catalog/llm';
 import matter from 'gray-matter';
 import { createServer } from 'http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -29,12 +30,27 @@ import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { Cron } from 'croner';
 import { promisify } from 'util';
 import { createServer as createServer$1 } from 'net';
+import { daemonHandshakeOverSink } from '@agentproto/acp/tunnel';
+import { PairingError, encodeOfferUrl, HOSTED_RENDEZVOUS_URL, decodePairingHello, respondToHandshake, encodePairingMessage, derivePairRoot, deriveEpochRoutingToken, currentEpoch } from '@agentproto/secrets/pairing';
+import { identityFingerprint } from '@agentproto/secrets/identity';
 
 /**
  * @agentproto/runtime v0.1.0-alpha
  * Long-running gateway: MCP server + HTTP transport + HEARTBEAT autonomy + conversation persistence over a workspace dir.
  */
-
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget);
 async function writeRuntimeMeta(workspace, meta) {
   const dir = join(workspace, ".agentproto");
   try {
@@ -317,12 +333,12 @@ async function runCommand(input) {
         return buf;
       }
       const room = STREAM_BUFFER_CAP - buf.length;
-      const text5 = chunk.toString("utf8");
-      if (text5.length > room) {
+      const text6 = chunk.toString("utf8");
+      if (text6.length > room) {
         truncated = true;
-        return buf + text5.slice(0, room);
+        return buf + text6.slice(0, room);
       }
-      return buf + text5;
+      return buf + text6;
     }
     child.stdout?.on("data", (d) => {
       stdout = appendCapped(stdout, d);
@@ -727,14 +743,14 @@ function extractText(value) {
   return null;
 }
 function formatToolResult(toolName, result, isError) {
-  const text5 = extractText(result);
+  const text6 = extractText(result);
   if (isError) {
-    const message = text5 ?? (result != null ? JSON.stringify(result) : "failed");
+    const message = text6 ?? (result != null ? JSON.stringify(result) : "failed");
     const firstLine = message.split(/\r?\n/)[0] ?? message;
     return truncate(firstLine, MAX_RESULT_LENGTH);
   }
-  if (text5 == null) return null;
-  const trimmed = text5.trim();
+  if (text6 == null) return null;
+  const trimmed = text6.trim();
   if (!trimmed) return null;
   const lines = trimmed.split(/\r?\n/);
   if (lines.length > 1) {
@@ -750,20 +766,42 @@ function sessionTranscriptDir(sessionId, baseDir) {
 function sessionEventsPath(sessionId, baseDir) {
   return join(sessionTranscriptDir(sessionId, baseDir), "events.jsonl");
 }
+function highestSeqOnDisk(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return 0;
+  }
+  let max = 0;
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const rec = JSON.parse(trimmed);
+      if (typeof rec.seq === "number" && rec.seq > max) max = rec.seq;
+    } catch {
+    }
+  }
+  return max;
+}
 function createTranscriptWriter(opts) {
   const baseDir = opts?.baseDir;
   const states = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Map();
   const getState = (sessionId) => {
     const existing = states.get(sessionId);
     if (existing) return existing;
     mkdirSync(sessionTranscriptDir(sessionId, baseDir), { recursive: true });
-    const stream = createWriteStream(sessionEventsPath(sessionId, baseDir), { flags: "a" });
+    const eventsPath = sessionEventsPath(sessionId, baseDir);
+    const resumeSeq = highestSeqOnDisk(eventsPath);
+    const stream = createWriteStream(eventsPath, { flags: "a" });
     stream.on("error", (err) => {
       console.warn(`[transcript-writer] session ${sessionId}: ${err.message}`);
     });
     const state = {
       stream,
-      seq: 0,
+      seq: resumeSeq,
       textBuf: "",
       thoughtBuf: "",
       textDebounce: null,
@@ -774,9 +812,12 @@ function createTranscriptWriter(opts) {
   };
   const writeRecord = (sessionId, state, record) => {
     state.seq += 1;
-    state.stream.write(
-      JSON.stringify({ seq: state.seq, ts: (/* @__PURE__ */ new Date()).toISOString(), ...record }) + "\n"
-    );
+    const full = { seq: state.seq, ts: (/* @__PURE__ */ new Date()).toISOString(), ...record };
+    state.stream.write(JSON.stringify(full) + "\n");
+    const subs = listeners.get(sessionId);
+    if (subs) {
+      for (const onRecord of subs) onRecord(full);
+    }
   };
   const flushTextBuf = (sessionId, state) => {
     if (state.textDebounce) {
@@ -784,9 +825,9 @@ function createTranscriptWriter(opts) {
       state.textDebounce = null;
     }
     if (!state.textBuf) return;
-    const text5 = state.textBuf;
+    const text6 = state.textBuf;
     state.textBuf = "";
-    writeRecord(sessionId, state, { kind: "text-delta", sessionId, text: text5 });
+    writeRecord(sessionId, state, { kind: "text-delta", sessionId, text: text6 });
   };
   const flushThoughtBuf = (sessionId, state) => {
     if (state.thoughtDebounce) {
@@ -794,9 +835,9 @@ function createTranscriptWriter(opts) {
       state.thoughtDebounce = null;
     }
     if (!state.thoughtBuf) return;
-    const text5 = state.thoughtBuf;
+    const text6 = state.thoughtBuf;
     state.thoughtBuf = "";
-    writeRecord(sessionId, state, { kind: "thought", sessionId, text: text5 });
+    writeRecord(sessionId, state, { kind: "thought", sessionId, text: text6 });
   };
   const flushBuffers = (sessionId, state) => {
     flushThoughtBuf(sessionId, state);
@@ -807,9 +848,9 @@ function createTranscriptWriter(opts) {
     state.textDebounce = setTimeout(() => {
       state.textDebounce = null;
       if (!state.textBuf) return;
-      const text5 = state.textBuf;
+      const text6 = state.textBuf;
       state.textBuf = "";
-      writeRecord(sessionId, state, { kind: "text-delta", sessionId, text: text5, partial: true });
+      writeRecord(sessionId, state, { kind: "text-delta", sessionId, text: text6, partial: true });
     }, DEBOUNCE_MS);
   };
   const scheduleThoughtDebounce = (sessionId, state) => {
@@ -817,17 +858,17 @@ function createTranscriptWriter(opts) {
     state.thoughtDebounce = setTimeout(() => {
       state.thoughtDebounce = null;
       if (!state.thoughtBuf) return;
-      const text5 = state.thoughtBuf;
+      const text6 = state.thoughtBuf;
       state.thoughtBuf = "";
-      writeRecord(sessionId, state, { kind: "thought", sessionId, text: text5, partial: true });
+      writeRecord(sessionId, state, { kind: "thought", sessionId, text: text6, partial: true });
     }, DEBOUNCE_MS);
   };
   return {
     recordPrompt(sessionId, message) {
       const state = getState(sessionId);
       flushBuffers(sessionId, state);
-      const text5 = typeof message === "string" ? message : JSON.stringify(message);
-      writeRecord(sessionId, state, { kind: "user-prompt", sessionId, text: text5 });
+      const text6 = typeof message === "string" ? message : JSON.stringify(message);
+      writeRecord(sessionId, state, { kind: "user-prompt", sessionId, text: text6 });
     },
     recordEvent(sessionId, evt) {
       const state = getState(sessionId);
@@ -863,7 +904,12 @@ function createTranscriptWriter(opts) {
             sessionId,
             toolCallId: evt.toolCallId,
             toolName: evt.toolName,
-            arguments: evt.arguments
+            arguments: evt.arguments,
+            // Carried through so a replay can tell an ENRICHMENT of an
+            // announced call from a genuine second call. Readers merge by
+            // toolCallId either way, but a record that silently drops the
+            // distinction can't be reasoned about after the fact.
+            ...evt.isUpdate ? { isUpdate: true } : {}
           });
           break;
         case "tool-result":
@@ -936,8 +982,8 @@ function createTranscriptWriter(opts) {
       if (!state) return Promise.resolve();
       flushBuffers(sessionId, state);
       states.delete(sessionId);
-      return new Promise((resolve13) => {
-        state.stream.end(() => resolve13());
+      return new Promise((resolve12) => {
+        state.stream.end(() => resolve12());
       });
     },
     closeAll() {
@@ -946,10 +992,24 @@ function createTranscriptWriter(opts) {
         const state = states.get(sessionId);
         if (!state) continue;
         flushBuffers(sessionId, state);
-        closings.push(new Promise((resolve13) => state.stream.end(() => resolve13())));
+        closings.push(new Promise((resolve12) => state.stream.end(() => resolve12())));
       }
       states.clear();
       return Promise.all(closings).then(() => void 0);
+    },
+    subscribe(sessionId, onRecord) {
+      let subs = listeners.get(sessionId);
+      if (!subs) {
+        subs = /* @__PURE__ */ new Set();
+        listeners.set(sessionId, subs);
+      }
+      subs.add(onRecord);
+      return () => {
+        const current = listeners.get(sessionId);
+        if (!current) return;
+        current.delete(onRecord);
+        if (current.size === 0) listeners.delete(sessionId);
+      };
     }
   };
 }
@@ -961,10 +1021,10 @@ var ROLE_ICON = {
   tool: "\u{1F527} Tool",
   system: "\u2699\uFE0F System"
 };
-function trunc(text5, n) {
-  if (text5.length <= n) return text5;
-  return text5.slice(0, n) + `
-\u2026 [${text5.length - n} chars truncated]`;
+function trunc(text6, n) {
+  if (text6.length <= n) return text6;
+  return text6.slice(0, n) + `
+\u2026 [${text6.length - n} chars truncated]`;
 }
 function renderMarkdown(session, opts = {}) {
   const { meta, messages } = session;
@@ -1065,9 +1125,9 @@ async function exportClaudeCodeSession(adapterSessionId, cwd) {
   let stream;
   try {
     stream = createReadStream(filePath, { encoding: "utf8" });
-    await new Promise((resolve13, reject) => {
+    await new Promise((resolve12, reject) => {
       stream.once("error", reject);
-      stream.once("open", resolve13);
+      stream.once("open", resolve12);
     });
   } catch (err) {
     const code = err.code;
@@ -1270,7 +1330,7 @@ async function exportHermesSession(adapterSessionId) {
 }
 async function defaultHermesRunner(adapterSessionId) {
   const { spawn: spawn6 } = await import('child_process');
-  return new Promise((resolve13, reject) => {
+  return new Promise((resolve12, reject) => {
     const chunks = [];
     const errChunks = [];
     const proc = spawn6(
@@ -1289,7 +1349,7 @@ async function defaultHermesRunner(adapterSessionId) {
           )
         );
       } else {
-        resolve13(Buffer.concat(chunks).toString("utf8"));
+        resolve12(Buffer.concat(chunks).toString("utf8"));
       }
     });
   });
@@ -1326,9 +1386,9 @@ async function exportDaemonEventsSession(sessionId, desc) {
   let stream;
   try {
     stream = createReadStream(filePath, { encoding: "utf8" });
-    await new Promise((resolve13, reject) => {
+    await new Promise((resolve12, reject) => {
       stream.once("error", reject);
-      stream.once("open", resolve13);
+      stream.once("open", resolve12);
     });
   } catch (err) {
     const code = err.code;
@@ -1398,10 +1458,10 @@ Either the session never drove an agent-cli turn, or it predates this feature.`
       case "tool-result": {
         flushAssistant();
         const name = rec.toolCallId ? toolNameById.get(rec.toolCallId) : void 0;
-        const text5 = typeof rec.result === "string" ? rec.result : JSON.stringify(rec.result ?? "");
+        const text6 = typeof rec.result === "string" ? rec.result : JSON.stringify(rec.result ?? "");
         messages.push({
           role: "tool",
-          text: rec.isError ? `[error] ${text5}` : text5,
+          text: rec.isError ? `[error] ${text6}` : text6,
           ...name ? { toolName: name } : {},
           ...tsOrUndefined !== void 0 ? { ts: tsOrUndefined } : {}
         });
@@ -1571,6 +1631,11 @@ async function loadWorkspacesConfig(path = DEFAULT_CONFIG_PATH()) {
 function findWorkspace(config, slug) {
   return config.workspaces.find((w) => w.slug === sanitizeSlug(slug));
 }
+function findWorkspaceByPath(config, dir) {
+  const resolved = resolve(dir);
+  const candidates = config.workspaces.filter((w) => resolved.startsWith(resolve(w.path) + "/") || resolved === resolve(w.path)).sort((a, b) => b.path.length - a.path.length);
+  return candidates[0];
+}
 function getActiveWorkspace(config) {
   if (!config.active) return config.workspaces[0];
   return findWorkspace(config, config.active) ?? config.workspaces[0];
@@ -1609,13 +1674,36 @@ function normalizeConfig(parsed) {
   return out;
 }
 var CONFIG_FILE_PATH = () => join(homedir(), ".agentproto", "config.json");
+function sanitizeAcpAgents(raw, target) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    console.warn(
+      `[runtime/config] ${target}: 'acpAgents' is not an object \u2014 ignoring`
+    );
+    return void 0;
+  }
+  const out = {};
+  for (const [slug, value] of Object.entries(raw)) {
+    if (value && typeof value === "object" && !Array.isArray(value) && typeof value.bin === "string" && value.bin.length > 0) {
+      out[slug] = value;
+    } else {
+      console.warn(
+        `[runtime/config] ${target}: acpAgents.${slug} is missing a string 'bin' \u2014 ignoring`
+      );
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
 async function loadConfig(path) {
   const target = CONFIG_FILE_PATH();
   try {
     const raw = await promises.readFile(target, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-      return parsed;
+      const cfg = parsed;
+      if (cfg.acpAgents !== void 0) {
+        cfg.acpAgents = sanitizeAcpAgents(cfg.acpAgents, target);
+      }
+      return cfg;
     }
     console.warn(
       `[runtime/config] ${target}: top-level value is not an object \u2014 ignoring`
@@ -1632,6 +1720,10 @@ async function loadConfig(path) {
   }
 }
 
+// src/providers-store.ts
+var providers_store_exports = {};
+__reExport(providers_store_exports, providers_store_star);
+
 // src/spawn-defaults.ts
 function resolveSpawnDefaults(defaults, adapterSlug, input) {
   const adapterDefaults = defaults?.adapters?.[adapterSlug];
@@ -1643,7 +1735,111 @@ function resolveSpawnDefaults(defaults, adapterSlug, input) {
   const skills = input.skills !== void 0 ? input.skills : Array.from(
     /* @__PURE__ */ new Set([...defaults?.skills ?? [], ...adapterDefaults?.skills ?? []])
   );
-  return { skills, options };
+  const requestedMode = input.auth?.mode ?? adapterDefaults?.auth?.mode;
+  const explicit = input.auth !== void 0 || adapterDefaults?.auth !== void 0;
+  const subscriptionCredential = input.auth?.token ?? adapterDefaults?.auth?.token;
+  const apiKeyCredential = input.auth?.apiKey ?? adapterDefaults?.auth?.apiKey;
+  const authProvider = input.auth?.provider ?? adapterDefaults?.auth?.provider;
+  return {
+    skills,
+    options,
+    auth: {
+      explicit,
+      ...requestedMode ? { requestedMode } : {},
+      ...subscriptionCredential !== void 0 ? { subscriptionCredential } : {},
+      ...apiKeyCredential !== void 0 ? { apiKeyCredential } : {},
+      ...authProvider ? { provider: authProvider } : {}
+    }
+  };
+}
+var CREDENTIAL_FINGERPRINT_PREFIXES = [
+  "sk-ant-oat",
+  "sk-ant-api",
+  "sk-ant-",
+  "sk-or-v1-",
+  "sk-or-",
+  "sk-proj-",
+  "sk-",
+  "gsk_",
+  "AIza"
+];
+function credentialFingerprint(mode, credential) {
+  const prefix = CREDENTIAL_FINGERPRINT_PREFIXES.find((p) => credential.startsWith(p));
+  const last4 = credential.slice(-4);
+  return prefix ? `${mode} \xB7 ${prefix}\u2026${last4}` : `${mode} \xB7 \u2026${last4}`;
+}
+var AuthResolutionError = class extends Error {
+  code = "unsupported_auth_mode";
+  constructor(message) {
+    super(message);
+    this.name = "AuthResolutionError";
+  }
+};
+function resolveAuthSpec(input) {
+  const provider = input.requestedProvider ?? input.descriptor.provider ?? (input.model ? getModelProvider(input.model) : void 0);
+  if (!provider) return void 0;
+  const sub = input.descriptor.authSubscription;
+  const supportsSub = sub !== void 0;
+  const enforce = input.descriptor.authEnforce ?? "when-configured";
+  const apiKeyEnv = (0, providers_store_exports.providerEnvVar)(provider);
+  const subCredAvailable = input.subscriptionCredential !== void 0;
+  const apiCredAvailable = input.apiKeyConfigCredential !== void 0 || input.apiKeyStoreCredential !== void 0;
+  let mode;
+  if (input.requestedMode) {
+    if (input.requestedMode === "subscription" && !supportsSub) {
+      throw new AuthResolutionError(
+        `auth mode "subscription" is not supported for provider "${provider}" (this adapter declares no authSubscription) \u2014 use api-key instead.`
+      );
+    }
+    mode = input.requestedMode;
+  } else {
+    const preference = supportsSub ? ["subscription", "api-key"] : ["api-key"];
+    mode = preference.find((m) => m === "subscription" ? subCredAvailable : apiCredAvailable) ?? preference[0];
+  }
+  let setEnv;
+  let credential;
+  let credentialSource;
+  if (mode === "subscription") {
+    setEnv = sub.setEnv;
+    credential = input.subscriptionCredential;
+    credentialSource = credential !== void 0 ? "explicit-config" : "none";
+  } else {
+    setEnv = apiKeyEnv;
+    if (input.apiKeyConfigCredential !== void 0) {
+      credential = input.apiKeyConfigCredential;
+      credentialSource = "explicit-config";
+    } else if (input.apiKeyStoreCredential !== void 0) {
+      credential = input.apiKeyStoreCredential;
+      credentialSource = "providers-store";
+    } else {
+      credential = void 0;
+      credentialSource = "none";
+    }
+  }
+  const credVars = /* @__PURE__ */ new Set([apiKeyEnv]);
+  if (sub) {
+    credVars.add(sub.setEnv);
+    for (const c of sub.conflictEnv ?? []) credVars.add(c);
+  }
+  credVars.delete(setEnv);
+  const unsetEnv = [...credVars];
+  if (mode === "subscription" && sub?.unsetEnvAdd) unsetEnv.push(...sub.unsetEnvAdd);
+  const spec = {
+    mode,
+    ...credential !== void 0 ? { credential } : {},
+    setEnv,
+    unsetEnv,
+    explicit: input.explicit,
+    enforce
+  };
+  const echo = {
+    provider,
+    authMode: mode,
+    credentialSource,
+    setEnv,
+    ...credential !== void 0 ? { fingerprint: credentialFingerprint(mode, credential) } : {}
+  };
+  return { spec, echo };
 }
 function normalizeSkillsOption(skills, options, declaredOptions) {
   if (skills.length === 0 || "skills" in options) return options;
@@ -1868,8 +2064,8 @@ var MAX_OUTPUT_LINES = 500;
 function extractPromptText(message) {
   if (typeof message === "string") return message;
   if (message && typeof message === "object" && "text" in message) {
-    const text5 = message.text;
-    if (typeof text5 === "string") return text5;
+    const text6 = message.text;
+    if (typeof text6 === "string") return text6;
   }
   return JSON.stringify(message);
 }
@@ -1928,6 +2124,16 @@ function createSandboxAgentSessionProxy(opts) {
 }
 
 // src/session-spawn.ts
+var SPAWN_CLAIM_WINDOW_MS = 3e4;
+var spawnClaimsByRegistry = /* @__PURE__ */ new WeakMap();
+function claimsFor(registry) {
+  let claims = spawnClaimsByRegistry.get(registry);
+  if (!claims) {
+    claims = /* @__PURE__ */ new Map();
+    spawnClaimsByRegistry.set(registry, claims);
+  }
+  return claims;
+}
 function cleanAgentLines(lines) {
   return lines.map((l) => l.replace(/\x1b\[[0-9;]*m/g, "")).filter((l) => {
     const t = l.trim();
@@ -1947,18 +2153,26 @@ async function spawnAgentSession(deps2, input) {
     resolveSandboxProvider: resolveSandboxProvider2
   } = deps2;
   let cwd = input.cwd;
-  let resolvedSlug = input.workspaceSlug ?? "default";
-  if (!cwd) {
+  let resolvedSlug = input.workspaceSlug;
+  if (!cwd || !resolvedSlug) {
     try {
       const config = await loadWorkspacesConfig();
-      const ws = input.workspaceSlug ? findWorkspace(config, input.workspaceSlug) : getActiveWorkspace(config);
-      if (ws) {
-        cwd = ws.path;
-        resolvedSlug = ws.slug;
+      if (!cwd) {
+        const ws = input.workspaceSlug ? findWorkspace(config, input.workspaceSlug) : getActiveWorkspace(config);
+        if (ws) {
+          cwd = ws.path;
+          resolvedSlug = ws.slug;
+        }
+      } else if (!resolvedSlug) {
+        const ws = findWorkspaceByPath(config, cwd);
+        if (ws) {
+          resolvedSlug = ws.slug;
+        }
       }
     } catch {
     }
   }
+  resolvedSlug = resolvedSlug ?? "default";
   if (!cwd) {
     return {
       ok: false,
@@ -2078,8 +2292,43 @@ async function spawnAgentSession(deps2, input) {
   }
   const spawnDefaults = resolveSpawnDefaults(configDefaults, input.adapter, {
     skills: input.skills,
-    options: input.options
+    options: input.options,
+    auth: input.auth
   });
+  let authSpec;
+  let authEcho;
+  if (resolved && input.sandbox === void 0 && resolved.authDescriptor) {
+    const authModel = input.model ?? resolved.defaultModel;
+    const pinnedProvider = spawnDefaults.auth.provider;
+    const resolvedProvider = pinnedProvider ?? resolved.authDescriptor.provider ?? (authModel ? getModelProvider(authModel) : void 0);
+    const apiKeyStoreCredential = resolvedProvider && spawnDefaults.auth.explicit && spawnDefaults.auth.apiKeyCredential === void 0 ? await (0, providers_store_exports.getProviderKey)(resolvedProvider) : void 0;
+    try {
+      const result = resolveAuthSpec({
+        descriptor: resolved.authDescriptor,
+        ...authModel ? { model: authModel } : {},
+        ...pinnedProvider ? { requestedProvider: pinnedProvider } : {},
+        ...spawnDefaults.auth.requestedMode ? { requestedMode: spawnDefaults.auth.requestedMode } : {},
+        explicit: spawnDefaults.auth.explicit,
+        ...spawnDefaults.auth.subscriptionCredential !== void 0 ? { subscriptionCredential: spawnDefaults.auth.subscriptionCredential } : {},
+        ...spawnDefaults.auth.apiKeyCredential !== void 0 ? { apiKeyConfigCredential: spawnDefaults.auth.apiKeyCredential } : {},
+        ...apiKeyStoreCredential !== void 0 ? { apiKeyStoreCredential } : {}
+      });
+      if (result) {
+        authSpec = result.spec;
+        authEcho = result.echo;
+      }
+    } catch (err) {
+      if (err instanceof AuthResolutionError) {
+        return {
+          ok: false,
+          code: "unsupported_auth_mode",
+          message: `agent_start: ${err.message}`,
+          details: { adapter: input.adapter, provider: resolvedProvider }
+        };
+      }
+      throw err;
+    }
+  }
   const effectiveOptions = normalizeSkillsOption(
     spawnDefaults.skills,
     spawnDefaults.options,
@@ -2088,6 +2337,39 @@ async function spawnAgentSession(deps2, input) {
   const effectivePrompt = input.prompt ? `${composeRoleContext(role, input.promptAppend, roleRegistry)}
 
 ${input.prompt}` : input.prompt;
+  let settleClaim;
+  if (input.idempotencyKey) {
+    const claims = claimsFor(registry);
+    const key = `${input.adapter}${cwd}${input.idempotencyKey}`;
+    const now = Date.now();
+    for (const [k, claim] of claims) {
+      if (claim.resolvedAt !== void 0 && now - claim.resolvedAt > SPAWN_CLAIM_WINDOW_MS) {
+        claims.delete(k);
+      }
+    }
+    const existing = claims.get(key);
+    if (existing) {
+      const result = await existing.result;
+      return result.ok ? { ...result, deduped: true } : result;
+    }
+    let resolveClaim;
+    claims.set(key, { result: new Promise((resolve12) => {
+      resolveClaim = resolve12;
+    }) });
+    settleClaim = (result) => {
+      if (result.ok) {
+        const claim = claims.get(key);
+        if (claim) claim.resolvedAt = Date.now();
+      } else {
+        claims.delete(key);
+      }
+      resolveClaim(result);
+    };
+  }
+  const finish = (result) => {
+    settleClaim?.(result);
+    return result;
+  };
   try {
     const resolvedMcpServers = await resolveMcpCredentialHeaders(mcpServers);
     let liveSessionId;
@@ -2128,7 +2410,9 @@ ${input.prompt}` : input.prompt;
         ...Object.keys(effectiveOptions).length > 0 ? { options: effectiveOptions } : {},
         ...input.model ? { model: input.model } : {},
         ...input.effort ? { effort: input.effort } : {},
+        ...authSpec ? { auth: authSpec } : {},
         ...resolvedMcpServers ? { mcpServers: resolvedMcpServers } : {},
+        ...input.permissionHold ? { permissionHold: true } : {},
         onActivity: () => {
           if (liveSessionId) registry.pulseActivity(liveSessionId);
         }
@@ -2157,8 +2441,28 @@ ${input.prompt}` : input.prompt;
       ...input.maxCostUsd !== void 0 ? { maxCostUsd: input.maxCostUsd } : {},
       ...readUsage ? { readUsage } : {},
       ...input.trace !== void 0 ? { trace: input.trace } : {},
+      // Verifiability: record the OBSERVABLE echo — resolved provider, mode,
+      // credential source, the env var actually set, and a non-secret
+      // fingerprint (never the credential). DECISION 9③/10②. Recorded only
+      // when a credential actually resolved (fingerprint present); a
+      // configured-but-missing-credential spawn fails fast in the driver
+      // before a descriptor exists. Absent for sandbox spawns (the box
+      // resolves its own credential, so a host-side echo would misrepresent
+      // it — `authEcho` is already left undefined for those above).
+      ...authEcho?.fingerprint ? {
+        auth: {
+          mode: authEcho.authMode,
+          fingerprint: authEcho.fingerprint,
+          provider: authEcho.provider,
+          credentialSource: authEcho.credentialSource,
+          setEnv: authEcho.setEnv
+        }
+      } : {},
       ...sandboxId ? { remote: true, sandboxId } : {},
-      ...sandboxTeardown ? { sandboxTeardown } : {}
+      ...sandboxTeardown ? { sandboxTeardown } : {},
+      // Hold mode is a local-driver capability; a sandbox spawn proxies to the
+      // box's own daemon, which handles permissions there.
+      ...input.permissionHold && input.sandbox === void 0 ? { permissionHold: true } : {}
     });
     liveSessionId = desc.id;
     bindOrchestratorLifecycle?.(desc.id);
@@ -2174,28 +2478,28 @@ ${input.prompt}` : input.prompt;
       if (waitUnsub) waitUnsub();
       const waitTail = waitLines.slice(-80);
       const output = cleanAgentLines(waitTail);
-      return { ok: true, descriptor: desc, output };
+      return finish({ ok: true, descriptor: desc, output });
     }
-    return { ok: true, descriptor: desc };
+    return finish({ ok: true, descriptor: desc });
   } catch (err) {
-    return {
+    return finish({
       ok: false,
       code: "agent_spawn_failed",
       message: `agent_start: spawn failed \u2014 ${err instanceof Error ? err.message : String(err)}`
-    };
+    });
   }
 }
 async function resolveMcpCredentialHeaders(mcpServers) {
   if (!mcpServers || mcpServers.length === 0) return mcpServers;
-  const { resolveMcpCredentialHeaders: resolve13 } = getMcpCredentialDeps();
-  if (!resolve13) return mcpServers;
+  const { resolveMcpCredentialHeaders: resolve12 } = getMcpCredentialDeps();
+  if (!resolve12) return mcpServers;
   return Promise.all(
     mcpServers.map(async (entry) => {
       const ref = entry.credentialRef;
       if (!ref) return entry;
       let brokered;
       try {
-        brokered = await resolve13({ credentialRef: ref });
+        brokered = await resolve12({ credentialRef: ref });
       } catch (err) {
         console.warn(
           `[agent_start] credentialRef resolution failed for "${entry.name}" (${ref}): ${err instanceof Error ? err.message : String(err)}`
@@ -2294,10 +2598,10 @@ async function bootSandboxAgentSession(opts) {
   };
 }
 async function resolveSandboxSecret(slug) {
-  const { resolveSandboxSecret: resolve13 } = getMcpCredentialDeps();
-  if (!resolve13) return null;
+  const { resolveSandboxSecret: resolve12 } = getMcpCredentialDeps();
+  if (!resolve12) return null;
   try {
-    return await resolve13(slug);
+    return await resolve12(slug);
   } catch (err) {
     console.warn(
       `[agent_start] sandbox secret resolution failed for "${slug}": ${err instanceof Error ? err.message : String(err)}`
@@ -2322,6 +2626,24 @@ var mcpPositiveNumber = z.preprocess(
   (v) => typeof v === "string" && v.trim() !== "" ? Number(v) : v,
   z.number().positive()
 );
+var sessionIdField = z.string().optional().describe(
+  "Session id (as returned by agent_start). Accepts either `sessionId` or its alias `id` \u2014 pass whichever you have."
+);
+var sessionIdAliasField = z.string().optional().describe("Alias for `sessionId` \u2014 the `id` field returned by agent_start.");
+function resolveSessionIdArg(input) {
+  return input.sessionId ?? input.id;
+}
+function missingSessionIdError(tool) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: `${tool}: missing session id \u2014 pass \`sessionId\` (or its alias \`id\`).`
+      }
+    ],
+    isError: true
+  };
+}
 function registerAgentTools(server, opts) {
   const {
     registry,
@@ -2356,6 +2678,12 @@ function registerAgentTools(server, opts) {
       mode: z.string().optional().describe(
         "Manifest-declared mode id (AIP-45 `modes`) applied at spawn time, BEFORE the child process starts \u2014 e.g. claude-code's 'plan' (read-only: reasons and proposes but does not edit or run commands), 'accept-edits', 'bypass-permissions'; codex's 'read-only' / 'full-access'; mastracode/opencode's 'plan' / 'build'. Adapters that don't declare `modes` (e.g. hermes) reject ANY value here \u2014 only pass this for adapters known to support it. Omit for the adapter's normal interactive mode."
       ),
+      idempotencyKey: z.string().min(1).optional().describe(
+        "Caller-declared 'this is the same logical spawn' token. A retried agent_start call (e.g. after a slow/lost response) that repeats the same `idempotencyKey` for the same `adapter`+`cwd` within ~30s of a successful spawn gets that SAME session's descriptor back instead of forking a second process \u2014 set `deduped: true` on the response so you can tell. Omit to spawn unconditionally (today's behaviour, and still required for deliberate concurrent spawns into the same cwd \u2014 this field can't distinguish a retry from an intentional duplicate spawn, only your own declared key can). Recommended for any caller that might retry a spawn it can't otherwise confirm succeeded."
+      ),
+      permissionHold: mcpBool.optional().describe(
+        "Start the session in permission-hold mode: every ACP permission request the agent raises (Write, Bash, \u2026) is SURFACED and HELD in the cross-session inbox (`permissions_list` / `permissions_respond`) instead of auto-answered, and the agent blocks until a human/orchestrator approves or denies it. Default false = today's auto-answer behaviour. ACP adapters only; others ignore it."
+      ),
       options: jsonTolerant(
         z.record(z.string(), z.union([z.boolean(), z.number(), z.string()]))
       ).optional().describe(
@@ -2370,6 +2698,15 @@ function registerAgentTools(server, opts) {
       effort: z.string().optional().describe(
         "Reasoning effort level (e.g. 'low', 'medium', 'high', 'xhigh', 'max', 'ultracode'). IMPORTANT: effort is calibrated per model \u2014 the same label maps to different compute budgets across models, and defaults differ by model (Sonnet 4.6 / Opus 4.8 default 'high'; Opus 4.7 default 'xhigh'). 'max' and 'ultracode' are session-only. Omit to keep the model's own default."
       ),
+      auth: jsonTolerant(
+        z.object({
+          mode: z.enum(["subscription", "api-key"]).optional(),
+          token: z.string().optional(),
+          apiKey: z.string().optional()
+        })
+      ).optional().describe(
+        "Deterministic billing-auth mode + EXPLICIT credential for adapters that declare it (today: claude-code). EXPLICIT credential selection, not scrub-by-absence: `mode` picks 'subscription' (default) or 'api-key'; `token`/`apiKey` (matching the resolved mode) is the secret VALUE, merged against `~/.agentproto/config.json`'s `defaults.adapters.claude-code.auth` (this field's `mode` wins; the credential for the resolved mode wins over the matching config field). For claude-code, 'subscription' SETS CLAUDE_CODE_OAUTH_TOKEN to `token` (a bearer token minted via `claude setup-token` \u2014 bills the Max/Pro subscription, not API credits) and DELETES ANTHROPIC_API_KEY + the cloud-provider redirect toggles + ANTHROPIC_BASE_URL. 'api-key' SETS ANTHROPIC_API_KEY to `apiKey` and DELETES ANTHROPIC_AUTH_TOKEN \u2014 the deliberate 'bill the API' choice. FAILS FAST (refuses the spawn, no fallback) when the resolved mode has no credential configured anywhere. The secret is never logged or echoed back \u2014 only a fingerprint appears on the session descriptor / `agent_sessions_list`. Adapters that don't declare this vocabulary ignore this field entirely."
+      ),
       mcpServers: jsonTolerant(
         z.array(
           z.object({
@@ -2460,18 +2797,22 @@ function registerAgentTools(server, opts) {
         input
       );
       if (result.ok) {
-        const body = result.output ? { ...result.descriptor, output: result.output } : result.descriptor;
+        const body = {
+          ...result.descriptor,
+          ...result.output ? { output: result.output } : {},
+          ...result.deduped ? { deduped: true } : {}
+        };
         return {
           content: [{ type: "text", text: JSON.stringify(body, null, 2) }]
         };
       }
-      const text5 = result.code === "orchestrator_max_depth_exceeded" || result.code === "orchestrator_child_quota_exceeded" || result.code === "role_spawn_denied" ? JSON.stringify(
+      const text6 = result.code === "orchestrator_max_depth_exceeded" || result.code === "orchestrator_child_quota_exceeded" || result.code === "role_spawn_denied" ? JSON.stringify(
         { error: result.code, message: result.message, ...result.details },
         null,
         2
       ) : result.message;
       return {
-        content: [{ type: "text", text: text5 }],
+        content: [{ type: "text", text: text6 }],
         isError: true
       };
     }
@@ -2480,15 +2821,18 @@ function registerAgentTools(server, opts) {
     "agent_prompt",
     "Send a follow-up prompt to a live agent session \u2014 multi-turn continuity without re-spawning. The session id comes from `agent_start` (or `agent_sessions_list`). Returns immediately; tail output via `agent_output` or the SSE /sessions/:id/stream endpoint. By default, a session mid-turn rejects the new prompt \u2014 pass `interrupt: true` to cancel the in-flight turn and redirect the SAME session onto this prompt instead, without losing its context (unlike `agent_kill`, which ends the session entirely). `interrupt` is a no-op on an already-idle session.",
     {
-      sessionId: z.string().describe("Session id returned by agent_start."),
+      sessionId: sessionIdField,
+      id: sessionIdAliasField,
       prompt: z.string().min(1).describe("The next user turn (plain text)."),
       interrupt: z.boolean().optional().describe(
         "When true and the session is mid-turn, cancel the in-flight turn and deliver this prompt on the same session instead of rejecting. No-op when the session is already idle. Default false (mid-turn rejects, as today)."
       )
     },
     async (input) => {
+      const sessionId = resolveSessionIdArg(input);
+      if (!sessionId) return missingSessionIdError("agent_prompt");
       try {
-        await registry.enqueuePrompt(input.sessionId, input.prompt, {
+        await registry.enqueuePrompt(sessionId, input.prompt, {
           interrupt: input.interrupt
         });
         return {
@@ -2496,7 +2840,7 @@ function registerAgentTools(server, opts) {
             {
               type: "text",
               text: JSON.stringify(
-                { ok: true, sessionId: input.sessionId, queued: true },
+                { ok: true, sessionId, queued: true },
                 null,
                 2
               )
@@ -2520,25 +2864,28 @@ function registerAgentTools(server, opts) {
     "agent_output",
     "Tail the recent output of a session. Returns the last N lines of the ring buffer (stdout + stderr inter-leaved, newest last). Use this to read an agent's reply after `agent_prompt`.",
     {
-      sessionId: z.string().describe("Session id."),
+      sessionId: sessionIdField,
+      id: sessionIdAliasField,
       lastN: z.number().int().min(1).max(500).optional().describe("Max lines to return. Default 80, max 500."),
       clean: mcpBool.optional().describe(
         "Strip ANSI codes and drop framing/decoration lines, returning human-readable text."
       )
     },
     async (input) => {
-      const desc = registry.get(input.sessionId);
+      const sessionId = resolveSessionIdArg(input);
+      if (!sessionId) return missingSessionIdError("agent_output");
+      const desc = registry.get(sessionId);
       if (!desc) {
         return {
           content: [
-            { type: "text", text: `agent_output: no session "${input.sessionId}"` }
+            { type: "text", text: `agent_output: no session "${sessionId}"` }
           ],
           isError: true
         };
       }
       const limit = input.lastN ?? 80;
       const lines = [];
-      const unsub = registry.attach(input.sessionId, (line, _stream) => {
+      const unsub = registry.attach(sessionId, (line, _stream) => {
         lines.push(line);
       });
       if (unsub) unsub();
@@ -2555,7 +2902,7 @@ function registerAgentTools(server, opts) {
             type: "text",
             text: JSON.stringify(
               {
-                sessionId: input.sessionId,
+                sessionId,
                 status: desc.status,
                 lastOutputAt: desc.lastOutputAt,
                 // Distinct liveness heartbeat: advances on ANY adapter-process
@@ -2585,15 +2932,18 @@ function registerAgentTools(server, opts) {
     "agent_kill",
     "Stop a session \u2014 SIGTERM the underlying child + close the agent protocol session. Use to free resources after the operator is done, or when a session is wedged.",
     {
-      sessionId: z.string().describe("Session id.")
+      sessionId: sessionIdField,
+      id: sessionIdAliasField
     },
     async (input) => {
+      const sessionId = resolveSessionIdArg(input);
+      if (!sessionId) return missingSessionIdError("agent_kill");
       if (callerScope) {
         const subtree = collectSubtree(
           callerScope.ownerSessionId,
           registry.list()
         );
-        if (!subtree.has(input.sessionId)) {
+        if (!subtree.has(sessionId)) {
           return {
             content: [
               {
@@ -2601,9 +2951,9 @@ function registerAgentTools(server, opts) {
                 text: JSON.stringify(
                   {
                     error: "orchestrator_session_out_of_scope",
-                    message: `agent_kill: session "${input.sessionId}" is not in your subtree \u2014 a scoped orchestrator can only kill sessions it (transitively) spawned. No action taken.`,
+                    message: `agent_kill: session "${sessionId}" is not in your subtree \u2014 a scoped orchestrator can only kill sessions it (transitively) spawned. No action taken.`,
                     ok: false,
-                    sessionId: input.sessionId
+                    sessionId
                   },
                   null,
                   2
@@ -2614,12 +2964,12 @@ function registerAgentTools(server, opts) {
           };
         }
       }
-      const ok = registry.kill(input.sessionId);
+      const ok = registry.kill(sessionId);
       return {
         content: [
           {
             type: "text",
-            text: JSON.stringify({ ok, sessionId: input.sessionId }, null, 2)
+            text: JSON.stringify({ ok, sessionId }, null, 2)
           }
         ]
       };
@@ -2729,9 +3079,10 @@ function registerExportSessionTool(server, ops) {
     "agent_export",
     "Export a clean, human-readable transcript of an agent session. Prefers the source the adapter already persists (claude-code: JSONL in ~/.claude/projects/; hermes: state.db in ~/.hermes/), falling back to agentproto's own daemon-captured events.jsonl for every other adapter (or once the native store is unreadable). Returns markdown (default) or JSON. Works on stopped and running sessions alike. Use after a long agent run to review the full conversation without the ANSI noise of the ring buffer.",
     {
-      sessionId: z.string().describe(
-        "agentproto session id (sess_xxx), adapter-native id, or session name."
+      sessionId: z.string().optional().describe(
+        "agentproto session id (sess_xxx), adapter-native id, or session name. Accepts either `sessionId` or its alias `id`."
       ),
+      id: sessionIdAliasField,
       adapter: z.string().optional().describe(
         "Override adapter slug (e.g. 'claude-code', 'hermes') when the session is not in the registry. Required when passing a raw adapter-native id."
       ),
@@ -2746,8 +3097,10 @@ function registerExportSessionTool(server, ops) {
       )
     },
     async (input) => {
+      const sessionId = resolveSessionIdArg(input);
+      if (!sessionId) return missingSessionIdError("agent_export");
       const result = await doExport({
-        sessionId: input.sessionId,
+        sessionId,
         registry: ops.registry,
         ...input.adapter ? { adapter: input.adapter } : {},
         ...input.cwd ? { cwd: input.cwd } : {},
@@ -3138,8 +3491,6 @@ function tokenizeCommand(s) {
   if (buf) out.push(buf);
   return out;
 }
-
-// src/session-restart-core.ts
 async function restartAgentSession(registry, resolveAgentAdapter, prev, opts = {}) {
   const augmented = opts.forceAgentResume ? prev : await augmentWithFsResume(prev);
   const strategy = opts.forceAgentResume ? { kind: "agent", resumeSessionId: prev.adapterSessionId } : decideRestartStrategy(augmented);
@@ -3161,6 +3512,33 @@ async function restartAgentSession(registry, resolveAgentAdapter, prev, opts = {
   let cwd = prev.cwd;
   if (!cwd) console.warn(`[restartAgentSession] no cwd on prior descriptor ${prev.id} \u2014 falling back to daemon's cwd ${process.cwd()}`);
   cwd ??= process.cwd();
+  let authSpec;
+  let authEcho;
+  if (resolved.authDescriptor) {
+    const configDefaults = opts.loadDefaultsConfig ? await opts.loadDefaultsConfig() : (await loadConfig()).defaults;
+    const explicitAuthInput = prev.auth ? { mode: prev.auth.mode } : void 0;
+    const spawnDefaults = resolveSpawnDefaults(configDefaults, adapterSlug, {
+      auth: explicitAuthInput
+    });
+    const authModel = prev.model ?? resolved.defaultModel;
+    const pinnedProvider = spawnDefaults.auth.provider;
+    const resolvedProvider = pinnedProvider ?? resolved.authDescriptor.provider ?? (authModel ? getModelProvider(authModel) : void 0);
+    const apiKeyStoreCredential = resolvedProvider && spawnDefaults.auth.explicit && spawnDefaults.auth.apiKeyCredential === void 0 ? await (0, providers_store_exports.getProviderKey)(resolvedProvider) : void 0;
+    const result = resolveAuthSpec({
+      descriptor: resolved.authDescriptor,
+      ...authModel ? { model: authModel } : {},
+      ...pinnedProvider ? { requestedProvider: pinnedProvider } : {},
+      ...spawnDefaults.auth.requestedMode ? { requestedMode: spawnDefaults.auth.requestedMode } : {},
+      explicit: spawnDefaults.auth.explicit,
+      ...spawnDefaults.auth.subscriptionCredential !== void 0 ? { subscriptionCredential: spawnDefaults.auth.subscriptionCredential } : {},
+      ...spawnDefaults.auth.apiKeyCredential !== void 0 ? { apiKeyConfigCredential: spawnDefaults.auth.apiKeyCredential } : {},
+      ...apiKeyStoreCredential !== void 0 ? { apiKeyStoreCredential } : {}
+    });
+    if (result) {
+      authSpec = result.spec;
+      authEcho = result.echo;
+    }
+  }
   const spawnWithResume = async (resumeSessionId) => {
     let liveSessionId;
     const agentSession = await resolved.startSession({
@@ -3168,6 +3546,7 @@ async function restartAgentSession(registry, resolveAgentAdapter, prev, opts = {
       ...resumeSessionId ? { resumeSessionId } : {},
       ...prev.model ? { model: prev.model } : {},
       ...prev.mcpServers ? { mcpServers: prev.mcpServers } : {},
+      ...authSpec ? { auth: authSpec } : {},
       onActivity: () => {
         if (liveSessionId) registry.pulseActivity(liveSessionId);
       }
@@ -3180,7 +3559,19 @@ async function restartAgentSession(registry, resolveAgentAdapter, prev, opts = {
       ...prev.label ? { label: prev.label } : {},
       ...prev.mcpServers ? { mcpServers: prev.mcpServers } : {},
       ...prev.model ? { model: prev.model } : {},
-      ...resolved.commandPreview ? { commandPreview: resolved.commandPreview } : {}
+      ...resolved.commandPreview ? { commandPreview: resolved.commandPreview } : {},
+      // Verifiability echo (never the credential) — see the auth
+      // resolution block above. Absent when no credential resolved,
+      // same as session-spawn.ts.
+      ...authEcho?.fingerprint ? {
+        auth: {
+          mode: authEcho.authMode,
+          fingerprint: authEcho.fingerprint,
+          provider: authEcho.provider,
+          credentialSource: authEcho.credentialSource,
+          setEnv: authEcho.setEnv
+        }
+      } : {}
     });
     liveSessionId = desc2.id;
     return desc2;
@@ -3274,24 +3665,30 @@ function normalize3(parsed) {
   }
   return { version: IMPORTED_MCPS_VERSION, imports };
 }
+function plausibleContextUsed(contextSize, contextUsed) {
+  if (contextUsed === void 0) return void 0;
+  if (contextSize !== void 0 && contextUsed > contextSize) return void 0;
+  return contextUsed;
+}
 var defaultResolver = (model) => resolvePricing(model);
 function tokenCost(tokens, pricePer1M) {
   return tokens === void 0 ? 0 : tokens * pricePer1M / 1e6;
 }
-function deriveSessionUsage(input, resolve13 = defaultResolver) {
+function deriveSessionUsage(input, resolve12 = defaultResolver) {
+  const contextUsed = plausibleContextUsed(input.contextSize, input.contextUsed);
   const base = {
     ...input.model !== void 0 ? { model: input.model } : {},
     ...input.tokensIn !== void 0 ? { tokensIn: input.tokensIn } : {},
     ...input.tokensOut !== void 0 ? { tokensOut: input.tokensOut } : {},
     ...input.contextSize !== void 0 ? { contextSize: input.contextSize } : {},
-    ...input.contextUsed !== void 0 ? { contextUsed: input.contextUsed } : {}
+    ...contextUsed !== void 0 ? { contextUsed } : {}
   };
   if (input.adapterCostUsd !== void 0) {
     return { ...base, costUsd: input.adapterCostUsd, source: "adapter" };
   }
   const hasTokens = input.tokensIn !== void 0 || input.tokensOut !== void 0;
   if (hasTokens) {
-    const pricing = input.model !== void 0 ? resolve13(input.model) : void 0;
+    const pricing = input.model !== void 0 ? resolve12(input.model) : void 0;
     if (!pricing) {
       return { ...base, source: "no-pricing" };
     }
@@ -3301,13 +3698,14 @@ function deriveSessionUsage(input, resolve13 = defaultResolver) {
   return { ...base, source: "none" };
 }
 function projectSessionUsage(desc) {
+  const contextUsed = plausibleContextUsed(desc.contextSize, desc.contextUsed);
   return {
     ...desc.model !== void 0 ? { model: desc.model } : {},
     ...desc.costUsd !== void 0 ? { costUsd: desc.costUsd } : {},
     ...desc.tokensIn !== void 0 ? { tokensIn: desc.tokensIn } : {},
     ...desc.tokensOut !== void 0 ? { tokensOut: desc.tokensOut } : {},
     ...desc.contextSize !== void 0 ? { contextSize: desc.contextSize } : {},
-    ...desc.contextUsed !== void 0 ? { contextUsed: desc.contextUsed } : {},
+    ...contextUsed !== void 0 ? { contextUsed } : {},
     source: desc.usageSource ?? "none"
   };
 }
@@ -3995,6 +4393,13 @@ function registerSessionTools(rawServer, opts) {
           }
         } catch {
         }
+      } else if (!input.workspaceSlug) {
+        try {
+          const config = await loadWorkspacesConfig();
+          const ws = findWorkspaceByPath(config, cwd);
+          if (ws) resolvedSlug = ws.slug;
+        } catch {
+        }
       }
       if (!cwd) {
         return {
@@ -4184,8 +4589,8 @@ var okResult = (r) => ({
   content: [{ type: "text", text: JSON.stringify(r, null, 2) }],
   structuredContent: r
 });
-var errResult = (text5) => ({
-  content: [{ type: "text", text: text5 }],
+var errResult = (text6) => ({
+  content: [{ type: "text", text: text6 }],
   isError: true
 });
 function registerBrowserTools(server, opts) {
@@ -6850,8 +7255,8 @@ function expandTemplate(template, when) {
   const date = when.toISOString().slice(0, 10);
   return template.replace(/\{date\}/g, date);
 }
-function preview(text5, max = 120) {
-  const flat = text5.replace(/\s+/g, " ").trim();
+function preview(text6, max = 120) {
+  const flat = text6.replace(/\s+/g, " ").trim();
   return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
 }
 function writeCommandLogEntry(sessionId, entry, baseDir) {
@@ -6974,8 +7379,8 @@ function createTerminalTranscriptWriter(opts) {
       const stream = streams.get(sessionId);
       if (!stream) return Promise.resolve();
       streams.delete(sessionId);
-      return new Promise((resolve13) => {
-        stream.end(() => resolve13());
+      return new Promise((resolve12) => {
+        stream.end(() => resolve12());
       });
     },
     closeAll() {
@@ -6984,8 +7389,8 @@ function createTerminalTranscriptWriter(opts) {
         const stream = streams.get(sessionId);
         if (!stream) continue;
         closings.push(
-          new Promise((resolve13) => {
-            stream.end(() => resolve13());
+          new Promise((resolve12) => {
+            stream.end(() => resolve12());
           })
         );
       }
@@ -7007,6 +7412,35 @@ function normalizeAgentPromptOptions(raw) {
   }).filter((s) => typeof s === "string");
   return labels.length > 0 ? labels : void 0;
 }
+function normalizePermissionOptions(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const o of raw) {
+    if (!o || typeof o !== "object") continue;
+    const r = o;
+    if (typeof r.optionId !== "string") continue;
+    out.push({
+      optionId: r.optionId,
+      ...typeof r.name === "string" ? { name: r.name } : {},
+      ...typeof r.kind === "string" ? { kind: r.kind } : {}
+    });
+  }
+  return out;
+}
+function selectPermissionOptionId(options, input) {
+  if (input.optionId) {
+    return options.some((o) => o.optionId === input.optionId) ? { optionId: input.optionId } : null;
+  }
+  const kindStarts = (prefix) => options.find((o) => typeof o.kind === "string" && o.kind.startsWith(prefix));
+  if (input.decision === "approve") {
+    const chosen = (input.scope === "always" ? options.find((o) => o.kind === "allow_always") : options.find((o) => o.kind === "allow_once")) ?? kindStarts("allow") ?? // Some agents label the grant "proceed"/"yes" without an `allow_` kind —
+    // fall back to the first non-reject option before giving up.
+    options.find((o) => !(typeof o.kind === "string" && o.kind.startsWith("reject")));
+    return chosen ? { optionId: chosen.optionId } : null;
+  }
+  const reject = options.find((o) => o.kind === "reject_once") ?? kindStarts("reject") ?? kindStarts("deny");
+  return reject ? { optionId: reject.optionId } : { cancelled: true };
+}
 function classifyBlockedOn(toolName) {
   if (!toolName) return void 0;
   const n = toolName.toLowerCase();
@@ -7014,6 +7448,10 @@ function classifyBlockedOn(toolName) {
   if (/^(command_execute|terminal_start)$|bash|terminal|command/.test(n)) return "command";
   return void 0;
 }
+function releaseBlockedOn(desc) {
+  desc.blockedOn = void 0;
+  desc.pendingToolCallId = void 0;
+}
 function isAbortError(err) {
   if (typeof err !== "object" || err === null) return false;
   const name = "name" in err ? err.name : void 0;
@@ -7095,11 +7533,12 @@ function createSessionsRegistry(opts) {
   const resumeAgent = opts?.resumeAgent;
   const sessionEvents = opts?.sessionEvents;
   const sessions = /* @__PURE__ */ new Map();
+  const pendingPermissions = /* @__PURE__ */ new Map();
   let persistTimer = null;
   let nextSubId = 1;
   let shutdownDone = false;
   if (persist) {
-    loadHistorySnapshot(persistPath, sessions);
+    loadHistorySnapshot(persistPath, sessions, sessionEvents);
   }
   const onProcessExit = () => {
     shutdownImpl();
@@ -7108,7 +7547,9 @@ function createSessionsRegistry(opts) {
     process.on("exit", onProcessExit);
   }
   const emitExited = (rt) => {
-    if (!sessionEvents || rt.exitedEmitted) return;
+    if (rt.exitedEmitted) return;
+    cancelPendingPermissionsForSession(rt);
+    if (!sessionEvents) return;
     rt.exitedEmitted = true;
     sessionEvents.emit({
       type: "session:exited",
@@ -7116,9 +7557,72 @@ function createSessionsRegistry(opts) {
       exitCode: rt.desc.exitCode,
       status: rt.desc.status,
       label: rt.desc.label,
-      ts: (/* @__PURE__ */ new Date()).toISOString()
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      ...rt.desc.endedReason ? { reason: rt.desc.endedReason } : {}
     });
   };
+  const refreshAwaitingPermission = (rt) => {
+    let has = false;
+    for (const p of pendingPermissions.values()) {
+      if (p.sessionId === rt.desc.id) {
+        has = true;
+        break;
+      }
+    }
+    if (has) rt.desc.awaitingPermission = true;
+    else delete rt.desc.awaitingPermission;
+  };
+  const registerPendingPermission = (rt, evt) => {
+    const id = evt.toolCallId;
+    if (!id) return;
+    const options = normalizePermissionOptions(evt.options);
+    const toolName = evt.toolName;
+    const text6 = evt.text ?? (toolName ? `Allow "${toolName}"?` : "The agent is requesting permission.");
+    const pending = {
+      id,
+      sessionId: rt.desc.id,
+      toolCallId: id,
+      ...toolName ? { toolName } : {},
+      text: text6,
+      options,
+      requestedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    pendingPermissions.set(id, pending);
+    rt.desc.awaitingPermission = true;
+    schedulePersist();
+    if (sessionEvents) {
+      sessionEvents.emit({
+        type: "session:permission-request",
+        sessionId: rt.desc.id,
+        permissionId: id,
+        ...toolName ? { toolName } : {},
+        text: text6,
+        ...rt.desc.label ? { label: rt.desc.label } : {},
+        ts: pending.requestedAt
+      });
+    }
+  };
+  const cancelPendingPermissionsForSession = (rt) => {
+    for (const [id, pending] of pendingPermissions) {
+      if (pending.sessionId !== rt.desc.id) continue;
+      pendingPermissions.delete(id);
+      try {
+        void rt.agentSession?.respondPermission?.(id, { cancelled: true });
+      } catch {
+      }
+      if (sessionEvents) {
+        sessionEvents.emit({
+          type: "session:permission-resolved",
+          sessionId: rt.desc.id,
+          permissionId: id,
+          decision: "cancelled",
+          ...rt.desc.label ? { label: rt.desc.label } : {},
+          ts: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+    }
+    delete rt.desc.awaitingPermission;
+  };
   const schedulePersist = () => {
     if (!persist) return;
     if (persistTimer) clearTimeout(persistTimer);
@@ -7198,6 +7702,7 @@ function createSessionsRegistry(opts) {
   const projectEvent = (rt, evt) => {
     switch (evt.kind) {
       case "text-delta":
+        releaseBlockedOn(rt.desc);
         if (evt.text) {
           const combined = rt.textBuf + evt.text;
           const lines = combined.split(/\r?\n/);
@@ -7223,17 +7728,18 @@ function createSessionsRegistry(opts) {
           rt.desc.blockedOn = blocked;
           rt.desc.pendingToolCallId = evt.toolCallId;
         }
-        appendLine(
-          rt,
-          `\x1B[36m[tool] ${formatToolCall(evt.toolName ?? "?", evt.arguments)}\x1B[0m`,
-          "stdout"
-        );
+        if (!evt.isUpdate) {
+          appendLine(
+            rt,
+            `\x1B[36m[tool] ${formatToolCall(evt.toolName ?? "?", evt.arguments)}\x1B[0m`,
+            "stdout"
+          );
+        }
         break;
       }
       case "tool-result": {
         if (rt.desc.blockedOn && evt.toolCallId === rt.desc.pendingToolCallId) {
-          rt.desc.blockedOn = void 0;
-          rt.desc.pendingToolCallId = void 0;
+          releaseBlockedOn(rt.desc);
         }
         const summary = formatToolResult(evt.toolName, evt.result, evt.isError ?? false);
         if (summary) {
@@ -7257,7 +7763,12 @@ function createSessionsRegistry(opts) {
             source: "structured"
           };
         }
-        appendLine(rt, `\x1B[33m[awaiting input]\x1B[0m`, "stdout");
+        if (rt.permissionHold) {
+          registerPendingPermission(rt, evt);
+          appendLine(rt, `\x1B[33m[permission] ${evt.text ?? evt.toolName ?? "requesting permission"}\x1B[0m`, "stdout");
+        } else {
+          appendLine(rt, `\x1B[33m[awaiting input]\x1B[0m`, "stdout");
+        }
         break;
       }
       case "turn-end": {
@@ -7282,6 +7793,7 @@ function createSessionsRegistry(opts) {
         break;
       }
       case "error": {
+        releaseBlockedOn(rt.desc);
         const code = typeof evt.error?.code === "number" ? ` (code ${evt.error.code})` : "";
         appendLine(
           rt,
@@ -7314,7 +7826,10 @@ function createSessionsRegistry(opts) {
       // reported cost/tokens are available live to session_list / session_usage.
       case "usage_update": {
         if (typeof evt.size === "number" && evt.size > 0) rt.desc.contextSize = evt.size;
-        if (typeof evt.used === "number" && evt.used > 0) rt.desc.contextUsed = evt.used;
+        if (typeof evt.used === "number" && evt.used > 0) {
+          const used = plausibleContextUsed(rt.desc.contextSize, evt.used);
+          if (used !== void 0) rt.desc.contextUsed = used;
+        }
         if (evt.cost) {
           rt.desc.costUsd = evt.cost.amount;
           rt.adapterReportedCost = true;
@@ -7344,13 +7859,13 @@ function createSessionsRegistry(opts) {
     }
     return rt;
   };
-  const waitForTurnSettled = (rt, id) => {
+  const waitForTurnSettled = (rt, id, caller) => {
     if (!rt.busy) return Promise.resolve();
-    return new Promise((resolve13, reject) => {
+    return new Promise((resolve12, reject) => {
       const onBusy = (busy) => {
         if (busy) return;
         cleanup();
-        resolve13();
+        resolve12();
       };
       const cleanup = () => {
         clearTimeout(timer);
@@ -7360,28 +7875,28 @@ function createSessionsRegistry(opts) {
         cleanup();
         reject(
           new Error(
-            `enqueuePrompt: session "${id}" did not settle after interrupt within ${INTERRUPT_SETTLE_TIMEOUT_MS}ms`
+            `${caller}: session "${id}" did not settle after interrupt within ${INTERRUPT_SETTLE_TIMEOUT_MS}ms`
           )
         );
       }, INTERRUPT_SETTLE_TIMEOUT_MS);
       rt.emitter.on("busy", onBusy);
     });
   };
-  const interruptInFlightTurn = async (rt, id) => {
+  const interruptInFlightTurn = async (rt, id, caller) => {
     const session = rt.agentSession;
     if (!session) {
       throw new Error(
-        `enqueuePrompt: session "${id}" is mid-turn but has no live agent session to cancel`
+        `${caller}: session "${id}" is mid-turn but has no live agent session to cancel`
       );
     }
     try {
       await session.cancel();
     } catch (err) {
       throw new Error(
-        `enqueuePrompt: session "${id}" does not support interrupt \u2014 cancelling the in-flight turn failed: ${err instanceof Error ? err.message : String(err)}`
+        `${caller}: session "${id}" does not support interrupt \u2014 cancelling the in-flight turn failed: ${err instanceof Error ? err.message : String(err)}`
       );
     }
-    await waitForTurnSettled(rt, id);
+    await waitForTurnSettled(rt, id, caller);
   };
   const maybeResumeAgent = async (rt) => {
     if (rt.agentSession) return;
@@ -7469,12 +7984,13 @@ function createSessionsRegistry(opts) {
     rt.emitter.emit("busy", true);
     rt.desc.awaitingInput = false;
     rt.desc.awaitingQuestion = void 0;
-    rt.desc.blockedOn = void 0;
-    rt.desc.pendingToolCallId = void 0;
+    releaseBlockedOn(rt.desc);
     let turnCompleted = false;
     let sawTurnEnd = false;
     let abnormalReason;
     let turnEndReason;
+    let sawAssistantText = false;
+    let sawToolCall = false;
     try {
       appendLine(
         rt,
@@ -7486,6 +8002,8 @@ function createSessionsRegistry(opts) {
       for await (const evt of rt.agentSession.send(wrapped)) {
         transcriptWriter.recordEvent(rt.desc.id, evt);
         projectEvent(rt, evt);
+        if (evt.kind === "text-delta" && evt.text?.trim()) sawAssistantText = true;
+        else if (evt.kind === "tool-call") sawToolCall = true;
         if (evt.kind === "turn-end") {
           sawTurnEnd = true;
           turnEndReason = evt.reason;
@@ -7512,8 +8030,7 @@ function createSessionsRegistry(opts) {
       rt.busy = false;
       rt.desc.busy = false;
       rt.emitter.emit("busy", false);
-      rt.desc.blockedOn = void 0;
-      rt.desc.pendingToolCallId = void 0;
+      releaseBlockedOn(rt.desc);
       if (!sawTurnEnd) {
         const reason = abnormalReason ?? (rt.desc.status === "killed" ? "aborted" : "exited");
         const synthetic = { kind: "turn-end", reason };
@@ -7566,6 +8083,14 @@ function createSessionsRegistry(opts) {
           void transcriptWriter.close(rt.desc.id);
           tracedSessions.delete(rt.desc.id);
         }
+        const emptyTurn = !sawAssistantText && !sawToolCall && !(rt.desc.awaitingInput ?? false);
+        if (emptyTurn) {
+          appendLine(
+            rt,
+            `\x1B[33m[warning] empty turn \u2014 no assistant output, no tool call, cost ${rt.desc.costUsd !== void 0 ? `$${rt.desc.costUsd}` : "unknown"}. Likely an invalid model id or a provider that returned nothing; verify the model slug (agentproto models <adapter>).\x1B[0m`,
+            "stderr"
+          );
+        }
         if (sessionEvents) {
           if (rt.desc.awaitingInput && !rt.desc.awaitingQuestion) {
             rt.desc.awaitingQuestion = deriveHeuristicQuestion(rt.recentLines);
@@ -7578,7 +8103,8 @@ function createSessionsRegistry(opts) {
             label: rt.desc.label,
             ts,
             ...rt.desc.awaitingQuestion ? { question: rt.desc.awaitingQuestion } : {},
-            ...turnEndReason ? { reason: turnEndReason } : {}
+            ...turnEndReason ? { reason: turnEndReason } : {},
+            ...emptyTurn ? { empty: true } : {}
           });
           if (rt.desc.awaitingInput) {
             sessionEvents.emit({
@@ -7608,8 +8134,8 @@ function createSessionsRegistry(opts) {
   };
   const wireOutputStreams = (rt) => {
     const onChunk = (stream) => (chunk) => {
-      const text5 = typeof chunk === "string" ? chunk : chunk.toString("utf8");
-      for (const line of text5.split(/\r?\n/)) {
+      const text6 = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      for (const line of text6.split(/\r?\n/)) {
         if (line.length > 0) appendLine(rt, line, stream);
       }
     };
@@ -7764,6 +8290,7 @@ function createSessionsRegistry(opts) {
         ...input.parentSessionId ? { parentSessionId: input.parentSessionId } : {},
         depth: input.depth ?? 0,
         ...input.model ? { model: input.model } : {},
+        ...input.auth ? { auth: input.auth } : {},
         ...priorCommandSessionId ? { priorCommandSessionId } : {},
         ...input.remote ? { remote: true } : {},
         ...input.sandboxId ? { sandboxId: input.sandboxId } : {},
@@ -7784,7 +8311,8 @@ function createSessionsRegistry(opts) {
         textBuf: "",
         thoughtBuf: "",
         maxCostUsd: input.maxCostUsd,
-        readUsage: input.readUsage
+        readUsage: input.readUsage,
+        ...input.permissionHold ? { permissionHold: true } : {}
       };
       rt.emitter.setMaxListeners(50);
       sessions.set(id, rt);
@@ -7983,8 +8511,11 @@ function createSessionsRegistry(opts) {
       schedulePersist();
       return desc;
     },
-    async sendPrompt(id, message) {
+    async sendPrompt(id, message, opts2) {
       const rtPre = sessions.get(id);
+      if (opts2?.interrupt && rtPre?.busy) {
+        await interruptInFlightTurn(rtPre, id, "sendPrompt");
+      }
       if (rtPre) await maybeResumeAgent(rtPre);
       const rt = validateAgentTurn(id, "sendPrompt");
       await runAgentTurn(rt, message);
@@ -7995,7 +8526,7 @@ function createSessionsRegistry(opts) {
         throw new Error(`enqueuePrompt: no session "${id}"`);
       }
       if (opts2?.interrupt && rtPre.busy) {
-        await interruptInFlightTurn(rtPre, id);
+        await interruptInFlightTurn(rtPre, id, "enqueuePrompt");
       }
       await maybeResumeAgent(rtPre);
       const rt = validateAgentTurn(id, "enqueuePrompt");
@@ -8032,6 +8563,9 @@ function createSessionsRegistry(opts) {
       rt.emitter.on("line", handler);
       return () => rt.emitter.off("line", handler);
     },
+    subscribeToRecords(id, onRecord) {
+      return baseTranscriptWriter.subscribe(id, onRecord);
+    },
     attachPty(id, initial, onData, onExit) {
       const rt = sessions.get(id);
       if (!rt || !rt.pty || !rt.ptySubscribers) return null;
@@ -8126,6 +8660,74 @@ function createSessionsRegistry(opts) {
       emitExited(rt);
       return true;
     },
+    listPendingPermissions(filter) {
+      const all = Array.from(pendingPermissions.values());
+      const scoped = filter?.sessionId ? all.filter((p) => p.sessionId === filter.sessionId) : all;
+      return scoped.map((p) => ({ ...p, options: p.options.map((o) => ({ ...o })) }));
+    },
+    async respondPermission(id, input) {
+      const pending = pendingPermissions.get(id);
+      if (!pending) {
+        return {
+          ok: false,
+          error: "not_found",
+          message: `no pending permission "${id}" (unknown or already resolved)`
+        };
+      }
+      const rt = sessions.get(pending.sessionId);
+      if (!rt || !rt.agentSession) {
+        pendingPermissions.delete(id);
+        if (rt) refreshAwaitingPermission(rt);
+        return {
+          ok: false,
+          error: "session_gone",
+          message: `session "${pending.sessionId}" for permission "${id}" is no longer alive`
+        };
+      }
+      const respond = rt.agentSession.respondPermission;
+      if (!respond) {
+        return {
+          ok: false,
+          error: "unsupported",
+          message: `session "${pending.sessionId}" driver does not support held permissions`
+        };
+      }
+      const selected = selectPermissionOptionId(pending.options, input);
+      if (selected === null) {
+        return {
+          ok: false,
+          error: "no_matching_option",
+          message: `permission "${id}" offers no ${input.decision === "approve" ? "allow" : "reject"}-flavored option; pass an explicit optionId (one of: ${pending.options.map((o) => o.optionId).join(", ")})`
+        };
+      }
+      pendingPermissions.delete(id);
+      const chosenOptionId = "optionId" in selected ? selected.optionId : void 0;
+      delete rt.desc.awaitingInput;
+      rt.desc.awaitingQuestion = void 0;
+      refreshAwaitingPermission(rt);
+      const okResolved = await respond(id, selected);
+      if (sessionEvents) {
+        sessionEvents.emit({
+          type: "session:permission-resolved",
+          sessionId: pending.sessionId,
+          permissionId: id,
+          decision: input.decision,
+          ...chosenOptionId ? { optionId: chosenOptionId } : {},
+          ...rt.desc.label ? { label: rt.desc.label } : {},
+          ts: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      schedulePersist();
+      if (!okResolved) {
+        return { ok: true, permission: pending, decision: input.decision, ...chosenOptionId ? { optionId: chosenOptionId } : {} };
+      }
+      return {
+        ok: true,
+        permission: pending,
+        decision: input.decision,
+        ...chosenOptionId ? { optionId: chosenOptionId } : {}
+      };
+    },
     forget(id) {
       const rt = sessions.get(id);
       if (!rt) return false;
@@ -8157,6 +8759,8 @@ function createSessionsRegistry(opts) {
       if (rt.desc.status === "running" || rt.desc.status === "starting") {
         rt.desc.status = "killed";
         rt.desc.endedAt = nowIso;
+        rt.desc.endedReason = "daemon-restart";
+        clearInFlightFlags(rt.desc);
         if (rt.agentSession) {
           recordExitUsageSnapshot(rt);
           void rt.agentSession.close().catch(() => void 0);
@@ -8168,6 +8772,7 @@ function createSessionsRegistry(opts) {
           }
         }
         rt.child?.kill("SIGTERM");
+        emitExited(rt);
       }
     }
     void transcriptWriter.closeAll();
@@ -8191,7 +8796,15 @@ function createSessionsRegistry(opts) {
     sessions.clear();
   }
 }
-function loadHistorySnapshot(persistPath, sessions) {
+function clearInFlightFlags(desc) {
+  desc.busy = false;
+  desc.awaitingInput = false;
+  desc.awaitingQuestion = void 0;
+  delete desc.awaitingPermission;
+  desc.blockedOn = void 0;
+  desc.pendingToolCallId = void 0;
+}
+function loadHistorySnapshot(persistPath, sessions, sessionEvents) {
   let raw;
   try {
     raw = readFileSync(persistPath, "utf8");
@@ -8216,8 +8829,14 @@ function loadHistorySnapshot(persistPath, sessions) {
     const reclassified = wasAlive ? {
       ...desc,
       status: "killed",
-      endedAt: desc.endedAt ?? now
+      endedAt: desc.endedAt ?? now,
+      endedReason: "daemon-restart"
     } : desc;
+    clearInFlightFlags(reclassified);
+    reclassified.contextUsed = plausibleContextUsed(
+      reclassified.contextSize,
+      reclassified.contextUsed
+    );
     const rt = {
       desc: reclassified,
       recentLines: [],
@@ -8226,10 +8845,22 @@ function loadHistorySnapshot(persistPath, sessions) {
       emitter: new EventEmitter(),
       busy: false,
       textBuf: "",
-      thoughtBuf: ""
+      thoughtBuf: "",
+      exitedEmitted: wasAlive
     };
     rt.emitter.setMaxListeners(50);
     sessions.set(desc.id, rt);
+    if (wasAlive) {
+      sessionEvents?.emit({
+        type: "session:exited",
+        sessionId: reclassified.id,
+        exitCode: reclassified.exitCode,
+        status: "killed",
+        ...reclassified.label ? { label: reclassified.label } : {},
+        reason: "daemon-restart",
+        ts: now
+      });
+    }
   }
 }
 function quoteArg(arg) {
@@ -8318,7 +8949,7 @@ async function monitorSessionWait(opts) {
       };
     }
   }
-  return new Promise((resolve13) => {
+  return new Promise((resolve12) => {
     const unsubs = [];
     let settled = false;
     const finish = (result) => {
@@ -8326,7 +8957,7 @@ async function monitorSessionWait(opts) {
       settled = true;
       clearTimeout(timer);
       for (const u of unsubs) u();
-      resolve13(result);
+      resolve12(result);
     };
     const relevantTypes = targetEvent === "any" ? ["session:turn-end", "session:awaiting-input", "session:exited"] : targetEvent === "turn-end" ? ["session:turn-end", "session:awaiting-input"] : targetEvent === "awaiting-input" ? ["session:awaiting-input"] : ["session:exited"];
     const idSet = new Set(resolvedIds);
@@ -8362,13 +8993,13 @@ async function monitorPolicyWait(opts) {
   if (isSettledStatus(initial.status)) {
     return { timedOut: false, state: initial };
   }
-  return new Promise((resolve13) => {
+  return new Promise((resolve12) => {
     let settled = false;
     const timer = setTimeout(() => {
       if (settled) return;
       settled = true;
       unsub();
-      resolve13({ timedOut: true });
+      resolve12({ timedOut: true });
     }, timeoutMs);
     const unsub = supervisor.onSettle((id) => {
       if (id !== policyId) return;
@@ -8378,7 +9009,7 @@ async function monitorPolicyWait(opts) {
       settled = true;
       clearTimeout(timer);
       unsub();
-      resolve13({ timedOut: false, state });
+      resolve12({ timedOut: false, state });
     });
   });
 }
@@ -8398,7 +9029,7 @@ function registerOrchestrationTools(rawServer, opts) {
         "Opaque cursor from a prior call's `nextCursor`. Omit (or pass 0) to start from the current tail \u2014 returns events emitted after this call."
       ),
       sessionIds: z.array(z.string()).optional().describe("Filter to these session ids. Omit \u2192 all sessions."),
-      types: z.array(z.enum(["turn-end", "awaiting-input", "exited", "command-done", "policy:passed", "policy:failed", "policy:commit-ready", "policy:committed", "cron:fired", "cron:succeeded", "cron:failed"])).optional().describe("Filter to these event types. Omit \u2192 all types."),
+      types: z.array(z.enum(["turn-end", "awaiting-input", "permission-request", "permission-resolved", "exited", "command-done", "policy:passed", "policy:failed", "policy:commit-ready", "policy:committed", "cron:fired", "cron:succeeded", "cron:failed"])).optional().describe("Filter to these event types. Omit \u2192 all types."),
       limit: z.number().int().min(1).max(200).optional().describe("Max events to return. Default 50.")
     },
     async (input) => {
@@ -8415,6 +9046,88 @@ function registerOrchestrationTools(rawServer, opts) {
       };
     }
   );
+  const isSessionInScope = (sessionId) => {
+    if (!callerScope) return true;
+    if (!callerScope.ownerSessionId) return false;
+    return collectSubtree(callerScope.ownerSessionId, registry.list()).has(sessionId);
+  };
+  const enrichPermission2 = (p) => {
+    const desc = registry.get(p.sessionId);
+    const ageMs = Date.now() - new Date(p.requestedAt).getTime();
+    return {
+      ...p,
+      ...desc?.adapterSlug ? { adapter: desc.adapterSlug } : {},
+      ...desc?.label ? { sessionLabel: desc.label } : {},
+      ...desc?.command ? { sessionTitle: desc.command } : {},
+      ageMs: ageMs >= 0 ? ageMs : 0
+    };
+  };
+  server.tool(
+    "permissions_list",
+    "List permission requests currently HELD across all permission-hold sessions (spawned with `permissionHold`). Each entry: id, sessionId, session adapter/title, the tool being requested, the offered options, and age. Resolve one with `permissions_respond`. Optionally filter by `sessionId`. Empty list = nothing is waiting on a decision.",
+    {
+      sessionId: z.string().optional().describe("Filter to one session's pending permissions. Omit \u2192 all sessions.")
+    },
+    async (input) => {
+      const pending = registry.listPendingPermissions(input.sessionId ? { sessionId: input.sessionId } : void 0).filter((p) => isSessionInScope(p.sessionId)).map(enrichPermission2);
+      return {
+        content: [{ type: "text", text: JSON.stringify({ permissions: pending }, null, 2) }]
+      };
+    }
+  );
+  server.tool(
+    "permissions_respond",
+    'Resolve a permission request parked by a permission-hold session (see `permissions_list`). `decision:"approve"` selects an allow option (allow-always when `scope:"always"` is offered, else allow-once); `decision:"deny"` selects a reject option (or cancels the request when none is offered). An explicit `optionId` overrides the decision\u2192option mapping. Errors clearly on an unknown/already-resolved id. The agent\'s turn unblocks with the chosen outcome.',
+    {
+      id: z.string().describe("Pending permission id from `permissions_list`."),
+      decision: z.enum(["approve", "deny"]).describe("approve \u2192 an allow option; deny \u2192 a reject option / cancel."),
+      optionId: z.string().optional().describe("Explicit offered optionId \u2014 wins over `decision` mapping."),
+      scope: z.enum(["once", "always"]).optional().describe("For approve: prefer allow-always when the request offers it.")
+    },
+    async (input) => {
+      const pending = registry.listPendingPermissions().find((p) => p.id === input.id);
+      if (!pending || !isSessionInScope(pending.sessionId)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "not_found", message: `no pending permission "${input.id}"` })
+            }
+          ],
+          isError: true
+        };
+      }
+      const result = await registry.respondPermission(input.id, {
+        decision: input.decision,
+        ...input.optionId ? { optionId: input.optionId } : {},
+        ...input.scope ? { scope: input.scope } : {}
+      });
+      if (!result.ok) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: result.error, message: result.message }) }],
+          isError: true
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                ok: true,
+                id: input.id,
+                sessionId: result.permission.sessionId,
+                decision: result.decision,
+                ...result.optionId ? { optionId: result.optionId } : {}
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
   const { routineRunner } = opts;
   if (routineRunner) {
     server.tool(
@@ -8899,7 +9612,16 @@ function registerOrchestrationTools(rawServer, opts) {
     "session_monitor",
     "Multiplexed long-poll: block until ANY of the listed sessions fires a lifecycle event. Returns immediately when a session is already in the target state. Eliminates polling in multi-session fan-in orchestration \u2014 one call replaces N concurrent waitForTurnEnd calls.",
     {
-      sessionIds: z.array(z.string()).min(1).max(20).describe("Session ids (or names) to watch. Returns on the first hit."),
+      // Accept the natural shapes an agent already has on hand: a single id
+      // (the `id` agent_start returns, or `sessionId` from the drive tools),
+      // or the fan-in array. `sessionIds` additionally tolerates a bare
+      // string (not just an array) so a one-session monitor doesn't force
+      // array-wrapping. All three coalesce into the watched-id list below.
+      sessionIds: jsonTolerant(z.union([z.string(), z.array(z.string())])).optional().describe(
+        "Session ids (or names) to watch \u2014 an array for fan-in, or a single id. Returns on the first hit. Provide this OR `sessionId`/`id`."
+      ),
+      sessionId: z.string().optional().describe("Single session id/name \u2014 singular alias for `sessionIds`."),
+      id: z.string().optional().describe("Alias for `sessionId` \u2014 the `id` returned by agent_start."),
       timeoutMs: z.number().int().min(1e3).max(49e3).optional().describe("Max wait in ms. Default 25 000. Stays under MCP request timeout."),
       event: z.enum(["turn-end", "awaiting-input", "exited", "any"]).optional().describe(
         "Event type to wait for. Default 'any'. 'turn-end' also matches 'awaiting-input' (both signal end-of-turn)."
@@ -8911,14 +9633,43 @@ function registerOrchestrationTools(rawServer, opts) {
     async (input) => {
       const timeout = input.timeoutMs ?? 25e3;
       const targetEvent = input.event ?? "any";
-      const result = await monitorSessionWait({
-        registry,
-        sessionEvents,
-        eventRing,
-        sessionIds: input.sessionIds,
-        event: targetEvent,
-        timeoutMs: timeout,
-        ...input.since !== void 0 ? { since: input.since } : {}
+      const fromSessionIds = input.sessionIds === void 0 ? [] : Array.isArray(input.sessionIds) ? input.sessionIds : [input.sessionIds];
+      const singular = input.sessionId ?? input.id;
+      const sessionIds = [...fromSessionIds, ...singular ? [singular] : []];
+      if (sessionIds.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "session_monitor: no sessions to watch \u2014 pass `sessionIds` (array or single id) or `sessionId`/`id`."
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      if (sessionIds.length > 20) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: `session_monitor: too many sessions (${sessionIds.length}); max 20 per call.`
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      const result = await monitorSessionWait({
+        registry,
+        sessionEvents,
+        eventRing,
+        sessionIds,
+        event: targetEvent,
+        timeoutMs: timeout,
+        ...input.since !== void 0 ? { since: input.since } : {}
       });
       const payload = { ...result };
       if (result.source === "ring" && input.since !== void 0) {
@@ -9777,6 +10528,28 @@ async function startHttpServer(opts) {
           );
           if (handled) return;
         }
+        if (opts.sessions && path.startsWith("/permissions")) {
+          if ((req.method ?? "GET") !== "GET") {
+            const gate = checkSessionsToken(req);
+            if (gate !== "ok") {
+              rejectUnauthorizedSession(req, res, gate);
+              return;
+            }
+          }
+          const handled = await handlePermissions(req, res, path, opts.sessions);
+          if (handled) return;
+        }
+        if (opts.pairings && path.startsWith("/pairings")) {
+          if ((req.method ?? "GET") !== "GET") {
+            const gate = checkSessionsToken(req);
+            if (gate !== "ok") {
+              rejectUnauthorizedSession(req, res, gate);
+              return;
+            }
+          }
+          const handled = await handlePairings(req, res, path, opts.pairings);
+          if (handled) return;
+        }
         if (opts.cronScheduler && path.startsWith("/cron")) {
           const handled = await handleCron(req, res, path, opts.cronScheduler);
           if (handled) return;
@@ -9842,16 +10615,16 @@ async function startHttpServer(opts) {
     });
   });
   const bind = opts.bind ?? "127.0.0.1";
-  await new Promise((resolve13, reject) => {
+  await new Promise((resolve12, reject) => {
     server.once("error", reject);
-    server.listen(opts.port, bind, () => resolve13());
+    server.listen(opts.port, bind, () => resolve12());
   });
   return {
     url: `http://${bind}:${opts.port}`,
     async stop() {
       wss.close();
       server.closeAllConnections();
-      await new Promise((resolve13) => server.close(() => resolve13()));
+      await new Promise((resolve12) => server.close(() => resolve12()));
     }
   };
 }
@@ -9969,6 +10742,33 @@ function clampInt(raw, fallback, min, max) {
   if (n > max) return max;
   return n;
 }
+function deliverRecordsExactlyOnce(opts) {
+  let lastSeqSent = opts.since;
+  let replaying = true;
+  const buffered = [];
+  const gate = (record) => {
+    const seq = record.seq;
+    if (typeof seq !== "number" || seq <= lastSeqSent) return;
+    lastSeqSent = seq;
+    opts.send(record);
+  };
+  const unsubscribe = opts.subscribe((record) => {
+    if (replaying) {
+      buffered.push(record);
+    } else {
+      gate(record);
+    }
+  });
+  const done = (async () => {
+    for await (const rec of opts.diskRecords) {
+      gate(rec);
+    }
+    replaying = false;
+    for (const rec of buffered) gate(rec);
+    buffered.length = 0;
+  })();
+  return { unsubscribe, done };
+}
 function parseOrchestratorField(raw) {
   const value = typeof raw === "string" ? tryParseJson(raw) : raw;
   if (typeof value === "boolean") return value;
@@ -10002,6 +10802,39 @@ function parseMcpServersField(raw) {
   }
   return servers;
 }
+function parseOptionsField(raw) {
+  const value = typeof raw === "string" ? tryParseJson(raw) : raw;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (typeof v === "boolean" || typeof v === "number" || typeof v === "string") {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+function parseAuthField(raw) {
+  const value = typeof raw === "string" ? tryParseJson(raw) : raw;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const obj = value;
+  const mode = obj.mode === "subscription" || obj.mode === "api-key" ? obj.mode : void 0;
+  const token = typeof obj.token === "string" ? obj.token : void 0;
+  const apiKey = typeof obj.apiKey === "string" ? obj.apiKey : void 0;
+  return {
+    ...mode ? { mode } : {},
+    ...token !== void 0 ? { token } : {},
+    ...apiKey !== void 0 ? { apiKey } : {}
+  };
+}
+async function resolveSlugFromCwd(cwd) {
+  if (!cwd) return void 0;
+  try {
+    const config = await loadWorkspacesConfig();
+    return findWorkspaceByPath(config, cwd)?.slug;
+  } catch {
+    return void 0;
+  }
+}
 async function handleSessions(req, res, path, registry, resolveAgentAdapter, ptyEnabled = false, resolveBrowserAdapter, listBrowserAdapters, sessionEvents, eventRing, buildOrchestratorMcp, daemonMcpUrl) {
   const json = (status, body) => {
     res.writeHead(status, { "content-type": "application/json" });
@@ -10040,8 +10873,17 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
         ...typeof b.mode === "string" && b.mode.length > 0 ? { mode: b.mode } : {},
         ...typeof b.model === "string" && b.model.length > 0 ? { model: b.model } : {},
         ...typeof b.effort === "string" && b.effort.length > 0 ? { effort: b.effort } : {},
+        ...b.options !== void 0 ? (() => {
+          const parsed = parseOptionsField(b.options);
+          return parsed !== void 0 ? { options: parsed } : {};
+        })() : {},
+        ...b.auth !== void 0 ? (() => {
+          const parsed = parseAuthField(b.auth);
+          return parsed !== void 0 ? { auth: parsed } : {};
+        })() : {},
         ...typeof b.prompt === "string" ? { prompt: b.prompt } : {},
         ...typeof b.label === "string" ? { label: b.label } : {},
+        ...typeof b.idempotencyKey === "string" && b.idempotencyKey.length > 0 ? { idempotencyKey: b.idempotencyKey } : {},
         ...typeof b.role === "string" && b.role.length > 0 ? { role: b.role } : {},
         ...typeof b.promptAppend === "string" ? { promptAppend: b.promptAppend } : {},
         ...b.orchestrator !== void 0 ? (() => {
@@ -10059,6 +10901,13 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
         ...b.trace !== void 0 ? (() => {
           const t = typeof b.trace === "boolean" ? b.trace : b.trace === "true" ? true : b.trace === "false" ? false : void 0;
           return t !== void 0 ? { trace: t } : {};
+        })() : {},
+        // Permission-hold mode — the HTTP twin of the MCP `agent_start` tool's
+        // `permissionHold` field (and `agentproto sessions start
+        // --hold-permissions`). Tolerate a stringified boolean like `trace`.
+        ...b.permissionHold !== void 0 ? (() => {
+          const h = typeof b.permissionHold === "boolean" ? b.permissionHold : b.permissionHold === "true" ? true : b.permissionHold === "false" ? false : void 0;
+          return h ? { permissionHold: true } : {};
         })() : {}
       }
     );
@@ -10071,7 +10920,10 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
       });
       return true;
     }
-    json(201, result.descriptor);
+    json(201, {
+      ...result.descriptor,
+      ...result.deduped ? { deduped: true } : {}
+    });
     return true;
   }
   if (path === "/sessions/browser" && req.method === "POST") {
@@ -10205,7 +11057,9 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
         `[/sessions/terminal] no cwd resolvable for argv=${argv.join(" ")} \u2014 falling back to daemon's cwd ${cwd}`
       );
     }
-    if (!workspaceSlug) workspaceSlug = "default";
+    if (!workspaceSlug) {
+      workspaceSlug = await resolveSlugFromCwd(cwd) ?? "default";
+    }
     try {
       const desc = registry.spawnPty({
         argv,
@@ -10249,7 +11103,7 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
         await registry.enqueuePrompt(id2, prompt, { interrupt });
         json(202, { ok: true, id: id2, queued: true });
       } else {
-        await registry.sendPrompt(id2, prompt);
+        await registry.sendPrompt(id2, prompt, { interrupt });
         json(200, { ok: true, id: id2 });
       }
     } catch (err) {
@@ -10276,10 +11130,14 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
       return true;
     }
     try {
+      const rawCwd = typeof b.cwd === "string" ? b.cwd : process.cwd();
       const desc = registry.spawn({
         kind: b.kind === "terminal" || b.kind === "agent-cli" || b.kind === "command" ? b.kind : "command",
-        workspaceSlug: typeof b.workspaceSlug === "string" ? b.workspaceSlug : "default",
-        cwd: typeof b.cwd === "string" ? b.cwd : process.cwd(),
+        // Same reverse-map as /sessions/terminal and spawnAgentSession: an
+        // explicit slug wins, otherwise derive it from cwd rather than
+        // dumping the session into "default".
+        workspaceSlug: typeof b.workspaceSlug === "string" ? b.workspaceSlug : await resolveSlugFromCwd(rawCwd) ?? "default",
+        cwd: rawCwd,
         argv,
         env: b.env && typeof b.env === "object" ? b.env : void 0,
         label: typeof b.label === "string" ? b.label : void 0
@@ -10294,7 +11152,7 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
     return true;
   }
   const idMatch = path.match(
-    /^\/sessions\/([^/]+)(\/stream|\/kill|\/preview|\/export|\/events|\/wait)?$/
+    /^\/sessions\/([^/]+)(\/events\/stream|\/stream|\/kill|\/preview|\/export|\/events|\/wait)?$/
   );
   if (!idMatch) return false;
   const [, rawIdOrName, suffix] = idMatch;
@@ -10351,9 +11209,9 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
     let fileStream;
     try {
       fileStream = createReadStream(filePath, { encoding: "utf8" });
-      await new Promise((resolve13, reject) => {
+      await new Promise((resolve12, reject) => {
         fileStream.once("error", reject);
-        fileStream.once("open", resolve13);
+        fileStream.once("open", resolve12);
       });
     } catch (err) {
       const code = err.code;
@@ -10391,6 +11249,85 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
     });
     return true;
   }
+  if (suffix === "/events/stream" && req.method === "GET") {
+    const reqUrl = req.url ?? "";
+    const qs = new URLSearchParams(
+      reqUrl.includes("?") ? reqUrl.slice(reqUrl.indexOf("?") + 1) : ""
+    );
+    const sinceRaw = qs.get("since");
+    if (sinceRaw !== null && !/^\d+$/.test(sinceRaw)) {
+      json(400, {
+        error: "invalid_since",
+        message: "since must be a non-negative integer"
+      });
+      return true;
+    }
+    const since = sinceRaw !== null ? Number.parseInt(sinceRaw, 10) : 0;
+    const filePath = sessionEventsPath(id);
+    let fileStream;
+    try {
+      fileStream = createReadStream(filePath, { encoding: "utf8" });
+      await new Promise((resolve12, reject) => {
+        fileStream.once("error", reject);
+        fileStream.once("open", resolve12);
+      });
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") {
+        json(404, { error: "no_transcript" });
+        return true;
+      }
+      throw err;
+    }
+    res.writeHead(200, {
+      "content-type": "text/event-stream",
+      "cache-control": "no-cache",
+      connection: "keep-alive"
+    });
+    res.write(`: connected
+
+`);
+    const ping = setInterval(() => {
+      try {
+        res.write(`: keep-alive
+
+`);
+      } catch {
+        clearInterval(ping);
+      }
+    }, 25e3);
+    async function* diskRecords() {
+      const rl = createInterface({ input: fileStream, crlfDelay: Infinity });
+      for await (const line of rl) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+          yield JSON.parse(trimmed);
+        } catch {
+          continue;
+        }
+      }
+    }
+    const { unsubscribe, done } = deliverRecordsExactlyOnce({
+      since,
+      diskRecords: diskRecords(),
+      subscribe: (onRecord) => registry.subscribeToRecords(id, onRecord),
+      send: (record) => {
+        try {
+          res.write(`data: ${JSON.stringify(record)}
+
+`);
+        } catch {
+        }
+      }
+    });
+    req.once("close", () => {
+      unsubscribe();
+      clearInterval(ping);
+    });
+    await done;
+    return true;
+  }
   if (suffix === "/preview" && req.method === "GET") {
     if (!resolvedDesc) {
       json(404, { error: "session_not_found", id: rawIdOrName });
@@ -10915,6 +11852,133 @@ async function handlePolicies(req, res, path, supervisor, registry) {
   json(200, state);
   return true;
 }
+async function handlePermissions(req, res, path, registry) {
+  const json = (status, body) => {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+  };
+  if (path === "/permissions" && req.method === "GET") {
+    const reqUrl = req.url ?? "";
+    const qs = new URLSearchParams(
+      reqUrl.includes("?") ? reqUrl.slice(reqUrl.indexOf("?") + 1) : ""
+    );
+    const sessionId = qs.get("sessionId") ?? void 0;
+    const permissions = registry.listPendingPermissions(sessionId ? { sessionId } : void 0).map((p) => enrichPermission(p, registry));
+    json(200, { permissions });
+    return true;
+  }
+  const idMatch = path.match(/^\/permissions\/([^/]+)$/);
+  if (idMatch && req.method === "POST") {
+    const id = decodeURIComponent(idMatch[1] ?? "");
+    const body = await readJsonBody(req);
+    const b = body && typeof body === "object" ? body : {};
+    const decision = b.decision;
+    if (decision !== "approve" && decision !== "deny") {
+      json(400, {
+        error: "invalid_decision",
+        message: 'body.decision must be "approve" or "deny"'
+      });
+      return true;
+    }
+    const optionId = typeof b.optionId === "string" ? b.optionId : void 0;
+    const scope = b.scope === "always" || b.scope === "once" ? b.scope : void 0;
+    const result = await registry.respondPermission(id, {
+      decision,
+      ...optionId ? { optionId } : {},
+      ...scope ? { scope } : {}
+    });
+    if (!result.ok) {
+      const status = result.error === "not_found" || result.error === "session_gone" ? 404 : 409;
+      json(status, { error: result.error, message: result.message });
+      return true;
+    }
+    json(200, {
+      ok: true,
+      id,
+      sessionId: result.permission.sessionId,
+      decision: result.decision,
+      ...result.optionId ? { optionId: result.optionId } : {}
+    });
+    return true;
+  }
+  if (path === "/permissions" || idMatch) {
+    json(405, { error: "method_not_allowed", message: "GET /permissions or POST /permissions/:id" });
+    return true;
+  }
+  return false;
+}
+function enrichPermission(p, registry) {
+  const desc = registry.get(p.sessionId);
+  const ageMs = Date.now() - new Date(p.requestedAt).getTime();
+  return {
+    ...p,
+    ...desc?.adapterSlug ? { adapter: desc.adapterSlug } : {},
+    ...desc?.label ? { sessionLabel: desc.label } : {},
+    ...desc?.command ? { sessionTitle: desc.command } : {},
+    ageMs: ageMs >= 0 ? ageMs : 0
+  };
+}
+async function handlePairings(req, res, path, registry) {
+  const json = (status, body) => {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+  };
+  if (path === "/pairings/offer" && req.method === "POST") {
+    const body = await readJsonBody(req);
+    const b = body && typeof body === "object" ? body : {};
+    const ttlMinutes = typeof b.ttlMinutes === "number" ? b.ttlMinutes : void 0;
+    const rendezvous = typeof b.rendezvous === "string" ? b.rendezvous : void 0;
+    try {
+      const offer = await registry.createOffer({
+        ...ttlMinutes ? { ttlMs: ttlMinutes * 6e4 } : {},
+        ...rendezvous ? { rendezvousUrl: rendezvous } : {}
+      });
+      json(200, {
+        url: offer.url,
+        fingerprint: offer.fingerprint,
+        rendezvous: offer.rendezvousUrl,
+        rendezvousIsHostedDefault: offer.rendezvousIsHostedDefault,
+        expiresAt: new Date(offer.exp * 1e3).toISOString()
+      });
+    } catch (err) {
+      json(400, {
+        error: "offer_failed",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+    return true;
+  }
+  if (path === "/pairings" && req.method === "GET") {
+    const pairings = (await registry.list()).map((p) => ({
+      name: p.name,
+      fingerprint: p.fingerprint,
+      createdAt: p.createdAt,
+      lastSeen: p.lastSeen,
+      rendezvous: p.rendezvousUrl
+    }));
+    json(200, { pairings });
+    return true;
+  }
+  const fpMatch = path.match(/^\/pairings\/([^/]+)$/);
+  if (fpMatch && req.method === "DELETE") {
+    const target = decodeURIComponent(fpMatch[1] ?? "");
+    const revoked = await registry.revoke(target);
+    if (!revoked) {
+      json(404, { error: "not_found", message: `no pairing matched "${target}"` });
+      return true;
+    }
+    json(200, { ok: true, revoked: target });
+    return true;
+  }
+  if (path === "/pairings" || path === "/pairings/offer" || fpMatch) {
+    json(405, {
+      error: "method_not_allowed",
+      message: "POST /pairings/offer \xB7 GET /pairings \xB7 DELETE /pairings/:fingerprint"
+    });
+    return true;
+  }
+  return false;
+}
 async function handleCron(req, res, path, scheduler) {
   const json = (status, body) => {
     res.writeHead(status, { "content-type": "application/json" });
@@ -11634,11 +12698,11 @@ function createRoutineRunner(opts) {
   const persist = () => {
     saveRuns(runs, persistPath);
   };
-  const waitTurnEnd = (sessionId) => new Promise((resolve13) => {
+  const waitTurnEnd = (sessionId) => new Promise((resolve12) => {
     const unsubs = [];
     const done = () => {
       for (const u of unsubs) u();
-      resolve13();
+      resolve12();
     };
     unsubs.push(
       sessionEvents.on("session:turn-end", (ev) => {
@@ -11954,9 +13018,9 @@ var SessionsRegistryAgentHost = class {
       if (!("role" in m)) continue;
       if (m.role !== "assistant") continue;
       if (!("text" in m)) continue;
-      const text5 = m.text;
-      if (typeof text5 === "string" && text5.trim()) {
-        return text5;
+      const text6 = m.text;
+      if (typeof text6 === "string" && text6.trim()) {
+        return text6;
       }
     }
     return "";
@@ -11967,11 +13031,11 @@ var SessionsRegistryAgentHost = class {
   }
   // ── Internal helpers ──────────────────────────────────────────────────
   waitTurnEnd(sessionId) {
-    return new Promise((resolve13, reject) => {
+    return new Promise((resolve12, reject) => {
       const unsubs = [];
       const done = () => {
         for (const u of unsubs) u();
-        resolve13();
+        resolve12();
       };
       const fail = (reason) => {
         for (const u of unsubs) u();
@@ -12185,9 +13249,9 @@ async function executeRunWorkflow(state, runtimeWf, agents, signal, cache, cache
       state.run.status = "cancelled";
       state.run.endedAt = (/* @__PURE__ */ new Date()).toISOString();
     } else {
-      const errMsg = err instanceof Error ? err.message : String(err);
+      const errMsg2 = err instanceof Error ? err.message : String(err);
       state.run.status = "failed";
-      state.run.error = errMsg;
+      state.run.error = errMsg2;
       state.run.endedAt = (/* @__PURE__ */ new Date()).toISOString();
       for (let i = 0; i < state.run.stages.length; i++) {
         const stage = state.run.stages[i];
@@ -12196,7 +13260,7 @@ async function executeRunWorkflow(state, runtimeWf, agents, signal, cache, cache
           for (const step of stage.steps) {
             step.status = "failed";
             step.endedAt = (/* @__PURE__ */ new Date()).toISOString();
-            step.error = errMsg;
+            step.error = errMsg2;
           }
         }
       }
@@ -12445,11 +13509,11 @@ var ANSI_RE2 = /\x1b\[[0-9;?]*[A-Za-z]/g;
 function stripAnsi2(s) {
   return s.replace(ANSI_RE2, "");
 }
-function parseVerdict(text5) {
+function parseVerdict(text6) {
   const re = /VERDICT:\s*(PASS|FAIL)/gi;
   let last = null;
   let m;
-  while ((m = re.exec(text5)) !== null) {
+  while ((m = re.exec(text6)) !== null) {
     last = m[1].toUpperCase();
   }
   return last;
@@ -13226,11 +14290,11 @@ function createInboundWatcher(opts) {
         return;
       }
       const raw = out.result;
-      const text5 = raw?.content?.find((c) => c.type === "text")?.text;
-      if (!text5) return;
+      const text6 = raw?.content?.find((c) => c.type === "text")?.text;
+      if (!text6) return;
       let data;
       try {
-        data = JSON.parse(text5);
+        data = JSON.parse(text6);
       } catch {
         return;
       }
@@ -13646,7 +14710,9 @@ var DEFAULT_ORCHESTRATOR_TOOLS = [
   "policy_attach",
   "policy_status",
   "policy_list",
-  "policy_cancel"
+  "policy_cancel",
+  "permissions_list",
+  "permissions_respond"
 ];
 var DEFAULT_MAX_DEPTH = 3;
 var HARD_MAX_DEPTH = 8;
@@ -13756,7 +14822,7 @@ function createOrchestratorInjector(deps2) {
     return { entry, scope, bindLifecycle };
   };
 }
-function makeBrowserHandle(entry, resolve13) {
+function makeBrowserHandle(entry, resolve12) {
   return {
     slug: entry.id,
     name: entry.name,
@@ -13767,7 +14833,7 @@ function makeBrowserHandle(entry, resolve13) {
     // check() is available for on-demand health probes but is never called
     // by the lister (kit invariant OQ-5). Returns true when the adapter
     // is present in the injected resolver map, false otherwise.
-    check: async () => resolve13 ? resolve13(entry.id) != null : true
+    check: async () => resolve12 ? resolve12(entry.id) != null : true
   };
 }
 var noopLedger = {
@@ -13825,13 +14891,13 @@ async function spawnCloudflaredUntil(argv, opts) {
   };
   let settled = false;
   let forwardedLen = 0;
-  return await new Promise((resolve13, reject) => {
+  return await new Promise((resolve12, reject) => {
     const poll = setInterval(() => {
-      const text5 = readAll();
+      const text6 = readAll();
       if (opts.onLog) {
-        const lastNl = text5.lastIndexOf("\n");
+        const lastNl = text6.lastIndexOf("\n");
         if (lastNl + 1 > forwardedLen) {
-          const chunk = text5.slice(forwardedLen, lastNl + 1);
+          const chunk = text6.slice(forwardedLen, lastNl + 1);
           for (const line of chunk.split(/\r?\n/)) {
             if (line.length > 0) opts.onLog(`[cloudflared] ${line}`);
           }
@@ -13839,11 +14905,11 @@ async function spawnCloudflaredUntil(argv, opts) {
         }
       }
       if (settled) return;
-      const m = text5.match(opts.readyRegex);
+      const m = text6.match(opts.readyRegex);
       if (m) {
         settled = true;
         clearTimeout(timer);
-        resolve13({ proc, match: m[0], stopTail: () => clearInterval(poll) });
+        resolve12({ proc, match: m[0], stopTail: () => clearInterval(poll) });
       }
     }, POLL_INTERVAL_MS);
     if (poll.unref) poll.unref();
@@ -13977,15 +15043,15 @@ function quickTunnelProvider() {
         }
       }, 3e3);
       timer.unref();
-      await new Promise((resolve13) => {
+      await new Promise((resolve12) => {
         if (proc.exitCode !== null) {
           clearTimeout(timer);
-          resolve13();
+          resolve12();
           return;
         }
         proc.once("exit", () => {
           clearTimeout(timer);
-          resolve13();
+          resolve12();
         });
       });
     }
@@ -14224,9 +15290,75 @@ function registerRemoteTools(server, opts) {
     }
   );
 }
+function text3(value) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+      }
+    ]
+  };
+}
+function registerPairingTools(server, opts) {
+  const { registry } = opts;
+  server.tool(
+    "pair_offer",
+    "Mint a one-time pairing offer and start listening for a client on the rendezvous broker. Returns an `agentproto://pair?\u2026` offer URL (share it / render it as a QR), the daemon's identity fingerprint, and the offer expiry. The URL is the bootstrap secret \u2014 it carries the daemon's public keys (MITM-proof against the broker) and a short-lived single-use token. The client runs `agentproto pair accept \"<url>\"`.",
+    {
+      ttlMinutes: z.number().int().min(1).max(1440).optional().describe("Offer time-to-live in minutes (default 10)."),
+      rendezvous: z.string().optional().describe(
+        "Rendezvous WS URL to route through (ws:// or wss://). Defaults to `pairing.rendezvous` from config.json, or the hosted broker (wss://rdv.agentproto.sh/v1) when neither is set. The response's `rendezvousIsHostedDefault` flags when that fallback applied."
+      )
+    },
+    async ({ ttlMinutes, rendezvous }) => {
+      const offer = await registry.createOffer({
+        ...ttlMinutes ? { ttlMs: ttlMinutes * 6e4 } : {},
+        ...rendezvous ? { rendezvousUrl: rendezvous } : {}
+      });
+      return text3({
+        url: offer.url,
+        fingerprint: offer.fingerprint,
+        rendezvous: offer.rendezvousUrl,
+        rendezvousIsHostedDefault: offer.rendezvousIsHostedDefault,
+        expiresAt: new Date(offer.exp * 1e3).toISOString()
+      });
+    }
+  );
+  server.tool(
+    "pair_list",
+    "List clients paired with this daemon: name, fingerprint, when first paired, and last seen. Read-only.",
+    {},
+    async () => {
+      const pairings = await registry.list();
+      return text3({
+        pairings: pairings.map((p) => ({
+          name: p.name,
+          fingerprint: p.fingerprint,
+          createdAt: p.createdAt,
+          lastSeen: p.lastSeen,
+          rendezvous: p.rendezvousUrl
+        }))
+      });
+    }
+  );
+  server.tool(
+    "pair_revoke",
+    "Revoke a pairing by fingerprint or name. Drops its rendezvous connections so the client can no longer reconnect, and removes it from pairings.json.",
+    {
+      target: z.string().describe("The pairing's fingerprint or name (see pair_list).")
+    },
+    async ({ target }) => {
+      const revoked = await registry.revoke(target);
+      return text3(
+        revoked ? { ok: true, revoked: target } : { ok: false, message: `no pairing matched "${target}"` }
+      );
+    }
+  );
+}
 
 // src/daemon-health-tools.ts
-function text3(value) {
+function text4(value) {
   return {
     content: [
       {
@@ -14242,7 +15374,7 @@ function registerDaemonHealthTools(server, opts) {
     "Cheap, side-effect-free liveness probe for this daemon. Returns the same fields as GET /health but in-process. `alive` is always true when the tool returns successfully; if the daemon is unreachable the failure is observed as a thrown/failed tool call at the transport level, not as a false field.",
     {},
     async () => {
-      return text3({
+      return text4({
         alive: true,
         status: "ok",
         workspace: opts.workspace,
@@ -14382,15 +15514,15 @@ function namedTunnelProvider(cfg) {
         }
       }, 3e3);
       timer.unref();
-      await new Promise((resolve13) => {
+      await new Promise((resolve12) => {
         if (proc.exitCode !== null) {
           clearTimeout(timer);
-          resolve13();
+          resolve12();
           return;
         }
         proc.once("exit", () => {
           clearTimeout(timer);
-          resolve13();
+          resolve12();
         });
       });
     }
@@ -14507,14 +15639,14 @@ function ngrokTunnelProvider(opts) {
       });
       child = proc;
       const forwardLogs = (chunk) => {
-        const text5 = chunk.toString("utf8");
-        for (const line of text5.split(/\r?\n/)) {
+        const text6 = chunk.toString("utf8");
+        for (const line of text6.split(/\r?\n/)) {
           if (line.length > 0) opts2.onLog?.(`[ngrok] ${line}`);
         }
       };
       proc.stderr?.on("data", forwardLogs);
       proc.stdout?.on("data", forwardLogs);
-      const url = await new Promise((resolve13, reject) => {
+      const url = await new Promise((resolve12, reject) => {
         let settled = false;
         const timer = setTimeout(() => {
           if (settled) return;
@@ -14542,7 +15674,7 @@ function ngrokTunnelProvider(opts) {
                 settled = true;
                 clearTimeout(timer);
                 if (apiPollHandle) clearInterval(apiPollHandle);
-                resolve13(pubUrl);
+                resolve12(pubUrl);
               }
             } catch {
             }
@@ -14551,16 +15683,16 @@ function ngrokTunnelProvider(opts) {
         };
         const onStdout = (chunk) => {
           if (settled) return;
-          const text5 = chunk.toString("utf8");
-          const reMatch = text5.match(URL_JSON_REGEX);
+          const text6 = chunk.toString("utf8");
+          const reMatch = text6.match(URL_JSON_REGEX);
           if (reMatch) {
             settled = true;
             clearTimeout(timer);
             if (apiPollHandle) clearInterval(apiPollHandle);
-            resolve13(reMatch[1]);
+            resolve12(reMatch[1]);
             return;
           }
-          for (const line of text5.split(/\r?\n/)) {
+          for (const line of text6.split(/\r?\n/)) {
             if (line.length === 0) continue;
             try {
               const parsed = JSON.parse(line);
@@ -14568,7 +15700,7 @@ function ngrokTunnelProvider(opts) {
                 settled = true;
                 clearTimeout(timer);
                 if (apiPollHandle) clearInterval(apiPollHandle);
-                resolve13(parsed.url);
+                resolve12(parsed.url);
                 return;
               }
             } catch {
@@ -14615,15 +15747,15 @@ function ngrokTunnelProvider(opts) {
         }
       }, 3e3);
       timer.unref();
-      await new Promise((resolve13) => {
+      await new Promise((resolve12) => {
         if (proc.exitCode !== null) {
           clearTimeout(timer);
-          resolve13();
+          resolve12();
           return;
         }
         proc.once("exit", () => {
           clearTimeout(timer);
-          resolve13();
+          resolve12();
         });
       });
     }
@@ -14993,7 +16125,7 @@ function makeStubProvider() {
     }
   };
 }
-function text4(value) {
+function text5(value) {
   return {
     content: [
       {
@@ -15057,7 +16189,7 @@ function registerTunnelTools(server, opts) {
           ...input.tunnelId ? { tunnelId: input.tunnelId } : {},
           ...input.credentialsFile ? { credentialsFile: input.credentialsFile } : {}
         });
-        return text4(desc);
+        return text5(desc);
       } catch (err) {
         return errText("tunnel_create", err);
       }
@@ -15078,7 +16210,7 @@ function registerTunnelTools(server, opts) {
           (t) => t.status === "starting" || t.status === "active"
         );
       }
-      return text4({ tunnels });
+      return text5({ tunnels });
     }
   );
   server.tool(
@@ -15103,7 +16235,7 @@ function registerTunnelTools(server, opts) {
             isError: true
           };
         }
-        return text4({ ok, tunnelId: input.tunnelId });
+        return text5({ ok, tunnelId: input.tunnelId });
       } catch (err) {
         return errText("tunnel_stop", err);
       }
@@ -15130,7 +16262,7 @@ function registerTunnelTools(server, opts) {
           isError: true
         };
       }
-      return text4(desc);
+      return text5(desc);
     }
   );
 }
@@ -15294,7 +16426,7 @@ var localSandboxProvider = {
   }
 };
 async function getFreePort() {
-  return new Promise((resolve13, reject) => {
+  return new Promise((resolve12, reject) => {
     const srv = createServer$1();
     srv.once("error", reject);
     srv.listen(0, "127.0.0.1", () => {
@@ -15304,7 +16436,7 @@ async function getFreePort() {
         return;
       }
       const { port } = address;
-      srv.close(() => resolve13(port));
+      srv.close(() => resolve12(port));
     });
   });
 }
@@ -15317,7 +16449,7 @@ async function probeHealth(url, timeoutMs) {
     } catch {
     }
     if (Date.now() >= deadline) return false;
-    await new Promise((resolve13) => setTimeout(resolve13, POLL_INTERVAL_MS2));
+    await new Promise((resolve12) => setTimeout(resolve12, POLL_INTERVAL_MS2));
   }
 }
 
@@ -15625,84 +16757,355 @@ function createWorkspaceFs(opts) {
     }
   };
 }
-var PROVIDER_ENV_VARS = {
-  anthropic: "ANTHROPIC_API_KEY",
-  openrouter: "OPENROUTER_API_KEY",
-  openai: "OPENAI_API_KEY",
-  google: "GOOGLE_GENERATIVE_AI_API_KEY",
-  groq: "GROQ_API_KEY",
-  mistral: "MISTRAL_API_KEY",
-  // Moonshot (Kimi) — an Anthropic-compatible gateway; its key is sent as a
-  // Bearer token (ANTHROPIC_AUTH_TOKEN) with a custom base_url by the claude-sdk
-  // gateway resolver. Native routers (Mastra/hermes) read this env name directly.
-  moonshot: "MOONSHOT_API_KEY",
-  // MiniMax — direct LLM provider (also serves voice/video under the same key).
-  minimax: "MINIMAX_API_KEY",
-  // Vercel AI Gateway — a gateway provider, like openrouter, that fronts many
-  // upstream model families behind one key.
-  "vercel-ai-gateway": "AI_GATEWAY_API_KEY"
-};
-function emptyFile() {
-  return { version: 1, providers: {} };
-}
-function providersPath() {
-  return resolve(homedir(), ".agentproto", "providers.json");
+var PAIRINGS_VERSION = 1;
+var DEFAULT_TTL_MS = 10 * 6e4;
+var DEFAULT_RECONNECT_MIN_MS = 1e3;
+var DEFAULT_RECONNECT_MAX_MS = 3e4;
+var DEFAULT_HANDSHAKE_TIMEOUT_MS = 11e4;
+function defaultPairingsPath() {
+  return join(homedir(), ".agentproto", "pairings.json");
+}
+function b64url(bytes) {
+  return bytes.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function constantTimeEqual(a, b) {
+  const key = randomBytes(32);
+  const da = createHmac("sha256", key).update(a, "utf8").digest();
+  const db = createHmac("sha256", key).update(b, "utf8").digest();
+  return timingSafeEqual(da, db);
+}
+function createPairingRegistry(deps2) {
+  const pairingsPath = deps2.pairingsPath ?? defaultPairingsPath();
+  const now = deps2.now ?? Date.now;
+  const log = deps2.log ?? (() => {
+  });
+  const reconnectMinMs = deps2.reconnectMinMs ?? DEFAULT_RECONNECT_MIN_MS;
+  const reconnectMaxMs = deps2.reconnectMaxMs ?? DEFAULT_RECONNECT_MAX_MS;
+  const handshakeTimeoutMs = deps2.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+  const pairings = /* @__PURE__ */ new Map();
+  const offers = /* @__PURE__ */ new Map();
+  const loops = /* @__PURE__ */ new Map();
+  const channels = /* @__PURE__ */ new Set();
+  let shuttingDown = false;
+  let loaded = false;
+  async function ensureLoaded() {
+    if (loaded) return;
+    loaded = true;
+    try {
+      const raw = await readFile(pairingsPath, "utf8");
+      const parsed = JSON.parse(raw);
+      if (isPairingsFile(parsed)) {
+        for (const rec of parsed.pairings) pairings.set(rec.fingerprint, rec);
+      }
+    } catch (err) {
+      if (!isEnoent(err)) {
+        log(`[pairing] could not read ${pairingsPath}: ${errMsg(err)}`);
+      }
+    }
+  }
+  async function persist() {
+    const file = {
+      v: PAIRINGS_VERSION,
+      pairings: Array.from(pairings.values())
+    };
+    const dir = dirname(pairingsPath);
+    await mkdir(dir, { recursive: true });
+    const tmp = join(dir, `.${basename(pairingsPath)}.tmp-${process.pid}`);
+    await writeFile(tmp, JSON.stringify(file, null, 2) + "\n", { encoding: "utf8", mode: 384 });
+    await chmod(tmp, 384).catch(() => {
+    });
+    await rename(tmp, pairingsPath);
+  }
+  function startLoop(spec) {
+    if (loops.has(spec.key)) return;
+    const abort = new AbortController();
+    const done = runLoop(spec, abort.signal).catch((err) => {
+      log(`[pairing] loop ${spec.key} ended: ${errMsg(err)}`);
+    });
+    loops.set(spec.key, { abort, done });
+  }
+  async function stopLoop(key) {
+    const loop = loops.get(key);
+    if (!loop) return;
+    loops.delete(key);
+    loop.abort.abort();
+    await loop.done.catch(() => {
+    });
+  }
+  async function runLoop(spec, signal) {
+    let backoff = reconnectMinMs;
+    while (!signal.aborted && spec.shouldContinue()) {
+      const expected = spec.token();
+      let sink;
+      try {
+        sink = await deps2.dial(dialUrl(spec.rendezvousUrl, expected), signal);
+      } catch (err) {
+        if (signal.aborted) break;
+        log(`[pairing] dial ${spec.key} failed: ${errMsg(err)}`);
+        await sleep(backoff, signal);
+        backoff = Math.min(backoff * 2, reconnectMaxMs);
+        continue;
+      }
+      const onAbort = () => {
+        try {
+          sink.close("registry shutdown");
+        } catch {
+        }
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      try {
+        let capturedSession = null;
+        let capturedHello = null;
+        let wrapped;
+        try {
+          const identity = await deps2.loadIdentity();
+          wrapped = await daemonHandshakeOverSink(
+            sink,
+            (helloBytes) => {
+              const hello = decodePairingHello(helloBytes);
+              const result = respondToHandshake(hello, {
+                identity,
+                verifyOfferToken: (presented) => spec.verify(presented, expected)
+              });
+              capturedSession = result.session;
+              capturedHello = hello;
+              return { reply: encodePairingMessage(result.reply), keys: result.session };
+            },
+            { timeoutMs: handshakeTimeoutMs }
+          );
+        } catch (err) {
+          if (signal.aborted) break;
+          void err;
+          await sleep(backoff, signal);
+          backoff = Math.min(backoff * 2, reconnectMaxMs);
+          continue;
+        }
+        backoff = reconnectMinMs;
+        if (!capturedSession || !capturedHello) {
+          wrapped.close("internal: missing session");
+          continue;
+        }
+        let ctx;
+        try {
+          ctx = await spec.onPaired(capturedSession, capturedHello);
+        } catch (err) {
+          log(`[pairing] persist for ${spec.key} failed: ${errMsg(err)}`);
+          wrapped.close("persist failed");
+          continue;
+        }
+        const handle = deps2.serve(wrapped, ctx);
+        channels.add(handle);
+        log(`[pairing] channel up (${ctx.mode}) for ${ctx.fingerprint} via ${spec.key}`);
+        await waitClosed(wrapped, signal);
+        channels.delete(handle);
+        await handle.close().catch(() => {
+        });
+        log(`[pairing] channel closed (${ctx.mode}) for ${ctx.fingerprint}`);
+        if (spec.singleUse) break;
+      } finally {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
+  }
+  async function createOffer(input = {}) {
+    await ensureLoaded();
+    let rendezvousUrl;
+    let rendezvousIsHostedDefault = false;
+    if (input.rendezvousUrl) {
+      rendezvousUrl = input.rendezvousUrl;
+    } else if (deps2.defaultRendezvousUrl !== void 0) {
+      if (deps2.defaultRendezvousUrl === "") {
+        throw new PairingError(
+          "malformed_offer",
+          'rendezvous disabled \u2014 pairing.rendezvous is set to "" (explicit opt-out); pass --rendezvous to route this offer through a specific broker'
+        );
+      }
+      rendezvousUrl = deps2.defaultRendezvousUrl;
+    } else {
+      rendezvousUrl = HOSTED_RENDEZVOUS_URL;
+      rendezvousIsHostedDefault = true;
+    }
+    const identity = await deps2.loadIdentity();
+    const token = b64url(randomBytes(16));
+    const ttlMs = input.ttlMs ?? DEFAULT_TTL_MS;
+    const exp = Math.floor((now() + ttlMs) / 1e3);
+    offers.set(token, { token, exp, spent: false, rendezvousUrl });
+    const fingerprint = identityFingerprint(identity.x25519.pub);
+    const url = encodeOfferUrl({
+      v: 1,
+      rendezvousUrl,
+      fingerprint,
+      daemonX25519Pub: identity.x25519.pub,
+      daemonEd25519Pub: identity.ed25519.pub,
+      token,
+      exp
+    });
+    startOfferLoop(token, rendezvousUrl);
+    log(
+      `[pairing] offer minted (exp ${new Date(exp * 1e3).toISOString()}) via ${rendezvousUrl}` + (rendezvousIsHostedDefault ? " (hosted default)" : "")
+    );
+    return { token, exp, url, fingerprint, rendezvousUrl, rendezvousIsHostedDefault };
+  }
+  function offerValid(token) {
+    const entry = offers.get(token);
+    return !!entry && !entry.spent && entry.exp * 1e3 > now();
+  }
+  function startOfferLoop(token, rendezvousUrl) {
+    startLoop({
+      key: `offer:${token}`,
+      rendezvousUrl,
+      token: () => token,
+      shouldContinue: () => offerValid(token),
+      singleUse: true,
+      verify: (presented, expected) => {
+        const entry = offers.get(expected);
+        if (!entry || entry.spent || entry.exp * 1e3 <= now()) return false;
+        if (!constantTimeEqual(presented, expected)) return false;
+        entry.spent = true;
+        return true;
+      },
+      onPaired: async (session, hello) => {
+        const pairRoot = derivePairRoot(session);
+        const fingerprint = session.peerFingerprint;
+        const nowIso = new Date(now()).toISOString();
+        const record = {
+          clientPub: hello.ePub,
+          name: session.clientName ?? fingerprint,
+          fingerprint,
+          createdAt: pairings.get(fingerprint)?.createdAt ?? nowIso,
+          lastSeen: nowIso,
+          pairRoot,
+          rendezvousUrl
+        };
+        pairings.set(fingerprint, record);
+        await persist();
+        startReconnectLoops(record);
+        return { mode: "offer", fingerprint, name: record.name };
+      }
+    });
+  }
+  function startReconnectLoops(record) {
+    for (const slot of ["cur", "prev"]) {
+      const epochOf = () => slot === "cur" ? currentEpoch(now()) : currentEpoch(now()) - 1;
+      startLoop({
+        key: `pair:${record.fingerprint}:${slot}`,
+        rendezvousUrl: record.rendezvousUrl,
+        token: () => deriveEpochRoutingToken(record.pairRoot, epochOf()),
+        shouldContinue: () => pairings.has(record.fingerprint),
+        singleUse: false,
+        verify: (presented, expected) => constantTimeEqual(presented, expected),
+        onPaired: async (session, _hello) => {
+          const existing = pairings.get(record.fingerprint);
+          if (existing) {
+            existing.lastSeen = new Date(now()).toISOString();
+            await persist().catch((err) => log(`[pairing] lastSeen persist failed: ${errMsg(err)}`));
+          }
+          return {
+            mode: "reconnect",
+            fingerprint: record.fingerprint,
+            name: existing?.name ?? record.name
+          };
+        }
+      });
+    }
+  }
+  async function startAutoconnect() {
+    await ensureLoaded();
+    for (const record of pairings.values()) {
+      startReconnectLoops(record);
+    }
+    if (pairings.size > 0) {
+      log(`[pairing] autoconnect: standing connections for ${pairings.size} pairing(s)`);
+    }
+  }
+  async function revoke(idOrName) {
+    await ensureLoaded();
+    let target = pairings.get(idOrName);
+    if (!target) {
+      for (const rec of pairings.values()) {
+        if (rec.name === idOrName) {
+          target = rec;
+          break;
+        }
+      }
+    }
+    if (!target) return false;
+    pairings.delete(target.fingerprint);
+    await persist();
+    await stopLoop(`pair:${target.fingerprint}:cur`);
+    await stopLoop(`pair:${target.fingerprint}:prev`);
+    log(`[pairing] revoked ${target.fingerprint} (${target.name})`);
+    return true;
+  }
+  async function list() {
+    await ensureLoaded();
+    return Array.from(pairings.values()).map((r) => ({ ...r }));
+  }
+  async function shutdown() {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    for (const key of Array.from(loops.keys())) {
+      await stopLoop(key);
+    }
+    for (const handle of Array.from(channels)) {
+      await handle.close().catch(() => {
+      });
+    }
+    channels.clear();
+  }
+  return { createOffer, list, revoke, startAutoconnect, shutdown };
 }
-function providerEnvVar(provider) {
-  return PROVIDER_ENV_VARS[provider] ?? `${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`;
+function dialUrl(rendezvousUrl, token) {
+  const sep = rendezvousUrl.includes("?") ? "&" : "?";
+  return `${rendezvousUrl}${sep}side=daemon&t=${encodeURIComponent(token)}`;
 }
-async function loadProviders() {
-  try {
-    const raw = await readFile(providersPath(), "utf8");
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== "object" || !("providers" in parsed) || typeof parsed.providers !== "object" || parsed.providers === null) {
-      return emptyFile();
+function waitClosed(sink, signal) {
+  return new Promise((resolve12) => {
+    if (!sink.isOpen) {
+      resolve12();
+      return;
     }
-    return {
-      version: 1,
-      providers: parsed.providers
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      resolve12();
     };
-  } catch {
-    return emptyFile();
-  }
+    sink.onClose(() => finish());
+    signal.addEventListener("abort", () => {
+      sink.close("registry shutdown");
+      finish();
+    });
+  });
 }
-async function writeProviders(file) {
-  const dir = join(homedir(), ".agentproto");
-  await mkdir(dir, { recursive: true });
-  await writeFile(providersPath(), JSON.stringify(file, null, 2) + "\n", {
-    encoding: "utf8",
-    mode: 384
+function sleep(ms, signal) {
+  return new Promise((resolve12) => {
+    if (signal.aborted) return resolve12();
+    const timer = setTimeout(resolve12, ms);
+    if (typeof timer.unref === "function") timer.unref();
+    signal.addEventListener("abort", () => {
+      clearTimeout(timer);
+      resolve12();
+    });
   });
 }
-async function setProviderKey(provider, apiKey, baseUrl) {
-  const file = await loadProviders();
-  file.providers[provider] = {
-    apiKey,
-    ...baseUrl ? { baseUrl } : {},
-    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  await writeProviders(file);
-  return providerEnvVar(provider);
-}
-async function removeProviderKey(provider) {
-  const file = await loadProviders();
-  if (!(provider in file.providers)) return false;
-  delete file.providers[provider];
-  await writeProviders(file);
-  return true;
+function isPairingsFile(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const rec = v;
+  if (rec["v"] !== PAIRINGS_VERSION) return false;
+  if (!Array.isArray(rec["pairings"])) return false;
+  return rec["pairings"].every(isPairingRecord);
 }
-async function injectProviderKeysIntoEnv(env = process.env) {
-  const file = await loadProviders();
-  const injected = [];
-  for (const [provider, entry] of Object.entries(file.providers)) {
-    if (!entry?.apiKey) continue;
-    const name = providerEnvVar(provider);
-    if (env[name]) continue;
-    env[name] = entry.apiKey;
-    if (entry.baseUrl) env[`${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_BASE_URL`] = entry.baseUrl;
-    injected.push(provider);
-  }
-  return injected;
+function isPairingRecord(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v;
+  return typeof r["clientPub"] === "string" && typeof r["name"] === "string" && typeof r["fingerprint"] === "string" && typeof r["createdAt"] === "string" && typeof r["lastSeen"] === "string" && typeof r["pairRoot"] === "string" && typeof r["rendezvousUrl"] === "string";
+}
+function isEnoent(err) {
+  return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
 }
 
 // src/index.ts
@@ -15714,7 +17117,9 @@ var DEFAULT_ALWAYS_ON_TOOLS = [
   "agent_kill",
   "session_list",
   "session_monitor",
-  "session_events_poll"
+  "session_events_poll",
+  "permissions_list",
+  "permissions_respond"
 ];
 async function createGateway(opts) {
   const startedAt = Date.now();
@@ -15891,6 +17296,9 @@ async function createGateway(opts) {
     registerDaemonHealthTools(server, { workspace, registered, startedAt });
     registerCommandTools(server, { workspace, registry: sessions });
     registerRemoteTools(server, { controller: remote });
+    if (opts.pairingRegistry) {
+      registerPairingTools(server, { registry: opts.pairingRegistry });
+    }
     registerSessionTools(server, {
       registry: sessions,
       mcpProxy,
@@ -16038,6 +17446,7 @@ async function createGateway(opts) {
     token,
     ptyEnabled: opts.spawnPty != null,
     tunnels,
+    ...opts.pairingRegistry ? { pairings: opts.pairingRegistry } : {},
     sessionEvents,
     eventRing,
     supervisor,
@@ -16082,6 +17491,7 @@ async function createGateway(opts) {
     registered,
     sessions,
     tunnels,
+    ...opts.pairingRegistry ? { pairing: opts.pairingRegistry } : {},
     token,
     mintOrchestratorScope: scopeTokens.mint,
     async stop() {
@@ -16090,6 +17500,10 @@ async function createGateway(opts) {
       cronScheduler.shutdown();
       supervisor.shutdown();
       sessions.shutdown();
+      if (opts.pairingRegistry) {
+        await opts.pairingRegistry.shutdown().catch(() => {
+        });
+      }
       await mcpProxy.closeAll();
       await tunnels.shutdown();
       await remote.shutdown();
@@ -16125,7 +17539,15 @@ async function runBoot(workspace, opts, conversations, events) {
     durationMs: 0
   });
 }
+var export_PROVIDER_ENV_VARS = providers_store_exports.PROVIDER_ENV_VARS;
+var export_getProviderKey = providers_store_exports.getProviderKey;
+var export_injectProviderKeysIntoEnv = providers_store_exports.injectProviderKeysIntoEnv;
+var export_loadProviders = providers_store_exports.loadProviders;
+var export_providerEnvVar = providers_store_exports.providerEnvVar;
+var export_providersPath = providers_store_exports.providersPath;
+var export_removeProviderKey = providers_store_exports.removeProviderKey;
+var export_setProviderKey = providers_store_exports.setProviderKey;
 
-export { DEFAULT_ORCHESTRATOR_TOOLS, PROVIDER_ENV_VARS, composeSessionObservers, createFileStepCache, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createScopeTokenRegistry, createWorkspaceFs, daemonRegistryDir, declaredPresetToProviderPreset, deriveSessionUsage, fileConversationStore, formatToolCall, formatToolResult, getMcpCredentialDeps, injectProviderKeysIntoEnv, listPresets, loadProviders, makeBrowserAdapterLister, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, parseDuration, projectSessionUsage, providerEnvVar, providersPath, readDaemonRegistry, readRuntimeMeta, removeProviderKey, setMcpCredentialDeps, setProviderKey, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };
+export { AuthResolutionError, DEFAULT_ORCHESTRATOR_TOOLS, PAIRINGS_VERSION, export_PROVIDER_ENV_VARS as PROVIDER_ENV_VARS, composeSessionObservers, createFileStepCache, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createScopeTokenRegistry, createWorkspaceFs, credentialFingerprint, daemonRegistryDir, declaredPresetToProviderPreset, deriveSessionUsage, fileConversationStore, formatToolCall, formatToolResult, getMcpCredentialDeps, export_getProviderKey as getProviderKey, export_injectProviderKeysIntoEnv as injectProviderKeysIntoEnv, listPresets, export_loadProviders as loadProviders, makeBrowserAdapterLister, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, normalizeSkillsOption, parseDuration, projectSessionUsage, export_providerEnvVar as providerEnvVar, export_providersPath as providersPath, readDaemonRegistry, readRuntimeMeta, registerPairingTools, export_removeProviderKey as removeProviderKey, resolveAuthSpec, resolveSpawnDefaults, setMcpCredentialDeps, export_setProviderKey as setProviderKey, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map