@ai-matrx/coding-sessions 0.1.81 → 0.1.83

package/dist/engine/index.d.cts

@@ -1 +1 @@
-export { c as CodingSessionsEngine, d as CodingSessionsEngineOptions, E as EFFORT_LEVELS, P as PreferenceStore, e as ProviderHomes, R as RAW_TRANSCRIPT_MAX_BYTES, f as RawBackupPolicy, g as RawBackupSink, h as RunStatus, i as buildCleanEnv, j as claudeDefaults, k as codexDefaults, l as createAiMatrxRawBackupSink, m as createCodingSessionsEngine, n as createRawBackupScheduler, o as defaultProviderHomes, p as describeActivity, q as describeProviderStatus, r as discoverLocalSessions, s as endsWithOpenToolCall, t as findDrivingProcess, u as findSessionFile, v as isAllowedEnvName, w as listProcesses, x as readSessionFile, y as searchLocalChats, z as sessionActivity, A as snippetAround } from '../index-RYOb-YZT.cjs';
+export { c as CodingSessionsEngine, d as CodingSessionsEngineOptions, E as EFFORT_LEVELS, P as PreferenceStore, e as ProviderHomes, R as RAW_TRANSCRIPT_MAX_BYTES, f as RawBackupPolicy, g as RawBackupSink, h as RunStatus, i as buildCleanEnv, j as claudeDefaults, k as codexDefaults, l as createAiMatrxRawBackupSink, m as createCodingSessionsEngine, n as createRawBackupScheduler, o as defaultProviderHomes, p as describeActivity, q as describeProviderStatus, r as discoverLocalSessions, s as endsWithOpenToolCall, t as findDrivingProcess, u as findSessionFile, v as isAllowedEnvName, w as listProcesses, x as readSessionFile, y as searchLocalChats, z as sessionActivity, A as snippetAround } from '../index-DQ0teQvw.cjs';

package/dist/engine/index.d.ts

@@ -1 +1 @@
-export { c as CodingSessionsEngine, d as CodingSessionsEngineOptions, E as EFFORT_LEVELS, P as PreferenceStore, e as ProviderHomes, R as RAW_TRANSCRIPT_MAX_BYTES, f as RawBackupPolicy, g as RawBackupSink, h as RunStatus, i as buildCleanEnv, j as claudeDefaults, k as codexDefaults, l as createAiMatrxRawBackupSink, m as createCodingSessionsEngine, n as createRawBackupScheduler, o as defaultProviderHomes, p as describeActivity, q as describeProviderStatus, r as discoverLocalSessions, s as endsWithOpenToolCall, t as findDrivingProcess, u as findSessionFile, v as isAllowedEnvName, w as listProcesses, x as readSessionFile, y as searchLocalChats, z as sessionActivity, A as snippetAround } from '../index-RYOb-YZT.js';
+export { c as CodingSessionsEngine, d as CodingSessionsEngineOptions, E as EFFORT_LEVELS, P as PreferenceStore, e as ProviderHomes, R as RAW_TRANSCRIPT_MAX_BYTES, f as RawBackupPolicy, g as RawBackupSink, h as RunStatus, i as buildCleanEnv, j as claudeDefaults, k as codexDefaults, l as createAiMatrxRawBackupSink, m as createCodingSessionsEngine, n as createRawBackupScheduler, o as defaultProviderHomes, p as describeActivity, q as describeProviderStatus, r as discoverLocalSessions, s as endsWithOpenToolCall, t as findDrivingProcess, u as findSessionFile, v as isAllowedEnvName, w as listProcesses, x as readSessionFile, y as searchLocalChats, z as sessionActivity, A as snippetAround } from '../index-DQ0teQvw.js';

package/dist/engine/index.js

@@ -1,7 +1,7 @@
 // src/engine/index.ts
-import { execFile as execFile2, fork } from "child_process";
+import { execFile as execFile3, fork } from "child_process";
 import { randomUUID as randomUUID3 } from "crypto";
-import { accessSync, constants as fsConstants, existsSync } from "fs";
+import { existsSync } from "fs";
 import { formatFileSize } from "@ai-matrx/kit/format";
 
 // src/engine/raw-backup.ts
