agent-shim 8.9.0 → 8.10.0

package/dist/index.mjs

@@ -54,8 +54,113 @@ var categories_default_default = {
 };
 
 // src/config/schema.ts
-import path from "node:path";
+import path2 from "node:path";
 import { z } from "zod";
+
+// src/versionDiscovery.ts
+import os from "node:os";
+import path from "node:path";
+
+// 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 path.join(os.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: path.join(versionsDir, options.version), source: "versions-dir", version: options.version };
+  }
+  if (highestVersion !== void 0) {
+    return {
+      path: path.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) {
@@ -99,7 +204,9 @@ var LaunchSchema = z.strictObject({
   remoteControl: z.boolean().optional(),
   provider: z.string().min(1).optional(),
   headroom: z.boolean().optional(),
-  trackUsage: z.boolean().optional()
+  trackUsage: 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: 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"];
@@ -118,7 +225,7 @@ var CommandSourceOptions = {
 var CredentialSourceSchema = z.union([
   z.strictObject({ env: z.string().min(1) }),
   z.strictObject({
-    file: z.string().min(1).refine((filePath) => filePath.startsWith("~/") || path.isAbsolute(filePath), {
+    file: z.string().min(1).refine((filePath) => filePath.startsWith("~/") || path2.isAbsolute(filePath), {
       message: "a credential file must be an absolute or ~-rooted path, since a launch can start in any directory"
     })
   }),
@@ -297,28 +404,11 @@ var SHIPPED_CATEGORY_DEFAULTS = Object.freeze({
 
 // src/config/store.ts
 import fs from "node:fs";
-import path2 from "node:path";
+import path3 from "node:path";
 import { randomUUID } from "node:crypto";
 
 // src/config/load.ts
 import { cosmiconfigSync } from "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 cosmiconfigSync(moduleName, { searchPlaces: [] });
 }
@@ -439,9 +529,9 @@ function readJson(filePath, schema, storeFs = nodeStoreFs) {
   return result.data;
 }
 function writeTextAtomic(filePath, contents, storeFs = nodeStoreFs) {
-  const dir = path2.dirname(filePath);
+  const dir = path3.dirname(filePath);
   storeFs.mkdirSync(dir);
-  const tempPath = path2.join(dir, `.${path2.basename(filePath)}.${String(process.pid)}.${randomUUID()}.tmp`);
+  const tempPath = path3.join(dir, `.${path3.basename(filePath)}.${String(process.pid)}.${randomUUID()}.tmp`);
   storeFs.writeFileUtf8(tempPath, contents);
   try {
     storeFs.renameSync(tempPath, filePath);
@@ -465,9 +555,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
@@ -890,6 +980,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;
@@ -1127,7 +1220,7 @@ function dedupeDiagnostics(diagnostics) {
 }
 
 // src/resolve/plan.ts
-import path3 from "node:path";
+import path4 from "node:path";
 function parentOf(rel) {
   const index = rel.lastIndexOf("/");
   return index === -1 ? "" : rel.slice(0, index);
@@ -1177,7 +1270,7 @@ function planFarm(params) {
     }
     return value;
   };
-  const linkTarget = (rel) => path3.join(params.facts.claudeHome, rel);
+  const linkTarget = (rel) => path4.join(params.facts.claudeHome, rel);
   const visit = (rel) => {
     const fact = params.facts.entries.get(rel);
     const decision = params.decisions.get(rel);
@@ -1255,7 +1348,7 @@ function descendPolicy(rules) {
 }
 
 // src/resolve/walk.ts
-import path4 from "node:path";
+import path5 from "node:path";
 
 // src/resolve/extends.ts
 function lineariseProfile(rootName, load) {
@@ -1323,10 +1416,10 @@ function profileLayers(rootName, load, startId) {
 
 // src/resolve/walk.ts
 function walkDirectoryAncestors(cwd, options) {
-  const limit = path4.resolve(options.limit ?? options.home);
+  const limit = path5.resolve(options.limit ?? options.home);
   const isReadable = options.isReadable ?? (() => true);
   const collected = [];
-  let current = path4.resolve(cwd);
+  let current = path5.resolve(cwd);
   for (; ; ) {
     if (!isReadable(current)) {
       break;
@@ -1335,7 +1428,7 @@ function walkDirectoryAncestors(cwd, options) {
     if (current === limit) {
       break;
     }
-    const parent = path4.dirname(current);
+    const parent = path5.dirname(current);
     if (parent === current) {
       break;
     }
@@ -1459,7 +1552,7 @@ function resolveDecisions(input) {
 }
 
 // src/launcher/farm.ts
-import path6 from "node:path";
+import path7 from "node:path";
 import { z as z2 } from "zod";
 
 // src/resolve/reconcile.ts
@@ -1563,7 +1656,7 @@ var LEGACY_FARM_MANIFEST_FILENAME = ".claude-use-farm.json";
 
 // src/launcher/lock.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
-import path5 from "node:path";
+import path6 from "node:path";
 var DEFAULT_STALE_AFTER_MS = 12e4;
 var DEFAULT_RETRY_DELAY_MS = 50;
 var DEFAULT_MAX_ATTEMPTS = 200;
@@ -1582,7 +1675,7 @@ var IdentityLockBusyError = class extends CliError {
   holderPid;
 };
 function identityLockPath(dir, identity) {
-  return path5.join(dir, `.${identity}.lock`);
+  return path6.join(dir, `.${identity}.lock`);
 }
 function parseLockRecord(raw) {
   if (raw === void 0) {
@@ -1661,7 +1754,7 @@ var FarmManifestSchema = z2.strictObject({
   links: z2.array(z2.strictObject({ rel: z2.string(), target: z2.string() }))
 });
 function readFarmManifest(fs12, farmRoot) {
-  const raw = fs12.readFileUtf8(path6.join(farmRoot, FARM_MANIFEST_FILENAME)) ?? fs12.readFileUtf8(path6.join(farmRoot, LEGACY_FARM_MANIFEST_FILENAME));
+  const raw = fs12.readFileUtf8(path7.join(farmRoot, FARM_MANIFEST_FILENAME)) ?? fs12.readFileUtf8(path7.join(farmRoot, LEGACY_FARM_MANIFEST_FILENAME));
   if (raw === void 0) {
     return void 0;
   }
@@ -1677,7 +1770,7 @@ function readFarmManifest(fs12, farmRoot) {
 function buildEntryFacts(params) {
   const entries = /* @__PURE__ */ new Map();
   const visit = (rel) => {
-    const absolute = path6.join(params.claudeHome, rel);
+    const absolute = path7.join(params.claudeHome, rel);
     const stat = params.fs.lstat(absolute);
     if (stat === void 0) {
       return void 0;
@@ -1720,7 +1813,7 @@ function buildEntryFacts(params) {
   };
 }
 function listSubtree(fs12, root, rel) {
-  const absolute = path6.join(root, rel);
+  const absolute = path7.join(root, rel);
   const stat = fs12.lstat(absolute);
   if (stat === void 0) {
     return [];
@@ -1750,7 +1843,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(path6.join(farmRoot, name))?.kind === "dir").sort();
+  return [...fs12.readdir(farmRoot)].filter((name) => name !== FARM_MANIFEST_FILENAME && name !== LEGACY_FARM_MANIFEST_FILENAME && fs12.lstat(path7.join(farmRoot, name))?.kind === "dir").sort();
 }
 function collectFarmListing(fs12, farmRoot, scopeRoots) {
   return scopeRoots.flatMap((root) => listSubtree(fs12, farmRoot, root));
@@ -1758,7 +1851,7 @@ function collectFarmListing(fs12, farmRoot, scopeRoots) {
 function collectCanonicalCounterparts(fs12, claudeHome, farmListing) {
   const out = [];
   for (const entry of farmListing) {
-    const absolute = path6.join(claudeHome, entry.rel);
+    const absolute = path7.join(claudeHome, entry.rel);
     const stat = fs12.lstat(absolute);
     if (stat === void 0) {
       continue;
@@ -1788,21 +1881,21 @@ function carryOver(params) {
     if (accounted.has(name)) {
       continue;
     }
-    const stat = params.fs.lstat(path6.join(params.previousRoot, name));
+    const stat = params.fs.lstat(path7.join(params.previousRoot, name));
     if (stat === void 0 || stat.kind === "symlink") {
       continue;
     }
-    if (params.fs.lstat(path6.join(params.farmRoot, name)) !== void 0) {
+    if (params.fs.lstat(path7.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(path6.join(params.previousRoot, name));
+        params.fs.removeRecursive(path7.join(params.previousRoot, name));
         autoResolved.push(name);
         continue;
       }
       collided.push(name);
       continue;
     }
-    params.fs.rename(path6.join(params.previousRoot, name), path6.join(params.farmRoot, name));
+    params.fs.rename(path7.join(params.previousRoot, name), path7.join(params.farmRoot, name));
     carried.push(name);
   }
   return { carried, autoResolved, collided };
@@ -1810,9 +1903,9 @@ function carryOver(params) {
 function buildScratchTree(params) {
   params.fs.mkdirp(params.scratchRoot);
   for (const entry of params.plan.entries) {
-    const absolute = path6.join(params.scratchRoot, entry.rel);
+    const absolute = path7.join(params.scratchRoot, entry.rel);
     if (entry.kind === "link") {
-      params.fs.mkdirp(path6.dirname(absolute));
+      params.fs.mkdirp(path7.dirname(absolute));
       params.fs.symlink(entry.target, absolute);
       continue;
     }
@@ -1821,14 +1914,14 @@ function buildScratchTree(params) {
     }
   }
   params.fs.writeFileUtf8(
-    path6.join(params.scratchRoot, FARM_MANIFEST_FILENAME),
+    path7.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(path6.dirname(params.farmRoot));
+    params.fs.mkdirp(path7.dirname(params.farmRoot));
     params.fs.rename(params.scratchRoot, params.farmRoot);
     return { carried: [], autoResolved: [], collided: [] };
   }
@@ -1852,14 +1945,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(path6.join(params.identitiesDir, name));
+    params.fs.removeRecursive(path7.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(path6.join(params.identitiesDir, first), params.farmRoot);
+    params.fs.rename(path7.join(params.identitiesDir, first), params.farmRoot);
     restoredFrom = first;
     previous = previous.slice(1);
   }
@@ -1867,7 +1960,7 @@ function recoverInterruptedSwap(params) {
   const autoResolved = [];
   const retained = [];
   for (const name of previous) {
-    const previousRoot = path6.join(params.identitiesDir, name);
+    const previousRoot = path7.join(params.identitiesDir, name);
     const result = carryOver({
       fs: params.fs,
       previousRoot,
@@ -1892,7 +1985,7 @@ function recoverInterruptedSwap(params) {
   };
 }
 function recoverFarm(params) {
-  const farmRoot = path6.join(params.identitiesDir, params.identity);
+  const farmRoot = path7.join(params.identitiesDir, params.identity);
   const lock = acquireIdentityLock({
     identity: params.identity,
     dir: params.identitiesDir,
@@ -1951,16 +2044,16 @@ function executeReconciliation(params) {
       });
       continue;
     }
-    const from = path6.join(params.farmRoot, action.rel);
-    const canonical = path6.join(params.claudeHome, action.rel);
+    const from = path7.join(params.farmRoot, action.rel);
+    const canonical = path7.join(params.claudeHome, action.rel);
     if (action.kind === "adopt") {
-      params.fs.mkdirp(path6.dirname(canonical));
+      params.fs.mkdirp(path7.dirname(canonical));
       params.fs.copyRecursive(from, canonical);
       adopted.push(action.rel);
       continue;
     }
     const preserved = `${canonical}.farm-conflict-${String(params.nowMs)}`;
-    params.fs.mkdirp(path6.dirname(canonical));
+    params.fs.mkdirp(path7.dirname(canonical));
     params.fs.copyRecursive(from, preserved);
     conflicts.push(action.rel);
   }
@@ -1985,7 +2078,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 = path6.join(params.identitiesDir, params.identity);
+  const farmRoot = path7.join(params.identitiesDir, params.identity);
   const lock = acquireIdentityLock({
     identity: params.identity,
     dir: params.identitiesDir,
@@ -2065,8 +2158,8 @@ function resyncFarm(params) {
         diagnostics
       };
     }
-    const scratchRoot = path6.join(params.identitiesDir, `.${params.identity}.scratch.${params.uniqueSuffix}`);
-    const previousRoot = path6.join(params.identitiesDir, `.${params.identity}.previous.${params.uniqueSuffix}`);
+    const scratchRoot = path7.join(params.identitiesDir, `.${params.identity}.scratch.${params.uniqueSuffix}`);
+    const previousRoot = path7.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) {
@@ -2495,7 +2588,7 @@ function providerBaseUrl(port, provider) {
 }
 
 // src/frontdoor/state.ts
-import path7 from "node:path";
+import path8 from "node:path";
 import { z as z3 } from "zod";
 var FRONT_DOOR_PROTOCOL = 2;
 var FrontDoorSessionSchema = z3.strictObject({ pid: z3.number().int().positive(), startedAt: z3.number(), token: z3.string().min(1) });
@@ -2547,7 +2640,7 @@ function readFrontDoorState(fs12, stateFile) {
   }
 }
 function writeFrontDoorState(fs12, stateFile, state) {
-  fs12.mkdirp(path7.dirname(stateFile));
+  fs12.mkdirp(path8.dirname(stateFile));
   fs12.writeFilePrivate(stateFile, `${JSON.stringify(state, null, 2)}
 `);
 }
@@ -2557,7 +2650,7 @@ function frontDoorOrigin(state) {
 }
 function writeFrontDoorSession(fs12, sessionsDir, session) {
   fs12.mkdirPrivate(sessionsDir);
-  fs12.writeFilePrivate(path7.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
+  fs12.writeFilePrivate(path8.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
 `);
 }
 function listFrontDoorSessions(fs12, sessionsDir) {
@@ -2567,7 +2660,7 @@ function listFrontDoorSessions(fs12, sessionsDir) {
       continue;
     }
     try {
-      const parsed = FrontDoorSessionSchema.safeParse(JSON.parse(fs12.readFileUtf8(path7.join(sessionsDir, name)) ?? ""));
+      const parsed = FrontDoorSessionSchema.safeParse(JSON.parse(fs12.readFileUtf8(path8.join(sessionsDir, name)) ?? ""));
       if (parsed.success) {
         sessions.push({ pid: parsed.data.pid, startedAt: parsed.data.startedAt });
       }
@@ -2578,7 +2671,7 @@ function listFrontDoorSessions(fs12, sessionsDir) {
   return sessions.sort((a, b) => a.pid - b.pid);
 }
 function removeFrontDoorSession(fs12, sessionsDir, pid) {
-  fs12.removeRecursive(path7.join(sessionsDir, `${String(pid)}.json`));
+  fs12.removeRecursive(path8.join(sessionsDir, `${String(pid)}.json`));
 }
 function pruneDeadFrontDoorSessions(fs12, sessionsDir, isRunning) {
   const removed = [];
@@ -4526,7 +4619,7 @@ function realConnectEffects() {
 // src/frontdoor/rcApi.ts
 import { createORPCClient, ORPCError } from "@orpc/client";
 import { RPCLink } from "@orpc/client/fetch";
-import { eventIterator, os, withEventMeta } from "@orpc/server";
+import { eventIterator, os as os2, withEventMeta } from "@orpc/server";
 import { BodyLimitPlugin, RPCHandler } from "@orpc/server/node";
 import { Agent as Agent3, fetch as undiciFetch } from "undici";
 
@@ -4613,7 +4706,7 @@ var RcAnswerOutputSchema = z4.strictObject({
 var RC_ORPC_PATH_PREFIX = "/__agent-shim/orpc";
 var RC_SUBSCRIBER_BUFFER_EVENTS = 100;
 function createRcApiRouter(deps) {
-  const authed = os.$context().use(({ context, next }) => {
+  const authed = os2.$context().use(({ context, next }) => {
     const presented = context.headers.authorization;
     const bearerPrefix = "bearer ".length;
     const token = typeof presented === "string" && presented.slice(0, bearerPrefix).toLowerCase() === "bearer " ? presented.slice(bearerPrefix) : void 0;
@@ -4984,7 +5077,7 @@ import { randomUUID as randomUUID3 } from "node:crypto";
 
 // src/headroom/state.ts
 import { createHash as createHash3 } from "node:crypto";
-import path8 from "node:path";
+import path9 from "node:path";
 import { z as z5 } from "zod";
 var HEADROOM_ANTHROPIC_UPSTREAM = "https://api.anthropic.com";
 var HEADROOM_STATE_SCHEMA_VERSION = 2;
@@ -5025,7 +5118,7 @@ function readHeadroomState(fs12, stateFile) {
   }
 }
 function writeHeadroomState(fs12, stateFile, state) {
-  fs12.mkdirp(path8.dirname(stateFile));
+  fs12.mkdirp(path9.dirname(stateFile));
   fs12.writeFilePrivate(stateFile, `${JSON.stringify(state, null, 2)}
 `);
 }
@@ -5053,7 +5146,7 @@ function readAllProviders(fs12, providersDir) {
       continue;
     }
     try {
-      const parsed = parseJson(fs12.readFileUtf8(path8.join(providersDir, name)), ProviderSchema);
+      const parsed = parseJson(fs12.readFileUtf8(path9.join(providersDir, name)), ProviderSchema);
       if (parsed !== void 0) {
         result.push({ name: name.slice(0, -".json".length), provider: parsed });
       }
@@ -5065,11 +5158,11 @@ function readAllProviders(fs12, providersDir) {
 }
 function writeSession(fs12, sessionsDir, session) {
   fs12.mkdirp(sessionsDir);
-  fs12.writeFileUtf8(path8.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
+  fs12.writeFileUtf8(path9.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
 `);
 }
 function removeSession(fs12, sessionsDir, pid) {
-  fs12.removeRecursive(path8.join(sessionsDir, `${String(pid)}.json`));
+  fs12.removeRecursive(path9.join(sessionsDir, `${String(pid)}.json`));
 }
 function listSessions(fs12, sessionsDir) {
   const sessions = [];
@@ -5078,7 +5171,7 @@ function listSessions(fs12, sessionsDir) {
       continue;
     }
     try {
-      const parsed = parseJson(fs12.readFileUtf8(path8.join(sessionsDir, name)), HeadroomSessionSchema);
+      const parsed = parseJson(fs12.readFileUtf8(path9.join(sessionsDir, name)), HeadroomSessionSchema);
       if (parsed !== void 0) {
         sessions.push(parsed);
       }
@@ -5183,10 +5276,10 @@ function ensureFrontDoor(params) {
 }
 
 // src/usage/read.ts
-import path10 from "node:path";
+import path11 from "node:path";
 
 // src/usage/account.ts
-import path9 from "node:path";
+import path10 from "node:path";
 
 // src/usage/schema.ts
 import { z as z6 } from "zod";
@@ -5352,7 +5445,7 @@ function isIdentityName(name) {
   return IdentitySchema.shape.name.safeParse(name).success;
 }
 function claudeJsonPath(identitiesDir, identity) {
-  return path9.join(identitiesDir, identity, CLAUDE_JSON);
+  return path10.join(identitiesDir, identity, CLAUDE_JSON);
 }
 function readAccountMetadata(fs12, identitiesDir, identity) {
   if (!isIdentityName(identity)) {
@@ -5411,7 +5504,7 @@ function readUsageLog(fs12, logDir, options = {}) {
     if (sinceMs !== void 0 && segment.endsAt <= sinceMs) {
       continue;
     }
-    const contents = fs12.readFileUtf8(path10.join(logDir, segment.name));
+    const contents = fs12.readFileUtf8(path11.join(logDir, segment.name));
     if (contents === void 0) {
       continue;
     }
@@ -5453,7 +5546,7 @@ function snapshotPath(snapshotsDir, identity) {
   if (!isIdentityName(identity)) {
     throw new Error(`"${identity}" is not a valid identity name.`);
   }
-  return path10.join(snapshotsDir, `${identity}.json`);
+  return path11.join(snapshotsDir, `${identity}.json`);
 }
 function readUsageSnapshot(fs12, snapshotsDir, identity) {
   const file = snapshotPath(snapshotsDir, identity);
@@ -5787,7 +5880,7 @@ function rankPool(input) {
 }
 
 // src/usage/poolPick.ts
-import path11 from "node:path";
+import path12 from "node:path";
 import { z as z9 } from "zod";
 
 // src/usage/store.ts
@@ -5854,13 +5947,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(path11.dirname(picksFile));
+  fs12.mkdirPrivate(path12.dirname(picksFile));
   fs12.writeFilePrivate(picksFile, `${JSON.stringify(next, null, 2)}
 `);
 }
 
 // src/launcher/identity.ts
-import path12 from "node:path";
+import path13 from "node:path";
 function poolNameOf(selector) {
   return selector.startsWith(POOL_SELECTOR_PREFIX) ? selector.slice(POOL_SELECTOR_PREFIX.length) : void 0;
 }
@@ -5909,7 +6002,7 @@ function decideConfigProfile(params) {
   return { source: "none" };
 }
 function loadIdentity(identitiesDir, name, fs12) {
-  return loadConfigFile(path12.join(identitiesDir, name, "identity.json"), IdentitySchema, fs12.readConfigFile);
+  return loadConfigFile(path13.join(identitiesDir, name, "identity.json"), IdentitySchema, fs12.readConfigFile);
 }
 
 // src/launcher/pool.ts
@@ -6124,7 +6217,7 @@ function hashSettings(settings) {
 }
 
 // src/headroom/socket.ts
-import path13 from "node:path";
+import path14 from "node:path";
 var GROUP_OR_OTHER_BITS = 63;
 var OCTAL_RADIX = 8;
 var MODE_DIGITS = 4;
@@ -6133,7 +6226,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 path13.join(paths.headroomSocketDir, `${String(supervisorPid)}${HEADROOM_SOCKET_SUFFIX}`);
+  return path14.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;
@@ -6182,7 +6275,7 @@ function pruneStaleHeadroomSockets(fs12, paths, isRunning) {
     if (pid === void 0 || isRunning(Number.parseInt(pid, 10))) {
       continue;
     }
-    fs12.removeRecursive(path13.join(paths.headroomSocketDir, name));
+    fs12.removeRecursive(path14.join(paths.headroomSocketDir, name));
     removed.push(name);
   }
   return removed;
@@ -6236,7 +6329,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;
@@ -6251,7 +6344,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;
   }
@@ -6263,7 +6356,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;
@@ -6505,15 +6598,15 @@ function evaluateAmbientCredentialGuard(params) {
 
 // src/paths.ts
 import fs3 from "node:fs";
-import os2 from "node:os";
-import path14 from "node:path";
-function resolveAgentShimHome(env = process.env, home = os2.homedir(), isDirectory = isExistingDirectory) {
+import os3 from "node:os";
+import path15 from "node:path";
+function resolveAgentShimHome(env = process.env, home = os3.homedir(), isDirectory = isExistingDirectory) {
   const fromEnv = env.AGENT_SHIM_HOME;
   if (fromEnv !== void 0 && fromEnv !== "") {
     return fromEnv;
   }
-  const current = path14.join(home, HOME_DIRNAME);
-  const legacy = path14.join(home, LEGACY_HOME_DIRNAME);
+  const current = path15.join(home, HOME_DIRNAME);
+  const legacy = path15.join(home, LEGACY_HOME_DIRNAME);
   return !isDirectory(current) && isDirectory(legacy) ? legacy : current;
 }
 function isExistingDirectory(candidate) {
@@ -6524,40 +6617,40 @@ function resolveClaudeHome() {
   if (fromEnv !== void 0 && fromEnv !== "") {
     return fromEnv;
   }
-  return path14.join(os2.homedir(), ".claude");
+  return path15.join(os3.homedir(), ".claude");
 }
 function buildLayoutPaths(root) {
   return {
     root,
-    identitiesDir: path14.join(root, "identities"),
-    configProfilesDir: path14.join(root, "config-profiles"),
-    providersDir: path14.join(root, "providers"),
-    directoryRulesFile: path14.join(root, "directory-rules.json"),
-    activeIdentityFile: path14.join(root, "active-identity"),
-    globalConfigFile: path14.join(root, "config.json"),
-    categoriesLocalFile: path14.join(root, "categories.local.json"),
-    claudeShimFile: path14.join(root, "claude-shim.json"),
-    headroomDir: path14.join(root, "headroom"),
-    headroomStateFile: path14.join(root, "headroom", `state.v${String(HEADROOM_STATE_SCHEMA_VERSION)}.json`),
-    headroomSocketDir: path14.join(root, "headroom", "run"),
-    headroomLockFile: path14.join(root, "headroom", "start.lock"),
-    headroomSessionsDir: path14.join(root, "headroom", "sessions"),
-    logsDir: path14.join(root, "logs"),
-    headroomLogPath: path14.join(root, "logs", "headroom.log"),
-    frontdoorDir: path14.join(root, "frontdoor"),
-    frontdoorCaDir: path14.join(root, "frontdoor", "ca"),
-    frontdoorCaCertFile: path14.join(root, "frontdoor", "ca", "ca.pem"),
-    frontdoorCaKeyFile: path14.join(root, "frontdoor", "ca", "ca.key"),
-    frontdoorCaBundlesDir: path14.join(root, "frontdoor", "ca", "bundles"),
-    frontdoorStateFile: path14.join(root, "frontdoor", "state.json"),
-    frontdoorLockFile: path14.join(root, "frontdoor", "start.lock"),
-    frontdoorControlTokenFile: path14.join(root, "frontdoor", "control-token"),
-    frontdoorSessionsDir: path14.join(root, "frontdoor", "sessions"),
-    frontdoorLogPath: path14.join(root, "logs", "frontdoor.log"),
-    usageDir: path14.join(root, "usage"),
-    usageLogDir: path14.join(root, "usage", "log"),
-    usageSnapshotsDir: path14.join(root, "usage", "snapshots"),
-    usagePicksFile: path14.join(root, "usage", "picks.json")
+    identitiesDir: path15.join(root, "identities"),
+    configProfilesDir: path15.join(root, "config-profiles"),
+    providersDir: path15.join(root, "providers"),
+    directoryRulesFile: path15.join(root, "directory-rules.json"),
+    activeIdentityFile: path15.join(root, "active-identity"),
+    globalConfigFile: path15.join(root, "config.json"),
+    categoriesLocalFile: path15.join(root, "categories.local.json"),
+    claudeShimFile: path15.join(root, "claude-shim.json"),
+    headroomDir: path15.join(root, "headroom"),
+    headroomStateFile: path15.join(root, "headroom", `state.v${String(HEADROOM_STATE_SCHEMA_VERSION)}.json`),
+    headroomSocketDir: path15.join(root, "headroom", "run"),
+    headroomLockFile: path15.join(root, "headroom", "start.lock"),
+    headroomSessionsDir: path15.join(root, "headroom", "sessions"),
+    logsDir: path15.join(root, "logs"),
+    headroomLogPath: path15.join(root, "logs", "headroom.log"),
+    frontdoorDir: path15.join(root, "frontdoor"),
+    frontdoorCaDir: path15.join(root, "frontdoor", "ca"),
+    frontdoorCaCertFile: path15.join(root, "frontdoor", "ca", "ca.pem"),
+    frontdoorCaKeyFile: path15.join(root, "frontdoor", "ca", "ca.key"),
+    frontdoorCaBundlesDir: path15.join(root, "frontdoor", "ca", "bundles"),
+    frontdoorStateFile: path15.join(root, "frontdoor", "state.json"),
+    frontdoorLockFile: path15.join(root, "frontdoor", "start.lock"),
+    frontdoorControlTokenFile: path15.join(root, "frontdoor", "control-token"),
+    frontdoorSessionsDir: path15.join(root, "frontdoor", "sessions"),
+    frontdoorLogPath: path15.join(root, "logs", "frontdoor.log"),
+    usageDir: path15.join(root, "usage"),
+    usageLogDir: path15.join(root, "usage", "log"),
+    usageSnapshotsDir: path15.join(root, "usage", "snapshots"),
+    usagePicksFile: path15.join(root, "usage", "picks.json")
   };
 }
 function resolveLayoutPaths() {
@@ -6566,11 +6659,11 @@ function resolveLayoutPaths() {
 
 // src/identityStore.ts
 import fs5 from "node:fs";
-import path16 from "node:path";
+import path17 from "node:path";
 
 // src/configProfilesStore.ts
 import fs4 from "node:fs";
-import path15 from "node:path";
+import path16 from "node:path";
 var ProfileNotFoundError = class extends CliError {
   constructor(profileName) {
     super(`No configuration profile named "${profileName}". Run \`agent-shim profile add ${profileName}\` first.`);
@@ -6596,7 +6689,7 @@ var InvalidCategoryNameError = class extends CliError {
   categoryName;
 };
 function profileJsonPath(paths, name) {
-  return path15.join(paths.configProfilesDir, `${name}.json`);
+  return path16.join(paths.configProfilesDir, `${name}.json`);
 }
 function profileExists(paths, name) {
   return fs4.existsSync(profileJsonPath(paths, name));
@@ -6784,7 +6877,7 @@ var InvalidIdentityNameError = class extends CliError {
   attemptedName;
 };
 function identityJsonPath(paths, name) {
-  return path16.join(paths.identitiesDir, name, "identity.json");
+  return path17.join(paths.identitiesDir, name, "identity.json");
 }
 function identityExists(paths, name) {
   return fs5.existsSync(identityJsonPath(paths, name));
@@ -6885,7 +6978,7 @@ function setIdentityCredential(paths, identityName, change) {
   });
 }
 function belongsToIdentity(entry, name) {
-  return entry === name || entry === path16.basename(identityLockPath("", name)) || entry.startsWith(`.${name}.scratch.`) || entry.startsWith(`.${name}.previous.`);
+  return entry === name || entry === path17.basename(identityLockPath("", name)) || entry.startsWith(`.${name}.scratch.`) || entry.startsWith(`.${name}.previous.`);
 }
 function removeIdentity(paths, name) {
   if (!identityExists(paths, name)) {
@@ -6893,7 +6986,7 @@ function removeIdentity(paths, name) {
   }
   for (const entry of fs5.readdirSync(paths.identitiesDir)) {
     if (belongsToIdentity(entry, name)) {
-      fs5.rmSync(path16.join(paths.identitiesDir, entry), { recursive: true, force: true });
+      fs5.rmSync(path17.join(paths.identitiesDir, entry), { recursive: true, force: true });
     }
   }
   if (readActiveIdentity(paths) === name) {
@@ -6903,7 +6996,7 @@ function removeIdentity(paths, name) {
 
 // src/providersStore.ts
 import fs6 from "node:fs";
-import path17 from "node:path";
+import path18 from "node:path";
 
 // src/credentialCache.ts
 import { z as z12 } from "zod";
@@ -7168,7 +7261,7 @@ var InvalidProviderNameError = class extends CliError {
 };
 var PROVIDER_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._@-]*$/;
 function providerJsonPath(paths, name) {
-  return path17.join(paths.providersDir, `${name}.json`);
+  return path18.join(paths.providersDir, `${name}.json`);
 }
 function providerExists(paths, name) {
   return fs6.existsSync(providerJsonPath(paths, name));
@@ -7244,7 +7337,7 @@ function readProvider(paths, name) {
   return parseProviderFile(filePath, raw);
 }
 function loadProvider(providersDir, name, port) {
-  const filePath = path17.join(providersDir, `${name}.json`);
+  const filePath = path18.join(providersDir, `${name}.json`);
   const raw = port.readConfigFile(filePath);
   return raw === void 0 ? void 0 : parseProviderFile(filePath, raw);
 }
@@ -7499,21 +7592,21 @@ function removeDirectoryRule(paths, rulePath) {
 import os5 from "node:os";
 
 // src/launcher/cascade.ts
-import path19 from "node:path";
+import path20 from "node:path";
 
 // src/pathNorm.ts
-import path18 from "node:path";
+import path19 from "node:path";
 function expandTilde(value, home) {
   if (value === "~") {
     return home;
   }
   if (value.startsWith("~/")) {
-    return path18.join(home, value.slice(2));
+    return path19.join(home, value.slice(2));
   }
   return value;
 }
 function normaliseRulePath(rulePath, home) {
-  return path18.resolve(expandTilde(rulePath, home));
+  return path19.resolve(expandTilde(rulePath, home));
 }
 
 // src/launcher/cascade.ts
@@ -7523,7 +7616,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 = path19.join(params.paths.configProfilesDir, `${name}.json`);
+    const filepath = path20.join(params.paths.configProfilesDir, `${name}.json`);
     const loaded = loadConfigFile(filepath, ConfigProfileSchema, params.read);
     if (loaded === void 0) {
       return void 0;
@@ -7538,8 +7631,8 @@ function loadCascadeInput(params) {
   });
   const levels = [];
   for (const dir of dirs) {
-    const portable = loadConfigFile(path19.join(dir, PORTABLE_CONFIG_FILENAME), PortableConfigSchema, params.read) ?? loadConfigFile(path19.join(dir, LEGACY_PORTABLE_CONFIG_FILENAME), PortableConfigSchema, params.read);
-    const portableLocal = loadConfigFile(path19.join(dir, PORTABLE_LOCAL_CONFIG_FILENAME), PortableConfigSchema, params.read) ?? loadConfigFile(path19.join(dir, LEGACY_PORTABLE_LOCAL_CONFIG_FILENAME), PortableConfigSchema, params.read);
+    const portable = loadConfigFile(path20.join(dir, PORTABLE_CONFIG_FILENAME), PortableConfigSchema, params.read) ?? loadConfigFile(path20.join(dir, LEGACY_PORTABLE_CONFIG_FILENAME), PortableConfigSchema, params.read);
+    const portableLocal = loadConfigFile(path20.join(dir, PORTABLE_LOCAL_CONFIG_FILENAME), PortableConfigSchema, params.read) ?? loadConfigFile(path20.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 {
@@ -7590,7 +7683,7 @@ function readDirectorySelections(loaded) {
 // src/realCredentialCache.ts
 import { spawnSync } from "node:child_process";
 import fs7 from "node:fs";
-import path20 from "node:path";
+import path21 from "node:path";
 var KEYCHAIN_CACHE_SERVICE = "agent-shim-credential-cache";
 var CACHE_DIR_MODE = 448;
 var CACHE_FILE_MODE = 384;
@@ -7617,8 +7710,8 @@ function security(args, stdin) {
   return { status: result.status, stdout: result.stdout };
 }
 function createRealCredentialCache(root) {
-  const dir = path20.join(root, "credential-cache");
-  const filePath = (owner) => path20.join(dir, cacheFileNameFor(owner));
+  const dir = path21.join(root, "credential-cache");
+  const filePath = (owner) => path21.join(dir, cacheFileNameFor(owner));
   return {
     read(store, owner) {
       if (store === "file") {
@@ -7672,70 +7765,6 @@ import fs8 from "node:fs";
 import os4 from "node:os";
 import path22 from "node:path";
 import { isSea } from "node:sea";
-
-// src/versionDiscovery.ts
-import os3 from "node:os";
-import path21 from "node:path";
-function defaultVersionsDir() {
-  return path21.join(os3.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: path21.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";
 }
@@ -8137,13 +8166,17 @@ function realContentSourcePath() {
   return resolveContentSourcePath({ isSea: isSea(), execPath: process.execPath, argv1: process.argv[1] });
 }
 function realResolveClaudeBinary(isOwnBinary) {
-  return () => discoverClaudeBinary({
+  return (request4) => discoverClaudeBinary({
     listVersionsDir,
     pathDirs: (process.env.PATH ?? "").split(path22.delimiter).filter((dir) => dir !== ""),
     findExecutableInDir,
-    isOwnBinary
+    isOwnBinary,
+    ...request4?.version === void 0 ? {} : { version: request4.version }
   });
 }
+function realInstalledClaudeVersions() {
+  return installedVersions(listVersionsDir(defaultVersionsDir()));
+}
 
 // src/checkReport.ts
 import path23 from "node:path";
@@ -8185,6 +8218,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) {
@@ -8335,6 +8396,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,
@@ -8359,6 +8433,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,
@@ -8371,7 +8446,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) {
@@ -8420,6 +8496,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")
@@ -8458,11 +8545,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;
@@ -8548,6 +8636,7 @@ function collectCheckReport(params) {
     settingsFiles,
     run: realRunPort,
     credentialCache: realCredentialCacheEnv(paths),
+    installedClaudeVersions: realInstalledClaudeVersions(),
     ...farmRoot === void 0 ? {} : { farmRoot },
     platform: process.platform,
     ...provider === void 0 ? {} : { provider }
@@ -8699,13 +8788,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();
@@ -8729,6 +8818,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.");
@@ -8761,12 +8857,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()) {
@@ -8782,13 +8879,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",
@@ -8797,7 +8894,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",
@@ -8835,12 +8932,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) ?? ""}"`);
@@ -8848,6 +8945,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 {
@@ -8859,11 +8957,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",
@@ -8872,27 +8970,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) {
@@ -9062,6 +9161,7 @@ function collectDoctorReport(params) {
   const report = runDoctor({
     env: params.env,
     credentialCache: realCredentialCacheEnv(paths),
+    installedClaudeVersions: realInstalledClaudeVersions(),
     identities,
     configProfiles,
     providers,
@@ -9111,7 +9211,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" },
@@ -9157,6 +9257,7 @@ function parseLauncherArgv(argv) {
   let flagIdentity;
   let configProfile;
   let provider;
+  let claudeVersion;
   const booleans = {};
   const categoryFlags = [];
   const shareFlags = [];
@@ -9211,6 +9312,9 @@ function parseLauncherArgv(argv) {
       case "--provider":
         provider = value;
         break;
+      case "--claude-version":
+        claudeVersion = value;
+        break;
       case "--category":
         categoryFlags.push(value);
         break;
@@ -9232,6 +9336,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,
@@ -9693,7 +9798,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.