@ai-matrx/coding-sessions 0.1.81 → 0.1.85

package/dist/engine/index.cjs

@@ -60,9 +60,9 @@ var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${_
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
 // src/engine/index.ts
-var import_node_child_process2 = require("child_process");
-var import_node_crypto4 = require("crypto");
-var import_node_fs3 = require("fs");
+var import_node_child_process3 = require("child_process");
+var import_node_crypto5 = require("crypto");
+var import_node_fs4 = require("fs");
 var import_format = require("@ai-matrx/kit/format");
 
 // src/engine/raw-backup.ts
@@ -159,10 +159,379 @@ function createAiMatrxRawBackupSink(options) {
   };
 }
 
+// src/engine/agent-attach.ts
+var import_promises2 = __toESM(require("fs/promises"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var AGENT_MCP_SERVER_NAME = "matrx-agent";
+var AGENT_PLUGIN_NAME = "matrx-agent";
+function escapeAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+function versionWords(bundle) {
+  return bundle.version_number !== null ? String(bundle.version_number) : "latest";
+}
+function renderAgentInstructions(bundle, options = {}) {
+  const included = bundle.skills.filter((skill) => skill.tier === "included");
+  const listed2 = bundle.skills.filter((skill) => skill.tier === "listed");
+  const parts = [`<ai_matrx_agent name="${escapeAttr(bundle.name)}" version="${versionWords(bundle)}">`];
+  if (included.length > 0) {
+    parts.push(
+      "## Skills (always in effect)",
+      ...included.map((skill) => `### ${skill.label}
+
+${skill.body.trim()}`)
+    );
+  }
+  if (options.claudeSkills && listed2.length > 0) {
+    parts.push(
+      [
+        "## Your skills",
+        "When a request matches one of these, load it with your Skill tool and follow it before answering:",
+        ...listed2.map((skill) => `- ${AGENT_PLUGIN_NAME}:${skill.slug} \u2014 ${skill.description || skill.label}`)
+      ].join("\n")
+    );
+  }
+  if (included.length > 0 || options.claudeSkills && listed2.length > 0) parts.push("## Your instructions");
+  parts.push(bundle.instructions.trim());
+  parts.push("</ai_matrx_agent>");
+  return `${parts.filter(Boolean).join("\n\n")}
+`;
+}
+function renderCodexSkillsList(bundle, skillsRoot) {
+  const listed2 = bundle.skills.filter((skill) => skill.tier === "listed");
+  if (listed2.length === 0) return "";
+  const lines = [
+    "<skills_instructions>",
+    "## AI Matrx agent skills",
+    "A skill is a set of instructions stored in a `SKILL.md` file. Each entry has a name, a description and the absolute path of its file. When a task matches a skill's description, read that file and follow it.",
+    "### Available skills",
+    ...listed2.map(
+      (skill) => `- ${skill.slug}: ${skill.description || skill.label} (file: ${import_node_path.default.join(skillsRoot, skill.slug, "SKILL.md")})`
+    ),
+    "</skills_instructions>"
+  ];
+  return lines.join("\n");
+}
+function tomlString(value) {
+  const scalar = value.replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g, "\uFFFD");
+  return JSON.stringify(scalar).replace(/\u007f/g, "\\u007f");
+}
+async function writeAgentAttachment(dir, bundle, options) {
+  const pluginDir = import_node_path.default.join(dir, "plugin");
+  const skillsRoot = import_node_path.default.join(dir, "skills");
+  await import_promises2.default.mkdir(import_node_path.default.join(pluginDir, ".claude-plugin"), { recursive: true, mode: 448 });
+  await import_promises2.default.mkdir(skillsRoot, { recursive: true, mode: 448 });
+  const instructions = renderAgentInstructions(bundle);
+  const instructionsFile = import_node_path.default.join(dir, "instructions.md");
+  await import_promises2.default.writeFile(instructionsFile, renderAgentInstructions(bundle, { claudeSkills: true }), { mode: 384 });
+  await import_promises2.default.writeFile(
+    import_node_path.default.join(pluginDir, ".claude-plugin", "plugin.json"),
+    `${JSON.stringify(
+      {
+        name: AGENT_PLUGIN_NAME,
+        description: `Skills of the AI Matrx agent "${bundle.name}"`,
+        version: versionWords(bundle) === "latest" ? "1.0.0" : `${versionWords(bundle)}.0.0`
+      },
+      null,
+      2
+    )}
+`,
+    { mode: 384 }
+  );
+  const listed2 = bundle.skills.filter((skill) => skill.tier === "listed");
+  const wanted = new Set(listed2.map((skill) => skill.slug));
+  for (const root of [import_node_path.default.join(pluginDir, "skills"), skillsRoot]) {
+    await import_promises2.default.mkdir(root, { recursive: true, mode: 448 });
+    for (const existing of await import_promises2.default.readdir(root).catch(() => [])) {
+      if (!wanted.has(existing)) await import_promises2.default.rm(import_node_path.default.join(root, existing), { recursive: true, force: true });
+    }
+    for (const skill of listed2) {
+      const skillDir = import_node_path.default.join(root, skill.slug);
+      await import_promises2.default.mkdir(skillDir, { recursive: true, mode: 448 });
+      await import_promises2.default.writeFile(import_node_path.default.join(skillDir, "SKILL.md"), skill.content, { mode: 384 });
+    }
+  }
+  let mcpConfigFile = null;
+  const mcpUrl = options.mcpUrl && bundle.tools.length > 0 ? options.mcpUrl : null;
+  const mcpPath = import_node_path.default.join(dir, "mcp.json");
+  if (mcpUrl) {
+    mcpConfigFile = mcpPath;
+    await import_promises2.default.writeFile(
+      mcpPath,
+      `${JSON.stringify({ mcpServers: { [AGENT_MCP_SERVER_NAME]: { type: "http", url: mcpUrl } } }, null, 2)}
+`,
+      { mode: 384 }
+    );
+  } else {
+    await import_promises2.default.rm(mcpPath, { force: true });
+  }
+  const skillsList = renderCodexSkillsList(bundle, skillsRoot);
+  return {
+    dir,
+    instructionsFile,
+    pluginDir,
+    mcpConfigFile,
+    mcpUrl,
+    // Same order as Claude's: the skills list first, the agent's words last.
+    codexInstructions: skillsList ? `${skillsList}
+
+${instructions}` : instructions
+  };
+}
+function agentArgsFor(provider, attachment, options) {
+  if (provider === "claude") {
+    const args2 = [
+      // Every turn: without snapshot off, a resumed Claude drops appended instructions.
+      "--append-system-prompt-file",
+      attachment.instructionsFile,
+      "--system-prompt-snapshot",
+      "off",
+      "--plugin-dir",
+      attachment.pluginDir
+    ];
+    if (attachment.mcpConfigFile) args2.push("--mcp-config", attachment.mcpConfigFile);
+    return args2;
+  }
+  const args = [];
+  if (!options.resuming) args.push("-c", `developer_instructions=${tomlString(attachment.codexInstructions)}`);
+  if (attachment.mcpUrl) {
+    const key = `mcp_servers.${AGENT_MCP_SERVER_NAME}`;
+    args.push(
+      "-c",
+      `${key}.url=${tomlString(attachment.mcpUrl)}`,
+      "-c",
+      `${key}.default_tools_approval_mode="approve"`
+    );
+  }
+  return args;
+}
+function sessionAgentRecord(bundle, options) {
+  const unavailable = bundle.unavailable.map((u) => ({ kind: u.kind, name: u.name, reason: u.reason }));
+  const missingSkills = unavailable.filter((u) => u.kind === "skill").length;
+  const missingTools = unavailable.filter((u) => u.kind === "tool").length;
+  if (!options.toolsServed && bundle.tools.length > 0) {
+    for (const tool of bundle.tools) {
+      unavailable.push({ kind: "tool", name: tool.canonical_name, reason: "Tools need the coding sessions host" });
+    }
+  }
+  const toolsLoaded = options.toolsServed ? bundle.tools.length : 0;
+  const loaded = [
+    { part: "instructions", loaded: bundle.instructions.trim() ? 1 : 0, total: 1 },
+    { part: "skills", loaded: bundle.skills.length, total: bundle.skills.length + missingSkills },
+    { part: "tools", loaded: toolsLoaded, total: bundle.tools.length + missingTools }
+  ];
+  return {
+    agentId: bundle.agent_id,
+    versionId: bundle.version_id,
+    versionNumber: bundle.version_number,
+    name: bundle.name,
+    definitionHash: bundle.definition_hash,
+    loaded,
+    unavailable
+  };
+}
+
+// src/engine/agents.ts
+var import_node_crypto2 = require("crypto");
+var import_promises3 = __toESM(require("fs/promises"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+var DEFAULT_SERVER_URL = "https://server.app.matrxserver.com";
+var DEFAULT_SUPABASE_URL = "https://db.matrxserver.com";
+var AGENT_CATALOG_RPCS = /* @__PURE__ */ new Set([
+  "agx_get_list_full",
+  "agx_search",
+  "agx_resolve_agent_address",
+  "ues_get_bulk",
+  "ues_list",
+  "ues_set",
+  "ues_touch"
+]);
+var agentsClient = async () => {
+  const [matrx, portable, mcp] = await Promise.all([
+    import("@ai-matrx/agents/matrx"),
+    import("@ai-matrx/agents/portable"),
+    import("@ai-matrx/agents/portable/mcp")
+  ]);
+  return { ...matrx, ...portable, ...mcp };
+};
+var SIGNED_OUT_AGENT_MESSAGE = "Sign in to AI Matrx to use your agents.";
+function userIdOf(credential) {
+  if (!credential || credential.kind !== "user") return null;
+  const payload = credential.accessToken.split(".")[1];
+  if (!payload) return null;
+  try {
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    return typeof claims.sub === "string" ? claims.sub : null;
+  } catch {
+    return null;
+  }
+}
+function createAgentConnection(options, dataDir) {
+  const credentials = options?.credentials ?? null;
+  const serverUrl = (options?.serverUrl ?? DEFAULT_SERVER_URL).replace(/\/+$/, "");
+  const supabaseUrl = (options?.supabaseUrl ?? DEFAULT_SUPABASE_URL).replace(/\/+$/, "");
+  const supabaseKey = options?.supabaseKey ?? null;
+  const root = import_node_path2.default.join(dataDir, "agents");
+  let mcpBaseUrl = null;
+  const handlers = /* @__PURE__ */ new Map();
+  const secretToSession = /* @__PURE__ */ new Map();
+  const organizationId = () => {
+    const raw = typeof options?.organizationId === "function" ? options.organizationId() : options?.organizationId;
+    return raw && raw.trim() ? raw.trim() : null;
+  };
+  const transport = async () => (await agentsClient()).createMatrxTransport({
+    baseUrl: serverUrl,
+    ...credentials ? { credentials } : {},
+    ...organizationId() ? { organizationId: () => organizationId() } : {},
+    source: "codingSessionsAgents"
+  });
+  const credential = async () => credentials ? credentials.get() : null;
+  const requireSignedIn = async () => {
+    if (!await credential()) throw new Error(SIGNED_OUT_AGENT_MESSAGE);
+  };
+  const sessionDir = (sessionId) => import_node_path2.default.join(root, sessionId.replace(/[^A-Za-z0-9_-]/g, "_"));
+  async function meta(sessionId) {
+    const file = import_node_path2.default.join(sessionDir(sessionId), "session.json");
+    const existing = await import_promises3.default.readFile(file, "utf8").then((text) => JSON.parse(text)).catch(() => null);
+    if (existing?.mcpSecret && existing.conversationId) return existing;
+    const created = { mcpSecret: (0, import_node_crypto2.randomBytes)(24).toString("base64url"), conversationId: (0, import_node_crypto2.randomUUID)() };
+    await import_promises3.default.mkdir(sessionDir(sessionId), { recursive: true, mode: 448 });
+    await import_promises3.default.writeFile(file, JSON.stringify(created), { mode: 384 });
+    return created;
+  }
+  async function findSessionBySecret(secret) {
+    for (const name of await import_promises3.default.readdir(root).catch(() => [])) {
+      const found = await import_promises3.default.readFile(import_node_path2.default.join(root, name, "session.json"), "utf8").then((text) => JSON.parse(text).mcpSecret === secret).catch(() => false);
+      if (found) {
+        secretToSession.set(secret, name);
+        return name;
+      }
+    }
+    return null;
+  }
+  async function readSessionBundle(sessionId) {
+    return import_promises3.default.readFile(import_node_path2.default.join(sessionDir(sessionId), "bundle.json"), "utf8").then((text) => JSON.parse(text)).catch(() => null);
+  }
+  return {
+    async access() {
+      const current = await credential().catch(() => null);
+      const userId = userIdOf(current);
+      return {
+        configured: credentials !== null && supabaseKey !== null,
+        signedIn: userId !== null,
+        userId,
+        organizationId: organizationId()
+      };
+    },
+    async catalogRpc(request) {
+      if (!AGENT_CATALOG_RPCS.has(request.fn)) {
+        return { data: null, error: { message: `Not an agent catalogue read: ${request.fn}` } };
+      }
+      const current = await credential();
+      if (!current || current.kind !== "user") return { data: null, error: { message: SIGNED_OUT_AGENT_MESSAGE, code: "signed_out" } };
+      if (!supabaseKey) return { data: null, error: { message: "This host has no AI Matrx database key.", code: "not_configured" } };
+      const query = new URLSearchParams();
+      if (request.order) query.set("order", `${request.order.column}.${request.order.ascending === false ? "desc" : "asc"}`);
+      if (request.range) {
+        query.set("offset", String(request.range[0]));
+        query.set("limit", String(request.range[1] - request.range[0] + 1));
+      }
+      const headers = {
+        apikey: supabaseKey,
+        Authorization: `Bearer ${current.accessToken}`,
+        "Content-Type": "application/json",
+        // Every catalogue RPC lives in `public`; the database's default
+        // exposed schema is not `public`, so name it (supabase-js does).
+        "Content-Profile": "public",
+        "Accept-Profile": "public"
+      };
+      if (request.count) headers.Prefer = `count=${request.count}`;
+      const qs = query.toString();
+      const response = await fetch(`${supabaseUrl}/rest/v1/rpc/${encodeURIComponent(request.fn)}${qs ? `?${qs}` : ""}`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(request.args ?? {})
+      });
+      const text = await response.text();
+      const body = text ? JSON.parse(text) : null;
+      if (!response.ok) {
+        const err = body ?? {};
+        return {
+          data: null,
+          error: { message: err.message ?? `HTTP ${response.status}`, code: err.code, details: err.details ?? null, hint: err.hint ?? null }
+        };
+      }
+      const range = response.headers.get("content-range");
+      const total = range?.split("/")[1];
+      return { data: body, error: null, count: total && total !== "*" ? Number(total) : null };
+    },
+    async details(agentId) {
+      await requireSignedIn();
+      const { fetchPortableAgent, fetchPortableAgentVersions } = await agentsClient();
+      const [bundle, versions] = await Promise.all([
+        fetchPortableAgent(await transport(), { agentId }),
+        fetchPortableAgentVersions(await transport(), agentId).catch(() => [])
+      ]);
+      return {
+        agentId: bundle.agent_id,
+        name: bundle.name,
+        variables: bundle.variables,
+        versions: versions.map((v) => ({ id: v.id, versionNumber: v.version_number, changedAt: v.changed_at })).sort((a, b) => b.versionNumber - a.versionNumber),
+        latestVersionNumber: bundle.version_number
+      };
+    },
+    async loadBundle(selection) {
+      await requireSignedIn();
+      const { fetchPortableAgent } = await agentsClient();
+      return fetchPortableAgent(
+        await transport(),
+        selection.versionId ? { versionId: selection.versionId } : { agentId: selection.agentId },
+        { variables: selection.variables ?? {} }
+      );
+    },
+    async saveSessionBundle(sessionId, bundle) {
+      await import_promises3.default.mkdir(sessionDir(sessionId), { recursive: true, mode: 448 });
+      await import_promises3.default.writeFile(import_node_path2.default.join(sessionDir(sessionId), "bundle.json"), JSON.stringify(bundle), { mode: 384 });
+      await meta(sessionId);
+    },
+    readSessionBundle,
+    sessionDir,
+    async mcpUrlFor(sessionId) {
+      if (!mcpBaseUrl) return null;
+      const { mcpSecret } = await meta(sessionId);
+      secretToSession.set(mcpSecret, sessionId);
+      return `${mcpBaseUrl}/mcp/${mcpSecret}`;
+    },
+    setMcpBaseUrl(baseUrl) {
+      mcpBaseUrl = baseUrl ? baseUrl.replace(/\/+$/, "") : null;
+    },
+    async handleMcp(secret, body) {
+      let handler = handlers.get(secret);
+      if (!handler) {
+        const sessionId = secretToSession.get(secret) ?? await findSessionBySecret(secret);
+        if (!sessionId) return null;
+        const bundle = await readSessionBundle(sessionId);
+        if (!bundle) return null;
+        const { conversationId } = await meta(sessionId);
+        const { createAgentToolsMcpHandler } = await agentsClient();
+        handler = createAgentToolsMcpHandler({
+          bundle,
+          credentials,
+          organizationId: () => organizationId(),
+          baseUrl: serverUrl,
+          conversationId
+        });
+        handlers.set(secret, handler);
+      }
+      return handler.handle(body);
+    }
+  };
+}
+
 // src/engine/index.ts
-var import_promises6 = __toESM(require("fs/promises"), 1);
-var import_node_os4 = __toESM(require("os"), 1);
-var import_node_path6 = __toESM(require("path"), 1);
+var import_promises8 = __toESM(require("fs/promises"), 1);
+var import_node_os5 = __toESM(require("os"), 1);
+var import_node_path9 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 
 // src/normalize/claude.ts
@@ -828,9 +1197,177 @@ function describeProblem(provider, problem) {
   };
 }
 
-// src/engine/clean-env.ts
+// src/engine/binaries.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
 var import_node_os = __toESM(require("os"), 1);
-var import_node_path = __toESM(require("path"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
+var SOURCE_LABEL = {
+  codex: { "desktop-app": "from ChatGPT app", path: "from PATH", "npm-global": "from npm", configured: "set by host" },
+  claude: { "desktop-app": "from Claude app", path: "from PATH", "npm-global": "from npm", configured: "set by host" }
+};
+function sourceLabel(provider, source) {
+  return SOURCE_LABEL[provider][source];
+}
+function parseVersion(text) {
+  const match = /(\d+)\.(\d+)\.(\d+)(?:[-.][0-9A-Za-z.]+)?/.exec(text ?? "");
+  return match ? match[0] : null;
+}
+function compareVersions(a, b) {
+  const [aCore = "", aPre] = a.split("-", 2);
+  const [bCore = "", bPre] = b.split("-", 2);
+  const pa = aCore.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  const pb = bCore.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  if (aPre && !bPre) return -1;
+  if (!aPre && bPre) return 1;
+  return 0;
+}
+function pickBinary(candidates) {
+  let best = null;
+  for (const c of candidates) {
+    if (!best) {
+      best = c;
+      continue;
+    }
+    if (c.version && (!best.version || compareVersions(c.version, best.version) > 0)) best = c;
+  }
+  return best;
+}
+function executable(file) {
+  try {
+    (0, import_node_fs.accessSync)(file, import_node_fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function exeName(name, platform) {
+  return platform === "win32" ? [`${name}.exe`, `${name}.cmd`, name] : [name];
+}
+function allOnPath(name, pathValue, platform = process.platform) {
+  const found = [];
+  for (const dir of pathValue.split(import_node_path3.default.delimiter)) {
+    if (!dir) continue;
+    for (const file of exeName(name, platform)) {
+      const candidate = import_node_path3.default.join(dir, file);
+      if (executable(candidate)) {
+        found.push(candidate);
+        break;
+      }
+    }
+  }
+  return found;
+}
+function desktopAppCandidates(provider, platform, home, applications) {
+  if (platform !== "darwin") return [];
+  if (provider === "codex") {
+    return applications.map(
+      (apps) => import_node_path3.default.join(apps, "ChatGPT.app", "Contents", "Resources", "codex-cli", "bin", "codex")
+    );
+  }
+  const root = import_node_path3.default.join(home, "Library", "Application Support", "Claude", "claude-code");
+  let versions = [];
+  try {
+    versions = (0, import_node_fs.readdirSync)(root);
+  } catch {
+    return [];
+  }
+  return versions.map((v) => import_node_path3.default.join(root, v, "claude.app", "Contents", "MacOS", "claude"));
+}
+function npmGlobalPrefix(env) {
+  const fromEnv = env.npm_config_prefix ?? env.NPM_CONFIG_PREFIX;
+  if (fromEnv) return Promise.resolve(fromEnv);
+  const npm = allOnPath("npm", env.PATH ?? "")[0];
+  if (!npm) return Promise.resolve(null);
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.execFile)(npm, ["prefix", "-g"], { timeout: 5e3, env }, (error, stdout) => {
+      resolve(error ? null : String(stdout).trim() || null);
+    });
+    child.stdin?.end();
+  });
+}
+function declaredVersion(provider, source, file) {
+  if (source !== "desktop-app") return null;
+  if (provider === "codex") {
+    try {
+      const pkg = JSON.parse((0, import_node_fs.readFileSync)(import_node_path3.default.join(import_node_path3.default.dirname(import_node_path3.default.dirname(file)), "codex-package.json"), "utf8"));
+      return typeof pkg.version === "string" ? parseVersion(pkg.version) : null;
+    } catch {
+      return null;
+    }
+  }
+  return parseVersion(import_node_path3.default.basename(import_node_path3.default.resolve(file, "..", "..", "..", "..")));
+}
+function runVersion(file, env) {
+  return new Promise((resolve) => {
+    const child = (0, import_node_child_process.execFile)(file, ["--version"], { timeout: 8e3, env }, (error, stdout) => {
+      resolve(error ? null : parseVersion(String(stdout)));
+    });
+    child.stdin?.end();
+  });
+}
+async function discoverBinaries(provider, options) {
+  const platform = options.platform ?? process.platform;
+  const home = options.home ?? options.env.HOME ?? import_node_os.default.homedir();
+  const listed2 = [
+    ...desktopAppCandidates(provider, platform, home, options.applications ?? ["/Applications", import_node_path3.default.join(home, "Applications")]).filter(executable).map((p) => ({ path: p, source: "desktop-app" })),
+    ...allOnPath(provider, options.env.PATH ?? "", platform).map((p) => ({ path: p, source: "path" }))
+  ];
+  const prefix = await npmGlobalPrefix(options.env);
+  if (prefix) {
+    const dir = platform === "win32" ? prefix : import_node_path3.default.join(prefix, "bin");
+    for (const file of exeName(provider, platform)) {
+      const candidate = import_node_path3.default.join(dir, file);
+      if (executable(candidate)) {
+        listed2.push({ path: candidate, source: "npm-global" });
+        break;
+      }
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const unique = listed2.filter((c) => {
+    let real = c.path;
+    try {
+      real = (0, import_node_fs.realpathSync)(c.path);
+    } catch {
+    }
+    if (seen.has(real)) return false;
+    seen.add(real);
+    return true;
+  });
+  return Promise.all(
+    unique.map(async (c) => ({
+      ...c,
+      version: declaredVersion(provider, c.source, c.path) ?? await runVersion(c.path, options.env)
+    }))
+  );
+}
+async function resolveBinary(provider, options) {
+  const candidates = options.discover === false ? [] : await discoverBinaries(provider, options);
+  const best = pickBinary(candidates);
+  const inUse = options.forced ? {
+    path: options.forced,
+    source: "configured",
+    version: candidates.find((c) => c.path === options.forced)?.version ?? (options.discover === false ? null : await runVersion(options.forced, options.env))
+  } : best;
+  if (!inUse) return null;
+  const newer = best && best.path !== inUse.path && best.version && (!inUse.version || compareVersions(best.version, inUse.version) > 0) ? { path: best.path, version: best.version, sourceLabel: sourceLabel(provider, best.source) } : null;
+  return {
+    path: inUse.path,
+    version: inUse.version,
+    source: inUse.source,
+    sourceLabel: sourceLabel(provider, inUse.source),
+    newer
+  };
+}
+
+// src/engine/clean-env.ts
+var import_node_os2 = __toESM(require("os"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
 var ALLOWED_NAMES = /* @__PURE__ */ new Set([
   "HOME",
   "USER",
@@ -852,11 +1389,11 @@ var ALLOWED_NAMES = /* @__PURE__ */ new Set([
 var ALLOWED_PREFIXES = ["LC_"];
 function wellKnownBinDirs(home) {
   return [
-    import_node_path.default.join(home, ".local", "bin"),
-    import_node_path.default.join(home, ".claude", "local"),
-    import_node_path.default.join(home, ".npm-global", "bin"),
-    import_node_path.default.join(home, ".bun", "bin"),
-    import_node_path.default.join(home, ".volta", "bin"),
+    import_node_path4.default.join(home, ".local", "bin"),
+    import_node_path4.default.join(home, ".claude", "local"),
+    import_node_path4.default.join(home, ".npm-global", "bin"),
+    import_node_path4.default.join(home, ".bun", "bin"),
+    import_node_path4.default.join(home, ".volta", "bin"),
     "/opt/homebrew/bin",
     "/usr/local/bin",
     "/usr/bin",
@@ -874,31 +1411,31 @@ function buildCleanEnv(hostEnv, extra = {}) {
     if (typeof value !== "string") continue;
     if (isAllowedEnvName(name)) out[name] = value;
   }
-  const home = out.HOME ?? import_node_os.default.homedir();
+  const home = out.HOME ?? import_node_os2.default.homedir();
   out.HOME = home;
-  const hostPath = (hostEnv.PATH ?? "").split(import_node_path.default.delimiter).filter(Boolean);
+  const hostPath = (hostEnv.PATH ?? "").split(import_node_path4.default.delimiter).filter(Boolean);
   const merged = [];
   for (const dir of [...hostPath, ...wellKnownBinDirs(home)]) {
     if (!merged.includes(dir)) merged.push(dir);
   }
-  out.PATH = merged.join(import_node_path.default.delimiter);
+  out.PATH = merged.join(import_node_path4.default.delimiter);
   for (const [name, value] of Object.entries(extra)) out[name] = value;
   return out;
 }
 
 // src/engine/files.ts
-var import_node_fs = require("fs");
-var import_promises2 = __toESM(require("fs/promises"), 1);
-var import_node_os2 = __toESM(require("os"), 1);
-var import_node_path2 = __toESM(require("path"), 1);
+var import_node_fs2 = require("fs");
+var import_promises4 = __toESM(require("fs/promises"), 1);
+var import_node_os3 = __toESM(require("os"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
 
 // src/engine/activity.ts
-var import_node_child_process = require("child_process");
+var import_node_child_process2 = require("child_process");
 var RECENT_WRITE_MS = 2 * 60 * 1e3;
 var OPEN_TOOL_WINDOW_MS = 15 * 60 * 1e3;
 function listProcesses() {
   return new Promise((resolve) => {
-    (0, import_node_child_process.execFile)("ps", ["-axww", "-o", "pid=,args="], { maxBuffer: 64 * 1024 * 1024, timeout: 5e3 }, (error, stdout) => {
+    (0, import_node_child_process2.execFile)("ps", ["-axww", "-o", "pid=,args="], { maxBuffer: 64 * 1024 * 1024, timeout: 5e3 }, (error, stdout) => {
       if (error) {
         resolve([]);
         return;
@@ -957,17 +1494,17 @@ function describeActivity(input) {
 }
 
 // src/engine/files.ts
-function defaultProviderHomes(home = import_node_os2.default.homedir()) {
+function defaultProviderHomes(home = import_node_os3.default.homedir()) {
   return {
-    claudeProjects: import_node_path2.default.join(home, ".claude", "projects"),
-    codexSessions: import_node_path2.default.join(home, ".codex", "sessions"),
-    codexIndex: import_node_path2.default.join(home, ".codex", "session_index.jsonl")
+    claudeProjects: import_node_path5.default.join(home, ".claude", "projects"),
+    codexSessions: import_node_path5.default.join(home, ".codex", "sessions"),
+    codexIndex: import_node_path5.default.join(home, ".codex", "session_index.jsonl")
   };
 }
 var UUIDISH = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
 async function safeReaddir(dir) {
   try {
-    return await import_promises2.default.readdir(dir, { withFileTypes: true });
+    return await import_promises4.default.readdir(dir, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -976,7 +1513,7 @@ async function statCandidate(provider, file) {
   const match = UUIDISH.exec(file);
   if (!match?.[1]) return null;
   try {
-    const stat = await import_promises2.default.stat(file);
+    const stat = await import_promises4.default.stat(file);
     return { provider, file, id: match[1], mtimeMs: stat.mtimeMs, size: stat.size };
   } catch {
     return null;
@@ -986,10 +1523,10 @@ async function claudeCandidates(root) {
   const out = [];
   for (const project of await safeReaddir(root)) {
     if (!project.isDirectory()) continue;
-    const dir = import_node_path2.default.join(root, project.name);
+    const dir = import_node_path5.default.join(root, project.name);
     const entries = await safeReaddir(dir);
     const stats = await Promise.all(
-      entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => statCandidate("claude", import_node_path2.default.join(dir, e.name)))
+      entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => statCandidate("claude", import_node_path5.default.join(dir, e.name)))
     );
     for (const s of stats) if (s) out.push(s);
   }
@@ -999,14 +1536,14 @@ async function codexCandidates(root) {
   const out = [];
   for (const year of await safeReaddir(root)) {
     if (!year.isDirectory()) continue;
-    for (const month of await safeReaddir(import_node_path2.default.join(root, year.name))) {
+    for (const month of await safeReaddir(import_node_path5.default.join(root, year.name))) {
       if (!month.isDirectory()) continue;
-      for (const day of await safeReaddir(import_node_path2.default.join(root, year.name, month.name))) {
+      for (const day of await safeReaddir(import_node_path5.default.join(root, year.name, month.name))) {
         if (!day.isDirectory()) continue;
-        const dir = import_node_path2.default.join(root, year.name, month.name, day.name);
+        const dir = import_node_path5.default.join(root, year.name, month.name, day.name);
         const entries = await safeReaddir(dir);
         const stats = await Promise.all(
-          entries.filter((e) => e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")).map((e) => statCandidate("codex", import_node_path2.default.join(dir, e.name)))
+          entries.filter((e) => e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")).map((e) => statCandidate("codex", import_node_path5.default.join(dir, e.name)))
         );
         for (const s of stats) if (s) out.push(s);
       }
@@ -1015,7 +1552,7 @@ async function codexCandidates(root) {
   return out;
 }
 async function readSlice(file, start, length) {
-  const handle = await import_promises2.default.open(file, "r");
+  const handle = await import_promises4.default.open(file, "r");
   try {
     const buffer = Buffer.alloc(length);
     const { bytesRead } = await handle.read(buffer, 0, length, start);
@@ -1088,9 +1625,9 @@ async function readCodexIndex(file) {
   const names = /* @__PURE__ */ new Map();
   let text;
   try {
-    const stat = await import_promises2.default.stat(file);
+    const stat = await import_promises4.default.stat(file);
     const budget = 4 * 1024 * 1024;
-    text = stat.size <= budget ? await import_promises2.default.readFile(file, "utf8") : completeLines(await readSlice(file, stat.size - budget, budget), true);
+    text = stat.size <= budget ? await import_promises4.default.readFile(file, "utf8") : completeLines(await readSlice(file, stat.size - budget, budget), true);
   } catch {
     return names;
   }
@@ -1211,7 +1748,7 @@ var MAX_HISTORY_BUDGET = 256 * 1024 * 1024;
 async function readSessionFile(provider, file, endOffset, maxBytes = HISTORY_BUDGET) {
   let size;
   try {
-    size = (await import_promises2.default.stat(file)).size;
+    size = (await import_promises4.default.stat(file)).size;
   } catch {
     return {
       items: [],
@@ -1227,7 +1764,7 @@ async function readSessionFile(provider, file, endOffset, maxBytes = HISTORY_BUD
   let droppedFirst = start > 0;
   let carry = "";
   await new Promise((resolve, reject) => {
-    const stream = (0, import_node_fs.createReadStream)(file, { start, end: Math.max(start, end - 1), encoding: "utf8" });
+    const stream = (0, import_node_fs2.createReadStream)(file, { start, end: Math.max(start, end - 1), encoding: "utf8" });
     stream.on("data", (chunk) => {
       const text = carry + String(chunk);
       const lines = text.split("\n");
@@ -1265,9 +1802,9 @@ async function describeSessionFile(candidate, codexNames) {
 }
 
 // src/engine/preferences.ts
-var import_node_crypto2 = require("crypto");
-var import_promises3 = __toESM(require("fs/promises"), 1);
-var import_node_path3 = __toESM(require("path"), 1);
+var import_node_crypto3 = require("crypto");
+var import_promises5 = __toESM(require("fs/promises"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
 var PreferenceStore = class {
   constructor(dir) {
     this.dir = dir;
@@ -1276,11 +1813,11 @@ var PreferenceStore = class {
   data = {};
   writing = Promise.resolve();
   get file() {
-    return import_node_path3.default.join(this.dir, "preferences.json");
+    return import_node_path6.default.join(this.dir, "preferences.json");
   }
   async load() {
     try {
-      const parsed = JSON.parse(await import_promises3.default.readFile(this.file, "utf8"));
+      const parsed = JSON.parse(await import_promises5.default.readFile(this.file, "utf8"));
       this.data = typeof parsed === "object" && parsed !== null ? parsed : {};
     } catch {
       this.data = {};
@@ -1318,10 +1855,10 @@ var PreferenceStore = class {
   persist() {
     const snapshot = JSON.stringify(this.data, null, 1);
     this.writing = this.writing.then(async () => {
-      await import_promises3.default.mkdir(this.dir, { recursive: true });
-      const tmp = `${this.file}.${(0, import_node_crypto2.randomUUID)()}.tmp`;
-      await import_promises3.default.writeFile(tmp, snapshot, { mode: 384 });
-      await import_promises3.default.rename(tmp, this.file);
+      await import_promises5.default.mkdir(this.dir, { recursive: true });
+      const tmp = `${this.file}.${(0, import_node_crypto3.randomUUID)()}.tmp`;
+      await import_promises5.default.writeFile(tmp, snapshot, { mode: 384 });
+      await import_promises5.default.rename(tmp, this.file);
     }).catch(() => {
     });
   }
@@ -1331,7 +1868,7 @@ var PreferenceStore = class {
 };
 
 // src/engine/search.ts
-var import_node_fs2 = require("fs");
+var import_node_fs3 = require("fs");
 function findInLine(provider, value, needle) {
   const items = provider === "claude" ? createClaudeNormalizer().push(value) : createCodexRolloutNormalizer().push(value);
   for (const item of items) {
@@ -1372,7 +1909,7 @@ async function scanFile(provider, file, needle, raw, deadline) {
   return new Promise((resolve) => {
     let carry = Buffer.alloc(0);
     let done = false;
-    const stream = (0, import_node_fs2.createReadStream)(file, { highWaterMark: 4 * 1024 * 1024 });
+    const stream = (0, import_node_fs3.createReadStream)(file, { highWaterMark: 4 * 1024 * 1024 });
     const finish = (value) => {
       if (done) return;
       done = true;
@@ -1478,9 +2015,9 @@ async function searchLocalChats(query, options = {}) {
 }
 
 // src/engine/store.ts
-var import_node_crypto3 = require("crypto");
-var import_promises4 = __toESM(require("fs/promises"), 1);
-var import_node_path4 = __toESM(require("path"), 1);
+var import_node_crypto4 = require("crypto");
+var import_promises6 = __toESM(require("fs/promises"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
 var MAX_RUNS = 2e3;
 var RunIndex = class {
   constructor(dir) {
@@ -1490,12 +2027,12 @@ var RunIndex = class {
   data = { version: 1, sessions: [], runs: [] };
   writing = Promise.resolve();
   get file() {
-    return import_node_path4.default.join(this.dir, "index.json");
+    return import_node_path7.default.join(this.dir, "index.json");
   }
   async load() {
-    await import_promises4.default.mkdir(this.dir, { recursive: true });
+    await import_promises6.default.mkdir(this.dir, { recursive: true });
     try {
-      const parsed = JSON.parse(await import_promises4.default.readFile(this.file, "utf8"));
+      const parsed = JSON.parse(await import_promises6.default.readFile(this.file, "utf8"));
       this.data = {
         version: 1,
         sessions: Array.isArray(parsed.sessions) ? parsed.sessions : [],
@@ -1537,9 +2074,9 @@ var RunIndex = class {
   persist() {
     const snapshot = JSON.stringify(this.data, null, 1);
     this.writing = this.writing.then(async () => {
-      const tmp = `${this.file}.${(0, import_node_crypto3.randomUUID)()}.tmp`;
-      await import_promises4.default.writeFile(tmp, snapshot, { mode: 384 });
-      await import_promises4.default.rename(tmp, this.file);
+      const tmp = `${this.file}.${(0, import_node_crypto4.randomUUID)()}.tmp`;
+      await import_promises6.default.writeFile(tmp, snapshot, { mode: 384 });
+      await import_promises6.default.rename(tmp, this.file);
     }).catch(() => {
     });
   }
@@ -1549,27 +2086,27 @@ var RunIndex = class {
   /** A stable Paperclip agent/company identity for this install, so the
    *  driver's scratch state is reused rather than growing per run. */
   async identity() {
-    const file = import_node_path4.default.join(this.dir, "identity.json");
+    const file = import_node_path7.default.join(this.dir, "identity.json");
     try {
-      const parsed = JSON.parse(await import_promises4.default.readFile(file, "utf8"));
+      const parsed = JSON.parse(await import_promises6.default.readFile(file, "utf8"));
       if (typeof parsed.companyId === "string" && typeof parsed.agentId === "string") {
         return { companyId: parsed.companyId, agentId: parsed.agentId };
       }
     } catch {
     }
-    const identity = { companyId: (0, import_node_crypto3.randomUUID)(), agentId: (0, import_node_crypto3.randomUUID)() };
-    await import_promises4.default.writeFile(file, JSON.stringify(identity), { mode: 384 });
+    const identity = { companyId: (0, import_node_crypto4.randomUUID)(), agentId: (0, import_node_crypto4.randomUUID)() };
+    await import_promises6.default.writeFile(file, JSON.stringify(identity), { mode: 384 });
     return identity;
   }
 };
 
 // src/engine/user-defaults.ts
-var import_promises5 = __toESM(require("fs/promises"), 1);
-var import_node_os3 = __toESM(require("os"), 1);
-var import_node_path5 = __toESM(require("path"), 1);
+var import_promises7 = __toESM(require("fs/promises"), 1);
+var import_node_os4 = __toESM(require("os"), 1);
+var import_node_path8 = __toESM(require("path"), 1);
 async function readJson(file) {
   try {
-    const parsed = JSON.parse(await import_promises5.default.readFile(file, "utf8"));
+    const parsed = JSON.parse(await import_promises7.default.readFile(file, "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : null;
   } catch {
     return null;
@@ -1578,10 +2115,10 @@ async function readJson(file) {
 function str3(value) {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
-async function claudeDefaults(cwd, home = import_node_os3.default.homedir()) {
+async function claudeDefaults(cwd, home = import_node_os4.default.homedir()) {
   const files = [
-    ...cwd ? [import_node_path5.default.join(cwd, ".claude", "settings.local.json"), import_node_path5.default.join(cwd, ".claude", "settings.json")] : [],
-    import_node_path5.default.join(home, ".claude", "settings.json")
+    ...cwd ? [import_node_path8.default.join(cwd, ".claude", "settings.local.json"), import_node_path8.default.join(cwd, ".claude", "settings.json")] : [],
+    import_node_path8.default.join(home, ".claude", "settings.json")
   ];
   let model = null;
   let effort = null;
@@ -1594,10 +2131,10 @@ async function claudeDefaults(cwd, home = import_node_os3.default.homedir()) {
   }
   return { model, effort };
 }
-async function codexDefaults(home = import_node_os3.default.homedir()) {
+async function codexDefaults(home = import_node_os4.default.homedir()) {
   let text;
   try {
-    text = await import_promises5.default.readFile(import_node_path5.default.join(home, ".codex", "config.toml"), "utf8");
+    text = await import_promises7.default.readFile(import_node_path8.default.join(home, ".codex", "config.toml"), "utf8");
   } catch {
     return { model: null, effort: null };
   }
@@ -1621,45 +2158,33 @@ var EFFORT_LEVELS = {
 // src/engine/index.ts
 var RAW_TRANSCRIPT_MAX_BYTES = 200 * 1048576;
 function moduleDir() {
-  return import_node_path6.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
+  return import_node_path9.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
 }
 function resolveWorkerPath() {
   const dir = moduleDir();
   for (const candidate of [
-    import_node_path6.default.join(dir, "worker.js"),
-    import_node_path6.default.join(dir, "worker.ts"),
-    import_node_path6.default.join(dir, "..", "engine", "worker.js"),
-    import_node_path6.default.join(dir, "..", "engine", "worker.ts")
+    import_node_path9.default.join(dir, "worker.js"),
+    import_node_path9.default.join(dir, "worker.ts"),
+    import_node_path9.default.join(dir, "..", "engine", "worker.js"),
+    import_node_path9.default.join(dir, "..", "engine", "worker.ts")
   ]) {
-    if ((0, import_node_fs3.existsSync)(candidate)) return candidate;
+    if ((0, import_node_fs4.existsSync)(candidate)) return candidate;
   }
   throw new Error(`[coding-sessions] The driver worker is missing next to ${dir}.`);
 }
 async function installShim(dataDir) {
-  const source = import_node_path6.default.resolve(moduleDir(), "..", "..", "bin", "cli-shim.sh");
-  if (!(0, import_node_fs3.existsSync)(source)) throw new Error(`[coding-sessions] The CLI shim is missing at ${source}.`);
-  const body = await import_promises6.default.readFile(source, "utf8");
-  const target = import_node_path6.default.join(dataDir, "bin", "cli-shim.sh");
-  const current = await import_promises6.default.readFile(target, "utf8").catch(() => null);
+  const source = import_node_path9.default.resolve(moduleDir(), "..", "..", "bin", "cli-shim.sh");
+  if (!(0, import_node_fs4.existsSync)(source)) throw new Error(`[coding-sessions] The CLI shim is missing at ${source}.`);
+  const body = await import_promises8.default.readFile(source, "utf8");
+  const target = import_node_path9.default.join(dataDir, "bin", "cli-shim.sh");
+  const current = await import_promises8.default.readFile(target, "utf8").catch(() => null);
   if (current !== body) {
-    await import_promises6.default.mkdir(import_node_path6.default.dirname(target), { recursive: true });
-    await import_promises6.default.writeFile(target, body, { mode: 493 });
+    await import_promises8.default.mkdir(import_node_path9.default.dirname(target), { recursive: true });
+    await import_promises8.default.writeFile(target, body, { mode: 493 });
   }
-  await import_promises6.default.chmod(target, 493);
+  await import_promises8.default.chmod(target, 493);
   return target;
 }
-function whichOnPath(name, pathValue) {
-  for (const dir of pathValue.split(import_node_path6.default.delimiter)) {
-    if (!dir) continue;
-    const candidate = import_node_path6.default.join(dir, name);
-    try {
-      (0, import_node_fs3.accessSync)(candidate, import_node_fs3.constants.X_OK);
-      return candidate;
-    } catch {
-    }
-  }
-  return null;
-}
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
@@ -1698,12 +2223,14 @@ function describeProviderStatus(provider, probe, lastProblem = null, quota = [])
 function describeAuthStatus(provider, probe) {
   const label = PROVIDER_LABEL[provider];
   const installed = probe?.installed === true;
-  const version = typeof probe?.version === "string" ? probe.version : null;
+  const binary = probe?.binary ?? null;
+  const version = binary?.version ?? (typeof probe?.version === "string" ? probe.version : null);
   const base = {
     provider,
     label,
     installed,
     version,
+    binary,
     loggedIn: false,
     billing: "unknown",
     plan: null,
@@ -1755,29 +2282,30 @@ function describeAuthStatus(provider, probe) {
   };
 }
 async function createCodingSessionsEngine(options = {}) {
-  const dataDir = options.dataDir ?? import_node_path6.default.join(import_node_os4.default.homedir(), ".matrx", "coding-sessions");
-  const stateDir = import_node_path6.default.join(dataDir, "paperclip-state");
+  const dataDir = options.dataDir ?? import_node_path9.default.join(import_node_os5.default.homedir(), ".matrx", "coding-sessions");
+  const stateDir = import_node_path9.default.join(dataDir, "paperclip-state");
   const homes = options.homes ?? defaultProviderHomes();
   const index = new RunIndex(dataDir);
   await index.load();
   const preferences = new PreferenceStore(dataDir);
   await preferences.load();
-  await import_promises6.default.mkdir(stateDir, { recursive: true });
+  await import_promises8.default.mkdir(stateDir, { recursive: true });
   const identity = await index.identity();
+  const agents = createAgentConnection(options.agents, dataDir);
   const backups = options.rawBackup ? createRawBackupScheduler({
     sink: options.rawBackup,
     findFile: (provider, providerSessionId) => findSessionFile(provider, providerSessionId, homes),
     onError: (error) => console.warn("[coding-sessions] raw transcript backup failed:", error)
   }) : null;
   const discoveredSeen = /* @__PURE__ */ new Map();
-  const healthFile = import_node_path6.default.join(dataDir, "provider-health.json");
+  const healthFile = import_node_path9.default.join(dataDir, "provider-health.json");
   let health = {};
   try {
-    health = JSON.parse(await import_promises6.default.readFile(healthFile, "utf8"));
+    health = JSON.parse(await import_promises8.default.readFile(healthFile, "utf8"));
   } catch {
     health = {};
   }
-  const saveHealth = () => import_promises6.default.writeFile(healthFile, JSON.stringify(health), { mode: 384 }).catch(() => void 0);
+  const saveHealth = () => import_promises8.default.writeFile(healthFile, JSON.stringify(health), { mode: 384 }).catch(() => void 0);
   function noteRunOutcome(provider, status, texts) {
     if (status === "completed") {
       if (health[provider]) {
@@ -1805,7 +2333,24 @@ async function createCodingSessionsEngine(options = {}) {
     // Marks the forked process as a driver worker (see worker.ts).
     MATRX_CODING_SESSIONS_WORKER: "1"
   });
-  const commandFor = (provider) => options.commands?.[provider] ?? whichOnPath(provider, workerEnv.PATH ?? "");
+  const binaryHome = options.hostEnv?.HOME ?? import_node_os5.default.homedir();
+  const binaryCache = /* @__PURE__ */ new Map();
+  function binaryFor(provider, fresh = false) {
+    const cached = binaryCache.get(provider);
+    if (cached && !fresh && Date.now() - cached.at < 5 * 6e4) return cached.value;
+    const forced = options.commands?.[provider];
+    const value = resolveBinary(provider, {
+      env: workerEnv,
+      home: binaryHome,
+      forced,
+      // A forced command needs no discovery to run; the status check still
+      // looks, so it can say when a newer copy exists.
+      discover: !forced || fresh
+    }).catch(() => forced ? { path: forced, version: null, source: "configured", sourceLabel: "set by host", newer: null } : null);
+    if (!forced || !fresh) binaryCache.set(provider, { at: Date.now(), value });
+    return value;
+  }
+  const commandFor = async (provider) => (await binaryFor(provider))?.path ?? null;
   const workerPath = resolveWorkerPath();
   const shimPath = await installShim(dataDir);
   const listeners = /* @__PURE__ */ new Set();
@@ -1855,7 +2400,7 @@ async function createCodingSessionsEngine(options = {}) {
     }
   }
   function forkWorker() {
-    return (0, import_node_child_process2.fork)(workerPath, [], {
+    return (0, import_node_child_process3.fork)(workerPath, [], {
       env: workerEnv,
       cwd: dataDir,
       stdio: ["ignore", "pipe", "pipe", "ipc"],
@@ -1876,8 +2421,8 @@ async function createCodingSessionsEngine(options = {}) {
   }
   async function startRun(session, prompt) {
     const provider = session.provider;
-    const realCommand = commandFor(provider);
-    const runId = (0, import_node_crypto4.randomUUID)();
+    const realCommand = await commandFor(provider);
+    const runId = (0, import_node_crypto5.randomUUID)();
     const model = session.model ?? (provider === "claude" ? (await userDefaults(provider, session.cwd)).model ?? null : null);
     const run = {
       runId,
@@ -1915,7 +2460,26 @@ async function createCodingSessionsEngine(options = {}) {
     let fileOffset = null;
     if (session.providerSessionId) {
       const file = await findSessionFile(provider, session.providerSessionId, homes);
-      if (file) fileOffset = (await import_promises6.default.stat(file).catch(() => null))?.size ?? null;
+      if (file) fileOffset = (await import_promises8.default.stat(file).catch(() => null))?.size ?? null;
+    }
+    let agentArgs = [];
+    if (session.agent) {
+      const bundle = await agents.readSessionBundle(session.id);
+      if (!bundle) {
+        const failed = saveRun({
+          ...run,
+          status: "failed",
+          endedAt: nowIso(),
+          error: `The agent ${session.agent.name} could not be loaded on this computer anymore. Start a new session to load it again.`
+        });
+        const current = index.session(session.id);
+        if (current) saveSession({ ...current, lastRunStatus: "failed" });
+        return failed;
+      }
+      const attachment = await writeAgentAttachment(agents.sessionDir(session.id), bundle, {
+        mcpUrl: await agents.mcpUrlFor(session.id)
+      });
+      agentArgs = agentArgsFor(provider, attachment, { resuming: session.providerSessionId !== null });
     }
     const child = forkWorker();
     const liveRun = {
@@ -2089,7 +2653,8 @@ async function createCodingSessionsEngine(options = {}) {
       resumeSessionId: session.providerSessionId,
       shimPath,
       realCommand,
-      identity
+      identity,
+      agentArgs
     });
     return run;
   }
@@ -2108,7 +2673,7 @@ async function createCodingSessionsEngine(options = {}) {
     }, 3e3);
   }
   async function pruneDriverScratch() {
-    const runsDir = import_node_path6.default.join(
+    const runsDir = import_node_path9.default.join(
       stateDir,
       "instances",
       "default",
@@ -2119,12 +2684,13 @@ async function createCodingSessionsEngine(options = {}) {
       "claude-runtime",
       "runs"
     );
-    const entries = await import_promises6.default.readdir(runsDir).catch(() => []);
+    const entries = await import_promises8.default.readdir(runsDir).catch(() => []);
     await Promise.all(
-      entries.filter((name) => !live.has(name)).map((name) => import_promises6.default.rm(import_node_path6.default.join(runsDir, name), { recursive: true, force: true }).catch(() => void 0))
+      entries.filter((name) => !live.has(name)).map((name) => import_promises8.default.rm(import_node_path9.default.join(runsDir, name), { recursive: true, force: true }).catch(() => void 0))
     );
   }
   async function probe() {
+    const [claudeBinary, codexBinary] = await Promise.all([binaryFor("claude", true), binaryFor("codex", true)]);
     return new Promise((resolve) => {
       const child = forkWorker();
       let answered = false;
@@ -2140,8 +2706,8 @@ async function createCodingSessionsEngine(options = {}) {
           answered = true;
           clearTimeout(timer);
           resolve({
-            claude: message.claude ?? {},
-            codex: message.codex ?? {}
+            claude: { ...message.claude ?? {}, binary: claudeBinary },
+            codex: { ...message.codex ?? {}, binary: codexBinary }
           });
         }
       });
@@ -2153,7 +2719,7 @@ async function createCodingSessionsEngine(options = {}) {
       });
       child.send({
         kind: "probe",
-        commands: { claude: commandFor("claude"), codex: commandFor("codex") },
+        commands: { claude: claudeBinary?.path ?? null, codex: codexBinary?.path ?? null },
         quota: options.quota !== false
       });
     });
@@ -2161,7 +2727,7 @@ async function createCodingSessionsEngine(options = {}) {
   function newSession(input) {
     const at = nowIso();
     return {
-      id: (0, import_node_crypto4.randomUUID)(),
+      id: (0, import_node_crypto5.randomUUID)(),
       provider: input.provider,
       providerSessionId: input.providerSessionId,
       cwd: input.cwd,
@@ -2179,17 +2745,17 @@ async function createCodingSessionsEngine(options = {}) {
   function resolveFolder(raw) {
     const trimmed = raw.trim();
     if (!trimmed) return null;
-    return import_node_path6.default.resolve(trimmed.replace(/^~(?=$|\/)/, import_node_os4.default.homedir()));
+    return import_node_path9.default.resolve(trimmed.replace(/^~(?=$|\/)/, import_node_os5.default.homedir()));
   }
   async function checkFolder(raw) {
     const target = resolveFolder(raw);
     if (!target) return { path: "", exists: false, isDirectory: false };
-    const stat = await import_promises6.default.stat(target).catch(() => null);
+    const stat = await import_promises8.default.stat(target).catch(() => null);
     return { path: target, exists: stat !== null, isDirectory: stat?.isDirectory() === true };
   }
   async function assertFolder(cwd) {
-    const resolved = import_node_path6.default.resolve(cwd.replace(/^~(?=$|\/)/, import_node_os4.default.homedir()));
-    const stat = await import_promises6.default.stat(resolved).catch(() => null);
+    const resolved = import_node_path9.default.resolve(cwd.replace(/^~(?=$|\/)/, import_node_os5.default.homedir()));
+    const stat = await import_promises8.default.stat(resolved).catch(() => null);
     if (!stat?.isDirectory()) {
       throw new Error(`The folder ${resolved} doesn't exist on this computer.`);
     }
@@ -2251,7 +2817,7 @@ async function createCodingSessionsEngine(options = {}) {
         folders.map(async ([folder, lastUsedAt]) => ({
           path: folder,
           lastUsedAt,
-          exists: (await import_promises6.default.stat(folder).catch(() => null))?.isDirectory() === true
+          exists: (await import_promises8.default.stat(folder).catch(() => null))?.isDirectory() === true
         }))
       );
     },
@@ -2296,7 +2862,7 @@ async function createCodingSessionsEngine(options = {}) {
     async createFolder(raw) {
       const target = resolveFolder(raw);
       if (!target) throw new Error("Type a folder path first.");
-      await import_promises6.default.mkdir(target, { recursive: true });
+      await import_promises8.default.mkdir(target, { recursive: true });
       return checkFolder(target);
     },
     async sessionActivity(provider, providerSessionId) {
@@ -2334,31 +2900,35 @@ async function createCodingSessionsEngine(options = {}) {
           reason: `${PROVIDER_LABEL[provider]} has no saved transcript for this chat on this computer.`
         };
       }
-      const stat = await import_promises6.default.stat(file);
+      const stat = await import_promises8.default.stat(file);
       if (stat.size > RAW_TRANSCRIPT_MAX_BYTES) {
         return {
           available: false,
           reason: `This transcript is ${(0, import_format.formatFileSize)(stat.size)}, larger than the ${(0, import_format.formatFileSize)(RAW_TRANSCRIPT_MAX_BYTES)} this page can hand over. It is at ${file}.`
         };
       }
-      const content = await import_promises6.default.readFile(file, "utf8");
-      return { available: true, fileName: import_node_path6.default.basename(file), bytes: stat.size, content };
+      const content = await import_promises8.default.readFile(file, "utf8");
+      return { available: true, fileName: import_node_path9.default.basename(file), bytes: stat.size, content };
     },
     async start(input) {
       const prompt = input.prompt.trim();
       if (!prompt) throw new Error("Type what you want done before starting.");
       const cwd = await assertFolder(input.cwd);
-      const session = saveSession(
-        newSession({
-          provider: input.provider,
-          cwd,
-          title: titleFrom(prompt),
-          model: input.model?.trim() || null,
-          effort: input.effort?.trim() || null,
-          origin: "started",
-          providerSessionId: null
-        })
-      );
+      const bundle = input.agent ? await agents.loadBundle(input.agent) : null;
+      const draft = newSession({
+        provider: input.provider,
+        cwd,
+        title: titleFrom(prompt),
+        model: input.model?.trim() || null,
+        effort: input.effort?.trim() || null,
+        origin: "started",
+        providerSessionId: null
+      });
+      if (bundle) {
+        await agents.saveSessionBundle(draft.id, bundle);
+        draft.agent = sessionAgentRecord(bundle, { toolsServed: await agents.mcpUrlFor(draft.id) !== null });
+      }
+      const session = saveSession(draft);
       const run = await startRun(session, prompt);
       return { session: index.session(session.id) ?? session, run, queued: false };
     },
@@ -2427,6 +2997,21 @@ async function createCodingSessionsEngine(options = {}) {
       if (opts && "effort" in opts) next.effort = typeof opts.effort === "string" && opts.effort.trim() ? opts.effort.trim() : null;
       return saveSession(next);
     },
+    async agentAccess() {
+      return agents.access();
+    },
+    async agentCatalogRpc(request) {
+      return agents.catalogRpc(request);
+    },
+    async agentDetails(agentId) {
+      return agents.details(String(agentId ?? ""));
+    },
+    setMcpBaseUrl(baseUrl) {
+      agents.setMcpBaseUrl(baseUrl);
+    },
+    async handleMcp(secret, body) {
+      return agents.handleMcp(secret, body);
+    },
     async dispose() {
       for (const liveRun of live.values()) {
         liveRun.stopRequested = true;
@@ -2463,7 +3048,7 @@ function openFolderIn(folder, target) {
     args = ["-a", app.app, folder];
   }
   return new Promise((resolve, reject) => {
-    (0, import_node_child_process2.execFile)(command, args, { timeout: 1e4 }, (error) => {
+    (0, import_node_child_process3.execFile)(command, args, { timeout: 1e4 }, (error) => {
       if (!error) return resolve();
       const label = target === "finder" ? "the folder" : OPEN_APP[target]?.label ?? target;
       reject(