@agentproto/runtime 0.7.0 → 1.0.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { createReadStream, existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, renameSync, promises, createWriteStream, statSync, openSync, closeSync } from 'fs';
+import { createReadStream, existsSync, promises, readdirSync, readFileSync, mkdirSync, writeFileSync, renameSync, createWriteStream, statSync, openSync, closeSync } from 'fs';
 import { homedir, tmpdir } from 'os';
 import { join, resolve, dirname, isAbsolute, normalize, relative, basename } from 'path';
 import { createInterface } from 'readline';
@@ -12,10 +12,12 @@ 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 { eligibleProfiles, getAuthProfile, KeychainStore } from '@agentproto/auth';
 import matter from 'gray-matter';
 import { createServer } from 'http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { WebSocketServer } from 'ws';
+import { resolveLlmModelRoute, formatModelRef, tryParseModelRef } from '@agentproto/model-catalog/route-identity';
 import { anthropicGatewayPresetList } from '@agentproto/provider-presets';
 import { createIngestionClient } from '@agentproto/telemetry-langfuse';
 import { resolveRedactor } from '@agentproto/redaction';
@@ -33,6 +35,7 @@ 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';
+import { inferLegacyModeKind } from '@agentproto/driver-agent-cli';
 
 /**
  * @agentproto/runtime v0.1.0-alpha
@@ -445,6 +448,156 @@ var init_transcript_writer = __esm({
     DEBOUNCE_MS = 250;
   }
 });
+function claudeProjectSlug(cwd) {
+  return cwd.replace(/[^a-zA-Z0-9]/g, "-");
+}
+function claudeCodeProjectDir(cwd) {
+  return resolve(homedir(), ".claude", "projects", claudeProjectSlug(cwd));
+}
+function extractFirstText(content) {
+  if (typeof content === "string") {
+    const t = content.trim();
+    return t || void 0;
+  }
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
+        const t = block.text.trim();
+        if (t) return t;
+      }
+    }
+  }
+  return void 0;
+}
+async function scanClaudeJsonl(filePath) {
+  const stream = createReadStream(filePath, { encoding: "utf8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  let startedAt;
+  let lastActivityAt;
+  let messageCount = 0;
+  let preview2;
+  let lastWriter;
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry;
+    try {
+      entry = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (typeof entry.timestamp === "string") {
+      if (!startedAt) startedAt = entry.timestamp;
+      lastActivityAt = entry.timestamp;
+    }
+    if (typeof entry.entrypoint === "string") {
+      lastWriter = entry.entrypoint;
+    }
+    if (entry.type === "user" || entry.type === "assistant") {
+      messageCount += 1;
+      if (preview2 === void 0 && entry.type === "user") {
+        const text6 = extractFirstText(entry.message?.content);
+        if (text6 !== void 0) {
+          preview2 = text6.length > 120 ? text6.slice(0, 120) : text6;
+        }
+      }
+    }
+  }
+  return { startedAt, lastActivityAt, messageCount, preview: preview2, lastWriter };
+}
+async function buildClaudeCandidate(filePath, conversationId) {
+  const scanned = await scanClaudeJsonl(filePath);
+  return { conversationId, ...scanned };
+}
+function claudeEntrypointFor(mode) {
+  return mode === "native" ? "cli" : "sdk-ts";
+}
+async function discoverClaudeCode(input) {
+  const { cwd, since, until, attachmentMode, expectedId } = input;
+  const dir = claudeCodeProjectDir(cwd);
+  if (expectedId) {
+    const filePath = join(dir, `${expectedId}.jsonl`);
+    try {
+      await promises.stat(filePath);
+    } catch {
+      return [];
+    }
+    return [await buildClaudeCandidate(filePath, expectedId)];
+  }
+  let entries;
+  try {
+    entries = await promises.readdir(dir);
+  } catch {
+    return [];
+  }
+  const jsonlFiles = entries.filter((e) => e.endsWith(".jsonl"));
+  if (jsonlFiles.length === 0) return [];
+  const sinceMs = since ? Date.parse(since) : NaN;
+  const untilMs = until ? Date.parse(until) : NaN;
+  const wantEntrypoint = attachmentMode ? claudeEntrypointFor(attachmentMode) : void 0;
+  const scored = [];
+  for (const f of jsonlFiles) {
+    const filePath = join(dir, f);
+    let mtimeMs;
+    try {
+      mtimeMs = (await promises.stat(filePath)).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (Number.isFinite(sinceMs) && mtimeMs < sinceMs - 1e3) continue;
+    const conversationId = f.replace(/\.jsonl$/, "");
+    const candidate = await buildClaudeCandidate(filePath, conversationId);
+    if (Number.isFinite(untilMs) && candidate.startedAt !== void 0) {
+      const startedMs = Date.parse(candidate.startedAt);
+      if (Number.isFinite(startedMs) && startedMs > untilMs) continue;
+    }
+    if (wantEntrypoint !== void 0 && candidate.lastWriter !== void 0 && candidate.lastWriter !== wantEntrypoint) {
+      continue;
+    }
+    scored.push({ candidate, mtimeMs });
+  }
+  scored.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return scored.map((s) => s.candidate);
+}
+async function readClaudeCode(conversationId, cwd) {
+  const { exportClaudeCodeSession: exportClaudeCodeSession2 } = await Promise.resolve().then(() => (init_transcript_export(), transcript_export_exports));
+  return exportClaudeCodeSession2(conversationId, cwd);
+}
+async function discoverHermes(input) {
+  const { discoverHermesSessions: discoverHermesSessions2 } = await Promise.resolve().then(() => (init_transcript_export(), transcript_export_exports));
+  return discoverHermesSessions2(input.cwd, input.since, input.expectedId);
+}
+async function readHermes(conversationId) {
+  const { exportHermesSession: exportHermesSession2 } = await Promise.resolve().then(() => (init_transcript_export(), transcript_export_exports));
+  return exportHermesSession2(conversationId);
+}
+var CONVERSATION_STORES;
+var init_conversation_store = __esm({
+  "src/conversation-store.ts"() {
+    CONVERSATION_STORES = {
+      "claude-code": {
+        storeAs: "claudeResumeId",
+        // Printed by claude on graceful exit when session persistence is on
+        // (default). Example: `claude --resume 0e483f81-1a44-4bec-9667-b37158450296`
+        outputHint: /claude\s+--resume\s+([0-9a-f-]{8,})/i,
+        attachArgv: (conversationId) => ["claude", "--resume", conversationId],
+        discover: discoverClaudeCode,
+        read: readClaudeCode
+      },
+      hermes: {
+        storeAs: "hermesResumeId",
+        // `hermes acp` is the ACP arm (bin_args in adapters/hermes/src/index.ts);
+        // `--resume SESSION --tui` is the native TUI resume path — same binary,
+        // different flags, unlike claude-code where the two arms are different
+        // binaries. Verified via `hermes --help`: `--resume SESSION, -r` =
+        // "Resume a previous session by ID or title", `--tui` = the real TUI.
+        attachArgv: (conversationId) => ["hermes", "--resume", conversationId, "--tui"],
+        discover: discoverHermes,
+        read: readHermes
+      }
+    };
+  }
+});
 
 // src/transcript-export.ts
 var transcript_export_exports = {};
@@ -549,7 +702,7 @@ async function exportClaudeCodeSession(adapterSessionId, cwd) {
       "claude-code exporter: cwd is required to locate the JSONL file.\nPass cwd explicitly or use a session id that is in the registry."
     );
   }
-  const encoded = cwd.replace(/\//g, "-");
+  const encoded = claudeProjectSlug(cwd);
   const filePath = join(homedir(), ".claude", "projects", encoded, `${adapterSessionId}.jsonl`);
   let stream;
   try {
@@ -1057,6 +1210,7 @@ var init_transcript_export = __esm({
   "src/transcript-export.ts"() {
     init_tool_presenter();
     init_transcript_writer();
+    init_conversation_store();
     ROLE_ICON = {
       user: "\u{1F9D1} User",
       assistant: "\u{1F916} Assistant",
@@ -1743,6 +1897,61 @@ function loadWorkspacesConfigSync(path = DEFAULT_CONFIG_PATH()) {
   }
   return normalizeConfig(parsed);
 }
+async function saveWorkspacesConfig(config, path = DEFAULT_CONFIG_PATH()) {
+  const normalized = normalizeConfig(config);
+  await promises.mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  await promises.writeFile(tmp, JSON.stringify(normalized, null, 2) + "\n", "utf8");
+  await promises.rename(tmp, path);
+}
+function addWorkspace(config, input) {
+  if (!isAbsolute(input.path)) {
+    throw new Error(
+      `addWorkspace: path must be absolute, got "${input.path}".`
+    );
+  }
+  const slug = sanitizeSlug(input.slug);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const existingIdx = config.workspaces.findIndex((w) => w.slug === slug);
+  const next = existingIdx >= 0 ? {
+    ...config.workspaces[existingIdx],
+    path: input.path,
+    ...input.label !== void 0 ? { label: input.label } : {},
+    updatedAt: now
+  } : {
+    slug,
+    path: input.path,
+    ...input.label ? { label: input.label } : {},
+    addedAt: now,
+    updatedAt: now
+  };
+  const workspaces = [...config.workspaces];
+  if (existingIdx >= 0) workspaces[existingIdx] = next;
+  else workspaces.push(next);
+  const active = config.active ?? slug;
+  return { ...config, workspaces, active };
+}
+function removeWorkspace(config, slug) {
+  const sanitised = sanitizeSlug(slug);
+  const workspaces = config.workspaces.filter((w) => w.slug !== sanitised);
+  let active = config.active;
+  if (active === sanitised) {
+    active = workspaces[0]?.slug;
+  }
+  const next = { ...config, workspaces };
+  if (active !== void 0) next.active = active;
+  else delete next.active;
+  return next;
+}
+function setActiveWorkspace(config, slug) {
+  const sanitised = sanitizeSlug(slug);
+  if (!config.workspaces.some((w) => w.slug === sanitised)) {
+    throw new Error(
+      `setActiveWorkspace: no workspace registered with slug "${sanitised}". Run \`agentproto workspace add <path> --slug ${sanitised}\` first.`
+    );
+  }
+  return { ...config, active: sanitised };
+}
 function findWorkspace(config, slug) {
   return config.workspaces.find((w) => w.slug === sanitizeSlug(slug));
 }
@@ -1809,7 +2018,7 @@ function sanitizeAcpAgents(raw, target) {
   return Object.keys(out).length > 0 ? out : void 0;
 }
 async function loadConfig(path) {
-  const target = CONFIG_FILE_PATH();
+  const target = path ?? CONFIG_FILE_PATH();
   try {
     const raw = await promises.readFile(target, "utf8");
     const parsed = JSON.parse(raw);
@@ -1900,6 +2109,7 @@ function resolveAuthSpec(input) {
   const subCredAvailable = input.subscriptionCredential !== void 0;
   const apiCredAvailable = input.apiKeyConfigCredential !== void 0 || input.apiKeyStoreCredential !== void 0;
   let mode;
+  let neitherConfigured = false;
   if (input.requestedMode) {
     if (input.requestedMode === "subscription" && !supportsSub) {
       throw new AuthResolutionError(
@@ -1909,7 +2119,11 @@ function resolveAuthSpec(input) {
     mode = input.requestedMode;
   } else {
     const preference = supportsSub ? ["subscription", "api-key"] : ["api-key"];
-    mode = preference.find((m) => m === "subscription" ? subCredAvailable : apiCredAvailable) ?? preference[0];
+    const available = preference.find(
+      (m) => m === "subscription" ? subCredAvailable : apiCredAvailable
+    );
+    mode = available ?? preference[0];
+    neitherConfigured = available === void 0;
   }
   let setEnv;
   let credential;
@@ -1945,7 +2159,8 @@ function resolveAuthSpec(input) {
     setEnv,
     unsetEnv,
     explicit: input.explicit,
-    enforce
+    enforce,
+    ...neitherConfigured ? { neitherConfigured } : {}
   };
   const echo = {
     provider,
@@ -2209,6 +2424,8 @@ function getMcpCredentialDeps() {
 // src/sandbox-agent-session-proxy.ts
 var MAX_POLL_MS = 49e3;
 var MAX_OUTPUT_LINES = 500;
+var MAX_CONSECUTIVE_POLL_FAILURES = 6;
+var POLL_RETRY_DELAY_MS = 5e3;
 function extractPromptText(message) {
   if (typeof message === "string") return message;
   if (message && typeof message === "object" && "text" in message) {
@@ -2226,29 +2443,63 @@ function createSandboxAgentSessionProxy(opts) {
     async *send(message) {
       const prompt = extractPromptText(message);
       lastPrompt = prompt;
-      await host.prompt(remoteSessionId, prompt);
       let seenLength = 0;
-      for (; ; ) {
-        const result = await host.waitForAny([remoteSessionId], {
-          event: "any",
-          timeoutMs: MAX_POLL_MS
-        });
-        if (result.timedOut) continue;
-        const tail = await host.output(remoteSessionId, MAX_OUTPUT_LINES);
-        if (tail.length > seenLength) {
-          yield { kind: "text-delta", text: tail.slice(seenLength) };
+      try {
+        await host.prompt(remoteSessionId, prompt);
+        let consecutivePollFailures = 0;
+        for (; ; ) {
+          let result;
+          try {
+            result = await host.waitForAny([remoteSessionId], {
+              event: "any",
+              timeoutMs: MAX_POLL_MS
+            });
+            consecutivePollFailures = 0;
+          } catch (pollErr) {
+            consecutivePollFailures++;
+            if (consecutivePollFailures >= MAX_CONSECUTIVE_POLL_FAILURES) {
+              throw new Error(
+                `sandbox proxy: ${consecutivePollFailures} consecutive poll failures against the box daemon (session "${remoteSessionId}") \u2014 giving up. Last error: ${pollErr instanceof Error ? pollErr.message : String(pollErr)}`
+              );
+            }
+            await new Promise((resolve14) => setTimeout(resolve14, POLL_RETRY_DELAY_MS));
+            continue;
+          }
+          if (result.timedOut) continue;
+          let tail;
+          try {
+            tail = await host.output(remoteSessionId, MAX_OUTPUT_LINES);
+          } catch {
+            try {
+              tail = await host.output(remoteSessionId, MAX_OUTPUT_LINES);
+            } catch {
+              tail = void 0;
+            }
+          }
+          if (tail !== void 0 && tail.length > seenLength) {
+            yield { kind: "text-delta", text: tail.slice(seenLength) };
+          }
+          if (tail !== void 0) seenLength = tail.length;
+          if (result.event === "exited") {
+            throw new Error(
+              `sandbox proxy: remote session "${remoteSessionId}" exited \u2014 the box's own agentproto daemon ended this session (crash, OOM, or an out-of-band kill).`
+            );
+          }
+          yield {
+            kind: "turn-end",
+            reason: result.event === "awaiting-input" ? "awaiting-input" : "completed"
+          };
+          return;
         }
-        seenLength = tail.length;
-        if (result.event === "exited") {
-          throw new Error(
-            `sandbox proxy: remote session "${remoteSessionId}" exited \u2014 the box's own agentproto daemon ended this session (crash, OOM, or an out-of-band kill).`
-          );
+      } catch (err) {
+        try {
+          const tail = await host.output(remoteSessionId, MAX_OUTPUT_LINES);
+          if (tail.length > seenLength) {
+            yield { kind: "text-delta", text: tail.slice(seenLength) };
+          }
+        } catch {
         }
-        yield {
-          kind: "turn-end",
-          reason: result.event === "awaiting-input" ? "awaiting-input" : "completed"
-        };
-        return;
+        throw err;
       }
     },
     async cancel() {
@@ -2271,6 +2522,50 @@ function createSandboxAgentSessionProxy(opts) {
   };
 }
 
+// src/worktree-isolation.ts
+var WORKTREE_ISOLATION_ENV = "AGENTPROTO_WORKTREES_ISOLATION";
+var DEFAULT_WORKTREE_ISOLATION = "on-request";
+function normalizeWorktreeField(field) {
+  if (field === void 0 || field === false) return void 0;
+  if (field === true) return {};
+  const request = {};
+  if (field.slug !== void 0) request.slug = field.slug;
+  if (field.base !== void 0) request.base = field.base;
+  return request;
+}
+function decideWorktreeIsolation(input) {
+  const request = normalizeWorktreeField(input.field);
+  if (input.depth > 0) return { action: "spawn-in-place" };
+  switch (input.mode) {
+    case "never":
+      if (request !== void 0) {
+        return {
+          action: "reject",
+          message: `agent_start: \`worktree\` was requested but this daemon's \`worktrees.isolation\` policy is set to "never". Remove the \`worktree\` field, or change the policy (config \`worktrees.isolation\` / env ${WORKTREE_ISOLATION_ENV}).`
+        };
+      }
+      return { action: "spawn-in-place" };
+    case "on-request":
+      return request !== void 0 ? { action: "provision", request } : { action: "spawn-in-place" };
+    case "always":
+      return { action: "provision", request: request ?? {} };
+  }
+}
+function parseWorktreeIsolationMode(raw) {
+  return raw === "always" || raw === "on-request" || raw === "never" ? raw : void 0;
+}
+async function loadWorktreeIsolation(loadCfg = loadConfig) {
+  const fromEnv = parseWorktreeIsolationMode(process.env[WORKTREE_ISOLATION_ENV]);
+  if (fromEnv) return fromEnv;
+  try {
+    const cfg = await loadCfg();
+    const fromCfg = parseWorktreeIsolationMode(cfg.worktrees?.isolation);
+    if (fromCfg) return fromCfg;
+  } catch {
+  }
+  return DEFAULT_WORKTREE_ISOLATION;
+}
+
 // src/session-spawn.ts
 var SPAWN_CLAIM_WINDOW_MS = 3e4;
 var spawnClaimsByRegistry = /* @__PURE__ */ new WeakMap();
