agl 40.5.0 → 40.6.0

package/ts/classes.proxydaemon.ts

@@ -3,12 +3,13 @@ import { commitinfo } from './00_commitinfo_data.js';
 import type { IAuthoritySocketPaths } from './classes.authorityclient.js';
 import { InferenceService } from './classes.inferenceservice.js';
 import { inferenceGatewayCredentialDigest, type IInferenceGatewayGrant, type IInferenceGatewayLease,
-  type IInferenceGatewayLimits } from './classes.inferencegateway.js';
+  type IInferenceGatewayLimits, type TInferenceGatewayRoute } from './classes.inferencegateway.js';
 import { InferenceRoutingError, type IInferenceRoutingPolicy } from './classes.inferencerouter.js';
-import { proxyClientNamePattern, type TInferenceProvider,
+import { aglProxyConfinedClient, aglProxyConfinedOrigin, proxyClientNamePattern, type TInferenceProvider,
   type TProxyCredentialDelivery } from './functions.proxycontract.js';
-import { AglProxyControlRefusal, AglProxyControlServer, type IAglProxyConnection, type IAglProxyStatus,
-  type IReq_AglProxyCatalog, type TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
+import { AglProxyControlRefusal, AglProxyControlServer, type IAglProxyConfinedGrant, type IAglProxyConnection,
+  type IAglProxyStatus, type IReq_AglProxyCatalog, type IReq_AglProxyReclaim,
+  type TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
 import { ProxyStore, type IProxySecretCodec } from './classes.proxystore.js';
 import type { InferenceUsageStore } from './classes.inferenceusage.js';
 import { prepareProxyCredentialDirectory, proxyCredentialFile, removeProxyCredentialFile,
@@ -27,6 +28,11 @@ export interface IAglProxyDaemonOptions {
   limits?: IInferenceGatewayLimits;
   /** How long a lease kept across a restart waits for its holder; `proxyLeaseReclaimWindowMs` unless a test shortens it. */
   leaseReclaimWindowMs?: number;
+  /**
+   * The confined listener's socket, alone in its directory (`IAGLHomePaths.proxyConfinedSocket`); unset, the proxy has no
+   * confined listener and refuses confined runs.
+   */
+  confinedSocketPath?: string;
 }
 
 /**
@@ -45,9 +51,19 @@ const catalogRefusal = (errorArg: unknown): AglProxyControlRefusal => new AglPro
   errorArg instanceof InferenceRoutingError ? errorArg.code : undefined,
 );
 
+/** The policy of every confined run's credential: the Claude pool, unrestricted, as Claude Code's own lease. */
+const confinedPolicy: IInferenceRoutingPolicy = Object.freeze({ provider: 'anthropic' });
+
+/** A confined run's id, as the operator names it: the first 12 hex characters of its credential's digest. */
+const confinedRunId = (digestArg: string): string => digestArg.slice(0, 12);
+
 /** A lease the proxy serves: held by the control connection it was issued or reclaimed on, or awaiting its holder. */
 interface IHeldLease {
   grant: IInferenceGatewayGrant;
+  route: TInferenceGatewayRoute;
+  createdAt: Date;
+  /** The connection the lease lives as long as, while a holder has it. */
+  holder?: IAglProxyConnection;
   /** Set while the lease, kept across a restart, waits for its holder; it ends when this timer fires. */
   reclaimTimer?: ReturnType<typeof setTimeout>;
 }
@@ -61,9 +77,10 @@ interface IClientLease {
 }
 
 /**
- * The permanent proxy: one loopback listener, one credential per client, and a private control socket that hands
- * a client its credential and a child a lease. The control socket is claimed first; it is the proof that no other
- * proxy runs for this AGL home, so the proxy's database is opened by this process alone.
+ * The permanent proxy: one loopback listener, one credential per client, a confined listener for Claude Code in
+ * containers, and a private control socket that hands a client its credential, a child a lease and a confined run its
+ * credential. The control socket is claimed first; it is the proof that no other proxy runs for this AGL home, so the
+ * proxy's database is opened by this process alone.
  */
 export class AglProxyDaemon {
   private readonly control: AglProxyControlServer;
@@ -107,7 +124,8 @@ export class AglProxyDaemon {
       port: this.options.port, signatureKey: identity.signatureKey, affinity: this.store.affinity(),
       placements: this.store.placements(), usageLedger: this.usage, spendStore: this.store.spend(),
       ...(this.options.providerFetch ? { providerFetch: this.options.providerFetch } : {}),
-      ...(this.options.limits ? { limits: this.options.limits } : {}) });
+      ...(this.options.limits ? { limits: this.options.limits } : {}),
+      ...(this.options.confinedSocketPath === undefined ? {} : { confinedSocketPath: this.options.confinedSocketPath }) });
     const baseUrl = await this.service.start(signal);
     const deliveries = new Set(await this.store.fileDeliveries());
     for (const credential of await this.store.credentials()) {
@@ -128,6 +146,8 @@ export class AglProxyDaemon {
       catalog: (requestArg, connectionArg) => this.catalog(requestArg, connectionArg),
       lease: (requestArg, connectionArg) => this.lease(requestArg.policy, requestArg.client, connectionArg),
       reclaim: async (requestArg, connectionArg) => this.reclaim(requestArg.token, connectionArg),
+      confined: (connectionArg) => this.confined(connectionArg),
+      confinedEnd: async (requestArg) => this.confinedEnd(requestArg.id),
       usage: async (requestArg, connectionArg) => 'since' in requestArg ? this.usage!.changes(requestArg)
         : await this.usage!.snapshot(requestArg, connectionArg.signal),
     });
@@ -145,7 +165,11 @@ export class AglProxyDaemon {
       }),
       leases: status.leases, inFlight: status.inFlight, limits: status.limits, authority: status.authority,
       accounts: status.accounts, usageObservations: status.usageObservations, nextPlacement: status.nextPlacement,
-      recentPlacements: status.recentPlacements,
+      recentPlacements: status.recentPlacements, confinedSocketPath: this.options.confinedSocketPath ?? null,
+      confinedRuns: [...this.leases].filter(([, heldArg]) => heldArg.route === 'confined')
+        .sort(([, left], [, right]) => left.createdAt.getTime() - right.createdAt.getTime())
+        .map(([digestArg, heldArg]) => ({ id: confinedRunId(digestArg), createdAt: heldArg.createdAt.toISOString(),
+          held: heldArg.reclaimTimer === undefined })),
     };
   }
 
