Merge train round 3 B5: GLM summary budget, skills catalog snapshots, Command Code 429 wait, remote session docs

devlog/_plan/260927_merge_train_3/050_batch5.md

@@ -0,0 +1,55 @@
+# B5 — narrowed carries, a Command Code retry default, and evidence-backed closes
+
+Base: `dev` `4b3737fc5c` (after B4 #6063). Branch `codex/train3-b5`.
+
+Previous D (B4): #6043 landed; #6044 held on its security blocker, #6051 on the owner's `.agents/` decision. The
+coordinator asked the lane to continue until nothing in scope is landable.
+
+| Item | Plan |
+|---|---|
+| #5953 (codingbooo) → #5465 | Carry, then narrow `protectGlmSummaryBudget` as the maintainer round asked: Z.AI host only (from the provider base URL), caller effort `high`/`max` only, the checkpoint shape (summary instruction plus a `<conversation>` transcript of at least 2000 characters), and each tiny cap field (≤1024) raised on its own to 8192. Negative tests for each boundary. |
+| #5180 (issue, found through Aside) | With no `retryOn429` knob, a key-auth Command Code destination gets the patient same-key policy OpenCode Go already has, so a burst 429 on a long turn waits (honoring Retry-After) instead of failing to the client. An explicit `retryOn429`, including `enabled: false`, still wins; OAuth is never replayed. |
+| #6027 (codingbooo) → #5569 | Carry, then fix the owner's three blockers: replace only when the whole body carries exactly one `<skills_instructions>` block (otherwise pass through); store a new snapshot only after `prepareResponsesRequest` reaches its success return, so a rejected first request pins nothing; share a snapshot without a principal only for loopback admission. Tests for each. |
+| #4055 | Close as fixed for the reported Tailscale Serve case (12-hour identity sessions with sliding renewal, #2776), and correct the stale `management-api.md` sentence that says remote binds never get a session. |
+| #3433 | Close with evidence: per-conversation identifiers are preserved at the forward boundary (#4365) and the managed Hermes export now sends one (#5742); 26 pinned tests pass. |
+
+Held: #6030 (draft; launchd PATH adoption drops non-PATH changes, two ratchet breaches, WinSW gap, conflict),
+#4143 (needs the reporter's desktop routing details).
+
+## Audit (Kimi, NEAR-PASS) and folded decisions
+
+- #5180: the predicate is key auth plus the existing `isCanonicalCommandCodeBaseUrl`; a row repointed at a custom
+  relay keeps fail-fast unless `retryOn429` is set.
+- #6027: `snapshotSkillsCatalogInBody` splits into a replace-only lookup before parsing and a store call at the
+  success return. Residuals named in the PR: a snapshot can be pinned by a turn whose upstream request later fails;
+  on a no-auth server bound beyond loopback, snapshots are keyed by conversation id alone, matching that server's
+  trust model.
+- #5953: the gate reads effective effort after combo overrides; transcript shapes that #5465 does not show stay
+  unprotected, which is today's behavior.
+
+## Build and evidence
+
+| Commit | What |
+|---|---|
+| `4fda15d338` | #5180: canonical key-auth Command Code gets the patient same-key 429 policy; test fails without the fix |
+| `3876151d01` | #5953 carried |
+| `fb3faab205` | #5953 narrowed: Z.AI host, effective `high`/`max`, checkpoint transcript ≥ 2000 characters, per-field cap raise to 8192; negative tests per boundary |
+| `25e01a8e2b` | #6027 carried (layout registries unioned, entry kept on an existing line) |
+| `01b7e24d2d` | #6027 blockers: one-block rule, store at the success return, anonymous sharing only on a no-auth server; three tests that fail on the PR head |
+| `ad3b374820`, `2256d097e6` | `management-api.md` describes remote dashboard sessions as shipped (#4055) |
+
+Closed during this cycle with evidence: #3433 (identifiers preserved at the forward boundary, #4365; managed Hermes
+sends one, #5742; 26 pinned tests pass).
+
+Aside: #5953 shows two CHANGES_REQUESTED reviews (the overbreadth this batch narrows); #6027 shows the owner's
+three-blocker review this batch answers; #5465, #5569 and #5180 pages captured. One Aside capture failed once with a
+daemon `Aside.controlTab` error after an Aside update and succeeded on retry.
+
+Local proof at `2256d097e6`: typecheck, structure and privacy exit 0; six focused files 60 pass; `tests/adapters/openai`
+591 pass; eight request-preparation files 108 pass. The full `tests/responses` directory shows 13 failures in
+`responses-compaction-recovery.test.ts` that do not reproduce when that file runs alone (33 pass on this branch and on
+`dev`); the same directory run on `dev` is recorded below.
+
+The full `tests/responses` run on `dev` `4b3737fc5c` shows the same 13 `responses-compaction-recovery` failures
+(3567 pass, 13 fail), so they are cross-file interference in a directory run, not this batch; the branch run was 3576
+pass, 13 fail.

docs-site/src/content/docs/guides/codex-prompt.md

@@ -169,6 +169,37 @@ repair writes a backup before it touches anything.
 Changes apply to newly started sessions. A session already running keeps the
 prompt settings it started with.
 
+## Keeping the skills catalog stable
+
+The proxy defaults to `skills.catalog_refresh: "per_session"`: the first
+`<skills_instructions>` catalog received for a conversation is reused on later
+requests in that conversation. This keeps skill discovery and `SKILL.md` edits
+from changing that part of the upstream prompt cache prefix mid-session.
+A request that carries more than one `<skills_instructions>` block is passed
+through unchanged, and a request the proxy rejects does not set the catalog.
+
+To use the catalog supplied by the client on every turn, set this in opencodex's
+`$OPENCODEX_HOME/config.json` (normally `~/.opencodex/config.json`), then restart
+the proxy:
+
+```json
+{
+  "skills": {
+    "catalog_refresh": "per_turn"
+  }
+}
+```
+
+The supported values are `"per_session"` (default) and `"per_turn"`. This is a
+proxy setting, separate from Codex's `skills.include_instructions` toggle.
+Requests without a reliable conversation identity use the catalog supplied by
+the client. Snapshots are held in memory and do not survive a proxy restart.
+They expire after four hours of inactivity and may be evicted when the bounded
+cache fills. An initial catalog block larger than 512 KiB is forwarded without caching.
+After expiry or eviction, the next received catalog becomes the new snapshot.
+The dashboard's prompt preview still reads the current files; it does not show
+the snapshot retained for an ongoing conversation.
+
 ## What this page reads, and what it does not
 
 opencodex reads one configuration file — your `config.toml`. Codex resolves its

docs-site/src/content/docs/reference/configuration/agents.md

@@ -8,6 +8,15 @@ routes, and limits delegated work.
 
 ## Agent fields
 
+### Skills catalog refresh
+
+`skills.catalog_refresh` accepts `"per_session"` (the default) or `"per_turn"`
+in opencodex's `config.json`. Session mode reuses the first received skills
+instructions for a conversation, protecting the prompt cache prefix from catalog
+changes between turns. Turn mode forwards the client's current catalog.
+See [Keeping the skills catalog stable](/guides/codex-prompt/#keeping-the-skills-catalog-stable)
+for configuration and snapshot lifetime details.
+
 ### Astra roster upgrade
 
 On the first start after upgrading, existing `subagentModels` lists receive

docs-site/src/content/docs/reference/configuration/providers.md

@@ -267,7 +267,7 @@ Providers can expose a built-in shorthand, such as `agy` for `google-antigravity
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | Disabled-by-default downstream SSE repair for exact placeholder ids, missing terminal ids, and (with `repairInvalidIds`) message/reasoning ids missing the canonical `msg_`/`rs_` prefix. Function-call ids are never rewritten. Built-in DeepSeek enables the last two by default. |
 | `responsesSnapshotRepair?` | `boolean` | Disabled-by-default client-facing repair for sparse Responses lifecycle snapshots in SSE and JSON. Fills missing canonical status, output, and tool metadata while raw inspection and persistence remain unchanged. |
 | `webSearchBridge?` | `{ enabled?: boolean; backend?: "ollama" \| "openai" \| "anthropic" \| "xai" \| "gemini" \| "exa"; maxSearches?: number; timeoutMs?: number; endpoint?: string }` | Key-auth `openai-responses` passthrough providers only. Off by default. Codex always declares the hosted `web_search` tool, and the passthrough relays it on the assumption the destination executes it. A gateway that does not run hosted search answers with a `function_call` named `web_search` that nothing runs, and the undeclared-tool guard ends the turn. With `enabled: true` and an explicit `backend` OpenCodex intercepts that call, runs the search itself, feeds the result back to the same upstream, and shows Codex a hosted `web_search_call` cell. Never armed for `authMode: "forward"` (ChatGPT already searches) or for a provider that executes hosted search upstream. `backend` is required; there is no implicit default and a missing credential for the named backend leaves the bridge disarmed rather than falling through to another paid search. `ollama` reuses this provider's own API key on `POST <origin>/api/web_search`, so the origin must be `https://ollama.com` unless the operator names `endpoint` explicitly. `openai` / `anthropic` / `xai` / `gemini` / `exa` reuse the matching sidecar executor and that executor's own credential (`webSearchSidecar.exaApiKey` for Exa). The search model comes from `webSearchSidecar.model` only when `webSearchSidecar.backend` resolves to the same backend this bridge names; otherwise the bridge runs that backend's own default, because a model chosen for one vendor is rejected by another. An unset `webSearchSidecar.backend` resolves to `openai`, so an unset-backend model reaches an `openai` bridge and no other. There is no per-provider bridge model override. Streaming turns only. A turn that mixes `web_search` with another client tool call still fails closed rather than dropping the client's call. Assistant text such as XML-like `<web_search>` prose is not executed. Defaults: `maxSearches: 3` (1..10), `timeoutMs: 60000` (1000..600000). |
-| `retryOn429?` | `{ enabled?: boolean; attempts?: number; intervalMs?: number; maxIntervalMs?: number; respectRetryAfter?: boolean }` | API-key providers only (`authMode: "key"`). Opt-in same-target 429 retry: when `retryOn429` is absent the feature is off; object presence enables it unless `enabled: false`. On 429 the proxy waits (upstream `Retry-After` or the fixed interval) and replays the identical request on the same key before any key failover — across the main text-turn recovery loop, the Responses passthrough wire, the image/video bridge, the web-search sidecar, and terminal continuations. Only pre-stream HTTP 429 responses are eligible for replay; custom `runTurn` transports are outside the HTTP retry loop. `attempts` counts same-key replays after the first 429 (total sends = `attempts` + 1) and is one request-wide budget shared by the main recovery loop, the terminal-guard continuation, and bridge retries. Exhausting `attempts` only stops further same-key replays: normal key failover or final-error handling then applies per the available targets — on the key-auth passthrough wire there is no failover, so the exhausted 429 surfaces as-is. Codex itself never retries 429, so this is the only defense for single-key providers. Defaults: `enabled: true`, `attempts: 3`, `intervalMs: 5000`, `maxIntervalMs: 60000` (any single wait is capped at `maxIntervalMs`, itself capped at 600000), `respectRetryAfter: true`. |
+| `retryOn429?` | `{ enabled?: boolean; attempts?: number; intervalMs?: number; maxIntervalMs?: number; respectRetryAfter?: boolean }` | API-key providers only (`authMode: "key"`). Opt-in same-target 429 retry: when `retryOn429` is absent the feature is off, except that key-auth OpenCode Go and Command Code (canonical endpoints) fall back to a patient policy (6 replays, 10 s interval, 60 s cap); object presence enables it unless `enabled: false`, which also turns that fallback off. On 429 the proxy waits (upstream `Retry-After` or the fixed interval) and replays the identical request on the same key before any key failover — across the main text-turn recovery loop, the Responses passthrough wire, the image/video bridge, the web-search sidecar, and terminal continuations. Only pre-stream HTTP 429 responses are eligible for replay; custom `runTurn` transports are outside the HTTP retry loop. `attempts` counts same-key replays after the first 429 (total sends = `attempts` + 1) and is one request-wide budget shared by the main recovery loop, the terminal-guard continuation, and bridge retries. Exhausting `attempts` only stops further same-key replays: normal key failover or final-error handling then applies per the available targets — on the key-auth passthrough wire there is no failover, so the exhausted 429 surfaces as-is. Codex itself never retries 429, so this is the only defense for single-key providers. Defaults: `enabled: true`, `attempts: 3`, `intervalMs: 5000`, `maxIntervalMs: 60000` (any single wait is capped at `maxIntervalMs`, itself capped at 600000), `respectRetryAfter: true`. |
 | `transientRetryOn5xx?` | `{ enabled?: boolean; attempts?: number }` | Key-auth `openai-chat` and `openai-responses` providers only. `authMode: "forward"` providers (the ChatGPT account pool) never read this option and keep the default ladder. Opt-in retry for pre-stream transient upstream statuses (500, 502, 503, 504, 520, 521, 522): absent means off, object presence enables it unless `enabled: false`. Covers the initial Responses request, the Responses passthrough lane and each of its recovery legs (OAuth-401 replay, same-target 429 replay, validated rebuild), the terminal-guard continuation, and native `/v1/chat/completions`. `attempts` is the TOTAL number of upstream sends allowed for one request including the first (1..10, default 3) — it is one budget shared with connection-reset recovery, so `3` means at most three real requests reach the provider. On the Responses passthrough lane the configured value is additionally intersected with the request-wide send allowance, so a value below that allowance narrows the ladder exactly while a value above it does not raise the bound. Waits use a fixed 400 ms exponential backoff capped at 5 s and honor `Retry-After`. Separate from `retryOn429`, which handles rate limiting; mid-stream failures are never replayed. |
 | `retryOnReset?` | `{ enabled?: boolean; replacements?: number }` | Native `openai-responses` providers, including `authMode: "forward"`. Opt-in replacement of a send that failed while the caller had observed nothing: absent means off, object presence enables it unless `enabled: false`. Covers both ambiguous stages — a connection that died before any response header, and an SSE body that died after the header while carrying only control events. A canonical ChatGPT upstream WebSocket that closed or errored after its create frame left, before any Responses event, is covered the same way, and its replacement is sent over HTTP. Only a self-contained request is ever replaced: `store: false`, complete `input`, no `previous_response_id`, `conversation` or `stream_id`, and only client-executed tools. `replacements` is the number of replacement sends ONE logical request may make across every leg and every combo child (1..2, default 1) — not a per-leg retry count and not a send budget, so a replacement still has to fit inside the send allowance the leg already had. A request that already emitted output or a tool call is never replaced, whatever this is set to. The replacement inference may still be billed if the origin had already started the first one, which is why this is off by default. |
 | `autoToolChoiceOnlyModels?` | `string[]` | Models whose `tool_choice` accepts only `auto` or `none`; forced choices are downgraded. |

docs-site/src/content/docs/reference/management-api.md

@@ -45,9 +45,12 @@ On a loopback bind, the dashboard bootstrap can receive a short-lived `ocx_sessi
 Each session lasts five minutes and is bound to the exact dashboard origin. Safe requests must
 match that origin. Unsafe methods also require the browser `Origin` and the session's CSRF token.
 
-Session issuance is disabled whenever data-plane authentication is required, which includes remote
-binds. A remote operator must authenticate with the raw admin token; no loopback-style GUI session
-is minted.
+When data-plane authentication is required, which includes remote binds, the loopback bootstrap
+does not mint a session. A remote dashboard gets a 12-hour session only through a trusted Tailscale
+identity (`remoteGui.allowedTailscaleUsers` on the Tailscale management ingress) or a one-use
+pairing grant; each authorized request extends it. Otherwise a remote operator authenticates with
+the raw admin token, and the dashboard asks for it again after a reload because the session lives
+only in page memory. See [Remote hub](/guides/remote-hub/).
 
 ## Common errors
 

scripts/test-layout/layout.json

@@ -173,7 +173,7 @@
     "cli-kiro-auto-selection.test.ts": "cli", "codebuddy-live-models.test.ts": "providers", "kiro-auto-selection.test.ts": "providers/kiro", "kiro-quota-metrics.test.ts": "providers/kiro", "management-provider-request-pacing.test.ts": "server",
     "desktop-supervised-restart.test.ts": "clients", "cli-restart-handoff.test.ts": "cli",
     "restart-replacement.test.ts": "server", "deepseek-artifact-tool-schema.test.ts": "providers",
-    "client-config-export-output-limit.test.ts": "config",
+    "client-config-export-output-limit.test.ts": "config", "responses-skills-snapshot.test.ts": "responses",
     "openai-chat-serialized-tool-call-scaling.test.ts": "adapters/openai",
     "openai-chat-tool-call-id-remint.test.ts": "adapters/openai",
     "coding-agent-json-lines-scaling.test.ts": "providers",

src/adapters/openai-chat.ts

@@ -1,11 +1,12 @@
 import { hasShrinkableOpenAIChatImages, normalizeOpenAIChatImages } from "./openai-chat-images";
+import { protectGlmSummaryBudget, resolveMaxTokens } from "./openai-chat/summary-budget";
 import { chatParallelToolCallsWireValue } from "./openai-chat/parallel-tool-calls";
 import { applyExplicitChatReasoningWirePolicy } from "./openai-chat/reasoning-wire";
 import type { AdapterRequest, IncomingMeta, ProviderAdapter } from "./base";
 import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig, OcxUsage } from "../types";
 import { modelInList } from "../types";
 import { createInlineThinkContentSplitter, splitInlineThinkContent } from "./inline-think-tags";
-import { mapReasoningEffort, modelRecordValue } from "../reasoning-effort";
+import { mapReasoningEffort } from "../reasoning-effort";
 import { debugProviderDiagnostic } from "../lib/debug";
 import { sseFieldValue } from "../lib/sse-decoder";
 import { isDebugEnabled } from "../lib/debug-settings";
@@ -51,12 +52,6 @@ export { stripBracketedModelSuffix } from "./openai-chat/wire";
 export { buildOpenAIChatPassthroughRequest } from "./openai-chat/passthrough";
 export { formatOpenAIChatErrorBody } from "./openai-chat/errors";
 
-function resolveMaxTokens(provider: OcxProviderConfig, parsed: OcxParsedRequest): number | undefined {
-  return parsed.options.maxOutputTokens
-    ?? modelRecordValue(provider.modelMaxOutputTokens, parsed.modelId)
-    ?? provider.defaultMaxOutputTokens;
-}
-
 function thinkingBudgetForEffort(parsed: OcxParsedRequest, reasoningEffort: string, maxOutputTokens?: number): number | undefined {
   if (parsed.options.reasoning === "minimal") return 0;
   const maxBudget = maxOutputTokens ?? 32768;
@@ -150,12 +145,14 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
           body.stop = parsed.options.stopSequences;
         }
         const reasoningDisabled = modelInList(provider.noReasoningModels, parsed.modelId);
-        const reasoningEffort = mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning);
+        const requestedEffort = protectGlmSummaryBudget(body, provider.baseUrl, parsed.options.reasoning)
+          ? "low" : parsed.options.reasoning;
+        const reasoningEffort = mapReasoningEffort(provider, parsed.modelId, requestedEffort);
         const explicitReasoning = applyExplicitChatReasoningWirePolicy({
           provider,
           modelId: parsed.modelId,
           hasTools: !!tools,
-          requestedEffort: parsed.options.reasoning,
+          requestedEffort,
           wireEffort: reasoningEffort,
           reasoningDisabled,
           body,