@@ -2298,8 +2593,20 @@ async function spawnAgentSession(deps2, input) {
     callerScope,
     webhookNotifier,
     loadDefaultsConfig,
-    resolveSandboxProvider: resolveSandboxProvider2
+    resolveSandboxProvider: resolveSandboxProvider2,
+    provisionWorktree,
+    resolveWorktreeIsolation
   } = deps2;
+  const explicitCwd = input.cwd !== void 0;
+  const explicitWorkspaceSlug = input.workspaceSlug !== void 0;
+  const childDepth = callerScope ? callerScope.depth + 1 : 0;
+  if (childDepth === 0 && !explicitCwd && !explicitWorkspaceSlug && normalizeWorktreeField(input.worktree) !== void 0) {
+    return {
+      ok: false,
+      code: "worktree_requires_explicit_repo",
+      message: "agent_start: `worktree` isolation was requested but neither `cwd` nor `workspaceSlug` was passed \u2014 refusing to guess the base repo from the daemon's active workspace. Pass `cwd` (an explicit path inside the repo to worktree from) or `workspaceSlug` (a slug from `agentproto workspace list`) to `agent_start`."
+    };
+  }
   let cwd = input.cwd;
   let resolvedSlug = input.workspaceSlug;
   if (!cwd || !resolvedSlug) {
@@ -2336,7 +2643,6 @@ async function spawnAgentSession(deps2, input) {
       message: `agent_start: adapter "${input.adapter}" could not be resolved. If it was working a moment ago, something may be mid-rebuild \u2014 wait and retry. If it has never been installed, run \`agentproto install ${input.adapter}\` first.`
     };
   }
-  const childDepth = callerScope ? callerScope.depth + 1 : 0;
   const parentSessionId = callerScope?.ownerSessionId;
   if (callerScope) {
     if (childDepth > callerScope.maxDepth) {
@@ -2366,6 +2672,35 @@ async function spawnAgentSession(deps2, input) {
       };
     }
   }
+  let worktreeRequest;
+  if (input.sandbox === void 0) {
+    const mode = resolveWorktreeIsolation ? await resolveWorktreeIsolation() : await loadWorktreeIsolation();
+    const decision = decideWorktreeIsolation({
+      mode,
+      field: input.worktree,
+      depth: childDepth
+    });
+    if (decision.action === "reject") {
+      return { ok: false, code: "worktree_disabled", message: decision.message };
+    }
+    if (decision.action === "provision") {
+      if (!explicitCwd && !explicitWorkspaceSlug) {
+        return {
+          ok: false,
+          code: "worktree_requires_explicit_repo",
+          message: "agent_start: `worktree` isolation was requested but neither `cwd` nor `workspaceSlug` was passed \u2014 refusing to guess the base repo from the daemon's active workspace. Pass `cwd` (an explicit path inside the repo to worktree from) or `workspaceSlug` (a slug from `agentproto workspace list`) to `agent_start`."
+        };
+      }
+      if (!provisionWorktree) {
+        return {
+          ok: false,
+          code: "worktree_provisioner_not_enabled",
+          message: `agent_start: \`worktree\` isolation is required (by request or the "${mode}" policy) but this daemon has no worktree provisioner wired (createGateway needs \`provisionWorktree\`, injected by the CLI over @agentproto/worktree).`
+        };
+      }
+      worktreeRequest = decision.request;
+    }
+  }
   const configDefaults = loadDefaultsConfig ? await loadDefaultsConfig() : (await loadConfig()).defaults;
   const roleRegistry = deps2.loadRoleRegistry ? await deps2.loadRoleRegistry() : await loadDefaultRoleRegistry();
   let role;
@@ -2443,9 +2778,10 @@ async function spawnAgentSession(deps2, input) {
     options: input.options,
     auth: input.auth
   });
+  const hasGatewayBaseUrlOption = typeof spawnDefaults.options?.base_url === "string" && spawnDefaults.options.base_url.length > 0;
   let authSpec;
   let authEcho;
-  if (resolved && input.sandbox === void 0 && resolved.authDescriptor) {
+  if (resolved && input.sandbox === void 0 && resolved.authDescriptor && !hasGatewayBaseUrlOption) {
     const authModel = input.model ?? resolved.defaultModel;
     const pinnedProvider = spawnDefaults.auth.provider;
     const resolvedProvider = pinnedProvider ?? resolved.authDescriptor.provider ?? (authModel ? getModelProvider(authModel) : void 0);
@@ -2476,6 +2812,12 @@ async function spawnAgentSession(deps2, input) {
       }
       throw err;
     }
+    if (authSpec && authSpec.enforce === "always" && authSpec.credential === void 0 && !spawnDefaults.auth.explicit && resolvedProvider !== void 0) {
+      const ignored = await (0, providers_store_exports.getProviderKey)(resolvedProvider);
+      if (ignored !== void 0) {
+        authSpec = { ...authSpec, ignoredApiKeyInStore: true };
+      }
+    }
   }
   const effectiveOptions = normalizeSkillsOption(
     spawnDefaults.skills,
@@ -2520,6 +2862,24 @@ ${input.prompt}` : input.prompt;
     return result;
   };
   try {
+    if (worktreeRequest && provisionWorktree) {
+      let outcome;
+      try {
+        outcome = await provisionWorktree({
+          cwd,
+          ...worktreeRequest.slug ? { slug: worktreeRequest.slug } : {},
+          ...worktreeRequest.base ? { base: worktreeRequest.base } : {},
+          ...input.label ? { labelHint: input.label } : {}
+        });
+      } catch (err) {
+        return finish({
+          ok: false,
+          code: "worktree_provision_failed",
+          message: `agent_start: worktree provisioning failed \u2014 ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+      if (outcome.isolated) cwd = outcome.cwd;
+    }
     const resolvedMcpServers = await resolveMcpCredentialHeaders(mcpServers);
     let liveSessionId;
     let agentSession;
@@ -2544,7 +2904,14 @@ ${input.prompt}` : input.prompt;
         ...resolvedMcpServers ? { mcpServers: resolvedMcpServers } : {},
         ...input.model ? { model: input.model } : {},
         ...input.effort ? { effort: input.effort } : {},
-        ...input.label ? { label: input.label } : {}
+        ...input.label ? { label: input.label } : {},
+        // Explicit billing-auth for the box's OWN agent_start. A fresh box
+        // has no ~/.agentproto/config.json and claude-code never inherits
+        // subscription auth from the shell env — the credential must ride the
+        // spawn call itself. Only the caller's EXPLICIT `auth` is forwarded
+        // (host config defaults stay host-scoped; the box resolves its own
+        // defaults otherwise).
+        ...input.auth ? { auth: input.auth } : {}
       });
       if (!booted.ok) return booted;
       agentSession = booted.agentSession;
@@ -2578,6 +2945,7 @@ ${input.prompt}` : input.prompt;
       agentSession,
       adapterSlug: input.adapter,
       ...input.model ? { model: input.model } : {},
+      ...input.mode ? { mode: input.mode } : {},
       ...input.wait && effectivePrompt ? {} : effectivePrompt ? { initialPrompt: effectivePrompt } : {},
       ...input.label ? { label: input.label } : {},
       ...resolvedMcpServers ? { mcpServers: resolvedMcpServers } : {},
@@ -2728,7 +3096,8 @@ async function bootSandboxAgentSession(opts) {
       ...opts.mcpServers ? { mcpServers: toMcpServerMounts(opts.mcpServers) } : {},
       ...opts.model ? { model: opts.model } : {},
       ...opts.effort ? { effort: opts.effort } : {},
-      ...opts.label ? { label: opts.label } : {}
+      ...opts.label ? { label: opts.label } : {},
+      ...opts.auth ? { auth: opts.auth } : {}
     });
     remoteSessionId = remoteDesc.id;
   } catch (err) {
@@ -2759,6 +3128,60 @@ async function resolveSandboxSecret(slug) {
     return null;
   }
 }
