@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/server/responses/ws-upstream.ts

@@ -29,33 +29,14 @@ export { CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_M
 export const MIN_BOUNDED_CODEX_WS_BUN_VERSION = "1.4.0";
 
 /**
- * Dial URL for a request URL. The canonical ChatGPT backend keeps its constant;
- * an operator-opted OpenAI-compatible upstream swaps https for wss on the same
- * path so gateways that serve the Responses WebSocket protocol on their
- * /v1/responses path get the same fast lane. Plain HTTP remains on SSE because
- * a provider WS handshake would otherwise send credentials and request data
- * without transport encryption.
+ * Dial URL for a first-party Responses endpoint. The canonical ChatGPT backend
+ * keeps its constant; the api.openai.com Responses endpoint swaps https for wss
+ * on the same path. No other upstream may enter the WebSocket lane.
  */
 function wsUpstreamUrlFor(httpUrl: string): string {
   if (httpUrl === CODEX_RESPONSES_HTTP_URL) return CODEX_RESPONSES_WS_URL;
-  return httpUrl.replace(/^http(s?):/, "ws$1:");
-}
-
-/**
- * An operator-opted OpenAI-compatible upstream only joins the WS lane for
- * Responses endpoints: the WebSocket path speaks the Responses event protocol,
- * and every downstream consumer (adapter parsers, usage sniffing, SSE relay)
- * assumes that wire. Other paths (chat completions, images, search) stay HTTP.
- */
-function isResponsesWebsocketEligibleUrl(url: string): boolean {
-  let parsed: URL;
-  try {
-    parsed = new URL(url);
-  } catch {
-    return false;
-  }
-  return parsed.protocol === "https:"
-    && parsed.pathname.endsWith("/responses");
+  if (httpUrl === OPENAI_API_RESPONSES_URL) return httpUrl.replace(/^http(s?):/, "ws$1:");
+  throw new Error("unsupported Codex WebSocket upstream");
 }
 export type BunRuntimeIdentity = {
   version: string;
@@ -108,8 +89,13 @@ export function shouldUseCodexWsUpstream(
 ): boolean {
   if (!bunSupportsBoundedCodexWsRelay(runtime)) return false;
   if (socks5ProxyFromEnv()) return false;
-  if (url !== CODEX_RESPONSES_HTTP_URL && !upstreamWebsocketConfigured) return false;
-  if (upstreamWebsocketConfigured && !isResponsesWebsocketEligibleUrl(url)) return false;
+  // Bun's client WebSocket API delivers only fully assembled messages and has
+  // no enforceable inbound payload limit. Keep arbitrary provider endpoints on
+  // bounded HTTP/SSE until the client can reject fragmented text and binary
+  // messages during ingestion rather than after allocation. The first-party
+  // api.openai.com lane still requires the operator opt-in.
+  if (url !== CODEX_RESPONSES_HTTP_URL
+    && !(upstreamWebsocketConfigured && url === OPENAI_API_RESPONSES_URL)) return false;
   if ((init?.method ?? "GET").toUpperCase() !== "POST") return false;
   const body = init?.body;
   if (typeof body !== "string") return false;
@@ -139,7 +125,8 @@ export function codexWsUpstreamFetch(
   const prepared = prepareCodexWsRequest(url, init);
   if (!prepared) return sseFallback(url, prepareCodexHttpInit(url, init));
   init = prepared.httpInit;
-  if (!bunSupportsBoundedCodexWsRelay(runtime)) {
+  if ((url !== CODEX_RESPONSES_HTTP_URL && url !== OPENAI_API_RESPONSES_URL)
+    || !bunSupportsBoundedCodexWsRelay(runtime)) {
     return sseFallback(url, init);
   }
   const signal = init.signal ?? undefined;

package/src/server/responses-custom-tool-repair.ts

@@ -1,6 +1,7 @@
 import type { TranslatorBudget } from "../lib/translator-budget";
 import { mayBecomePatchEnvelope, normalizeApplyPatchDelimiters } from "../responses/apply-patch-envelope";
 import { compileCodeModeHelperInput, resolveCodeModeHelperName } from "../responses/code-mode-helper-compat";
+import { progressiveFreeformInput } from "../responses/progressive-freeform-input";
 import { declaresCodeModeExec } from "../types/tools";
 import {
   customToolItemId,
@@ -15,50 +16,10 @@ import {
   type SseBlockRewrite,
 } from "./sse-payload-rewrite";
 
-/** Exact compact prefix used by our upstream rewriter; progressive matching also
- *  tolerates insignificant JSON whitespace via FREEFORM_WRAP_PREFIX_RE. */
-const FREEFORM_WRAP_PREFIX = '{"input":"';
-const FREEFORM_WRAP_PREFIX_RE = /^\s*\{\s*"input"\s*:\s*"/;
-
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
-/**
- * Progressive decode of the freeform `{ "input": "…" }` wrapper.
- * Returns null when the accumulated text does not (yet) match that wrapper so
- * callers suppress deltas and rely on `response.custom_tool_call_input.done`.
- */
-function partialCustomToolInput(argumentsText: string): string | null {
-  const match = FREEFORM_WRAP_PREFIX_RE.exec(argumentsText);
-  if (!match) return null;
-  const body = argumentsText.slice(match[0]!.length);
-  let output = "";
-  for (let index = 0; index < body.length; index++) {
-    const char = body[index];
-    if (char === '"') break;
-    if (char !== "\\") {
-      output += char;
-      continue;
-    }
-    const escaped = body[index + 1];
-    if (escaped === undefined) break;
-    index += 1;
-    if (escaped === "n") output += "\n";
-    else if (escaped === "t") output += "\t";
-    else if (escaped === "r") output += "\r";
-    else if (escaped === "b") output += "\b";
-    else if (escaped === "f") output += "\f";
-    else if (escaped === "u") {
-      const hex = body.slice(index + 1, index + 5);
-      if (hex.length !== 4 || !/^[0-9a-fA-F]{4}$/.test(hex)) break;
-      output += String.fromCharCode(Number.parseInt(hex, 16));
-      index += 4;
-    } else output += escaped;
-  }
-  return output;
-}
-
 function replaceSseEventName(block: string, type: string): string {
   const newline = block.includes("\r\n") ? "\r\n" : "\n";
   const lines = block.split(/\r?\n/);
@@ -332,21 +293,33 @@ export function createRoutedCustomToolRestoreBlockRewrite(
       openCalls.set(upstreamItemId, open);
       // A helper alias will become JavaScript at completion, never raw patch/JSON.
       if (itemNames.get(upstreamItemId)?.aliased) return [];
-      // Still accumulating toward the compact wrapper, or an unrecognized shape:
-      // suppress progressive emission and let the done event carry input.
-      if (FREEFORM_WRAP_PREFIX.startsWith(open.argumentsText)) return [];
-      const fullInput = partialCustomToolInput(open.argumentsText);
+      const itemName = itemNames.get(upstreamItemId);
+      const ownsFreeformGrammar = itemName?.namespace === undefined
+        || itemName?.namespace === "functions";
+      const fullInput = progressiveFreeformInput(
+        open.argumentsText,
+        ownsFreeformGrammar ? itemName?.name ?? "" : "",
+      );
       if (fullInput === null) return [];
-      // Hold a buffer that could still become a complete patch envelope. The done event
-      // recompiles such a body into an apply_patch helper call, so streaming the envelope
-      // bytes first and replacing them at completion is the rewind this path forbids.
-      // Mirrors the same hold in `src/bridge.ts`.
-      if (
-        declaresCodeModeExec(declaredNames)
-        && itemNames.get(upstreamItemId)?.namespace === undefined
-        && itemNames.get(upstreamItemId)?.name === "exec"
-        && mayBecomePatchEnvelope(fullInput)
-      ) return [];
+      // This routed path historically holds every unrecognized JSON object until done.
+      // The shared decoder streams ordinary raw input, so retain the stricter routed rule
+      // when no recognized wrapper transformed the accumulated object.
+      if (fullInput === open.argumentsText && open.argumentsText.trimStart().startsWith("{")) return [];
+      // Hold a buffer that could still become a complete patch envelope, for either of the two
+      // reasons completion rewrites one. Both are the same rewind this path forbids, and both
+      // mirror `src/bridge/sse.ts`.
+      //
+      // `exec`: the done event recompiles such a body into an apply_patch helper call.
+      // `apply_patch`: `normalizeApplyPatchDelimiters` rewrites a decorated
+      // `*** Begin Patch ***` envelope at completion, so the decorated markers would be
+      // published and then replaced by the normalized ones. Before the shared decoder, this
+      // path held every non-canonical shape and so never reached that case; now that ordinary
+      // raw input streams, the second reason has to be stated explicitly.
+      const mayCompile = declaresCodeModeExec(declaredNames)
+        && itemName?.namespace === undefined
+        && itemName?.name === "exec";
+      const mayNormalize = ownsFreeformGrammar && itemName?.name === "apply_patch";
+      if ((mayCompile || mayNormalize) && mayBecomePatchEnvelope(fullInput)) return [];
       if (!fullInput.startsWith(open.emittedInput) || fullInput.length === open.emittedInput.length) return [];
       const inputDelta = fullInput.slice(open.emittedInput.length);
       open.emittedInput = fullInput;

package/src/server/responses-request-tool-scope.ts

@@ -0,0 +1,214 @@
+/**
+ * The tool selection a Responses request actually authorized, read from the final outbound body.
+ *
+ * The undeclared-tool guard answers whether a NAME was declared. This answers a different
+ * question: whether this request still permits a client tool call at all, and which names it
+ * permits. `tool_choice: "none"`, a forced selector and an `allowed_tools` allow-list each narrow
+ * the catalog without removing a declaration, so a name can be declared and forbidden at the same
+ * time — and a repair that rebuilds a terminal from collected items would otherwise hand the
+ * client a call the caller ruled out.
+ *
+ * The scope is read from the OUTBOUND body, after every removal, rename and translation, because
+ * that is the request the destination answered. A catalog that ends up empty there authorizes no
+ * client call whatever the selector still says.
+ */
+import type { MuseToolNameAliases } from "../responses/muse-tool-name-alias";
+import { museWireNameForOriginal } from "../responses/muse-tool-name-alias";
+import type {
+  RoutedNamespaceToolAliases,
+  RoutedNamespaceToolIdentity,
+} from "../responses/namespace-tool-compat";
+import {
+  CLIENT_EXECUTED_CALL_TYPES,
+  collectDeclaredWireToolNames,
+  hasExplicitWireToolCatalog,
+} from "./responses-undeclared-tool-guard";
+import { isPlainObject } from "./responses-snapshot-codec";
+
+type ToolKind = "function" | "custom";
+const BUILTIN_FUNCTIONS_NAMESPACE = "functions";
+
+type ToolIdentity = Readonly<{
+  kind: ToolKind;
+  name: string;
+  namespace?: string;
+}>;
+
+export type RequestToolScopeCorrespondence = Readonly<{
+  clientToolAuthorizationBody?: unknown;
+  routedNamespaceToolAliases?: RoutedNamespaceToolAliases;
+  routedMuseToolNameAliases?: MuseToolNameAliases;
+  convertedRoutedCustomToolNames?: ReadonlySet<string>;
+}>;
+
+function identityKey(identity: ToolIdentity): string {
+  return JSON.stringify([identity.kind, identity.namespace ?? null, identity.name]);
+}
+
+function clientNamespace(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 && value !== BUILTIN_FUNCTIONS_NAMESPACE
+    ? value
+    : undefined;
+}
+
+function selectorIdentity(selector: unknown): ToolIdentity | undefined {
+  if (!isPlainObject(selector)) return undefined;
+  if (selector.type !== "function" && selector.type !== "custom") return undefined;
+  if (typeof selector.name !== "string" || selector.name.length === 0) return undefined;
+  if ("namespace" in selector && typeof selector.namespace !== "string") return undefined;
+  const namespace = clientNamespace(selector.namespace);
+  return { kind: selector.type, name: selector.name, ...(namespace ? { namespace } : {}) };
+}
+
+function callIdentity(item: Record<string, unknown>): ToolIdentity | undefined {
+  const kind = item.type === "function_call"
+    ? "function"
+    : item.type === "custom_tool_call"
+      ? "custom"
+      : undefined;
+  if (!kind || typeof item.name !== "string" || item.name.length === 0) return undefined;
+  const namespace = clientNamespace(item.namespace);
+  return { kind, name: item.name, ...(namespace ? { namespace } : {}) };
+}
+
+function sameRestoredIdentity(left: ToolIdentity, right: RoutedNamespaceToolIdentity): boolean {
+  return left.namespace === right.namespace
+    && left.name === right.name
+    && left.kind === right.kind;
+}
+
+/**
+ * Exact identities this restored call could have used on the final outbound wire.
+ *
+ * Namespace spellings come only from namespace-tool-compat's request-scoped, ambiguity-checked
+ * aliases. Muse aliases then compose over those wire names. A kind change is admitted only when
+ * the request recorded that exact custom identity as converted to a function.
+ */
+function outboundCallIdentities(
+  item: Record<string, unknown>,
+  correspondence: RequestToolScopeCorrespondence,
+): ReadonlySet<string> {
+  const restored = callIdentity(item);
+  if (!restored) return new Set();
+  const keys = new Set<string>([identityKey(restored)]);
+  const museAliases = correspondence.routedMuseToolNameAliases ?? new Map();
+  const convertedCustom = correspondence.convertedRoutedCustomToolNames ?? new Set();
+  const originalSelection = isPlainObject(correspondence.clientToolAuthorizationBody)
+    ? toolSelection(correspondence.clientToolAuthorizationBody)
+    : UNRESTRICTED;
+  const originalSelectionAllowsRestored = originalSelection.kind === "allow"
+    && originalSelection.identities.has(identityKey(restored));
+
+  const addWireIdentity = (
+    preMuseName: string,
+    clientKind: ToolKind,
+    conversionIdentityVerified: boolean,
+  ): void => {
+    const name = museWireNameForOriginal(preMuseName, museAliases);
+    if (name === undefined) return;
+    const kind = clientKind === "custom"
+      && convertedCustom.has(preMuseName)
+      && conversionIdentityVerified
+      ? "function"
+      : clientKind;
+    keys.add(identityKey({ kind, name }));
+  };
+
+  if (restored.namespace === undefined) {
+    addWireIdentity(restored.name, restored.kind, originalSelectionAllowsRestored);
+  }
+  for (const [wireName, identity] of correspondence.routedNamespaceToolAliases ?? new Map()) {
+    // namespace-tool-compat emits only aliases authorized under the outbound selector's kind,
+    // then restores `custom` provenance from the request's conversion set. That exact alias edge is
+    // already the proof that this custom-to-function transition belongs to this identity.
+    if (sameRestoredIdentity(restored, identity)) addWireIdentity(wireName, identity.kind, true);
+  }
+  return keys;
+}
+
+type ToolSelection =
+  | { readonly kind: "unrestricted" }
+  | { readonly kind: "deny_all" }
+  | { readonly kind: "allow"; readonly identities: ReadonlySet<string> };
+
+const UNRESTRICTED: ToolSelection = { kind: "unrestricted" };
+
+/**
+ * Read the selector only where it states a client-call boundary.
+ *
+ * `auto`, `required` and an absent selector restrict nothing. A hosted selector
+ * (`{ type: "web_search" }`) forces a tool the PROVIDER runs and does not describe the client
+ * calls this turn may contain, so it is left alone rather than read as a deny-all: a false
+ * refusal would drop a call the caller could have executed.
+ */
+function toolSelection(body: Record<string, unknown>): ToolSelection {
+  const choice = body.tool_choice;
+  if (choice === "none") return { kind: "deny_all" };
+  if (!isPlainObject(choice)) return UNRESTRICTED;
+  if (choice.type === "allowed_tools") {
+    const identities = new Set<string>();
+    if (!Array.isArray(choice.tools)) return { kind: "allow", identities };
+    for (const entry of choice.tools) {
+      const identity = selectorIdentity(entry);
+      if (identity) identities.add(identityKey(identity));
+    }
+    // An allow-list carrying no client tool — emptied by normalization, or hosted entries only —
+    // still bounds this turn: it allows no client call.
+    return { kind: "allow", identities };
+  }
+  if (choice.type === "function" || choice.type === "custom") {
+    const identity = selectorIdentity(choice);
+    return {
+      kind: "allow",
+      identities: new Set(identity ? [identityKey(identity)] : []),
+    };
+  }
+  return UNRESTRICTED;
+}
+
+export type RequestToolScope = {
+  /**
+   * The name a client call is refused under, or undefined when this request permits it.
+   * A nameless call type is not answered here: only the declaration guard knows those.
+   */
+  forbiddenClientToolCallName(item: Record<string, unknown>): string | undefined;
+};
+
+/**
+ * The client-call boundary this request states, or undefined when it states none.
+ *
+ * Returning undefined for an unrestricted request keeps every ordinary turn on the path it
+ * already had: a caller that selected nothing gets no new refusal.
+ */
+export function requestToolScope(
+  body: unknown,
+  correspondence: RequestToolScopeCorrespondence = {},
+): RequestToolScope | undefined {
+  if (!isPlainObject(body)) return undefined;
+  const selection = toolSelection(body);
+  // A readable catalog that declares no client-executable name is authoritative, exactly as it is
+  // for the declaration guard: an explicit empty list denies every client call. An absent catalog
+  // says nothing — a passthrough request may omit `tools` and still receive a call the client
+  // understands.
+  const catalogDeniesClientCalls = hasExplicitWireToolCatalog(body)
+    && collectDeclaredWireToolNames(body).size === 0;
+  if (selection.kind === "unrestricted" && !catalogDeniesClientCalls) return undefined;
+  return {
+    forbiddenClientToolCallName(item: Record<string, unknown>): string | undefined {
+      if (typeof item.type !== "string" || !CLIENT_EXECUTED_CALL_TYPES.has(item.type)) {
+        return undefined;
+      }
+      const restored = callIdentity(item);
+      const reported = restored?.name;
+      if (reported === undefined) return undefined;
+      if (catalogDeniesClientCalls || selection.kind === "deny_all") return reported;
+      if (selection.kind === "allow") {
+        const candidates = outboundCallIdentities(item, correspondence);
+        return [...candidates].some(candidate => selection.identities.has(candidate))
+          ? undefined
+          : reported;
+      }
+      return undefined;
+    },
+  };
+}

package/src/server/responses-undeclared-tool-guard.ts

@@ -1,4 +1,9 @@
-import { collectAmbiguousDottedAliases, dottedAliasIsUnambiguous, wireToolInnerName } from "../responses/tool-name-aliases";
+import {
+  collectAmbiguousDottedAliases,
+  dottedAliasIsUnambiguous,
+  isSchemaValidResponsesToolName,
+  wireToolInnerName,
+} from "../responses/tool-name-aliases";
 import {
   dottedToolName,
   NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES,
@@ -8,7 +13,10 @@ import {
 import { replaceSseDataPayload, sseDataPayload, type SseBlockRewrite } from "./sse-payload-rewrite";
 
 /** Item types the client executes through a request-declared wire name. */
-const CLIENT_EXECUTED_CALL_TYPES = new Set(["function_call", "custom_tool_call"]);
+export const CLIENT_EXECUTED_CALL_TYPES: ReadonlySet<string> = new Set([
+  "function_call",
+  "custom_tool_call",
+]);
 /** Codex groups ordinary top-level tools here; unlike an MCP namespace, it has no wire prefix. */
 const BUILTIN_FUNCTIONS_NAMESPACE = "functions";
 
@@ -512,6 +520,31 @@ export function normalizeDefaultNamespaceInItem(
         return { value: { ...item, name: bare }, changed: true };
       }
     }
+    // Authorization and emission were reading two different resolvers for the same question.
+    // `undeclaredNameInItem` resolves an emitted name through `normalizeDeclaredToolName`, which
+    // maps a `default.`-prefixed code-mode helper onto the declared `exec` (#4412) as well as a
+    // `default.`-prefixed bare tool (#4176); the rewrite above learned only the second case. So a
+    // routed Muse turn under a code-mode catalog had `default.view_image` ACCEPTED as `exec` and
+    // then relayed under the name the upstream schema rejects. Codex stored
+    // `{"type":"function_call","name":"default.view_image"}`, answered "unsupported call", and
+    // every later replay of that history — a side chat, a compaction — was refused on
+    // `input[N].name` for the lifetime of the conversation (#5095).
+    //
+    // Emit the name the guard authorized rather than a second, weaker opinion about it. The two
+    // must agree: a name good enough to admit is the name the client has to receive.
+    //
+    // Gated on the name actually being unusable, so this branch cannot touch a name the upstream
+    // accepts whatever the resolver would have said about it. The routed-custom-tool and
+    // namespace restores run earlier in the same chain and already rewrite the shapes they own,
+    // which leaves this as the boundary check for the names no restore claimed.
+    if (!isSchemaValidResponsesToolName(name)) {
+      const authorized = normalizeDeclaredToolName(name, declared, declaredBare);
+      if (
+        authorized !== name
+        && declared.has(authorized)
+        && isSchemaValidResponsesToolName(authorized)
+      ) return { value: { ...item, name: authorized }, changed: true };
+    }
   }
   return { value: item, changed: false };
 }

package/src/server/search.ts

@@ -25,6 +25,9 @@ import { codexAccountNamespaceForModel } from "../codex/account-namespace-match"
 import { NATIVE_RESERVE_MODEL } from "../codex/catalog/native-models";
 import { isCodexReserveRequestEligible } from "../codex/loopback-target";
 import type { DataPlaneAdmission } from "./auth-cors";
+import {
+  admissionScopeDenial,
+} from "./admission-model-scope";
 import { formatCodexProviderForLog } from "../codex/routing";
 import { signalWithTimeout } from "../lib/abort";
 import { readBoundedResponseBytes } from "../lib/bounded-body";
@@ -87,6 +90,11 @@ export async function handleSearch(
       if (!route.codexAccountId || route.codexAccountNamespace !== accountNamespace) {
         return formatErrorResponse(400, "invalid_request_error", "Invalid Codex account-qualified search model");
       }
+      // This branch resolves a model through the router and bills the account it
+      // names, so a scoped key is held to the same destination rule it is held
+      // to on the inference path.
+      const denial = admissionScopeDenial(config, admission, model, route);
+      if (denial) return denial;
       exactAccount = { accountId: route.codexAccountId, modelId: route.modelId };
       logCtx.provider = `${route.providerName}-${accountNamespace}`;
       logCtx.routeDecision = route.routeDecision;
@@ -108,7 +116,7 @@ export async function handleSearch(
   }
   const candidates = listOpenAiForwardSidecarCandidates(config);
   if (candidates.length === 0) {
-    return handleAlphaSearchSidecarFallback(body, config, req.signal, logCtx);
+    return handleAlphaSearchSidecarFallback(body, config, req.signal, logCtx, admission);
   }
 
   let upstream: Awaited<ReturnType<typeof resolveFirstUsableOpenAiSidecar>>;
@@ -148,6 +156,22 @@ export async function handleSearch(
     throw err;
   }
 
+  if (!accountNamespace) {
+    // An unqualified search model is never routed: the caller's own string is
+    // relayed to whichever ChatGPT account this upstream resolved to, and that
+    // account is billed for it. The qualified branch above was already judged
+    // against the route it resolved, so it is not judged twice here.
+    const searchModel = typeof model === "string" && model.trim() ? model : undefined;
+    const denial = admissionScopeDenial(config, admission, searchModel, {
+      providerName: upstream.providerName,
+      modelId: searchModel,
+    });
+    if (denial) {
+      upstream.releaseProbeLease?.();
+      return denial;
+    }
+  }
+
   const headers: Record<string, string> = { "content-type": "application/json" };
   if (upstream.provider.headers) Object.assign(headers, upstream.provider.headers);
   for (const [name, value] of upstream.headers) headers[name] = value;

package/src/server/sse-payload-rewrite.ts

@@ -230,7 +230,7 @@ export function replaceSseDataPayload(block: string, payload: string): string {
       continue;
     }
     if (!replaced) {
-      rewritten.push(`data: ${payload}`);
+      rewritten.push(...payload.split(/\r?\n/).map(line => `data: ${line}`));
       replaced = true;
     }
   }

package/src/server/usage-ledger-retention.ts

@@ -0,0 +1,73 @@
+/**
+ * Runtime owner for the opt-in usage-ledger size limit (#5063).
+ *
+ * The compactor in `src/usage/ledger-retention.ts` knows how to publish a smaller ledger safely.
+ * This is the part that decides when, and -- the half #5063 was missing -- what has to be
+ * discarded afterwards.
+ *
+ * Deleting rows from usage.jsonl invalidates three readers that do not watch the file: the
+ * 2,000-entry Logs ring, which otherwise keeps serving rows the ledger no longer has; the
+ * retained usage aggregate and failure projection, whose checkpoints now point past a boundary
+ * that moved; and the request-history index, whose source identity has changed. A compaction
+ * that skips any of them makes the dashboard disagree with the ledger, which is the disagreement
+ * this batch exists to remove.
+ */
+import { currentUsageLogRevision, setUsageLedgerAppendHook } from "../usage/log";
+import { enforceUsageLedgerSizeLimit } from "../usage/ledger-retention";
+import { discardRetainedFailureProjection } from "../usage/failure-projection-cache";
+import { rehydrateRequestLogsAfterLedgerReplacement } from "./request-log";
+import type { UsageLedgerRetentionStatus } from "../usage/retention-contract";
+
+let configuredMaxBytes: number | undefined;
+let enforcing = false;
+
+function invalidateLedgerReaders(): void {
+  // Ordered cheapest-first, and each guarded on its own: a projection that fails to discard
+  // must not stop the ring from being rebuilt, because the ring is the surface an operator is
+  // looking at while this happens.
+  try { discardRetainedFailureProjection(); } catch { /* rebuildable by construction */ }
+  void (async () => {
+    try {
+      const { discardRetainedUsageAggregate } = await import("./management/usage-aggregate-cache");
+      discardRetainedUsageAggregate();
+    } catch { /* rebuildable by construction */ }
+    try {
+      const { closeRequestHistoryIndex } = await import("../routing/history/indexer");
+      closeRequestHistoryIndex();
+    } catch { /* the index rebuilds from its own source-identity contract */ }
+  })();
+  try { rehydrateRequestLogsAfterLedgerReplacement(); } catch { /* the ring refills as rows arrive */ }
+}
+
+function enforceNow(): void {
+  // Re-entrancy guard, not a lock. The compaction itself runs inside the append call stack, and
+  // its own publication writes nothing through appendUsageEntry -- this exists so a future
+  // caller on that path cannot start a second pass over a file the first one is replacing.
+  if (enforcing) return;
+  enforcing = true;
+  try {
+    const result = enforceUsageLedgerSizeLimit(configuredMaxBytes);
+    if (result.kind === "replaced") invalidateLedgerReaders();
+  } catch (error) {
+    // Never fail a request because history could not be trimmed. The limit is not enforced and
+    // says so; the next append tries again from a fresh revision.
+    console.warn(
+      `[usage-retention] could not enforce the usage ledger size limit: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  } finally {
+    enforcing = false;
+  }
+}
+
+/** Install or update the policy. `undefined` removes the hook entirely. */
+export function setUsageLedgerRetention(maxBytes: number | undefined): void {
+  configuredMaxBytes = maxBytes;
+  setUsageLedgerAppendHook(maxBytes === undefined ? null : enforceNow);
+}
+
+export function usageLedgerRetentionStatus(): UsageLedgerRetentionStatus {
+  return {
+    ...(configuredMaxBytes !== undefined ? { maxBytes: configuredMaxBytes } : {}),
+    currentBytes: currentUsageLogRevision()?.size ?? 0,
+  };
+}

package/src/service/cli.ts

@@ -13,7 +13,8 @@ import { resolveServiceListenPort, reportServiceServing } from "./health";
 import { platformOps, proxyStillLiveAfterStop, stopTrackedProxyForServiceCommand, installServiceSafely, installFreshWindowsSchedulerSafely, removeServiceInstallState, isServiceInstalled } from "./orchestration";
 import { repairService } from "./repair";
 import type { ServiceRepairVerb } from "./repair";
-import { TASK, plistPath, readServiceBackend } from "./state";
+import { TASK, plistPath, readServiceBackend, releaseServiceOwner, resolveServiceOwnership } from "./state";
+import { foreignServiceOwnerRefusal, unknownServiceOwnerRefusal } from "./repair";
 import type { ServiceBackend } from "./state";
 import { unitPath } from "./systemd";
 import { inspectWindowsSchedulerServiceStatus, schtasksErrorDetail, probeWindowsSchedulerTask } from "./windows-scheduler";
@@ -233,6 +234,15 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     case "install":
       assertServiceEnvironmentMatchesInstall();
       assertServiceAuthEnvironment();
+      // The install may advance provenance, but it may take back only the owner it observed
+      // before touching the registration. A desktop successor that claims ownership while
+      // the install is running must survive the late release below.
+      const ownershipBeforeInstall = resolveServiceOwnership();
+      if (ownershipBeforeInstall.kind === "unknown") {
+        console.error(`❌ ${unknownServiceOwnerRefusal(ownershipBeforeInstall.reason, "install")}`);
+        process.exitCode = 1;
+        break;
+      }
       // A manually started proxy can still own the configured port while the service
       // registration is absent or unloaded. Stop both the registered manager and any
       // tracked standalone listener before loading the freshly written service assets.
@@ -258,6 +268,23 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
         process.exitCode = 1;
         break;
       }
+      // ONLY now. `install` is the verb that takes the runtime back, and it does so after the
+      // registration exists — releasing first meant a cancelled UAC prompt, a failed
+      // registration or an aborted cleanup left the retained npm registration looking
+      // CLI-owned, so the next incidental repair would reactivate it.
+      //
+      // `repair` and `restart` refuse under a foreign owner precisely because they run
+      // incidentally — from a tray helper, from `ocx update`, from a doctor suggestion — and
+      // undoing a takeover the user consented to must be something the user asked for.
+      {
+        const released = releaseServiceOwner(ownershipBeforeInstall, { allowRevisionAdvance: true });
+        if (released) {
+          console.log(
+            `ℹ️  The desktop app owned the background runtime (install ${released.installId}, `
+            + `consent generation ${released.consentGeneration}); this install took it back.`,
+          );
+        }
+      }
       // The wrapper was written moments ago in this process, so the configured port
       // and the baked one cannot have diverged yet — unlike `start`, which reads the
       // installed artifact instead.
@@ -269,15 +296,34 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       // Same one-time marker and same guards (TTY, gh auth, agent deferral) apply.
       await maybeShowStarPrompt();
       break;
-    case "start":
+    case "start": {
       // The installed launcher preserves the recorded CODEX_SQLITE_HOME: a
       // changed sqlite_home/CODEX_SQLITE_HOME/CODEX_HOME would start the service
       // on the recorded database while this shell resolves another, splitting
       // native Codex history between databases. Same guard `stop` already runs.
       assertServiceEnvironmentMatchesInstall();
+      // `start` activates the npm registration, so it refuses on the same terms repair does.
+      // The Windows tray starts the service automatically, which would otherwise put a second
+      // proxy beside the one the desktop app is running without anyone asking for it.
+      // `stop` and `uninstall` are deliberately NOT gated: they deactivate.
+      //
+      // Reported rather than thrown: the tray drives this through `runTrayProxyStart`, which
+      // does not catch, and a refusal is a decision rather than a crash.
+      const ownership = resolveServiceOwnership();
+      const refusal = ownership.kind === "unknown"
+        ? unknownServiceOwnerRefusal(ownership.reason, "start")
+        : ownership.kind === "owned" && ownership.ownership.owner !== "cli"
+          ? foreignServiceOwnerRefusal(ownership.ownership, "start")
+          : null;
+      if (refusal) {
+        console.error(`❌ ${refusal}`);
+        process.exitCode = 1;
+        break;
+      }
       ops.start();
       await reportServiceServing("started");
       break;
+    }
     case "stop": {
       assertServiceEnvironmentMatchesInstall();
       // Only stop what is actually installed. The unguarded call ran a real `launchctl unload`