agl 41.0.1 → 41.2.0

package/readme.md

@@ -331,6 +331,7 @@ agl proxy run claude --                       # Claude Code on Claude accounts
 agl proxy run claude --provider openai --model <catalog-model> --
 agl proxy run opencode --model <catalog-model> -- run 'Explain this repository'
 agl proxy confined run -- docker run --rm --user "$(id -u):$(id -g)" -i <image> claude -p   # Claude Code in a container
+agl proxy confined run --provider openai -- docker run --rm --user "$(id -u):$(id -g)" -i <image> claude -p
 agl proxy confined end <run id>
 ```
 
@@ -444,7 +445,8 @@ listener, a Unix socket that serves confined runs alone (see [Confined container
 - A ChatGPT pool serves `/openai/v1/responses` and `/openai/v1/models` (the pooled Codex catalog in Codex's
   own shape when Codex names its `client_version`), and `/anthropic/v1/messages` and `/anthropic/v1/models`
   for Claude Code on ChatGPT models. Raw Responses requests retain their storage and streaming choices.
-  Claude Code's Messages requests are translated by the shared provider package;
+  Claude Code's Messages requests are translated by the shared provider package (see
+  [Claude Code on the ChatGPT pool](#claude-code-on-the-chatgpt-pool));
   `/anthropic/v1/messages/count_tokens` answers 404 there by design, on which Claude Code estimates the count
   itself. Other OpenAI endpoints, such as Chat Completions, and WebSocket inference are not served.
 - A Claude pool serves Claude Code's own requests: `/anthropic/v1/messages`,
@@ -626,7 +628,15 @@ proxy then keeps the account out of rotation itself until it restarts, and says
 The proxy also records the tokens every answer states -- input, output, cache reads and cache writes -- per minute and per
 hour, model, client name, account and the session id the client sent, minutes for a day and hours for eight days, also
 for an Anthropic API key; it keeps no prompt, answer or credential, and a write that fails is reported on its standard
-error and retried with the next. The controller reads these only while a browser watches a usage window:
+error and retried with the next. An answer that does not state its cache reads or writes (a ChatGPT answer without
+`input_tokens_details.cache_write_tokens`, a Claude answer whose `cache_read_input_tokens` or
+`cache_creation_input_tokens` is missing or null) has unknown cache reads or writes, not none: each bucket counts the
+reads and writes its answers stated (`cacheReadTokens`, `cacheWriteTokens`) and, beside them, the answers that did not
+state theirs (`cacheReadUnknownCalls`, `cacheWriteUnknownCalls`). An OpenAI account's unknown cache counts stay in its
+input count, since OpenAI counts every input token there; a Claude account's input leaves the cache out, so a bucket of
+one with unknown cache counts adds up to less than its answers used (`controllerUsageTotalIsLowerBound`). A bucket
+stored before AGL counted them reads with all its answers unknown. The controller reads these only while a browser
+watches a usage window:
 `controller.metrics.usage.watch { window }` (`1h` by minute, `24h` or `7d` by hour) answers the window's buckets with
 a `watchId`, the feed's `epoch` and a `revision`, and the changes follow on that connection alone as `usage.changed`
 events, each continuing the revision before it, until `controller.metrics.usage.unwatch { watchId }` or the
@@ -640,7 +650,10 @@ is told to watch again and refused. An unreachable proxy refuses a watch with `p
 
 The web app's header has a **Metrics** button. It shows the token usage in the main pane, as the Board button
 shows the board; leaving it ends its watch. A toggle chooses the last hour, day or week. Totals for input, output,
-cache reads, cache writes and calls head the view; below them a line chart shows the tokens per minute by model, each
+cache reads, cache writes and calls head the view; cache reads and writes read **Unknown** when no call stated any, and
+**≥** the stated count when some calls did not, with the number of calls whose count is unknown under the tile (the
+model and session tables say the same, and their **Total** reads **≥** when it leaves out a Claude answer's unknown
+cache count); below them a line chart shows the tokens per minute by model, each
 model's line drawn from zero (each completed minute for the hour, the hourly average for the day and week, the current
 hour's over its minutes so far), and pointing at a moment lists every model's value there with the time. A table lists
 every model the window counted, sorted by total tokens. A model's row opens a second table of its sessions by client and session id. The
@@ -706,45 +719,112 @@ proxy's binding with it, and the sessions it served move at their next request.
 pool, 16 requests in flight per session, 256 per client credential, 512 in all, 32 MiB per request and 8 MiB
 per inspected response event (or non-streaming JSON response).
 