+
+// src/canonical-posture.ts
+var POSTURE_PREAMBLES = {
+  plan: "You are in PLAN mode. Investigate and propose a concrete plan for the user to approve; do NOT edit files, run commands, or make any other changes until the plan is explicitly approved. Reading and searching are fine.",
+  "accept-edits": "You are in ACCEPT-EDITS mode. File edits are auto-approved, so apply them directly without pausing for confirmation on each one; commands and other actions still warrant the usual care.",
+  bypass: "You are in BYPASS-PERMISSIONS mode. No approval prompts will interrupt you \u2014 every file edit and command runs without confirmation. Be deliberate and careful: there is no safety prompt between you and a destructive action.",
+  "read-only": "You are in READ-ONLY mode. You may read, search, and analyze, but you must NOT edit files, run commands that mutate state, or make any other changes. Answer and advise only."
+};
+var POSTURE_NATIVE_ALIASES = {
+  default: ["default", "build", "normal", "standard"],
+  plan: ["plan", "planning", "plan-mode"],
+  "accept-edits": ["accept-edits", "auto-accept", "auto-edit"],
+  bypass: ["bypass", "bypass-permissions", "full-access", "yolo", "dangerously-skip-permissions"],
+  "read-only": ["read-only", "chat", "ask"]
+};
+var CANONICAL_POSTURES = Object.keys(
+  POSTURE_NATIVE_ALIASES
+);
+var CANONICAL_POSTURE_SET = new Set(CANONICAL_POSTURES);
+function isCanonicalPosture(value) {
+  return CANONICAL_POSTURE_SET.has(value);
+}
+function parsePostureInput(raw) {
+  return isCanonicalPosture(raw) ? raw : { harnessModeId: raw };
+}
+function normalizeModeId(id) {
+  return id.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+var CANONICAL_BY_NORMALIZED_ALIAS = (() => {
+  const index = /* @__PURE__ */ new Map();
+  for (const [posture, aliases] of Object.entries(POSTURE_NATIVE_ALIASES)) {
+    for (const alias of aliases) index.set(normalizeModeId(alias), posture);
+  }
+  return index;
+})();
+function canonicalForModeId(modeId) {
+  return CANONICAL_BY_NORMALIZED_ALIAS.get(normalizeModeId(modeId));
+}
+function findNativeMode(posture, availableModes) {
+  if (typeof posture === "object") {
+    const target = normalizeModeId(posture.harnessModeId);
+    return availableModes.find((mode) => normalizeModeId(mode.id) === target);
+  }
+  return availableModes.find((mode) => canonicalForModeId(mode.id) === posture);
+}
+function resolvePosture(posture, availableModes) {
+  const native = findNativeMode(posture, availableModes);
+  if (native) return { kind: "native", mode: native };
+  if (typeof posture === "object") {
+    return { kind: "unavailable", requestedModeId: posture.harnessModeId };
+  }
+  if (posture === "default") return { kind: "noop", posture: "default" };
+  return { kind: "prompt", posture, preamble: POSTURE_PREAMBLES[posture] };
+}
 var sandboxSpecWithReuseSchema = z.object({
   ...SandboxSpecSchema.shape,
   reuse: z.string().min(1).optional().describe(
@@ -2799,12 +3222,15 @@ function registerAgentTools(server, opts) {
     registry,
     resolveAgentAdapter,
     listAgentAdapters,
+    listCatalogModels,
     buildOrchestratorMcp,
     callerScope,
     webhookNotifier,
     daemonMcpUrl,
     loadRoleRegistry: loadRoleRegistry2,
-    resolveSandboxProvider: resolveSandboxProvider2
+    resolveSandboxProvider: resolveSandboxProvider2,
+    provisionWorktree,
+    resolveWorktreeIsolation
   } = opts;
   server.tool(
     "agent_start",
@@ -2919,6 +3345,22 @@ function registerAgentTools(server, opts) {
         ])
       ).optional().describe(
         "Run this session inside a sandbox instead of on the host \u2014 pass a provider slug (see `list_sandbox_providers`) or an inline AIP-36 SandboxDefinition object. The daemon boots the sandbox, spawns `adapter` on the box's OWN agentproto daemon, and proxies the conversation back onto this session \u2014 `agent_prompt`/`agent_output`/`agent_kill` behave exactly as they do for a local spawn, and the transcript stays readable here even after the box is torn down. Omit to run locally (default). Pass an inline spec with `reuse: \"<sandboxId>\"` (from a prior session's `sandboxId`) to reconnect to an existing box instead \u2014 by default such a box is PAUSED (not killed) on session close so it stays reusable; set `lifecycle.destroy_on` to always kill it."
+      ),
+      worktree: jsonTolerant(
+        z.union([
+          mcpBool,
+          z.object({
+            slug: z.string().regex(
+              /^[a-z0-9][a-z0-9-]*$/,
+              "slug must be lowercase kebab-case (letters, digits, hyphens)"
+            ).optional().describe(
+              "Pin the worktree's slug (names its branch `wt/<slug>` and its directory). Omit to auto-mint a collision-free one from the label."
+            ),
+            base: z.string().min(1).optional().describe("Git ref the worktree branch is cut from. Default 'origin/main'.")
+          }).strict()
+        ])
+      ).optional().describe(
+        "Isolate this session in its OWN git worktree instead of spawning directly in `cwd` \u2014 so a parallel agent can't collide on the working tree. `true` provisions a worktree on a fresh branch `wt/<slug>` cut from origin/main (slug auto-minted from `label`); pass `{ slug, base }` to pin either. The daemon boots the worktree (git worktree add + the repo's agentproto.json setup hooks) and spawns `adapter` THERE; the session's cwd, and every path it edits, live inside the worktree. Honoured only for a ROOT spawn (a spawn made THROUGH an orchestrator inherits its parent's tree \u2014 no second worktree) and only when `cwd` is inside a git repo (nothing to isolate otherwise \u21D2 spawns plain, no error). The daemon's `worktrees.isolation` policy may force this ON for every root spawn (`always`) or OFF (`never`, which REJECTS an explicit `worktree`). Ignored for a `sandbox` spawn (the box already isolates). The worktree is NOT auto-removed on session close \u2014 it holds the agent's work; tear it down with `agentproto worktree rm|archive|gc`."
       )
     },
     async (input) => {
@@ -2942,7 +3384,9 @@ function registerAgentTools(server, opts) {
           callerScope,
           webhookNotifier,
           loadRoleRegistry: loadRoleRegistry2,
-          resolveSandboxProvider: resolveSandboxProvider2
+          resolveSandboxProvider: resolveSandboxProvider2,
+          ...provisionWorktree ? { provisionWorktree } : {},
+          ...resolveWorktreeIsolation ? { resolveWorktreeIsolation } : {}
         },
         input
       );
@@ -3091,7 +3535,7 @@ function registerAgentTools(server, opts) {
       if (callerScope) {
         const subtree = collectSubtree(
           callerScope.ownerSessionId,
-          registry.list()
+          registry.list({ includeArchived: true })
         );
         if (!subtree.has(sessionId)) {
           return {
@@ -3159,35 +3603,142 @@ function registerAgentTools(server, opts) {
     }
   );
   server.tool(
-    "agent_sessions_list",
-    "List agent-CLI sessions tracked by the daemon. Equivalent to `session_list({kind: 'agent-cli'})`. Each entry includes `kind`, `status`, age, etc. Use this when you only want the agent-CLI subset.",
+    "agent_set_model",
+    "Switch the model on a LIVE agent-cli session without restarting it \u2014 the mid-session counterpart to picking a model at `agent_start` time. Dispatches on the adapter's own apply strategy: a session whose adapter selects models via ACP session config or a `/model` control turn switches live; one that takes its model as a spawn-time CLI argument (e.g. codex) can't, and reports `{applied:false, reason:\"requires-restart\"}` instead of failing. Never throws on a rejected switch \u2014 check `applied` in the result.",
     {
-      kind: z.enum(["terminal", "agent-cli", "command", "all"]).optional().describe(
-        "Optional override of the default `agent-cli` filter. `all` returns every kind."
-      ),
-      onlyAlive: z.boolean().optional().describe("When true, only running/starting sessions. Default false."),
-      status: z.enum(["starting", "running", "exited", "killed", "error"]).optional().describe("Filter by exact status (overrides onlyAlive).")
+      sessionId: sessionIdField,
+      id: sessionIdAliasField,
+      model: z.string().describe("Model id to switch to.")
     },
     async (input) => {
-      let rows = registry.list();
-      if (callerScope) {
-        const subtree = collectSubtree(callerScope.ownerSessionId, rows);
-        rows = rows.filter((s) => subtree.has(s.id));
-      }
-      const kind = input.kind ?? "agent-cli";
-      if (kind !== "all") {
-        rows = rows.filter((s) => s.kind === kind);
-      }
-      if (input.status) {
-        rows = rows.filter((s) => s.status === input.status);
-      } else if (input.onlyAlive) {
-        rows = rows.filter(
-          (s) => s.status === "running" || s.status === "starting"
-        );
-      }
-      return {
-        content: [
-          { type: "text", text: JSON.stringify({ sessions: rows }, null, 2) }
+      const sessionId = resolveSessionIdArg(input);
+      if (!sessionId) return missingSessionIdError("agent_set_model");
+      try {
+        const result = await registry.setModel(sessionId, input.model);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ ok: true, sessionId, ...result }, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `agent_set_model: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "agent_set_effort",
+    "Switch the reasoning/compute budget (effort) on a LIVE agent-cli session without restarting it \u2014 the effort-axis counterpart to `agent_set_model`. Applied via the adapter's ACP session config. Effort is model-dependent: the same label means a different budget across models and some labels are model-gated (opus offers `ultracode`, haiku doesn't), so a label the current model rejects reports `{applied:false, reason}` instead of failing. Never throws on a rejected switch \u2014 check `applied` in the result.",
+    {
+      sessionId: sessionIdField,
+      id: sessionIdAliasField,
+      effort: z.string().describe(
+        "Effort label to switch to (e.g. low/medium/high/xhigh/max/ultracode; the accepted set is model-dependent)."
+      )
+    },
+    async (input) => {
+      const sessionId = resolveSessionIdArg(input);
+      if (!sessionId) return missingSessionIdError("agent_set_effort");
+      try {
+        const result = await registry.setEffort(sessionId, input.effort);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ ok: true, sessionId, ...result }, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `agent_set_effort: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "agent_set_posture",
+    'Switch the posture (what the agent may DO \u2014 plan / accept-edits / bypass / read-only, or a raw harness mode id) on a LIVE agent-cli session. When the posture maps to a NATIVE mode the harness advertises, it switches live (`applied:true`). When there is no native mode (the posture would have to be prompt-injected or applied at spawn), it is NOT forced live \u2014 the result is `{applied:false, reason:"requires-restart"}` so the caller can re-apply it through a session restart instead. Never throws on a rejected switch \u2014 check `applied`.',
+    {
+      sessionId: sessionIdField,
+      id: sessionIdAliasField,
+      posture: z.string().describe(
+        "Posture to switch to: a canonical value (default/plan/accept-edits/bypass/read-only) or a raw harness mode id."
+      )
+    },
+    async (input) => {
+      const sessionId = resolveSessionIdArg(input);
+      if (!sessionId) return missingSessionIdError("agent_set_posture");
+      try {
+        const result = await registry.setPosture(sessionId, parsePostureInput(input.posture));
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ ok: true, sessionId, ...result }, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `agent_set_posture: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "agent_sessions_list",
+    "List agent-CLI sessions tracked by the daemon. Equivalent to `session_list({kind: 'agent-cli'})`. Each entry includes `kind`, `status`, age, etc. Use this when you only want the agent-CLI subset.",
+    {
+      kind: z.enum(["terminal", "agent-cli", "command", "all"]).optional().describe(
+        "Optional override of the default `agent-cli` filter. `all` returns every kind."
+      ),
+      onlyAlive: z.boolean().optional().describe("When true, only running/starting sessions. Default false."),
+      status: z.enum(["starting", "running", "exited", "killed", "error"]).optional().describe("Filter by exact status (overrides onlyAlive).")
+    },
+    async (input) => {
+      let rows = registry.list({ includeArchived: true });
+      if (callerScope) {
+        const subtree = collectSubtree(callerScope.ownerSessionId, rows);
+        rows = rows.filter((s) => subtree.has(s.id));
+      }
+      rows = rows.filter((s) => !s.archived);
+      const kind = input.kind ?? "agent-cli";
+      if (kind !== "all") {
+        rows = rows.filter((s) => s.kind === kind);
+      }
+      if (input.status) {
+        rows = rows.filter((s) => s.status === input.status);
+      } else if (input.onlyAlive) {
+        rows = rows.filter(
+          (s) => s.status === "running" || s.status === "starting"
+        );
+      }
+      return {
+        content: [
+          { type: "text", text: JSON.stringify({ sessions: rows }, null, 2) }
         ]
       };
     }
@@ -3226,6 +3777,50 @@ function registerAgentTools(server, opts) {
       }
     }
   );
+  server.tool(
+    "catalog_models",
+    "Read-only vendor/product/route catalog (SPEC \xA75) \u2014 every model this host can reach, widened beyond any one adapter's model list via OpenRouter/Requesty/HuggingFace routing, with a profile-aware `runnable` flag per route. Use before `agent_start` to see what's actually spawnable given the auth profiles configured on this host.",
+    {
+      adapter: z.string().optional().describe("Keep only routes reachable via this adapter slug."),
+      vendor: z.string().optional().describe("Keep only this vendor's entry."),
+      route: z.string().optional().describe("Keep only routes with this route id."),
+      runnableOnly: mcpBool.optional().describe("Drop every route with runnable:false.")
+    },
+    async ({ adapter, vendor, route, runnableOnly }) => {
+      if (!listCatalogModels) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "catalog_models is not enabled \u2014 the daemon was started without a catalog lister. Wire `buildCatalogModels` via `createGateway({ listCatalogModels })`."
+            }
+          ],
+          isError: true
+        };
+      }
+      try {
+        const catalog = await listCatalogModels({
+          ...adapter ? { adapter } : {},
+          ...vendor ? { vendor } : {},
+          ...route ? { route } : {},
+          ...runnableOnly ? { runnableOnly: true } : {}
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(catalog, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `catalog_models failed: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
   server.tool(
     "role_list",
     "Enumerate every spawn-time role known to the daemon \u2014 the two built-ins (executor, supervisor) plus any custom role installed as a role pack. Read-only: pure visibility into the same registry `agent_start`'s `role` field and privilege-lattice spawn gate use \u2014 this tool never itself grants or denies a spawn. Use before `agent_start` with `orchestrator` to discover which roles this session may in turn spawn.",
@@ -3537,151 +4132,9 @@ function stringifyValues(raw) {
   }
   return out;
 }
-function claudeCodeProjectDir(cwd) {
-  const encoded = cwd.replace(/\//g, "-");
-  return resolve(homedir(), ".claude", "projects", encoded);
-}
-function extractFirstText(content) {
-  if (typeof content === "string") {
-    const t = content.trim();
-    return t || void 0;
-  }
-  if (Array.isArray(content)) {
-    for (const block of content) {
-      if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
-        const t = block.text.trim();
-        if (t) return t;
-      }
-    }
-  }
-  return void 0;
-}
-async function scanClaudeJsonl(filePath) {
-  const stream = createReadStream(filePath, { encoding: "utf8" });
-  const rl = createInterface({ input: stream, crlfDelay: Infinity });
-  let startedAt;
-  let lastActivityAt;
-  let messageCount = 0;
-  let preview2;
-  let lastWriter;
-  for await (const line of rl) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    let entry;
-    try {
-      entry = JSON.parse(trimmed);
-    } catch {
-      continue;
-    }
-    if (typeof entry.timestamp === "string") {
-      if (!startedAt) startedAt = entry.timestamp;
-      lastActivityAt = entry.timestamp;
-    }
-    if (typeof entry.entrypoint === "string") {
-      lastWriter = entry.entrypoint;
-    }
-    if (entry.type === "user" || entry.type === "assistant") {
-      messageCount += 1;
-      if (preview2 === void 0 && entry.type === "user") {
-        const text6 = extractFirstText(entry.message?.content);
-        if (text6 !== void 0) {
-          preview2 = text6.length > 120 ? text6.slice(0, 120) : text6;
-        }
-      }
-    }
-  }
-  return { startedAt, lastActivityAt, messageCount, preview: preview2, lastWriter };
-}
-async function buildClaudeCandidate(filePath, conversationId) {
-  const scanned = await scanClaudeJsonl(filePath);
-  return { conversationId, ...scanned };
-}
-function claudeEntrypointFor(mode) {
-  return mode === "native" ? "cli" : "sdk-ts";
-}
-async function discoverClaudeCode(input) {
-  const { cwd, since, until, attachmentMode, expectedId } = input;
-  const dir = claudeCodeProjectDir(cwd);
-  if (expectedId) {
-    const filePath = join(dir, `${expectedId}.jsonl`);
-    try {
-      await promises.stat(filePath);
-    } catch {
-      return [];
-    }
-    return [await buildClaudeCandidate(filePath, expectedId)];
-  }
-  let entries;
-  try {
-    entries = await promises.readdir(dir);
-  } catch {
-    return [];
-  }
-  const jsonlFiles = entries.filter((e) => e.endsWith(".jsonl"));
-  if (jsonlFiles.length === 0) return [];
-  const sinceMs = since ? Date.parse(since) : NaN;
-  const untilMs = until ? Date.parse(until) : NaN;
-  const wantEntrypoint = attachmentMode ? claudeEntrypointFor(attachmentMode) : void 0;
-  const scored = [];
-  for (const f of jsonlFiles) {
-    const filePath = join(dir, f);
-    let mtimeMs;
-    try {
-      mtimeMs = (await promises.stat(filePath)).mtimeMs;
-    } catch {
-      continue;
-    }
-    if (Number.isFinite(sinceMs) && mtimeMs < sinceMs - 1e3) continue;
-    const conversationId = f.replace(/\.jsonl$/, "");
-    const candidate = await buildClaudeCandidate(filePath, conversationId);
-    if (Number.isFinite(untilMs) && candidate.startedAt !== void 0) {
-      const startedMs = Date.parse(candidate.startedAt);
-      if (Number.isFinite(startedMs) && startedMs > untilMs) continue;
-    }
-    if (wantEntrypoint !== void 0 && candidate.lastWriter !== void 0 && candidate.lastWriter !== wantEntrypoint) {
-      continue;
-    }
-    scored.push({ candidate, mtimeMs });
-  }
-  scored.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return scored.map((s) => s.candidate);
-}
-async function readClaudeCode(conversationId, cwd) {
-  const { exportClaudeCodeSession: exportClaudeCodeSession2 } = await Promise.resolve().then(() => (init_transcript_export(), transcript_export_exports));
-  return exportClaudeCodeSession2(conversationId, cwd);
-}
-async function discoverHermes(input) {
-  const { discoverHermesSessions: discoverHermesSessions2 } = await Promise.resolve().then(() => (init_transcript_export(), transcript_export_exports));
-  return discoverHermesSessions2(input.cwd, input.since, input.expectedId);
-}
-async function readHermes(conversationId) {
-  const { exportHermesSession: exportHermesSession2 } = await Promise.resolve().then(() => (init_transcript_export(), transcript_export_exports));
-  return exportHermesSession2(conversationId);
-}
-var CONVERSATION_STORES = {
-  "claude-code": {
-    storeAs: "claudeResumeId",
-    // Printed by claude on graceful exit when session persistence is on
-    // (default). Example: `claude --resume 0e483f81-1a44-4bec-9667-b37158450296`
-    outputHint: /claude\s+--resume\s+([0-9a-f-]{8,})/i,
-    attachArgv: (conversationId) => ["claude", "--resume", conversationId],
-    discover: discoverClaudeCode,
-    read: readClaudeCode
-  },
-  hermes: {
-    storeAs: "hermesResumeId",
-    // `hermes acp` is the ACP arm (bin_args in adapters/hermes/src/index.ts);
-    // `--resume SESSION --tui` is the native TUI resume path — same binary,
-    // different flags, unlike claude-code where the two arms are different
-    // binaries. Verified via `hermes --help`: `--resume SESSION, -r` =
-    // "Resume a previous session by ID or title", `--tui` = the real TUI.
-    attachArgv: (conversationId) => ["hermes", "--resume", conversationId, "--tui"],
-    discover: discoverHermes,
-    read: readHermes
-  }
-};
 
 // src/resume-strategies.ts
+init_conversation_store();
 var claudeCodeStore = CONVERSATION_STORES["claude-code"];
 var RESUME_STRATEGIES = {
   "claude-code": {
@@ -3789,6 +4242,46 @@ function tokenizeCommand(s) {
   if (buf) out.push(buf);
   return out;
 }
+var RestartOverrideError = class extends Error {
+  code = "restart_override_invalid";
+  status = 400;
+  constructor(message) {
+    super(message);
+    this.name = "RestartOverrideError";
+  }
+};
+async function resolveAccessProfileFromStore(profileRef) {
+  const profile = await getAuthProfile(profileRef);
+  if (!profile) return void 0;
+  const stored = await new KeychainStore().read({ path: profile.credentialRef });
+  return { profile, ...stored?.value !== void 0 ? { credential: stored.value } : {} };
+}
+function methodToMode(method) {
+  return method === "oauth-bearer" ? "subscription" : "api-key";
+}
+function directMethods(descriptor) {
+  const methods = [];
+  if (descriptor?.authSubscription) methods.push("oauth-bearer");
+  if (descriptor?.provider) methods.push("api-key");
+  return methods;
+}
+function eligibilityManifest(adapterSlug, descriptor, route, model) {
+  const baseVendor = descriptor?.provider ?? (model ? getModelProvider(model) : void 0);
+  const gateway = route?.gateway;
+  const routeId = gateway ?? baseVendor;
+  if (routeId === void 0) return void 0;
+  const isDirect = baseVendor !== void 0 && routeId === baseVendor;
+  const billedVendor2 = isDirect ? baseVendor : routeId;
+  const methods = isDirect ? directMethods(descriptor) : ["api-key"];
+  return {
+    manifest: {
+      id: adapterSlug,
+      vendorByRoute: { [routeId]: billedVendor2 },
+      methodsByRoute: { [routeId]: methods }
+    },
+    routeId
+  };
+}
 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);
@@ -3810,15 +4303,80 @@ 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();
+  const overrides = opts.overrides ?? {};
+  const effModel = overrides.model ?? prev.model;
+  const effEffort = overrides.effort ?? prev.effort;
+  const effRoute = overrides.route ?? prev.route;
+  const effPosture = overrides.posture ?? prev.posture;
+  const effContextProfile = overrides.contextProfile ?? prev.contextProfile;
+  const effMode = overrides.mode ?? prev.mode;
+  const accessOverrideRef = overrides.access?.profileRef;
   let authSpec;
   let authEcho;
-  if (resolved.authDescriptor) {
+  let accessProfileEcho = prev.accessProfile;
+  if (accessOverrideRef !== void 0) {
+    const resolveProfile = opts.resolveAccessProfile ?? resolveAccessProfileFromStore;
+    const found = await resolveProfile(accessOverrideRef);
+    if (!found) {
+      throw new RestartOverrideError(
+        `restart access override: no auth profile "${accessOverrideRef}" found.`
+      );
+    }
+    const { profile, credential } = found;
+    if (!resolved.authDescriptor) {
+      throw new RestartOverrideError(
+        `restart access override: adapter "${adapterSlug}" presents no billing-auth, so profile "${profile.id}" cannot be attached.`
+      );
+    }
+    const projected = eligibilityManifest(
+      adapterSlug,
+      resolved.authDescriptor,
+      effRoute,
+      effModel ?? resolved.defaultModel
+    );
+    if (!projected) {
+      throw new RestartOverrideError(
+        `restart access override: cannot resolve a billing vendor for adapter "${adapterSlug}" (no fixed provider, no model) \u2014 profile "${profile.id}" eligibility is unverifiable, refusing to spawn.`
+      );
+    }
+    const { manifest, routeId } = projected;
+    if (eligibleProfiles([profile], manifest, routeId).length === 0) {
+      const billed = manifest.vendorByRoute[routeId];
+      const methods = manifest.methodsByRoute[routeId] ?? [];
+      throw new RestartOverrideError(
+        `restart access override: profile "${profile.id}" (${profile.vendor}/${profile.method}) is not eligible for adapter "${adapterSlug}" on route "${routeId}" \u2014 that endpoint bills "${billed}" via [${methods.join(", ") || "no presentable methods"}]. Attach a profile whose vendor + method match the route.`
+      );
+    }
+    const mode = methodToMode(profile.method);
+    const result = resolveAuthSpec({
+      descriptor: resolved.authDescriptor,
+      ...effModel ? { model: effModel } : {},
+      requestedProvider: profile.vendor,
+      requestedMode: mode,
+      // Attaching a named profile is always an EXPLICIT billing choice — so a
+      // missing credential fails loud (driver `missing_auth_credential`) rather
+      // than falling back to ambient env or the prior credential.
+      explicit: true,
+      ...mode === "subscription" && credential !== void 0 ? { subscriptionCredential: credential } : {},
+      ...mode === "api-key" && credential !== void 0 ? { apiKeyConfigCredential: credential } : {}
+    });
+    if (result) {
+      authSpec = result.spec;
+      authEcho = result.echo;
+    }
+    accessProfileEcho = {
+      profileRef: profile.id,
+      ...profile.label !== void 0 ? { label: profile.label } : {},
+      vendor: profile.vendor,
+      method: profile.method
+    };
+  } else 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 authModel = effModel ?? 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;
@@ -3836,19 +4394,32 @@ async function restartAgentSession(registry, resolveAgentAdapter, prev, opts = {
       authSpec = result.spec;
       authEcho = result.echo;
     }
+    if (authSpec && authSpec.enforce === "always" && authSpec.credential === void 0 && !spawnDefaults.auth.explicit && resolvedProvider !== void 0) {
+      const ignored = await (0, providers_store_exports.getProviderKey)(resolvedProvider);
+      if (ignored !== void 0) {
+        authSpec = { ...authSpec, ignoredApiKeyInStore: true };
+      }
+    }
   }
   const spawnWithResume = async (resumeSessionId) => {
     let liveSessionId;
     const agentSession = await resolved.startSession({
       cwd,
       ...resumeSessionId ? { resumeSessionId } : {},
-      ...prev.model ? { model: prev.model } : {},
+      ...effModel ? { model: effModel } : {},
+      ...effEffort ? { effort: effEffort } : {},
+      // Legacy AIP-45 mode override only — the decomposed route/posture/
+      // contextProfile spawn-env apply-path rides the driver's mode
+      // decomposition (build step 2), out of scope here; they still round-trip
+      // on the descriptor below.
+      ...overrides.mode ? { mode: overrides.mode } : {},
       ...prev.mcpServers ? { mcpServers: prev.mcpServers } : {},
       ...authSpec ? { auth: authSpec } : {},
       onActivity: () => {
         if (liveSessionId) registry.pulseActivity(liveSessionId);
       }
     });
+    const resumeVia = !resumeSessionId ? "" : opts.forceAgentResume ? "resumed via ACP" : describeResumePath(augmented);
     const desc2 = registry.spawnAgent({
       workspaceSlug: prev.workspaceSlug,
       cwd,
@@ -3856,7 +4427,17 @@ async function restartAgentSession(registry, resolveAgentAdapter, prev, opts = {
       adapterSlug,
       ...prev.label ? { label: prev.label } : {},
       ...prev.mcpServers ? { mcpServers: prev.mcpServers } : {},
-      ...prev.model ? { model: prev.model } : {},
+      ...effModel ? { model: effModel } : {},
+      // Decomposed config-axis echoes (SPEC §3.7) — carried forward from `prev`
+      // and overlaid with any override so every axis round-trips onto the fresh
+      // descriptor and the picker re-opens on it (SPEC §3.8), even the axes
+      // whose spawn-env apply-path isn't wired here yet (route/posture/context).
+      ...effEffort ? { effort: effEffort } : {},
+      ...effPosture !== void 0 ? { posture: effPosture } : {},
+      ...effRoute ? { route: effRoute } : {},
+      ...effContextProfile ? { contextProfile: effContextProfile } : {},
+      ...accessProfileEcho ? { accessProfile: accessProfileEcho } : {},
+      ...effMode ? { mode: effMode } : {},
       ...resolved.commandPreview ? { commandPreview: resolved.commandPreview } : {},
       // Verifiability echo (never the credential) — see the auth
       // resolution block above. Absent when no credential resolved,
@@ -3869,31 +4450,53 @@ async function restartAgentSession(registry, resolveAgentAdapter, prev, opts = {
           credentialSource: authEcho.credentialSource,
           setEnv: authEcho.setEnv
         }
-      } : {}
+      } : {},
+      resumedFrom: prev.id,
+      resumeVia
     });
     liveSessionId = desc2.id;
     return desc2;
   };
   let desc;
   let resumeFallback = false;
-  let usedResumeSessionId = strategy.resumeSessionId;
   try {
     desc = await spawnWithResume(strategy.resumeSessionId);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (strategy.resumeSessionId && /not found|Resource not found/i.test(msg)) {
       desc = await spawnWithResume(void 0);
-      usedResumeSessionId = void 0;
       resumeFallback = true;
     } else {
       throw err;
     }
   }
-  const resumeVia = !usedResumeSessionId ? "" : opts.forceAgentResume ? "resumed via ACP" : describeResumePath(augmented);
+  const ts = (/* @__PURE__ */ new Date()).toISOString();
+  const emit = (axis, value) => {
+    registry.emitConfigChanged({
+      type: "session:config-changed",
+      sessionId: desc.id,
+      axis,
+      value,
+      ...desc.label ? { label: desc.label } : {},
+      ts
+    });
+  };
+  if (overrides.model !== void 0) emit("model", overrides.model);
+  if (overrides.effort !== void 0) emit("effort", overrides.effort);
+  if (accessOverrideRef !== void 0) emit("access", { profileRef: accessOverrideRef });
+  if (overrides.route !== void 0) emit("route", overrides.route);
+  if (overrides.posture !== void 0) emit("posture", overrides.posture);
+  if (overrides.contextProfile !== void 0) emit("contextProfile", overrides.contextProfile);
   return {
     desc,
     resumedFrom: prev.id,
-    resumeVia,
+    // `spawnWithResume` already computed + persisted this onto `desc` (the
+    // fix this module carries — see `SessionDescriptor.resumedFrom`'s doc);
+    // reading it back here rather than recomputing keeps the RESULT and the
+    // STORED descriptor from ever being able to diverge. Never actually
+    // undefined — every `spawnWithResume` call sets it, `?? ""` is just
+    // satisfying the optional field's type.
+    resumeVia: desc.resumeVia ?? "",
     ...resumeFallback ? { resumeFallback: true } : {}
   };
 }
@@ -4037,6 +4640,9 @@ function withToolExclusion(server, excluded) {
     }
   });
 }
+
+// src/conversation-read.ts
+init_conversation_store();
 init_transcript_export();
 var BINARY_TO_STORE_KEY = {
   claude: "claude-code",
@@ -4216,7 +4822,7 @@ function buildSessionTree(sessions) {
   });
   return sessions.filter((s) => !s.parentSessionId || !idSet.has(s.parentSessionId)).sort((a, b) => a.startedAt.localeCompare(b.startedAt)).map(toNode);
 }
-z.preprocess(
+var mcpBool2 = z.preprocess(
   (v) => v === "true" ? true : v === "false" ? false : v,
   z.boolean()
 );
@@ -4238,14 +4844,20 @@ function registerSessionTools(rawServer, opts) {
         "Filter by session kind. `all` (default) returns every kind. Use `terminal` to list only PTY sessions, `agent-cli` for structured ACP agents."
       ),
       onlyAlive: z.boolean().optional().describe("When true, only running/starting sessions. Default false."),
-      status: z.enum(["starting", "running", "exited", "killed", "error"]).optional().describe("Filter by exact status (overrides onlyAlive).")
+      status: z.enum(["starting", "running", "exited", "killed", "error"]).optional().describe("Filter by exact status (overrides onlyAlive)."),
+      includeArchived: z.boolean().optional().describe(
+        "When true, also include archived sessions (hidden from every other view by `session_archive`). Default false."
+      )
     },
     async (input) => {
-      let rows = registry.list();
+      let rows = registry.list({ includeArchived: true });
       if (callerScope) {
         const subtree = collectSubtree(callerScope.ownerSessionId, rows);
         rows = rows.filter((s) => subtree.has(s.id));
       }
+      if (!input.includeArchived) {
+        rows = rows.filter((s) => !s.archived);
+      }
       if (input.kind && input.kind !== "all") {
         rows = rows.filter((s) => s.kind === input.kind);
       }
@@ -4283,7 +4895,10 @@ function registerSessionTools(rawServer, opts) {
         };
       }
       if (callerScope) {
-        const subtree = collectSubtree(callerScope.ownerSessionId, registry.list());
+        const subtree = collectSubtree(
+          callerScope.ownerSessionId,
+          registry.list({ includeArchived: true })
+        );
         if (!subtree.has(desc.id)) {
           return {
             content: [
@@ -4319,11 +4934,12 @@ function registerSessionTools(rawServer, opts) {
       status: z.enum(["starting", "running", "exited", "killed", "error"]).optional().describe("Filter by exact status (overrides onlyAlive).")
     },
     async (input) => {
-      let rows = registry.list();
+      let rows = registry.list({ includeArchived: true });
       if (callerScope) {
         const subtree = collectSubtree(callerScope.ownerSessionId, rows);
         rows = rows.filter((s) => subtree.has(s.id));
       }
+      rows = rows.filter((s) => !s.archived);
       const kind = input.kind ?? "terminal";
       if (kind !== "all") {
         rows = rows.filter((s) => s.kind === kind);
@@ -4353,11 +4969,12 @@ function registerSessionTools(rawServer, opts) {
       status: z.enum(["starting", "running", "exited", "killed", "error"]).optional().describe("Filter by exact status (overrides onlyAlive).")
     },
     async (input) => {
-      let rows = registry.list();
+      let rows = registry.list({ includeArchived: true });
       if (callerScope) {
         const subtree = collectSubtree(callerScope.ownerSessionId, rows);
         rows = rows.filter((s) => subtree.has(s.id));
       }
+      rows = rows.filter((s) => !s.archived);
       const kind = input.kind ?? "command";
       if (kind !== "all") {
         rows = rows.filter((s) => s.kind === kind);
@@ -4641,11 +5258,12 @@ function registerSessionTools(rawServer, opts) {
       )
     },
     async (input) => {
-      let rows = registry.list();
+      let rows = registry.list({ includeArchived: true });
       if (callerScope) {
         const subtree = collectSubtree(callerScope.ownerSessionId, rows);
         rows = rows.filter((s) => subtree.has(s.id));
       }
+      rows = rows.filter((s) => !s.archived);
       if (input.onlyAlive) {
         rows = rows.filter(
           (s) => s.status === "running" || s.status === "starting"
@@ -4678,7 +5296,25 @@ function registerSessionTools(rawServer, opts) {
       cols: z.number().int().min(1).max(500).optional().describe(
         "PTY cols \u2014 only used when the restart resolves to a provider-native or plain PTY resume. Default 80."
       ),
-      rows: z.number().int().min(1).max(200).optional().describe("PTY rows \u2014 same case as `cols`. Default 24.")
+      rows: z.number().int().min(1).max(200).optional().describe("PTY rows \u2014 same case as `cols`. Default 24."),
+      // ── Restart-with-override axes (SPEC §4.3, step 6) — the single path
+      //    for all four restart-only axes. Each optional; an omitted axis is
+      //    carried forward from the prior session, an axis set here wins.
+      model: z.string().min(1).optional().describe("Override the model on restart (route-identity ref)."),
+      effort: z.enum(["low", "medium", "high", "xhigh", "max", "ultracode"]).optional().describe("Override the reasoning-effort level on restart."),
+      access: z.object({
+        profileRef: z.string().min(1).describe("Attach this NAMED auth profile (SPEC \xA71c). Rejected 400 if it's not eligible for the resolved (adapter \xD7 route).")
+      }).optional().describe("Switch the session's billing wallet to a named auth profile."),
+      route: z.object({
+        gateway: z.string().min(1).describe("Endpoint/gateway id (anthropic|moonshot|\u2026)."),
+        baseUrl: z.string().url().optional().describe("Explicit base URL for a custom gateway.")
+      }).optional().describe("Override the endpoint/gateway rail on restart (access is downstream)."),
+      posture: z.union([
+        z.enum(["default", "plan", "accept-edits", "bypass", "read-only"]),
+        z.object({ harnessModeId: z.string().min(1) })
+      ]).optional().describe("Override the posture (what the agent may DO) on restart."),
+      contextProfile: z.string().min(1).optional().describe("Override what enters context (full|lean|\u2026) on restart."),
+      mode: z.string().min(1).optional().describe("Legacy AIP-45 mode id override, forwarded verbatim to the driver at spawn.")
     },
     async (input) => {
       const prev = registry.findByIdOrName(input.idOrName);
@@ -4694,7 +5330,10 @@ function registerSessionTools(rawServer, opts) {
         };
       }
       if (callerScope) {
-        const subtree = collectSubtree(callerScope.ownerSessionId, registry.list());
+        const subtree = collectSubtree(
+          callerScope.ownerSessionId,
+          registry.list({ includeArchived: true })
+        );
         if (!subtree.has(prev.id)) {
           return {
             content: [
@@ -4712,6 +5351,84 @@ function registerSessionTools(rawServer, opts) {
           };
         }
       }
+      const overrides = {
+        ...input.model !== void 0 ? { model: input.model } : {},
+        ...input.effort !== void 0 ? { effort: input.effort } : {},
+        ...input.access !== void 0 ? { access: input.access } : {},
+        ...input.route !== void 0 ? { route: input.route } : {},
+        ...input.posture !== void 0 ? { posture: input.posture } : {},
+        ...input.contextProfile !== void 0 ? { contextProfile: input.contextProfile } : {},
+        ...input.mode !== void 0 ? { mode: input.mode } : {}
+      };
+      if (Object.keys(overrides).length > 0) {
+        if (!prev.adapterSlug || !resolveAgentAdapter) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "restart_override_invalid",
+                  status: 400,
+                  message: "session_restart: restart-with-override only applies to agent-cli sessions (a PTY/command session has no config axes to override).",
+                  ok: false,
+                  sessionId: prev.id
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+        try {
+          const restarted = await restartAgentSession(registry, resolveAgentAdapter, prev, {
+            forceAgentResume: true,
+            overrides
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    ...restarted.desc,
+                    resumedFrom: restarted.resumedFrom,
+                    resumeVia: restarted.resumeVia,
+                    ...restarted.resumeFallback ? { resumeFallback: true } : {}
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        } catch (err) {
+          if (err instanceof RestartOverrideError) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: err.code,
+                    status: err.status,
+                    message: err.message,
+                    ok: false,
+                    sessionId: prev.id
+                  })
+                }
+              ],
+              isError: true
+            };
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: `session_restart: ${err instanceof Error ? err.message : String(err)}`
+              }
+            ],
+            isError: true
+          };
+        }
+      }
       const augmented = await augmentWithFsResume(prev);
       const strategy = decideRestartStrategy(augmented);
       if (strategy.kind === "unsupported") {
@@ -4743,17 +5460,15 @@ function registerSessionTools(rawServer, opts) {
             cols: input.cols ?? 80,
             rows: input.rows ?? 24,
             ...prev.name ? { name: prev.name } : {},
-            ...prev.label ? { label: prev.label } : {}
+            ...prev.label ? { label: prev.label } : {},
+            resumedFrom: prev.id,
+            resumeVia: describeResumePath(augmented)
           });
           return {
             content: [
               {
                 type: "text",
-                text: JSON.stringify(
-                  { ...desc, resumedFrom: prev.id, resumeVia: describeResumePath(augmented) },
-                  null,
-                  2
-                )
+                text: JSON.stringify(desc, null, 2)
               }
             ]
           };
@@ -4774,36 +5489,158 @@ function registerSessionTools(rawServer, opts) {
             content: [
               {
                 type: "text",
-                text: "session_restart: agent_start is not enabled \u2014 the daemon was started without an adapter resolver."
+                text: "session_restart: agent_start is not enabled \u2014 the daemon was started without an adapter resolver."
+              }
+            ],
+            isError: true
+          };
+        }
+        const restarted = await restartAgentSession(registry, resolveAgentAdapter, prev);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  ...restarted.desc,
+                  resumedFrom: restarted.resumedFrom,
+                  resumeVia: restarted.resumeVia,
+                  ...restarted.resumeFallback ? { resumeFallback: true } : {}
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `session_restart: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "session_archive",
+    "Archive a terminal-status session (exited/killed/error) so it drops out of `session_list`'s / `GET /sessions`'s default view \u2014 a housekeeping flag, not a daemon action: the session's history and transcript are untouched and stay fully readable (`session_usage`, `agent_export`, or `session_list({ includeArchived: true })`). Refuses a still-alive session (running/starting) \u2014 archiving one would hide it from view while it keeps working unattended. Use `session_unarchive` to restore visibility.",
+    {
+      idOrName: z.string().min(1).describe(
+        "Session id or name to archive \u2014 from `session_list`, must be terminal-status."
+      )
+    },
+    async (input) => {
+      const prev = registry.findByIdOrName(input.idOrName);
+      if (!prev) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `no session "${input.idOrName}" found` })
+            }
+          ],
+          isError: true
+        };
+      }
+      if (callerScope) {
+        const subtree = collectSubtree(
+          callerScope.ownerSessionId,
+          registry.list({ includeArchived: true })
+        );
+        if (!subtree.has(prev.id)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "orchestrator_session_out_of_scope",
+                  message: `session_archive: session "${prev.id}" is not in your subtree \u2014 a scoped orchestrator can only archive sessions it (transitively) spawned.`,
+                  ok: false,
+                  sessionId: prev.id
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+      }
+      try {
+        const desc = registry.archiveSession(prev.id);
+        return {
+          content: [{ type: "text", text: JSON.stringify(desc, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `session_archive: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "session_unarchive",
+    "Restore an archived session to `session_list`'s default view \u2014 the inverse of `session_archive`. No status guard: archiving never touches daemon state, so there is nothing to re-validate \u2014 any archived session can be unarchived at any time.",
+    {
+      idOrName: z.string().min(1).describe(
+        "Session id or name to unarchive \u2014 find it via `session_list({ includeArchived: true })`."
+      )
+    },
+    async (input) => {
+      const prev = registry.findByIdOrName(input.idOrName);
+      if (!prev) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `no session "${input.idOrName}" found` })
+            }
+          ],
+          isError: true
+        };
+      }
+      if (callerScope) {
+        const subtree = collectSubtree(
+          callerScope.ownerSessionId,
+          registry.list({ includeArchived: true })
+        );
+        if (!subtree.has(prev.id)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "orchestrator_session_out_of_scope",
+                  message: `session_unarchive: session "${prev.id}" is not in your subtree \u2014 a scoped orchestrator can only unarchive sessions it (transitively) spawned.`,
+                  ok: false,
+                  sessionId: prev.id
+                })
               }
             ],
             isError: true
           };
         }
-        const restarted = await restartAgentSession(registry, resolveAgentAdapter, prev);
+      }
+      try {
+        const desc = registry.unarchiveSession(prev.id);
         return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  ...restarted.desc,
-                  resumedFrom: restarted.resumedFrom,
-                  resumeVia: restarted.resumeVia,
-                  ...restarted.resumeFallback ? { resumeFallback: true } : {}
-                },
-                null,
-                2
-              )
-            }
-          ]
+          content: [{ type: "text", text: JSON.stringify(desc, null, 2) }]
         };
       } catch (err) {
         return {
           content: [
             {
               type: "text",
-              text: `session_restart: ${err instanceof Error ? err.message : String(err)}`
+              text: `session_unarchive: ${err instanceof Error ? err.message : String(err)}`
             }
           ],
           isError: true
@@ -4872,7 +5709,16 @@ function registerSessionTools(rawServer, opts) {
           cols: input.cols ?? 80,
           rows: input.rows ?? 24,
           ...input.name ? { name: input.name } : {},
-          ...input.label ? { label: input.label } : {}
+          ...input.label ? { label: input.label } : {},
+          // Parent attribution + depth (orchestrator WP4) — same rule as
+          // `agent_start` (session-spawn.ts): a spawn through a scoped
+          // sub-gateway is attributed to the owning orchestrator so
+          // `session_tree` shows the PTY as its child. Depth caps and
+          // child quotas stay agent_start-only for now.
+          ...callerScope?.ownerSessionId ? {
+            parentSessionId: callerScope.ownerSessionId,
+            depth: callerScope.depth + 1
+          } : {}
         });
         return {
           content: [{ type: "text", text: JSON.stringify(desc, null, 2) }]
@@ -4951,10 +5797,13 @@ function registerSessionTools(rawServer, opts) {
   );
   server.tool(
     "terminal_output",
-    "Snapshot the recent byte buffer of a PTY session. Returns base64-encoded bytes (the buffer is RAW including ANSI escapes \u2014 strip with a regex if you want plain text). `lastBytes` caps the read from the tail.",
+    "Snapshot the recent byte buffer of a PTY session. Returns base64-encoded bytes (the buffer is RAW including ANSI escapes) by default; pass `clean: true` for ANSI-stripped plain text instead. `lastBytes` caps the read from the tail.",
     {
       sessionId: z.string().describe("Session id OR name from terminal_start."),
-      lastBytes: z.number().int().min(1).max(64 * 1024).optional().describe("Max bytes from the tail. Default: full ring buffer (~64 KiB).")
+      lastBytes: z.number().int().min(1).max(64 * 1024).optional().describe("Max bytes from the tail. Default: full ring buffer (~64 KiB)."),
+      clean: mcpBool2.optional().describe(
+        "Strip ANSI codes, returning human-readable text (as `text` instead of `b64`). Default false = raw base64."
+      )
     },
     async (input) => {
       if (!ptyEnabled) return ptyNotConfigured("terminal_output");
@@ -4994,7 +5843,7 @@ function registerSessionTools(rawServer, opts) {
                 sessionId: desc.id,
                 status: desc.status,
                 bytes: buf.byteLength,
-                b64: buf.toString("base64")
+                ...input.clean ? { text: stripAnsi(buf.toString("utf8")) } : { b64: buf.toString("base64") }
               },
               null,
               2
@@ -7811,6 +8660,9 @@ function filterSessionObserver(inner, shouldObserve) {
 // src/sessions.ts
 init_tool_presenter();
 init_transcript_writer();
+
+// src/conversation-index.ts
+init_conversation_store();
 var DEFAULT_BUCKET = "default";
 var BUCKETS_ROOT = () => resolve(homedir(), ".agentproto", "workspaces");
 var LEGACY_SESSIONS_FILE = () => resolve(homedir(), ".agentproto", "sessions.json");
@@ -7934,6 +8786,110 @@ function readBucketRows(root, slug) {
     return [];
   }
 }
+var rowId = (row) => row && typeof row === "object" && "id" in row && typeof row.id === "string" ? row.id : void 0;
+function mergeBucketRows(onDisk, rows, everHeldIds) {
+  const incomingIds = new Set(rows.map(rowId).filter((id) => id !== void 0));
+  const preserved = onDisk.filter((row) => {
+    const id = rowId(row);
+    return id !== void 0 && !incomingIds.has(id) && !everHeldIds.has(id);
+  });
+  return [...rows, ...preserved];
+}
+
+// src/conversation-index.ts
+function conversationIndexPath(bucketsRoot, slug) {
+  return join(bucketDir(bucketsRoot, slug), "conversations.jsonl");
+}
+async function listClaudeSubagents(projectDir, adapterSessionId) {
+  const dir = join(projectDir, adapterSessionId, "subagents");
+  let entries;
+  try {
+    entries = await promises.readdir(dir);
+  } catch {
+    return [];
+  }
+  return entries.filter((e) => e.startsWith("agent-") && e.endsWith(".jsonl")).map((e) => join(dir, e)).sort();
+}
+async function resolveNativeLink(input) {
+  const { cwd, adapterSlug, adapterSessionId } = input;
+  if (adapterSlug === "claude-code") {
+    const dir = claudeCodeProjectDir(cwd);
+    const path = join(dir, `${adapterSessionId}.jsonl`);
+    const subagents = await listClaudeSubagents(dir, adapterSessionId);
+    return { kind: "claude-jsonl", path, subagents };
+  }
+  if (adapterSlug === "hermes") {
+    return {
+      kind: "hermes-sqlite",
+      dbPath: join(homedir(), ".hermes", "state.db"),
+      rowId: adapterSessionId
+    };
+  }
+  return void 0;
+}
+async function appendConversationRecord(bucketsRoot, slug, record) {
+  const path = conversationIndexPath(bucketsRoot, slug);
+  await promises.mkdir(dirname(path), { recursive: true });
+  await promises.appendFile(path, JSON.stringify(record) + "\n", "utf8");
+}
+function isConversationIndexRecord(value) {
+  if (!value || typeof value !== "object") return false;
+  const r = value;
+  return typeof r.sessionId === "string" && typeof r.workspace === "string" && typeof r.cwd === "string" && typeof r.adapterSlug === "string" && typeof r.adapterSessionId === "string" && typeof r.agentprotoTranscript === "string" && typeof r.startedAt === "string";
+}
+async function readConversationIndex(bucketsRoot, slug) {
+  const path = conversationIndexPath(bucketsRoot, slug);
+  let raw;
+  try {
+    raw = await promises.readFile(path, "utf8");
+  } catch {
+    return [];
+  }
+  const bySession = /* @__PURE__ */ new Map();
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (!isConversationIndexRecord(parsed)) continue;
+    bySession.set(parsed.sessionId, parsed);
+  }
+  return Array.from(bySession.values());
+}
+async function findConversationRecord(bucketsRoot, slug, sessionId) {
+  const rows = await readConversationIndex(bucketsRoot, slug);
+  return rows.find((r) => r.sessionId === sessionId);
+}
+async function locateConversationBySessionId(bucketsRoot, listBuckets2, sessionId) {
+  for (const slug of listBuckets2()) {
+    const record = await findConversationRecord(bucketsRoot, slug, sessionId);
+    if (record) return { workspace: slug, record };
+  }
+  return void 0;
+}
+async function locateConversationByNativePath(bucketsRoot, listBuckets2, nativePath) {
+  const target = resolve(nativePath);
+  for (const slug of listBuckets2()) {
+    const rows = await readConversationIndex(bucketsRoot, slug);
+    for (const record of rows) {
+      if (!record.native || record.native.kind !== "claude-jsonl") continue;
+      if (resolve(record.native.path) === target) {
+        return { workspace: slug, record };
+      }
+      const matchedSubagentPath = record.native.subagents.find(
+        (p) => resolve(p) === target
+      );
+      if (matchedSubagentPath) {
+        return { workspace: slug, record, matchedSubagentPath };
+      }
+    }
+  }
+  return void 0;
+}
 
 // src/terminal-transcript-writer.ts
 init_transcript_writer();
@@ -8111,6 +9067,15 @@ var SessionNotAliveError = class extends Error {
 var RECENT_LINES_CAP = 500;
 var RECENT_BYTES_CAP = 64 * 1024;
 var PERSIST_DEBOUNCE_MS = 1500;
+var EMPTY_ID_SET = /* @__PURE__ */ new Set();
+function markHeldId(map, slug, id) {
+  let set = map.get(slug);
+  if (!set) {
+    set = /* @__PURE__ */ new Set();
+    map.set(slug, set);
+  }
+  set.add(id);
+}
 var HISTORY_CAP = 200;
 var INTERRUPT_SETTLE_TIMEOUT_MS = 6e4;
 function stampProcessAlive(desc) {
@@ -8135,6 +9100,11 @@ function findPriorCommandSessionId(liveSessions, cwd) {
   }
   return best?.desc.id;
 }
+function currentRouteOf(desc) {
+  if (desc.route?.gateway) return desc.route.gateway;
+  if (desc.model) return tryParseModelRef(desc.model)?.route;
+  return void 0;
+}
 function worktreeFields(cwd) {
   const identity = resolveWorktreeIdentity(cwd);
   if (!identity) return {};
@@ -8185,6 +9155,8 @@ function createSessionsRegistry(opts) {
   let nextSubId = 1;
   let shutdownDone = false;
   const knownBuckets = /* @__PURE__ */ new Set();
+  const sourceBucketOf = /* @__PURE__ */ new Map();
+  const heldIdsByBucket = /* @__PURE__ */ new Map();
   if (persist) {
     if (partitioned) {
       migrateLegacySessionsFile({
@@ -8197,13 +9169,17 @@ function createSessionsRegistry(opts) {
         loadHistorySnapshot(
           bucketSessionsFile(bucketsRoot, slug),
           sessions,
-          sessionEvents
+          sessionEvents,
+          slug,
+          sourceBucketOf,
+          heldIdsByBucket
         );
       }
     } else {
       loadHistorySnapshot(legacyPath, sessions, sessionEvents);
     }
   }
+  const bootLoadedBuckets = new Set(knownBuckets);
   const onProcessExit = () => {
     shutdownImpl();
   };
@@ -8287,6 +9263,39 @@ function createSessionsRegistry(opts) {
     }
     delete rt.desc.awaitingPermission;
   };
+  const recordConversationLink = (rt, adapterSessionIdOverride) => {
+    if (!persist || !partitioned) return;
+    const desc = rt.desc;
+    if (desc.kind !== "agent-cli") return;
+    const adapterSlug = desc.adapterSlug;
+    const adapterSessionId = adapterSessionIdOverride ?? desc.adapterSessionId;
+    const cwd = desc.cwd;
+    if (!adapterSlug || !adapterSessionId || !cwd) return;
+    void (async () => {
+      try {
+        const native = await resolveNativeLink({ cwd, adapterSlug, adapterSessionId });
+        const registered = readRegisteredSlugs(workspacesConfigPath);
+        const slug = resolveBucketSlug(desc.workspaceSlug, registered);
+        const record = {
+          sessionId: desc.id,
+          workspace: slug,
+          cwd,
+          adapterSlug,
+          adapterSessionId,
+          ...native ? { native } : {},
+          agentprotoTranscript: sessionEventsPath(desc.id, transcriptBaseDir),
+          ...desc.title ? { title: desc.title } : {},
+          startedAt: desc.startedAt,
+          ...desc.endedAt ? { endedAt: desc.endedAt } : {}
+        };
+        await appendConversationRecord(bucketsRoot, slug, record);
+      } catch (err) {
+        console.warn(
+          `[sessions] conversation-index write failed for ${desc.id}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    })();
+  };
   const schedulePersist = () => {
     if (!persist) return;
     if (persistTimer) clearTimeout(persistTimer);
@@ -8303,7 +9312,8 @@ function createSessionsRegistry(opts) {
     const groups = /* @__PURE__ */ new Map();
     for (const slug of knownBuckets) groups.set(slug, []);
     for (const desc of snapshotRows()) {
-      const slug = resolveBucketSlug(desc.workspaceSlug, registered);
+      const slug = sourceBucketOf.get(desc.id) ?? resolveBucketSlug(desc.workspaceSlug, registered);
+      markHeldId(heldIdsByBucket, slug, desc.id);
       const list = groups.get(slug);
       if (list) list.push(desc);
       else groups.set(slug, [desc]);
@@ -8311,6 +9321,11 @@ function createSessionsRegistry(opts) {
     for (const slug of groups.keys()) knownBuckets.add(slug);
     return groups;
   };
+  const rowsToWrite = (slug, rows) => bootLoadedBuckets.has(slug) ? rows : mergeBucketRows(
+    readBucketRows(bucketsRoot, slug),
+    rows,
+    heldIdsByBucket.get(slug) ?? EMPTY_ID_SET
+  );
   const persistSnapshot = async () => {
     try {
       const savedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -8318,7 +9333,7 @@ function createSessionsRegistry(opts) {
         for (const [slug, rows] of groupRowsByBucket()) {
           await writeBucketSnapshot(bucketsRoot, slug, {
             savedAt,
-            sessions: rows
+            sessions: rowsToWrite(slug, rows)
           });
         }
         return;
@@ -8353,6 +9368,7 @@ function createSessionsRegistry(opts) {
         [strategy.storeAs]: m[1]
       };
       schedulePersist();
+      recordConversationLink(rt, m[1]);
     }
   };
   const appendBytes = (rt, chunk) => {
@@ -8630,6 +9646,7 @@ function createSessionsRegistry(opts) {
           rt.emitter.emit("status", rt.desc.status);
         }
         schedulePersist();
+        recordConversationLink(rt);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         appendLine(rt, `[error] resume failed: ${msg}`, "stderr");
@@ -8974,11 +9991,25 @@ function createSessionsRegistry(opts) {
         ...input.parentSessionId ? { parentSessionId: input.parentSessionId } : {},
         depth: input.depth ?? 0,
         ...input.model ? { model: input.model } : {},
+        ...input.mode ? { mode: input.mode } : {},
         ...input.auth ? { auth: input.auth } : {},
+        // Decomposed config-axis echoes (SPEC §3.7), same optional-spread
+        // shape as `model`/`mode`/`auth` above.
+        ...input.effort ? { effort: input.effort } : {},
+        ...input.posture !== void 0 ? { posture: input.posture } : {},
+        ...input.route ? { route: input.route } : {},
+        ...input.contextProfile ? { contextProfile: input.contextProfile } : {},
+        ...input.accessProfile ? { accessProfile: input.accessProfile } : {},
         ...priorCommandSessionId ? { priorCommandSessionId } : {},
         ...input.remote ? { remote: true } : {},
         ...input.sandboxId ? { sandboxId: input.sandboxId } : {},
-        ...input.sandboxTeardown ? { sandboxTeardown: input.sandboxTeardown } : {}
+        ...input.sandboxTeardown ? { sandboxTeardown: input.sandboxTeardown } : {},
+        // Restart lineage (see SessionDescriptor.resumedFrom's doc). `resumeVia`
+        // can legitimately be "" (a fresh fallback spawn with no continuity),
+        // so it's gated on `!== undefined` rather than truthiness — a truthy
+        // gate would silently drop the empty-string case.
+        ...input.resumedFrom ? { resumedFrom: input.resumedFrom } : {},
+        ...input.resumeVia !== void 0 ? { resumeVia: input.resumeVia } : {}
       };
       if (input.trace ?? opts?.langfuseTracingDefault ?? false) {
         tracedSessions.add(id);
@@ -9006,6 +10037,7 @@ function createSessionsRegistry(opts) {
         "stdout"
       );
       schedulePersist();
+      recordConversationLink(rt);
       if (input.initialPrompt) {
         void runAgentTurn(rt, input.initialPrompt).catch((err) => {
           appendLine(
@@ -9065,7 +10097,16 @@ function createSessionsRegistry(opts) {
         ...worktreeFields(input.cwd),
         ...input.name ? { name: input.name } : {},
         ...input.label ? { label: input.label } : {},
-        ...priorCommandSessionId ? { priorCommandSessionId } : {}
+        ...priorCommandSessionId ? { priorCommandSessionId } : {},
+        // Parent attribution + depth (orchestrator WP4) — same recording
+        // rule as spawnAgent above: depth always set so subtree/depth
+        // logic never distinguishes "absent" from "root".
+        ...input.parentSessionId ? { parentSessionId: input.parentSessionId } : {},
+        depth: input.depth ?? 0,
+        // Restart lineage — same gating rule as spawnAgent above (`resumeVia`
+        // can legitimately be "").
+        ...input.resumedFrom ? { resumedFrom: input.resumedFrom } : {},
+        ...input.resumeVia !== void 0 ? { resumeVia: input.resumeVia } : {}
       };
       const rt = {
         desc,
@@ -9231,14 +10272,126 @@ function createSessionsRegistry(opts) {
       await interruptInFlightTurn(rt, id, "interruptSession");
       return { wasBusy: true };
     },
+    async setModel(id, modelId) {
+      const rt = sessions.get(id);
+      if (!rt) throw new Error(`setModel: no session "${id}"`);
+      if (rt.desc.kind !== "agent-cli" || !rt.agentSession) {
+        throw new Error(`setModel: session "${id}" is not an agent-cli session`);
+      }
+      const targetRoute = tryParseModelRef(modelId)?.route;
+      const currentRoute = currentRouteOf(rt.desc);
+      if (targetRoute && currentRoute && targetRoute !== currentRoute) {
+        return {
+          applied: false,
+          reason: "requires-restart",
+          suggestedOverride: { route: { gateway: targetRoute }, model: modelId }
+        };
+      }
+      if (!rt.agentSession.setModel) {
+        return { applied: false, reason: "not-supported" };
+      }
+      const result = await rt.agentSession.setModel(modelId);
+      if (result.applied) {
+        rt.desc.model = result.model ?? modelId;
+        schedulePersist();
+        if (sessionEvents) {
+          const ts = (/* @__PURE__ */ new Date()).toISOString();
+          sessionEvents.emit({
+            type: "session:config-changed",
+            sessionId: id,
+            axis: "model",
+            value: rt.desc.model,
+            label: rt.desc.label,
+            ts
+          });
+          sessionEvents.emit({
+            type: "session:model-changed",
+            sessionId: id,
+            model: rt.desc.model,
+            label: rt.desc.label,
+            ts
+          });
+        }
+      }
+      return result;
+    },
+    emitConfigChanged(ev) {
+      sessionEvents?.emit(ev);
+    },
+    async setEffort(id, effort) {
+      const rt = sessions.get(id);
+      if (!rt) throw new Error(`setEffort: no session "${id}"`);
+      if (rt.desc.kind !== "agent-cli" || !rt.agentSession) {
+        throw new Error(`setEffort: session "${id}" is not an agent-cli session`);
+      }
+      if (!rt.agentSession.setEffort) {
+        return { applied: false, reason: "not-supported" };
+      }
+      const result = await rt.agentSession.setEffort(effort);
+      if (result.applied) {
+        rt.desc.effort = result.effort ?? effort;
+        schedulePersist();
+        if (sessionEvents) {
+          sessionEvents.emit({
+            type: "session:config-changed",
+            sessionId: id,
+            axis: "effort",
+            value: rt.desc.effort,
+            label: rt.desc.label,
+            ts: (/* @__PURE__ */ new Date()).toISOString()
+          });
+        }
+      }
+      return result;
+    },
+    async setPosture(id, posture) {
+      const rt = sessions.get(id);
+      if (!rt) throw new Error(`setPosture: no session "${id}"`);
+      if (rt.desc.kind !== "agent-cli" || !rt.agentSession) {
+        throw new Error(`setPosture: session "${id}" is not an agent-cli session`);
+      }
+      const resolution = resolvePosture(posture, rt.agentSession.availableModes ?? []);
+      if (resolution.kind !== "native") {
+        return {
+          applied: false,
+          reason: "requires-restart",
+          resolution: resolution.kind
+        };
+      }
+      if (!rt.agentSession.setSessionMode) {
+        return { applied: false, reason: "not-supported", resolution: "native" };
+      }
+      const result = await rt.agentSession.setSessionMode(resolution.mode.id);
+      if (!result.applied) {
+        return {
+          applied: false,
+          resolution: "native",
+          ...result.reason ? { reason: result.reason } : {}
+        };
+      }
+      rt.desc.posture = posture;
+      schedulePersist();
+      if (sessionEvents) {
+        sessionEvents.emit({
+          type: "session:config-changed",
+          sessionId: id,
+          axis: "posture",
+          value: posture,
+          label: rt.desc.label,
+          ts: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+      return { applied: true, posture, modeId: resolution.mode.id, resolution: "native" };
+    },
     pulseActivity(id) {
       const rt = sessions.get(id);
       if (!rt) return;
       rt.desc.lastActivityAt = (/* @__PURE__ */ new Date()).toISOString();
       schedulePersist();
     },
-    list() {
-      return Array.from(sessions.values()).map((s) => s.desc).sort((a, b) => b.startedAt.localeCompare(a.startedAt)).map((desc) => {
+    list(opts2) {
+      const includeArchived = opts2?.includeArchived ?? false;
+      return Array.from(sessions.values()).map((s) => s.desc).filter((desc) => includeArchived || !desc.archived).sort((a, b) => b.startedAt.localeCompare(a.startedAt)).map((desc) => {
         stampProcessAlive(desc);
         return desc;
       });
@@ -9354,6 +10507,28 @@ function createSessionsRegistry(opts) {
       emitExited(rt);
       return true;
     },
+    archiveSession(id) {
+      const rt = sessions.get(id);
+      if (!rt) throw new Error(`archiveSession: no session "${id}"`);
+      const isAlive = rt.desc.status === "running" || rt.desc.status === "starting";
+      if (isAlive) {
+        throw new Error(
+          `archiveSession: session "${id}" is still ${rt.desc.status} \u2014 only a terminal-status session (exited/killed/error) can be archived.`
+        );
+      }
+      rt.desc.archived = true;
+      schedulePersist();
+      stampProcessAlive(rt.desc);
+      return rt.desc;
+    },
+    unarchiveSession(id) {
+      const rt = sessions.get(id);
+      if (!rt) throw new Error(`unarchiveSession: no session "${id}"`);
+      rt.desc.archived = false;
+      schedulePersist();
+      stampProcessAlive(rt.desc);
+      return rt.desc;
+    },
     listPendingPermissions(filter) {
       const all = Array.from(pendingPermissions.values());
       const scoped = filter?.sessionId ? all.filter((p) => p.sessionId === filter.sessionId) : all;
@@ -9478,7 +10653,7 @@ function createSessionsRegistry(opts) {
           for (const [slug, rows] of groupRowsByBucket()) {
             writeBucketSnapshotSync(bucketsRoot, slug, {
               savedAt: nowIso,
-              sessions: rows
+              sessions: rowsToWrite(slug, rows)
             });
           }
         } else {
@@ -9500,7 +10675,7 @@ function clearInFlightFlags(desc) {
   desc.blockedOn = void 0;
   desc.pendingToolCallId = void 0;
 }
-function loadHistorySnapshot(persistPath, sessions, sessionEvents) {
+function loadHistorySnapshot(persistPath, sessions, sessionEvents, bucketSlug, sourceBucketOf, heldIdsByBucket) {
   let raw;
   try {
     raw = readFileSync(persistPath, "utf8");
@@ -9552,6 +10727,10 @@ function loadHistorySnapshot(persistPath, sessions, sessionEvents) {
     };
     rt.emitter.setMaxListeners(50);
     sessions.set(desc.id, rt);
+    if (bucketSlug !== void 0) {
+      sourceBucketOf?.set(desc.id, bucketSlug);
+      if (heldIdsByBucket) markHeldId(heldIdsByBucket, bucketSlug, desc.id);
+    }
     if (wasAlive) {
       sessionEvents?.emit({
         type: "session:exited",
@@ -10427,7 +11606,7 @@ function registerOrchestrationTools(rawServer, opts) {
   const server = opts.toolSubset ? withToolSubset(rawServer, opts.toolSubset) : rawServer;
   const { registry, sessionEvents, eventRing, callerScope, inboundWatcher } = opts;
   const isPolicyInSubtree = (policy, ownerId) => {
-    const subtree = collectSubtree(ownerId, registry.list());
+    const subtree = collectSubtree(ownerId, registry.list({ includeArchived: true }));
     const ids = policy.sessionIds.length > 0 ? policy.sessionIds : [policy.sessionId];
     return ids.every((id) => subtree.has(id));
   };
@@ -10459,7 +11638,10 @@ function registerOrchestrationTools(rawServer, opts) {
   const isSessionInScope = (sessionId) => {
     if (!callerScope) return true;
     if (!callerScope.ownerSessionId) return false;
-    return collectSubtree(callerScope.ownerSessionId, registry.list()).has(sessionId);
+    return collectSubtree(
+      callerScope.ownerSessionId,
+      registry.list({ includeArchived: true })
+    ).has(sessionId);
   };
   const enrichPermission2 = (p) => {
     const desc = registry.get(p.sessionId);
@@ -10637,6 +11819,12 @@ function registerOrchestrationTools(rawServer, opts) {
         "Reuse the session spawned by an earlier step (any prior stage), by that step's `label`. Ignored if `adapter` is set. Lets a later-stage step act on an earlier stage's output (e.g. a 'verify' step reusing a 'produce' step's session)."
       ),
       cacheable: z.boolean().optional().describe("Cache this step's output under the run's cacheKey (opt-in; for idempotent/pure steps only)."),
+      sandbox: z.union([
+        z.string().min(1).describe("Sandbox provider slug from `list_sandbox_providers` (e.g. 'local', 'e2b')."),
+        z.object({ provider: z.string().min(1) }).passthrough().describe("Inline AIP-36 SandboxSpec ({ provider, config?, env?, \u2026 }).")
+      ]).optional().describe(
+        "Run this step's session inside a sandbox instead of on the host \u2014 same semantics as `agent_start.sandbox`. Only meaningful with `adapter`."
+      ),
       policy: z.discriminatedUnion("awaiting", [
         z.object({ awaiting: z.literal("auto-allow"), prompt: z.string() }),
         z.object({
@@ -10858,7 +12046,10 @@ function registerOrchestrationTools(rawServer, opts) {
             };
           }
           const targetIds = input.sessionIds && input.sessionIds.length > 0 ? input.sessionIds : input.sessionId ? [input.sessionId] : [];
-          const subtree = collectSubtree(callerScope.ownerSessionId, registry.list());
+          const subtree = collectSubtree(
+            callerScope.ownerSessionId,
+            registry.list({ includeArchived: true })
+          );
           const outside = targetIds.filter((id) => !subtree.has(id));
           if (outside.length > 0) {
             return {
@@ -11716,55 +12907,170 @@ async function startHttpServer(opts) {
           await handleHeartbeatTick(req, res);
           return;
         }
-        if (path === "/files/upload" && req.method === "POST") {
+        if (path === "/files/upload" && req.method === "POST") {
+          const gate = checkSessionsToken(req);
+          if (gate !== "ok") {
+            rejectUnauthorizedSession(req, res, gate);
+            return;
+          }
+          await handleFileUpload(req, res, url);
+          return;
+        }
+        if (opts.sessions && path.startsWith("/sessions")) {
+          if (isMutatingSessionsRoute(req.method ?? "GET", path)) {
+            const gate = checkSessionsToken(req);
+            if (gate !== "ok") {
+              rejectUnauthorizedSession(req, res, gate);
+              return;
+            }
+          }
+          const handled = await handleSessions(
+            req,
+            res,
+            path,
+            opts.sessions,
+            opts.resolveAgentAdapter,
+            opts.ptyEnabled === true,
+            opts.resolveBrowserAdapter,
+            opts.listBrowserAdapters,
+            opts.sessionEvents,
+            opts.eventRing,
+            opts.buildOrchestratorMcp,
+            opts.daemonMcpUrl,
+            opts.provisionWorktree
+          );
+          if (handled) return;
+        }
+        if (path === "/workspaces" && req.method === "GET") {
+          try {
+            const config = await loadWorkspacesConfig();
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify(config));
+          } catch (err) {
+            res.writeHead(500, { "content-type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error: "workspaces_load_failed",
+                message: err instanceof Error ? err.message : String(err)
+              })
+            );
+          }
+          return;
+        }
+        if (path === "/workspaces" && req.method === "POST") {
+          const gate = checkSessionsToken(req);
+          if (gate !== "ok") {
+            rejectUnauthorizedSession(req, res, gate);
+            return;
+          }
+          const body = await readJsonBody(req);
+          if (!body || typeof body.path !== "string" || !body.path) {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "missing_path" }));
+            return;
+          }
+          if (!isAbsolute(body.path)) {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error: "workspace_path_not_absolute",
+                message: `path must be absolute, got "${body.path}".`
+              })
+            );
+            return;
+          }
+          try {
+            await stat(body.path);
+          } catch {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error: "workspace_path_not_found",
+                message: `"${body.path}" doesn't exist.`
+              })
+            );
+            return;
+          }
+          if (body.slug !== void 0 && typeof body.slug !== "string") {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "invalid_slug" }));
+            return;
+          }
+          if (body.label !== void 0 && typeof body.label !== "string") {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "invalid_label" }));
+            return;
+          }
+          try {
+            const config = await loadWorkspacesConfig();
+            const next = addWorkspace(config, {
+              slug: body.slug || basename(body.path),
+              path: body.path,
+              ...body.label ? { label: body.label } : {}
+            });
+            await saveWorkspacesConfig(next);
+            res.writeHead(201, { "content-type": "application/json" });
+            res.end(JSON.stringify(next));
+          } catch (err) {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error: "workspace_add_failed",
+                message: err instanceof Error ? err.message : String(err)
+              })
+            );
+          }
+          return;
+        }
+        if (path === "/workspaces/active" && req.method === "PUT") {
           const gate = checkSessionsToken(req);
           if (gate !== "ok") {
             rejectUnauthorizedSession(req, res, gate);
             return;
           }
-          await handleFileUpload(req, res, url);
-          return;
-        }
-        if (opts.sessions && path.startsWith("/sessions")) {
-          if (isMutatingSessionsRoute(req.method ?? "GET", path)) {
-            const gate = checkSessionsToken(req);
-            if (gate !== "ok") {
-              rejectUnauthorizedSession(req, res, gate);
-              return;
-            }
+          const body = await readJsonBody(req);
+          if (!body || typeof body.slug !== "string" || !body.slug) {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "missing_slug" }));
+            return;
           }
