claude-use 9.12.0 → 9.13.0

package/dist/index.mjs

@@ -2573,7 +2573,7 @@ function listFrontDoorSessions(fs12, sessionsDir) {
     try {
       const parsed = FrontDoorSessionSchema.safeParse(JSON.parse(fs12.readFileUtf8(path8.join(sessionsDir, name)) ?? ""));
       if (parsed.success) {
-        sessions.push({ pid: parsed.data.pid, startedAt: parsed.data.startedAt });
+        sessions.push({ pid: parsed.data.pid, startedAt: parsed.data.startedAt, ...parsed.data.supervisorPid === void 0 ? {} : { supervisorPid: parsed.data.supervisorPid } });
       }
     } catch {
       continue;
@@ -2599,7 +2599,7 @@ var init_state = __esm({
   "src/frontdoor/state.ts"() {
     "use strict";
     FRONT_DOOR_PROTOCOL = 3;
-    FrontDoorSessionSchema = z3.strictObject({ pid: z3.number().int().positive(), startedAt: z3.number(), token: z3.string().min(1) });
+    FrontDoorSessionSchema = z3.strictObject({ pid: z3.number().int().positive(), startedAt: z3.number(), token: z3.string().min(1), supervisorPid: z3.number().int().positive().optional() });
     FrontDoorStateSchema = z3.strictObject({
       /**
        * The launcher-to-door wire protocol this supervisor speaks, written once it is serving; absent in state written by a release that predates the field, which `ensureFrontDoor` reads as protocol 0. A launcher replaces a door whose protocol is lower than its own (see `FRONT_DOOR_PROTOCOL`).
@@ -2639,7 +2639,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "claude-use",
-      version: "9.12.0",
+      version: "9.13.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>",
@@ -2742,6 +2742,36 @@ var init_package = __esm({
   }
 });
 
+// src/frontdoor/supervisorProcesses.ts
+function parseFrontDoorSupervisorPids(psOutput) {
+  const pids = [];
+  for (const line of psOutput.split("\n")) {
+    const [pidText, ...argumentsList] = line.trim().split(/\s+/);
+    const pid = Number(pidText);
+    if (Number.isInteger(pid) && pid > 0 && argumentsList.includes(FRONT_DOOR_SUPERVISOR_ARGUMENT)) {
+      pids.push(pid);
+    }
+  }
+  return pids.sort((a, b) => a - b);
+}
+function listFrontDoorSupervisors(run, uid) {
+  const result = run.run("ps", ["-U", String(uid), "-o", "pid=,command="]);
+  if (result.status === null) {
+    return { ok: false, message: "ps could not be run" };
+  }
+  if (result.status !== 0) {
+    return { ok: false, message: `ps exited ${String(result.status)}${result.stderr.trim() === "" ? "" : `: ${result.stderr.trim()}`}` };
+  }
+  return { ok: true, pids: parseFrontDoorSupervisorPids(result.stdout) };
+}
+var FRONT_DOOR_SUPERVISOR_ARGUMENT;
+var init_supervisorProcesses = __esm({
+  "src/frontdoor/supervisorProcesses.ts"() {
+    "use strict";
+    FRONT_DOOR_SUPERVISOR_ARGUMENT = "__frontdoor-supervisor";
+  }
+});
+
 // src/headroom/state.ts
 import { createHash as createHash3 } from "node:crypto";
 import path11 from "node:path";
@@ -3338,9 +3368,15 @@ async function runSupervisor(initialConfig, ports, options = {}) {
     await ports.sleep(HEADROOM_POLL_MS);
   }
 }
+function currentHeadroomAllowlistInputs(fs12, paths) {
+  return {
+    providers: readAllProviders(fs12, paths.providersDir).map((entry) => entry.provider),
+    frontDoorOrigin: frontDoorOrigin(readFrontDoorState(fs12, paths.frontdoorStateFile))
+  };
+}
 function currentHeadroomAllowlist(fs12, paths) {
-  const providers = readAllProviders(fs12, paths.providersDir).map((entry) => entry.provider);
-  return headroomAllowlist(headroomUpstreams(providers, frontDoorOrigin(readFrontDoorState(fs12, paths.frontdoorStateFile))));
+  const inputs = currentHeadroomAllowlistInputs(fs12, paths);
+  return headroomAllowlist(headroomUpstreams(inputs.providers, inputs.frontDoorOrigin));
 }
 function allowlistOf(ports) {
   return currentHeadroomAllowlist(ports.fs, ports.paths);
@@ -3408,6 +3444,10 @@ function realIsProcessZombie(pid) {
 function realIsProcessRunning(pid) {
   return realIsProcessAlive(pid) && !realIsProcessZombie(pid);
 }
+function realIsFrontDoorSupervisor(pid) {
+  const result = spawnSync("ps", ["-o", "pid=,command=", "-p", String(pid)], { encoding: "utf8" });
+  return result.status === 0 && parseFrontDoorSupervisorPids(result.stdout).includes(pid);
+}
 function expandHome2(filePath) {
   return filePath.startsWith("~/") ? path13.join(os3.homedir(), filePath.slice(1)) : filePath;
 }
@@ -3611,6 +3651,7 @@ var init_realPorts = __esm({
     "use strict";
     init_load();
     init_versionDiscovery();
+    init_supervisorProcesses();
     init_ensure();
     init_supervisor();
     init_state2();
@@ -4645,7 +4686,7 @@ function assessIdentity(member, nowMs) {
   );
   if (blockedUntil > nowMs) {
     if (unified.overageStatus === "allowed") {
-      return { candidate: { ...base, class: "pay-per-use", reasons: [`plan exhausted until ${new Date(blockedUntil).toISOString()}, continues as extra usage`, ...windowReasons, ...planReasons] } };
+      return { candidate: { ...base, class: "pay-per-use", planReturnsAtMs: blockedUntil, reasons: [`plan exhausted until ${new Date(blockedUntil).toISOString()} (in ${formatAge(blockedUntil - nowMs)}), continues as extra usage`, ...windowReasons, ...planReasons] } };
     }
     return { candidate: { ...base, class: "ineligible", blockedUntilMs: blockedUntil, reasons: [`refused until ${new Date(blockedUntil).toISOString()} (in ${formatAge(blockedUntil - nowMs)})`, ...unified.fallbackAvailable === true ? ["a fallback is on offer, so requests for some models may still be served"] : [], ...windowReasons, ...overageReasons, ...planReasons] } };
   }
@@ -4760,7 +4801,8 @@ function rankPool(input) {
   return {
     candidates: ordered,
     ...pick === void 0 ? { ...earliestReturn === void 0 ? {} : { earliestReturn } } : { pick },
-    ...movedOff === void 0 || pick === void 0 ? {} : { movedOff }
+    ...movedOff === void 0 || pick === void 0 ? {} : { movedOff },
+    ...pick?.planReturnsAtMs === void 0 ? {} : { planReturn: { identity: pick.identity, atMs: pick.planReturnsAtMs } }
   };
 }
 var MS_PER_SECOND4, MS_PER_HOUR2, HOURS_PER_DAY2, FIVE_HOURS, PROMPT_CACHE_TTL_HOURS, PERCENT, SEVEN_DAYS, FIVE_HOUR_WINDOW_MS, SEVEN_DAY_WINDOW_MS, PROMPT_CACHE_TTL_MS, CLASS_ORDER;
@@ -6140,32 +6182,50 @@ function ensureFrontDoor(params) {
   let replaced = false;
   const distrusted = /* @__PURE__ */ new Set();
   let lastRejection;
+  const verifyWithRetry = (port) => {
+    let verdict = ports.verifyListener(port);
+    for (let attempt = 1; !verdict.ok && attempt < FRONTDOOR_PROBE_ATTEMPTS; attempt += 1) {
+      ports.sleep(FRONTDOOR_LAUNCHER_POLL_MS);
+      verdict = ports.verifyListener(port);
+    }
+    return verdict;
+  };
+  const stopAndAwaitExit = (supervisorPid, failure) => {
+    ports.stopSupervisor(supervisorPid);
+    while (ports.isRunning(supervisorPid)) {
+      if (ports.now() >= deadline) {
+        throw new FrontDoorStartError(`${failure}. Daemon log: ${paths.frontdoorLogPath}`);
+      }
+      ports.sleep(FRONTDOOR_LAUNCHER_POLL_MS);
+    }
+  };
   for (; ; ) {
     const state = readFrontDoorState(ports.fs, paths.frontdoorStateFile);
     const supervisorPid = state?.supervisorPid;
     if (supervisorPid !== void 0 && !distrusted.has(supervisorPid) && ports.isRunning(supervisorPid)) {
       if (state?.port !== void 0 && state.connectPort !== void 0) {
-        const verdict = ports.verifyListener(state.port);
+        const verdict = verifyWithRetry(state.port);
         if (verdict.ok && !replaced && !spawned && (params.replace === true || (state.protocol ?? 0) < FRONT_DOOR_PROTOCOL)) {
-          ports.stopSupervisor(supervisorPid);
-          while (ports.isRunning(supervisorPid)) {
-            if (ports.now() >= deadline) {
-              throw new FrontDoorStartError(`the front door (pid ${String(supervisorPid)}, protocol ${String(state.protocol ?? 0)}; this launcher speaks protocol ${String(FRONT_DOOR_PROTOCOL)}) was asked to be replaced and did not exit. Daemon log: ${paths.frontdoorLogPath}`);
-            }
-            ports.sleep(FRONTDOOR_LAUNCHER_POLL_MS);
-          }
+          stopAndAwaitExit(
+            supervisorPid,
+            `the front door (pid ${String(supervisorPid)}, protocol ${String(state.protocol ?? 0)}; this launcher speaks protocol ${String(FRONT_DOOR_PROTOCOL)}) was asked to be replaced and did not exit`
+          );
           replaced = true;
           continue;
         }
         if (verdict.ok) {
           const token = randomUUID3();
-          writeFrontDoorSession(ports.fs, paths.frontdoorSessionsDir, { pid: params.launcherPid, startedAt: ports.now(), token });
+          writeFrontDoorSession(ports.fs, paths.frontdoorSessionsDir, { pid: params.launcherPid, startedAt: ports.now(), token, supervisorPid });
           return { port: state.port, connectPort: state.connectPort, token };
         }
         lastRejection = `the listener on 127.0.0.1:${String(state.port)} (recorded for pid ${String(supervisorPid)}) failed authentication: ${verdict.reason}`;
         if (spawned) {
           throw new FrontDoorStartError(`${lastRejection}; refusing to send this session's credentials to it. Daemon log: ${paths.frontdoorLogPath}`);
         }
+        if (ports.isFrontDoorSupervisor(supervisorPid)) {
+          stopAndAwaitExit(supervisorPid, `the front door (pid ${String(supervisorPid)}) stopped answering and did not exit when asked to`);
+          continue;
+        }
         distrusted.add(supervisorPid);
         continue;
       }
@@ -6196,7 +6256,7 @@ function ensureFrontDoor(params) {
     ports.sleep(FRONTDOOR_LAUNCHER_POLL_MS);
   }
 }
-var FRONTDOOR_START_TIMEOUT_MS, FRONTDOOR_LAUNCHER_POLL_MS, FrontDoorStartError;
+var FRONTDOOR_START_TIMEOUT_MS, FRONTDOOR_LAUNCHER_POLL_MS, FRONTDOOR_PROBE_ATTEMPTS, FrontDoorStartError;
 var init_ensure2 = __esm({
   "src/frontdoor/ensure.ts"() {
     "use strict";
@@ -6205,6 +6265,7 @@ var init_ensure2 = __esm({
     init_state();
     FRONTDOOR_START_TIMEOUT_MS = 3e4;
     FRONTDOOR_LAUNCHER_POLL_MS = 100;
+    FRONTDOOR_PROBE_ATTEMPTS = 3;
     FrontDoorStartError = class extends CliError {
       constructor(message) {
         super(message);
@@ -6688,7 +6749,12 @@ function resolvePoolLaunch(params) {
     if (graph.ranking.candidates.length === 0) {
       return { ok: false, message: `agent-shim: no member of pool "${poolName}" is an existing identity.` };
     }
-    const { pick, earliestReturn, movedOff } = graph.ranking;
+    const { pick, earliestReturn, movedOff, planReturn } = graph.ranking;
+    if (pick !== void 0 && params.wait && planReturn !== void 0) {
+      log.info(`agent-shim: pool "${poolName}" would continue ${planReturn.identity} on extra usage; waiting until ${new Date(planReturn.atMs).toISOString()} for its plan window`);
+      params.sleep(Math.max(planReturn.atMs - nowMs, 0));
+      continue;
+    }
     if (pick !== void 0) {
       if (params.recordPick) {
         recordStickyPick(params.usageFs, params.paths.usagePicksFile, params.cwd, pick.identity, nowMs);
@@ -7391,6 +7457,7 @@ function realEnsurePorts(paths, spawnDaemon) {
     now: () => Date.now(),
     sleep: realSleepSync,
     spawnSupervisor: (layout) => spawnDaemon(layout, "__frontdoor-supervisor", layout.frontdoorLogPath),
+    isFrontDoorSupervisor: realIsFrontDoorSupervisor,
     stopSupervisor: (pid) => {
       process.kill(pid, "SIGTERM");
     },
@@ -8291,16 +8358,27 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
   ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: front door on 127.0.0.1:${String(http3.port)}, CONNECT surface on 127.0.0.1:${String(connect3.port)}`);
   let idleSince;
   let ticks = 0;
+  const supersedingOwner = () => {
+    const owner = readFrontDoorState(fs12, paths.frontdoorStateFile)?.supervisorPid;
+    return owner !== void 0 && owner !== ports.ownPid && ports.isRunning(owner) ? owner : void 0;
+  };
+  let supersededBy;
+  let served;
   const binaryReplaced = () => {
     const current = ports.statOwnExecutable();
     return current !== void 0 && servingBinary !== void 0 && (current.dev !== servingBinary.dev || current.ino !== servingBinary.ino || current.size !== servingBinary.size || current.mtimeMs !== servingBinary.mtimeMs);
   };
-  const shutdown = async () => {
+  const closeServing = async () => {
     await direct.close();
     await connect3.close();
     await http3.close();
     ports.closeRcStreamHub();
-    writeFrontDoorState(fs12, paths.frontdoorStateFile, sticky());
+  };
+  const shutdown = async () => {
+    await closeServing();
+    if (supersedingOwner() === void 0) {
+      writeFrontDoorState(fs12, paths.frontdoorStateFile, sticky());
+    }
     return 0;
   };
   for (; ; ) {
@@ -8313,7 +8391,28 @@ async function runFrontDoorSupervisor(idleShutdownMinutes, ports, options = {})
     ports.observeLaunchRegistry(listed, pruned);
     ports.checkQuotaExpiry();
     const prunedPids = new Set(pruned);
-    if (listed.filter((session) => !prunedPids.has(session.pid)).length === 0) {
+    const live = listed.filter((session) => !prunedPids.has(session.pid));
+    if (supersededBy === void 0) {
+      supersededBy = supersedingOwner();
+      if (supersededBy !== void 0) {
+        ports.log(`agent-shim frontdoor supervisor ${String(ports.ownPid)}: supervisor ${String(supersededBy)} now owns the front door; taking no new sessions and exiting once the sessions this door serves have ended`);
+        ports.doorHealth.superseded(supersededBy);
+        await ports.sleep(FRONTDOOR_POLL_MS);
+        continue;
+      }
+    } else {
+      const owner = supersededBy;
+      served = (served ?? live.filter((session) => session.pid !== ports.ownPid && session.pid !== owner && (session.supervisorPid === void 0 || session.supervisorPid === ports.ownPid))).filter((own) => live.some((session) => session.pid === own.pid && session.startedAt === own.startedAt));
+      if (served.length === 0) {
+        ports.log("agent-shim frontdoor supervisor: the sessions this superseded door served have ended; closing the front door and exiting");
+        ports.doorHealth.drained();
+        await closeServing();
+        return 0;
+      }
+      await ports.sleep(FRONTDOOR_POLL_MS);
+      continue;
+    }
+    if (live.length === 0) {
       if (ticks > 1 && binaryReplaced()) {
         ports.log("agent-shim frontdoor supervisor: the installed binary changed and no sessions are live; turning the door over for the next launch");
         ports.doorHealth.binaryTurnover();
@@ -12467,7 +12566,55 @@ init_credential();
 init_credentialCache();
 init_realCredentialCache();
 init_source();
+
+// src/headroom/allowlistDrift.ts
+init_state2();
+function diagnoseAllowlistDrift(params) {
+  const { recordedHash, providers, frontDoorOrigin: frontDoorOrigin2 } = params;
+  if (recordedHash === void 0 || recordedHash === hashAllowlist(headroomAllowlist(headroomUpstreams(providers, frontDoorOrigin2)))) {
+    return void 0;
+  }
+  const originIsInput = providers.length > 0 && frontDoorOrigin2 !== void 0;
+  if (!originIsInput) {
+    return ["provider-files"];
+  }
+  return recordedHash === hashAllowlist(headroomAllowlist(headroomUpstreams(providers, void 0))) ? ["front-door-origin"] : ["provider-files", "front-door-origin"];
+}
+
+// src/doctorReport.ts
 init_state2();
+init_supervisor();
+init_state();
+
+// src/doctorFrontDoor.ts
+function pushFrontDoor(push, supervisors, registeredPid) {
+  if (!supervisors.ok) {
+    push("frontdoor", "warn", `Could not list processes to look for duplicate front door supervisors: ${supervisors.message}.`);
+    return;
+  }
+  const { pids } = supervisors;
+  if (pids.length === 0) {
+    push("frontdoor", "pass", "No front door supervisor is running.");
+    return;
+  }
+  const [only, ...rest] = pids;
+  if (only !== void 0 && rest.length === 0) {
+    push("frontdoor", "pass", `One front door supervisor is running (pid ${String(only)}).`);
+    return;
+  }
+  const serving = registeredPid !== void 0 && pids.includes(registeredPid) ? `The front door state file names pid ${String(registeredPid)} as the serving supervisor.` : "The front door state file names no running supervisor.";
+  for (const pid of pids.filter((candidate) => candidate !== registeredPid)) {
+    push(
+      "frontdoor",
+      "fail",
+      `Front door supervisor pid ${String(pid)} is running beside ${String(pids.length - 1)} other(s). ${serving} Stop it with \`kill ${String(pid)}\`; launches still connected to it lose their door.`,
+      String(pid)
+    );
+  }
+}
+
+// src/doctorReport.ts
+init_supervisorProcesses();
 init_legacy();
 init_providersStore();
 init_guard();
@@ -12490,7 +12637,8 @@ var DOCTOR_SECTIONS = [
   "global-config",
   "categories-local",
   "active-identity",
-  "headroom"
+  "headroom",
+  "frontdoor"
 ];
 function refinePathShadow(status, ownExecutablePath, realpath) {
   if (status.status !== "shadowed") {
@@ -12886,6 +13034,17 @@ function runDoctor(params) {
           `Headroom daemon is up on unix socket ${state.socketPath} (supervisor ${String(state.supervisorPid)}, daemon ${String(state.headroomPid)}).`
         );
       }
+      const allowlist = params.headroom.allowlist;
+      if (supervisorAlive && headroomAlive && state.socketPath !== void 0 && allowlist?.driftInputs?.includes("front-door-origin") === true) {
+        const origin = allowlist.frontDoorOrigin ?? "";
+        const certainty = allowlist.driftInputs.includes("provider-files") ? "may exclude" : "excludes";
+        push(
+          "headroom",
+          "fail",
+          `Headroom daemon ${String(state.headroomPid)} was started with an allowlist that ${certainty} the serving front door's direct origin ${origin}, so it refuses every request a provider launch sends back through the door. Its supervisor restarts it once no launch is registered against it; \`agent-shim headroom status\` lists the registered launches, and \`--no-headroom\` launches are unaffected.`,
+          String(state.headroomPid)
+        );
+      }
       if (state.lastError !== void 0 && supervisorAlive) {
         push("headroom", "warn", `Headroom recorded a previous error: ${state.lastError}`);
       }
@@ -12898,6 +13057,10 @@ function runDoctor(params) {
       }
     }
   }
+  if (params.frontDoor !== void 0) {
+    const validated3 = params.frontDoor.state.raw === void 0 ? void 0 : validateJson(FrontDoorStateSchema, params.frontDoor.state);
+    pushFrontDoor(push, params.frontDoor.supervisors, validated3?.ok === true ? validated3.data.supervisorPid : void 0);
+  }
   if (params.activeIdentity.raw === void 0) {
     push("active-identity", "pass", "No active identity set.");
   } else {
@@ -12927,6 +13090,7 @@ var SECTION_TITLES = {
   "directory-rules": "Directory rules",
   "global-config": "Global config",
   headroom: "Headroom daemon",
+  frontdoor: "Front door",
   "categories-local": "categories.local.json",
   "active-identity": "Active identity"
 };
@@ -12944,6 +13108,7 @@ var SECTION_ORDER = [
   "directory-rules",
   "global-config",
   "headroom",
+  "frontdoor",
   "categories-local",
   "active-identity"
 ];
@@ -13021,6 +13186,9 @@ function collectDoctorReport(params) {
     shimState.targetPath,
     realpathOrSelf
   );
+  const uid = process.getuid?.();
+  const allowlistInputs = currentHeadroomAllowlistInputs(realFarmFs, paths);
+  const servingHeadroom = resolveServingHeadroomState(realFarmFs, { stateFile: paths.headroomStateFile, legacyStateFile: paths.headroomLegacyStateFile }, realIsProcessRunning);
   const report = runDoctor({
     env: params.env,
     credentialCache: realCredentialCacheEnv(paths),
@@ -13059,8 +13227,13 @@ function collectDoctorReport(params) {
         const statePath = resolved?.path ?? paths.headroomStateFile;
         return { path: statePath, raw: realFarmFs.readFileUtf8(statePath) };
       })(),
-      isRunning: realIsProcessRunning
-    }
+      isRunning: realIsProcessRunning,
+      allowlist: {
+        driftInputs: diagnoseAllowlistDrift({ recordedHash: servingHeadroom?.state.allowlistHash, ...allowlistInputs }),
+        frontDoorOrigin: allowlistInputs.frontDoorOrigin
+      }
+    },
+    ...uid === void 0 ? {} : { frontDoor: { state: { path: paths.frontdoorStateFile, raw: realFsPort.readFileUtf8(paths.frontdoorStateFile) }, supervisors: listFrontDoorSupervisors(realRunPort, uid) } }
   });
   return report;
 }
@@ -13762,7 +13935,9 @@ var DoorHealthEventSchema = z23.discriminatedUnion("kind", [
   z23.strictObject({ kind: z23.literal("generation"), pid: z23.number().int().positive(), providerPort: z23.number().int().positive(), connectPort: z23.number().int().positive(), directPort: z23.number().int().positive(), observedAt: z23.number() }),
   z23.strictObject({ kind: z23.literal("listenerFailed"), pid: z23.number().int().positive(), listener: z23.enum(["provider", "connect", "direct"]), message: z23.string(), observedAt: z23.number() }),
   z23.strictObject({ kind: z23.literal("binaryTurnover"), pid: z23.number().int().positive(), observedAt: z23.number() }),
-  z23.strictObject({ kind: z23.literal("idleShutdown"), pid: z23.number().int().positive(), observedAt: z23.number() })
+  z23.strictObject({ kind: z23.literal("idleShutdown"), pid: z23.number().int().positive(), observedAt: z23.number() }),
+  z23.strictObject({ kind: z23.literal("superseded"), pid: z23.number().int().positive(), ownerPid: z23.number().int().positive(), observedAt: z23.number() }),
+  z23.strictObject({ kind: z23.literal("drained"), pid: z23.number().int().positive(), observedAt: z23.number() })
 ]);
 var QuotaExpiringEventSchema = z23.strictObject({
   identity: z23.string().min(1),
@@ -14259,6 +14434,12 @@ function createDoorHealthPublisher(hub, now, pid) {
     },
     binaryTurnover: () => {
       publisher.publish({ kind: "binaryTurnover", pid, observedAt: now() });
+    },
+    superseded: (ownerPid) => {
+      publisher.publish({ kind: "superseded", pid, ownerPid, observedAt: now() });
+    },
+    drained: () => {
+      publisher.publish({ kind: "drained", pid, observedAt: now() });
     }
   };
 }

package/dist/types/index.d.ts

@@ -4586,6 +4586,18 @@ type PathShadowStatus = {
     readonly by: string;
 };
 
+/** One input the headroom allowlist is computed from: the provider definitions on disk, or the front door's direct origin. */
+type AllowlistDriftInput = "provider-files" | "front-door-origin";
+
+/** What listing the front-door supervisors found: their pids, or why the process table could not be read. */
+type FrontDoorSupervisorListing = {
+    readonly ok: true;
+    readonly pids: readonly number[];
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+
 /** The result of a successful discovery. */
 interface DiscoveredClaudeBinary {
     /** Full path to the discovered `claude` executable. */
@@ -4604,7 +4616,7 @@ type ClaudeBinaryResolver = (request?: Readonly<ClaudeBinaryRequest>) => Discove
 
 declare const DOCTOR_SEVERITIES: readonly ["pass", "warn", "fail"];
 type DoctorSeverity = (typeof DOCTOR_SEVERITIES)[number];
-declare const DOCTOR_SECTIONS: readonly ["ambient-credential", "binary-discovery", "claude-shim", "path-resolution", "legacy-name", "config-profile", "identity", "sign-in", "pool", "provider", "keychain", "directory-rules", "global-config", "categories-local", "active-identity", "headroom"];
+declare const DOCTOR_SECTIONS: readonly ["ambient-credential", "binary-discovery", "claude-shim", "path-resolution", "legacy-name", "config-profile", "identity", "sign-in", "pool", "provider", "keychain", "directory-rules", "global-config", "categories-local", "active-identity", "headroom", "frontdoor"];
 type DoctorSection = (typeof DOCTOR_SECTIONS)[number];
 /** One line of `agent-shim doctor`'s report. `subject` names the identity/profile/rule the finding is about, when the section has more than one of those. */
 interface DoctorFinding {
@@ -4700,6 +4712,18 @@ interface RunDoctorParams {
     readonly headroom: {
         readonly state: DoctorFileInput;
         readonly isRunning: (pid: number) => boolean;
+        /** What the daemon's allowlist is measured against. Omit to skip the allowlist check; with it, a daemon whose allowlist may exclude the serving door's direct origin is a failure. */
+        readonly allowlist?: {
+            /** The inputs that could explain the recorded allowlist hash not matching the current allowlist, or undefined when it matches. */
+            readonly driftInputs: readonly AllowlistDriftInput[] | undefined;
+            /** The serving front door's direct origin, or undefined before it has ever served. */
+            readonly frontDoorOrigin: string | undefined;
+        };
+    };
+    /** The front door's state.json and the supervisor processes alive for this user. Omit to skip the front-door checks (the platform cannot list processes); with it, more than one supervisor alive at once is a failure naming each superseded one. */
+    readonly frontDoor?: {
+        readonly state: DoctorFileInput;
+        readonly supervisors: FrontDoorSupervisorListing;
     };
 }
 /**
@@ -4888,11 +4912,14 @@ declare const UsageSnapshotSchema: z.ZodObject<{
 }, z.core.$strict>;
 type UsageSnapshot = z.infer<typeof UsageSnapshotSchema>;
 
-/** The record held in one front-door session-registry file: the launcher's pid plus the per-launch capability token its child presents on every request. */
+/**
+ * The record held in one front-door session-registry file: the launcher's pid plus the per-launch capability token its child presents on every request, and the supervisor of the door the launch was sent to. `supervisorPid` is absent on a record written before it existed and on a door's own transparent-surface record; such a launch cannot be attributed to a door, so a superseded door treats it as its own.
+ */
 declare const FrontDoorSessionSchema: z.ZodObject<{
     pid: z.ZodNumber;
     startedAt: z.ZodNumber;
     token: z.ZodString;
+    supervisorPid: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 type FrontDoorSession = z.infer<typeof FrontDoorSessionSchema>;
 /**
@@ -4911,7 +4938,7 @@ declare const FrontDoorStateSchema: z.ZodObject<{
 }, z.core.$strict>;
 type FrontDoorState = z.infer<typeof FrontDoorStateSchema>;
 /** A registered launch as status and the idle decision see it: the pid and start time, never the token, so nothing that prints or serialises a session can leak the capability. */
-type FrontDoorSessionSummary = Pick<FrontDoorSession, "pid" | "startedAt">;
+type FrontDoorSessionSummary = Pick<FrontDoorSession, "pid" | "startedAt" | "supervisorPid">;
 
 /** How a sign-out went: whether OpenAI was told, so the person knows the grant is dead on its side too. */
 interface SiwcLogoutResult {
@@ -6283,7 +6310,7 @@ declare const LaunchLifecycleEventSchema: z.ZodObject<{
 /** One launch lifecycle event, as the TypeScript the publisher emits and its consumers handle. */
 type LaunchLifecycleEvent = z.output<typeof LaunchLifecycleEventSchema>;
 /**
- * One door health event: the supervisor's own state transitions, observed at the moment they happened in this process. `generation` is the door fully serving (every listener bound and the state file naming it); `listenerFailed` is a start failure that ends the generation, naming which listener and why; `binaryTurnover` is the door retiring because the installed binary changed and no session is live, so the next launch serves from the new one; `idleShutdown` is the door closing itself with an empty session registry.
+ * One door health event: the supervisor's own state transitions, observed at the moment they happened in this process. `generation` is the door fully serving (every listener bound and the state file naming it); `listenerFailed` is a start failure that ends the generation, naming which listener and why; `binaryTurnover` is the door retiring because the installed binary changed and no session is live, so the next launch serves from the new one; `idleShutdown` is the door closing itself with an empty session registry; `superseded` is the state file coming to name another live supervisor, `ownerPid`, after which this door takes no new sessions; `drained` is a superseded door closing itself because every session it served has ended.
  */
 declare const DoorHealthEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"generation">;
@@ -6310,6 +6337,15 @@ declare const DoorHealthEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"idleShutdown">;
     pid: z.ZodNumber;
     observedAt: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"superseded">;
+    pid: z.ZodNumber;
+    ownerPid: z.ZodNumber;
+    observedAt: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"drained">;
+    pid: z.ZodNumber;
+    observedAt: z.ZodNumber;
 }, z.core.$strict>], "kind">;
 /** One door health event, as the TypeScript the publisher emits and its consumers handle. */
 type DoorHealthEvent = z.output<typeof DoorHealthEventSchema>;
@@ -7387,6 +7423,7 @@ declare function createControlApiRouter(deps: ControlApiDeps): {
                     "config-profile": "config-profile";
                     identity: "identity";
                     provider: "provider";
+                    frontdoor: "frontdoor";
                     pool: "pool";
                     keychain: "keychain";
                     "ambient-credential": "ambient-credential";
@@ -9369,6 +9406,7 @@ declare function createDoorApiRouter(deps: DoorApiDeps): {
                     "config-profile": "config-profile";
                     identity: "identity";
                     provider: "provider";
+                    frontdoor: "frontdoor";
                     pool: "pool";
                     keychain: "keychain";
                     "ambient-credential": "ambient-credential";
@@ -11175,6 +11213,7 @@ declare const DoctorFindingSchema: z.ZodObject<{
         "config-profile": "config-profile";
         identity: "identity";
         provider: "provider";
+        frontdoor: "frontdoor";
         pool: "pool";
         keychain: "keychain";
         "ambient-credential": "ambient-credential";
@@ -11205,6 +11244,7 @@ declare const DoctorRunOutputSchema: z.ZodObject<{
             "config-profile": "config-profile";
             identity: "identity";
             provider: "provider";
+            frontdoor: "frontdoor";
             pool: "pool";
             keychain: "keychain";
             "ambient-credential": "ambient-credential";
@@ -11397,7 +11437,7 @@ interface LaunchEventPublisher {
 declare function createLaunchEventPublisher(hub: DoorEventHub, now: () => number): LaunchEventPublisher;
 
 /**
- * The door health publisher: the supervisor's own state transitions as backbone events, so a consumer of the door learns the door itself changed and not only its sessions. The publisher emits nothing of its own: the supervisor tells it the moments it already lives through (every listener bound, a start failure that ends the generation, the binary turnover, the idle shutdown), each published the moment it happens rather than at a tick, because these are process facts, not registry facts diffed between observations.
+ * The door health publisher: the supervisor's own state transitions as backbone events, so a consumer of the door learns the door itself changed and not only its sessions. The publisher emits nothing of its own: the supervisor tells it the moments it already lives through (every listener bound, a start failure that ends the generation, the binary turnover, the idle shutdown, the supersession and the drained exit that follows it), each published the moment it happens rather than at a tick, because these are process facts, not registry facts diffed between observations.
  */
 /** Everything the door health publisher needs: the backbone it publishes on and the clock its events are observed at. */
 interface DoorHealthPublisher {
@@ -11413,6 +11453,10 @@ interface DoorHealthPublisher {
     readonly binaryTurnover: () => void;
     /** Publishes the idle shutdown: the door closing itself with an empty session registry. */
     readonly idleShutdown: () => void;
+    /** Publishes the supersession: the state file naming another live supervisor, `ownerPid`, so this door takes no new sessions and serves only those it already had. */
+    readonly superseded: (ownerPid: number) => void;
+    /** Publishes the drained exit: a superseded door closing itself because every session it served has ended. */
+    readonly drained: () => void;
 }
 /** Creates the door health publisher. One per door process, fed by the supervisor. */
 declare function createDoorHealthPublisher(hub: DoorEventHub, now: () => number, pid: number): DoorHealthPublisher;
@@ -11662,8 +11706,10 @@ interface EnsureFrontDoorPorts {
     readonly spawnSupervisor: (paths: LayoutPaths) => number;
     /** Authenticates the provider listener on `port`: a TLS handshake chaining to agent-shim's CA and a healthy answer, with no capability sent (see `probeFrontDoorSync`). */
     readonly verifyListener: (port: number) => ListenerVerdict;
-    /** Asks a running front-door supervisor to exit, without waiting for it to: the caller polls `isRunning`. Only ever called for a pid whose recorded listener has just authenticated as agent-shim's own. */
+    /** Asks a running front-door supervisor to exit, without waiting for it to: the caller polls `isRunning`. Only ever called for a pid whose recorded listener has just authenticated as agent-shim's own, or whose process is agent-shim's front-door supervisor (`isFrontDoorSupervisor`). */
     readonly stopSupervisor: (pid: number) => void;
+    /** Whether `pid` is a live agent-shim front-door supervisor process, read from the process's own command line. This is what separates a wedged door of this tool, which a replacement must retire so the two never coexist, from an unrelated process that reuses the recorded pid, which must never be signalled. */
+    readonly isFrontDoorSupervisor: (pid: number) => boolean;
 }
 /**
  * Brings the front door up for this launch, or finds it serving, and registers this launcher pid in its session registry: the fact that keeps the door from idling out while this session lives, and the record that holds this launch's capability token. The same lock-and-poll coordination as headroom's and the old codex daemon's ensure: the exclusive-create start lock decides which of several concurrent launches spawns the one supervisor, everyone waits on state.json, and a lock whose holder died is removed and retried. Ready means state names a live supervisor and both listeners' ports, which the supervisor writes only after both have bound (and the provider listener has answered its own health probe).
@@ -11751,7 +11797,7 @@ interface RunFrontDoorSupervisorOptions {
     readonly tickLimit?: number;
 }
 /**
- * Runs the front-door supervisor: binds all three listeners (the HTTPS provider listener, the CONNECT surface and the plain-HTTP direct listener, each on its sticky port), records the serving state, and shuts down with an empty session registry, either at the first such tick after the executable it serves as has been replaced on disk (so an applied update reaches the door without waiting out the idle window) or after `idleShutdownMinutes` of it. Returns the exit code: 0 for either retirement, 1 for a fatal start failure.
+ * Runs the front-door supervisor: binds all three listeners (the HTTPS provider listener, the CONNECT surface and the plain-HTTP direct listener, each on its sticky port), records the serving state, and shuts down with an empty session registry, either at the first such tick after the executable it serves as has been replaced on disk (so an applied update reaches the door without waiting out the idle window) or after `idleShutdownMinutes` of it. A door whose state file comes to name another live supervisor is superseded: from then on it takes no new sessions, never writes the state file again, and exits as soon as the sessions it was serving have ended. Returns the exit code: 0 for any of these retirements, 1 for a fatal start failure.
  *
  * The listeners live in this process, so there is no child to keep alive: a crash of this process is a crash of every routed session's door at once, and recovery is the next launch's ensure spawning a replacement on the same sticky ports, which is exactly the failure model the issue asks to settle with tests. Keeping the headroom daemon alive is the headroom supervisor's job, not this one's; the two daemons idle out independently.
  */
@@ -11902,6 +11948,8 @@ interface Candidate {
     readonly headroom?: number;
     /** When an `ineligible` candidate can be used again. */
     readonly blockedUntilMs?: number;
+    /** When the exhausted plan window of a `pay-per-use` candidate that is only on extra usage because its plan ran out resets, so a launch can hold for it rather than spend. Absent for a candidate that bills by use with no plan allowance. */
+    readonly planReturnsAtMs?: number;
     readonly plan: PlanClass;
     /** True when the member's policy condition could not be decided and it is ranked last within its class, naming the missing fact in its reasons. */
     readonly policyDemoted?: boolean;
@@ -11918,6 +11966,11 @@ interface PoolRanking {
         readonly identity: string;
         readonly atMs: number;
     };
+    /** When the pick continues on extra usage only because its plan ran out, the identity and the instant its plan window resets: what a launch that would rather wait than spend sleeps until. Absent when the pick is on plan quota, bills by use with no plan, or no member can be picked. */
+    readonly planReturn?: {
+        readonly identity: string;
+        readonly atMs: number;
+    };
     /** The member a resumed or continued conversation started on but moved off, and why, when a launch that resumes could not keep it. One sentence for the launch decision line and `check`. */
     readonly movedOff?: {
         readonly identity: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-use",
-  "version": "9.12.0",
+  "version": "9.13.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>",