+#### Claude Code on the ChatGPT pool
+
+Claude Code on the ChatGPT pool -- `agl proxy run claude --provider openai`, a Claude terminal on ChatGPT models, a client
+moved there with `agl proxy credential <client> --provider openai`, or a confined run with `--provider openai` -- sends
+Anthropic Messages requests. The proxy translates each for the ChatGPT backend (`https://chatgpt.com/backend-api/codex/responses`,
+a Responses endpoint) with the Messages translation of `@modelprofile.com/flexharness-providers` and sends it on the
+chosen ChatGPT account's own credential.
+
+What the translation adds to a request is what the backend requires, and no text of AGL's own:
+
+- Claude Code's system prompt becomes the request's `instructions`, which the backend requires at its top; a system
+  message later in the conversation stays in its place as a `developer` message.
+- `store: false` (the backend keeps no response), `stream: true` (an answer is assembled whole for a client that did not
+  ask to stream) and, for a model that reasons, `include: ["reasoning.encrypted_content"]`: the model's reasoning comes
+  back encrypted and travels in the thinking block's signature, which the proxy signs with a key of its own for the
+  account it came from. A thinking block whose signature this proxy did not write for that account is not sent back;
+  the answer counts them in `x-flexharness-thinking-dropped`.
+- `prompt_cache_key`, Claude Code's session id (`x-claude-code-session-id`), so the backend's prompt cache keys on the
+  conversation; parallel tool calls turned off when Claude Code turns them off; Claude Code's tools as function tools,
+  a name of more than 64 characters under a short alias.
+- The account's credential and account id. None of Claude Code's own headers go on, and never the client's credential.
+
+What it drops: from a request, `max_tokens` (the backend takes no output limit; the answer says
+`x-flexharness-max-tokens: not-sent`), a thinking token budget (`budget_tokens`, which has no equivalent: the effort
+sets the depth), and Anthropic's own hints -- prompt cache markers, `metadata`, `service_tier`, citations -- which are
+accepted without effect. What cannot be translated faithfully is refused with a 400 that names it: server tools (Claude
+Code then continues without them), server-side context management, code execution containers, remote MCP servers and
+deferred tool loading, whose betas `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` keeps Claude Code from sending. Of an
+answer Claude Code gets the model's text, its tool calls, its reasoning summary as thinking, the stop reason and the
+token counts (input, output, cache reads and writes, a cache count `null` when the backend did not state it); the
+backend's response id, its own headers and the rest of its response do not reach it.
+
+Reasoning effort: Claude Code sends its effort as `output_config.effort` (`low` to `max`, chosen with `/effort`,
+`--effort` or `CLAUDE_CODE_EFFORT_LEVEL`), together with adaptive thinking; Claude Code 2.1.288, the release of AGL's
+Agent SDK, sends `high` when none is chosen, for a ChatGPT model's id as well. The translation sends it as the request's
+`reasoning.effort`, fitted to the efforts the model's catalog lists: a model without the requested one gets the nearest
+lower, and the answer names the fit in `x-flexharness-effort-fitted` (`max=>xhigh`). Thinking asks for the reasoning's
+summary (`reasoning.summary: auto`). A request without an effort sends none, which leaves the depth to the backend.
+
+The ChatGPT account's own side: OpenAI documents Codex's personalization as its client's -- personal instructions in
+the Codex home's global `AGENTS.md`, memories in a local store under the Codex home (off by default) -- and ChatGPT's
+own memory as ChatGPT on the web's (learn.chatgpt.com, *Personalize ChatGPT* and *Memories*, read 2026-10-26). On this
+route no Codex client and no Codex home take part: a request carries Claude Code's own system prompt and messages, names
+no personality and no stored response, and carries nothing of the account but its credential and id. Whether the
+ChatGPT backend adds anything of the account's side -- custom instructions, memory or other personalization -- to a
+request on its own side cannot be seen in the request or its answer, so AGL cannot know it beyond what OpenAI documents.
+
 #### Confined containers
 
 `agl proxy confined run` runs Claude Code in a Docker container that reaches AGL through one route only: the proxy's
 confined listener, a Unix socket alone in a directory of its own (`agl-proxy-confined/proxy.sock` beside the proxy's
-control socket; `agl proxy status` names it). The listener serves the Claude pool's three endpoints Claude Code uses --
+control socket; `agl proxy status` names it). Each run is served from one pool, chosen when it starts: the Claude pool,
+or with `--provider openai` the ChatGPT pool. The listener serves the three endpoints Claude Code uses --
 `GET /anthropic/v1/models`, `POST /anthropic/v1/messages` and `POST /anthropic/v1/messages/count_tokens` -- exactly as