-          const handled = await handleSessions(
-            req,
-            res,
-            path,
-            opts.sessions,
-            opts.resolveAgentAdapter,
-            opts.ptyEnabled === true,
-            opts.resolveBrowserAdapter,
-            opts.listBrowserAdapters,
-            opts.sessionEvents,
-            opts.eventRing,
-            opts.buildOrchestratorMcp,
-            opts.daemonMcpUrl
-          );
-          if (handled) return;
-        }
-        if (path === "/workspaces" && req.method === "GET") {
           try {
             const config = await loadWorkspacesConfig();
+            const next = setActiveWorkspace(config, body.slug);
+            await saveWorkspacesConfig(next);
             res.writeHead(200, { "content-type": "application/json" });
-            res.end(JSON.stringify(config));
+            res.end(JSON.stringify(next));
           } catch (err) {
-            res.writeHead(500, { "content-type": "application/json" });
+            res.writeHead(404, { "content-type": "application/json" });
             res.end(
               JSON.stringify({
-                error: "workspaces_load_failed",
+                error: "workspace_not_found",
                 message: err instanceof Error ? err.message : String(err)
               })
             );
           }
           return;
         }
+        const workspaceSlugMatch = path.match(/^\/workspaces\/([^/]+)$/);
+        if (workspaceSlugMatch && req.method === "DELETE") {
+          const gate = checkSessionsToken(req);
+          if (gate !== "ok") {
+            rejectUnauthorizedSession(req, res, gate);
+            return;
+          }
+          const slug = decodeURIComponent(workspaceSlugMatch[1] ?? "");
+          const config = await loadWorkspacesConfig();
+          if (!findWorkspace(config, slug)) {
+            res.writeHead(404, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "workspace_not_found", slug }));
+            return;
+          }
+          const next = removeWorkspace(config, slug);
+          await saveWorkspacesConfig(next);
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify(next));
+          return;
+        }
         if (path === "/mcps/imports" && req.method === "GET") {
           const config = await loadImportedMcps();
           res.writeHead(200, { "content-type": "application/json" });
@@ -11920,6 +13226,41 @@ async function startHttpServer(opts) {
           }
           return;
         }
