agent-shim 8.22.0 → 8.23.0

package/README.md

@@ -145,7 +145,7 @@ agent-shim frontdoor rc watch [<cse_id>] [--json]
 agent-shim frontdoor rc selfhost mint <identity> [--force] [--json]
 agent-shim usage [--identity <name>] [--provider <name>] [--since <duration>] [--refresh] [--json]
 agent-shim account show [<identity>] [--refresh] [--json]
-agent-shim update [--check] [--json]
+agent-shim update [--check] [--mode <off|notify|auto>] [--json]
 agent-shim completion <bash|zsh|fish>
 agent-shim shim enable [--dir <path>] [--force]
 agent-shim shim disable [--dir <path>] [--force]

package/dist/cli.cjs

@@ -55361,6 +55361,11 @@ var FrontDoorGlobalConfigSchema = external_exports.strictObject({
   /** How long the front door may sit with no registered sessions before it closes and exits. Defaults to FRONTDOOR_DEFAULT_IDLE_SHUTDOWN_MINUTES. */
   idleShutdownMinutes: external_exports.number().int().positive().optional()
 });
+var UPDATE_MODES = ["off", "notify", "auto"];
+var UpdateGlobalConfigSchema = external_exports.strictObject({
+  /** What a launch does about a newer release of agent-shim itself; see `UPDATE_MODES`. Absent means `off`. */
+  mode: external_exports.enum(UPDATE_MODES).optional()
+});
 var GlobalConfigSchema = external_exports.strictObject({
   $schema: external_exports.string().optional(),
   defaultConfigProfile: external_exports.string().min(1).optional(),
@@ -55370,6 +55375,7 @@ var GlobalConfigSchema = external_exports.strictObject({
   launch: LaunchSchema.optional(),
   headroom: HeadroomGlobalConfigSchema.optional(),
   frontdoor: FrontDoorGlobalConfigSchema.optional(),
+  update: UpdateGlobalConfigSchema.optional(),
   pools: external_exports.record(PoolNameSchema, PoolSchema).optional()
 });
 var IdentitySchema = external_exports.strictObject({
@@ -61790,7 +61796,7 @@ function registerIdentityCommand(program2, deps) {
 // package.json
 var package_default = {
   name: "agent-shim",
-  version: "8.22.0",
+  version: "8.23.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>",
@@ -77539,6 +77545,7 @@ function registerRunCommand(program2, handler) {
 }
 
 // src/update/commands.ts
+var import_node_child_process7 = require("node:child_process");
 var import_node_fs17 = __toESM(require("node:fs"), 1);
 var import_node_os7 = __toESM(require("node:os"), 1);
 var import_node_path41 = __toESM(require("node:path"), 1);
@@ -77874,11 +77881,41 @@ function formatUpdateReport(report) {
       return report.action;
   }
 }
+function setUpdateMode(paths, mode) {
+  const existing = readGlobalConfig(paths);
+  applyPatch(paths.globalConfigFile, GlobalConfigSchema, { update: { ...existing?.update, mode } }, { defaults: {} });
+}
+function realLaunchUpdatePort(paths) {
+  return {
+    effectiveUrl: realUpdatePorts.http.effectiveUrl,
+    readStamp: (filePath) => realUpdatePorts.fs.readFileUtf8(filePath),
+    writeStamp: (filePath, contents) => {
+      writeTextAtomic(filePath, contents);
+    },
+    now: () => Date.now(),
+    spawnDetached: (args) => {
+      const invocation = selfInvocation(args);
+      const child = (0, import_node_child_process7.spawn)(invocation.command, invocation.args, { detached: true, stdio: "ignore", env: { ...process.env, AGENT_SHIM_HOME: paths.root } });
+      child.unref();
+    },
+    writeErr: (line) => {
+      console.error(line);
+    }
+  };
+}
 function registerUpdateCommand(program2, deps, ports = realUpdatePorts) {
   withExamples(
     program2.command("update").description(
-      "Download the newest release binary and install it over the running one. An installation that belongs to a package manager (Homebrew, npm, Scoop) names its channel and its upgrade command instead of updating in place."
-    ).option("--check", "Only report whether a newer release exists; download and change nothing.").option("--json", "Print the result as JSON.").action(async (options) => {
+      "Download the newest release binary and install it over the running one. An installation that belongs to a package manager (Homebrew, npm, Scoop) names its channel and its upgrade command instead of updating in place. With --mode, set the launch-time update mode in the global config instead of updating now."
+    ).option("--check", "Only report whether a newer release exists; download and change nothing.").addOption(new Option("--mode <mode>", "Set what a launch does about a newer release (off: nothing; notify: print one line; auto: also apply it in the background) in the global config, then exit.").choices(UPDATE_MODES)).option("--json", "Print the result as JSON.").action(async (options) => {
+      const mode = options.mode;
+      if (mode !== void 0) {
+        setUpdateMode(deps.paths, mode);
+        reportMutation(options.json, { action: "updated", kind: "update", name: "mode", value: { mode } }, () => {
+          console.log(`update mode set to ${mode}`);
+        });
+        return;
+      }
       const report = await runSelfUpdate(ports, {
         currentVersion: package_default.version,
         platform: process.platform,
@@ -77894,7 +77931,7 @@ function registerUpdateCommand(program2, deps, ports = realUpdatePorts) {
       }
       console.log(formatUpdateReport(report));
     }),
-    ["agent-shim update", "agent-shim update --check", "agent-shim update --json"]
+    ["agent-shim update", "agent-shim update --check", "agent-shim update --mode auto", "agent-shim update --json"]
   );
 }
 
@@ -78479,6 +78516,68 @@ function spawnClaude(params) {
   return params.proc.exit(exitCodeFor(result));
 }
 
+// src/update/launchHook.ts
+var UPDATE_CHECK_COOLDOWN_MS = 864e5;
+function resolveUpdateMode(globalConfig2) {
+  return globalConfig2?.update?.mode ?? "off";
+}
+function updateCheckDue(contents, nowMs, cooldownMs = UPDATE_CHECK_COOLDOWN_MS) {
+  if (contents === void 0) {
+    return true;
+  }
+  const checkedAt = Date.parse(contents.trim());
+  if (Number.isNaN(checkedAt)) {
+    return true;
+  }
+  const age = nowMs - checkedAt;
+  return age < 0 || age >= cooldownMs;
+}
+var NOOP_HANDLE = { markChildStarted: () => void 0 };
+function updateNotifyLine(currentVersion, latest) {
+  return `agent-shim: update available: ${currentVersion} -> ${latest} (run \`agent-shim update\` to install it)`;
+}
+function runLaunchUpdateCheck(params) {
+  const { mode, checkPath, currentVersion, port } = params;
+  if (mode === "off" || port === void 0) {
+    return NOOP_HANDLE;
+  }
+  let childStarted = false;
+  try {
+    if (!updateCheckDue(port.readStamp(checkPath), port.now())) {
+      return NOOP_HANDLE;
+    }
+    port.writeStamp(checkPath, new Date(port.now()).toISOString());
+  } catch {
+    return NOOP_HANDLE;
+  }
+  const answer = (url2) => {
+    try {
+      const latest = releaseTagFromUrl(url2);
+      if (latest === void 0 || compareVersions3(latest, currentVersion) <= 0) {
+        return;
+      }
+      if (mode === "auto") {
+        port.spawnDetached(["update"]);
+      }
+      if (!childStarted) {
+        port.writeErr(updateNotifyLine(currentVersion, latest));
+      }
+    } catch {
+    }
+  };
+  port.effectiveUrl(LATEST_RELEASE_URL).then(
+    (url2) => {
+      answer(url2);
+    },
+    () => void 0
+  );
+  return {
+    markChildStarted: () => {
+      childStarted = true;
+    }
+  };
+}
+
 // src/launcher.ts
 function resolveIdentityCredential(identity, credential, env, port) {
   if (port === void 0) {
@@ -78644,6 +78743,12 @@ function prepareLaunch(params) {
   log.info(
     `agent-shim: identity ${identityDecision.name ?? "(none)"} (${identityDecision.source}${poolExplanation === void 0 ? "" : `, ${poolExplanation}`}), config profile ${configProfileDecision.name ?? "(none)"} (${configProfileDecision.source})` + (resolvedProvider === void 0 ? "" : `, provider ${resolvedProvider.name} (credential ${resolvedProvider.credential.target} from ${describeSource(resolvedProvider.credential.source)})`) + (identityCredential === void 0 ? "" : `, identity credential ${identityCredential.target} from ${describeSource(identityCredential.source)}`)
   );
+  const updateCheck = runLaunchUpdateCheck({
+    mode: params.updateMode ?? "off",
+    checkPath: import_node_path43.default.join(paths.root, "update.check"),
+    currentVersion: package_default.version,
+    port: params.update
+  });
   let cascadeLaunch;
   if (farmContext !== void 0) {
     const { farm: resyncFarmRuntime, identity: resyncIdentity, cascade } = farmContext;
@@ -78749,11 +78854,12 @@ function prepareLaunch(params) {
       registered();
     }
   };
-  return { bin: discovered.path, args: finalArgv, env: finalEnv, release };
+  return { bin: discovered.path, args: finalArgv, env: finalEnv, release, markChildStarted: updateCheck.markChildStarted };
 }
 function runLauncher(params) {
   const plan = prepareLaunch(params);
   try {
+    plan.markChildStarted();
     spawnClaude({ bin: plan.bin, args: plan.args, env: plan.env, spawn: params.spawn, proc: params.proc, beforeExit: plan.release });
   } finally {
     plan.release();
@@ -78768,6 +78874,7 @@ function buildFarmRuntime(paths, cwd) {
   const loaded = loadCascadeInput({ paths, home, cwd, read });
   const selections = readDirectorySelections(loaded);
   const git = resolveGitBranch(realRunPort, cwd);
+  const updateMode = resolveUpdateMode(loaded.globalConfig);
   return {
     runtime: {
       fs: realFarmFs,
@@ -78793,7 +78900,8 @@ function buildFarmRuntime(paths, cwd) {
     ...selections.identity === void 0 ? {} : { directoryIdentity: selections.identity },
     ...selections.configProfile === void 0 ? {} : { directoryConfigProfile: selections.configProfile },
     ...loaded.globalConfig?.defaultConfigProfile === void 0 ? {} : { globalDefaultConfigProfile: loaded.globalConfig.defaultConfigProfile },
-    ...loaded.globalConfig?.pools === void 0 ? {} : { pools: loaded.globalConfig.pools }
+    ...loaded.globalConfig?.pools === void 0 ? {} : { pools: loaded.globalConfig.pools },
+    ...updateMode === "off" ? {} : { updateMode }
   };
 }
 function realClaudeBinaryResolver(paths) {
@@ -78815,6 +78923,7 @@ function realPrepareLaunchParams(paths, options) {
     ...farm.directoryConfigProfile === void 0 ? {} : { directoryRuleConfigProfile: farm.directoryConfigProfile },
     ...farm.globalDefaultConfigProfile === void 0 ? {} : { globalDefaultConfigProfile: farm.globalDefaultConfigProfile },
     ...farm.pools === void 0 ? {} : { pools: farm.pools },
+    ...farm.updateMode === void 0 ? {} : { updateMode: farm.updateMode },
     ...options.allowMissingConfigProfile === void 0 ? {} : { allowMissingConfigProfile: options.allowMissingConfigProfile }
   };
 }
@@ -78918,6 +79027,8 @@ async function runClaude(argvOverride) {
       farm,
       allowMissingConfigProfile
     }),
+    // Wired here rather than in realPrepareLaunchParams because the port re-invokes this very binary: correct for the agent-shim command line, wrong for a library host whose own executable is not agent-shim.
+    update: realLaunchUpdatePort(paths),
     spawn: realSpawnPort
   });
 }

package/dist/index.cjs

@@ -640,6 +640,11 @@ var FrontDoorGlobalConfigSchema = import_zod.z.strictObject({
   /** How long the front door may sit with no registered sessions before it closes and exits. Defaults to FRONTDOOR_DEFAULT_IDLE_SHUTDOWN_MINUTES. */
   idleShutdownMinutes: import_zod.z.number().int().positive().optional()
 });
+var UPDATE_MODES = ["off", "notify", "auto"];
+var UpdateGlobalConfigSchema = import_zod.z.strictObject({
+  /** What a launch does about a newer release of agent-shim itself; see `UPDATE_MODES`. Absent means `off`. */
+  mode: import_zod.z.enum(UPDATE_MODES).optional()
+});
 var GlobalConfigSchema = import_zod.z.strictObject({
   $schema: import_zod.z.string().optional(),
   defaultConfigProfile: import_zod.z.string().min(1).optional(),
@@ -649,6 +654,7 @@ var GlobalConfigSchema = import_zod.z.strictObject({
   launch: LaunchSchema.optional(),
   headroom: HeadroomGlobalConfigSchema.optional(),
   frontdoor: FrontDoorGlobalConfigSchema.optional(),
+  update: UpdateGlobalConfigSchema.optional(),
   pools: import_zod.z.record(PoolNameSchema, PoolSchema).optional()
 });
 var IdentitySchema = import_zod.z.strictObject({
@@ -11457,6 +11463,106 @@ function removeDirectoryRule(paths, rulePath) {
 var import_node_crypto10 = require("node:crypto");
 var import_node_path30 = __toESM(require("node:path"), 1);
 
+// package.json
+var package_default = {
+  name: "agent-shim",
+  version: "8.23.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>",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/ExaDev/agent-shim.git"
+  },
+  homepage: "https://github.com/ExaDev/agent-shim#readme",
+  bugs: "https://github.com/ExaDev/agent-shim/issues",
+  keywords: [
+    "claude-code",
+    "claude",
+    "cli"
+  ],
+  packageManager: "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
+  type: "module",
+  engines: {
+    node: "^22.18 || >=24"
+  },
+  bin: {
+    "agent-shim": "dist/cli.cjs",
+    "claude-use": "dist/cli.cjs"
+  },
+  files: [
+    "dist/cli.cjs",
+    "dist/index.mjs",
+    "dist/index.cjs",
+    "dist/types"
+  ],
+  scripts: {
+    prepare: "husky && node scripts/build.mts --bundle-only",
+    typecheck: "turbo run _typecheck",
+    _typecheck: "tsc --noEmit",
+    lint: "turbo run _lint",
+    _lint: "eslint . --cache --cache-location .eslintcache --max-warnings 0",
+    test: "turbo run _test",
+    _test: "vitest run",
+    "test:coverage": "turbo run _test:coverage",
+    "_test:coverage": "vitest run --coverage",
+    knip: "turbo run _knip",
+    _knip: "knip --cache",
+    build: "turbo run _build",
+    _build: "node scripts/build.mts",
+    "build:bundle": "node scripts/build.mts --bundle-only",
+    prepublishOnly: "pnpm build:bundle",
+    schema: "node scripts/gen-schema.mts"
+  },
+  dependencies: {
+    "@clack/prompts": "^1.8.0",
+    "@orpc/client": "1.15.4",
+    "@orpc/server": "1.15.4",
+    commander: "^15.0.0",
+    cosmiconfig: "^10.0.1",
+    picomatch: "^4.0.7",
+    undici: "7.29.1",
+    zod: "^4.6.1"
+  },
+  devDependencies: {
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@exadev/eslint-config": "2.12.1",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/node": "^26.5.1",
+    "@types/picomatch": "^4.0.3",
+    "@vitest/coverage-v8": "^4.1.11",
+    "conventional-changelog-conventionalcommits": "^10.4.0",
+    esbuild: "^0.28.2",
+    eslint: "^10.10.0",
+    globals: "^17.12.0",
+    husky: "^9.1.7",
+    jiti: "^2.7.0",
+    knip: "^6.35.1",
+    "lint-staged": "^17.5.0",
+    rollup: "4.64.0",
+    "rollup-plugin-dts": "6.5.1",
+    "semantic-release": "^25.0.9",
+    turbo: "^2.11.5",
+    typescript: "^6.0.3",
+    "typescript-eslint": "^8.70.0",
+    vitest: "^4.1.11"
+  },
+  main: "dist/index.cjs",
+  module: "dist/index.mjs",
+  types: "dist/types/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/types/index.d.ts",
+      import: "./dist/index.mjs",
+      require: "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+};
+
 // src/launcher/argv.ts
 var ConflictingIdentityError = class extends UsageError {
   constructor(positional, flag) {
@@ -11929,6 +12035,88 @@ function spawnClaude(params) {
   return params.proc.exit(exitCodeFor(result));
 }
 
+// src/update/update.ts
+var LATEST_RELEASE_URL = "https://github.com/ExaDev/agent-shim/releases/latest";
+function compareVersions3(left, right) {
+  const parse = (version) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (match === null) {
+      throw new Error(`not a plain release version: ${version}`);
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+  };
+  const leftParts = parse(left);
+  const rightParts = parse(right);
+  return leftParts.map((part, index) => part - (rightParts[index] ?? 0)).find((difference) => difference !== 0) ?? 0;
+}
+function releaseTagFromUrl(url) {
+  const segment = url.split("?")[0]?.split("/").at(-1);
+  const candidate = segment?.startsWith("v") === true ? segment.slice(1) : void 0;
+  return candidate !== void 0 && /^\d+\.\d+\.\d+$/.test(candidate) ? candidate : void 0;
+}
+
+// src/update/launchHook.ts
+var UPDATE_CHECK_COOLDOWN_MS = 864e5;
+function resolveUpdateMode(globalConfig) {
+  return globalConfig?.update?.mode ?? "off";
+}
+function updateCheckDue(contents, nowMs, cooldownMs = UPDATE_CHECK_COOLDOWN_MS) {
+  if (contents === void 0) {
+    return true;
+  }
+  const checkedAt = Date.parse(contents.trim());
+  if (Number.isNaN(checkedAt)) {
+    return true;
+  }
+  const age = nowMs - checkedAt;
+  return age < 0 || age >= cooldownMs;
+}
+var NOOP_HANDLE = { markChildStarted: () => void 0 };
+function updateNotifyLine(currentVersion, latest) {
+  return `agent-shim: update available: ${currentVersion} -> ${latest} (run \`agent-shim update\` to install it)`;
+}
+function runLaunchUpdateCheck(params) {
+  const { mode, checkPath, currentVersion, port } = params;
+  if (mode === "off" || port === void 0) {
+    return NOOP_HANDLE;
+  }
+  let childStarted = false;
+  try {
+    if (!updateCheckDue(port.readStamp(checkPath), port.now())) {
+      return NOOP_HANDLE;
+    }
+    port.writeStamp(checkPath, new Date(port.now()).toISOString());
+  } catch {
+    return NOOP_HANDLE;
+  }
+  const answer = (url) => {
+    try {
+      const latest = releaseTagFromUrl(url);
+      if (latest === void 0 || compareVersions3(latest, currentVersion) <= 0) {
+        return;
+      }
+      if (mode === "auto") {
+        port.spawnDetached(["update"]);
+      }
+      if (!childStarted) {
+        port.writeErr(updateNotifyLine(currentVersion, latest));
+      }
+    } catch {
+    }
+  };
+  port.effectiveUrl(LATEST_RELEASE_URL).then(
+    (url) => {
+      answer(url);
+    },
+    () => void 0
+  );
+  return {
+    markChildStarted: () => {
+      childStarted = true;
+    }
+  };
+}
+
 // src/launcher.ts
 function resolveIdentityCredential(identity, credential, env, port) {
   if (port === void 0) {
@@ -12094,6 +12282,12 @@ function prepareLaunch(params) {
   log.info(
     `agent-shim: identity ${identityDecision.name ?? "(none)"} (${identityDecision.source}${poolExplanation === void 0 ? "" : `, ${poolExplanation}`}), config profile ${configProfileDecision.name ?? "(none)"} (${configProfileDecision.source})` + (resolvedProvider === void 0 ? "" : `, provider ${resolvedProvider.name} (credential ${resolvedProvider.credential.target} from ${describeSource(resolvedProvider.credential.source)})`) + (identityCredential === void 0 ? "" : `, identity credential ${identityCredential.target} from ${describeSource(identityCredential.source)}`)
   );
+  const updateCheck = runLaunchUpdateCheck({
+    mode: params.updateMode ?? "off",
+    checkPath: import_node_path30.default.join(paths.root, "update.check"),
+    currentVersion: package_default.version,
+    port: params.update
+  });
   let cascadeLaunch;
   if (farmContext !== void 0) {
     const { farm: resyncFarmRuntime, identity: resyncIdentity, cascade } = farmContext;
@@ -12199,11 +12393,12 @@ function prepareLaunch(params) {
       registered();
     }
   };
-  return { bin: discovered.path, args: finalArgv, env: finalEnv, release };
+  return { bin: discovered.path, args: finalArgv, env: finalEnv, release, markChildStarted: updateCheck.markChildStarted };
 }
 function runLauncher(params) {
   const plan = prepareLaunch(params);
   try {
+    plan.markChildStarted();
     spawnClaude({ bin: plan.bin, args: plan.args, env: plan.env, spawn: params.spawn, proc: params.proc, beforeExit: plan.release });
   } finally {
     plan.release();
@@ -12366,6 +12561,7 @@ function buildFarmRuntime(paths, cwd) {
   const loaded = loadCascadeInput({ paths, home, cwd, read });
   const selections = readDirectorySelections(loaded);
   const git = resolveGitBranch(realRunPort, cwd);
+  const updateMode = resolveUpdateMode(loaded.globalConfig);
   return {
     runtime: {
       fs: realFarmFs,
@@ -12391,7 +12587,8 @@ function buildFarmRuntime(paths, cwd) {
     ...selections.identity === void 0 ? {} : { directoryIdentity: selections.identity },
     ...selections.configProfile === void 0 ? {} : { directoryConfigProfile: selections.configProfile },
     ...loaded.globalConfig?.defaultConfigProfile === void 0 ? {} : { globalDefaultConfigProfile: loaded.globalConfig.defaultConfigProfile },
-    ...loaded.globalConfig?.pools === void 0 ? {} : { pools: loaded.globalConfig.pools }
+    ...loaded.globalConfig?.pools === void 0 ? {} : { pools: loaded.globalConfig.pools },
+    ...updateMode === "off" ? {} : { updateMode }
   };
 }
 function realClaudeBinaryResolver(paths) {
@@ -12413,6 +12610,7 @@ function realPrepareLaunchParams(paths, options) {
     ...farm.directoryConfigProfile === void 0 ? {} : { directoryRuleConfigProfile: farm.directoryConfigProfile },
     ...farm.globalDefaultConfigProfile === void 0 ? {} : { globalDefaultConfigProfile: farm.globalDefaultConfigProfile },
     ...farm.pools === void 0 ? {} : { pools: farm.pools },
+    ...farm.updateMode === void 0 ? {} : { updateMode: farm.updateMode },
     ...options.allowMissingConfigProfile === void 0 ? {} : { allowMissingConfigProfile: options.allowMissingConfigProfile }
   };
 }

package/dist/index.mjs

@@ -368,6 +368,11 @@ var FrontDoorGlobalConfigSchema = z.strictObject({
   /** How long the front door may sit with no registered sessions before it closes and exits. Defaults to FRONTDOOR_DEFAULT_IDLE_SHUTDOWN_MINUTES. */
   idleShutdownMinutes: z.number().int().positive().optional()
 });
+var UPDATE_MODES = ["off", "notify", "auto"];
+var UpdateGlobalConfigSchema = z.strictObject({
+  /** What a launch does about a newer release of agent-shim itself; see `UPDATE_MODES`. Absent means `off`. */
+  mode: z.enum(UPDATE_MODES).optional()
+});
 var GlobalConfigSchema = z.strictObject({
   $schema: z.string().optional(),
   defaultConfigProfile: z.string().min(1).optional(),
@@ -377,6 +382,7 @@ var GlobalConfigSchema = z.strictObject({
   launch: LaunchSchema.optional(),
   headroom: HeadroomGlobalConfigSchema.optional(),
   frontdoor: FrontDoorGlobalConfigSchema.optional(),
+  update: UpdateGlobalConfigSchema.optional(),
   pools: z.record(PoolNameSchema, PoolSchema).optional()
 });
 var IdentitySchema = z.strictObject({
@@ -11185,6 +11191,106 @@ function removeDirectoryRule(paths, rulePath) {
 import { randomUUID as randomUUID4 } from "node:crypto";
 import path30 from "node:path";
 
+// package.json
+var package_default = {
+  name: "agent-shim",
+  version: "8.23.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>",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/ExaDev/agent-shim.git"
+  },
+  homepage: "https://github.com/ExaDev/agent-shim#readme",
+  bugs: "https://github.com/ExaDev/agent-shim/issues",
+  keywords: [
+    "claude-code",
+    "claude",
+    "cli"
+  ],
+  packageManager: "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
+  type: "module",
+  engines: {
+    node: "^22.18 || >=24"
+  },
+  bin: {
+    "agent-shim": "dist/cli.cjs",
+    "claude-use": "dist/cli.cjs"
+  },
+  files: [
+    "dist/cli.cjs",
+    "dist/index.mjs",
+    "dist/index.cjs",
+    "dist/types"
+  ],
+  scripts: {
+    prepare: "husky && node scripts/build.mts --bundle-only",
+    typecheck: "turbo run _typecheck",
+    _typecheck: "tsc --noEmit",
+    lint: "turbo run _lint",
+    _lint: "eslint . --cache --cache-location .eslintcache --max-warnings 0",
+    test: "turbo run _test",
+    _test: "vitest run",
+    "test:coverage": "turbo run _test:coverage",
+    "_test:coverage": "vitest run --coverage",
+    knip: "turbo run _knip",
+    _knip: "knip --cache",
+    build: "turbo run _build",
+    _build: "node scripts/build.mts",
+    "build:bundle": "node scripts/build.mts --bundle-only",
+    prepublishOnly: "pnpm build:bundle",
+    schema: "node scripts/gen-schema.mts"
+  },
+  dependencies: {
+    "@clack/prompts": "^1.8.0",
+    "@orpc/client": "1.15.4",
+    "@orpc/server": "1.15.4",
+    commander: "^15.0.0",
+    cosmiconfig: "^10.0.1",
+    picomatch: "^4.0.7",
+    undici: "7.29.1",
+    zod: "^4.6.1"
+  },
+  devDependencies: {
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@exadev/eslint-config": "2.12.1",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/node": "^26.5.1",
+    "@types/picomatch": "^4.0.3",
+    "@vitest/coverage-v8": "^4.1.11",
+    "conventional-changelog-conventionalcommits": "^10.4.0",
+    esbuild: "^0.28.2",
+    eslint: "^10.10.0",
+    globals: "^17.12.0",
+    husky: "^9.1.7",
+    jiti: "^2.7.0",
+    knip: "^6.35.1",
+    "lint-staged": "^17.5.0",
+    rollup: "4.64.0",
+    "rollup-plugin-dts": "6.5.1",
+    "semantic-release": "^25.0.9",
+    turbo: "^2.11.5",
+    typescript: "^6.0.3",
+    "typescript-eslint": "^8.70.0",
+    vitest: "^4.1.11"
+  },
+  main: "dist/index.cjs",
+  module: "dist/index.mjs",
+  types: "dist/types/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/types/index.d.ts",
+      import: "./dist/index.mjs",
+      require: "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+};
+
 // src/launcher/argv.ts
 var ConflictingIdentityError = class extends UsageError {
   constructor(positional, flag) {
@@ -11657,6 +11763,88 @@ function spawnClaude(params) {
   return params.proc.exit(exitCodeFor(result));
 }
 
+// src/update/update.ts
+var LATEST_RELEASE_URL = "https://github.com/ExaDev/agent-shim/releases/latest";
+function compareVersions3(left, right) {
+  const parse = (version) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (match === null) {
+      throw new Error(`not a plain release version: ${version}`);
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+  };
+  const leftParts = parse(left);
+  const rightParts = parse(right);
+  return leftParts.map((part, index) => part - (rightParts[index] ?? 0)).find((difference) => difference !== 0) ?? 0;
+}
+function releaseTagFromUrl(url) {
+  const segment = url.split("?")[0]?.split("/").at(-1);
+  const candidate = segment?.startsWith("v") === true ? segment.slice(1) : void 0;
+  return candidate !== void 0 && /^\d+\.\d+\.\d+$/.test(candidate) ? candidate : void 0;
+}
+
+// src/update/launchHook.ts
+var UPDATE_CHECK_COOLDOWN_MS = 864e5;
+function resolveUpdateMode(globalConfig) {
+  return globalConfig?.update?.mode ?? "off";
+}
+function updateCheckDue(contents, nowMs, cooldownMs = UPDATE_CHECK_COOLDOWN_MS) {
+  if (contents === void 0) {
+    return true;
+  }
+  const checkedAt = Date.parse(contents.trim());
+  if (Number.isNaN(checkedAt)) {
+    return true;
+  }
+  const age = nowMs - checkedAt;
+  return age < 0 || age >= cooldownMs;
+}
+var NOOP_HANDLE = { markChildStarted: () => void 0 };
+function updateNotifyLine(currentVersion, latest) {
+  return `agent-shim: update available: ${currentVersion} -> ${latest} (run \`agent-shim update\` to install it)`;
+}
+function runLaunchUpdateCheck(params) {
+  const { mode, checkPath, currentVersion, port } = params;
+  if (mode === "off" || port === void 0) {
+    return NOOP_HANDLE;
+  }
+  let childStarted = false;
+  try {
+    if (!updateCheckDue(port.readStamp(checkPath), port.now())) {
+      return NOOP_HANDLE;
+    }
+    port.writeStamp(checkPath, new Date(port.now()).toISOString());
+  } catch {
+    return NOOP_HANDLE;
+  }
+  const answer = (url) => {
+    try {
+      const latest = releaseTagFromUrl(url);
+      if (latest === void 0 || compareVersions3(latest, currentVersion) <= 0) {
+        return;
+      }
+      if (mode === "auto") {
+        port.spawnDetached(["update"]);
+      }
+      if (!childStarted) {
+        port.writeErr(updateNotifyLine(currentVersion, latest));
+      }
+    } catch {
+    }
+  };
+  port.effectiveUrl(LATEST_RELEASE_URL).then(
+    (url) => {
+      answer(url);
+    },
+    () => void 0
+  );
+  return {
+    markChildStarted: () => {
+      childStarted = true;
+    }
+  };
+}
+
 // src/launcher.ts
 function resolveIdentityCredential(identity, credential, env, port) {
   if (port === void 0) {
@@ -11822,6 +12010,12 @@ function prepareLaunch(params) {
   log.info(
     `agent-shim: identity ${identityDecision.name ?? "(none)"} (${identityDecision.source}${poolExplanation === void 0 ? "" : `, ${poolExplanation}`}), config profile ${configProfileDecision.name ?? "(none)"} (${configProfileDecision.source})` + (resolvedProvider === void 0 ? "" : `, provider ${resolvedProvider.name} (credential ${resolvedProvider.credential.target} from ${describeSource(resolvedProvider.credential.source)})`) + (identityCredential === void 0 ? "" : `, identity credential ${identityCredential.target} from ${describeSource(identityCredential.source)}`)
   );
+  const updateCheck = runLaunchUpdateCheck({
+    mode: params.updateMode ?? "off",
+    checkPath: path30.join(paths.root, "update.check"),
+    currentVersion: package_default.version,
+    port: params.update
+  });
   let cascadeLaunch;
   if (farmContext !== void 0) {
     const { farm: resyncFarmRuntime, identity: resyncIdentity, cascade } = farmContext;
@@ -11927,11 +12121,12 @@ function prepareLaunch(params) {
       registered();
     }
   };
-  return { bin: discovered.path, args: finalArgv, env: finalEnv, release };
+  return { bin: discovered.path, args: finalArgv, env: finalEnv, release, markChildStarted: updateCheck.markChildStarted };
 }
 function runLauncher(params) {
   const plan = prepareLaunch(params);
   try {
+    plan.markChildStarted();
     spawnClaude({ bin: plan.bin, args: plan.args, env: plan.env, spawn: params.spawn, proc: params.proc, beforeExit: plan.release });
   } finally {
     plan.release();
@@ -12094,6 +12289,7 @@ function buildFarmRuntime(paths, cwd) {
   const loaded = loadCascadeInput({ paths, home, cwd, read });
   const selections = readDirectorySelections(loaded);
   const git = resolveGitBranch(realRunPort, cwd);
+  const updateMode = resolveUpdateMode(loaded.globalConfig);
   return {
     runtime: {
       fs: realFarmFs,
@@ -12119,7 +12315,8 @@ function buildFarmRuntime(paths, cwd) {
     ...selections.identity === void 0 ? {} : { directoryIdentity: selections.identity },
     ...selections.configProfile === void 0 ? {} : { directoryConfigProfile: selections.configProfile },
     ...loaded.globalConfig?.defaultConfigProfile === void 0 ? {} : { globalDefaultConfigProfile: loaded.globalConfig.defaultConfigProfile },
-    ...loaded.globalConfig?.pools === void 0 ? {} : { pools: loaded.globalConfig.pools }
+    ...loaded.globalConfig?.pools === void 0 ? {} : { pools: loaded.globalConfig.pools },
+    ...updateMode === "off" ? {} : { updateMode }
   };
 }
 function realClaudeBinaryResolver(paths) {
@@ -12141,6 +12338,7 @@ function realPrepareLaunchParams(paths, options) {
     ...farm.directoryConfigProfile === void 0 ? {} : { directoryRuleConfigProfile: farm.directoryConfigProfile },
     ...farm.globalDefaultConfigProfile === void 0 ? {} : { globalDefaultConfigProfile: farm.globalDefaultConfigProfile },
     ...farm.pools === void 0 ? {} : { pools: farm.pools },
+    ...farm.updateMode === void 0 ? {} : { updateMode: farm.updateMode },
     ...options.allowMissingConfigProfile === void 0 ? {} : { allowMissingConfigProfile: options.allowMissingConfigProfile }
   };
 }

package/dist/types/index.d.ts

@@ -542,6 +542,11 @@ declare const HeadroomGlobalConfigSchema: z.ZodObject<{
     readMaturation: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 type HeadroomGlobalConfig = z.infer<typeof HeadroomGlobalConfigSchema>;
+/**
+ * The launch-time update modes. `off` never touches the network at launch; `notify` checks for a newer release on a cooldown and prints one line naming it and the command to apply it; `auto` additionally applies the update in the background.
+ */
+declare const UPDATE_MODES: readonly ["off", "notify", "auto"];
+type UpdateMode = (typeof UPDATE_MODES)[number];
 /** The user-global `~/.agent-shim/config.json`. */
 declare const GlobalConfigSchema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
@@ -602,6 +607,13 @@ declare const GlobalConfigSchema: z.ZodObject<{
     frontdoor: z.ZodOptional<z.ZodObject<{
         idleShutdownMinutes: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
+    update: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            off: "off";
+            notify: "notify";
+        }>>;
+    }, z.core.$strict>>;
     pools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         identities: z.ZodArray<z.ZodString>;
         preference: z.ZodOptional<z.ZodEnum<{
@@ -3998,13 +4010,13 @@ declare function createControlApiRouter(deps: ControlApiDeps): {
                     "config-profile": "config-profile";
                     identity: "identity";
                     provider: "provider";
+                    pool: "pool";
+                    keychain: "keychain";
                     "ambient-credential": "ambient-credential";
                     "binary-discovery": "binary-discovery";
                     "claude-shim": "claude-shim";
                     "path-resolution": "path-resolution";
                     "legacy-name": "legacy-name";
-                    pool: "pool";
-                    keychain: "keychain";
                     "directory-rules": "directory-rules";
                     "categories-local": "categories-local";
                     "active-identity": "active-identity";
@@ -4475,13 +4487,13 @@ declare function createDoorApiRouter(deps: DoorApiDeps): {
                     "config-profile": "config-profile";
                     identity: "identity";
                     provider: "provider";
+                    pool: "pool";
+                    keychain: "keychain";
                     "ambient-credential": "ambient-credential";
                     "binary-discovery": "binary-discovery";
                     "claude-shim": "claude-shim";
                     "path-resolution": "path-resolution";
                     "legacy-name": "legacy-name";
-                    pool: "pool";
-                    keychain: "keychain";
                     "directory-rules": "directory-rules";
                     "categories-local": "categories-local";
                     "active-identity": "active-identity";
@@ -4769,13 +4781,13 @@ declare const DoctorFindingSchema: z.ZodObject<{
         "config-profile": "config-profile";
         identity: "identity";
         provider: "provider";
+        pool: "pool";
+        keychain: "keychain";
         "ambient-credential": "ambient-credential";
         "binary-discovery": "binary-discovery";
         "claude-shim": "claude-shim";
         "path-resolution": "path-resolution";
         "legacy-name": "legacy-name";
-        pool: "pool";
-        keychain: "keychain";
         "directory-rules": "directory-rules";
         "categories-local": "categories-local";
         "active-identity": "active-identity";
@@ -4798,13 +4810,13 @@ declare const DoctorRunOutputSchema: z.ZodObject<{
             "config-profile": "config-profile";
             identity: "identity";
             provider: "provider";
+            pool: "pool";
+            keychain: "keychain";
             "ambient-credential": "ambient-credential";
             "binary-discovery": "binary-discovery";
             "claude-shim": "claude-shim";
             "path-resolution": "path-resolution";
             "legacy-name": "legacy-name";
-            pool: "pool";
-            keychain: "keychain";
             "directory-rules": "directory-rules";
             "categories-local": "categories-local";
             "active-identity": "active-identity";
@@ -5672,6 +5684,24 @@ interface CliOverride {
     };
 }
 
+/**
+ * Everything the launch-time update check needs from its host, injected so tests run it against scripted answers and no launch ever reaches GitHub by accident. Deliberately narrower than `UpdatePorts`: the launch path never downloads anything (the detached `agent-shim update` does), so only the release check, the cooldown stamp, the clock, the background spawn and the terminal are wired.
+ */
+interface UpdateLaunchPort {
+    /** Resolves the URL the `releases/latest` redirect lands on, exactly as `agent-shim update` resolves the newest version. */
+    readonly effectiveUrl: (url: string) => Promise<string>;
+    /** Reads the cooldown stamp, or undefined when it does not exist. */
+    readonly readStamp: (filePath: string) => string | undefined;
+    /** Writes the cooldown stamp atomically: a reader either sees the previous whole stamp or the new one, never a partial write. */
+    readonly writeStamp: (filePath: string, contents: string) => void;
+    /** The clock the cooldown reads, in epoch milliseconds. */
+    readonly now: () => number;
+    /** Re-invokes this very binary with `args` as a detached child whose stdio is ignored and which is unref'd, so it outlives the launch and never holds the terminal. */
+    readonly spawnDetached: (args: readonly string[]) => void;
+    /** Writes one line to the launching terminal's stderr. */
+    readonly writeErr: (line: string) => void;
+}
+
 /**
  * Everything the farm resync needs that the launcher itself has no way to produce: a real filesystem, a real clock, the working directory, and a way to load the cascade for it.
  *
@@ -5732,6 +5762,10 @@ interface PrepareLaunchParams {
     readonly credentials?: CredentialPort;
     /** True when the user was asked on a terminal whether to create the selected configuration profile and chose to launch without it. Without that explicit choice, a selected profile with no file is refused rather than silently skipped. */
     readonly allowMissingConfigProfile?: boolean;
+    /** The user-global `update.mode`, resolved from the same global config the launcher already loads. Absent means `off`, and `off` runs no launch-time update check at all. */
+    readonly updateMode?: UpdateMode;
+    /** Wires the launch-time update check behind `update.mode`. Omitted by a caller that cannot resolve releases, re-invoke this binary, or write to the terminal; a mode of `notify` or `auto` with no port wired simply checks nothing. */
+    readonly update?: UpdateLaunchPort;
 }
 /** Inputs to `runLauncher`: a launch's inputs plus the port that spawns the child. */
 interface RunLauncherParams extends PrepareLaunchParams {
@@ -5746,11 +5780,13 @@ interface LaunchPlan {
     readonly env: Readonly<Record<string, string | undefined>>;
     /** Releases the daemon session registrations this launch holds. Call it when the child has exited; it is safe to call more than once. */
     readonly release: () => void;
+    /** Marks the moment this plan's child is spawned: the launch-time update check suppresses its notify line from then on, since a line printed after the child took over the terminal would land mid-session. Call it immediately before spawning; it is safe to call more than once. */
+    readonly markChildStarted: () => void;
 }
 /**
  * Prepares one `claude` launch, in order:
  *
- * `CLAUDE_CONFIG_DIR` escape-hatch check, then the identity/config-profile decision, the provider decision, the identity's own credential, the ambient-credential guard, farm resync, version discovery, flag resolution (and, when headroom resolved on, daemon bring-up), the extra-flags split, and the final argument list and environment, returned as a `LaunchPlan` for the caller to spawn. It refuses through `params.proc.exit`, so a caller that is not a command line process passes a `proc` whose `exit` throws.
+ * `CLAUDE_CONFIG_DIR` escape-hatch check, then the identity/config-profile decision, the provider decision, the identity's own credential, the ambient-credential guard, the config-gated launch-time update check (fired after the decision line and never awaited; see `runLaunchUpdateCheck`), farm resync, version discovery, flag resolution (and, when headroom resolved on, daemon bring-up), the extra-flags split, and the final argument list and environment, returned as a `LaunchPlan` for the caller to spawn. It refuses through `params.proc.exit`, so a caller that is not a command line process passes a `proc` whose `exit` throws.
  *
  * A launch that resolves an identity with no `identity.json`, or a configuration profile with no file, is refused with exit 1 naming the missing name and how it was selected: silently proceeding would create a brand-new login for a mistyped `@name`, or launch with a whole cascade layer missing. On a terminal, `src/runClaude.ts` offers to create either before this runs.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-shim",
-  "version": "8.22.0",
+  "version": "8.23.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>",