agl 41.0.0 → 41.1.0

package/ts/classes.proxycontrol.ts

@@ -72,6 +72,8 @@ export interface IAglProxyStatus {
 export interface IAglProxyConfinedRunStatus {
   /** The run's id: the first 12 hex characters of its credential's SHA-256 digest, never the credential. */
   id: string;
+  /** The pool the run is served from: Claude accounts (`anthropic`) or ChatGPT accounts (`openai`). */
+  provider: TInferenceProvider;
   createdAt: string;
   /** False while a restarted proxy serves the credential for its reclaim window, waiting for its holder to take it back. */
   held: boolean;
@@ -148,24 +150,35 @@ export interface IReq_AglProxyReclaim extends ITypedRequest {
 
 /**
  * A confined run's credential: accepted on the confined listener alone, never on the loopback one, and served there from
- * the Claude pool exactly as the loopback listener serves a Claude client, its sessions those of the client
- * `aglProxyConfinedClient`. Like a lease it lives as long as the connection that asked for it, a restarted proxy keeps it
- * for its holder to take back (`agl.proxy.reclaim`), and the proxy keeps only its digest. `agl.proxy.confined.end` ends it
- * at once.
+ * the pool `provider` names -- the Claude pool when it names none -- exactly as the loopback listener serves Claude Code on
+ * that pool, its sessions those of the client `aglProxyConfinedClient` on that pool. A ChatGPT-pool run is served by the
+ * pool's ChatGPT accounts alone, since a translated Messages request never goes to an API key. Like a lease it lives as
+ * long as the connection that asked for it, a restarted proxy keeps it for its holder to take back
+ * (`agl.proxy.reclaim`), and the proxy keeps only its digest. `agl.proxy.confined.end` ends it at once.
  */
 export interface IReq_AglProxyConfined extends ITypedRequest {
   method: 'agl.proxy.confined';
-  request: Record<string, never>;
+  /** An empty request asks for a Claude-pool run, as every proxy since confined runs takes it. */
+  request: { provider?: TInferenceProvider };
   response: IAglProxyConfinedGrant;
 }
 
-/** What a confined run is given: its id, its credential, the confined listener's socket and the origin to name with it. */
+/**
+ * What a confined run is given: its id, its pool, its credential, the confined listener's socket and the origin to name
+ * with it, and, for a ChatGPT-pool run, the pool's models as the proxy read them when it issued the credential, which the
+ * launcher configures Claude Code with as `agl proxy run claude --provider openai` does. A Claude-pool run gets none:
+ * Claude Code reads that pool's models through the confined listener.
+ */
 export interface IAglProxyConfinedGrant {
   /** See `IAglProxyConfinedRunStatus.id`. */
   id: string;
+  /** The run's pool; a proxy older than ChatGPT-pool runs names none, and issues Claude-pool runs alone. */
+  provider?: TInferenceProvider;
   token: string;
   socketPath: string;
   baseUrl: string;
+  /** A ChatGPT-pool run's models, the pool's default among them; absent for a Claude-pool run. */
+  models?: TInferenceModel[];
 }
 
 /**
@@ -207,7 +220,7 @@ export interface IAglProxyControlHandlers {
   catalog(requestArg: IReq_AglProxyCatalog['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyCatalog['response']>;
   lease(requestArg: IReq_AglProxyLease['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyLease['response']>;
   reclaim(requestArg: IReq_AglProxyReclaim['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyReclaim['response']>;
-  confined(connectionArg: IAglProxyConnection): Promise<IReq_AglProxyConfined['response']>;
+  confined(requestArg: IReq_AglProxyConfined['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyConfined['response']>;
   confinedEnd(requestArg: IReq_AglProxyConfinedEnd['request']): Promise<IReq_AglProxyConfinedEnd['response']>;
   usage(requestArg: IReq_AglProxyUsage['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyUsage['response']>;
 }
@@ -303,8 +316,11 @@ export class AglProxyControlServer {
       return this.handlers!.reclaim(requestArg, connectionArg);
     }));
     this.router.addTypedHandler(handler<IReq_AglProxyConfined>('agl.proxy.confined', (requestArg, connectionArg) => {
-      if (!isRecord(requestArg) || Object.keys(requestArg).length !== 0) throw new AglProxyControlRefusal('Invalid proxy confined request.');
-      return this.handlers!.confined(connectionArg);
+      if (!isRecord(requestArg) || Object.keys(requestArg).some((keyArg) => keyArg !== 'provider')
+        || (requestArg.provider !== undefined && !inferenceProviders.includes(requestArg.provider))) {
+        throw new AglProxyControlRefusal('Invalid proxy confined request.');
+      }
+      return this.handlers!.confined(requestArg, connectionArg);
     }));
     this.router.addTypedHandler(handler<IReq_AglProxyConfinedEnd>('agl.proxy.confined.end', (requestArg) => {
       if (!isRecord(requestArg) || typeof requestArg.id !== 'string' || !aglProxyConfinedIdPattern.test(requestArg.id)

package/ts/classes.proxycontrolclient.ts

@@ -190,12 +190,15 @@ export class AglProxyControlClient {
   }
 
   /**
-   * A confined run's credential, the confined listener's socket and the origin to name with it; the credential lives as
-   * long as the returned connection (see `IReq_AglProxyConfined`).
+   * A confined run's credential on the pool `providerArg` names, the confined listener's socket and the origin to name
+   * with it; the credential lives as long as the returned connection (see `IReq_AglProxyConfined`). A Claude-pool run is
+   * asked for with the empty request every proxy since confined runs takes.
    */
-  public async confined(signalArg: AbortSignal): Promise<IReq_AglProxyConfined['response'] & IAglProxyLeaseConnection> {
+  public async confined(providerArg: TInferenceProvider,
+    signalArg: AbortSignal): Promise<IReq_AglProxyConfined['response'] & IAglProxyLeaseConnection> {
     let held: { socket: net.Socket; rest: Buffer } | undefined;
-    const response = await exchange<IReq_AglProxyConfined['response']>(this.socketPath, 'agl.proxy.confined', {},
+    const request: IReq_AglProxyConfined['request'] = providerArg === 'anthropic' ? {} : { provider: providerArg };
+    const response = await exchange<IReq_AglProxyConfined['response']>(this.socketPath, 'agl.proxy.confined', request,
       signalArg, (socketArg, restArg) => { held = { socket: socketArg, rest: restArg }; });
     return { ...response, ...leaseConnection(held) };
   }

package/ts/classes.proxydaemon.ts

@@ -8,7 +8,7 @@ import { InferenceRoutingError, type IInferenceRoutingPolicy } from './classes.i
 import { aglProxyConfinedClient, aglProxyConfinedOrigin, proxyClientNamePattern, type TInferenceProvider,
   type TProxyCredentialDelivery } from './functions.proxycontract.js';
 import { AglProxyControlRefusal, AglProxyControlServer, type IAglProxyConfinedGrant, type IAglProxyConnection,
-  type IAglProxyStatus, type IReq_AglProxyCatalog, type IReq_AglProxyReclaim,
+  type IAglProxyStatus, type IReq_AglProxyCatalog, type IReq_AglProxyConfined, type IReq_AglProxyReclaim,
   type TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
 import { ProxyStore, type IProxySecretCodec } from './classes.proxystore.js';
 import type { InferenceUsageStore } from './classes.inferenceusage.js';
@@ -51,8 +51,16 @@ 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' });
+/**
+ * The policy of a confined run's credential, by its pool: the pool, unrestricted, as Claude Code's own lease on the Claude
+ * pool and `agl proxy run claude --provider openai`'s on the ChatGPT pool.
+ */
+const confinedPolicies: Readonly<Record<TInferenceProvider, IInferenceRoutingPolicy>> = Object.freeze({
+  anthropic: Object.freeze({ provider: 'anthropic' }),
+  // A ChatGPT-pool run's policy is the one `agl proxy run claude --provider openai` leases: its translated Messages
+  // requests go to the pool's ChatGPT accounts alone, never to an API key (see `IReq_AglProxyConfined`).
+  openai: Object.freeze({ provider: 'openai' }),
+});
 
 /** 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);
@@ -61,6 +69,8 @@ const confinedRunId = (digestArg: string): string => digestArg.slice(0, 12);
 interface IHeldLease {
   grant: IInferenceGatewayGrant;
   route: TInferenceGatewayRoute;
+  /** The pool the lease is served from; a policy that names none is the ChatGPT pool's, as the router reads it. */
+  provider: TInferenceProvider;
   createdAt: Date;
   /** The connection the lease lives as long as, while a holder has it. */
   holder?: IAglProxyConnection;
@@ -146,7 +156,7 @@ 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),
+      confined: (requestArg, connectionArg) => this.confined(requestArg, 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),
@@ -168,8 +178,8 @@ export class AglProxyDaemon {
       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 })),
+        .map(([digestArg, heldArg]) => ({ id: confinedRunId(digestArg), provider: heldArg.provider,
+          createdAt: heldArg.createdAt.toISOString(), held: heldArg.reclaimTimer === undefined })),
     };
   }
 
@@ -289,7 +299,8 @@ 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, route: 'loopback', createdAt: new Date(), holder: connectionArg };
+    const held: IHeldLease = { grant: lease, route: 'loopback', provider: policyArg.provider ?? 'openai', 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,
@@ -319,30 +330,45 @@ export class AglProxyDaemon {
    * proves the caller holds the credential the lease was issued with.
    */
   /**
-   * 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.
+   * A confined run's credential (see `IReq_AglProxyConfined`): a lease of the pool the request names -- the Claude pool
+   * when it names none -- that continues the confined client's sessions on that pool 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`). A Claude-pool run gets no model list: Claude Code reads the pool's models
+   * through the confined listener, and the pool is judged at each request. A ChatGPT-pool run gets the pool's models, as
+   * an `agl proxy run` lease does, for its launcher to configure Claude Code with.
    */
-  private async confined(connectionArg: IAglProxyConnection): Promise<IAglProxyConfinedGrant> {
+  private async confined(requestArg: IReq_AglProxyConfined['request'],
+    connectionArg: IAglProxyConnection): Promise<IAglProxyConfinedGrant> {
     const socketPath = this.options.confinedSocketPath;
     if (socketPath === undefined) throw new AglProxyControlRefusal('This AGL proxy has no confined listener.');
+    const provider = requestArg.provider ?? 'anthropic';
+    const policy = confinedPolicies[provider];
+    const service = this.service!;
     let lease: IInferenceGatewayLease;
-    try { lease = await this.service!.open(confinedPolicy, { sessionScope: aglProxyConfinedClient, route: 'confined' }); }
+    try { lease = await service.open(policy, { 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 };
+    const held: IHeldLease = { grant: lease, route: 'confined', provider, 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' }));
+        policy, 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 };
+    const grant: IAglProxyConfinedGrant = { id: confinedRunId(lease.digest), provider, token: lease.token, socketPath,
+      baseUrl: aglProxyConfinedOrigin };
+    if (provider === 'anthropic') return grant;
+    try {
+      // A launcher that goes away stops the model list read it asked for.
+      return { ...grant, models: await service.router.models(policy, AbortSignal.any([connectionArg.signal, AbortSignal.timeout(60_000)])) };
+    } catch (errorArg) {
+      this.endLease(lease.digest, held);
+      throw catalogRefusal(errorArg);
+    }
   }
 
   /**
@@ -414,7 +440,7 @@ export class AglProxyDaemon {
         await this.forgetLease(kept.digest);
         continue;
       }
-      const held: IHeldLease = { grant, route: kept.route, createdAt: kept.createdAt };
+      const held: IHeldLease = { grant, route: kept.route, provider: kept.policy.provider ?? 'openai', createdAt: kept.createdAt };
       held.reclaimTimer = setTimeout(() => this.endLease(kept.digest, held), Math.max(0, deadline - Date.now()));
       this.leases.set(kept.digest, held);
     }

package/ts/classes.proxyleaseholder.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
-import type { IInferenceRoutingPolicy } from './classes.inferencerouter.js';
-import type { IReq_AglProxyReclaim, TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
+import type { IInferenceRoutingPolicy, TInferenceModel } from './classes.inferencerouter.js';
+import type { IAglProxyConfinedGrant, IReq_AglProxyReclaim, TAglProxyLeaseCatalog } from './classes.proxycontrol.js';
+import type { TInferenceProvider } from './functions.proxycontract.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. */
@@ -159,28 +160,56 @@ export class AglProxyLeaseHolder extends AglProxyHeldCredential {
   }
 }
 
+export interface IAglProxyConfinedHolderOptions extends IAglProxyHolderOptions {
+  /** The run's pool: Claude accounts (`anthropic`) or, translated, the ChatGPT accounts (`openai`). */
+  provider: TInferenceProvider;
+}
+
+/**
+ * Why a confined grant does not serve the pool it was asked for, or `undefined` when it does: a proxy older than
+ * ChatGPT-pool runs names no pool and issues Claude-pool runs alone, and a ChatGPT-pool run comes with the pool's models.
+ */
+const confinedGrantMismatch = (providerArg: TInferenceProvider, grantArg: IAglProxyConfinedGrant): string | undefined => {
+  if (providerArg === 'anthropic') {
+    return grantArg.provider === undefined || grantArg.provider === 'anthropic' ? undefined
+      : 'The AGL proxy issued a confined run of another pool than the Claude pool asked for.';
+  }
+  return grantArg.provider === 'openai' && Array.isArray(grantArg.models) ? undefined
+    : 'The AGL proxy issued no ChatGPT-pool confined run with the pool\'s models; it may run an AGL older than ChatGPT-pool runs.';
+};
+
 /**
  * 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> {
+  public static async take(optionsArg: IAglProxyConfinedHolderOptions, signalArg: AbortSignal): Promise<AglProxyConfinedHolder> {
     const control = new AglProxyControlClient(optionsArg.socketPath);
-    const grant = await control.confined(signalArg);
+    const grant = await control.confined(optionsArg.provider, signalArg);
+    const mismatch = confinedGrantMismatch(optionsArg.provider, grant);
+    if (mismatch !== undefined) {
+      grant.close();
+      throw new Error(mismatch);
+    }
     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 run's pool. */
+  public readonly provider: TInferenceProvider;
+  /** A ChatGPT-pool run's models as the proxy read them when it issued the credential; empty for a Claude-pool run. */
+  public readonly models: readonly TInferenceModel[];
   /** 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) {
+  private constructor(controlArg: AglProxyControlClient, grantArg: IAglProxyConfinedGrant & IAglProxyLeaseConnection,
+    optionsArg: IAglProxyConfinedHolderOptions) {
     super(controlArg, grantArg, optionsArg);
     this.id = grantArg.id;
+    this.provider = optionsArg.provider;
+    this.models = grantArg.models ?? [];
     this.confinedSocketPath = grantArg.socketPath;
   }
 

package/ts/classes.proxystore.ts

@@ -151,8 +151,9 @@ export interface IProxyLeaseDocument {
    */
   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.
+   * `confined` for a confined run's credential, accepted on the confined listener alone, with the policy of its pool,
+   * the Claude pool's or the ChatGPT pool's, unrestricted, and the confined client's sessions on that pool; absent for a
+   * lease of the loopback listener.
    */
   route?: 'confined';
 }
@@ -174,6 +175,10 @@ const assertLeasePolicy = (valueArg: unknown): IProxyLeasePolicyDocument => {
   return value;
 };
 
+/** A confined run's policy, as kept: one pool, unrestricted (see `IProxyLeaseDocument.route`). */
+const confinedLeasePolicies: ReadonlySet<string> = new Set([JSON.stringify({ provider: 'anthropic' }),
+  JSON.stringify({ provider: 'openai' })]);
+
 const assertLease: (valueArg: unknown) => asserts valueArg is IProxyLeaseDocument = (valueArg) => {
   const value = valueArg as Partial<IProxyLeaseDocument> | null;
   if (!value || typeof value !== 'object'
@@ -182,7 +187,7 @@ const assertLease: (valueArg: unknown) => asserts valueArg is IProxyLeaseDocumen
     || typeof value.client !== 'string' || !proxyClientNamePattern.test(value.client)
     || !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' })))) {
+      || !confinedLeasePolicies.has(JSON.stringify(value.policy))))) {
     throw new Error('Invalid proxy lease.');
   }
   assertLeasePolicy(value.policy);

package/ts/classes.upgradecoordinator.ts

@@ -85,6 +85,18 @@ interface IUpgradeSemver {
   prerelease: string[];
 }
 
+const upgradeOwnerCommands = [
+  '__serve', '__upgrade-worker', 'upgrade', 'start', 'restart', 'service', 'foreground', 'temp-password', 'config',
+] as const;
+/** The CLI commands this release runs under an upgrade lock or a start lease. */
+type TUpgradeOwnerCommand = (typeof upgradeOwnerCommands)[number];
+const upgradeOwnerCommandSet: ReadonlySet<string> = new Set(upgradeOwnerCommands);
+/**
+ * A command a later release's CLI holds a start lease under (`agl remote` from 42 on), read back after a rollback:
+ * its owner is live while that command runs and stale once it ended, like any other.
+ */
+const laterReleaseStartCommandPattern = /^[a-z][a-z0-9-]{0,31}$/;
+
 interface IUpgradeProcessOwner {
   version: typeof coordinationVersion;
   kind: TUpgradeOwnerKind;
@@ -94,7 +106,8 @@ interface IUpgradeProcessOwner {
   processGroupId: number;
   fingerprint: string;
   cliPath: string;
-  command: '__serve' | '__upgrade-worker' | 'upgrade' | 'start' | 'restart' | 'service' | 'foreground' | 'temp-password' | 'config';
+  /** A `TUpgradeOwnerCommand`, or for a start lease also a later release's command. */
+  command: string;
   createdAt: number;
 }
 
@@ -504,15 +517,11 @@ const parseOwner = (valueArg: unknown): IUpgradeProcessOwner => {
     || value.fingerprint.length > 256
     || typeof value.cliPath !== 'string'
     || !plugins.path.isAbsolute(value.cliPath)
-    || (value.command !== '__serve'
-      && value.command !== '__upgrade-worker'
-      && value.command !== 'start'
-      && value.command !== 'upgrade'
-      && value.command !== 'foreground'
-      && value.command !== 'temp-password'
-      && value.command !== 'config'
-      && value.command !== 'restart'
-      && value.command !== 'service')
+    || typeof value.command !== 'string'
+    || (
+      !upgradeOwnerCommandSet.has(value.command)
+      && (value.kind !== 'start' || !laterReleaseStartCommandPattern.test(value.command))
+    )
   ) {
     throw new Error('Upgrade owner metadata is invalid.');
   }
@@ -1330,7 +1339,7 @@ const ownerForCurrentProcess = async (
   kindArg: TUpgradeOwnerKind,
   tokenArg: string,
   cliPathArg: string,
-  commandArg: IUpgradeProcessOwner['command'],
+  commandArg: TUpgradeOwnerCommand,
 ): Promise<IUpgradeProcessOwner> => {
   const identity = await readControllerProcessIdentity(process.pid);
   if (!identity) throw new Error('Unable to establish upgrade process ownership.');

package/ts/classes.upgradetransaction.ts

@@ -9,6 +9,7 @@ import {
 } from '../ts_interfaces/index.js';
 import { resolveAGLHomePaths } from './classes.aglhome.js';
 import {
+  isControllerManagementProtocolVersion,
   isLoopbackPortListening,
   queryControllerStatus,
   requestControllerUpgradeFinalize,
@@ -144,8 +145,22 @@ export interface IPnpmGlobalInstallation {
   packageDirectory: string;
   cliPath: string;
   packageVersion: string;
+  /**
+   * The management protocol the installed `package.json` declares (`controllerManagementProtocolVersion`), which
+   * decides how the controller this package starts is reached before it reports its status; absent when it declares
+   * none, as every release older than the loopback management endpoint.
+   */
+  managementProtocolVersion?: number;
 }
 
+/**
+ * What a `package.json` declares as `controllerManagementProtocolVersion`: `undefined` for no declaration, `false`
+ * for one that is not a safe integer of 1 or more, which makes the package metadata incompatible.
+ */
+const readDeclaredManagementProtocolVersion = (valueArg: unknown): number | undefined | false => (
+  valueArg === undefined ? undefined : isControllerManagementProtocolVersion(valueArg) ? valueArg : false
+);
+
 export interface IDetachedUpgradeWorker {
   pid: number;
   processGroupId: number;
@@ -597,15 +612,20 @@ export const resolvePnpmGlobalInstallation = async (): Promise<IPnpmGlobalInstal
     version?: unknown;
     bin?: unknown;
     controllerUpgradeManagementVersion?: unknown;
+    controllerManagementProtocolVersion?: unknown;
   };
   const currentIdentity: { cliName: string; cliRelativePath: string; managementVersion: number } = (
     currentPackageIdentity
   );
+  const managementProtocolVersion = readDeclaredManagementProtocolVersion(
+    packageJson.controllerManagementProtocolVersion,
+  );
   if (
     packageJson.name !== controllerPackageName
     || packageJson.version !== dependency.version
     || packageJson.controllerUpgradeManagementVersion !== currentIdentity.managementVersion
     || Number(controllerUpgradeManagementVersion) !== currentIdentity.managementVersion
+    || managementProtocolVersion === false
     || !declaresControllerCommands(packageJson.bin, currentIdentity)
   ) {
     throw new Error(`The pnpm-global ${controllerPackageName} package metadata is incompatible.`);
@@ -621,6 +641,7 @@ export const resolvePnpmGlobalInstallation = async (): Promise<IPnpmGlobalInstal
     packageDirectory,
     cliPath,
     packageVersion: dependency.version,
+    ...(managementProtocolVersion === undefined ? {} : { managementProtocolVersion }),
   };
 };
 
@@ -749,10 +770,14 @@ const readExactGlobalPackage = async (
   }
   const manifest = packageJson as Record<string, unknown>;
   const bin = manifest.bin;
+  const managementProtocolVersion = readDeclaredManagementProtocolVersion(
+    manifest.controllerManagementProtocolVersion,
+  );
   if (
     manifest.name !== identityArg.packageName
     || manifest.version !== identityArg.version
     || manifest.controllerUpgradeManagementVersion !== identityArg.managementVersion
+    || managementProtocolVersion === false
     || !bin
     || typeof bin !== 'object'
     || Array.isArray(bin)
@@ -772,6 +797,7 @@ const readExactGlobalPackage = async (
     packageDirectory,
     cliPath,
     packageVersion: identityArg.version,
+    ...(managementProtocolVersion === undefined ? {} : { managementProtocolVersion }),
     packageName: identityArg.packageName,
     cliName: identityArg.cliName,
     cliRelativePath: identityArg.cliRelativePath,
@@ -952,11 +978,15 @@ const resolveAuthoritativeRecoveryInstallation = async (
   }
   const manifest = packageJson as Record<string, unknown>;
   const bin = manifest.bin;
+  const managementProtocolVersion = readDeclaredManagementProtocolVersion(
+    manifest.controllerManagementProtocolVersion,
+  );
   if (
     manifest.name !== currentIdentity.packageName
     || typeof manifest.version !== 'string'
     || !currentIdentity.versions.includes(manifest.version)
     || manifest.controllerUpgradeManagementVersion !== currentIdentity.managementVersion
+    || managementProtocolVersion === false
     || !declaresControllerCommands(bin, currentIdentity)
   ) throw new Error('The authoritative recovery package identity is incompatible.');
   if (!(await plugins.fs.promises.stat(cliPath)).isFile()) {
@@ -970,6 +1000,7 @@ const resolveAuthoritativeRecoveryInstallation = async (
     packageDirectory,
     cliPath,
     packageVersion: manifest.version,
+    ...(managementProtocolVersion === undefined ? {} : { managementProtocolVersion }),
   };
 };
 
@@ -1956,6 +1987,10 @@ const grantControllerAction = async (
   },
 });
 
+/**
+ * Reads the status of a controller the upgrade just started from `installationArg`, over the transport that
+ * package's `package.json` declares.
+ */
 const queryUpgradeManagedController = async (
   portArg: number,
   identityArg: {
@@ -1963,10 +1998,12 @@ const queryUpgradeManagedController = async (
     packageVersion: string;
     managementVersion: number;
   },
+  installationArg: IPnpmGlobalInstallation,
 ): Promise<IControllerStatus> => queryControllerStatus(portArg, {
   packageName: identityArg.packageName,
   packageVersion: identityArg.packageVersion,
   upgradeManagementVersion: identityArg.managementVersion,
+  managementProtocolVersion: installationArg.managementProtocolVersion,
 });
 
 const finalizeControllerUpgrade = async (
@@ -1980,7 +2017,7 @@ const finalizeControllerUpgrade = async (
   try {
     response = await requestControllerUpgradeFinalize(statusArg.controllerPid > 0
       ? (await coordinatorArg.readTransaction(tokenArg)).port
-      : 0, tokenArg, modeArg);
+      : 0, statusArg, tokenArg, modeArg);
   } finally {
     await coordinatorArg.removeControllerActionGrant('finalize', tokenArg);
   }
@@ -2103,6 +2140,7 @@ export const prepareAndStopRunningController = async (
   try {
     await (dependenciesArg.requestPrepareBegin ?? requestControllerUpgradePrepareBegin)(
       optionsArg.port,
+      optionsArg.runningStatus,
       optionsArg.token,
       optionsArg.targetVersion,
       optionsArg.gracePeriodMs,
@@ -2323,6 +2361,7 @@ const runPackageTransitionUpgradeWorker = async (optionsArg: {
       packageVersion: initialTransaction.sourceVersion,
       protocolVersion: controllerProtocolVersion,
       upgradeManagementVersion: initialTransaction.sourceManagementVersion,
+      managementProtocolVersion: currentInstallation.managementProtocolVersion,
     });
     assertExpectedController(runningStatus, payload.expectedController);
     if (
@@ -2470,6 +2509,7 @@ const runPackageTransitionUpgradeWorker = async (optionsArg: {
         const restoredStatus = await queryUpgradeManagedController(
           payload.port,
           sourceControllerIdentity(initialTransaction),
+          sourceTopology.source,
         );
         await finalizeControllerUpgrade(
           coordinator,
@@ -2520,6 +2560,7 @@ const runPackageTransitionUpgradeWorker = async (optionsArg: {
     const targetStatus = await queryUpgradeManagedController(
       payload.port,
       targetControllerIdentity(initialTransaction),
+      targetInstallation,
     );
     await updateWorkerProgress(
       coordinator,
@@ -2728,6 +2769,7 @@ export async function runUpgradeWorker(
         packageVersion: currentInstallation.packageVersion,
         protocolVersion: controllerProtocolVersion,
         upgradeManagementVersion: controllerUpgradeManagementVersion,
+        managementProtocolVersion: currentInstallation.managementProtocolVersion,
       });
       assertExpectedController(runningStatus, payloadArg.expectedController);
       if (
@@ -2812,6 +2854,7 @@ export async function runUpgradeWorker(
               packageVersion: restored.packageVersion,
               managementVersion: controllerUpgradeManagementVersion,
             },
+            restored,
           );
           await finalizeControllerUpgrade(
             coordinator,
@@ -2851,7 +2894,7 @@ export async function runUpgradeWorker(
         packageName: controllerPackageName,
         packageVersion: latestVersion,
         managementVersion: controllerUpgradeManagementVersion,
-      });
+      }, upgradedInstallation);
       await updateWorkerProgress(
         coordinator,
         payloadArg.token,
@@ -2997,6 +3040,7 @@ const recoverPackageTransition = async (optionsArg: {
         packageName: current.targetPackageName,
         packageVersion: upgradeTransactionTargetVersion(current)!,
         upgradeManagementVersion: current.targetManagementVersion,
+        managementProtocolVersion: targetInstallation.managementProtocolVersion,
       }).catch(() => undefined);
       if (!status) {
         if (await retainedUpgradeTargetIsAuthoritative({
@@ -3019,6 +3063,7 @@ const recoverPackageTransition = async (optionsArg: {
         status = await queryUpgradeManagedController(
           current.port,
           targetControllerIdentity(current),
+          targetInstallation,
         );
       }
       await finalizeControllerUpgrade(
@@ -3051,6 +3096,7 @@ const recoverPackageTransition = async (optionsArg: {
       packageName: transaction.sourcePackageName,
       packageVersion: transaction.sourceVersion,
       upgradeManagementVersion: transaction.sourceManagementVersion,
+      managementProtocolVersion: sourceInstallation.managementProtocolVersion,
     }).catch(() => undefined);
     if (!status) {
       await startRestoredController(
@@ -3062,6 +3108,7 @@ const recoverPackageTransition = async (optionsArg: {
       status = await queryUpgradeManagedController(
         transaction.port,
         sourceControllerIdentity(transaction),
+        sourceInstallation,
       );
     }
     await finalizeControllerUpgrade(
@@ -3130,6 +3177,7 @@ const recoverStalledUpgradeUnderLock = async (optionsArg: {
         packageName: controllerPackageName,
         packageVersion: targetInstallation.packageVersion,
         upgradeManagementVersion: controllerUpgradeManagementVersion,
+        managementProtocolVersion: targetInstallation.managementProtocolVersion,
       }).catch(() => undefined);
       if (!status) {
         if (await retainedUpgradeTargetIsAuthoritative({
@@ -3156,6 +3204,7 @@ const recoverStalledUpgradeUnderLock = async (optionsArg: {
             packageVersion: targetInstallation.packageVersion,
             managementVersion: controllerUpgradeManagementVersion,
           },
+          targetInstallation,
         );
       }
       await finalizeControllerUpgrade(
@@ -3187,6 +3236,7 @@ const recoverStalledUpgradeUnderLock = async (optionsArg: {
       packageName: controllerPackageName,
       packageVersion: sourceInstallation.packageVersion,
       upgradeManagementVersion: controllerUpgradeManagementVersion,
+      managementProtocolVersion: sourceInstallation.managementProtocolVersion,
     }).catch(() => undefined);
     if (!status) {
       await startRestoredController(
@@ -3202,6 +3252,7 @@ const recoverStalledUpgradeUnderLock = async (optionsArg: {
           packageVersion: sourceInstallation.packageVersion,
           managementVersion: controllerUpgradeManagementVersion,
         },
+        sourceInstallation,
       );
     }
     await finalizeControllerUpgrade(