+        if (path === "/catalog/models" && req.method === "GET") {
+          if (!opts.listCatalogModels) {
+            res.writeHead(501, { "content-type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error: "lister_not_configured",
+                message: "Daemon was started without `listCatalogModels` \u2014 see `buildCatalogModels` in `catalog-models.ts`."
+              })
+            );
+            return;
+          }
+          try {
+            const qs = new URLSearchParams(
+              url.includes("?") ? url.slice(url.indexOf("?") + 1) : ""
+            );
+            const runnableOnlyParam = qs.get("runnableOnly");
+            const catalog = await opts.listCatalogModels({
+              ...qs.get("adapter") ? { adapter: qs.get("adapter") } : {},
+              ...qs.get("vendor") ? { vendor: qs.get("vendor") } : {},
+              ...qs.get("route") ? { route: qs.get("route") } : {},
+              ...runnableOnlyParam === "true" ? { runnableOnly: true } : {}
+            });
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify(catalog));
+          } catch (err) {
+            res.writeHead(500, { "content-type": "application/json" });
+            res.end(
+              JSON.stringify({
+                error: "list_failed",
+                message: err instanceof Error ? err.message : String(err)
+              })
+            );
+          }
+          return;
+        }
         if (path === "/presets" && req.method === "GET") {
           const handled = await handlePresets(req, res, path);
           if (handled) return;
@@ -12203,6 +13544,22 @@ function parseOrchestratorField(raw) {
   }
   return void 0;
 }
