agent-shim 8.9.0 → 8.10.0

package/dist/index.cjs

@@ -268,8 +268,113 @@ var categories_default_default = {
 };
 
 // src/config/schema.ts
-var import_node_path = __toESM(require("node:path"), 1);
+var import_node_path2 = __toESM(require("node:path"), 1);
 var import_zod = require("zod");
+
+// src/versionDiscovery.ts
+var import_node_os = __toESM(require("node:os"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+
+// src/cliError.ts
+var EXIT_FAILURE = 1;
+var EXIT_USAGE = 2;
+var CliError = class extends Error {
+  /** The process exit status this failure maps to. `EXIT_FAILURE` unless a subclass says otherwise. */
+  exitCode = EXIT_FAILURE;
+};
+var UsageError = class extends CliError {
+  exitCode = EXIT_USAGE;
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+};
+
+// src/versionDiscovery.ts
+function defaultVersionsDir() {
+  return import_node_path.default.join(import_node_os.default.homedir(), ".local", "share", "claude", "versions");
+}
+var NUMERIC_DOTTED_VERSION_RE = /^\d+(?:\.\d+)*$/;
+function isNumericDottedVersion(name) {
+  return NUMERIC_DOTTED_VERSION_RE.test(name);
+}
+function compareVersions(a, b) {
+  if (!isNumericDottedVersion(a)) {
+    throw new Error(`compareVersions: "${a}" is not a valid plain dotted-numeric version`);
+  }
+  if (!isNumericDottedVersion(b)) {
+    throw new Error(`compareVersions: "${b}" is not a valid plain dotted-numeric version`);
+  }
+  const segmentsA = a.split(".").map(Number);
+  const segmentsB = b.split(".").map(Number);
+  const length = Math.max(segmentsA.length, segmentsB.length);
+  for (let i = 0; i < length; i += 1) {
+    const segmentA = segmentsA[i] ?? 0;
+    const segmentB = segmentsB[i] ?? 0;
+    if (segmentA !== segmentB) {
+      return segmentA - segmentB;
+    }
+  }
+  return 0;
+}
+var ClaudeVersionNotInstalledError = class extends CliError {
+  constructor(version, versionsDir, installed) {
+    super(
+      `Claude Code ${version} is pinned for this launch but is not installed under "${versionsDir}"` + (installed.length === 0 ? " (no versions are installed there)." : `. Installed: ${installed.join(", ")}.`) + " Install it, or change or remove the pin (--claude-version, AGENT_SHIM_CLAUDE_VERSION, or launch.claudeVersion)."
+    );
+    this.version = version;
+    this.versionsDir = versionsDir;
+    this.installed = installed;
+    this.name = "ClaudeVersionNotInstalledError";
+  }
+  version;
+  versionsDir;
+  installed;
+};
+function installedVersions(entries) {
+  return entries.filter((entry) => entry.isFile && entry.isExecutable && entry.sizeBytes > 0 && isNumericDottedVersion(entry.name)).map((entry) => entry.name).sort(compareVersions);
+}
+function pickHighestVersion(entries) {
+  const candidates = entries.filter(
+    (entry) => entry.isFile && entry.isExecutable && entry.sizeBytes > 0 && isNumericDottedVersion(entry.name)
+  );
+  if (candidates.length === 0) {
+    return void 0;
+  }
+  return candidates.reduce(
+    (highest, candidate) => compareVersions(candidate.name, highest.name) > 0 ? candidate : highest
+  ).name;
+}
+function discoverClaudeBinary(options) {
+  const versionsDir = options.versionsDir ?? defaultVersionsDir();
+  const entries = options.listVersionsDir(versionsDir);
+  const highestVersion = pickHighestVersion(entries);
+  if (options.version !== void 0) {
+    const installed = installedVersions(entries);
+    if (!installed.includes(options.version)) {
+      throw new ClaudeVersionNotInstalledError(options.version, versionsDir, installed);
+    }
+    return { path: import_node_path.default.join(versionsDir, options.version), source: "versions-dir", version: options.version };
+  }
+  if (highestVersion !== void 0) {
+    return {
+      path: import_node_path.default.join(versionsDir, highestVersion),
+      source: "versions-dir",
+      version: highestVersion
+    };
+  }
+  for (const dir of options.pathDirs) {
+    const found = options.findExecutableInDir(dir, "claude");
+    if (found !== void 0 && !options.isOwnBinary(found)) {
+      return { path: found, source: "path-fallback" };
+    }
+  }
+  throw new Error(
+    `Could not find a claude binary. Looked for genuinely-executable versioned binaries under "${versionsDir}" (missing, empty, or containing nothing executable) and for a "claude" executable on PATH (never this tool's own binary). Install Claude Code, or set the versions directory / PATH correctly, then try again.`
+  );
+}
+
+// src/config/schema.ts
 var CATEGORY_NAMES = ["secret", "runtime", "history", "knowledge", "settings"];
 var OVERRIDABLE_CATEGORIES = ["runtime", "history", "knowledge", "settings"];
 function isOverridableCategory(name) {
@@ -313,7 +418,9 @@ var LaunchSchema = import_zod.z.strictObject({
   remoteControl: import_zod.z.boolean().optional(),
   provider: import_zod.z.string().min(1).optional(),
   headroom: import_zod.z.boolean().optional(),
-  trackUsage: import_zod.z.boolean().optional()
+  trackUsage: import_zod.z.boolean().optional(),
+  /** The exact Claude Code version to run, as it is named in Claude Code's versions directory (`2.1.220`). A pin that is not installed fails the launch; it never falls back to the highest version. */
+  claudeVersion: import_zod.z.string().regex(NUMERIC_DOTTED_VERSION_RE, "must be an exact dotted-numeric Claude Code version such as 2.1.220").optional()
 });
 var CREDENTIAL_TARGETS = ["bearer", "apiKey", "oauthToken"];
 var PROVIDER_CREDENTIAL_TARGETS = ["bearer", "apiKey"];
@@ -332,7 +439,7 @@ var CommandSourceOptions = {
 var CredentialSourceSchema = import_zod.z.union([
   import_zod.z.strictObject({ env: import_zod.z.string().min(1) }),
   import_zod.z.strictObject({
-    file: import_zod.z.string().min(1).refine((filePath) => filePath.startsWith("~/") || import_node_path.default.isAbsolute(filePath), {
+    file: import_zod.z.string().min(1).refine((filePath) => filePath.startsWith("~/") || import_node_path2.default.isAbsolute(filePath), {
       message: "a credential file must be an absolute or ~-rooted path, since a launch can start in any directory"
     })
   }),
@@ -511,28 +618,11 @@ var SHIPPED_CATEGORY_DEFAULTS = Object.freeze({
 
 // src/config/store.ts
 var import_node_fs = __toESM(require("node:fs"), 1);
-var import_node_path2 = __toESM(require("node:path"), 1);
+var import_node_path3 = __toESM(require("node:path"), 1);
 var import_node_crypto = require("node:crypto");
 
 // src/config/load.ts
 var import_cosmiconfig = require("cosmiconfig");
-
-// src/cliError.ts
-var EXIT_FAILURE = 1;
-var EXIT_USAGE = 2;
-var CliError = class extends Error {
-  /** The process exit status this failure maps to. `EXIT_FAILURE` unless a subclass says otherwise. */
-  exitCode = EXIT_FAILURE;
-};
-var UsageError = class extends CliError {
-  exitCode = EXIT_USAGE;
-  constructor(message) {
-    super(message);
-    this.name = "UsageError";
-  }
-};
-
-// src/config/load.ts
 function createExplorer(moduleName = "agent-shim") {
   return (0, import_cosmiconfig.cosmiconfigSync)(moduleName, { searchPlaces: [] });
 }
@@ -653,9 +743,9 @@ function readJson(filePath, schema, storeFs = nodeStoreFs) {
   return result.data;
 }
 function writeTextAtomic(filePath, contents, storeFs = nodeStoreFs) {
-  const dir = import_node_path2.default.dirname(filePath);
+  const dir = import_node_path3.default.dirname(filePath);
   storeFs.mkdirSync(dir);
-  const tempPath = import_node_path2.default.join(dir, `.${import_node_path2.default.basename(filePath)}.${String(process.pid)}.${(0, import_node_crypto.randomUUID)()}.tmp`);
+  const tempPath = import_node_path3.default.join(dir, `.${import_node_path3.default.basename(filePath)}.${String(process.pid)}.${(0, import_node_crypto.randomUUID)()}.tmp`);
   storeFs.writeFileUtf8(tempPath, contents);
   try {
     storeFs.renameSync(tempPath, filePath);
@@ -679,9 +769,9 @@ function applyPatch(filePath, schema, patch, options = {}) {
   if (!result.success) {
     throw new ConfigValidationError(filePath, result.error.issues);
   }
-  const validated = result.data;
-  writeJsonAtomic(filePath, validated, storeFs);
-  return validated;
+  const validated2 = result.data;
+  writeJsonAtomic(filePath, validated2, storeFs);
+  return validated2;
 }
 
 // src/config/classify.ts
@@ -1104,6 +1194,9 @@ function flattenLayers(layers, options) {
       if (layer.launch.trackUsage !== void 0) {
         launch.trackUsage = layer.launch.trackUsage;
       }
+      if (layer.launch.claudeVersion !== void 0) {
+        launch.claudeVersion = layer.launch.claudeVersion;
+      }
     }
     if (layer.entries === void 0) {
       continue;
@@ -1341,7 +1434,7 @@ function dedupeDiagnostics(diagnostics) {
 }
 
 // src/resolve/plan.ts
-var import_node_path3 = __toESM(require("node:path"), 1);
+var import_node_path4 = __toESM(require("node:path"), 1);
 function parentOf(rel) {
   const index = rel.lastIndexOf("/");
   return index === -1 ? "" : rel.slice(0, index);
@@ -1391,7 +1484,7 @@ function planFarm(params) {
     }
     return value;
   };
-  const linkTarget = (rel) => import_node_path3.default.join(params.facts.claudeHome, rel);
+  const linkTarget = (rel) => import_node_path4.default.join(params.facts.claudeHome, rel);
   const visit = (rel) => {
     const fact = params.facts.entries.get(rel);
     const decision = params.decisions.get(rel);
@@ -1469,7 +1562,7 @@ function descendPolicy(rules) {
 }
 
 // src/resolve/walk.ts
-var import_node_path4 = __toESM(require("node:path"), 1);
+var import_node_path5 = __toESM(require("node:path"), 1);
 
 // src/resolve/extends.ts
 function lineariseProfile(rootName, load) {
@@ -1537,10 +1630,10 @@ function profileLayers(rootName, load, startId) {
 
 // src/resolve/walk.ts
 function walkDirectoryAncestors(cwd, options) {
-  const limit = import_node_path4.default.resolve(options.limit ?? options.home);
+  const limit = import_node_path5.default.resolve(options.limit ?? options.home);
   const isReadable = options.isReadable ?? (() => true);
   const collected = [];
-  let current = import_node_path4.default.resolve(cwd);
+  let current = import_node_path5.default.resolve(cwd);
   for (; ; ) {
     if (!isReadable(current)) {
       break;
@@ -1549,7 +1642,7 @@ function walkDirectoryAncestors(cwd, options) {
     if (current === limit) {
       break;
     }
-    const parent = import_node_path4.default.dirname(current);
+    const parent = import_node_path5.default.dirname(current);
     if (parent === current) {
       break;
     }
@@ -1673,7 +1766,7 @@ function resolveDecisions(input) {
 }
 
 // src/launcher/farm.ts
-var import_node_path6 = __toESM(require("node:path"), 1);
+var import_node_path7 = __toESM(require("node:path"), 1);
 var import_zod2 = require("zod");
 
 // src/resolve/reconcile.ts
@@ -1777,7 +1870,7 @@ var LEGACY_FARM_MANIFEST_FILENAME = ".claude-use-farm.json";
 
 // src/launcher/lock.ts
 var import_node_crypto2 = require("node:crypto");
-var import_node_path5 = __toESM(require("node:path"), 1);
+var import_node_path6 = __toESM(require("node:path"), 1);
 var DEFAULT_STALE_AFTER_MS = 12e4;
 var DEFAULT_RETRY_DELAY_MS = 50;
 var DEFAULT_MAX_ATTEMPTS = 200;
@@ -1796,7 +1889,7 @@ var IdentityLockBusyError = class extends CliError {
   holderPid;
 };
 function identityLockPath(dir, identity) {
-  return import_node_path5.default.join(dir, `.${identity}.lock`);
+  return import_node_path6.default.join(dir, `.${identity}.lock`);
 }
 function parseLockRecord(raw) {
   if (raw === void 0) {
@@ -1875,7 +1968,7 @@ var FarmManifestSchema = import_zod2.z.strictObject({
   links: import_zod2.z.array(import_zod2.z.strictObject({ rel: import_zod2.z.string(), target: import_zod2.z.string() }))
 });
 function readFarmManifest(fs12, farmRoot) {
-  const raw = fs12.readFileUtf8(import_node_path6.default.join(farmRoot, FARM_MANIFEST_FILENAME)) ?? fs12.readFileUtf8(import_node_path6.default.join(farmRoot, LEGACY_FARM_MANIFEST_FILENAME));
+  const raw = fs12.readFileUtf8(import_node_path7.default.join(farmRoot, FARM_MANIFEST_FILENAME)) ?? fs12.readFileUtf8(import_node_path7.default.join(farmRoot, LEGACY_FARM_MANIFEST_FILENAME));
   if (raw === void 0) {
     return void 0;
   }
@@ -1891,7 +1984,7 @@ function readFarmManifest(fs12, farmRoot) {
 function buildEntryFacts(params) {
   const entries = /* @__PURE__ */ new Map();
   const visit = (rel) => {
-    const absolute = import_node_path6.default.join(params.claudeHome, rel);
+    const absolute = import_node_path7.default.join(params.claudeHome, rel);
     const stat = params.fs.lstat(absolute);
     if (stat === void 0) {
       return void 0;
@@ -1934,7 +2027,7 @@ function buildEntryFacts(params) {
   };
 }
 function listSubtree(fs12, root, rel) {
-  const absolute = import_node_path6.default.join(root, rel);
+  const absolute = import_node_path7.default.join(root, rel);
   const stat = fs12.lstat(absolute);
   if (stat === void 0) {
     return [];
@@ -1964,7 +2057,7 @@ function reconciliationScope(fs12, farmRoot, manifest) {
   if (manifest !== void 0) {
     return topLevelScopeRoots(manifest.materialised);
   }
-  return [...fs12.readdir(farmRoot)].filter((name) => name !== FARM_MANIFEST_FILENAME && name !== LEGACY_FARM_MANIFEST_FILENAME && fs12.lstat(import_node_path6.default.join(farmRoot, name))?.kind === "dir").sort();
+  return [...fs12.readdir(farmRoot)].filter((name) => name !== FARM_MANIFEST_FILENAME && name !== LEGACY_FARM_MANIFEST_FILENAME && fs12.lstat(import_node_path7.default.join(farmRoot, name))?.kind === "dir").sort();
 }
 function collectFarmListing(fs12, farmRoot, scopeRoots) {
   return scopeRoots.flatMap((root) => listSubtree(fs12, farmRoot, root));
@@ -1972,7 +2065,7 @@ function collectFarmListing(fs12, farmRoot, scopeRoots) {
 function collectCanonicalCounterparts(fs12, claudeHome, farmListing) {
   const out = [];
   for (const entry of farmListing) {
-    const absolute = import_node_path6.default.join(claudeHome, entry.rel);
+    const absolute = import_node_path7.default.join(claudeHome, entry.rel);
     const stat = fs12.lstat(absolute);
     if (stat === void 0) {
       continue;
@@ -2002,21 +2095,21 @@ function carryOver(params) {
     if (accounted.has(name)) {
       continue;
     }
-    const stat = params.fs.lstat(import_node_path6.default.join(params.previousRoot, name));
+    const stat = params.fs.lstat(import_node_path7.default.join(params.previousRoot, name));
     if (stat === void 0 || stat.kind === "symlink") {
       continue;
     }
-    if (params.fs.lstat(import_node_path6.default.join(params.farmRoot, name)) !== void 0) {
+    if (params.fs.lstat(import_node_path7.default.join(params.farmRoot, name)) !== void 0) {
       const category = params.classification === void 0 ? void 0 : classifyEntries([name], params.classification).classification.get(name);
       if (category === "runtime") {
-        params.fs.removeRecursive(import_node_path6.default.join(params.previousRoot, name));
+        params.fs.removeRecursive(import_node_path7.default.join(params.previousRoot, name));
         autoResolved.push(name);
         continue;
       }
       collided.push(name);
       continue;
     }
-    params.fs.rename(import_node_path6.default.join(params.previousRoot, name), import_node_path6.default.join(params.farmRoot, name));
+    params.fs.rename(import_node_path7.default.join(params.previousRoot, name), import_node_path7.default.join(params.farmRoot, name));
     carried.push(name);
   }
   return { carried, autoResolved, collided };
@@ -2024,9 +2117,9 @@ function carryOver(params) {
 function buildScratchTree(params) {
   params.fs.mkdirp(params.scratchRoot);
   for (const entry of params.plan.entries) {
-    const absolute = import_node_path6.default.join(params.scratchRoot, entry.rel);
+    const absolute = import_node_path7.default.join(params.scratchRoot, entry.rel);
     if (entry.kind === "link") {
-      params.fs.mkdirp(import_node_path6.default.dirname(absolute));
+      params.fs.mkdirp(import_node_path7.default.dirname(absolute));
       params.fs.symlink(entry.target, absolute);
       continue;
     }
@@ -2035,14 +2128,14 @@ function buildScratchTree(params) {
     }
   }
   params.fs.writeFileUtf8(
-    import_node_path6.default.join(params.scratchRoot, FARM_MANIFEST_FILENAME),
+    import_node_path7.default.join(params.scratchRoot, FARM_MANIFEST_FILENAME),
     `${JSON.stringify(params.manifest, null, 2)}
 `
   );
 }
 function swapIn(params) {
   if (params.fs.lstat(params.farmRoot) === void 0) {
-    params.fs.mkdirp(import_node_path6.default.dirname(params.farmRoot));
+    params.fs.mkdirp(import_node_path7.default.dirname(params.farmRoot));
     params.fs.rename(params.scratchRoot, params.farmRoot);
     return { carried: [], autoResolved: [], collided: [] };
   }
@@ -2066,14 +2159,14 @@ function recoverInterruptedSwap(params) {
   const names = [...params.fs.readdir(params.identitiesDir)].sort();
   const removedScratch = [];
   for (const name of names.filter((candidate) => candidate.startsWith(scratchPrefix))) {
-    params.fs.removeRecursive(import_node_path6.default.join(params.identitiesDir, name));
+    params.fs.removeRecursive(import_node_path7.default.join(params.identitiesDir, name));
     removedScratch.push(name);
   }
   let previous = names.filter((candidate) => candidate.startsWith(previousPrefix));
   let restoredFrom;
   const first = previous[0];
   if (first !== void 0 && params.fs.lstat(params.farmRoot) === void 0) {
-    params.fs.rename(import_node_path6.default.join(params.identitiesDir, first), params.farmRoot);
+    params.fs.rename(import_node_path7.default.join(params.identitiesDir, first), params.farmRoot);
     restoredFrom = first;
     previous = previous.slice(1);
   }
@@ -2081,7 +2174,7 @@ function recoverInterruptedSwap(params) {
   const autoResolved = [];
   const retained = [];
   for (const name of previous) {
-    const previousRoot = import_node_path6.default.join(params.identitiesDir, name);
+    const previousRoot = import_node_path7.default.join(params.identitiesDir, name);
     const result = carryOver({
       fs: params.fs,
       previousRoot,
@@ -2106,7 +2199,7 @@ function recoverInterruptedSwap(params) {
   };
 }
 function recoverFarm(params) {
-  const farmRoot = import_node_path6.default.join(params.identitiesDir, params.identity);
+  const farmRoot = import_node_path7.default.join(params.identitiesDir, params.identity);
   const lock = acquireIdentityLock({
     identity: params.identity,
     dir: params.identitiesDir,
@@ -2165,16 +2258,16 @@ function executeReconciliation(params) {
       });
       continue;
     }
-    const from = import_node_path6.default.join(params.farmRoot, action.rel);
-    const canonical = import_node_path6.default.join(params.claudeHome, action.rel);
+    const from = import_node_path7.default.join(params.farmRoot, action.rel);
+    const canonical = import_node_path7.default.join(params.claudeHome, action.rel);
     if (action.kind === "adopt") {
-      params.fs.mkdirp(import_node_path6.default.dirname(canonical));
+      params.fs.mkdirp(import_node_path7.default.dirname(canonical));
       params.fs.copyRecursive(from, canonical);
       adopted.push(action.rel);
       continue;
     }
     const preserved = `${canonical}.farm-conflict-${String(params.nowMs)}`;
-    params.fs.mkdirp(import_node_path6.default.dirname(canonical));
+    params.fs.mkdirp(import_node_path7.default.dirname(canonical));
     params.fs.copyRecursive(from, preserved);
     conflicts.push(action.rel);
   }
@@ -2199,7 +2292,7 @@ function farmAlreadyMatches(existing, next) {
   return existing.identity === next.identity && existing.claudeHome === next.claudeHome && sameStrings(existing.materialised, next.materialised) && sameLinks(existing.links, next.links);
 }
 function resyncFarm(params) {
-  const farmRoot = import_node_path6.default.join(params.identitiesDir, params.identity);
+  const farmRoot = import_node_path7.default.join(params.identitiesDir, params.identity);
   const lock = acquireIdentityLock({
     identity: params.identity,
     dir: params.identitiesDir,
@@ -2279,8 +2372,8 @@ function resyncFarm(params) {
         diagnostics
       };
     }
-    const scratchRoot = import_node_path6.default.join(params.identitiesDir, `.${params.identity}.scratch.${params.uniqueSuffix}`);
-    const previousRoot = import_node_path6.default.join(params.identitiesDir, `.${params.identity}.previous.${params.uniqueSuffix}`);
+    const scratchRoot = import_node_path7.default.join(params.identitiesDir, `.${params.identity}.scratch.${params.uniqueSuffix}`);
+    const previousRoot = import_node_path7.default.join(params.identitiesDir, `.${params.identity}.previous.${params.uniqueSuffix}`);
     buildScratchTree({ fs: params.fs, scratchRoot, plan: resolved.farm, manifest });
     const swap = swapIn({ fs: params.fs, farmRoot, scratchRoot, previousRoot, classification: params.classification });
     if (swap.retainedPrevious !== void 0) {
@@ -2709,7 +2802,7 @@ function providerBaseUrl(port, provider) {
 }
 
 // src/frontdoor/state.ts
-var import_node_path7 = __toESM(require("node:path"), 1);
+var import_node_path8 = __toESM(require("node:path"), 1);
 var import_zod3 = require("zod");
 var FRONT_DOOR_PROTOCOL = 2;
 var FrontDoorSessionSchema = import_zod3.z.strictObject({ pid: import_zod3.z.number().int().positive(), startedAt: import_zod3.z.number(), token: import_zod3.z.string().min(1) });
@@ -2761,7 +2854,7 @@ function readFrontDoorState(fs12, stateFile) {
   }
 }
 function writeFrontDoorState(fs12, stateFile, state) {
-  fs12.mkdirp(import_node_path7.default.dirname(stateFile));
+  fs12.mkdirp(import_node_path8.default.dirname(stateFile));
   fs12.writeFilePrivate(stateFile, `${JSON.stringify(state, null, 2)}
 `);
 }
@@ -2771,7 +2864,7 @@ function frontDoorOrigin(state) {
 }
 function writeFrontDoorSession(fs12, sessionsDir, session) {
   fs12.mkdirPrivate(sessionsDir);
-  fs12.writeFilePrivate(import_node_path7.default.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
+  fs12.writeFilePrivate(import_node_path8.default.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
 `);
 }
 function listFrontDoorSessions(fs12, sessionsDir) {
@@ -2781,7 +2874,7 @@ function listFrontDoorSessions(fs12, sessionsDir) {
       continue;
     }
     try {
-      const parsed = FrontDoorSessionSchema.safeParse(JSON.parse(fs12.readFileUtf8(import_node_path7.default.join(sessionsDir, name)) ?? ""));
+      const parsed = FrontDoorSessionSchema.safeParse(JSON.parse(fs12.readFileUtf8(import_node_path8.default.join(sessionsDir, name)) ?? ""));
       if (parsed.success) {
         sessions.push({ pid: parsed.data.pid, startedAt: parsed.data.startedAt });
       }
@@ -2792,7 +2885,7 @@ function listFrontDoorSessions(fs12, sessionsDir) {
   return sessions.sort((a, b) => a.pid - b.pid);
 }
 function removeFrontDoorSession(fs12, sessionsDir, pid) {
-  fs12.removeRecursive(import_node_path7.default.join(sessionsDir, `${String(pid)}.json`));
+  fs12.removeRecursive(import_node_path8.default.join(sessionsDir, `${String(pid)}.json`));
 }
 function pruneDeadFrontDoorSessions(fs12, sessionsDir, isRunning) {
   const removed = [];
@@ -5198,7 +5291,7 @@ var import_node_crypto7 = require("node:crypto");
 
 // src/headroom/state.ts
 var import_node_crypto6 = require("node:crypto");
-var import_node_path8 = __toESM(require("node:path"), 1);
+var import_node_path9 = __toESM(require("node:path"), 1);
 var import_zod5 = require("zod");
 var HEADROOM_ANTHROPIC_UPSTREAM = "https://api.anthropic.com";
 var HEADROOM_STATE_SCHEMA_VERSION = 2;
@@ -5239,7 +5332,7 @@ function readHeadroomState(fs12, stateFile) {
   }
 }
 function writeHeadroomState(fs12, stateFile, state) {
-  fs12.mkdirp(import_node_path8.default.dirname(stateFile));
+  fs12.mkdirp(import_node_path9.default.dirname(stateFile));
   fs12.writeFilePrivate(stateFile, `${JSON.stringify(state, null, 2)}
 `);
 }
@@ -5267,7 +5360,7 @@ function readAllProviders(fs12, providersDir) {
       continue;
     }
     try {
-      const parsed = parseJson(fs12.readFileUtf8(import_node_path8.default.join(providersDir, name)), ProviderSchema);
+      const parsed = parseJson(fs12.readFileUtf8(import_node_path9.default.join(providersDir, name)), ProviderSchema);
       if (parsed !== void 0) {
         result.push({ name: name.slice(0, -".json".length), provider: parsed });
       }
@@ -5279,11 +5372,11 @@ function readAllProviders(fs12, providersDir) {
 }
 function writeSession(fs12, sessionsDir, session) {
   fs12.mkdirp(sessionsDir);
-  fs12.writeFileUtf8(import_node_path8.default.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
+  fs12.writeFileUtf8(import_node_path9.default.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
 `);
 }
 function removeSession(fs12, sessionsDir, pid) {
-  fs12.removeRecursive(import_node_path8.default.join(sessionsDir, `${String(pid)}.json`));
+  fs12.removeRecursive(import_node_path9.default.join(sessionsDir, `${String(pid)}.json`));
 }
 function listSessions(fs12, sessionsDir) {
   const sessions = [];
@@ -5292,7 +5385,7 @@ function listSessions(fs12, sessionsDir) {
       continue;
     }
     try {
-      const parsed = parseJson(fs12.readFileUtf8(import_node_path8.default.join(sessionsDir, name)), HeadroomSessionSchema);
+      const parsed = parseJson(fs12.readFileUtf8(import_node_path9.default.join(sessionsDir, name)), HeadroomSessionSchema);
       if (parsed !== void 0) {
         sessions.push(parsed);
       }
@@ -5397,10 +5490,10 @@ function ensureFrontDoor(params) {
 }
 
 // src/usage/read.ts
-var import_node_path10 = __toESM(require("node:path"), 1);
+var import_node_path11 = __toESM(require("node:path"), 1);
 
 // src/usage/account.ts
-var import_node_path9 = __toESM(require("node:path"), 1);
+var import_node_path10 = __toESM(require("node:path"), 1);
 
 // src/usage/schema.ts
 var import_zod6 = require("zod");
@@ -5566,7 +5659,7 @@ function isIdentityName(name) {
   return IdentitySchema.shape.name.safeParse(name).success;
 }
 function claudeJsonPath(identitiesDir, identity) {
-  return import_node_path9.default.join(identitiesDir, identity, CLAUDE_JSON);
+  return import_node_path10.default.join(identitiesDir, identity, CLAUDE_JSON);
 }
 function readAccountMetadata(fs12, identitiesDir, identity) {
   if (!isIdentityName(identity)) {
@@ -5625,7 +5718,7 @@ function readUsageLog(fs12, logDir, options = {}) {
     if (sinceMs !== void 0 && segment.endsAt <= sinceMs) {
       continue;
     }
-    const contents = fs12.readFileUtf8(import_node_path10.default.join(logDir, segment.name));
+    const contents = fs12.readFileUtf8(import_node_path11.default.join(logDir, segment.name));
     if (contents === void 0) {
       continue;
     }
@@ -5667,7 +5760,7 @@ function snapshotPath(snapshotsDir, identity) {
   if (!isIdentityName(identity)) {
     throw new Error(`"${identity}" is not a valid identity name.`);
   }
-  return import_node_path10.default.join(snapshotsDir, `${identity}.json`);
+  return import_node_path11.default.join(snapshotsDir, `${identity}.json`);
 }
 function readUsageSnapshot(fs12, snapshotsDir, identity) {
   const file = snapshotPath(snapshotsDir, identity);
@@ -6001,7 +6094,7 @@ function rankPool(input) {
 }
 
 // src/usage/poolPick.ts
-var import_node_path11 = __toESM(require("node:path"), 1);
+var import_node_path12 = __toESM(require("node:path"), 1);
 var import_zod9 = require("zod");
 
 // src/usage/store.ts
@@ -6068,13 +6161,13 @@ function recordStickyPick(fs12, picksFile, directory, identity, nowMs) {
   const current = readPicksFile(fs12, picksFile).file.picks;
   const kept = Object.entries(current).filter(([, entry]) => nowMs - Date.parse(entry.at) <= USAGE_RETENTION_MS);
   const next = { schemaVersion: SCHEMA_VERSION, picks: { ...Object.fromEntries(kept), [directory]: { identity, at: new Date(nowMs).toISOString() } } };
-  fs12.mkdirPrivate(import_node_path11.default.dirname(picksFile));
+  fs12.mkdirPrivate(import_node_path12.default.dirname(picksFile));
   fs12.writeFilePrivate(picksFile, `${JSON.stringify(next, null, 2)}
 `);
 }
 
 // src/launcher/identity.ts
-var import_node_path12 = __toESM(require("node:path"), 1);
+var import_node_path13 = __toESM(require("node:path"), 1);
 function poolNameOf(selector) {
   return selector.startsWith(POOL_SELECTOR_PREFIX) ? selector.slice(POOL_SELECTOR_PREFIX.length) : void 0;
 }
@@ -6123,7 +6216,7 @@ function decideConfigProfile(params) {
   return { source: "none" };
 }
 function loadIdentity(identitiesDir, name, fs12) {
-  return loadConfigFile(import_node_path12.default.join(identitiesDir, name, "identity.json"), IdentitySchema, fs12.readConfigFile);
+  return loadConfigFile(import_node_path13.default.join(identitiesDir, name, "identity.json"), IdentitySchema, fs12.readConfigFile);
 }
 
 // src/launcher/pool.ts
@@ -6338,7 +6431,7 @@ function hashSettings(settings) {
 }
 
 // src/headroom/socket.ts
-var import_node_path13 = __toESM(require("node:path"), 1);
+var import_node_path14 = __toESM(require("node:path"), 1);
 var GROUP_OR_OTHER_BITS = 63;
 var OCTAL_RADIX = 8;
 var MODE_DIGITS = 4;
@@ -6347,7 +6440,7 @@ var HEADROOM_SOCKET_NAME = /^(\d+)\.sock$/;
 var UNIX_SOCKET_PATH_MAX_BYTES = 103;
 var PLATFORMS_WITHOUT_UNIX_SOCKETS = ["win32"];
 function headroomSocketPath(paths, supervisorPid) {
-  return import_node_path13.default.join(paths.headroomSocketDir, `${String(supervisorPid)}${HEADROOM_SOCKET_SUFFIX}`);
+  return import_node_path14.default.join(paths.headroomSocketDir, `${String(supervisorPid)}${HEADROOM_SOCKET_SUFFIX}`);
 }
 function platformRefusal(platform) {
   return PLATFORMS_WITHOUT_UNIX_SOCKETS.includes(platform) ? `headroom routing needs a unix domain socket, which headroom cannot serve on ${platform}; agent-shim never falls back to a TCP port for this hop` : void 0;
@@ -6396,7 +6489,7 @@ function pruneStaleHeadroomSockets(fs12, paths, isRunning) {
     if (pid === void 0 || isRunning(Number.parseInt(pid, 10))) {
       continue;
     }
-    fs12.removeRecursive(import_node_path13.default.join(paths.headroomSocketDir, name));
+    fs12.removeRecursive(import_node_path14.default.join(paths.headroomSocketDir, name));
     removed.push(name);
   }
   return removed;
@@ -6450,7 +6543,7 @@ function versionSatisfies(version, source) {
   if (installed === void 0 || wanted === void 0) {
     return true;
   }
-  const cmp = compareVersions(installed, wanted);
+  const cmp = compareVersions2(installed, wanted);
   switch (specifier[0]) {
     case "==":
       return cmp === 0;
@@ -6465,7 +6558,7 @@ function versionSatisfies(version, source) {
     case "<":
       return cmp < 0;
     case "~=":
-      return compareVersions(installed.slice(0, Math.max(0, wanted.length - 1)), wanted.slice(0, Math.max(0, wanted.length - 1))) === 0 && cmp >= 0;
+      return compareVersions2(installed.slice(0, Math.max(0, wanted.length - 1)), wanted.slice(0, Math.max(0, wanted.length - 1))) === 0 && cmp >= 0;
     default:
       return true;
   }
@@ -6477,7 +6570,7 @@ function parseVersion(input) {
   }
   return match[0].split(".").map((part) => Number.parseInt(part, 10));
 }
-function compareVersions(a, b) {
+function compareVersions2(a, b) {
   for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
     const left = a[index] ?? 0;
     const right = b[index] ?? 0;
@@ -6719,15 +6812,15 @@ function evaluateAmbientCredentialGuard(params) {
 
 // src/paths.ts
 var import_node_fs2 = __toESM(require("node:fs"), 1);
-var import_node_os = __toESM(require("node:os"), 1);
-var import_node_path14 = __toESM(require("node:path"), 1);
-function resolveAgentShimHome(env = process.env, home = import_node_os.default.homedir(), isDirectory = isExistingDirectory) {
+var import_node_os2 = __toESM(require("node:os"), 1);
+var import_node_path15 = __toESM(require("node:path"), 1);
+function resolveAgentShimHome(env = process.env, home = import_node_os2.default.homedir(), isDirectory = isExistingDirectory) {
   const fromEnv = env.AGENT_SHIM_HOME;
   if (fromEnv !== void 0 && fromEnv !== "") {
     return fromEnv;
   }
-  const current = import_node_path14.default.join(home, HOME_DIRNAME);
-  const legacy = import_node_path14.default.join(home, LEGACY_HOME_DIRNAME);
+  const current = import_node_path15.default.join(home, HOME_DIRNAME);
+  const legacy = import_node_path15.default.join(home, LEGACY_HOME_DIRNAME);
   return !isDirectory(current) && isDirectory(legacy) ? legacy : current;
 }
 function isExistingDirectory(candidate) {
@@ -6738,40 +6831,40 @@ function resolveClaudeHome() {
   if (fromEnv !== void 0 && fromEnv !== "") {
     return fromEnv;
   }
-  return import_node_path14.default.join(import_node_os.default.homedir(), ".claude");
+  return import_node_path15.default.join(import_node_os2.default.homedir(), ".claude");
 }
 function buildLayoutPaths(root) {
   return {
     root,
-    identitiesDir: import_node_path14.default.join(root, "identities"),
-    configProfilesDir: import_node_path14.default.join(root, "config-profiles"),
-    providersDir: import_node_path14.default.join(root, "providers"),
-    directoryRulesFile: import_node_path14.default.join(root, "directory-rules.json"),
-    activeIdentityFile: import_node_path14.default.join(root, "active-identity"),
-    globalConfigFile: import_node_path14.default.join(root, "config.json"),
-    categoriesLocalFile: import_node_path14.default.join(root, "categories.local.json"),
-    claudeShimFile: import_node_path14.default.join(root, "claude-shim.json"),
-    headroomDir: import_node_path14.default.join(root, "headroom"),
-    headroomStateFile: import_node_path14.default.join(root, "headroom", `state.v${String(HEADROOM_STATE_SCHEMA_VERSION)}.json`),
-    headroomSocketDir: import_node_path14.default.join(root, "headroom", "run"),
-    headroomLockFile: import_node_path14.default.join(root, "headroom", "start.lock"),
-    headroomSessionsDir: import_node_path14.default.join(root, "headroom", "sessions"),
-    logsDir: import_node_path14.default.join(root, "logs"),
-    headroomLogPath: import_node_path14.default.join(root, "logs", "headroom.log"),
-    frontdoorDir: import_node_path14.default.join(root, "frontdoor"),
-    frontdoorCaDir: import_node_path14.default.join(root, "frontdoor", "ca"),
-    frontdoorCaCertFile: import_node_path14.default.join(root, "frontdoor", "ca", "ca.pem"),
-    frontdoorCaKeyFile: import_node_path14.default.join(root, "frontdoor", "ca", "ca.key"),
-    frontdoorCaBundlesDir: import_node_path14.default.join(root, "frontdoor", "ca", "bundles"),
-    frontdoorStateFile: import_node_path14.default.join(root, "frontdoor", "state.json"),
-    frontdoorLockFile: import_node_path14.default.join(root, "frontdoor", "start.lock"),
-    frontdoorControlTokenFile: import_node_path14.default.join(root, "frontdoor", "control-token"),
-    frontdoorSessionsDir: import_node_path14.default.join(root, "frontdoor", "sessions"),
-    frontdoorLogPath: import_node_path14.default.join(root, "logs", "frontdoor.log"),
-    usageDir: import_node_path14.default.join(root, "usage"),
-    usageLogDir: import_node_path14.default.join(root, "usage", "log"),
-    usageSnapshotsDir: import_node_path14.default.join(root, "usage", "snapshots"),
-    usagePicksFile: import_node_path14.default.join(root, "usage", "picks.json")
+    identitiesDir: import_node_path15.default.join(root, "identities"),
+    configProfilesDir: import_node_path15.default.join(root, "config-profiles"),
+    providersDir: import_node_path15.default.join(root, "providers"),
+    directoryRulesFile: import_node_path15.default.join(root, "directory-rules.json"),
+    activeIdentityFile: import_node_path15.default.join(root, "active-identity"),
+    globalConfigFile: import_node_path15.default.join(root, "config.json"),
+    categoriesLocalFile: import_node_path15.default.join(root, "categories.local.json"),
+    claudeShimFile: import_node_path15.default.join(root, "claude-shim.json"),
+    headroomDir: import_node_path15.default.join(root, "headroom"),
+    headroomStateFile: import_node_path15.default.join(root, "headroom", `state.v${String(HEADROOM_STATE_SCHEMA_VERSION)}.json`),
+    headroomSocketDir: import_node_path15.default.join(root, "headroom", "run"),
+    headroomLockFile: import_node_path15.default.join(root, "headroom", "start.lock"),
+    headroomSessionsDir: import_node_path15.default.join(root, "headroom", "sessions"),
+    logsDir: import_node_path15.default.join(root, "logs"),
+    headroomLogPath: import_node_path15.default.join(root, "logs", "headroom.log"),
+    frontdoorDir: import_node_path15.default.join(root, "frontdoor"),
+    frontdoorCaDir: import_node_path15.default.join(root, "frontdoor", "ca"),
+    frontdoorCaCertFile: import_node_path15.default.join(root, "frontdoor", "ca", "ca.pem"),
+    frontdoorCaKeyFile: import_node_path15.default.join(root, "frontdoor", "ca", "ca.key"),
+    frontdoorCaBundlesDir: import_node_path15.default.join(root, "frontdoor", "ca", "bundles"),
+    frontdoorStateFile: import_node_path15.default.join(root, "frontdoor", "state.json"),
+    frontdoorLockFile: import_node_path15.default.join(root, "frontdoor", "start.lock"),
+    frontdoorControlTokenFile: import_node_path15.default.join(root, "frontdoor", "control-token"),
+    frontdoorSessionsDir: import_node_path15.default.join(root, "frontdoor", "sessions"),
+    frontdoorLogPath: import_node_path15.default.join(root, "logs", "frontdoor.log"),
+    usageDir: import_node_path15.default.join(root, "usage"),
+    usageLogDir: import_node_path15.default.join(root, "usage", "log"),
+    usageSnapshotsDir: import_node_path15.default.join(root, "usage", "snapshots"),
+    usagePicksFile: import_node_path15.default.join(root, "usage", "picks.json")
   };
 }
 function resolveLayoutPaths() {
@@ -6780,11 +6873,11 @@ function resolveLayoutPaths() {
 
 // src/identityStore.ts
 var import_node_fs4 = __toESM(require("node:fs"), 1);
-var import_node_path16 = __toESM(require("node:path"), 1);
+var import_node_path17 = __toESM(require("node:path"), 1);
 
 // src/configProfilesStore.ts
 var import_node_fs3 = __toESM(require("node:fs"), 1);
-var import_node_path15 = __toESM(require("node:path"), 1);
+var import_node_path16 = __toESM(require("node:path"), 1);
 var ProfileNotFoundError = class extends CliError {
   constructor(profileName) {
     super(`No configuration profile named "${profileName}". Run \`agent-shim profile add ${profileName}\` first.`);
@@ -6810,7 +6903,7 @@ var InvalidCategoryNameError = class extends CliError {
   categoryName;
 };
 function profileJsonPath(paths, name) {
-  return import_node_path15.default.join(paths.configProfilesDir, `${name}.json`);
+  return import_node_path16.default.join(paths.configProfilesDir, `${name}.json`);
 }
 function profileExists(paths, name) {
   return import_node_fs3.default.existsSync(profileJsonPath(paths, name));
@@ -6998,7 +7091,7 @@ var InvalidIdentityNameError = class extends CliError {
   attemptedName;
 };
 function identityJsonPath(paths, name) {
-  return import_node_path16.default.join(paths.identitiesDir, name, "identity.json");
+  return import_node_path17.default.join(paths.identitiesDir, name, "identity.json");
 }
 function identityExists(paths, name) {
   return import_node_fs4.default.existsSync(identityJsonPath(paths, name));
@@ -7099,7 +7192,7 @@ function setIdentityCredential(paths, identityName, change) {
   });
 }
 function belongsToIdentity(entry, name) {
-  return entry === name || entry === import_node_path16.default.basename(identityLockPath("", name)) || entry.startsWith(`.${name}.scratch.`) || entry.startsWith(`.${name}.previous.`);
+  return entry === name || entry === import_node_path17.default.basename(identityLockPath("", name)) || entry.startsWith(`.${name}.scratch.`) || entry.startsWith(`.${name}.previous.`);
 }
 function removeIdentity(paths, name) {
   if (!identityExists(paths, name)) {
@@ -7107,7 +7200,7 @@ function removeIdentity(paths, name) {
   }
   for (const entry of import_node_fs4.default.readdirSync(paths.identitiesDir)) {
     if (belongsToIdentity(entry, name)) {
-      import_node_fs4.default.rmSync(import_node_path16.default.join(paths.identitiesDir, entry), { recursive: true, force: true });
+      import_node_fs4.default.rmSync(import_node_path17.default.join(paths.identitiesDir, entry), { recursive: true, force: true });
     }
   }
   if (readActiveIdentity(paths) === name) {
@@ -7117,7 +7210,7 @@ function removeIdentity(paths, name) {
 
 // src/providersStore.ts
 var import_node_fs5 = __toESM(require("node:fs"), 1);
-var import_node_path17 = __toESM(require("node:path"), 1);
+var import_node_path18 = __toESM(require("node:path"), 1);
 
 // src/credentialCache.ts
 var import_zod12 = require("zod");
@@ -7382,7 +7475,7 @@ var InvalidProviderNameError = class extends CliError {
 };
 var PROVIDER_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._@-]*$/;
 function providerJsonPath(paths, name) {
-  return import_node_path17.default.join(paths.providersDir, `${name}.json`);
+  return import_node_path18.default.join(paths.providersDir, `${name}.json`);
 }
 function providerExists(paths, name) {
   return import_node_fs5.default.existsSync(providerJsonPath(paths, name));
@@ -7458,7 +7551,7 @@ function readProvider(paths, name) {
   return parseProviderFile(filePath, raw);
 }
 function loadProvider(providersDir, name, port) {
-  const filePath = import_node_path17.default.join(providersDir, `${name}.json`);
+  const filePath = import_node_path18.default.join(providersDir, `${name}.json`);
   const raw = port.readConfigFile(filePath);
   return raw === void 0 ? void 0 : parseProviderFile(filePath, raw);
 }
@@ -7713,21 +7806,21 @@ function removeDirectoryRule(paths, rulePath) {
 var import_node_os4 = __toESM(require("node:os"), 1);
 
 // src/launcher/cascade.ts
-var import_node_path19 = __toESM(require("node:path"), 1);
+var import_node_path20 = __toESM(require("node:path"), 1);
 
 // src/pathNorm.ts
-var import_node_path18 = __toESM(require("node:path"), 1);
+var import_node_path19 = __toESM(require("node:path"), 1);
 function expandTilde(value, home) {
   if (value === "~") {
     return home;
   }
   if (value.startsWith("~/")) {
-    return import_node_path18.default.join(home, value.slice(2));
+    return import_node_path19.default.join(home, value.slice(2));
   }
   return value;
 }
 function normaliseRulePath(rulePath, home) {
-  return import_node_path18.default.resolve(expandTilde(rulePath, home));
+  return import_node_path19.default.resolve(expandTilde(rulePath, home));
 }
 
 // src/launcher/cascade.ts
@@ -7737,7 +7830,7 @@ function loadCascadeInput(params) {
   const globalConfig = loadConfigFile(params.paths.globalConfigFile, GlobalConfigSchema, params.read);
   const directoryRules = loadConfigFile(params.paths.directoryRulesFile, DirectoryRulesSchema, params.read);
   const loadProfile = (name) => {
-    const filepath = import_node_path19.default.join(params.paths.configProfilesDir, `${name}.json`);
+    const filepath = import_node_path20.default.join(params.paths.configProfilesDir, `${name}.json`);
     const loaded = loadConfigFile(filepath, ConfigProfileSchema, params.read);
     if (loaded === void 0) {
       return void 0;
@@ -7752,8 +7845,8 @@ function loadCascadeInput(params) {
   });
   const levels = [];
   for (const dir of dirs) {
-    const portable = loadConfigFile(import_node_path19.default.join(dir, PORTABLE_CONFIG_FILENAME), PortableConfigSchema, params.read) ?? loadConfigFile(import_node_path19.default.join(dir, LEGACY_PORTABLE_CONFIG_FILENAME), PortableConfigSchema, params.read);
-    const portableLocal = loadConfigFile(import_node_path19.default.join(dir, PORTABLE_LOCAL_CONFIG_FILENAME), PortableConfigSchema, params.read) ?? loadConfigFile(import_node_path19.default.join(dir, LEGACY_PORTABLE_LOCAL_CONFIG_FILENAME), PortableConfigSchema, params.read);
+    const portable = loadConfigFile(import_node_path20.default.join(dir, PORTABLE_CONFIG_FILENAME), PortableConfigSchema, params.read) ?? loadConfigFile(import_node_path20.default.join(dir, LEGACY_PORTABLE_CONFIG_FILENAME), PortableConfigSchema, params.read);
+    const portableLocal = loadConfigFile(import_node_path20.default.join(dir, PORTABLE_LOCAL_CONFIG_FILENAME), PortableConfigSchema, params.read) ?? loadConfigFile(import_node_path20.default.join(dir, LEGACY_PORTABLE_LOCAL_CONFIG_FILENAME), PortableConfigSchema, params.read);
     const rules = (directoryRules?.config.rules ?? []).map((rule, index) => ({ rule, index })).filter(({ rule }) => normaliseRulePath(rule.path, params.home) === dir).map(({ rule, index }) => {
       const entryOrder = directoryRules?.ruleEntryOrders[index];
       return {
@@ -7804,7 +7897,7 @@ function readDirectorySelections(loaded) {
 // src/realCredentialCache.ts
 var import_node_child_process = require("node:child_process");
 var import_node_fs6 = __toESM(require("node:fs"), 1);
-var import_node_path20 = __toESM(require("node:path"), 1);
+var import_node_path21 = __toESM(require("node:path"), 1);
 var KEYCHAIN_CACHE_SERVICE = "agent-shim-credential-cache";
 var CACHE_DIR_MODE = 448;
 var CACHE_FILE_MODE = 384;
@@ -7831,8 +7924,8 @@ function security(args, stdin) {
   return { status: result.status, stdout: result.stdout };
 }
 function createRealCredentialCache(root) {
-  const dir = import_node_path20.default.join(root, "credential-cache");
-  const filePath = (owner) => import_node_path20.default.join(dir, cacheFileNameFor(owner));
+  const dir = import_node_path21.default.join(root, "credential-cache");
+  const filePath = (owner) => import_node_path21.default.join(dir, cacheFileNameFor(owner));
   return {
     read(store, owner) {
       if (store === "file") {
@@ -7886,70 +7979,6 @@ var import_node_fs7 = __toESM(require("node:fs"), 1);
 var import_node_os3 = __toESM(require("node:os"), 1);
 var import_node_path22 = __toESM(require("node:path"), 1);
 var import_node_sea = require("node:sea");
-
-// src/versionDiscovery.ts
-var import_node_os2 = __toESM(require("node:os"), 1);
-var import_node_path21 = __toESM(require("node:path"), 1);
-function defaultVersionsDir() {
-  return import_node_path21.default.join(import_node_os2.default.homedir(), ".local", "share", "claude", "versions");
-}
-var NUMERIC_DOTTED_VERSION_RE = /^\d+(?:\.\d+)*$/;
-function isNumericDottedVersion(name) {
-  return NUMERIC_DOTTED_VERSION_RE.test(name);
-}
-function compareVersions2(a, b) {
-  if (!isNumericDottedVersion(a)) {
-    throw new Error(`compareVersions: "${a}" is not a valid plain dotted-numeric version`);
-  }
-  if (!isNumericDottedVersion(b)) {
-    throw new Error(`compareVersions: "${b}" is not a valid plain dotted-numeric version`);
-  }
-  const segmentsA = a.split(".").map(Number);
-  const segmentsB = b.split(".").map(Number);
-  const length = Math.max(segmentsA.length, segmentsB.length);
-  for (let i = 0; i < length; i += 1) {
-    const segmentA = segmentsA[i] ?? 0;
-    const segmentB = segmentsB[i] ?? 0;
-    if (segmentA !== segmentB) {
-      return segmentA - segmentB;
-    }
-  }
-  return 0;
-}
-function pickHighestVersion(entries) {
-  const candidates = entries.filter(
-    (entry) => entry.isFile && entry.isExecutable && entry.sizeBytes > 0 && isNumericDottedVersion(entry.name)
-  );
-  if (candidates.length === 0) {
-    return void 0;
-  }
-  return candidates.reduce(
-    (highest, candidate) => compareVersions2(candidate.name, highest.name) > 0 ? candidate : highest
-  ).name;
-}
-function discoverClaudeBinary(options) {
-  const versionsDir = options.versionsDir ?? defaultVersionsDir();
-  const entries = options.listVersionsDir(versionsDir);
-  const highestVersion = pickHighestVersion(entries);
-  if (highestVersion !== void 0) {
-    return {
-      path: import_node_path21.default.join(versionsDir, highestVersion),
-      source: "versions-dir",
-      version: highestVersion
-    };
-  }
-  for (const dir of options.pathDirs) {
-    const found = options.findExecutableInDir(dir, "claude");
-    if (found !== void 0 && !options.isOwnBinary(found)) {
-      return { path: found, source: "path-fallback" };
-    }
-  }
-  throw new Error(
-    `Could not find a claude binary. Looked for genuinely-executable versioned binaries under "${versionsDir}" (missing, empty, or containing nothing executable) and for a "claude" executable on PATH (never this tool's own binary). Install Claude Code, or set the versions directory / PATH correctly, then try again.`
-  );
-}
-
-// src/realPorts.ts
 function isEnoent3(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
@@ -8351,13 +8380,17 @@ function realContentSourcePath() {
   return resolveContentSourcePath({ isSea: (0, import_node_sea.isSea)(), execPath: process.execPath, argv1: process.argv[1] });
 }
 function realResolveClaudeBinary(isOwnBinary) {
-  return () => discoverClaudeBinary({
+  return (request4) => discoverClaudeBinary({
     listVersionsDir,
     pathDirs: (process.env.PATH ?? "").split(import_node_path22.default.delimiter).filter((dir) => dir !== ""),
     findExecutableInDir,
-    isOwnBinary
+    isOwnBinary,
+    ...request4?.version === void 0 ? {} : { version: request4.version }
   });
 }
+function realInstalledClaudeVersions() {
+  return installedVersions(listVersionsDir(defaultVersionsDir()));
+}
 
 // src/checkReport.ts
 var import_node_path23 = __toESM(require("node:path"), 1);
@@ -8399,6 +8432,34 @@ function parseEnvBool(variable, value) {
   return parsed;
 }
 
+// src/launcher/claudeVersion.ts
+var InvalidClaudeVersionError = class extends UsageError {
+  constructor(value, origin) {
+    super(`${origin} names Claude Code version "${value}", which is not an exact dotted-numeric version such as 2.1.220.`);
+    this.value = value;
+    this.origin = origin;
+    this.name = "InvalidClaudeVersionError";
+  }
+  value;
+  origin;
+};
+function validated(value, origin) {
+  if (!NUMERIC_DOTTED_VERSION_RE.test(value)) {
+    throw new InvalidClaudeVersionError(value, origin);
+  }
+  return value;
+}
+function resolveClaudeVersion(params) {
+  if (params.flag !== void 0) {
+    return { version: validated(params.flag, "--claude-version"), source: "flag" };
+  }
+  const fromEnv = params.env.AGENT_SHIM_CLAUDE_VERSION;
+  if (fromEnv !== void 0 && fromEnv !== "") {
+    return { version: validated(fromEnv, "AGENT_SHIM_CLAUDE_VERSION"), source: "environment" };
+  }
+  return params.cascade === void 0 ? void 0 : { version: params.cascade, source: "cascade" };
+}
+
 // src/checkReport.ts
 var HISTORY_PROJECTS_KEY_PREFIX = "history/projects/";
 function projectFragmentOf(rawKey) {
@@ -8549,6 +8610,19 @@ function buildCredentialReport(provider, identity, identityName, cacheEnv) {
     ...identityCached === void 0 ? {} : { identityCached }
   };
 }
+function buildClaudeVersionReport(params, cascadePin) {
+  const installed = params.installedClaudeVersions;
+  if (installed === void 0) {
+    return void 0;
+  }
+  const pin = resolveClaudeVersion({ env: params.env, ...cascadePin === void 0 ? {} : { cascade: cascadePin } });
+  const highestInstalled = installed.at(-1);
+  return {
+    ...pin === void 0 ? {} : { pinned: { ...pin, installed: installed.includes(pin.version) } },
+    ...highestInstalled === void 0 ? {} : { highestInstalled },
+    installed
+  };
+}
 function runCheck(params) {
   const facts = buildEntryFacts({
     fs: params.farmFs,
@@ -8573,6 +8647,7 @@ function runCheck(params) {
   const settingsShared = resolved.flattened.categories.get("settings") ?? SHIPPED_CATEGORY_DEFAULTS.settings;
   const settingsExposure = inspectSettingsExposure({ settingsShared, files: params.settingsFiles });
   const keychain = params.platform === "darwin" && params.run !== void 0 && params.farmRoot !== void 0 ? lookupKeychainService(params.run, params.farmRoot) : void 0;
+  const claudeVersion = buildClaudeVersionReport(params, resolved.flattened.launch.claudeVersion);
   return {
     ...params.identityName === void 0 ? {} : { identityName: params.identityName },
     identitySource: params.identitySource,
@@ -8585,7 +8660,8 @@ function runCheck(params) {
     ambientCredential,
     ...keychain === void 0 ? {} : { keychain },
     settingsExposure,
-    credential: buildCredentialReport(params.provider, params.identity, params.identityName, params.credentialCache)
+    credential: buildCredentialReport(params.provider, params.identity, params.identityName, params.credentialCache),
+    ...claudeVersion === void 0 ? {} : { claudeVersion }
   };
 }
 function formatCheckReport(report) {
@@ -8634,6 +8710,17 @@ function formatCheckReport(report) {
   if (credential.applies === "stored-login") {
     lines.push("  The identity's stored login (no credential block applies).");
   }
+  if (report.claudeVersion !== void 0) {
+    lines.push("", "Claude Code version:");
+    const { pinned, highestInstalled, installed } = report.claudeVersion;
+    if (pinned !== void 0) {
+      lines.push(
+        pinned.installed ? `  ${pinned.version}, pinned by the ${pinned.source} (installed)` : `  ${pinned.version}, pinned by the ${pinned.source}, but NOT installed; a launch here fails. Installed: ${installed.length === 0 ? "none" : installed.join(", ")}`
+      );
+    } else {
+      lines.push(highestInstalled === void 0 ? "  none installed in the versions directory (a launch falls back to a claude on PATH)" : `  ${highestInstalled} (the highest installed; nothing pins a version)`);
+    }
+  }
   lines.push("", "Ambient-credential exposure:");
   lines.push(
     report.ambientCredential.ok ? `  OK \u2014 none of ${AMBIENT_CREDENTIAL_VARS.join(", ")} is set to a non-empty value.` : report.ambientCredential.message.split("\n").map((line) => `  ${line}`).join("\n")
@@ -8672,11 +8759,12 @@ function checkReportToJson(report) {
     ambientCredential: report.ambientCredential.ok ? { ok: true } : { ok: false, variable: report.ambientCredential.variable, message: report.ambientCredential.message },
     ...report.keychain === void 0 ? {} : { keychain: report.keychain },
     settingsExposure: report.settingsExposure,
-    credential: report.credential
+    credential: report.credential,
+    ...report.claudeVersion === void 0 ? {} : { claudeVersion: report.claudeVersion }
   };
 }
 function checkReportHasWarnings(report) {
-  return report.resolved.diagnostics.some((diagnostic) => diagnostic.severity !== "info") || report.projectEncodingAmbiguities.length > 0 || !report.ambientCredential.ok || report.credential.provider?.problem !== void 0;
+  return report.resolved.diagnostics.some((diagnostic) => diagnostic.severity !== "info") || report.projectEncodingAmbiguities.length > 0 || !report.ambientCredential.ok || report.credential.provider?.problem !== void 0 || report.claudeVersion?.pinned?.installed === false;
 }
 function loadCheckProvider(paths, name) {
   let definition;
@@ -8762,6 +8850,7 @@ function collectCheckReport(params) {
     settingsFiles,
     run: realRunPort,
     credentialCache: realCredentialCacheEnv(paths),
+    installedClaudeVersions: realInstalledClaudeVersions(),
     ...farmRoot === void 0 ? {} : { farmRoot },
     platform: process.platform,
     ...provider === void 0 ? {} : { provider }
@@ -8913,13 +9002,13 @@ function pushProvider(push, entry, cacheEnv) {
     push("provider", "fail", new LegacyProviderFileError(entry.path, conversion).message, entry.name);
     return;
   }
-  const validated = ProviderSchema.safeParse(parsed);
-  if (!validated.success) {
-    push("provider", "fail", new ConfigValidationError(entry.path, validated.error.issues).message, entry.name);
+  const validated2 = ProviderSchema.safeParse(parsed);
+  if (!validated2.success) {
+    push("provider", "fail", new ConfigValidationError(entry.path, validated2.error.issues).message, entry.name);
     return;
   }
-  const cache = cacheClause(cacheEnv, `provider ${entry.name}`, validated.data.credential);
-  push("provider", cache.unreadable ? "fail" : "pass", `${entry.name} is valid (${describeProviderEndpoint(validated.data)}, credential ${describeCredential(validated.data.credential)})${cache.text}.`, entry.name);
+  const cache = cacheClause(cacheEnv, `provider ${entry.name}`, validated2.data.credential);
+  push("provider", cache.unreadable ? "fail" : "pass", `${entry.name} is valid (${describeProviderEndpoint(validated2.data)}, credential ${describeCredential(validated2.data.credential)})${cache.text}.`, entry.name);
 }
 function pushLegacyName(push, params) {
   const legacyVariables = Object.keys(params.env).filter((name) => name.startsWith(LEGACY_ENV_PREFIX) && params.env[name] !== void 0).sort();
@@ -8943,6 +9032,13 @@ function runDoctor(params) {
   const push = (section, severity, message, subject) => {
     findings.push({ section, severity, message, ...subject === void 0 ? {} : { subject } });
   };
+  const checkPin = (section, subject, where, version) => {
+    const installed = params.installedClaudeVersions;
+    if (version === void 0 || installed === void 0 || installed.includes(version)) {
+      return;
+    }
+    push(section, "warn", `${where} pins Claude Code ${version}, which is not installed (installed: ${installed.length === 0 ? "none" : installed.join(", ")}); a launch that resolves to it fails.`, subject);
+  };
   const ambient = detectAmbientCredential(params.env);
   if (ambient === void 0) {
     push("ambient-credential", "pass", "No ambient-credential environment variable is set.");
@@ -8975,12 +9071,13 @@ function runDoctor(params) {
   pushLegacyName(push, params);
   const profileSources = /* @__PURE__ */ new Map();
   for (const entry of params.configProfiles) {
-    const validated = validateJson(ConfigProfileSchema, entry);
-    if (!validated.ok) {
-      push("config-profile", "fail", validated.message, entry.name);
+    const validated2 = validateJson(ConfigProfileSchema, entry);
+    if (!validated2.ok) {
+      push("config-profile", "fail", validated2.message, entry.name);
       continue;
     }
-    profileSources.set(entry.name, { name: entry.name, profile: validated.data });
+    profileSources.set(entry.name, { name: entry.name, profile: validated2.data });
+    checkPin("config-profile", entry.name, `Configuration profile "${entry.name}"`, validated2.data.launch?.claudeVersion);
   }
   const loadProfile = (name) => profileSources.get(name);
   for (const name of profileSources.keys()) {
@@ -8996,13 +9093,13 @@ function runDoctor(params) {
   const validProfileNames = new Set(profileSources.keys());
   const validIdentityNames = /* @__PURE__ */ new Set();
   for (const entry of params.identities) {
-    const validated = validateJson(IdentitySchema, entry);
-    if (!validated.ok) {
-      push("identity", "fail", validated.message, entry.name);
+    const validated2 = validateJson(IdentitySchema, entry);
+    if (!validated2.ok) {
+      push("identity", "fail", validated2.message, entry.name);
       continue;
     }
     validIdentityNames.add(entry.name);
-    const defaultProfile = validated.data.defaultConfigProfile;
+    const defaultProfile = validated2.data.defaultConfigProfile;
     if (defaultProfile !== void 0 && !validProfileNames.has(defaultProfile)) {
       push(
         "identity",
@@ -9011,7 +9108,7 @@ function runDoctor(params) {
         entry.name
       );
     } else {
-      const credential = validated.data.credential;
+      const credential = validated2.data.credential;
       const cache = credential === void 0 ? { text: "", unreadable: false } : cacheClause(params.credentialCache, `identity ${entry.name}`, credential);
       push(
         "identity",
@@ -9049,12 +9146,12 @@ function runDoctor(params) {
   if (params.directoryRules.raw === void 0) {
     push("directory-rules", "pass", "No directory-rules.json configured.");
   } else {
-    const validated = validateJson(DirectoryRulesSchema, params.directoryRules);
-    if (!validated.ok) {
-      push("directory-rules", "fail", validated.message);
+    const validated2 = validateJson(DirectoryRulesSchema, params.directoryRules);
+    if (!validated2.ok) {
+      push("directory-rules", "fail", validated2.message);
     } else {
       push("directory-rules", "pass", `${params.directoryRules.path} is valid.`);
-      for (const rule of validated.data.rules) {
+      for (const rule of validated2.data.rules) {
         const badRefs = [];
         if (rule.identity !== void 0 && !selectionExists(rule.identity)) {
           badRefs.push(poolNameOf(rule.identity) === void 0 ? `identity "${rule.identity}"` : `pool "${poolNameOf(rule.identity) ?? ""}"`);
@@ -9062,6 +9159,7 @@ function runDoctor(params) {
         if (rule.configProfile !== void 0 && !validProfileNames.has(rule.configProfile)) {
           badRefs.push(`configuration profile "${rule.configProfile}"`);
         }
+        checkPin("directory-rules", rule.path, `Rule for "${rule.path}"`, rule.launch?.claudeVersion);
         if (badRefs.length > 0) {
           push("directory-rules", "fail", `Rule for "${rule.path}" names ${badRefs.join(" and ")}, which do not exist.`, rule.path);
         } else {
@@ -9073,11 +9171,11 @@ function runDoctor(params) {
   if (params.globalConfig.raw === void 0) {
     push("global-config", "pass", "No config.json configured.");
   } else {
-    const validated = validateJson(GlobalConfigSchema, params.globalConfig);
-    if (!validated.ok) {
-      push("global-config", "fail", validated.message);
+    const validated2 = validateJson(GlobalConfigSchema, params.globalConfig);
+    if (!validated2.ok) {
+      push("global-config", "fail", validated2.message);
     } else {
-      const defaultProfile = validated.data.defaultConfigProfile;
+      const defaultProfile = validated2.data.defaultConfigProfile;
       if (defaultProfile !== void 0 && !validProfileNames.has(defaultProfile)) {
         push(
           "global-config",
@@ -9086,27 +9184,28 @@ function runDoctor(params) {
         );
       } else {
         push("global-config", "pass", `${params.globalConfig.path} is valid.`);
+        checkPin("global-config", void 0, "config.json", validated2.data.launch?.claudeVersion);
       }
     }
   }
   if (params.categoriesLocal.raw === void 0) {
     push("categories-local", "pass", "No categories.local.json configured.");
   } else {
-    const validated = validateJson(CategoryClassificationOverlaySchema, params.categoriesLocal);
+    const validated2 = validateJson(CategoryClassificationOverlaySchema, params.categoriesLocal);
     push(
       "categories-local",
-      validated.ok ? "pass" : "fail",
-      validated.ok ? `${params.categoriesLocal.path} is valid.` : validated.message
+      validated2.ok ? "pass" : "fail",
+      validated2.ok ? `${params.categoriesLocal.path} is valid.` : validated2.message
     );
   }
   if (params.headroom.state.raw === void 0) {
     push("headroom", "pass", "No headroom daemon has ever run; nothing to check.");
   } else {
-    const validated = validateJson(HeadroomStateSchema, params.headroom.state);
-    if (!validated.ok) {
-      push("headroom", "fail", validated.message);
+    const validated2 = validateJson(HeadroomStateSchema, params.headroom.state);
+    if (!validated2.ok) {
+      push("headroom", "fail", validated2.message);
     } else {
-      const state = validated.data;
+      const state = validated2.data;
       const supervisorAlive = state.supervisorPid !== void 0 && params.headroom.isRunning(state.supervisorPid);
       const headroomAlive = state.headroomPid !== void 0 && params.headroom.isRunning(state.headroomPid);
       if (state.supervisorPid === void 0) {
@@ -9276,6 +9375,7 @@ function collectDoctorReport(params) {
   const report = runDoctor({
     env: params.env,
     credentialCache: realCredentialCacheEnv(paths),
+    installedClaudeVersions: realInstalledClaudeVersions(),
     identities,
     configProfiles,
     providers,
@@ -9325,7 +9425,7 @@ var ConflictingIdentityError = class extends UsageError {
   positional;
   flag;
 };
-var VALUED_FLAGS = ["--identity", "--config-profile", "--provider", "--category", "--share", "--hide"];
+var VALUED_FLAGS = ["--identity", "--config-profile", "--provider", "--claude-version", "--category", "--share", "--hide"];
 var BOOLEAN_FLAGS = [
   { flag: "--headroom", key: "headroom" },
   { flag: "--track-usage", key: "trackUsage" },
@@ -9371,6 +9471,7 @@ function parseLauncherArgv(argv) {
   let flagIdentity;
   let configProfile;
   let provider;
+  let claudeVersion;
   const booleans = {};
   const categoryFlags = [];
   const shareFlags = [];
@@ -9425,6 +9526,9 @@ function parseLauncherArgv(argv) {
       case "--provider":
         provider = value;
         break;
+      case "--claude-version":
+        claudeVersion = value;
+        break;
       case "--category":
         categoryFlags.push(value);
         break;
@@ -9446,6 +9550,7 @@ function parseLauncherArgv(argv) {
     ...identity === void 0 ? {} : { identity },
     ...configProfile === void 0 ? {} : { configProfile },
     ...provider === void 0 ? {} : { provider },
+    ...claudeVersion === void 0 ? {} : { claudeVersion },
     ...native ? { native: true } : {},
     ...booleans,
     categoryFlags,
@@ -9907,7 +10012,11 @@ function prepareLaunch(params) {
   } else if (params.farm !== void 0) {
     cascadeLaunch = flattenLayers(assembleCascade(params.farm.loadCascade(configProfileDecision.name, cliOverride)).layers, { home: params.farm.home }).launch;
   }
-  const discovered = params.resolveClaudeBinary();
+  const pinnedVersion = resolveClaudeVersion({ env, ...parsedArgv.claudeVersion === void 0 ? {} : { flag: parsedArgv.claudeVersion }, ...cascadeLaunch?.claudeVersion === void 0 ? {} : { cascade: cascadeLaunch.claudeVersion } });
+  const discovered = params.resolveClaudeBinary(pinnedVersion === void 0 ? void 0 : { version: pinnedVersion.version });
+  if (pinnedVersion !== void 0) {
+    log.info(`agent-shim: Claude Code ${pinnedVersion.version} (pinned by ${pinnedVersion.source})`);
+  }
   const resolvedFlags = resolveLaunchFlags({
     env,
     // A pool pick reads the usage the front door records, so a pool launch records its own unless something says otherwise.