agent-shim 9.12.1 → 9.13.0

package/dist/types/index.d.ts

@@ -1332,8 +1332,8 @@ declare const HeadroomGlobalConfigSchema: z.ZodObject<{
     targetRatio: z.ZodOptional<z.ZodNumber>;
     ccr: z.ZodOptional<z.ZodEnum<{
         default: "default";
-        none: "none";
         lossless: "lossless";
+        none: "none";
     }>>;
     rolloutChannel: z.ZodOptional<z.ZodEnum<{
         beta: "beta";
@@ -1460,8 +1460,8 @@ declare const GlobalConfigSchema: z.ZodObject<{
         targetRatio: z.ZodOptional<z.ZodNumber>;
         ccr: z.ZodOptional<z.ZodEnum<{
             default: "default";
-            none: "none";
             lossless: "lossless";
+            none: "none";
         }>>;
         rolloutChannel: z.ZodOptional<z.ZodEnum<{
             beta: "beta";
@@ -3859,12 +3859,12 @@ declare const CheckReportJsonSchema: z.ZodObject<{
     identity: z.ZodObject<{
         name: z.ZodNullable<z.ZodString>;
         source: z.ZodEnum<{
+            env: "env";
+            none: "none";
             "config-dir-escape-hatch": "config-dir-escape-hatch";
             argv: "argv";
-            env: "env";
             "directory-pin": "directory-pin";
             "active-identity-file": "active-identity-file";
-            none: "none";
         }>;
     }, z.core.$strict>;
     pool: z.ZodOptional<z.ZodObject<{
@@ -3942,11 +3942,11 @@ declare const CheckReportJsonSchema: z.ZodObject<{
             "category-default": "category-default";
         }>;
         category: z.ZodNullable<z.ZodEnum<{
-            secret: "secret";
             runtime: "runtime";
             history: "history";
             knowledge: "knowledge";
             settings: "settings";
+            secret: "secret";
         }>>;
         rule: z.ZodOptional<z.ZodObject<{
             key: z.ZodString;
@@ -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>;
@@ -6440,9 +6476,9 @@ declare function createLifecycleApiRouter(deps: LifecycleApiDeps): {
             current: zod.ZodString;
             latest: zod.ZodString;
             action: zod.ZodEnum<{
+                updated: "updated";
                 current: "current";
                 available: "available";
-                updated: "updated";
             }>;
         }, zod_v4_core.$strict>, MergedErrorMap<$ErrorMap, TErrorMap>>;
     };
@@ -6689,12 +6725,12 @@ declare function createLaunchApiRouter(deps: LaunchApiDeps): {
             decision: zod.ZodObject<{
                 identity: zod.ZodOptional<zod.ZodString>;
                 identitySource: zod.ZodEnum<{
+                    env: "env";
+                    none: "none";
                     "config-dir-escape-hatch": "config-dir-escape-hatch";
                     argv: "argv";
-                    env: "env";
                     "directory-pin": "directory-pin";
                     "active-identity-file": "active-identity-file";
-                    none: "none";
                 }>;
                 pool: zod.ZodOptional<zod.ZodObject<{
                     name: zod.ZodString;
@@ -7080,12 +7116,12 @@ declare function createControlApiRouter(deps: ControlApiDeps): {
             identity: zod.ZodObject<{
                 name: zod.ZodNullable<zod.ZodString>;
                 source: zod.ZodEnum<{
+                    env: "env";
+                    none: "none";
                     "config-dir-escape-hatch": "config-dir-escape-hatch";
                     argv: "argv";
-                    env: "env";
                     "directory-pin": "directory-pin";
                     "active-identity-file": "active-identity-file";
-                    none: "none";
                 }>;
             }, zod_v4_core.$strict>;
             pool: zod.ZodOptional<zod.ZodObject<{
@@ -7163,11 +7199,11 @@ declare function createControlApiRouter(deps: ControlApiDeps): {
                     "category-default": "category-default";
                 }>;
                 category: zod.ZodNullable<zod.ZodEnum<{
-                    secret: "secret";
                     runtime: "runtime";
                     history: "history";
                     knowledge: "knowledge";
                     settings: "settings";
+                    secret: "secret";
                 }>>;
                 rule: zod.ZodOptional<zod.ZodObject<{
                     key: zod.ZodString;
@@ -7386,9 +7422,11 @@ declare function createControlApiRouter(deps: ControlApiDeps): {
                     "global-config": "global-config";
                     "config-profile": "config-profile";
                     identity: "identity";
+                    keychain: "keychain";
                     provider: "provider";
+                    headroom: "headroom";
+                    frontdoor: "frontdoor";
                     pool: "pool";
-                    keychain: "keychain";
                     "ambient-credential": "ambient-credential";
                     "binary-discovery": "binary-discovery";
                     "claude-shim": "claude-shim";
@@ -7398,7 +7436,6 @@ declare function createControlApiRouter(deps: ControlApiDeps): {
                     "directory-rules": "directory-rules";
                     "categories-local": "categories-local";
                     "active-identity": "active-identity";
-                    headroom: "headroom";
                 }>;
                 subject: zod.ZodOptional<zod.ZodString>;
                 severity: zod.ZodEnum<{
@@ -7519,12 +7556,12 @@ declare function createDoorApiRouter(deps: DoorApiDeps): {
             decision: zod.ZodObject<{
                 identity: zod.ZodOptional<zod.ZodString>;
                 identitySource: zod.ZodEnum<{
+                    env: "env";
+                    none: "none";
                     "config-dir-escape-hatch": "config-dir-escape-hatch";
                     argv: "argv";
-                    env: "env";
                     "directory-pin": "directory-pin";
                     "active-identity-file": "active-identity-file";
-                    none: "none";
                 }>;
                 pool: zod.ZodOptional<zod.ZodObject<{
                     name: zod.ZodString;
@@ -8861,9 +8898,9 @@ declare function createDoorApiRouter(deps: DoorApiDeps): {
             current: zod.ZodString;
             latest: zod.ZodString;
             action: zod.ZodEnum<{
+                updated: "updated";
                 current: "current";
                 available: "available";
-                updated: "updated";
             }>;
         }, zod_v4_core.$strict>, MergedErrorMap<$ErrorMap, TErrorMap>>;
     };
@@ -9062,12 +9099,12 @@ declare function createDoorApiRouter(deps: DoorApiDeps): {
             identity: zod.ZodObject<{
                 name: zod.ZodNullable<zod.ZodString>;
                 source: zod.ZodEnum<{
+                    env: "env";
+                    none: "none";
                     "config-dir-escape-hatch": "config-dir-escape-hatch";
                     argv: "argv";
-                    env: "env";
                     "directory-pin": "directory-pin";
                     "active-identity-file": "active-identity-file";
-                    none: "none";
                 }>;
             }, zod_v4_core.$strict>;
             pool: zod.ZodOptional<zod.ZodObject<{
@@ -9145,11 +9182,11 @@ declare function createDoorApiRouter(deps: DoorApiDeps): {
                     "category-default": "category-default";
                 }>;
                 category: zod.ZodNullable<zod.ZodEnum<{
-                    secret: "secret";
                     runtime: "runtime";
                     history: "history";
                     knowledge: "knowledge";
                     settings: "settings";
+                    secret: "secret";
                 }>>;
                 rule: zod.ZodOptional<zod.ZodObject<{
                     key: zod.ZodString;
@@ -9368,9 +9405,11 @@ declare function createDoorApiRouter(deps: DoorApiDeps): {
                     "global-config": "global-config";
                     "config-profile": "config-profile";
                     identity: "identity";
+                    keychain: "keychain";
                     provider: "provider";
+                    headroom: "headroom";
+                    frontdoor: "frontdoor";
                     pool: "pool";
-                    keychain: "keychain";
                     "ambient-credential": "ambient-credential";
                     "binary-discovery": "binary-discovery";
                     "claude-shim": "claude-shim";
@@ -9380,7 +9419,6 @@ declare function createDoorApiRouter(deps: DoorApiDeps): {
                     "directory-rules": "directory-rules";
                     "categories-local": "categories-local";
                     "active-identity": "active-identity";
-                    headroom: "headroom";
                 }>;
                 subject: zod.ZodOptional<zod.ZodString>;
                 severity: zod.ZodEnum<{
@@ -11174,9 +11212,11 @@ declare const DoctorFindingSchema: z.ZodObject<{
         "global-config": "global-config";
         "config-profile": "config-profile";
         identity: "identity";
+        keychain: "keychain";
         provider: "provider";
+        headroom: "headroom";
+        frontdoor: "frontdoor";
         pool: "pool";
-        keychain: "keychain";
         "ambient-credential": "ambient-credential";
         "binary-discovery": "binary-discovery";
         "claude-shim": "claude-shim";
@@ -11186,7 +11226,6 @@ declare const DoctorFindingSchema: z.ZodObject<{
         "directory-rules": "directory-rules";
         "categories-local": "categories-local";
         "active-identity": "active-identity";
-        headroom: "headroom";
     }>;
     subject: z.ZodOptional<z.ZodString>;
     severity: z.ZodEnum<{
@@ -11204,9 +11243,11 @@ declare const DoctorRunOutputSchema: z.ZodObject<{
             "global-config": "global-config";
             "config-profile": "config-profile";
             identity: "identity";
+            keychain: "keychain";
             provider: "provider";
+            headroom: "headroom";
+            frontdoor: "frontdoor";
             pool: "pool";
-            keychain: "keychain";
             "ambient-credential": "ambient-credential";
             "binary-discovery": "binary-discovery";
             "claude-shim": "claude-shim";
@@ -11216,7 +11257,6 @@ declare const DoctorRunOutputSchema: z.ZodObject<{
             "directory-rules": "directory-rules";
             "categories-local": "categories-local";
             "active-identity": "active-identity";
-            headroom: "headroom";
         }>;
         subject: z.ZodOptional<z.ZodString>;
         severity: z.ZodEnum<{
@@ -11237,9 +11277,9 @@ declare const UpdateCheckOutputSchema: z.ZodObject<{
     current: z.ZodString;
     latest: z.ZodString;
     action: z.ZodEnum<{
+        updated: "updated";
         current: "current";
         available: "available";
-        updated: "updated";
     }>;
 }, z.core.$strict>;
 /** The Sign in with ChatGPT login's state as `codex status` reports it: no sign-in yet, signed in (with who, whether the plan scope was granted, and when the access token lapses), or a file that cannot be read. */
@@ -11289,12 +11329,12 @@ declare const LaunchResolveOutputSchema: z.ZodObject<{
     decision: z.ZodObject<{
         identity: z.ZodOptional<z.ZodString>;
         identitySource: z.ZodEnum<{
+            env: "env";
+            none: "none";
             "config-dir-escape-hatch": "config-dir-escape-hatch";
             argv: "argv";
-            env: "env";
             "directory-pin": "directory-pin";
             "active-identity-file": "active-identity-file";
-            none: "none";
         }>;
         pool: z.ZodOptional<z.ZodObject<{
             name: z.ZodString;
@@ -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;
@@ -11753,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.
  */
@@ -11904,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;
@@ -11920,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": "agent-shim",
-  "version": "9.12.1",
+  "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>",