@ai-matrx/coding-sessions 0.1.80 → 0.1.83

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @ai-matrx/coding-sessions
 
+## 0.1.83
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/coding-sessions/v0.1.81..npm/coding-sessions/v0.1.83 -- apps/shared/coding-sessions`).
+No source changes intended and no consumer action required.
+
+## 0.1.82
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/coding-sessions/v0.1.81..npm/coding-sessions/v0.1.82 -- apps/shared/coding-sessions`).
+No source changes intended and no consumer action required.
+
+## 0.1.81
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/coding-sessions/v0.1.80..npm/coding-sessions/v0.1.81 -- apps/shared/coding-sessions`).
+No source changes intended and no consumer action required.
+
 ## 0.1.80
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

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_child_process3 = require("child_process");
 var import_node_crypto4 = require("crypto");
-var import_node_fs3 = require("fs");
+var import_node_fs4 = require("fs");
 var import_format = require("@ai-matrx/kit/format");
 
 // src/engine/raw-backup.ts
@@ -161,8 +161,8 @@ function createAiMatrxRawBackupSink(options) {
 
 // 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_node_os5 = __toESM(require("os"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 
 // src/normalize/claude.ts
@@ -828,9 +828,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 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_path.default.delimiter)) {
+    if (!dir) continue;
+    for (const file of exeName(name, platform)) {
+      const candidate = import_node_path.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_path.default.join(apps, "ChatGPT.app", "Contents", "Resources", "codex-cli", "bin", "codex")
+    );
+  }
+  const root = import_node_path.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_path.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_path.default.join(import_node_path.default.dirname(import_node_path.default.dirname(file)), "codex-package.json"), "utf8"));
+      return typeof pkg.version === "string" ? parseVersion(pkg.version) : null;
+    } catch {
+      return null;
+    }
+  }
+  return parseVersion(import_node_path.default.basename(import_node_path.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_path.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_path.default.join(prefix, "bin");
+    for (const file of exeName(provider, platform)) {
+      const candidate = import_node_path.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_path2 = __toESM(require("path"), 1);
 var ALLOWED_NAMES = /* @__PURE__ */ new Set([
   "HOME",
   "USER",
@@ -852,11 +1020,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_path2.default.join(home, ".local", "bin"),
+    import_node_path2.default.join(home, ".claude", "local"),
+    import_node_path2.default.join(home, ".npm-global", "bin"),
+    import_node_path2.default.join(home, ".bun", "bin"),
+    import_node_path2.default.join(home, ".volta", "bin"),
     "/opt/homebrew/bin",
     "/usr/local/bin",
     "/usr/bin",
@@ -874,31 +1042,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_path2.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_path2.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_node_fs2 = 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_os3 = __toESM(require("os"), 1);
+var import_node_path3 = __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,11 +1125,11 @@ 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_path3.default.join(home, ".claude", "projects"),
+    codexSessions: import_node_path3.default.join(home, ".codex", "sessions"),
+    codexIndex: import_node_path3.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;
@@ -986,10 +1154,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_path3.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_path3.default.join(dir, e.name)))
     );
     for (const s of stats) if (s) out.push(s);
   }
@@ -999,14 +1167,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_path3.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_path3.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_path3.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_path3.default.join(dir, e.name)))
         );
         for (const s of stats) if (s) out.push(s);
       }
@@ -1227,7 +1395,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");
@@ -1267,7 +1435,7 @@ 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_path4 = __toESM(require("path"), 1);
 var PreferenceStore = class {
   constructor(dir) {
     this.dir = dir;
@@ -1276,7 +1444,7 @@ var PreferenceStore = class {
   data = {};
   writing = Promise.resolve();
   get file() {
-    return import_node_path3.default.join(this.dir, "preferences.json");
+    return import_node_path4.default.join(this.dir, "preferences.json");
   }
   async load() {
     try {
@@ -1331,7 +1499,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 +1540,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;
@@ -1480,7 +1648,7 @@ 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_path5 = __toESM(require("path"), 1);
 var MAX_RUNS = 2e3;
 var RunIndex = class {
   constructor(dir) {
@@ -1490,7 +1658,7 @@ 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_path5.default.join(this.dir, "index.json");
   }
   async load() {
     await import_promises4.default.mkdir(this.dir, { recursive: true });
@@ -1549,7 +1717,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 = import_node_path4.default.join(this.dir, "identity.json");
+    const file = import_node_path5.default.join(this.dir, "identity.json");
     try {
       const parsed = JSON.parse(await import_promises4.default.readFile(file, "utf8"));
       if (typeof parsed.companyId === "string" && typeof parsed.agentId === "string") {
@@ -1565,8 +1733,8 @@ var RunIndex = class {
 
 // 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_node_os4 = __toESM(require("os"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
 async function readJson(file) {
   try {
     const parsed = JSON.parse(await import_promises5.default.readFile(file, "utf8"));
@@ -1578,10 +1746,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_path6.default.join(cwd, ".claude", "settings.local.json"), import_node_path6.default.join(cwd, ".claude", "settings.json")] : [],
+    import_node_path6.default.join(home, ".claude", "settings.json")
   ];
   let model = null;
   let effort = null;
@@ -1594,10 +1762,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_promises5.default.readFile(import_node_path6.default.join(home, ".codex", "config.toml"), "utf8");
   } catch {
     return { model: null, effort: null };
   }
@@ -1621,45 +1789,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_path7.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_path7.default.join(dir, "worker.js"),
+    import_node_path7.default.join(dir, "worker.ts"),
+    import_node_path7.default.join(dir, "..", "engine", "worker.js"),
+    import_node_path7.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 source = import_node_path7.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_promises6.default.readFile(source, "utf8");
-  const target = import_node_path6.default.join(dataDir, "bin", "cli-shim.sh");
+  const target = import_node_path7.default.join(dataDir, "bin", "cli-shim.sh");
   const current = await import_promises6.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.mkdir(import_node_path7.default.dirname(target), { recursive: true });
     await import_promises6.default.writeFile(target, body, { mode: 493 });
   }
   await import_promises6.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 +1854,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,8 +1913,8 @@ 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_path7.default.join(import_node_os5.default.homedir(), ".matrx", "coding-sessions");
+  const stateDir = import_node_path7.default.join(dataDir, "paperclip-state");
   const homes = options.homes ?? defaultProviderHomes();
   const index = new RunIndex(dataDir);
   await index.load();
@@ -1770,7 +1928,7 @@ async function createCodingSessionsEngine(options = {}) {
     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_path7.default.join(dataDir, "provider-health.json");
   let health = {};
   try {
     health = JSON.parse(await import_promises6.default.readFile(healthFile, "utf8"));
@@ -1805,7 +1963,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 +2030,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,7 +2051,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 = (0, import_node_crypto4.randomUUID)();
     const model = session.model ?? (provider === "claude" ? (await userDefaults(provider, session.cwd)).model ?? null : null);
     const run = {
@@ -2108,7 +2283,7 @@ async function createCodingSessionsEngine(options = {}) {
     }, 3e3);
   }
   async function pruneDriverScratch() {
-    const runsDir = import_node_path6.default.join(
+    const runsDir = import_node_path7.default.join(
       stateDir,
       "instances",
       "default",
@@ -2121,10 +2296,11 @@ async function createCodingSessionsEngine(options = {}) {
     );
     const entries = await import_promises6.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_promises6.default.rm(import_node_path7.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 +2316,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 +2329,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
       });
     });
@@ -2179,7 +2355,7 @@ 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_path7.default.resolve(trimmed.replace(/^~(?=$|\/)/, import_node_os5.default.homedir()));
   }
   async function checkFolder(raw) {
     const target = resolveFolder(raw);
@@ -2188,7 +2364,7 @@ async function createCodingSessionsEngine(options = {}) {
     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 resolved = import_node_path7.default.resolve(cwd.replace(/^~(?=$|\/)/, import_node_os5.default.homedir()));
     const stat = await import_promises6.default.stat(resolved).catch(() => null);
     if (!stat?.isDirectory()) {
       throw new Error(`The folder ${resolved} doesn't exist on this computer.`);
@@ -2342,7 +2518,7 @@ async function createCodingSessionsEngine(options = {}) {
         };
       }
       const content = await import_promises6.default.readFile(file, "utf8");
-      return { available: true, fileName: import_node_path6.default.basename(file), bytes: stat.size, content };
+      return { available: true, fileName: import_node_path7.default.basename(file), bytes: stat.size, content };
     },
     async start(input) {
       const prompt = input.prompt.trim();
@@ -2463,7 +2639,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(