-the loopback listener serves a Claude client, and refuses every other path, method and pool with 404 before anything is
-read or routed; nothing else of AGL is reachable through it. It accepts confined runs' credentials alone: a request
-without a credential, with one the proxy does not know, or with a credential of the loopback listener (any client's or
-lease's) is refused with 401, and a confined run's credential is refused on the loopback listener alike.
+the loopback listener serves Claude Code on the run's pool: on the Claude pool sent on to Anthropic as Claude Code sent
+them, on the ChatGPT pool translated (see [Claude Code on the ChatGPT pool](#claude-code-on-the-chatgpt-pool), where
+`count_tokens` answers 404 and Claude Code estimates). It refuses every other path and method with 404 before anything
+is read or routed, every `/openai/v1/` path of a ChatGPT-pool run among them; nothing else of AGL is reachable through
+it. It accepts confined runs' credentials alone: a request without a credential, with one the proxy does not know, or
+with a credential of the loopback listener (any client's or lease's) is refused with 401, and a confined run's
+credential is refused on the loopback listener alike.
 
 ```sh
 agl proxy confined run -- docker run --rm --user "$(id -u):$(id -g)" -i <image> \
   claude -p --model claude-opus-5-5 --output-format json < prompt.txt
-agl proxy status                  # names the confined listener and lists the runs by id
+agl proxy confined run --provider openai -- docker run --rm --user "$(id -u):$(id -g)" -i <image> \
+  claude -p --output-format json < prompt.txt          # on the ChatGPT pool's default model
+agl proxy status                  # names the confined listener and lists the runs by id, with their pools
 agl proxy confined end <run id>   # ends a run's credential at once
 ```
 
 Before the container starts, the command asks the proxy for the run's credential: one for this run alone, a lease of
-the Claude pool (the Claude accounts first, then the Anthropic API keys) whose sessions are those of the client
-`confined`, so its requests are placed, moved and counted (token usage under `confined`) like any other Claude
-client's. Right after `docker run` it adds the listener's directory as a read-only mount at `/run/agl-proxy` and what
-Claude Code inside needs to reach it, each variable passed by name so the credential appears on no command line:
+the run's pool whose sessions are those of the client `confined` on that pool, so its requests are placed, moved and
+counted (token usage under `confined`) like any other client's of that pool. Without `--provider`, or with
+`--provider anthropic`, it is a lease of the Claude pool (the Claude accounts first, then the Anthropic API keys),
+exactly as before ChatGPT-pool runs. With `--provider openai` it is a lease of the ChatGPT pool as
+`agl proxy run claude --provider openai` takes one: its translated Messages requests go to the pool's ChatGPT accounts
+alone, never to an OpenAI API key (see [ChatGPT accounts first, then OpenAI API keys](#chatgpt-accounts-first-then-openai-api-keys)),
+and the proxy hands the run the pool's models with it. Right after `docker run` the command adds the listener's
+directory as a read-only mount at `/run/agl-proxy` and what Claude Code inside needs to reach it, each variable passed
+by name so the credential appears on no command line:
 
 - `ANTHROPIC_UNIX_SOCKET=/run/agl-proxy/proxy.sock`: Claude Code sends its API requests through the socket, as plain
   HTTP, so no relay runs in the container (Claude Code's own setting, which `claude ssh` uses; verified with Claude Code
   2.1.288, the release of AGL's Agent SDK);
 - `ANTHROPIC_BASE_URL=http://localhost/anthropic`: the path Claude Code puts on its requests; the host is not used;
 - `ANTHROPIC_AUTH_TOKEN`: the run's credential;
-- `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` and `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`, as `agl proxy run
-  claude` sets them.
-
-It prints the run's id on standard error (`AGL proxy confined run <id>: …`), passes its standard input and output
-through, and exits with the container's status. The container never receives an account token, the control socket or
-any other part of the AGL home: the mount holds the socket alone, and the variables that would give Claude Code another
-login or route (`CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, …) are removed from the environment `docker` runs with,
-so a `-e NAME` of one of them passes nothing. What the launcher names itself after `docker run` is its own: it must not
-set the variables above. The command takes `docker run` and `docker container run` only, with the image and its
-command after the options.
+- on the Claude pool, `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` and `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`, as
+  `agl proxy run claude` sets them;
+- on the ChatGPT pool, the variables `agl proxy run claude --provider openai` sets: the pool's default model as
+  `ANTHROPIC_MODEL` and for every alias (`ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`,
+  `ANTHROPIC_DEFAULT_HAIKU_MODEL`), the context window the catalog states for it (`CLAUDE_CODE_MAX_CONTEXT_TOKENS`),
+  `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` and
+  `CLAUDE_CODE_ATTRIBUTION_HEADER=0`. Two things of that command stay on the host: its Claude Code configuration
+  directory, which lies in the AGL home, and its `/model` picker of the pool's models, an option of Claude Code's
+  command line, which the launcher leaves as the container's command names it. Name another of the pool's models with
+  Claude Code's own `--model` in the container's command.
+
+It prints the run's id on standard error (`AGL proxy confined run <id>: …`; a ChatGPT-pool run's line says
+`served from the ChatGPT pool`), passes its standard input and output through, and exits with the container's status. The
+container never receives an account token, the control socket or any other part of the AGL home: the mount holds the
+socket alone, and the variables that would give Claude Code another login or route (`CLAUDE_CODE_OAUTH_TOKEN`,
+`ANTHROPIC_API_KEY`, …), and on the ChatGPT pool every model variable above, are removed from the environment `docker`
+runs with, so a `-e NAME` of one of them passes nothing. What the launcher names itself after `docker run` is its own:
+it must not set the variables above. The command takes `docker run` and `docker container run` only, with the image and
+its command after the options.
 
 The socket and its directory are the proxy user's alone (0600 and 0700), so the container's processes connect as that
 user: `--user` with its uid and gid under a Docker daemon that runs as root, or the container's own root under rootless
@@ -760,10 +840,12 @@ serves it again at once while the command takes it back. `agl proxy confined end
 flight end, the next one is refused, and the command stops the container (`docker run` passes its SIGTERM on) and exits
 with the reason; it does the same when the proxy does not hand the credential back after a restart.
 
-Downgrade: an earlier proxy refuses to start while its store keeps a confined run's credential, which its check of the
-kept leases does not know. Let every confined run end before downgrading; if an earlier proxy's start already failed,
-start this release once with no confined run going and wait out the 60-second reclaim window, which ends the kept
-credential, then downgrade.
+Downgrade: an earlier proxy refuses to start while its store keeps a confined run's credential its check of the kept
+leases does not know: any confined run's for a release before confined runs, a ChatGPT-pool run's for one before
+ChatGPT-pool runs (41.0.1 and earlier). Let every confined run end before downgrading; if an earlier proxy's start
+already failed, start this release once with no confined run going and wait out the 60-second reclaim window, which
+ends the kept credential, then downgrade. A launcher older than ChatGPT-pool runs still runs Claude-pool runs on this
+proxy; an older proxy refuses this release's `--provider openai`, as it issues no ChatGPT-pool run.
 
 ## Native Codex Harness
 
@@ -2836,6 +2918,7 @@ The upgrade worker:
 - Restarts `agl-proxy.service` onto the new release once the target controller is up, when the unit is installed and running and runs the pnpm-global `agl` shim, and waits until the proxy answers as the new release and its credential launcher, run with an empty environment as a harness runs it, runs the new release too. A unit that is not installed or not running is left alone. A restart that fails does not fail the upgrade: it is logged as a warning and appended to the completion message (`message` in `--json` output).
 - Moves the accounts service onto the authswitch the new AGL brings, with authswitch's own `authority service stop`, `install` and `start`: the service is stopped before the package changes and started again, on the new release, when it ran before. A release that declares no `authswitch` command is refused before anything is stopped. A host without the service's unit keeps it that way, and the service's store is never touched. Stopping the service also stops the managed Codex runtimes it runs; they start again when next asked for. The log names what was stopped and started; a failed upgrade restores the previous AGL first, then the running service, and each step is recorded in the upgrade transaction, so recovering a lost worker finishes or undoes it.
 - Preserves its transaction across worker or controller failure.
+- Reads the controller's status, prepares it and finalizes it through the controller's loopback management endpoint (an HTTP `POST` of one TypedRequest to `/management/typedrequest` on the controller's port, addressed to `127.0.0.1:<port>`), never through the browser's WebSocket, so the worker of one release finalizes the controller of the next whatever transport that release's browser speaks. `agl status` and `agl upgrade` read their own release's controller the same way. The endpoint is used only for a controller that declares it: before the controller runs, by `controllerManagementProtocolVersion` in the `package.json` of the installed release that starts it, and once it runs, by `managementProtocolVersion` in its status. A controller that declares neither, as every release before the endpoint, such as a source an upgrade recovery restores, is reached over its controller socket, which keeps serving the status read and the upgrade methods for the workers of earlier releases. Nothing is tried over one transport and then the other.
 
 The cohort is every conversation with an AGL prompt that is queued or still running when the upgrade starts. AGL seals prompt admission, so no new message is accepted and no queue starts a turn, and stops each of them, as **Stop** does:
 
@@ -2857,6 +2940,16 @@ Upgrade coordination lives under `$AGL_HOME/upgrade`. Private logs live under `$
 
 A failure reference from the Errors dialog appears in those logs on the line the controller wrote when the failure happened, together with the operation and the cause. The journal the dialog reads it from is in memory only, so it is gone after a controller restart while the log line remains.
 
+### Rolling back from a later release
+
+A later release keeps a port's trusted-proxy secret sealed in the controller's database and never exports it, and `agl remote set` there can store gateway sources, which 41.1.x cannot enforce. To roll back a port that a later release serves behind a TLS reverse proxy:
+
+1. On the later release, stop the controller and run `agl remote unset --port <port>`. It moves the port back to `http://localhost:<port>` and removes its passkey, so the next start prints a setup code. A 41.1.x controller refuses to start on a configuration with gateway sources, and its refusal names this command.
+2. Roll back and start the controller.
+3. To serve 41.1.x behind the proxy again, generate a new secret and set it both on the proxy route (`X-Harness-Controller-Proxy-Secret`) and in `AGL_TRUSTED_PROXY_SECRET`, as in [Remote Browser Access](#remote-browser-access). 41.1.x fixes a port's public origin and TLS mode on its first start, so that is a port that has not been started yet.
+
+Audit events of types a later release wrote stay in the audit log and are pruned with the others.
+
 ### Migrating From `hcon`
 
 Starting from `@modelprofile.com/harness-controller@20.0.2`, run the active command twice:
@@ -2989,13 +3082,15 @@ Backend isolation is mandatory. Proxy mode binds the controller to all interface
 - Local mode binds the controller to loopback only.
 - The private OpenCode server always remains on loopback and uses a generated per-process password.
 - Application RPC starts only after the exact TypedSocket package-major handshake.
+- The management endpoint (`/management/typedrequest`, used by the CLI and the upgrade worker) answers only an HTTP `POST` of `application/json` from a loopback peer (`127.0.0.1` or `::1`), addressed to `127.0.0.1:<port>`, with no `Origin` and no forwarding header (`Forwarded`, `X-Forwarded-*`, `X-Real-IP`, `X-Harness-Controller-Proxy-Secret`), so a browser or a request a proxy forwards is refused, also in proxy mode. It serves only the status read and the upgrade methods; each upgrade method authorises itself against the upgrade token and its one-time grant, as it does over the socket, and every upgrade request counts against the controller's global unauthenticated preflight limit.
 - Client-managed connection tags are disabled; authentication and routing use server-owned peer state.
 - Setup attempts are globally rate limited before enrollment.
 - Permission auto-accept is an explicit server policy, never an assumption based on an open browser.
 - Questions are never auto-answered.
 - Unknown, malformed, concurrent, or unverifiable lifecycle state fails closed.
 - The inference proxy's confined listener is a Unix socket of the proxy's user alone; it accepts only confined runs'
-  credentials and serves them only the Claude pool's three Claude Code endpoints.
+  credentials and serves them only Claude Code's three endpoints of the run's pool, the Claude pool or, translated, the
+  ChatGPT pool's ChatGPT accounts.
 
 The global **auto-accept permissions (yolo)** setting replies once to pending permissions across registered projects and writes those replies to the audit log. Each conversation also has a run-local Ask/Yolo switch. For an active managed OpenCode root, that switch covers its currently active direct children under the same exact family authority. For an active managed Flex root, it covers admitted descendants through their exact active parent-run authority chain; a relationship alone grants nothing. Terminal children are never auto-accepted. Disabling either policy seals new automatic replies and drains already admitted replies before returning. Neither mode creates persistent broad provider grants.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: 'agl',
-  version: '41.0.1',
+  version: '41.2.0',
   description: 'Agent Gateway Layer for OpenCode, FlexHarness, and Codex sessions'
 }

package/ts/aglapi/aglapisurface.document.ts

@@ -3765,11 +3765,15 @@ export const AGL_API_SURFACE: plugins.flexTypedRequest.IFlexTypedRequestSurface
           },
           "protocolVersion": {
             "type": "number",
-            "const": 46
+            "const": 47
           },
           "upgradeManagementVersion": {
             "type": "number"
           },
+          "managementProtocolVersion": {
+            "type": "number",
+            "description": "The protocol of the controller's loopback management endpoint (`controllerManagementProtocolVersion`); absent from a controller older than the endpoint, which is reached over its socket."
+          },
           "controllerPid": {
             "type": "number"
           },
@@ -3887,7 +3891,7 @@ export const AGL_API_SURFACE: plugins.flexTypedRequest.IFlexTypedRequestSurface
         ],
         "additionalProperties": false
       },
-      "declaration": "interface IControllerStatus {\n  packageName: string;\n  packageVersion: string;\n  protocolVersion: 46;\n  upgradeManagementVersion: number;\n  controllerPid: number;\n  processGroupId: number;\n  processFingerprint: string;\n  processMode: TControllerProcessMode;\n  lifecycleState: TControllerLifecycleState;\n  startedAt: number;\n  setupRequired: boolean;\n  /** Present when the controller runs as the systemd user unit (`agl service install`); absent for a detached or foreground one. */\n  serviceUnit?: \"agl-controller.service\";\n  /** The TLS mode of the runtime configuration the controller runs with; absent until it is resolved. */\n  tlsMode?: TControllerTlsMode;\n  upgrade?: IControllerUpgradeStatus;\n  /** AGL's inference proxy, by state only; details need a signed-in owner (`controller.proxy.status.get`). */\n  proxy?: { state: TControllerProxyState };\n  harnesses: Array<{\n    harnessId: TControllerSessionHarnessId;\n    pid?: number;\n    state: TControllerHarnessLifecycleState;\n    healthy: boolean;\n    version?: string;\n    supportsLocalAttachments?: boolean;\n    connectionMode?: 'local' | 'shared' | 'remote';\n    diagnostic?: IControllerCodexDiagnostic;\n    /** Codex only: automatic reconnection of this entry's profile to the local shared app-server. */\n    rejoin?: IControllerCodexRejoinStatus;\n    /**\n     * Codex only, on the controller status: every connected or required profile. The entry's\n     * `healthy` is then true only when each of them is, apart from a profile on an account Codex\n     * cannot run on now, listed `stopped` with an `account_unavailable` diagnostic that says why;\n     * its other members describe the default profile.\n     */\n    profiles?: IControllerCodexProfileStatus[];\n  }>;\n}"
+      "declaration": "interface IControllerStatus {\n  packageName: string;\n  packageVersion: string;\n  protocolVersion: 47;\n  upgradeManagementVersion: number;\n  /**\n   * The protocol of the controller's loopback management endpoint (`controllerManagementProtocolVersion`); absent\n   * from a controller older than the endpoint, which is reached over its socket.\n   */\n  managementProtocolVersion?: number;\n  controllerPid: number;\n  processGroupId: number;\n  processFingerprint: string;\n  processMode: TControllerProcessMode;\n  lifecycleState: TControllerLifecycleState;\n  startedAt: number;\n  setupRequired: boolean;\n  /** Present when the controller runs as the systemd user unit (`agl service install`); absent for a detached or foreground one. */\n  serviceUnit?: \"agl-controller.service\";\n  /** The TLS mode of the runtime configuration the controller runs with; absent until it is resolved. */\n  tlsMode?: TControllerTlsMode;\n  upgrade?: IControllerUpgradeStatus;\n  /** AGL's inference proxy, by state only; details need a signed-in owner (`controller.proxy.status.get`). */\n  proxy?: { state: TControllerProxyState };\n  harnesses: Array<{\n    harnessId: TControllerSessionHarnessId;\n    pid?: number;\n    state: TControllerHarnessLifecycleState;\n    healthy: boolean;\n    version?: string;\n    supportsLocalAttachments?: boolean;\n    connectionMode?: 'local' | 'shared' | 'remote';\n    diagnostic?: IControllerCodexDiagnostic;\n    /** Codex only: automatic reconnection of this entry's profile to the local shared app-server. */\n    rejoin?: IControllerCodexRejoinStatus;\n    /**\n     * Codex only, on the controller status: every connected or required profile. The entry's\n     * `healthy` is then true only when each of them is, apart from a profile on an account Codex\n     * cannot run on now, listed `stopped` with an `account_unavailable` diagnostic that says why;\n     * its other members describe the default profile.\n     */\n    profiles?: IControllerCodexProfileStatus[];\n  }>;\n}"
     },
     {
       "name": "IControllerTerminalResource",

package/ts/classes.authmodels.ts

@@ -69,6 +69,41 @@ const credentialTransports = new Set([
   'usb',
 ]);
 const auditEventTypes: ReadonlySet<string> = new Set(controllerAuditEventTypes);
+/**
+ * Any release's audit type, as the known ones are spelled: two or more dot-separated segments of lowercase letters,
+ * digits and inner hyphens, each starting with a letter (`session.pendingprompt.edit`,
+ * `provider.connection.activate-opencode`), at most 128 characters.
+ */
+const auditEventTypePattern = /^[a-z](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z](?:[a-z0-9-]*[a-z0-9])?)+$/;
+const auditEventTypeMaxLength = 128;
+const auditDetailsMaxDepth = 8;
+const auditDetailsMaxBytes = 4096;
+
+/** Plain JSON: plain objects, dense arrays, strings, finite numbers, booleans and null, nested at most `depthArg` deep. */
+const isBoundedPlainJson = (valueArg: unknown, depthArg: number): boolean => {
+  if (valueArg === null || typeof valueArg === 'string' || typeof valueArg === 'boolean') return true;
+  if (typeof valueArg === 'number') return Number.isFinite(valueArg);
+  if (depthArg < 1) return false;
+  if (Array.isArray(valueArg)) {
+    if (Object.getPrototypeOf(valueArg) !== Array.prototype) return false;
+    for (let index = 0; index < valueArg.length; index++) {
+      if (!Object.hasOwn(valueArg, index) || !isBoundedPlainJson(valueArg[index], depthArg - 1)) return false;
+    }
+    return Object.keys(valueArg).length === valueArg.length;
+  }
+  return isPlainObject(valueArg)
+    && Object.getOwnPropertySymbols(valueArg).length === 0
+    && Object.values(valueArg).every((entryArg) => isBoundedPlainJson(entryArg, depthArg - 1));
+};
+
+/**
+ * An audit event's `details`: this release never writes or reads them; a later release records what its own types
+ * add there. Bounded plain JSON: an object at most eight levels deep and 4 KiB serialized.
+ */
+const isAuditDetails = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  isPlainObject(valueArg)
+  && isBoundedPlainJson(valueArg, auditDetailsMaxDepth)
+  && Buffer.byteLength(JSON.stringify(valueArg), 'utf8') <= auditDetailsMaxBytes;
 const auditOutcomes = new Set(['attempted', 'succeeded', 'denied', 'failed']);
 const auditRetentionSeconds = 90 * 24 * 60 * 60;
 
@@ -206,10 +241,29 @@ const isStoredCredential = (valueArg: unknown): valueArg is IStoredPasskeyCreden
     && isBase64Url(valueArg.counterUpdateId, 32);
 };
 
+/**
+ * The stored runtime configuration names `gatewaySources`, which only a later release writes (`agl remote set` with
+ * gateway sources). This release cannot enforce them, so it refuses the document; the message names the one remedy.
+ */
+export class ControllerRuntimeConfigFromLaterReleaseError extends Error {
+  constructor(controllerPortArg: unknown) {
+    const port = isValidPort(controllerPortArg) ? String(controllerPortArg) : '<port>';
+    super(
+      `The stored runtime configuration of controller:${port} names gatewaySources, which a later AGL release set `
+      + 'and this release cannot enforce, so it does not start. Run '
+      + `\`agl remote unset --port ${port}\` on the later release before rolling back.`,
+    );
+    this.name = 'ControllerRuntimeConfigFromLaterReleaseError';
+  }
+}
+
 export const assertControllerAuthDocument = (
   valueArg: unknown,
 ): asserts valueArg is IControllerAuthDocument => {
   if (!isPlainObject(valueArg)) throw new Error('Invalid controller authentication document.');
+  if (isPlainObject(valueArg.config) && Object.hasOwn(valueArg.config, 'gatewaySources')) {
+    throw new ControllerRuntimeConfigFromLaterReleaseError(valueArg.config.controllerPort);
+  }
   if (
     !hasExactKeys(valueArg, [
       'id',
@@ -315,36 +369,48 @@ export const assertWebAuthnCeremonyDocument = (
   }
 };
 
+/**
+ * A stored audit event. The log is shared with later releases, so a type this release does not know (a later
+ * release's, read back after a rollback) is accepted when it is spelled as an audit type: its envelope is checked as
+ * strictly as a known type's, and only the rules that tie a field to particular types (`senderLabel` to
+ * `session.message`, `localCli` to `configuration.*`) are left to the release that knows the type. A known type keeps
+ * every check. `details` is bounded plain JSON on any type.
+ */
 export const assertControllerAuditEventDocument = (
   valueArg: unknown,
 ): asserts valueArg is IControllerAuditEvent => {
   if (!isPlainObject(valueArg)) throw new Error('Invalid controller audit event.');
+  const type = valueArg.type;
+  if (typeof type !== 'string' || type.length > auditEventTypeMaxLength || !auditEventTypePattern.test(type)) {
+    throw new Error('Invalid controller audit event.');
+  }
+  const known = auditEventTypes.has(type);
   if (
     !hasExactKeys(
       valueArg,
       ['id', 'controllerId', 'timestamp', 'type', 'outcome'],
-      ['operationId', 'peerId', 'credentialId', 'sessionId', 'requestId', 'senderLabel', 'localCli'],
+      ['operationId', 'peerId', 'credentialId', 'sessionId', 'requestId', 'senderLabel', 'localCli', 'details'],
     )
     || !isBase64Url(valueArg.id, 32)
     || !isNonEmptyString(valueArg.controllerId)
     || !/^controller:[1-9][0-9]{0,4}$/.test(valueArg.controllerId)
     || Number(valueArg.controllerId.slice('controller:'.length)) > 65535
     || !isValidDate(valueArg.timestamp)
-    || !auditEventTypes.has(valueArg.type as string)
     || !auditOutcomes.has(valueArg.outcome as string)
     || (
       Object.hasOwn(valueArg, 'operationId')
-      && !isBase64Url(valueArg.operationId, valueArg.type === 'resource.browser.operation' ? 18 : 24)
+      && !isBase64Url(valueArg.operationId, type === 'resource.browser.operation' ? 18 : 24)
     )
     || (
       Object.hasOwn(valueArg, 'senderLabel')
-      && (valueArg.type !== 'session.message' || !isControllerAgentMessageSender(valueArg.senderLabel))
+      && ((known && type !== 'session.message') || !isControllerAgentMessageSender(valueArg.senderLabel))
     )
+    || (Object.hasOwn(valueArg, 'details') && !isAuditDetails(valueArg.details))
   ) {
     throw new Error('Invalid controller audit event.');
   }
   if (Object.hasOwn(valueArg, 'localCli')) {
-    if (!(valueArg.type as string).startsWith('configuration.')) throw new Error('Invalid local configuration audit event.');
+    if (known && !type.startsWith('configuration.')) throw new Error('Invalid local configuration audit event.');
     assertConfigurationLocalCliActor(valueArg.localCli);
   }
   for (const optionalKey of [
@@ -1919,4 +1985,7 @@ export class ControllerAuditEventModel
 
   @plugins.nosqldb.svDb()
   public localCli?: IControllerAuditEvent['localCli'];
+
+  @plugins.nosqldb.svDb()
+  public details?: IControllerAuditEvent['details'];
 }

package/ts/classes.authstore.ts

@@ -44,6 +44,7 @@ import {
 import {
   ControllerAuditEventModel,
   ControllerAuthModel,
+  ControllerRuntimeConfigFromLaterReleaseError,
   ControllerPendingPromptModel,
   ControllerProjectModel,
   ControllerResourceModel,
@@ -202,6 +203,24 @@ const auditPruneMaxBatchesPerSweep = 50;
 const auditCountPruneMaxBatchesPerSweep = 250;
 const auditPruneIntervalMs = 30 * 60 * 1000;
 
+/**
+ * The stored authentication document of `controllerIdArg`. A runtime configuration only a later release writes is
+ * refused with its own reason (`ControllerRuntimeConfigFromLaterReleaseError`), not the client's generic assertion
+ * failure, so the operator reads the remedy.
+ */
+const findStoredAuthDocument = async (
+  controllerIdArg: string,
+): Promise<plugins.nosqldb.TStoredDocument<IControllerAuthDocument> | null> => {
+  try {
+    return await ControllerAuthModel.exact.findStoredOne({ id: controllerIdArg });
+  } catch (errorArg) {
+    if (errorArg instanceof Error && errorArg.cause instanceof ControllerRuntimeConfigFromLaterReleaseError) {
+      throw errorArg.cause;
+    }
+    throw errorArg;
+  }
+};
+
 /** A concurrent prune that removed an event first leaves nothing to do for it. */
 const deleteStoredAuditEvents = async (
   eventsArg: Array<plugins.nosqldb.TStoredDocument<IControllerAuditEvent>>,
@@ -1306,7 +1325,7 @@ export class SmartDataAuthStore implements IAuthStore, IAuthStoreSessionIdentity
       throw new Error('controllerPort must be an integer between 1 and 65535.');
     }
     this.controllerId = `controller:${controllerPortArg}`;
-    const stored = await ControllerAuthModel.exact.findStoredOne({ id: this.controllerId });
+    const stored = await findStoredAuthDocument(this.controllerId);
     if (!stored) return undefined;
     return cloneRuntimeConfig(ControllerAuthModel.exact.toPersisted(stored).config);
   }
@@ -1336,7 +1355,7 @@ export class SmartDataAuthStore implements IAuthStore, IAuthStoreSessionIdentity
     }
     const controllerId = `controller:${runtimeConfigArg.controllerPort}`;
     this.controllerId = controllerId;
-    const existing = await ControllerAuthModel.exact.findStoredOne({ id: controllerId });
+    const existing = await findStoredAuthDocument(controllerId);
     if (existing) {
       const document = ControllerAuthModel.exact.toPersisted(existing);
       return this.finalizeRuntimeConfigDocument(document, runtimeConfigArg);
@@ -1356,7 +1375,7 @@ export class SmartDataAuthStore implements IAuthStore, IAuthStoreSessionIdentity
       return this.finalizeRuntimeConfigDocument(document, runtimeConfigArg);
     } catch (errorArg) {
       if (!isAmbiguousWrite(errorArg)) throw errorArg;
-      const reconciled = await ControllerAuthModel.exact.findStoredOne({ id: controllerId });
+      const reconciled = await findStoredAuthDocument(controllerId);
       if (!reconciled) {
         throw new AuthError(
           'ambiguous_write',
@@ -2326,7 +2345,7 @@ export class SmartDataAuthStore implements IAuthStore, IAuthStoreSessionIdentity
     if (!this.controllerId) {
       throw new AuthError('not_initialized', 'The controller runtime configuration is unresolved.');
     }
-    const stored = await ControllerAuthModel.exact.findStoredOne({ id: this.controllerId });
+    const stored = await findStoredAuthDocument(this.controllerId);
     if (!stored) {
       throw new AuthError('not_initialized', 'The controller authentication document is missing.');
     }
@@ -5297,6 +5316,7 @@ export class SmartDataAuthStore implements IAuthStore, IAuthStoreSessionIdentity
       && leftArg.credentialId === rightArg.credentialId
       && leftArg.senderLabel === rightArg.senderLabel
       && JSON.stringify(leftArg.localCli) === JSON.stringify(rightArg.localCli)
+      && JSON.stringify(leftArg.details) === JSON.stringify(rightArg.details)
       && (
         leftArg.sessionId === undefined
           ? rightArg.sessionId === undefined

package/ts/classes.cli.ts

@@ -6,6 +6,7 @@ import {
   controllerProtocolVersion,
   controllerServiceUnitName,
   controllerUpgradeManagementVersion,
+  controllerManagementProtocolVersion,
   configurationOwnerTokenEnvironmentVariable,
   describeBrowserPaintAvailability,
   type IControllerStatus,
@@ -39,6 +40,7 @@ import {
   stopRunningController,
   tryQueryControllerStatus as tryQueryManagedControllerStatus,
   waitUntilControllerExited,
+  type IControllerStatusQuery,
 } from './classes.controllermanagement.js';
 import {
   inspectControllerProcess,
@@ -409,11 +411,16 @@ export const parseRuntimeOverrides = (
   };
 };
 
-const currentStatusExpectation = {
+/**
+ * The CLI manages the controller of its own package, so it reads that controller's status over the transport its own
+ * `package.json` declares (`controllerManagementProtocolVersion`, which this build's constant equals).
+ */
+const currentStatusExpectation: IControllerStatusQuery = {
   packageName: controllerPackageName,
   packageVersion: commitinfo.version,
   protocolVersion: controllerProtocolVersion,
   upgradeManagementVersion: controllerUpgradeManagementVersion,
+  managementProtocolVersion: controllerManagementProtocolVersion,
 };
 
 const assertStatus = (statusArg: unknown): IControllerStatus => assertControllerStatus(
@@ -1780,7 +1787,7 @@ const upgradeController = async (argvArg: TParsedArguments): Promise<void> => {
             controller: payload.expectedController!,
           });
           try {
-            const launched = await requestControllerUpgradeLaunch(port, payload.token);
+            const launched = await requestControllerUpgradeLaunch(port, status, payload.token);
             worker = {
               pid: launched.workerPid,
               cliPath: installation.cliPath,