@@ -100,8 +100,8 @@ function createAiMatrxRawBackupSink(options) {
 
 // src/engine/index.ts
 import fs6 from "fs/promises";
-import os4 from "os";
-import path6 from "path";
+import os5 from "os";
+import path7 from "path";
 import { fileURLToPath } from "url";
 
 // src/normalize/claude.ts
@@ -767,9 +767,177 @@ function describeProblem(provider, problem) {
   };
 }
 
-// src/engine/clean-env.ts
+// src/engine/binaries.ts
+import { execFile } from "child_process";
+import { accessSync, constants as fsConstants, readdirSync, readFileSync, realpathSync } from "fs";
 import os from "os";
 import path from "path";
+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 {
+    accessSync(file, fsConstants.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(path.delimiter)) {
+    if (!dir) continue;
+    for (const file of exeName(name, platform)) {
+      const candidate = path.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) => path.join(apps, "ChatGPT.app", "Contents", "Resources", "codex-cli", "bin", "codex")
+    );
+  }
+  const root = path.join(home, "Library", "Application Support", "Claude", "claude-code");
+  let versions = [];
+  try {
+    versions = readdirSync(root);
+  } catch {
+    return [];
+  }
+  return versions.map((v) => path.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 = 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(readFileSync(path.join(path.dirname(path.dirname(file)), "codex-package.json"), "utf8"));
+      return typeof pkg.version === "string" ? parseVersion(pkg.version) : null;
+    } catch {
+      return null;
+    }
+  }
+  return parseVersion(path.basename(path.resolve(file, "..", "..", "..", "..")));
+}
+function runVersion(file, env) {
+  return new Promise((resolve) => {
+    const child = 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 ?? os.homedir();
+  const listed2 = [
+    ...desktopAppCandidates(provider, platform, home, options.applications ?? ["/Applications", path.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 : path.join(prefix, "bin");
+    for (const file of exeName(provider, platform)) {
+      const candidate = path.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 = 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
+import os2 from "os";
+import path2 from "path";
 var ALLOWED_NAMES = /* @__PURE__ */ new Set([
   "HOME",
   "USER",
@@ -791,11 +959,11 @@ var ALLOWED_NAMES = /* @__PURE__ */ new Set([
 var ALLOWED_PREFIXES = ["LC_"];
 function wellKnownBinDirs(home) {
   return [
-    path.join(home, ".local", "bin"),
-    path.join(home, ".claude", "local"),
-    path.join(home, ".npm-global", "bin"),
-    path.join(home, ".bun", "bin"),
-    path.join(home, ".volta", "bin"),
+    path2.join(home, ".local", "bin"),
+    path2.join(home, ".claude", "local"),
+    path2.join(home, ".npm-global", "bin"),
+    path2.join(home, ".bun", "bin"),
+    path2.join(home, ".volta", "bin"),
     "/opt/homebrew/bin",
     "/usr/local/bin",
     "/usr/bin",
@@ -813,14 +981,14 @@ function buildCleanEnv(hostEnv, extra = {}) {
     if (typeof value !== "string") continue;
     if (isAllowedEnvName(name)) out[name] = value;
   }
-  const home = out.HOME ?? os.homedir();
+  const home = out.HOME ?? os2.homedir();
   out.HOME = home;
-  const hostPath = (hostEnv.PATH ?? "").split(path.delimiter).filter(Boolean);
+  const hostPath = (hostEnv.PATH ?? "").split(path2.delimiter).filter(Boolean);
   const merged = [];
   for (const dir of [...hostPath, ...wellKnownBinDirs(home)]) {
     if (!merged.includes(dir)) merged.push(dir);
   }
-  out.PATH = merged.join(path.delimiter);
+  out.PATH = merged.join(path2.delimiter);
   for (const [name, value] of Object.entries(extra)) out[name] = value;
   return out;
 }
@@ -828,16 +996,16 @@ function buildCleanEnv(hostEnv, extra = {}) {
 // src/engine/files.ts
 import { createReadStream } from "fs";
 import fs2 from "fs/promises";
-import os2 from "os";
-import path2 from "path";
+import os3 from "os";
+import path3 from "path";
 
 // src/engine/activity.ts
-import { execFile } from "child_process";
+import { execFile as execFile2 } from "child_process";
 var RECENT_WRITE_MS = 2 * 60 * 1e3;
 var OPEN_TOOL_WINDOW_MS = 15 * 60 * 1e3;
 function listProcesses() {
   return new Promise((resolve) => {
-    execFile("ps", ["-axww", "-o", "pid=,args="], { maxBuffer: 64 * 1024 * 1024, timeout: 5e3 }, (error, stdout) => {
+    execFile2("ps", ["-axww", "-o", "pid=,args="], { maxBuffer: 64 * 1024 * 1024, timeout: 5e3 }, (error, stdout) => {
       if (error) {
         resolve([]);
         return;
@@ -896,11 +1064,11 @@ function describeActivity(input) {
 }
 
 // src/engine/files.ts
-function defaultProviderHomes(home = os2.homedir()) {
+function defaultProviderHomes(home = os3.homedir()) {
   return {
-    claudeProjects: path2.join(home, ".claude", "projects"),
-    codexSessions: path2.join(home, ".codex", "sessions"),
-    codexIndex: path2.join(home, ".codex", "session_index.jsonl")
+    claudeProjects: path3.join(home, ".claude", "projects"),
+    codexSessions: path3.join(home, ".codex", "sessions"),
+    codexIndex: path3.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;
@@ -925,10 +1093,10 @@ async function claudeCandidates(root) {
   const out = [];
   for (const project of await safeReaddir(root)) {
     if (!project.isDirectory()) continue;
-    const dir = path2.join(root, project.name);
+    const dir = path3.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", path2.join(dir, e.name)))
+      entries.filter((e) => e.isFile() && e.name.endsWith(".jsonl")).map((e) => statCandidate("claude", path3.join(dir, e.name)))
     );
     for (const s of stats) if (s) out.push(s);
   }
@@ -938,14 +1106,14 @@ async function codexCandidates(root) {
   const out = [];
   for (const year of await safeReaddir(root)) {
     if (!year.isDirectory()) continue;
-    for (const month of await safeReaddir(path2.join(root, year.name))) {
+    for (const month of await safeReaddir(path3.join(root, year.name))) {
       if (!month.isDirectory()) continue;
-      for (const day of await safeReaddir(path2.join(root, year.name, month.name))) {
+      for (const day of await safeReaddir(path3.join(root, year.name, month.name))) {
         if (!day.isDirectory()) continue;
-        const dir = path2.join(root, year.name, month.name, day.name);
+        const dir = path3.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", path2.join(dir, e.name)))
+          entries.filter((e) => e.isFile() && e.name.startsWith("rollout-") && e.name.endsWith(".jsonl")).map((e) => statCandidate("codex", path3.join(dir, e.name)))
         );
         for (const s of stats) if (s) out.push(s);
       }
@@ -1206,7 +1374,7 @@ async function describeSessionFile(candidate, codexNames) {
 // src/engine/preferences.ts
 import { randomUUID } from "crypto";
 import fs3 from "fs/promises";
-import path3 from "path";
+import path4 from "path";
 var PreferenceStore = class {
   constructor(dir) {
     this.dir = dir;
@@ -1215,7 +1383,7 @@ var PreferenceStore = class {
   data = {};
   writing = Promise.resolve();
   get file() {
-    return path3.join(this.dir, "preferences.json");
+    return path4.join(this.dir, "preferences.json");
   }
   async load() {
     try {
@@ -1419,7 +1587,7 @@ async function searchLocalChats(query, options = {}) {
 // src/engine/store.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import fs4 from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 var MAX_RUNS = 2e3;
 var RunIndex = class {
   constructor(dir) {
@@ -1429,7 +1597,7 @@ var RunIndex = class {
   data = { version: 1, sessions: [], runs: [] };
   writing = Promise.resolve();
   get file() {
-    return path4.join(this.dir, "index.json");
+    return path5.join(this.dir, "index.json");
   }
   async load() {
     await fs4.mkdir(this.dir, { recursive: true });
@@ -1488,7 +1656,7 @@ 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 = path4.join(this.dir, "identity.json");
+    const file = path5.join(this.dir, "identity.json");
     try {
       const parsed = JSON.parse(await fs4.readFile(file, "utf8"));
       if (typeof parsed.companyId === "string" && typeof parsed.agentId === "string") {
@@ -1504,8 +1672,8 @@ var RunIndex = class {
 
 // src/engine/user-defaults.ts
 import fs5 from "fs/promises";
-import os3 from "os";
-import path5 from "path";
+import os4 from "os";
+import path6 from "path";
 async function readJson(file) {
   try {
     const parsed = JSON.parse(await fs5.readFile(file, "utf8"));
@@ -1517,10 +1685,10 @@ async function readJson(file) {
 function str3(value) {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
-async function claudeDefaults(cwd, home = os3.homedir()) {
+async function claudeDefaults(cwd, home = os4.homedir()) {
   const files = [
-    ...cwd ? [path5.join(cwd, ".claude", "settings.local.json"), path5.join(cwd, ".claude", "settings.json")] : [],
-    path5.join(home, ".claude", "settings.json")
+    ...cwd ? [path6.join(cwd, ".claude", "settings.local.json"), path6.join(cwd, ".claude", "settings.json")] : [],
+    path6.join(home, ".claude", "settings.json")
   ];
   let model = null;
   let effort = null;
@@ -1533,10 +1701,10 @@ async function claudeDefaults(cwd, home = os3.homedir()) {
   }
   return { model, effort };
 }
-async function codexDefaults(home = os3.homedir()) {
+async function codexDefaults(home = os4.homedir()) {
   let text;
   try {
-    text = await fs5.readFile(path5.join(home, ".codex", "config.toml"), "utf8");
+    text = await fs5.readFile(path6.join(home, ".codex", "config.toml"), "utf8");
   } catch {
     return { model: null, effort: null };
   }
@@ -1560,45 +1728,33 @@ var EFFORT_LEVELS = {
 // src/engine/index.ts
 var RAW_TRANSCRIPT_MAX_BYTES = 200 * 1048576;
 function moduleDir() {
-  return path6.dirname(fileURLToPath(import.meta.url));
+  return path7.dirname(fileURLToPath(import.meta.url));
 }
 function resolveWorkerPath() {
   const dir = moduleDir();
   for (const candidate of [
-    path6.join(dir, "worker.js"),
-    path6.join(dir, "worker.ts"),
-    path6.join(dir, "..", "engine", "worker.js"),
-    path6.join(dir, "..", "engine", "worker.ts")
+    path7.join(dir, "worker.js"),
+    path7.join(dir, "worker.ts"),
+    path7.join(dir, "..", "engine", "worker.js"),
+    path7.join(dir, "..", "engine", "worker.ts")
   ]) {
     if (existsSync(candidate)) return candidate;
   }
   throw new Error(`[coding-sessions] The driver worker is missing next to ${dir}.`);
 }
 async function installShim(dataDir) {
-  const source = path6.resolve(moduleDir(), "..", "..", "bin", "cli-shim.sh");
+  const source = path7.resolve(moduleDir(), "..", "..", "bin", "cli-shim.sh");
   if (!existsSync(source)) throw new Error(`[coding-sessions] The CLI shim is missing at ${source}.`);
   const body = await fs6.readFile(source, "utf8");
-  const target = path6.join(dataDir, "bin", "cli-shim.sh");
+  const target = path7.join(dataDir, "bin", "cli-shim.sh");
   const current = await fs6.readFile(target, "utf8").catch(() => null);
   if (current !== body) {
-    await fs6.mkdir(path6.dirname(target), { recursive: true });
+    await fs6.mkdir(path7.dirname(target), { recursive: true });
     await fs6.writeFile(target, body, { mode: 493 });
   }
   await fs6.chmod(target, 493);
   return target;
 }
-function whichOnPath(name, pathValue) {
-  for (const dir of pathValue.split(path6.delimiter)) {
-    if (!dir) continue;
-    const candidate = path6.join(dir, name);
-    try {
-      accessSync(candidate, fsConstants.X_OK);
-      return candidate;
-    } catch {
-    }
-  }
-  return null;
-}
 function nowIso() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
@@ -1637,12 +1793,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,
@@ -1694,8 +1852,8 @@ function describeAuthStatus(provider, probe) {
   };
 }
 async function createCodingSessionsEngine(options = {}) {
-  const dataDir = options.dataDir ?? path6.join(os4.homedir(), ".matrx", "coding-sessions");
-  const stateDir = path6.join(dataDir, "paperclip-state");
+  const dataDir = options.dataDir ?? path7.join(os5.homedir(), ".matrx", "coding-sessions");
+  const stateDir = path7.join(dataDir, "paperclip-state");
   const homes = options.homes ?? defaultProviderHomes();
   const index = new RunIndex(dataDir);
   await index.load();
@@ -1709,7 +1867,7 @@ async function createCodingSessionsEngine(options = {}) {
     onError: (error) => console.warn("[coding-sessions] raw transcript backup failed:", error)
   }) : null;
   const discoveredSeen = /* @__PURE__ */ new Map();
-  const healthFile = path6.join(dataDir, "provider-health.json");
+  const healthFile = path7.join(dataDir, "provider-health.json");
   let health = {};
   try {
     health = JSON.parse(await fs6.readFile(healthFile, "utf8"));
@@ -1744,7 +1902,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 ?? os5.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();
@@ -1815,7 +1990,7 @@ async function createCodingSessionsEngine(options = {}) {
   }
   async function startRun(session, prompt) {
     const provider = session.provider;
-    const realCommand = commandFor(provider);
+    const realCommand = await commandFor(provider);
     const runId = randomUUID3();
     const model = session.model ?? (provider === "claude" ? (await userDefaults(provider, session.cwd)).model ?? null : null);
     const run = {
@@ -2047,7 +2222,7 @@ async function createCodingSessionsEngine(options = {}) {
     }, 3e3);
   }
   async function pruneDriverScratch() {
-    const runsDir = path6.join(
+    const runsDir = path7.join(
       stateDir,
       "instances",
       "default",
@@ -2060,10 +2235,11 @@ async function createCodingSessionsEngine(options = {}) {
     );
     const entries = await fs6.readdir(runsDir).catch(() => []);
     await Promise.all(
-      entries.filter((name) => !live.has(name)).map((name) => fs6.rm(path6.join(runsDir, name), { recursive: true, force: true }).catch(() => void 0))
+      entries.filter((name) => !live.has(name)).map((name) => fs6.rm(path7.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;
@@ -2079,8 +2255,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 }
           });
         }
       });
@@ -2092,7 +2268,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
       });
     });
@@ -2118,7 +2294,7 @@ async function createCodingSessionsEngine(options = {}) {
   function resolveFolder(raw) {
     const trimmed = raw.trim();
     if (!trimmed) return null;
-    return path6.resolve(trimmed.replace(/^~(?=$|\/)/, os4.homedir()));
+    return path7.resolve(trimmed.replace(/^~(?=$|\/)/, os5.homedir()));
   }
   async function checkFolder(raw) {
     const target = resolveFolder(raw);
@@ -2127,7 +2303,7 @@ async function createCodingSessionsEngine(options = {}) {
     return { path: target, exists: stat !== null, isDirectory: stat?.isDirectory() === true };
   }
   async function assertFolder(cwd) {
-    const resolved = path6.resolve(cwd.replace(/^~(?=$|\/)/, os4.homedir()));
+    const resolved = path7.resolve(cwd.replace(/^~(?=$|\/)/, os5.homedir()));
     const stat = await fs6.stat(resolved).catch(() => null);
     if (!stat?.isDirectory()) {
       throw new Error(`The folder ${resolved} doesn't exist on this computer.`);
@@ -2281,7 +2457,7 @@ async function createCodingSessionsEngine(options = {}) {
         };
       }
       const content = await fs6.readFile(file, "utf8");
-      return { available: true, fileName: path6.basename(file), bytes: stat.size, content };
+      return { available: true, fileName: path7.basename(file), bytes: stat.size, content };
     },
     async start(input) {
       const prompt = input.prompt.trim();
@@ -2402,7 +2578,7 @@ function openFolderIn(folder, target) {
     args = ["-a", app.app, folder];
   }
   return new Promise((resolve, reject) => {
-    execFile2(command, args, { timeout: 1e4 }, (error) => {
+    execFile3(command, args, { timeout: 1e4 }, (error) => {
       if (!error) return resolve();
       const label = target === "finder" ? "the folder" : OPEN_APP[target]?.label ?? target;
       reject(