@@ -265,11 +289,11 @@ export class AglProxyDaemon {
     // The lease continues the sessions of the client it is taken for (see `IReq_AglProxyLease`).
     try { lease = await service.open(policyArg, { sessionScope: clientArg }); }
     catch (errorArg) { throw new AglProxyControlRefusal(errorArg instanceof Error ? errorArg.message : 'The lease could not be opened.'); }
-    const held: IHeldLease = { grant: lease };
+    const held: IHeldLease = { grant: lease, route: 'loopback', createdAt: new Date(), holder: connectionArg };
     this.leases.set(lease.digest, held);
     try {
       await this.trackLeaseWrite(this.store!.recordLease({ digest: lease.digest, client: clientArg, policy: policyArg,
-        createdAt: new Date() }));
+        createdAt: held.createdAt, route: 'loopback' }));
     } catch (errorArg) {
       this.endLease(lease.digest, held);
       throw new AglProxyControlRefusal(errorArg instanceof Error ? errorArg.message : 'The lease could not be recorded.');
@@ -294,7 +318,50 @@ export class AglProxyDaemon {
    * an unknown credential from an expired or a held one. The credential is looked up by its SHA-256 digest: a match
    * proves the caller holds the credential the lease was issued with.
    */
-  private async reclaim(tokenArg: string, connectionArg: IAglProxyConnection): Promise<{ baseUrl: string }> {
+  /**
+   * A confined run's credential (see `IReq_AglProxyConfined`): a lease of the Claude pool that continues the confined
+   * client's sessions and is accepted on the confined listener alone. It is kept, as its digest, before it is handed out,
+   * and ends when its holder's connection closes or the operator ends it (`confinedEnd`). No model list is read for it:
+   * Claude Code reads the pool's models through the confined listener, and the pool is judged at each request.
+   */
+  private async confined(connectionArg: IAglProxyConnection): Promise<IAglProxyConfinedGrant> {
+    const socketPath = this.options.confinedSocketPath;
+    if (socketPath === undefined) throw new AglProxyControlRefusal('This AGL proxy has no confined listener.');
+    let lease: IInferenceGatewayLease;
+    try { lease = await this.service!.open(confinedPolicy, { sessionScope: aglProxyConfinedClient, route: 'confined' }); }
+    catch (errorArg) {
+      throw new AglProxyControlRefusal(errorArg instanceof Error ? errorArg.message : 'The confined credential could not be issued.');
+    }
+    const held: IHeldLease = { grant: lease, route: 'confined', createdAt: new Date(), holder: connectionArg };
+    this.leases.set(lease.digest, held);
+    try {
+      await this.trackLeaseWrite(this.store!.recordLease({ digest: lease.digest, client: aglProxyConfinedClient,
+        policy: confinedPolicy, createdAt: held.createdAt, route: 'confined' }));
+    } catch (errorArg) {
+      this.endLease(lease.digest, held);
+      throw new AglProxyControlRefusal(errorArg instanceof Error ? errorArg.message : 'The confined credential could not be recorded.');
+    }
+    connectionArg.onClose(() => this.endLease(lease.digest, held));
+    return { id: confinedRunId(lease.digest), token: lease.token, socketPath, baseUrl: aglProxyConfinedOrigin };
+  }
+
+  /**
+   * Ends a confined run's credential at once, held or waiting for its holder: the gateway refuses it from now on, and
+   * its requests in flight end. The holder's connection is closed with the reason, so it stops its container instead of
+   * taking the credential back.
+   */
+  private confinedEnd(idArg: string): { id: string } {
+    const matches = [...this.leases].filter(([digestArg, heldArg]) => heldArg.route === 'confined'
+      && confinedRunId(digestArg) === idArg);
+    if (matches.length !== 1) throw new AglProxyControlRefusal(`The AGL proxy serves no confined run ${idArg}.`);
+    const [[digest, held]] = matches;
+    const holder = held.holder;
+    this.endLease(digest, held);
+    holder?.end(`The operator ended confined run ${idArg} (\`agl proxy confined end\`).`);
+    return { id: idArg };
+  }
+
+  private async reclaim(tokenArg: string, connectionArg: IAglProxyConnection): Promise<IReq_AglProxyReclaim['response']> {
     const digest = inferenceGatewayCredentialDigest(tokenArg);
     const held = this.leases.get(digest);
     if (!held?.reclaimTimer || connectionArg.signal.aborted) {
@@ -309,8 +376,10 @@ export class AglProxyDaemon {
       this.endLease(digest, held);
       throw new AglProxyControlRefusal(errorArg instanceof Error ? errorArg.message : 'The lease could not be taken back.');
     }
+    held.holder = connectionArg;
     connectionArg.onClose(() => this.endLease(digest, held));
-    return { baseUrl: held.grant.baseUrl };
+    return held.route === 'confined' ? { baseUrl: aglProxyConfinedOrigin, socketPath: this.options.confinedSocketPath! }
+      : { baseUrl: held.grant.baseUrl };
   }
 
   /**
@@ -338,14 +407,14 @@ export class AglProxyDaemon {
       let grant: IInferenceGatewayGrant;
       try {
         if (!kept.orphanedAt) await this.store!.recordLeaseOrphaned(kept.digest, orphanedAt);
-        grant = await service.restore(kept.policy, { digest: kept.digest, sessionScope: kept.client });
+        grant = await service.restore(kept.policy, { digest: kept.digest, sessionScope: kept.client, route: kept.route });
       } catch (errorArg) {
         // A lease the gateway no longer admits (its policy or limits changed) cannot be served; it ends here.
         this.reportLease(kept.digest, 'is not served again', errorArg);
         await this.forgetLease(kept.digest);
         continue;
       }
-      const held: IHeldLease = { grant };
+      const held: IHeldLease = { grant, route: kept.route, createdAt: kept.createdAt };
       held.reclaimTimer = setTimeout(() => this.endLease(kept.digest, held), Math.max(0, deadline - Date.now()));
       this.leases.set(kept.digest, held);
     }
@@ -358,6 +427,7 @@ export class AglProxyDaemon {
   private endLease(digestArg: string, heldArg: IHeldLease): void {
     if (this.abort.signal.aborted || this.leases.get(digestArg) !== heldArg) return;
     clearTimeout(heldArg.reclaimTimer);
+    heldArg.holder = undefined;
     this.leases.delete(digestArg);
     heldArg.grant.close();
     void this.forgetLease(digestArg);

package/ts/classes.proxyleaseholder.ts

@@ -1,6 +1,6 @@
 import * as plugins from './plugins.js';
 import type { IInferenceRoutingPolicy } from './classes.inferencerouter.js';
-import type { TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
+import type { IReq_AglProxyReclaim, TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
 import { AglProxyControlClient, AglProxyRefusedError, type IAglProxyLeaseConnection } from './classes.proxycontrolclient.js';
 
 /** The delays between attempts to take a lease back from a restarting proxy; the last one repeats. */
@@ -22,33 +22,30 @@ export class AglProxyLeaseLostError extends Error {
   }
 }
 
-export interface IAglProxyLeaseHolderOptions {
+/** How a holder reaches its proxy and how long it keeps trying to take its lease back. */
+export interface IAglProxyHolderOptions {
   socketPath: string;
+  reclaimDelaysMs?: readonly number[];
+  reclaimDeadlineMs?: number;
+}
+
+export interface IAglProxyLeaseHolderOptions extends IAglProxyHolderOptions {
   policy: IInferenceRoutingPolicy;
   /** The proxy client whose sessions the lease continues (see `IReq_AglProxyLease`). */
   client: string;
-  reclaimDelaysMs?: readonly number[];
-  reclaimDeadlineMs?: number;
 }
 
 /**
- * A proxy lease its holder keeps for as long as it needs it. The lease lives as long as the holder's control
- * connection; when that connection closes without the holder closing it -- the proxy stopped or restarted -- the
- * holder reconnects with a bounded backoff and takes the same lease back by its credential, so the child configured
- * with that credential keeps working. A lease the proxy refuses to hand back, or a proxy that does not come back in
- * time, is lost for good: `lost` settles with the reason, for the holder to show rather than leave its child failing.
+ * A proxy credential its holder keeps for as long as it needs it: a lease, or a confined run's credential. It lives as
+ * long as the holder's control connection; when that connection closes without the holder closing it -- the proxy
+ * stopped or restarted -- the holder reconnects with a bounded backoff and takes the same credential back, so the child
+ * configured with it keeps working. A credential the proxy refuses to hand back, one the proxy ended itself (it says
+ * why), or a proxy that does not come back in time, is lost for good: `lost` settles with the reason, for the holder to
+ * show rather than leave its child failing.
  */
-export class AglProxyLeaseHolder {
-  /** Takes a new lease of the proxy on `socketPathArg`. */
-  public static async take(optionsArg: IAglProxyLeaseHolderOptions, signalArg: AbortSignal): Promise<AglProxyLeaseHolder> {
-    const control = new AglProxyControlClient(optionsArg.socketPath);
-    const lease = await control.lease(optionsArg.policy, optionsArg.client, signalArg);
-    return new AglProxyLeaseHolder(control, lease, optionsArg);
-  }
-
+class AglProxyHeldCredential {
   public readonly baseUrl: string;
   public readonly token: string;
-  public readonly catalog: TAglProxyLeaseCatalog;
   /** Settles with the reason once the lease is lost for good; never for a lease its holder closes. */
   public readonly lost: Promise<AglProxyLeaseLostError>;
   private stateValue: TAglProxyLeaseState = 'held';
@@ -56,18 +53,23 @@ export class AglProxyLeaseHolder {
   private readonly abort = new AbortController();
   private readonly resolveLost: (errorArg: AglProxyLeaseLostError) => void;
 
-  private constructor(
+  protected constructor(
     private readonly control: AglProxyControlClient,
-    leaseArg: { baseUrl: string; token: string; catalog: TAglProxyLeaseCatalog } & IAglProxyLeaseConnection,
-    private readonly options: IAglProxyLeaseHolderOptions,
+    issuedArg: { baseUrl: string; token: string } & IAglProxyLeaseConnection,
+    private readonly options: IAglProxyHolderOptions,
   ) {
-    this.baseUrl = leaseArg.baseUrl;
-    this.token = leaseArg.token;
-    this.catalog = leaseArg.catalog;
+    this.baseUrl = issuedArg.baseUrl;
+    this.token = issuedArg.token;
     const lost = Promise.withResolvers<AglProxyLeaseLostError>();
     this.lost = lost.promise;
     this.resolveLost = lost.resolve;
-    this.watch(leaseArg);
+    this.watch(issuedArg);
+  }
+
+  /** Why a credential taken back cannot continue where its child was configured, or `undefined` when it can. */
+  protected relocation(reclaimedArg: IReq_AglProxyReclaim['response']): string | undefined {
+    return reclaimedArg.baseUrl === this.baseUrl ? undefined
+      : `The AGL proxy restarted at ${reclaimedArg.baseUrl} instead of ${this.baseUrl}, where this lease is configured.`;
   }
 
   public get state(): TAglProxyLeaseState {
@@ -84,8 +86,10 @@ export class AglProxyLeaseHolder {
 
   private watch(connectionArg: IAglProxyLeaseConnection): void {
     this.connection = connectionArg;
-    void connectionArg.closed.then(() => {
+    void connectionArg.closed.then((endedArg) => {
       if (this.connection !== connectionArg || this.stateValue !== 'held') return;
+      // The proxy ended the credential itself and said why: there is nothing to take back.
+      if (endedArg !== undefined) { this.lose(endedArg); return; }
       this.stateValue = 'reclaiming';
       void this.reclaim();
     });
@@ -109,9 +113,10 @@ export class AglProxyLeaseHolder {
         const reclaimed = await this.control.reclaim(this.token,
           AbortSignal.any([this.abort.signal, AbortSignal.timeout(Math.max(1, deadline - Date.now()))]));
         if (this.stateValue !== 'reclaiming') { reclaimed.close(); return; }
-        if (reclaimed.baseUrl !== this.baseUrl) {
+        const relocation = this.relocation(reclaimed);
+        if (relocation !== undefined) {
           reclaimed.close();
-          this.lose(`The AGL proxy restarted at ${reclaimed.baseUrl} instead of ${this.baseUrl}, where this lease is configured.`);
+          this.lose(relocation);
           return;
         }
         this.stateValue = 'held';
@@ -134,3 +139,54 @@ export class AglProxyLeaseHolder {
     this.resolveLost(new AglProxyLeaseLostError(messageArg));
   }
 }
+
+/** A proxy lease for one child, with the pool's models as the proxy read them when it issued the lease. */
+export class AglProxyLeaseHolder extends AglProxyHeldCredential {
+  /** Takes a new lease of the proxy on `socketPathArg`. */
+  public static async take(optionsArg: IAglProxyLeaseHolderOptions, signalArg: AbortSignal): Promise<AglProxyLeaseHolder> {
+    const control = new AglProxyControlClient(optionsArg.socketPath);
+    const lease = await control.lease(optionsArg.policy, optionsArg.client, signalArg);
+    return new AglProxyLeaseHolder(control, lease, optionsArg);
+  }
+
+  public readonly catalog: TAglProxyLeaseCatalog;
+
+  private constructor(controlArg: AglProxyControlClient,
+    leaseArg: { baseUrl: string; token: string; catalog: TAglProxyLeaseCatalog } & IAglProxyLeaseConnection,
+    optionsArg: IAglProxyLeaseHolderOptions) {
+    super(controlArg, leaseArg, optionsArg);
+    this.catalog = leaseArg.catalog;
+  }
+}
+
+/**
+ * A confined run's credential (see `IReq_AglProxyConfined`), held for as long as its container runs. It is configured
+ * with the confined listener's socket, so one taken back on another socket cannot continue.
+ */
+export class AglProxyConfinedHolder extends AglProxyHeldCredential {
+  /** Takes a new confined run's credential of the proxy on `optionsArg.socketPath`, its control socket. */
+  public static async take(optionsArg: IAglProxyHolderOptions, signalArg: AbortSignal): Promise<AglProxyConfinedHolder> {
+    const control = new AglProxyControlClient(optionsArg.socketPath);
+    const grant = await control.confined(signalArg);
+    return new AglProxyConfinedHolder(control, grant, optionsArg);
+  }
+
+  /** The run's id, as `agl proxy confined end` and `agl proxy status` name it. */
+  public readonly id: string;
+  /** The confined listener's socket, on the host. */
+  public readonly confinedSocketPath: string;
+
+  private constructor(controlArg: AglProxyControlClient,
+    grantArg: { id: string; baseUrl: string; token: string; socketPath: string } & IAglProxyLeaseConnection,
+    optionsArg: IAglProxyHolderOptions) {
+    super(controlArg, grantArg, optionsArg);
+    this.id = grantArg.id;
+    this.confinedSocketPath = grantArg.socketPath;
+  }
+
+  protected override relocation(reclaimedArg: IReq_AglProxyReclaim['response']): string | undefined {
+    return reclaimedArg.socketPath === this.confinedSocketPath ? undefined
+      : `The AGL proxy restarted with its confined listener at ${reclaimedArg.socketPath ?? 'none'} instead of `
+        + `${this.confinedSocketPath}, which this run's container has mounted.`;
+  }
+}

package/ts/classes.proxystore.ts

@@ -5,9 +5,10 @@ import { InferenceSessionModel } from './classes.inferencesession.js';
 import { InferencePlacementModel, InferencePlacementStore } from './classes.inferenceplacement.js';
 import { InferenceUsageModel, InferenceUsageStore } from './classes.inferenceusage.js';
 import { InferenceSpendModel, InferenceSpendStore } from './classes.inferencespend.js';
-import { assertInferenceRoutingPolicy } from './classes.inferencegateway.js';
+import { assertInferenceRoutingPolicy, type TInferenceGatewayRoute } from './classes.inferencegateway.js';
 import type { IInferenceRoutingPolicy } from './classes.inferencerouter.js';
 import {
+  aglProxyConfinedClient,
   defaultProxyClientProvider,
   defaultProxyClients,
   inferenceProviders,
@@ -149,6 +150,11 @@ export interface IProxyLeaseDocument {
    * until its holder takes it back, which removes it. Absent while a holder has the lease.
    */
   orphanedAt?: Date;
+  /**
+   * `confined` for a confined run's credential, accepted on the confined listener alone, with the Claude pool's policy
+   * and the confined client's sessions; absent for a lease of the loopback listener.
+   */
+  route?: 'confined';
 }
 
 const isDate = (valueArg: unknown): valueArg is Date => valueArg instanceof Date && Number.isFinite(valueArg.getTime());
@@ -171,10 +177,12 @@ const assertLeasePolicy = (valueArg: unknown): IProxyLeasePolicyDocument => {
 const assertLease: (valueArg: unknown) => asserts valueArg is IProxyLeaseDocument = (valueArg) => {
   const value = valueArg as Partial<IProxyLeaseDocument> | null;
   if (!value || typeof value !== 'object'
-    || Object.keys(value).length !== (Object.hasOwn(value, 'orphanedAt') ? 5 : 4)
+    || Object.keys(value).length !== 4 + Number(Object.hasOwn(value, 'orphanedAt')) + Number(Object.hasOwn(value, 'route'))
     || typeof value.id !== 'string' || !/^[a-f0-9]{64}$/.test(value.id)
     || typeof value.client !== 'string' || !proxyClientNamePattern.test(value.client)
-    || !isDate(value.createdAt) || (Object.hasOwn(value, 'orphanedAt') && !isDate(value.orphanedAt))) {
+    || !isDate(value.createdAt) || (Object.hasOwn(value, 'orphanedAt') && !isDate(value.orphanedAt))
+    || (Object.hasOwn(value, 'route') && (value.route !== 'confined' || value.client !== aglProxyConfinedClient
+      || JSON.stringify(value.policy) !== JSON.stringify({ provider: 'anthropic' })))) {
     throw new Error('Invalid proxy lease.');
   }
   assertLeasePolicy(value.policy);
@@ -189,6 +197,7 @@ export class ProxyLeaseModel extends plugins.nosqldb.SmartDataDbDoc<ProxyLeaseMo
   @plugins.nosqldb.svDb() public policy!: IProxyLeasePolicyDocument;
   @plugins.nosqldb.svDb() public createdAt!: Date;
   @plugins.nosqldb.svDb() public orphanedAt?: Date;
+  @plugins.nosqldb.svDb() public route?: 'confined';
 }
 
 const proxyModels = [ProxyIdentityModel, ProxyClientModel, ProxyDeliveryModel, ProxyLeaseModel, InferenceAffinityModel,
@@ -226,6 +235,8 @@ export interface IProxyLease {
   createdAt: Date;
   /** See `IProxyLeaseDocument.orphanedAt`. */
   orphanedAt?: Date;
+  /** The listener the lease's credential is accepted on; see `IProxyLeaseDocument.route`. */
+  route: TInferenceGatewayRoute;
 }
 
 /**
@@ -381,7 +392,7 @@ export class ProxyStore {
     };
     if (await ProxyLeaseModel.exact.count({}) >= maximumProxyLeases) throw new Error('The proxy keeps at most 128 leases.');
     const inserted = await ProxyLeaseModel.exact.insert({ id: leaseArg.digest, client: leaseArg.client, policy,
-      createdAt: new Date(leaseArg.createdAt.getTime()) });
+      createdAt: new Date(leaseArg.createdAt.getTime()), ...(leaseArg.route === 'confined' ? { route: 'confined' as const } : {}) });
     if (inserted.status !== 'inserted' && inserted.status !== 'already_committed') throw new Error('The proxy lease could not be recorded.');
   }
 
@@ -391,7 +402,7 @@ export class ProxyStore {
     return stored.map((entryArg) => {
       const lease = ProxyLeaseModel.exact.toPersisted(entryArg);
       return { digest: lease.id, client: lease.client, policy: lease.policy, createdAt: lease.createdAt,
-        ...(lease.orphanedAt === undefined ? {} : { orphanedAt: lease.orphanedAt }) };
+        route: lease.route ?? 'loopback', ...(lease.orphanedAt === undefined ? {} : { orphanedAt: lease.orphanedAt }) };
     });
   }
 

package/ts/classes.workercallerbindings.ts

@@ -0,0 +1,147 @@
+import * as plugins from './plugins.js';
+import type { IWorkerBridgeCommand, IWorkerProcessSnapshot } from './functions.workerprocessproof.js';
+
+/** The Claude process a kept binding was last proved against: its PID, start and the digest of its whole snapshot. */
+export interface IWorkerCallerBindingProcess {
+  pid: number;
+  startTicks: string;
+  snapshotDigest: string;
+}
+
+/**
+ * What the controller keeps of a fleet Claude worker's current caller launch, so a restarted controller proves the
+ * worker's bridge again instead of forgetting it. Never a credential, never the launch id or generation themselves:
+ * the overlay holds those, and a bridge presents them; the record keeps their digests to find and check the launch.
+ */
+export interface IWorkerCallerBindingDocument {
+  /** The fleet worker's id: a worker keeps one binding, its current launch's. */
+  id: string;
+  projectId: string;
+  harnessId: 'claude';
+  /** SHA-256 digests (base64url) of the launch id and of its generation. */
+  launchDigest: string;
+  generationDigest: string;
+  /** The bridge command approved when the launch was prepared, and the Claude Code executable it was proved against. */
+  command: IWorkerBridgeCommand;
+  claudeExecutable: string;
+  revision: number;
+  /** Once bound: the background job, its session, and the job's process when one was proved. */
+  binding?: { nativeSessionId: string; jobId: string; process?: IWorkerCallerBindingProcess };
+  updateId: string;
+}
+export type TWorkerCallerBindingRecord = Omit<IWorkerCallerBindingDocument, 'updateId'>;
+
+/** Where the controller keeps the bindings of fleet Claude launches. */
+export interface IWorkerCallerBindingStore {
+  /** The binding kept for the launch whose id has the digest `launchDigestArg`. */
+  find(launchDigestArg: string): Promise<TWorkerCallerBindingRecord | undefined>;
+  /** Keeps `recordArg` as its worker's binding; another launch's binding of the worker is replaced. */
+  save(recordArg: TWorkerCallerBindingRecord): Promise<void>;
+  /** Deletes the worker's binding; with `launchDigestArg`, only while it is that launch's. */
+  delete(workerIdArg: string, launchDigestArg?: string): Promise<void>;
+}
+
+export const workerCallerDigest = (valueArg: string): string => plugins.crypto.createHash('sha256').update(valueArg).digest('base64url');
+export const workerProcessSnapshotDigest = (snapshotArg: IWorkerProcessSnapshot): string => workerCallerDigest(JSON.stringify([
+  snapshotArg.pid, snapshotArg.parentPid, snapshotArg.startTicks, snapshotArg.executable, snapshotArg.arguments]));
+
+const digest = plugins.z.string().regex(/^[A-Za-z0-9_-]{43}$/u);
+const absolutePath = plugins.z.string().min(2).max(4096).refine((valueArg) => plugins.path.isAbsolute(valueArg) && !valueArg.includes('\0'));
+const documentSchema = plugins.z.object({
+  id: plugins.z.string().min(3).max(1024), projectId: plugins.z.string().regex(/^[A-Za-z0-9_.:-]{1,256}$/u),
+  harnessId: plugins.z.literal('claude'), launchDigest: digest, generationDigest: digest,
+  command: plugins.z.object({ executable: absolutePath, entry: absolutePath,
+    arguments: plugins.z.array(plugins.z.string().max(4096)).max(64) }).strict(),
+  claudeExecutable: absolutePath, revision: plugins.z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  binding: plugins.z.object({ nativeSessionId: plugins.z.string().uuid(), jobId: plugins.z.string().regex(/^[A-Za-z0-9_.:-]{1,256}$/u),
+    process: plugins.z.object({ pid: plugins.z.number().int().min(2), startTicks: plugins.z.string().regex(/^\d{1,32}$/u),
+      snapshotDigest: digest }).strict().optional() }).strict().optional(),
+  updateId: plugins.z.string().uuid(),
+}).strict();
+
+@plugins.nosqldb.namedIndex({ name: 'worker_caller_launch', key: { launchDigest: 1 }, options: { unique: true } })
+@plugins.nosqldb.managed({ collectionName: 'agl_worker_caller_bindings' })
+@plugins.nosqldb.exactPersistence({ assertDocument: (input: unknown) => {
+  const doc = documentSchema.parse(input);
+  if (!doc.id.startsWith(`${doc.projectId}:`)) throw new Error('Worker caller binding identity mismatch.');
+  if (doc.binding && doc.revision < 1) throw new Error('Worker caller binding revision mismatch.');
+} })
+export class WorkerCallerBindingModel extends plugins.nosqldb.SmartDataDbDoc<WorkerCallerBindingModel, IWorkerCallerBindingDocument> {
+  declare static exact: plugins.nosqldb.TExact<WorkerCallerBindingModel>;
+  @plugins.nosqldb.unI() public id!: string;
+  @plugins.nosqldb.svDb() public projectId!: string;
+  @plugins.nosqldb.svDb() public harnessId!: 'claude';
+  @plugins.nosqldb.svDb() public launchDigest!: string;
+  @plugins.nosqldb.svDb() public generationDigest!: string;
+  @plugins.nosqldb.svDb() public command!: IWorkerBridgeCommand;
+  @plugins.nosqldb.svDb() public claudeExecutable!: string;
+  @plugins.nosqldb.svDb() public revision!: number;
+  @plugins.nosqldb.svDb() public binding?: IWorkerCallerBindingDocument['binding'];
+  @plugins.nosqldb.svDb() public updateId!: string;
+}
+
+const ambiguous = (errorArg: unknown): boolean => errorArg instanceof plugins.nosqldb.SmartdataExactPersistenceError && errorArg.code === 'ambiguous_write';
+const record = (documentArg: IWorkerCallerBindingDocument): TWorkerCallerBindingRecord => {
+  const { updateId: _updateId, ...rest } = structuredClone(documentArg);
+  return rest;
+};
+
+/** The kept bindings in the controller's store; the auth store owns the model manager and database. Writes run one at a time. */
+export class WorkerCallerBindingStore implements IWorkerCallerBindingStore {
+  private mutationTail: Promise<void> = Promise.resolve();
+
+  public async find(launchDigestArg: string): Promise<TWorkerCallerBindingRecord | undefined> {
+    const stored = await WorkerCallerBindingModel.exact.findStoredOne({ launchDigest: launchDigestArg });
+    return stored ? record(WorkerCallerBindingModel.exact.toPersisted(stored)) : undefined;
+  }
+
+  public save(recordArg: TWorkerCallerBindingRecord): Promise<void> {
+    return this.mutate(async () => {
+      const candidate: IWorkerCallerBindingDocument = { ...structuredClone(recordArg), updateId: plugins.crypto.randomUUID() };
+      const stored = await WorkerCallerBindingModel.exact.findStoredOne({ id: candidate.id });
+      try {
+        if (stored) {
+          const current = WorkerCallerBindingModel.exact.toPersisted(stored);
+          if (current.launchDigest === candidate.launchDigest) {
+            // A launch's binding only gains or renews its job; it is never unbound again.
+            if (current.binding && !candidate.binding) throw new Error('A kept worker caller binding cannot lose its job.');
+            const result = await WorkerCallerBindingModel.exact.transition({ current: stored, change: (model) => { Object.assign(model, candidate); } });
+            if (result.status !== 'transitioned') throw new Error('The kept worker caller binding changed concurrently.');
+            return;
+          }
+          const deleted = await WorkerCallerBindingModel.exact.delete({ current: stored });
+          if (deleted.status !== 'deleted') throw new Error('The kept worker caller binding changed concurrently.');
+        }
+        const inserted = await WorkerCallerBindingModel.exact.insert(candidate);
+        if (WorkerCallerBindingModel.exact.toPersisted(inserted.document).updateId !== candidate.updateId) {
+          throw new Error('Another worker caller binding holds this launch.');
+        }
+      } catch (error) {
+        if (!ambiguous(error)) throw error;
+        const after = await WorkerCallerBindingModel.exact.findStoredOne({ id: candidate.id });
+        if (!after || WorkerCallerBindingModel.exact.toPersisted(after).updateId !== candidate.updateId) {
+          throw new Error('Keeping the worker caller binding has an uncertain outcome.', { cause: error });
+        }
+      }
+    });
+  }
+
+  public delete(workerIdArg: string, launchDigestArg?: string): Promise<void> {
+    return this.mutate(async () => {
+      const stored = await WorkerCallerBindingModel.exact.findStoredOne({ id: workerIdArg });
+      if (!stored || launchDigestArg !== undefined && WorkerCallerBindingModel.exact.toPersisted(stored).launchDigest !== launchDigestArg) return;
+      try {
+        const result = await WorkerCallerBindingModel.exact.delete({ current: stored });
+        if (result.status !== 'deleted') throw new Error('The kept worker caller binding changed concurrently.');
+      } catch (error) {
+        if (!ambiguous(error) || await WorkerCallerBindingModel.exact.findStoredOne({ id: workerIdArg })) throw error;
+      }
+    });
+  }
+
+  private mutate(operationArg: () => Promise<void>): Promise<void> {
+    const task = this.mutationTail.then(operationArg);
+    this.mutationTail = task.then(() => undefined, () => undefined);
+    return task;
+  }
+}