+function parseWorktreeField(raw) {
+  const value = typeof raw === "string" ? tryParseJson(raw) ?? raw : raw;
+  if (typeof value === "boolean") return value;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const obj = value;
+    const slug = typeof obj.slug === "string" ? obj.slug : void 0;
+    const base = typeof obj.base === "string" ? obj.base : void 0;
+    return {
+      ...slug !== void 0 ? { slug } : {},
+      ...base !== void 0 ? { base } : {}
+    };
+  }
+  return void 0;
+}
 function parseMcpServersField(raw) {
   const value = typeof raw === "string" ? tryParseJson(raw) : raw;
   if (!Array.isArray(value)) return void 0;
@@ -12253,13 +13610,16 @@ async function resolveSlugFromCwd(cwd) {
     return void 0;
   }
 }
-async function handleSessions(req, res, path, registry, resolveAgentAdapter, ptyEnabled = false, resolveBrowserAdapter, listBrowserAdapters, sessionEvents, eventRing, buildOrchestratorMcp, daemonMcpUrl) {
+async function handleSessions(req, res, path, registry, resolveAgentAdapter, ptyEnabled = false, resolveBrowserAdapter, listBrowserAdapters, sessionEvents, eventRing, buildOrchestratorMcp, daemonMcpUrl, provisionWorktree) {
   const json = (status, body) => {
     res.writeHead(status, { "content-type": "application/json" });
     res.end(JSON.stringify(body));
   };
   if (path === "/sessions" && req.method === "GET") {
-    json(200, { sessions: registry.list() });
+    const reqUrl = req.url ?? "";
+    const queryString = reqUrl.includes("?") ? reqUrl.slice(reqUrl.indexOf("?") + 1) : "";
+    const includeArchived = new URLSearchParams(queryString).get("includeArchived") === "true";
+    json(200, { sessions: registry.list({ includeArchived }) });
     return true;
   }
   if (path === "/sessions/agent" && req.method === "POST") {
@@ -12282,7 +13642,13 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
       return true;
     }
     const result = await spawnAgentSession(
-      { registry, resolveAgentAdapter, buildOrchestratorMcp, daemonMcpUrl },
+      {
+        registry,
+        resolveAgentAdapter,
+        buildOrchestratorMcp,
+        daemonMcpUrl,
+        ...provisionWorktree ? { provisionWorktree } : {}
+      },
       {
         adapter,
         ...typeof b.cwd === "string" && b.cwd.length > 0 ? { cwd: b.cwd } : {},
@@ -12326,11 +13692,19 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
         ...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 } : {};
+        })() : {},
+        // Worktree isolation — the HTTP twin of the MCP `agent_start` tool's
+        // `worktree` field. Same `spawnAgentSession` core resolves the
+        // `worktrees.isolation` policy, so `always` bites here too and there's
+        // no policy-bypassing spawn path.
+        ...b.worktree !== void 0 ? (() => {
+          const parsed = parseWorktreeField(b.worktree);
+          return parsed !== void 0 ? { worktree: parsed } : {};
         })() : {}
       }
     );
     if (!result.ok) {
-      const status = result.code === "adapter_not_found" || result.code === "no_cwd" ? 404 : result.code === "orchestrator_not_enabled" ? 501 : result.code === "orchestrator_max_depth_exceeded" || result.code === "orchestrator_child_quota_exceeded" || result.code === "role_spawn_denied" ? 409 : result.code === "invalid_role" ? 400 : 500;
+      const status = result.code === "adapter_not_found" || result.code === "no_cwd" ? 404 : result.code === "orchestrator_not_enabled" ? 501 : result.code === "orchestrator_max_depth_exceeded" || result.code === "orchestrator_child_quota_exceeded" || result.code === "role_spawn_denied" ? 409 : result.code === "invalid_role" || result.code === "worktree_requires_explicit_repo" ? 400 : 500;
       json(status, {
         error: result.code,
         message: result.message,
@@ -12549,6 +13923,129 @@ async function handleSessions(req, res, path, registry, resolveAgentAdapter, pty
     }
     return true;
   }
+  const modelMatch = path.match(/^\/sessions\/([^/]+)\/model$/);
+  if (modelMatch && req.method === "POST") {
+    const id2 = modelMatch[1];
+    if (!id2) return false;
+    const body = await readJsonBody(req);
+    const model = body && typeof body === "object" && typeof body.model === "string" ? body.model : void 0;
+    if (!model) {
+      json(400, { error: "missing_model" });
+      return true;
+    }
+    try {
+      const result = await registry.setModel(id2, model);
+      json(200, { ok: true, id: id2, ...result });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const status = msg.includes("no session") ? 404 : msg.includes("not an agent-cli session") ? 400 : 500;
+      json(status, { error: "set_model_failed", message: msg });
+    }
+    return true;
+  }
+  const restartMatch = path.match(/^\/sessions\/([^/]+)\/restart$/);
+  if (restartMatch && req.method === "POST") {
+    const id2 = restartMatch[1];
+    if (!id2) return false;
+    if (!resolveAgentAdapter) {
+      json(501, {
+        error: "restart_not_enabled",
+        message: "POST /sessions/:id/restart needs the host to inject `resolveAgentAdapter`."
+      });
+      return true;
+    }
+    const prev = registry.findByIdOrName(id2);
+    if (!prev) {
+      json(404, { error: "no_session", message: `no session "${id2}" found` });
+      return true;
+    }
+    if (!prev.adapterSlug) {
+      json(400, {
+        error: "restart_override_invalid",
+        message: "restart-with-override only applies to agent-cli sessions (a PTY/command session has no config axes to override)."
+      });
+      return true;
+    }
+    const body = await readJsonBody(req);
+    const b = body && typeof body === "object" ? body : {};
+    const str = (v) => typeof v === "string" ? v : void 0;
+    const overrides = {
+      ...str(b.model) !== void 0 ? { model: str(b.model) } : {},
+      ...str(b.effort) !== void 0 ? { effort: str(b.effort) } : {},
+      ...b.access && typeof b.access === "object" && str(b.access.profileRef) !== void 0 ? { access: { profileRef: str(b.access.profileRef) } } : {},
+      ...b.route && typeof b.route === "object" && str(b.route.gateway) !== void 0 ? {
+        route: {
+          gateway: str(b.route.gateway),
+          ...str(b.route.baseUrl) !== void 0 ? { baseUrl: str(b.route.baseUrl) } : {}
+        }
+      } : {},
+      ...b.posture !== void 0 ? { posture: b.posture } : {},
+      ...str(b.contextProfile) !== void 0 ? { contextProfile: str(b.contextProfile) } : {},
+      ...str(b.mode) !== void 0 ? { mode: str(b.mode) } : {}
+    };
+    try {
+      const restarted = await restartAgentSession(registry, resolveAgentAdapter, prev, {
+        forceAgentResume: true,
+        overrides
+      });
+      json(200, {
+        ...restarted.desc,
+        resumedFrom: restarted.resumedFrom,
+        resumeVia: restarted.resumeVia,
+        ...restarted.resumeFallback ? { resumeFallback: true } : {}
+      });
+    } catch (err) {
+      if (err instanceof RestartOverrideError) {
+        json(err.status, { error: err.code, message: err.message, sessionId: prev.id });
+        return true;
+      }
+      json(500, {
+        error: "restart_failed",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+    return true;
+  }
+  const effortMatch = path.match(/^\/sessions\/([^/]+)\/effort$/);
+  if (effortMatch && req.method === "POST") {
+    const id2 = effortMatch[1];
+    if (!id2) return false;
+    const body = await readJsonBody(req);
+    const effort = body && typeof body === "object" && typeof body.effort === "string" ? body.effort : void 0;
+    if (!effort) {
+      json(400, { error: "missing_effort" });
+      return true;
+    }
+    try {
+      const result = await registry.setEffort(id2, effort);
+      json(200, { ok: true, id: id2, ...result });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const status = msg.includes("no session") ? 404 : msg.includes("not an agent-cli session") ? 400 : 500;
+      json(status, { error: "set_effort_failed", message: msg });
+    }
+    return true;
+  }
+  const postureMatch = path.match(/^\/sessions\/([^/]+)\/posture$/);
+  if (postureMatch && req.method === "POST") {
+    const id2 = postureMatch[1];
+    if (!id2) return false;
+    const body = await readJsonBody(req);
+    const postureRaw = body && typeof body === "object" && typeof body.posture === "string" ? body.posture : void 0;
+    if (!postureRaw) {
+      json(400, { error: "missing_posture" });
+      return true;
+    }
+    try {
+      const result = await registry.setPosture(id2, parsePostureInput(postureRaw));
+      json(200, { ok: true, id: id2, ...result });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const status = msg.includes("no session") ? 404 : msg.includes("not an agent-cli session") ? 400 : 500;
+      json(status, { error: "set_posture_failed", message: msg });
+    }
+    return true;
+  }
   if (path === "/sessions" && req.method === "POST") {
     const body = await readJsonBody(req);
     if (!body || typeof body !== "object") {
@@ -14389,8 +15886,6 @@ function createRoutineRunner(opts) {
     }
   };
 }
-
-// src/sessions-registry-agent-host.ts
 init_transcript_export();
 var SessionsRegistryAgentHost = class {
   constructor(registry, sessionEvents, resolveAgentAdapter, opts) {
@@ -14405,10 +15900,45 @@ var SessionsRegistryAgentHost = class {
   opts;
   sessionsByLabel = /* @__PURE__ */ new Map();
   async spawn(adapter, opts) {
-    const resolved = await this.resolveAgentAdapter(adapter);
-    if (!resolved) throw new Error(`adapter '${adapter}' not found`);
     const workspaceSlug = opts.workspaceSlug ?? this.opts?.workspaceSlug ?? "default";
     const cwd = opts.cwd ?? this.opts?.cwd ?? process.cwd();
+    if (opts.sandbox !== void 0) {
+      let sandbox;
+      if (typeof opts.sandbox === "string") {
+        sandbox = opts.sandbox;
+      } else {
+        const parsed = SandboxSpecSchema.safeParse({ config: {}, ...opts.sandbox });
+        if (!parsed.success) {
+          throw new Error(
+            `agent step sandbox spec invalid (provider "${opts.sandbox.provider}"): ${parsed.error.message}`
+          );
+        }
+        sandbox = parsed.data;
+      }
+      const result = await spawnAgentSession(
+        {
+          registry: this.registry,
+          resolveAgentAdapter: this.resolveAgentAdapter,
+          ...this.opts?.resolveSandboxProvider ? { resolveSandboxProvider: this.opts.resolveSandboxProvider } : {}
+        },
+        {
+          adapter,
+          cwd,
+          workspaceSlug,
+          sandbox,
+          label: `agent-step:${adapter}`
+        }
+      );
+      if (!result.ok) {
+        throw new Error(`agent step sandbox spawn failed (${result.code}): ${result.message}`);
+      }
+      if (opts.stepId) {
+        this.sessionsByLabel.set(opts.stepId, result.descriptor.id);
+      }
+      return result.descriptor.id;
+    }
+    const resolved = await this.resolveAgentAdapter(adapter);
+    if (!resolved) throw new Error(`adapter '${adapter}' not found`);
     const agentSession = await resolved.startSession({ cwd });
     const desc = this.registry.spawnAgent({
       workspaceSlug,
@@ -14503,7 +16033,14 @@ var SessionsRegistryAgentHost = class {
       };
       unsubs.push(
         this.sessionEvents.on("session:turn-end", (ev) => {
-          if (ev.sessionId === sessionId) done();
+          if (ev.sessionId !== sessionId) return;
+          if (ev.empty === true) {
+            fail(
+              `session ${sessionId} produced an empty turn \u2014 no assistant output or tool call (commonly an auth failure or an invalid model id)`
+            );
+          } else {
+            done();
+          }
         })
       );
       unsubs.push(
@@ -14584,6 +16121,7 @@ function translateStages(stages, workflowId) {
           id: step.label,
           ...step.adapter !== void 0 ? { adapter: step.adapter } : {},
           ...step.sessionRef !== void 0 ? { sessionRef: step.sessionRef } : {},
+          ...step.sandbox !== void 0 ? { sandbox: step.sandbox } : {},
           ...step.cacheable ? { cacheable: true } : {},
           prompt: () => step.prompt ?? "",
           policy: step.policy ?? { awaiting: "fail" }
@@ -14601,6 +16139,45 @@ function translateStages(stages, workflowId) {
     steps
   };
 }
+function collectAgentSteps(steps) {
+  const collected = [];
+  for (const step of steps) {
+    if (step.kind === "agent") {
+      const adapter = typeof step.adapter === "string" ? step.adapter : void 0;
+      collected.push({ id: step.id, adapter, sessionRef: step.sessionRef });
+    } else if (step.kind === "parallel") {
+      for (const branch of step.branches) collected.push(...collectAgentSteps(branch.steps));
+    } else if (step.kind === "group") {
+      collected.push(...collectAgentSteps(step.steps));
+    } else if (step.kind === "map") ; else if (step.kind === "pipeline") {
+      for (const stage of step.stages) {
+      }
+    } else if (step.kind === "branch") {
+      collected.push(...collectAgentSteps(step.then));
+      if (step.otherwise) collected.push(...collectAgentSteps(step.otherwise));
+    } else if (step.kind === "loop") {
+      collected.push(...collectAgentSteps(step.body));
+    } else if (step.kind === "subworkflow") {
+      collected.push(...collectAgentSteps(step.workflow.steps));
+    }
+  }
+  return collected;
+}
+function runtimeWorkflowToStages(workflow) {
+  const agents = collectAgentSteps(workflow.steps);
+  if (agents.length === 0) {
+    return [{ steps: [{ label: "workflow" }] }];
+  }
+  return [
+    {
+      steps: agents.map((a) => ({
+        label: a.id,
+        ...a.adapter !== void 0 ? { adapter: a.adapter } : {},
+        ...a.sessionRef !== void 0 ? { sessionRef: a.sessionRef } : {}
+      }))
+    }
+  ];
+}
 var DEFAULT_PERSIST_PATH2 = () => join(homedir(), ".agentproto", "workflow-runs.json");
 function loadRuns2(persistPath) {
   const result = /* @__PURE__ */ new Map();
@@ -14658,13 +16235,10 @@ function fireNotifyUrl(run) {
   }).catch(() => void 0);
 }
 function resolveStepSessionId(step, agents) {
-  if (step.adapter) {
-    return agents.resolveByLabel(step.label);
-  }
   if (step.sessionRef) {
     return agents.resolveByLabel(step.sessionRef);
   }
-  return void 0;
+  return agents.resolveByLabel(step.label);
 }
 function fillStepStates(stages, defs, agents) {
   const sessionIds = [];
@@ -14724,6 +16298,8 @@ async function executeRunWorkflow(state, runtimeWf, agents, signal, cache, cache
           }
         }
       }
+      const sessionIds = fillStepStates(state.run.stages, state.stages, agents);
+      if (sessionIds.length > 0) state.run.result = { sessionIds };
     }
   }
   fireNotifyUrl(state.run);
@@ -14775,7 +16351,8 @@ function createWorkflowRunner(opts) {
         {
           workspaceSlug: input.workspaceSlug,
           cwd: input.cwd,
-          notifyUrl: input.notifyUrl
+          notifyUrl: input.notifyUrl,
+          ...opts.resolveSandboxProvider ? { resolveSandboxProvider: opts.resolveSandboxProvider } : {}
         }
       );
       const cache = input.cacheKey ? createFileStepCache(input.cacheKey) : void 0;
@@ -14792,26 +16369,30 @@ function createWorkflowRunner(opts) {
       }
       const handle = await loadWorkflowHandle(args.path);
       const workflow = await compileWorkflow2(handle);
+      const fileStages = runtimeWorkflowToStages(workflow);
       const runId = `wfrun_${randomUUID()}`;
       const run = {
         runId,
         workflowId: handle.id,
         status: "running",
         startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        stages: [
-          {
-            index: 0,
-            status: "pending",
-            steps: [{ index: 0, label: "workflow", status: "pending" }]
-          }
-        ]
+        stages: fileStages.map((stage, si) => ({
+          index: si,
+          ...stage.label !== void 0 ? { label: stage.label } : {},
+          status: "pending",
+          steps: stage.steps.map((s, i) => ({
+            index: i,
+            label: s.label,
+            status: "pending"
+          }))
+        }))
       };
       const abort = new AbortController();
       const state = {
         run,
         cancelled: false,
         abort,
-        stages: [],
+        stages: fileStages,
         ...args.cwd !== void 0 ? { cwd: args.cwd } : {},
         ...args.workspaceSlug !== void 0 ? { workspaceSlug: args.workspaceSlug } : {}
       };
@@ -14823,7 +16404,8 @@ function createWorkflowRunner(opts) {
         resolveAgentAdapter,
         {
           workspaceSlug: args.workspaceSlug,
-          cwd: args.cwd
+          cwd: args.cwd,
+          ...opts.resolveSandboxProvider ? { resolveSandboxProvider: opts.resolveSandboxProvider } : {}
         }
       );
       const cache = args.cacheKey ? createFileStepCache(args.cacheKey) : void 0;
@@ -15588,6 +17170,216 @@ function createOrchestratorInjector(deps2) {
     return { entry, scope, bindLifecycle };
   };
 }
+var WIDENING_ROUTES = ["openrouter", "requesty", "huggingface"];
+function normalizeRouterPrefixedId(id) {
+  const firstSlash = id.indexOf("/");
+  if (firstSlash === -1) return id;
+  const head = id.slice(0, firstSlash);
+  if (!WIDENING_ROUTES.includes(head)) return id;
+  const remainder = id.slice(firstSlash + 1);
+  if (!remainder.includes("/") || remainder.includes("@")) return id;
+  return `${remainder}@${head}`;
+}
+function tryResolveLlmModelRoute(id) {
+  try {
+    return resolveLlmModelRoute(id);
+  } catch {
+    return void 0;
+  }
+}
+function vendorFromIdPrefix(bareId) {
+  if (/^claude[-/]/.test(bareId)) return "anthropic";
+  if (/^(gpt[-/]|o[1-9](-|$)|chatgpt)/.test(bareId)) return "openai";
+  if (/^gemini[-/]/.test(bareId)) return "google";
+  if (/^grok[-/]/.test(bareId)) return "x-ai";
+  if (/^deepseek[-/]/.test(bareId)) return "deepseek";
+  return void 0;
+}
+function resolveModelId(id) {
+  const normalized = normalizeRouterPrefixedId(id);
+  const resolved = tryResolveLlmModelRoute(normalized);
+  if (resolved) {
+    return {
+      vendor: resolved.vendor,
+      product: resolved.product,
+      directRoute: resolved.route,
+      ref: formatModelRef(resolved.ref),
+      baseUrl: resolved.transport.baseUrl ?? null,
+      pricing: {
+        inPer1M: resolved.pricing.inputPer1M,
+        outPer1M: resolved.pricing.outputPer1M
+      }
+    };
+  }
+  const parsed = tryParseModelRef(normalized);
+  if (parsed) {
+    return {
+      vendor: parsed.vendor,
+      product: parsed.product,
+      directRoute: parsed.route,
+      ref: formatModelRef(parsed),
+      baseUrl: null,
+      pricing: null
+    };
+  }
+  const vendor = vendorFromIdPrefix(id) ?? "unknown";
+  return {
+    vendor,
+    product: id,
+    directRoute: vendor,
+    ref: `${vendor}/${id}`,
+    baseUrl: null,
+    pricing: null
+  };
+}
+function methodsForDirect(descriptor) {
+  const methods = [];
+  if (descriptor?.authSubscription) methods.push("oauth-bearer");
+  if (descriptor?.provider) methods.push("api-key");
+  return methods;
+}
+function isDirectRoute(mode, resolved) {
+  return mode === void 0 && resolved.directRoute === resolved.vendor;
+}
+function curatedContributions(adapters) {
+  const out = [];
+  for (const adapter of adapters) {
+    for (const model of adapter.models) {
+      const resolved = resolveModelId(model.id);
+      const route = model.mode ?? resolved.directRoute;
+      const methods = isDirectRoute(model.mode, resolved) ? methodsForDirect(adapter.authDescriptor) : ["api-key"];
+      out.push({
+        vendor: resolved.vendor,
+        product: resolved.product,
+        route,
+        ref: resolved.ref,
+        baseUrl: resolved.baseUrl,
+        pricing: resolved.pricing,
+        curated: true,
+        adapterSlug: adapter.slug,
+        ...model.mode ? { adapterMode: model.mode } : {},
+        methods
+      });
+    }
+  }
+  return out;
+}
+function widenedContributions(curated) {
+  const seenProducts = /* @__PURE__ */ new Map();
+  for (const c of curated) {
+    const key = `${c.vendor}/${c.product}`;
+    const routes = seenProducts.get(key) ?? /* @__PURE__ */ new Set();
+    routes.add(c.route);
+    seenProducts.set(key, routes);
+  }
+  const out = [];
+  for (const [key, existingRoutes] of seenProducts) {
+    const [vendor, product] = key.split("/", 2);
+    for (const router of WIDENING_ROUTES) {
+      if (existingRoutes.has(router)) continue;
+      const resolved = resolveLlmModelRoute(`${vendor}/${product}@${router}`);
+      if (!resolved) continue;
+      out.push({
+        vendor,
+        product,
+        route: router,
+        ref: formatModelRef(resolved.ref),
+        baseUrl: resolved.transport.baseUrl ?? null,
+        pricing: {
+          inPer1M: resolved.pricing.inputPer1M,
+          outPer1M: resolved.pricing.outputPer1M
+        },
+        curated: false,
+        methods: ["api-key"]
+      });
+    }
+  }
+  return out;
+}
+function mergeContributions(contributions) {
+  const rows = /* @__PURE__ */ new Map();
+  for (const c of contributions) {
+    const key = `${c.vendor}\0${c.product}\0${c.route}`;
+    const existing = rows.get(key);
+    if (!existing) {
+      rows.set(key, {
+        vendor: c.vendor,
+        product: c.product,
+        route: c.route,
+        ref: c.ref,
+        baseUrl: c.baseUrl,
+        pricing: c.pricing,
+        curated: c.curated,
+        adapters: c.adapterSlug ? [c.adapterSlug] : [],
+        adapterModes: c.adapterMode ? [c.adapterMode] : [],
+        methods: [...c.methods]
+      });
+      continue;
+    }
+    existing.curated = existing.curated || c.curated;
+    existing.baseUrl = existing.baseUrl ?? c.baseUrl;
+    existing.pricing = existing.pricing ?? c.pricing;
+    if (c.adapterSlug && !existing.adapters.includes(c.adapterSlug)) {
+      existing.adapters.push(c.adapterSlug);
+    }
+    if (c.adapterMode && !existing.adapterModes.includes(c.adapterMode)) {
+      existing.adapterModes.push(c.adapterMode);
+    }
+    for (const m of c.methods) {
+      if (!existing.methods.includes(m)) existing.methods.push(m);
+    }
+  }
+  return [...rows.values()];
+}
+function billedVendor(vendor, route) {
+  return route === vendor ? vendor : route;
+}
+function buildCatalogModels(input) {
+  const contributions = [
+    ...curatedContributions(input.adapters),
+    ...widenedContributions(curatedContributions(input.adapters))
+  ];
+  const merged = mergeContributions(contributions);
+  const query = input.query ?? {};
+  const vendors = /* @__PURE__ */ new Map();
+  for (const row of merged) {
+    if (query.vendor && row.vendor !== query.vendor) continue;
+    if (query.route && row.route !== query.route) continue;
+    if (query.adapter && !row.adapters.includes(query.adapter)) continue;
+    const manifest = {
+      id: `${row.vendor}/${row.product}@${row.route}`,
+      vendorByRoute: { [row.route]: billedVendor(row.vendor, row.route) },
+      methodsByRoute: { [row.route]: row.methods }
+    };
+    const eligible = eligibleProfiles(input.profiles, manifest, row.route);
+    const runnable = eligible.length > 0;
+    if (query.runnableOnly && !runnable) continue;
+    const route = {
+      route: row.route,
+      ref: row.ref,
+      baseUrl: row.baseUrl,
+      pricing: row.pricing,
+      runnable,
+      eligibleProfiles: eligible.map((p) => p.id),
+      adapterModes: row.adapterModes,
+      adapters: row.adapters,
+      curated: row.curated
+    };
+    const products = vendors.get(row.vendor) ?? /* @__PURE__ */ new Map();
+    vendors.set(row.vendor, products);
+    const routes = products.get(row.product) ?? [];
+    products.set(row.product, routes);
+    routes.push(route);
+  }
+  const result = [...vendors.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([vendor, products]) => ({
+    vendor,
+    products: [...products.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([product, routes]) => ({
+      product,
+      routes: [...routes].sort((a, b) => a.route.localeCompare(b.route))
+    }))
+  }));
+  return { vendors: result };
+}
 function makeBrowserHandle(entry, resolve14) {
   return {
     slug: entry.id,
@@ -17487,7 +19279,7 @@ var WorkspacePathError = class extends Error {
 };
 function createWorkspaceFs(opts) {
   const root = resolve(opts.workspace);
-  function resolvePath4(path) {
+  function resolvePath5(path) {
     if (typeof path !== "string" || path.length === 0) {
       throw new WorkspacePathError("path must be a non-empty string");
     }
@@ -17507,18 +19299,18 @@ function createWorkspaceFs(opts) {
   }
   return {
     async readFile(path) {
-      const abs = resolvePath4(path);
+      const abs = resolvePath5(path);
       const buf = await readFile(abs);
       return buf.toString("utf8");
     },
     async writeFile(path, content) {
-      const abs = resolvePath4(path);
+      const abs = resolvePath5(path);
       await mkdir(dirname(abs), { recursive: true });
       await writeFile(abs, content);
     },
     async exists(path) {
       try {
-        const abs = resolvePath4(path);
+        const abs = resolvePath5(path);
         return existsSync(abs);
       } catch {
         return false;
@@ -17876,6 +19668,62 @@ function isEnoent(err) {
 function errMsg(err) {
   return err instanceof Error ? err.message : String(err);
 }
+var POSTURE_MODE_VALUES = {
+  default: "default",
+  plan: "plan",
+  "accept-edits": "accept-edits",
+  "bypass-permissions": "bypass",
+  "read-only": "read-only",
+  "full-access": "bypass",
+  build: "default"
+};
+function decomposeMode(modes, modeId) {
+  const declared = modes.find((mode) => mode.id === modeId);
+  const kind = declared?.kind ?? inferLegacyModeKind(modeId);
+  if (kind === "route") return { route: { gateway: modeId } };
+  if (kind === "posture") return { posture: POSTURE_MODE_VALUES[modeId] ?? "default" };
+  return { contextProfile: modeId };
+}
+function decomposedAxisMatches(cfg, decomposed) {
+  if (decomposed.route) return cfg.route?.gateway === decomposed.route.gateway;
+  if (decomposed.posture !== void 0) return cfg.posture === decomposed.posture;
+  if (decomposed.contextProfile !== void 0) {
+    return cfg.contextProfile === decomposed.contextProfile;
+  }
+  return false;
+}
+function composeMode(cfg, modes) {
+  for (const mode of modes) {
+    if (decomposedAxisMatches(cfg, decomposeMode(modes, mode.id))) return mode.id;
+  }
+  return void 0;
+}
+
+// src/index.ts
+init_conversation_store();
+async function isAgentCliAuthConfigured(slug, descriptor, model) {
+  const config = await loadConfig();
+  const spawnDefaults = resolveSpawnDefaults(config.defaults, slug, {});
+  const pinnedProvider = spawnDefaults.auth.provider;
+  const resolvedProvider = pinnedProvider ?? descriptor.provider ?? (model ? getModelProvider(model) : 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,
+      ...model ? { model } : {},
+      ...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 } : {}
+    });
+    return result?.spec.credential !== void 0;
+  } catch (err) {
+    if (err instanceof AuthResolutionError) return false;
+    throw err;
+  }
+}
 
 // src/index.ts
 var DEFAULT_ALWAYS_ON_TOOLS = [
@@ -18025,6 +19873,10 @@ async function createGateway(opts) {
     sessionEvents,
     resolveAgentAdapter: opts.resolveAgentAdapter,
     persist,
+    // Sandbox-capable agent steps (`AgentStep.sandbox` / workflow_start's
+    // step `sandbox`) resolve providers through the same resolver
+    // `agent_start.sandbox` uses.
+    resolveSandboxProvider: resolveSandboxProviderResolved,
     // Compile a loaded WORKFLOW.md handle into a runnable RuntimeWorkflow
     // for `workflow_run_file` / `startFromFile`. The daemon's workflow
     // surface is agent-step based (like the stage primitive), so no tool/
@@ -18086,8 +19938,10 @@ async function createGateway(opts) {
       webhookNotifier,
       daemonMcpUrl,
       resolveSandboxProvider: resolveSandboxProviderResolved,
+      ...opts.provisionWorktree ? { provisionWorktree: opts.provisionWorktree } : {},
       ...opts.resolveAgentAdapter ? { resolveAgentAdapter: opts.resolveAgentAdapter } : {},
-      ...opts.listAgentAdapters ? { listAgentAdapters: opts.listAgentAdapters } : {}
+      ...opts.listAgentAdapters ? { listAgentAdapters: opts.listAgentAdapters } : {},
+      ...opts.listCatalogModels ? { listCatalogModels: opts.listCatalogModels } : {}
     });
     registerBrowserTools(server, {
       registry: sessions,
@@ -18241,7 +20095,9 @@ async function createGateway(opts) {
     // `agent_start` tool gets (session-spawn.ts is the shared logic).
     buildOrchestratorMcp: orchestratorInjector,
     daemonMcpUrl,
+    ...opts.provisionWorktree ? { provisionWorktree: opts.provisionWorktree } : {},
     ...opts.listAgentAdapters ? { listAgentAdapters: opts.listAgentAdapters } : {},
+    ...opts.listCatalogModels ? { listCatalogModels: opts.listCatalogModels } : {},
     ...opts.resolveBrowserAdapter ? { resolveBrowserAdapter: opts.resolveBrowserAdapter } : {},
     ...opts.listBrowserAdapters ? { listBrowserAdapters: opts.listBrowserAdapters } : {},
     meta: { workspace, registered, startedAt },
@@ -18328,6 +20184,6 @@ var export_providersPath = providers_store_exports.providersPath;
 var export_removeProviderKey = providers_store_exports.removeProviderKey;
 var export_setProviderKey = providers_store_exports.setProviderKey;
 
-export { AuthResolutionError, BUCKETS_ROOT, DEFAULT_BUCKET, DEFAULT_ORCHESTRATOR_TOOLS, LEGACY_SESSIONS_FILE, PAIRINGS_VERSION, export_PROVIDER_ENV_VARS as PROVIDER_ENV_VARS, bucketDir, bucketSessionsFile, bucketTranscriptDir, composeSessionObservers, createFileStepCache, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createScopeTokenRegistry, createWorkspaceFs, credentialFingerprint, daemonRegistryDir, declaredPresetToProviderPreset, deriveSessionUsage, fileConversationStore, formatToolCall, formatToolResult, getMcpCredentialDeps, export_getProviderKey as getProviderKey, export_injectProviderKeysIntoEnv as injectProviderKeysIntoEnv, isSafeBucketSlug, listBuckets, listPresets, export_loadProviders as loadProviders, makeBrowserAdapterLister, migrateLegacySessionsFile, migrationMarkerPath, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, normalizeSkillsOption, parseDuration, policyWatchesSession, projectSessionUsage, export_providerEnvVar as providerEnvVar, export_providersPath as providersPath, readDaemonRegistry, readRegisteredSlugs, readRuntimeMeta, registerPairingTools, export_removeProviderKey as removeProviderKey, resolveAuthSpec, resolveBucketSlug, resolveSpawnDefaults, setMcpCredentialDeps, export_setProviderKey as setProviderKey, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };
+export { AuthResolutionError, BUCKETS_ROOT, DEFAULT_BUCKET, DEFAULT_ORCHESTRATOR_TOOLS, DEFAULT_WORKTREE_ISOLATION, LEGACY_SESSIONS_FILE, PAIRINGS_VERSION, POSTURE_NATIVE_ALIASES, POSTURE_PREAMBLES, export_PROVIDER_ENV_VARS as PROVIDER_ENV_VARS, WORKTREE_ISOLATION_ENV, appendConversationRecord, bucketDir, bucketSessionsFile, bucketTranscriptDir, buildCatalogModels, canonicalForModeId, claudeProjectSlug, composeMode, composeSessionObservers, conversationIndexPath, createFileStepCache, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createPairingRegistry, createScopeTokenRegistry, createWorkspaceFs, credentialFingerprint, daemonRegistryDir, decideWorktreeIsolation, declaredPresetToProviderPreset, decomposeMode, deriveSessionUsage, fileConversationStore, findConversationRecord, findNativeMode, formatToolCall, formatToolResult, getMcpCredentialDeps, export_getProviderKey as getProviderKey, export_injectProviderKeysIntoEnv as injectProviderKeysIntoEnv, isAgentCliAuthConfigured, isSafeBucketSlug, listBuckets, listPresets, export_loadProviders as loadProviders, loadWorktreeIsolation, locateConversationByNativePath, locateConversationBySessionId, makeBrowserAdapterLister, migrateLegacySessionsFile, migrationMarkerPath, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, normalizeModeId, normalizeSkillsOption, normalizeWorktreeField, parseDuration, parseWorktreeIsolationMode, policyWatchesSession, projectSessionUsage, export_providerEnvVar as providerEnvVar, export_providersPath as providersPath, readConversationIndex, readDaemonRegistry, readRegisteredSlugs, readRuntimeMeta, registerPairingTools, export_removeProviderKey as removeProviderKey, resolveAuthSpec, resolveBucketSlug, resolveNativeLink, resolvePosture, resolveSpawnDefaults, setMcpCredentialDeps, export_setProviderKey as setProviderKey, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map