agent-shim 7.4.0 → 7.5.0

package/README.md

@@ -226,6 +226,7 @@ Issues and pull requests are welcome. Please keep the tool itself free of assump
 - [docs/architecture.md](docs/architecture.md): the source layout file by file, error reporting design, schema rationale, and resolver mechanics.
 - [docs/release-process.md](docs/release-process.md): the semantic-release pipeline, the Node SEA build, its macOS x64 limitation, and npm/GitHub Packages publishing.
 - [docs/testing.md](docs/testing.md): the full list of cases the test suites cover.
+- [docs/library.md](docs/library.md): using agent-shim in process: what the library exposes, and what stays CLI-only.
 - [docs/installation.md](docs/installation.md): every install channel in full, with the platform support matrix.
 - [docs/development.md](docs/development.md): test isolation, commit hooks, and the secret-redaction filter rationale.
 

package/dist/cli.cjs

@@ -61051,7 +61051,7 @@ function resolveLaunchIdentity(paths, cwd) {
 // package.json
 var package_default = {
   name: "agent-shim",
-  version: "7.4.0",
+  version: "7.5.0",
   description: "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   license: "MIT",
   author: "Joseph Mearman <joseph@mearman.co.uk>",

package/dist/index.cjs

@@ -34,13 +34,35 @@ __export(index_exports, {
   CONNECT_INTERCEPT_HOST: () => CONNECT_INTERCEPT_HOST,
   CONNECT_INTERCEPT_HOSTS: () => CONNECT_INTERCEPT_HOSTS,
   CONNECT_LIMITS: () => CONNECT_LIMITS,
+  CategoryClassificationOverlaySchema: () => CategoryClassificationOverlaySchema,
+  CategoryClassificationSchema: () => CategoryClassificationSchema,
+  CategoryMapSchema: () => CategoryMapSchema,
+  CliError: () => CliError,
+  ConfigProfileSchema: () => ConfigProfileSchema,
+  CredentialCacheSchema: () => CredentialCacheSchema,
+  CredentialSchema: () => CredentialSchema,
+  CredentialSourceSchema: () => CredentialSourceSchema,
+  DirectoryRuleSchema: () => DirectoryRuleSchema,
+  DirectoryRulesSchema: () => DirectoryRulesSchema,
+  EXIT_FAILURE: () => EXIT_FAILURE,
+  EXIT_USAGE: () => EXIT_USAGE,
+  EntryValueSchema: () => EntryValueSchema,
   FARM_MANIFEST_FILENAME: () => FARM_MANIFEST_FILENAME,
   FrontDoorStartError: () => FrontDoorStartError,
+  GlobalConfigSchema: () => GlobalConfigSchema,
   HeadroomStartError: () => HeadroomStartError,
+  IdentitySchema: () => IdentitySchema,
+  PoolNameSchema: () => PoolNameSchema,
+  PoolSchema: () => PoolSchema,
+  PortableConfigSchema: () => PortableConfigSchema,
+  ProviderSchema: () => ProviderSchema,
   ROUTED_PATH_PREFIX: () => ROUTED_PATH_PREFIX,
+  UsageError: () => UsageError,
   UsageSnapshotError: () => UsageSnapshotError,
   UsageSnapshotSchema: () => UsageSnapshotSchema,
+  WhenSchema: () => WhenSchema,
   buildEntryFacts: () => buildEntryFacts,
+  buildLayoutPaths: () => buildLayoutPaths,
   carryOver: () => carryOver,
   createLeafCache: () => createLeafCache,
   detectAmbientCredential: () => detectAmbientCredential,
@@ -61,7 +83,10 @@ __export(index_exports, {
   realConnectEffects: () => realConnectEffects,
   recoverFarm: () => recoverFarm,
   recoveryDiagnostics: () => recoveryDiagnostics,
+  resolveAgentShimHome: () => resolveAgentShimHome,
+  resolveClaudeHome: () => resolveClaudeHome,
   resolveDecisions: () => resolveDecisions,
+  resolveLayoutPaths: () => resolveLayoutPaths,
   resolveSupervisorConfig: () => resolveSupervisorConfig,
   resyncFarm: () => resyncFarm,
   runFrontDoorSupervisor: () => runFrontDoorSupervisor,
@@ -323,10 +348,18 @@ 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/classify.ts
 var GLOB_METACHARACTERS = /[*?[\]{}!()]/;
@@ -1287,6 +1320,8 @@ function planReconciliation(params) {
 }
 
 // src/legacy.ts
+var HOME_DIRNAME = ".agent-shim";
+var LEGACY_HOME_DIRNAME = ".claude-use";
 var LEGACY_FARM_MANIFEST_FILENAME = ".claude-use-farm.json";
 
 // src/launcher/lock.ts
@@ -1388,8 +1423,8 @@ var FarmManifestSchema = import_zod2.z.strictObject({
   materialised: import_zod2.z.array(import_zod2.z.string()),
   links: import_zod2.z.array(import_zod2.z.strictObject({ rel: import_zod2.z.string(), target: import_zod2.z.string() }))
 });
-function readFarmManifest(fs2, farmRoot) {
-  const raw = fs2.readFileUtf8(import_node_path4.default.join(farmRoot, FARM_MANIFEST_FILENAME)) ?? fs2.readFileUtf8(import_node_path4.default.join(farmRoot, LEGACY_FARM_MANIFEST_FILENAME));
+function readFarmManifest(fs3, farmRoot) {
+  const raw = fs3.readFileUtf8(import_node_path4.default.join(farmRoot, FARM_MANIFEST_FILENAME)) ?? fs3.readFileUtf8(import_node_path4.default.join(farmRoot, LEGACY_FARM_MANIFEST_FILENAME));
   if (raw === void 0) {
     return void 0;
   }
@@ -1447,9 +1482,9 @@ function buildEntryFacts(params) {
     entries
   };
 }
-function listSubtree(fs2, root, rel) {
+function listSubtree(fs3, root, rel) {
   const absolute = import_node_path4.default.join(root, rel);
-  const stat = fs2.lstat(absolute);
+  const stat = fs3.lstat(absolute);
   if (stat === void 0) {
     return [];
   }
@@ -1457,10 +1492,10 @@ function listSubtree(fs2, root, rel) {
     return [{ rel, kind: "symlink" }];
   }
   if (stat.kind === "dir") {
-    const children = [...fs2.readdir(absolute)].sort().flatMap((name) => listSubtree(fs2, root, `${rel}/${name}`));
+    const children = [...fs3.readdir(absolute)].sort().flatMap((name) => listSubtree(fs3, root, `${rel}/${name}`));
     return [{ rel, kind: "dir" }, ...children];
   }
-  const contentHash = fs2.hashFile(absolute);
+  const contentHash = fs3.hashFile(absolute);
   return [{ rel, kind: "file", ...contentHash === void 0 ? {} : { contentHash } }];
 }
 function topLevelScopeRoots(roots) {
@@ -1474,25 +1509,25 @@ function topLevelScopeRoots(roots) {
   }
   return kept;
 }
-function reconciliationScope(fs2, farmRoot, manifest) {
+function reconciliationScope(fs3, farmRoot, manifest) {
   if (manifest !== void 0) {
     return topLevelScopeRoots(manifest.materialised);
   }
-  return [...fs2.readdir(farmRoot)].filter((name) => name !== FARM_MANIFEST_FILENAME && name !== LEGACY_FARM_MANIFEST_FILENAME && fs2.lstat(import_node_path4.default.join(farmRoot, name))?.kind === "dir").sort();
+  return [...fs3.readdir(farmRoot)].filter((name) => name !== FARM_MANIFEST_FILENAME && name !== LEGACY_FARM_MANIFEST_FILENAME && fs3.lstat(import_node_path4.default.join(farmRoot, name))?.kind === "dir").sort();
 }
-function collectFarmListing(fs2, farmRoot, scopeRoots) {
-  return scopeRoots.flatMap((root) => listSubtree(fs2, farmRoot, root));
+function collectFarmListing(fs3, farmRoot, scopeRoots) {
+  return scopeRoots.flatMap((root) => listSubtree(fs3, farmRoot, root));
 }
-function collectCanonicalCounterparts(fs2, claudeHome, farmListing) {
+function collectCanonicalCounterparts(fs3, claudeHome, farmListing) {
   const out = [];
   for (const entry of farmListing) {
     const absolute = import_node_path4.default.join(claudeHome, entry.rel);
-    const stat = fs2.lstat(absolute);
+    const stat = fs3.lstat(absolute);
     if (stat === void 0) {
       continue;
     }
     if (stat.kind === "file") {
-      const contentHash = fs2.hashFile(absolute);
+      const contentHash = fs3.hashFile(absolute);
       out.push({ rel: entry.rel, kind: "file", ...contentHash === void 0 ? {} : { contentHash } });
       continue;
     }
@@ -2176,10 +2211,10 @@ var FrontDoorStateSchema = import_zod3.z.strictObject({
   /** The last fatal error, kept across shutdowns so `frontdoor status` can explain a front door that is not running. */
   lastError: import_zod3.z.string().optional()
 });
-function readFrontDoorState(fs2, stateFile) {
+function readFrontDoorState(fs3, stateFile) {
   let raw;
   try {
-    raw = fs2.readFileUtf8(stateFile);
+    raw = fs3.readFileUtf8(stateFile);
   } catch {
     return void 0;
   }
@@ -2193,28 +2228,28 @@ function readFrontDoorState(fs2, stateFile) {
     return void 0;
   }
 }
-function writeFrontDoorState(fs2, stateFile, state) {
-  fs2.mkdirp(import_node_path5.default.dirname(stateFile));
-  fs2.writeFileUtf8(stateFile, `${JSON.stringify(state, null, 2)}
+function writeFrontDoorState(fs3, stateFile, state) {
+  fs3.mkdirp(import_node_path5.default.dirname(stateFile));
+  fs3.writeFileUtf8(stateFile, `${JSON.stringify(state, null, 2)}
 `);
 }
 function frontDoorOrigin(state) {
   const port = state?.directPort ?? state?.lastDirectPort;
   return port === void 0 ? void 0 : `http://127.0.0.1:${String(port)}`;
 }
-function writeFrontDoorSession(fs2, sessionsDir, session) {
-  fs2.mkdirPrivate(sessionsDir);
-  fs2.writeFilePrivate(import_node_path5.default.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
+function writeFrontDoorSession(fs3, sessionsDir, session) {
+  fs3.mkdirPrivate(sessionsDir);
+  fs3.writeFilePrivate(import_node_path5.default.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
 `);
 }
-function listFrontDoorSessions(fs2, sessionsDir) {
+function listFrontDoorSessions(fs3, sessionsDir) {
   const sessions = [];
-  for (const name of fs2.readdir(sessionsDir)) {
+  for (const name of fs3.readdir(sessionsDir)) {
     if (!name.endsWith(".json")) {
       continue;
     }
     try {
-      const parsed = FrontDoorSessionSchema.safeParse(JSON.parse(fs2.readFileUtf8(import_node_path5.default.join(sessionsDir, name)) ?? ""));
+      const parsed = FrontDoorSessionSchema.safeParse(JSON.parse(fs3.readFileUtf8(import_node_path5.default.join(sessionsDir, name)) ?? ""));
       if (parsed.success) {
         sessions.push({ pid: parsed.data.pid, startedAt: parsed.data.startedAt });
       }
@@ -2224,14 +2259,14 @@ function listFrontDoorSessions(fs2, sessionsDir) {
   }
   return sessions.sort((a, b) => a.pid - b.pid);
 }
-function removeFrontDoorSession(fs2, sessionsDir, pid) {
-  fs2.removeRecursive(import_node_path5.default.join(sessionsDir, `${String(pid)}.json`));
+function removeFrontDoorSession(fs3, sessionsDir, pid) {
+  fs3.removeRecursive(import_node_path5.default.join(sessionsDir, `${String(pid)}.json`));
 }
-function pruneDeadFrontDoorSessions(fs2, sessionsDir, isRunning) {
+function pruneDeadFrontDoorSessions(fs3, sessionsDir, isRunning) {
   const removed = [];
-  for (const session of listFrontDoorSessions(fs2, sessionsDir)) {
+  for (const session of listFrontDoorSessions(fs3, sessionsDir)) {
     if (!isRunning(session.pid)) {
-      removeFrontDoorSession(fs2, sessionsDir, session.pid);
+      removeFrontDoorSession(fs3, sessionsDir, session.pid);
       removed.push(session.pid);
     }
   }
@@ -2243,8 +2278,8 @@ var FRONTDOOR_SUPERVISOR_STILL_RUNNING = -1;
 var FRONTDOOR_POLL_MS = 1e3;
 var MS_PER_MINUTE = 6e4;
 async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {}) {
-  const { fs: fs2, paths } = ports;
-  const previous = readFrontDoorState(fs2, paths.frontdoorStateFile);
+  const { fs: fs3, paths } = ports;
+  const previous = readFrontDoorState(fs3, paths.frontdoorStateFile);
   let lastPort = previous?.lastPort;
   let lastConnectPort = previous?.lastConnectPort;
   let lastDirectPort = previous?.lastDirectPort;
@@ -2254,12 +2289,12 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
     ...lastDirectPort === void 0 ? {} : { lastDirectPort }
   });
   const fail = (message) => {
-    writeFrontDoorState(fs2, paths.frontdoorStateFile, { lastError: message, ...sticky() });
-    fs2.removeRecursive(paths.frontdoorLockFile);
+    writeFrontDoorState(fs3, paths.frontdoorStateFile, { lastError: message, ...sticky() });
+    fs3.removeRecursive(paths.frontdoorLockFile);
     ports.log(`agent-shim frontdoor supervisor: ${message}`);
     return 1;
   };
-  writeFrontDoorState(fs2, paths.frontdoorStateFile, { supervisorPid: ports.ownPid, ...sticky() });
+  writeFrontDoorState(fs3, paths.frontdoorStateFile, { supervisorPid: ports.ownPid, ...sticky() });
   const previousSticky = lastPort;
   let http2;
   try {
@@ -2296,8 +2331,8 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
     ports.log(`agent-shim frontdoor supervisor: sticky direct port ${String(previousStickyDirect)} was occupied; moving to ${String(direct.port)} (headroom must be restarted to admit the new address)`);
   }
   lastDirectPort = direct.port;
-  writeFrontDoorState(fs2, paths.frontdoorStateFile, { supervisorPid: ports.ownPid, port: http2.port, connectPort: connect2.port, directPort: direct.port, ...sticky() });
-  fs2.removeRecursive(paths.frontdoorLockFile);
+  writeFrontDoorState(fs3, paths.frontdoorStateFile, { supervisorPid: ports.ownPid, port: http2.port, connectPort: connect2.port, directPort: direct.port, ...sticky() });
+  fs3.removeRecursive(paths.frontdoorLockFile);
   ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: front door on 127.0.0.1:${String(http2.port)}, CONNECT surface on 127.0.0.1:${String(connect2.port)}`);
   let idleSince;
   let ticks = 0;
@@ -2306,15 +2341,15 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
       return FRONTDOOR_SUPERVISOR_STILL_RUNNING;
     }
     ticks += 1;
-    pruneDeadFrontDoorSessions(fs2, paths.frontdoorSessionsDir, ports.isRunning);
-    if (listFrontDoorSessions(fs2, paths.frontdoorSessionsDir).length === 0) {
+    pruneDeadFrontDoorSessions(fs3, paths.frontdoorSessionsDir, ports.isRunning);
+    if (listFrontDoorSessions(fs3, paths.frontdoorSessionsDir).length === 0) {
       idleSince ??= ports.now();
       if (ports.now() - idleSince >= idleShutdownMinutes * MS_PER_MINUTE) {
         ports.log(`agent-shim frontdoor supervisor: no sessions for ${String(idleShutdownMinutes)} minute(s); closing the front door and exiting`);
         await direct.close();
         await connect2.close();
         await http2.close();
-        writeFrontDoorState(fs2, paths.frontdoorStateFile, sticky());
+        writeFrontDoorState(fs3, paths.frontdoorStateFile, sticky());
         return 0;
       }
     } else {
@@ -2369,8 +2404,8 @@ function parseConnectTarget(authority) {
 function isInterceptedHost(host, interceptHosts) {
   return interceptHosts.includes(host);
 }
-function servedByPipeline(path8) {
-  return path8?.startsWith(ROUTED_PATH_PREFIX) === true;
+function servedByPipeline(path9) {
+  return path9?.startsWith(ROUTED_PATH_PREFIX) === true;
 }
 var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
   "connection",
@@ -2853,16 +2888,16 @@ function parseJson(raw, schema) {
   const parsed = schema.safeParse(JSON.parse(raw));
   return parsed.success ? parsed.data : void 0;
 }
-function readHeadroomState(fs2, stateFile) {
+function readHeadroomState(fs3, stateFile) {
   try {
-    return parseJson(fs2.readFileUtf8(stateFile), HeadroomStateSchema);
+    return parseJson(fs3.readFileUtf8(stateFile), HeadroomStateSchema);
   } catch {
     return void 0;
   }
 }
-function writeHeadroomState(fs2, stateFile, state) {
-  fs2.mkdirp(import_node_path6.default.dirname(stateFile));
-  fs2.writeFilePrivate(stateFile, `${JSON.stringify(state, null, 2)}
+function writeHeadroomState(fs3, stateFile, state) {
+  fs3.mkdirp(import_node_path6.default.dirname(stateFile));
+  fs3.writeFilePrivate(stateFile, `${JSON.stringify(state, null, 2)}
 `);
 }
 function headroomAllowlist(providers) {
@@ -2882,14 +2917,14 @@ function headroomUpstreams(providers, frontDoorOrigin2) {
 function hashAllowlist(allowlist) {
   return (0, import_node_crypto4.createHash)("sha256").update(allowlist.join("\n")).digest("hex");
 }
-function readAllProviders(fs2, providersDir) {
+function readAllProviders(fs3, providersDir) {
   const result = [];
-  for (const name of fs2.readdir(providersDir)) {
+  for (const name of fs3.readdir(providersDir)) {
     if (!name.endsWith(".json")) {
       continue;
     }
     try {
-      const parsed = parseJson(fs2.readFileUtf8(import_node_path6.default.join(providersDir, name)), ProviderSchema);
+      const parsed = parseJson(fs3.readFileUtf8(import_node_path6.default.join(providersDir, name)), ProviderSchema);
       if (parsed !== void 0) {
         result.push({ name: name.slice(0, -".json".length), provider: parsed });
       }
@@ -2899,22 +2934,22 @@ function readAllProviders(fs2, providersDir) {
   }
   return result;
 }
-function writeSession(fs2, sessionsDir, session) {
-  fs2.mkdirp(sessionsDir);
-  fs2.writeFileUtf8(import_node_path6.default.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
+function writeSession(fs3, sessionsDir, session) {
+  fs3.mkdirp(sessionsDir);
+  fs3.writeFileUtf8(import_node_path6.default.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
 `);
 }
-function removeSession(fs2, sessionsDir, pid) {
-  fs2.removeRecursive(import_node_path6.default.join(sessionsDir, `${String(pid)}.json`));
+function removeSession(fs3, sessionsDir, pid) {
+  fs3.removeRecursive(import_node_path6.default.join(sessionsDir, `${String(pid)}.json`));
 }
-function listSessions(fs2, sessionsDir) {
+function listSessions(fs3, sessionsDir) {
   const sessions = [];
-  for (const name of fs2.readdir(sessionsDir)) {
+  for (const name of fs3.readdir(sessionsDir)) {
     if (!name.endsWith(".json")) {
       continue;
     }
     try {
-      const parsed = parseJson(fs2.readFileUtf8(import_node_path6.default.join(sessionsDir, name)), HeadroomSessionSchema);
+      const parsed = parseJson(fs3.readFileUtf8(import_node_path6.default.join(sessionsDir, name)), HeadroomSessionSchema);
       if (parsed !== void 0) {
         sessions.push(parsed);
       }
@@ -2924,22 +2959,22 @@ function listSessions(fs2, sessionsDir) {
   }
   return sessions.sort((a, b) => a.pid - b.pid);
 }
-function sessionsForSupervisor(fs2, sessionsDir, supervisorPid) {
-  return listSessions(fs2, sessionsDir).filter((session) => session.supervisorPid === supervisorPid);
+function sessionsForSupervisor(fs3, sessionsDir, supervisorPid) {
+  return listSessions(fs3, sessionsDir).filter((session) => session.supervisorPid === supervisorPid);
 }
-function pruneDeadSessions(fs2, sessionsDir, isRunning) {
+function pruneDeadSessions(fs3, sessionsDir, isRunning) {
   const removed = [];
-  for (const session of listSessions(fs2, sessionsDir)) {
+  for (const session of listSessions(fs3, sessionsDir)) {
     if (!isRunning(session.pid)) {
-      removeSession(fs2, sessionsDir, session.pid);
+      removeSession(fs3, sessionsDir, session.pid);
       removed.push(session.pid);
     }
   }
   return removed;
 }
-function readStartLock(fs2, lockFile) {
+function readStartLock(fs3, lockFile) {
   try {
-    return parseJson(fs2.readFileUtf8(lockFile), HeadroomLockSchema);
+    return parseJson(fs3.readFileUtf8(lockFile), HeadroomLockSchema);
   } catch {
     return void 0;
   }
@@ -3176,9 +3211,9 @@ function snapshotPath(snapshotsDir, identity) {
   }
   return import_node_path7.default.join(snapshotsDir, `${identity}.json`);
 }
-function readUsageSnapshot(fs2, snapshotsDir, identity) {
+function readUsageSnapshot(fs3, snapshotsDir, identity) {
   const file = snapshotPath(snapshotsDir, identity);
-  const raw = fs2.readFileUtf8(file);
+  const raw = fs3.readFileUtf8(file);
   if (raw === void 0) {
     return void 0;
   }
@@ -3194,8 +3229,8 @@ function readUsageSnapshot(fs2, snapshotsDir, identity) {
   }
   return snapshot.data;
 }
-function listUsageSnapshots(fs2, snapshotsDir) {
-  return fs2.readdir(snapshotsDir).flatMap((name) => {
+function listUsageSnapshots(fs3, snapshotsDir) {
+  return fs3.readdir(snapshotsDir).flatMap((name) => {
     if (!name.endsWith(".json")) {
       return [];
     }
@@ -3203,7 +3238,7 @@ function listUsageSnapshots(fs2, snapshotsDir) {
     if (!isIdentityName(identity)) {
       return [];
     }
-    const snapshot = readUsageSnapshot(fs2, snapshotsDir, identity);
+    const snapshot = readUsageSnapshot(fs3, snapshotsDir, identity);
     return snapshot === void 0 ? [] : [snapshot];
   }).sort((left, right) => left.identity.localeCompare(right.identity));
 }
@@ -3370,9 +3405,9 @@ function compareVersions(a, b) {
 }
 var HEADROOM_SUPERVISOR_STILL_RUNNING = -1;
 async function runSupervisor(initialConfig, ports, options = {}) {
-  const { fs: fs2, paths } = ports;
+  const { fs: fs3, paths } = ports;
   let config = initialConfig;
-  const previousState = readHeadroomState(fs2, paths.headroomStateFile);
+  const previousState = readHeadroomState(fs3, paths.headroomStateFile);
   if (previousState?.supervisorPid !== void 0 && previousState.supervisorPid !== ports.ownPid && ports.isRunning(previousState.supervisorPid)) {
     ports.log(`agent-shim headroom supervisor ${String(ports.ownPid)}: supervisor ${String(previousState.supervisorPid)} already owns the daemon; exiting`);
     return 0;
@@ -3381,19 +3416,19 @@ async function runSupervisor(initialConfig, ports, options = {}) {
   let lastPort = previousState?.lastPort;
   const sticky = () => lastPort === void 0 ? {} : { lastPort };
   const ownsState = () => {
-    const owner = readHeadroomState(fs2, paths.headroomStateFile)?.supervisorPid;
+    const owner = readHeadroomState(fs3, paths.headroomStateFile)?.supervisorPid;
     return owner === void 0 || owner === ports.ownPid || !ports.isRunning(owner);
   };
   const writeOwnState = (state) => {
     if (!ownsState()) {
       return false;
     }
-    writeHeadroomState(fs2, paths.headroomStateFile, state);
+    writeHeadroomState(fs3, paths.headroomStateFile, state);
     return true;
   };
   const fail = (message) => {
     if (writeOwnState({ lastError: message, ...sticky() })) {
-      fs2.removeRecursive(paths.headroomLockFile);
+      fs3.removeRecursive(paths.headroomLockFile);
     }
     ports.log(`agent-shim headroom supervisor: ${message}`);
     return 1;
@@ -3442,7 +3477,7 @@ async function runSupervisor(initialConfig, ports, options = {}) {
     const settingsHash = hashSettings(config.settings);
     const allowlist = allowlistOf(ports);
     const allowlistHash = hashAllowlist(allowlist);
-    pruneDeadSessions(fs2, paths.headroomSessionsDir, ports.isRunning);
+    pruneDeadSessions(fs3, paths.headroomSessionsDir, ports.isRunning);
     const ownsNow = ownsState();
     if (!ownsNow && !superseded) {
       ports.log("agent-shim headroom supervisor: another supervisor now owns state.json; serving this daemon's own sessions until they end");
@@ -3494,7 +3529,7 @@ async function runSupervisor(initialConfig, ports, options = {}) {
           ...sticky()
         });
         if (recorded) {
-          fs2.removeRecursive(paths.headroomLockFile);
+          fs3.removeRecursive(paths.headroomLockFile);
         }
         idleSince = void 0;
         ports.log(`agent-shim headroom supervisor: headroom pid ${String(pid)} ready on 127.0.0.1:${String(port)}`);
@@ -3509,7 +3544,7 @@ async function runSupervisor(initialConfig, ports, options = {}) {
       }
     } else {
       if (runningHash !== allowlistHash || runningSettingsHash !== settingsHash || installedSource !== config.source) {
-        if (sessionsForSupervisor(fs2, paths.headroomSessionsDir, ports.ownPid).length === 0) {
+        if (sessionsForSupervisor(fs3, paths.headroomSessionsDir, ports.ownPid).length === 0) {
           ports.log("agent-shim headroom supervisor: configuration drifted and no sessions are live; restarting headroom");
           ports.stopProcess(headroomPid);
           headroomPid = void 0;
@@ -3518,7 +3553,7 @@ async function runSupervisor(initialConfig, ports, options = {}) {
           continue;
         }
       }
-      const sessions = sessionsForSupervisor(fs2, paths.headroomSessionsDir, ports.ownPid);
+      const sessions = sessionsForSupervisor(fs3, paths.headroomSessionsDir, ports.ownPid);
       if (sessions.length === 0) {
         idleSince ??= ports.now();
         const idleMs = ports.now() - idleSince;
@@ -3540,9 +3575,9 @@ async function runSupervisor(initialConfig, ports, options = {}) {
     await ports.sleep(HEADROOM_POLL_MS);
   }
 }
-function currentHeadroomAllowlist(fs2, paths) {
-  const providers = readAllProviders(fs2, paths.providersDir).map((entry) => entry.provider);
-  return headroomAllowlist(headroomUpstreams(providers, frontDoorOrigin(readFrontDoorState(fs2, paths.frontdoorStateFile))));
+function currentHeadroomAllowlist(fs3, paths) {
+  const providers = readAllProviders(fs3, paths.providersDir).map((entry) => entry.provider);
+  return headroomAllowlist(headroomUpstreams(providers, frontDoorOrigin(readFrontDoorState(fs3, paths.frontdoorStateFile))));
 }
 function allowlistOf(ports) {
   return currentHeadroomAllowlist(ports.fs, ports.paths);
@@ -3606,19 +3641,100 @@ function evaluateAmbientCredentialGuard(params) {
     message: formatAmbientCredentialGuardMessage(detected.variable, params.identityName)
   };
 }
+
+// src/paths.ts
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_os = __toESM(require("node:os"), 1);
+var import_node_path8 = __toESM(require("node:path"), 1);
+function resolveAgentShimHome(env = process.env, home = import_node_os.default.homedir(), isDirectory = isExistingDirectory) {
+  const fromEnv = env.AGENT_SHIM_HOME;
+  if (fromEnv !== void 0 && fromEnv !== "") {
+    return fromEnv;
+  }
+  const current = import_node_path8.default.join(home, HOME_DIRNAME);
+  const legacy = import_node_path8.default.join(home, LEGACY_HOME_DIRNAME);
+  return !isDirectory(current) && isDirectory(legacy) ? legacy : current;
+}
+function isExistingDirectory(candidate) {
+  return import_node_fs.default.statSync(candidate, { throwIfNoEntry: false })?.isDirectory() ?? false;
+}
+function resolveClaudeHome() {
+  const fromEnv = process.env.AGENT_SHIM_CLAUDE_HOME;
+  if (fromEnv !== void 0 && fromEnv !== "") {
+    return fromEnv;
+  }
+  return import_node_path8.default.join(import_node_os.default.homedir(), ".claude");
+}
+function buildLayoutPaths(root) {
+  return {
+    root,
+    identitiesDir: import_node_path8.default.join(root, "identities"),
+    configProfilesDir: import_node_path8.default.join(root, "config-profiles"),
+    providersDir: import_node_path8.default.join(root, "providers"),
+    directoryRulesFile: import_node_path8.default.join(root, "directory-rules.json"),
+    activeIdentityFile: import_node_path8.default.join(root, "active-identity"),
+    globalConfigFile: import_node_path8.default.join(root, "config.json"),
+    categoriesLocalFile: import_node_path8.default.join(root, "categories.local.json"),
+    claudeShimFile: import_node_path8.default.join(root, "claude-shim.json"),
+    headroomDir: import_node_path8.default.join(root, "headroom"),
+    headroomStateFile: import_node_path8.default.join(root, "headroom", "state.json"),
+    headroomLockFile: import_node_path8.default.join(root, "headroom", "start.lock"),
+    headroomSessionsDir: import_node_path8.default.join(root, "headroom", "sessions"),
+    logsDir: import_node_path8.default.join(root, "logs"),
+    headroomLogPath: import_node_path8.default.join(root, "logs", "headroom.log"),
+    frontdoorDir: import_node_path8.default.join(root, "frontdoor"),
+    frontdoorCaDir: import_node_path8.default.join(root, "frontdoor", "ca"),
+    frontdoorCaCertFile: import_node_path8.default.join(root, "frontdoor", "ca", "ca.pem"),
+    frontdoorCaKeyFile: import_node_path8.default.join(root, "frontdoor", "ca", "ca.key"),
+    frontdoorCaBundlesDir: import_node_path8.default.join(root, "frontdoor", "ca", "bundles"),
+    frontdoorStateFile: import_node_path8.default.join(root, "frontdoor", "state.json"),
+    frontdoorLockFile: import_node_path8.default.join(root, "frontdoor", "start.lock"),
+    frontdoorSessionsDir: import_node_path8.default.join(root, "frontdoor", "sessions"),
+    frontdoorLogPath: import_node_path8.default.join(root, "logs", "frontdoor.log"),
+    usageDir: import_node_path8.default.join(root, "usage"),
+    usageLogDir: import_node_path8.default.join(root, "usage", "log"),
+    usageSnapshotsDir: import_node_path8.default.join(root, "usage", "snapshots"),
+    usagePicksFile: import_node_path8.default.join(root, "usage", "picks.json")
+  };
+}
+function resolveLayoutPaths() {
+  return buildLayoutPaths(resolveAgentShimHome());
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AMBIENT_CREDENTIAL_VARS,
   CONNECT_INTERCEPT_HOST,
   CONNECT_INTERCEPT_HOSTS,
   CONNECT_LIMITS,
+  CategoryClassificationOverlaySchema,
+  CategoryClassificationSchema,
+  CategoryMapSchema,
+  CliError,
+  ConfigProfileSchema,
+  CredentialCacheSchema,
+  CredentialSchema,
+  CredentialSourceSchema,
+  DirectoryRuleSchema,
+  DirectoryRulesSchema,
+  EXIT_FAILURE,
+  EXIT_USAGE,
+  EntryValueSchema,
   FARM_MANIFEST_FILENAME,
   FrontDoorStartError,
+  GlobalConfigSchema,
   HeadroomStartError,
+  IdentitySchema,
+  PoolNameSchema,
+  PoolSchema,
+  PortableConfigSchema,
+  ProviderSchema,
   ROUTED_PATH_PREFIX,
+  UsageError,
   UsageSnapshotError,
   UsageSnapshotSchema,
+  WhenSchema,
   buildEntryFacts,
+  buildLayoutPaths,
   carryOver,
   createLeafCache,
   detectAmbientCredential,
@@ -3639,7 +3755,10 @@ function evaluateAmbientCredentialGuard(params) {
   realConnectEffects,
   recoverFarm,
   recoveryDiagnostics,
+  resolveAgentShimHome,
+  resolveClaudeHome,
   resolveDecisions,
+  resolveLayoutPaths,
   resolveSupervisorConfig,
   resyncFarm,
   runFrontDoorSupervisor,

package/dist/index.mjs

@@ -248,10 +248,18 @@ 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/classify.ts
 var GLOB_METACHARACTERS = /[*?[\]{}!()]/;
@@ -1212,6 +1220,8 @@ function planReconciliation(params) {
 }
 
 // src/legacy.ts
+var HOME_DIRNAME = ".agent-shim";
+var LEGACY_HOME_DIRNAME = ".claude-use";
 var LEGACY_FARM_MANIFEST_FILENAME = ".claude-use-farm.json";
 
 // src/launcher/lock.ts
@@ -1313,8 +1323,8 @@ var FarmManifestSchema = z2.strictObject({
   materialised: z2.array(z2.string()),
   links: z2.array(z2.strictObject({ rel: z2.string(), target: z2.string() }))
 });
-function readFarmManifest(fs2, farmRoot) {
-  const raw = fs2.readFileUtf8(path4.join(farmRoot, FARM_MANIFEST_FILENAME)) ?? fs2.readFileUtf8(path4.join(farmRoot, LEGACY_FARM_MANIFEST_FILENAME));
+function readFarmManifest(fs3, farmRoot) {
+  const raw = fs3.readFileUtf8(path4.join(farmRoot, FARM_MANIFEST_FILENAME)) ?? fs3.readFileUtf8(path4.join(farmRoot, LEGACY_FARM_MANIFEST_FILENAME));
   if (raw === void 0) {
     return void 0;
   }
@@ -1372,9 +1382,9 @@ function buildEntryFacts(params) {
     entries
   };
 }
-function listSubtree(fs2, root, rel) {
+function listSubtree(fs3, root, rel) {
   const absolute = path4.join(root, rel);
-  const stat = fs2.lstat(absolute);
+  const stat = fs3.lstat(absolute);
   if (stat === void 0) {
     return [];
   }
@@ -1382,10 +1392,10 @@ function listSubtree(fs2, root, rel) {
     return [{ rel, kind: "symlink" }];
   }
   if (stat.kind === "dir") {
-    const children = [...fs2.readdir(absolute)].sort().flatMap((name) => listSubtree(fs2, root, `${rel}/${name}`));
+    const children = [...fs3.readdir(absolute)].sort().flatMap((name) => listSubtree(fs3, root, `${rel}/${name}`));
     return [{ rel, kind: "dir" }, ...children];
   }
-  const contentHash = fs2.hashFile(absolute);
+  const contentHash = fs3.hashFile(absolute);
   return [{ rel, kind: "file", ...contentHash === void 0 ? {} : { contentHash } }];
 }
 function topLevelScopeRoots(roots) {
@@ -1399,25 +1409,25 @@ function topLevelScopeRoots(roots) {
   }
   return kept;
 }
-function reconciliationScope(fs2, farmRoot, manifest) {
+function reconciliationScope(fs3, farmRoot, manifest) {
   if (manifest !== void 0) {
     return topLevelScopeRoots(manifest.materialised);
   }
-  return [...fs2.readdir(farmRoot)].filter((name) => name !== FARM_MANIFEST_FILENAME && name !== LEGACY_FARM_MANIFEST_FILENAME && fs2.lstat(path4.join(farmRoot, name))?.kind === "dir").sort();
+  return [...fs3.readdir(farmRoot)].filter((name) => name !== FARM_MANIFEST_FILENAME && name !== LEGACY_FARM_MANIFEST_FILENAME && fs3.lstat(path4.join(farmRoot, name))?.kind === "dir").sort();
 }
-function collectFarmListing(fs2, farmRoot, scopeRoots) {
-  return scopeRoots.flatMap((root) => listSubtree(fs2, farmRoot, root));
+function collectFarmListing(fs3, farmRoot, scopeRoots) {
+  return scopeRoots.flatMap((root) => listSubtree(fs3, farmRoot, root));
 }
-function collectCanonicalCounterparts(fs2, claudeHome, farmListing) {
+function collectCanonicalCounterparts(fs3, claudeHome, farmListing) {
   const out = [];
   for (const entry of farmListing) {
     const absolute = path4.join(claudeHome, entry.rel);
-    const stat = fs2.lstat(absolute);
+    const stat = fs3.lstat(absolute);
     if (stat === void 0) {
       continue;
     }
     if (stat.kind === "file") {
-      const contentHash = fs2.hashFile(absolute);
+      const contentHash = fs3.hashFile(absolute);
       out.push({ rel: entry.rel, kind: "file", ...contentHash === void 0 ? {} : { contentHash } });
       continue;
     }
@@ -2101,10 +2111,10 @@ var FrontDoorStateSchema = z3.strictObject({
   /** The last fatal error, kept across shutdowns so `frontdoor status` can explain a front door that is not running. */
   lastError: z3.string().optional()
 });
-function readFrontDoorState(fs2, stateFile) {
+function readFrontDoorState(fs3, stateFile) {
   let raw;
   try {
-    raw = fs2.readFileUtf8(stateFile);
+    raw = fs3.readFileUtf8(stateFile);
   } catch {
     return void 0;
   }
@@ -2118,28 +2128,28 @@ function readFrontDoorState(fs2, stateFile) {
     return void 0;
   }
 }
-function writeFrontDoorState(fs2, stateFile, state) {
-  fs2.mkdirp(path5.dirname(stateFile));
-  fs2.writeFileUtf8(stateFile, `${JSON.stringify(state, null, 2)}
+function writeFrontDoorState(fs3, stateFile, state) {
+  fs3.mkdirp(path5.dirname(stateFile));
+  fs3.writeFileUtf8(stateFile, `${JSON.stringify(state, null, 2)}
 `);
 }
 function frontDoorOrigin(state) {
   const port = state?.directPort ?? state?.lastDirectPort;
   return port === void 0 ? void 0 : `http://127.0.0.1:${String(port)}`;
 }
-function writeFrontDoorSession(fs2, sessionsDir, session) {
-  fs2.mkdirPrivate(sessionsDir);
-  fs2.writeFilePrivate(path5.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
+function writeFrontDoorSession(fs3, sessionsDir, session) {
+  fs3.mkdirPrivate(sessionsDir);
+  fs3.writeFilePrivate(path5.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
 `);
 }
-function listFrontDoorSessions(fs2, sessionsDir) {
+function listFrontDoorSessions(fs3, sessionsDir) {
   const sessions = [];
-  for (const name of fs2.readdir(sessionsDir)) {
+  for (const name of fs3.readdir(sessionsDir)) {
     if (!name.endsWith(".json")) {
       continue;
     }
     try {
-      const parsed = FrontDoorSessionSchema.safeParse(JSON.parse(fs2.readFileUtf8(path5.join(sessionsDir, name)) ?? ""));
+      const parsed = FrontDoorSessionSchema.safeParse(JSON.parse(fs3.readFileUtf8(path5.join(sessionsDir, name)) ?? ""));
       if (parsed.success) {
         sessions.push({ pid: parsed.data.pid, startedAt: parsed.data.startedAt });
       }
@@ -2149,14 +2159,14 @@ function listFrontDoorSessions(fs2, sessionsDir) {
   }
   return sessions.sort((a, b) => a.pid - b.pid);
 }
-function removeFrontDoorSession(fs2, sessionsDir, pid) {
-  fs2.removeRecursive(path5.join(sessionsDir, `${String(pid)}.json`));
+function removeFrontDoorSession(fs3, sessionsDir, pid) {
+  fs3.removeRecursive(path5.join(sessionsDir, `${String(pid)}.json`));
 }
-function pruneDeadFrontDoorSessions(fs2, sessionsDir, isRunning) {
+function pruneDeadFrontDoorSessions(fs3, sessionsDir, isRunning) {
   const removed = [];
-  for (const session of listFrontDoorSessions(fs2, sessionsDir)) {
+  for (const session of listFrontDoorSessions(fs3, sessionsDir)) {
     if (!isRunning(session.pid)) {
-      removeFrontDoorSession(fs2, sessionsDir, session.pid);
+      removeFrontDoorSession(fs3, sessionsDir, session.pid);
       removed.push(session.pid);
     }
   }
@@ -2168,8 +2178,8 @@ var FRONTDOOR_SUPERVISOR_STILL_RUNNING = -1;
 var FRONTDOOR_POLL_MS = 1e3;
 var MS_PER_MINUTE = 6e4;
 async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {}) {
-  const { fs: fs2, paths } = ports;
-  const previous = readFrontDoorState(fs2, paths.frontdoorStateFile);
+  const { fs: fs3, paths } = ports;
+  const previous = readFrontDoorState(fs3, paths.frontdoorStateFile);
   let lastPort = previous?.lastPort;
   let lastConnectPort = previous?.lastConnectPort;
   let lastDirectPort = previous?.lastDirectPort;
@@ -2179,12 +2189,12 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
     ...lastDirectPort === void 0 ? {} : { lastDirectPort }
   });
   const fail = (message) => {
-    writeFrontDoorState(fs2, paths.frontdoorStateFile, { lastError: message, ...sticky() });
-    fs2.removeRecursive(paths.frontdoorLockFile);
+    writeFrontDoorState(fs3, paths.frontdoorStateFile, { lastError: message, ...sticky() });
+    fs3.removeRecursive(paths.frontdoorLockFile);
     ports.log(`agent-shim frontdoor supervisor: ${message}`);
     return 1;
   };
-  writeFrontDoorState(fs2, paths.frontdoorStateFile, { supervisorPid: ports.ownPid, ...sticky() });
+  writeFrontDoorState(fs3, paths.frontdoorStateFile, { supervisorPid: ports.ownPid, ...sticky() });
   const previousSticky = lastPort;
   let http2;
   try {
@@ -2221,8 +2231,8 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
     ports.log(`agent-shim frontdoor supervisor: sticky direct port ${String(previousStickyDirect)} was occupied; moving to ${String(direct.port)} (headroom must be restarted to admit the new address)`);
   }
   lastDirectPort = direct.port;
-  writeFrontDoorState(fs2, paths.frontdoorStateFile, { supervisorPid: ports.ownPid, port: http2.port, connectPort: connect2.port, directPort: direct.port, ...sticky() });
-  fs2.removeRecursive(paths.frontdoorLockFile);
+  writeFrontDoorState(fs3, paths.frontdoorStateFile, { supervisorPid: ports.ownPid, port: http2.port, connectPort: connect2.port, directPort: direct.port, ...sticky() });
+  fs3.removeRecursive(paths.frontdoorLockFile);
   ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: front door on 127.0.0.1:${String(http2.port)}, CONNECT surface on 127.0.0.1:${String(connect2.port)}`);
   let idleSince;
   let ticks = 0;
@@ -2231,15 +2241,15 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
       return FRONTDOOR_SUPERVISOR_STILL_RUNNING;
     }
     ticks += 1;
-    pruneDeadFrontDoorSessions(fs2, paths.frontdoorSessionsDir, ports.isRunning);
-    if (listFrontDoorSessions(fs2, paths.frontdoorSessionsDir).length === 0) {
+    pruneDeadFrontDoorSessions(fs3, paths.frontdoorSessionsDir, ports.isRunning);
+    if (listFrontDoorSessions(fs3, paths.frontdoorSessionsDir).length === 0) {
       idleSince ??= ports.now();
       if (ports.now() - idleSince >= idleShutdownMinutes * MS_PER_MINUTE) {
         ports.log(`agent-shim frontdoor supervisor: no sessions for ${String(idleShutdownMinutes)} minute(s); closing the front door and exiting`);
         await direct.close();
         await connect2.close();
         await http2.close();
-        writeFrontDoorState(fs2, paths.frontdoorStateFile, sticky());
+        writeFrontDoorState(fs3, paths.frontdoorStateFile, sticky());
         return 0;
       }
     } else {
@@ -2294,8 +2304,8 @@ function parseConnectTarget(authority) {
 function isInterceptedHost(host, interceptHosts) {
   return interceptHosts.includes(host);
 }
-function servedByPipeline(path8) {
-  return path8?.startsWith(ROUTED_PATH_PREFIX) === true;
+function servedByPipeline(path9) {
+  return path9?.startsWith(ROUTED_PATH_PREFIX) === true;
 }
 var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
   "connection",
@@ -2778,16 +2788,16 @@ function parseJson(raw, schema) {
   const parsed = schema.safeParse(JSON.parse(raw));
   return parsed.success ? parsed.data : void 0;
 }
-function readHeadroomState(fs2, stateFile) {
+function readHeadroomState(fs3, stateFile) {
   try {
-    return parseJson(fs2.readFileUtf8(stateFile), HeadroomStateSchema);
+    return parseJson(fs3.readFileUtf8(stateFile), HeadroomStateSchema);
   } catch {
     return void 0;
   }
 }
-function writeHeadroomState(fs2, stateFile, state) {
-  fs2.mkdirp(path6.dirname(stateFile));
-  fs2.writeFilePrivate(stateFile, `${JSON.stringify(state, null, 2)}
+function writeHeadroomState(fs3, stateFile, state) {
+  fs3.mkdirp(path6.dirname(stateFile));
+  fs3.writeFilePrivate(stateFile, `${JSON.stringify(state, null, 2)}
 `);
 }
 function headroomAllowlist(providers) {
@@ -2807,14 +2817,14 @@ function headroomUpstreams(providers, frontDoorOrigin2) {
 function hashAllowlist(allowlist) {
   return createHash2("sha256").update(allowlist.join("\n")).digest("hex");
 }
-function readAllProviders(fs2, providersDir) {
+function readAllProviders(fs3, providersDir) {
   const result = [];
-  for (const name of fs2.readdir(providersDir)) {
+  for (const name of fs3.readdir(providersDir)) {
     if (!name.endsWith(".json")) {
       continue;
     }
     try {
-      const parsed = parseJson(fs2.readFileUtf8(path6.join(providersDir, name)), ProviderSchema);
+      const parsed = parseJson(fs3.readFileUtf8(path6.join(providersDir, name)), ProviderSchema);
       if (parsed !== void 0) {
         result.push({ name: name.slice(0, -".json".length), provider: parsed });
       }
@@ -2824,22 +2834,22 @@ function readAllProviders(fs2, providersDir) {
   }
   return result;
 }
-function writeSession(fs2, sessionsDir, session) {
-  fs2.mkdirp(sessionsDir);
-  fs2.writeFileUtf8(path6.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
+function writeSession(fs3, sessionsDir, session) {
+  fs3.mkdirp(sessionsDir);
+  fs3.writeFileUtf8(path6.join(sessionsDir, `${String(session.pid)}.json`), `${JSON.stringify(session, null, 2)}
 `);
 }
-function removeSession(fs2, sessionsDir, pid) {
-  fs2.removeRecursive(path6.join(sessionsDir, `${String(pid)}.json`));
+function removeSession(fs3, sessionsDir, pid) {
+  fs3.removeRecursive(path6.join(sessionsDir, `${String(pid)}.json`));
 }
-function listSessions(fs2, sessionsDir) {
+function listSessions(fs3, sessionsDir) {
   const sessions = [];
-  for (const name of fs2.readdir(sessionsDir)) {
+  for (const name of fs3.readdir(sessionsDir)) {
     if (!name.endsWith(".json")) {
       continue;
     }
     try {
-      const parsed = parseJson(fs2.readFileUtf8(path6.join(sessionsDir, name)), HeadroomSessionSchema);
+      const parsed = parseJson(fs3.readFileUtf8(path6.join(sessionsDir, name)), HeadroomSessionSchema);
       if (parsed !== void 0) {
         sessions.push(parsed);
       }
@@ -2849,22 +2859,22 @@ function listSessions(fs2, sessionsDir) {
   }
   return sessions.sort((a, b) => a.pid - b.pid);
 }
-function sessionsForSupervisor(fs2, sessionsDir, supervisorPid) {
-  return listSessions(fs2, sessionsDir).filter((session) => session.supervisorPid === supervisorPid);
+function sessionsForSupervisor(fs3, sessionsDir, supervisorPid) {
+  return listSessions(fs3, sessionsDir).filter((session) => session.supervisorPid === supervisorPid);
 }
-function pruneDeadSessions(fs2, sessionsDir, isRunning) {
+function pruneDeadSessions(fs3, sessionsDir, isRunning) {
   const removed = [];
-  for (const session of listSessions(fs2, sessionsDir)) {
+  for (const session of listSessions(fs3, sessionsDir)) {
     if (!isRunning(session.pid)) {
-      removeSession(fs2, sessionsDir, session.pid);
+      removeSession(fs3, sessionsDir, session.pid);
       removed.push(session.pid);
     }
   }
   return removed;
 }
-function readStartLock(fs2, lockFile) {
+function readStartLock(fs3, lockFile) {
   try {
-    return parseJson(fs2.readFileUtf8(lockFile), HeadroomLockSchema);
+    return parseJson(fs3.readFileUtf8(lockFile), HeadroomLockSchema);
   } catch {
     return void 0;
   }
@@ -3101,9 +3111,9 @@ function snapshotPath(snapshotsDir, identity) {
   }
   return path7.join(snapshotsDir, `${identity}.json`);
 }
-function readUsageSnapshot(fs2, snapshotsDir, identity) {
+function readUsageSnapshot(fs3, snapshotsDir, identity) {
   const file = snapshotPath(snapshotsDir, identity);
-  const raw = fs2.readFileUtf8(file);
+  const raw = fs3.readFileUtf8(file);
   if (raw === void 0) {
     return void 0;
   }
@@ -3119,8 +3129,8 @@ function readUsageSnapshot(fs2, snapshotsDir, identity) {
   }
   return snapshot.data;
 }
-function listUsageSnapshots(fs2, snapshotsDir) {
-  return fs2.readdir(snapshotsDir).flatMap((name) => {
+function listUsageSnapshots(fs3, snapshotsDir) {
+  return fs3.readdir(snapshotsDir).flatMap((name) => {
     if (!name.endsWith(".json")) {
       return [];
     }
@@ -3128,7 +3138,7 @@ function listUsageSnapshots(fs2, snapshotsDir) {
     if (!isIdentityName(identity)) {
       return [];
     }
-    const snapshot = readUsageSnapshot(fs2, snapshotsDir, identity);
+    const snapshot = readUsageSnapshot(fs3, snapshotsDir, identity);
     return snapshot === void 0 ? [] : [snapshot];
   }).sort((left, right) => left.identity.localeCompare(right.identity));
 }
@@ -3295,9 +3305,9 @@ function compareVersions(a, b) {
 }
 var HEADROOM_SUPERVISOR_STILL_RUNNING = -1;
 async function runSupervisor(initialConfig, ports, options = {}) {
-  const { fs: fs2, paths } = ports;
+  const { fs: fs3, paths } = ports;
   let config = initialConfig;
-  const previousState = readHeadroomState(fs2, paths.headroomStateFile);
+  const previousState = readHeadroomState(fs3, paths.headroomStateFile);
   if (previousState?.supervisorPid !== void 0 && previousState.supervisorPid !== ports.ownPid && ports.isRunning(previousState.supervisorPid)) {
     ports.log(`agent-shim headroom supervisor ${String(ports.ownPid)}: supervisor ${String(previousState.supervisorPid)} already owns the daemon; exiting`);
     return 0;
@@ -3306,19 +3316,19 @@ async function runSupervisor(initialConfig, ports, options = {}) {
   let lastPort = previousState?.lastPort;
   const sticky = () => lastPort === void 0 ? {} : { lastPort };
   const ownsState = () => {
-    const owner = readHeadroomState(fs2, paths.headroomStateFile)?.supervisorPid;
+    const owner = readHeadroomState(fs3, paths.headroomStateFile)?.supervisorPid;
     return owner === void 0 || owner === ports.ownPid || !ports.isRunning(owner);
   };
   const writeOwnState = (state) => {
     if (!ownsState()) {
       return false;
     }
-    writeHeadroomState(fs2, paths.headroomStateFile, state);
+    writeHeadroomState(fs3, paths.headroomStateFile, state);
     return true;
   };
   const fail = (message) => {
     if (writeOwnState({ lastError: message, ...sticky() })) {
-      fs2.removeRecursive(paths.headroomLockFile);
+      fs3.removeRecursive(paths.headroomLockFile);
     }
     ports.log(`agent-shim headroom supervisor: ${message}`);
     return 1;
@@ -3367,7 +3377,7 @@ async function runSupervisor(initialConfig, ports, options = {}) {
     const settingsHash = hashSettings(config.settings);
     const allowlist = allowlistOf(ports);
     const allowlistHash = hashAllowlist(allowlist);
-    pruneDeadSessions(fs2, paths.headroomSessionsDir, ports.isRunning);
+    pruneDeadSessions(fs3, paths.headroomSessionsDir, ports.isRunning);
     const ownsNow = ownsState();
     if (!ownsNow && !superseded) {
       ports.log("agent-shim headroom supervisor: another supervisor now owns state.json; serving this daemon's own sessions until they end");
@@ -3419,7 +3429,7 @@ async function runSupervisor(initialConfig, ports, options = {}) {
           ...sticky()
         });
         if (recorded) {
-          fs2.removeRecursive(paths.headroomLockFile);
+          fs3.removeRecursive(paths.headroomLockFile);
         }
         idleSince = void 0;
         ports.log(`agent-shim headroom supervisor: headroom pid ${String(pid)} ready on 127.0.0.1:${String(port)}`);
@@ -3434,7 +3444,7 @@ async function runSupervisor(initialConfig, ports, options = {}) {
       }
     } else {
       if (runningHash !== allowlistHash || runningSettingsHash !== settingsHash || installedSource !== config.source) {
-        if (sessionsForSupervisor(fs2, paths.headroomSessionsDir, ports.ownPid).length === 0) {
+        if (sessionsForSupervisor(fs3, paths.headroomSessionsDir, ports.ownPid).length === 0) {
           ports.log("agent-shim headroom supervisor: configuration drifted and no sessions are live; restarting headroom");
           ports.stopProcess(headroomPid);
           headroomPid = void 0;
@@ -3443,7 +3453,7 @@ async function runSupervisor(initialConfig, ports, options = {}) {
           continue;
         }
       }
-      const sessions = sessionsForSupervisor(fs2, paths.headroomSessionsDir, ports.ownPid);
+      const sessions = sessionsForSupervisor(fs3, paths.headroomSessionsDir, ports.ownPid);
       if (sessions.length === 0) {
         idleSince ??= ports.now();
         const idleMs = ports.now() - idleSince;
@@ -3465,9 +3475,9 @@ async function runSupervisor(initialConfig, ports, options = {}) {
     await ports.sleep(HEADROOM_POLL_MS);
   }
 }
-function currentHeadroomAllowlist(fs2, paths) {
-  const providers = readAllProviders(fs2, paths.providersDir).map((entry) => entry.provider);
-  return headroomAllowlist(headroomUpstreams(providers, frontDoorOrigin(readFrontDoorState(fs2, paths.frontdoorStateFile))));
+function currentHeadroomAllowlist(fs3, paths) {
+  const providers = readAllProviders(fs3, paths.providersDir).map((entry) => entry.provider);
+  return headroomAllowlist(headroomUpstreams(providers, frontDoorOrigin(readFrontDoorState(fs3, paths.frontdoorStateFile))));
 }
 function allowlistOf(ports) {
   return currentHeadroomAllowlist(ports.fs, ports.paths);
@@ -3531,18 +3541,99 @@ function evaluateAmbientCredentialGuard(params) {
     message: formatAmbientCredentialGuardMessage(detected.variable, params.identityName)
   };
 }
+
+// src/paths.ts
+import fs2 from "node:fs";
+import os from "node:os";
+import path8 from "node:path";
+function resolveAgentShimHome(env = process.env, home = os.homedir(), isDirectory = isExistingDirectory) {
+  const fromEnv = env.AGENT_SHIM_HOME;
+  if (fromEnv !== void 0 && fromEnv !== "") {
+    return fromEnv;
+  }
+  const current = path8.join(home, HOME_DIRNAME);
+  const legacy = path8.join(home, LEGACY_HOME_DIRNAME);
+  return !isDirectory(current) && isDirectory(legacy) ? legacy : current;
+}
+function isExistingDirectory(candidate) {
+  return fs2.statSync(candidate, { throwIfNoEntry: false })?.isDirectory() ?? false;
+}
+function resolveClaudeHome() {
+  const fromEnv = process.env.AGENT_SHIM_CLAUDE_HOME;
+  if (fromEnv !== void 0 && fromEnv !== "") {
+    return fromEnv;
+  }
+  return path8.join(os.homedir(), ".claude");
+}
+function buildLayoutPaths(root) {
+  return {
+    root,
+    identitiesDir: path8.join(root, "identities"),
+    configProfilesDir: path8.join(root, "config-profiles"),
+    providersDir: path8.join(root, "providers"),
+    directoryRulesFile: path8.join(root, "directory-rules.json"),
+    activeIdentityFile: path8.join(root, "active-identity"),
+    globalConfigFile: path8.join(root, "config.json"),
+    categoriesLocalFile: path8.join(root, "categories.local.json"),
+    claudeShimFile: path8.join(root, "claude-shim.json"),
+    headroomDir: path8.join(root, "headroom"),
+    headroomStateFile: path8.join(root, "headroom", "state.json"),
+    headroomLockFile: path8.join(root, "headroom", "start.lock"),
+    headroomSessionsDir: path8.join(root, "headroom", "sessions"),
+    logsDir: path8.join(root, "logs"),
+    headroomLogPath: path8.join(root, "logs", "headroom.log"),
+    frontdoorDir: path8.join(root, "frontdoor"),
+    frontdoorCaDir: path8.join(root, "frontdoor", "ca"),
+    frontdoorCaCertFile: path8.join(root, "frontdoor", "ca", "ca.pem"),
+    frontdoorCaKeyFile: path8.join(root, "frontdoor", "ca", "ca.key"),
+    frontdoorCaBundlesDir: path8.join(root, "frontdoor", "ca", "bundles"),
+    frontdoorStateFile: path8.join(root, "frontdoor", "state.json"),
+    frontdoorLockFile: path8.join(root, "frontdoor", "start.lock"),
+    frontdoorSessionsDir: path8.join(root, "frontdoor", "sessions"),
+    frontdoorLogPath: path8.join(root, "logs", "frontdoor.log"),
+    usageDir: path8.join(root, "usage"),
+    usageLogDir: path8.join(root, "usage", "log"),
+    usageSnapshotsDir: path8.join(root, "usage", "snapshots"),
+    usagePicksFile: path8.join(root, "usage", "picks.json")
+  };
+}
+function resolveLayoutPaths() {
+  return buildLayoutPaths(resolveAgentShimHome());
+}
 export {
   AMBIENT_CREDENTIAL_VARS,
   CONNECT_INTERCEPT_HOST,
   CONNECT_INTERCEPT_HOSTS,
   CONNECT_LIMITS,
+  CategoryClassificationOverlaySchema,
+  CategoryClassificationSchema,
+  CategoryMapSchema,
+  CliError,
+  ConfigProfileSchema,
+  CredentialCacheSchema,
+  CredentialSchema,
+  CredentialSourceSchema,
+  DirectoryRuleSchema,
+  DirectoryRulesSchema,
+  EXIT_FAILURE,
+  EXIT_USAGE,
+  EntryValueSchema,
   FARM_MANIFEST_FILENAME,
   FrontDoorStartError,
+  GlobalConfigSchema,
   HeadroomStartError,
+  IdentitySchema,
+  PoolNameSchema,
+  PoolSchema,
+  PortableConfigSchema,
+  ProviderSchema,
   ROUTED_PATH_PREFIX,
+  UsageError,
   UsageSnapshotError,
   UsageSnapshotSchema,
+  WhenSchema,
   buildEntryFacts,
+  buildLayoutPaths,
   carryOver,
   createLeafCache,
   detectAmbientCredential,
@@ -3563,7 +3654,10 @@ export {
   realConnectEffects,
   recoverFarm,
   recoveryDiagnostics,
+  resolveAgentShimHome,
+  resolveClaudeHome,
   resolveDecisions,
+  resolveLayoutPaths,
   resolveSupervisorConfig,
   resyncFarm,
   runFrontDoorSupervisor,

package/dist/types/config/schema.d.ts

@@ -427,7 +427,7 @@ export declare const POOL_SELECTOR_PREFIX = "pool:";
 /** A pool's own name: the identity alphabet minus `@`, since a pool is never an email address. */
 export declare const PoolNameSchema: z.ZodString;
 /** A named, explicit set of identities to choose among at launch. Never implicit: a pool lists its members, so an identity that bills a client is only ever picked when someone put it there. */
-declare const PoolSchema: z.ZodObject<{
+export declare const PoolSchema: z.ZodObject<{
     identities: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
 export type Pool = z.infer<typeof PoolSchema>;

package/dist/types/index.d.ts

@@ -4,7 +4,8 @@
  * - identity and configuration-profile resolution and farm sync (`resolveDecisions`, `resyncFarm`, `buildEntryFacts`, ...), pure over facts and ports passed in;
  * - routing: the front door's Remote-Control-preserving, capability-authenticated CONNECT surface and its certificate authority, the front-door supervisor and ensure lifecycle, and the headroom supervisor and ensure lifecycle, each pure over its injected ports;
  * - the ambient-credential guard;
- * - the per-identity usage snapshot a statusline or launcher reads: its schema and the reader over an injected filesystem.
+ * - the per-identity usage snapshot a statusline or launcher reads: its schema and the reader over an injected filesystem;
+ * - the state root's layout (`resolveAgentShimHome`, `resolveLayoutPaths`, `buildLayoutPaths`), which includes adopting an existing `~/.claude-use` in place, and the Zod schema and inferred type of every configuration file (identity, configuration profile, provider, pool, directory rules, global config, credential), so a tool can validate or generate them with the same definitions the CLI uses.
  *
  * Everything the CLI alone needs (commander wiring, prompts, `doctor`, `check`) is deliberately not exported here.
  */
@@ -19,3 +20,6 @@ export { UsageSnapshotSchema, type UsageSnapshot } from "./usage/schema";
 export { ensureHeadroom, HeadroomStartError, type EnsureHeadroomPorts } from "./headroom/ensure";
 export { resolveSupervisorConfig, runSupervisor, type HeadroomSupervisorConfig, type RunSupervisorOptions, type SupervisorPorts } from "./headroom/supervisor";
 export { AMBIENT_CREDENTIAL_VARS, detectAmbientCredential, evaluateAmbientCredentialGuard, formatAmbientCredentialGuardMessage, type AmbientCredentialDetection, type AmbientCredentialGuardResult, type AmbientCredentialVar, type EvaluateAmbientCredentialGuardParams, type InjectedCredential, } from "./launcher/guard";
+export { buildLayoutPaths, resolveAgentShimHome, resolveClaudeHome, resolveLayoutPaths, type LayoutPaths } from "./paths";
+export { CliError, EXIT_FAILURE, EXIT_USAGE, UsageError } from "./cliError";
+export { CategoryClassificationOverlaySchema, CategoryClassificationSchema, CategoryMapSchema, ConfigProfileSchema, CredentialCacheSchema, CredentialSchema, CredentialSourceSchema, DirectoryRuleSchema, DirectoryRulesSchema, EntryValueSchema, GlobalConfigSchema, IdentitySchema, PoolNameSchema, PoolSchema, PortableConfigSchema, ProviderSchema, WhenSchema, type CategoryMap, type ConfigProfile, type Credential, type CredentialSource, type DirectoryRule, type DirectoryRules, type EntryValue, type GlobalConfig, type Identity, type Pool, type PortableConfig, type Provider, type WhenCondition, } from "./config/schema";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-shim",
-  "version": "7.4.0",
+  "version": "7.5.0",
   "description": "A profile manager and launcher for Claude Code that lets one person run multiple logins from one machine while controlling what gets shared between them.",
   "license": "MIT",
   "author": "Joseph Mearman <joseph@mearman.co.uk>",