@bitkyc08/opencodex 2.57.0 → 2.59.0

package/src/codex/inject/restore.ts

@@ -28,6 +28,7 @@ import {
 import {
   preflightCodexHistoryInjection,
   syncCodexHistoryProvider,
+  HISTORY_RELABEL_STANDS_DOWN,
   type CodexHistoryFailureReason,
 } from "../history-provider";
 import {
@@ -44,7 +45,11 @@ import {
 } from "../paths";
 import { shouldInjectApiAuthHeader } from "../loopback-target";
 import { currentExternalCodexModelProvider } from "./config-toml";
-import { removeCodexConfig } from "./remove";
+import {
+  readOcxProviderTableBlock,
+  removeCodexConfig,
+  retainOcxProviderTableOnDisk,
+} from "./remove";
 
 class CodexRestoreRefusal extends Error {
   constructor(readonly config: CodexRestoreConfigResult) {
@@ -57,13 +62,49 @@ export function setBeforeRestoreConfigForTests(hook: typeof beforeRestoreConfigF
   beforeRestoreConfigForTests = hook;
 }
 
-export type CodexRestoreArtifactState = "ok" | "skipped" | "failed";
+/**
+ * `partial` means the artifact was restored as far as it safely could be and named what
+ * it left behind. It is not a failure — the caller's obligation was discharged — but it
+ * is not a plain `ok` either, because something on disk still needs a decision (#4812).
+ */
+export type CodexRestoreArtifactState = "ok" | "partial" | "skipped" | "failed";
+
+/** What a degraded restore kept, why, and how to finish the job. */
+export interface RetainedCodexProviderTable {
+  reason: typeof HISTORY_RELABEL_STANDS_DOWN;
+  /** The exact `config.toml` lines left on disk. */
+  lines: string[];
+  followUp: string;
+}
+
+const RETAINED_PROVIDER_TABLE_FOLLOW_UP =
+  "Run 'ocx restore --remove-codex-provider-table' to remove it; conversations already tagged "
+  + "opencodex will stop opening if you do.";
+
+/**
+ * The one sentence every teardown surface prints about retained residue.
+ *
+ * Shared rather than rewritten per caller: `restore`, `stop`, `uninstall`, the service
+ * subcommands and the stop API all report this same outcome, and a user who runs two of
+ * them should not have to work out whether two different descriptions mean the same state.
+ */
+export function describeRetainedCodexProviderTable(retained: RetainedCodexProviderTable): string {
+  return "Kept [model_providers.opencodex] in $CODEX_HOME/config.toml because Codex owns this home's"
+    + ` paginated history (${retained.reason}): conversations already tagged opencodex resolve only`
+    + ` through that table. Plain \`codex\` is native again. ${retained.followUp}`;
+}
 
 export interface CodexRestoreConfigResult {
   state: CodexRestoreArtifactState;
   changed: boolean;
-  action: "journal-restored" | "owned-fields-stripped" | "external-provider-preserved" | "failed";
+  action:
+    | "journal-restored"
+    | "owned-fields-stripped"
+    | "routing-restored-provider-retained"
+    | "external-provider-preserved"
+    | "failed";
   message: string;
+  retained?: RetainedCodexProviderTable;
 }
 
 export interface CodexRestoreCatalogResult {
@@ -101,6 +142,14 @@ export interface CodexNativeRestoreResult {
    * make a safety decision depend on prose.
    */
   historyPreflightRefusal?: string;
+  /**
+   * Set when routing came out but `[model_providers.opencodex]` stayed (#4812).
+   *
+   * Distinct from `historyPreflightRefusal`, which means nothing was attempted at all.
+   * This one means the config obligation WAS discharged, so a stop receipt must be
+   * released rather than preserved.
+   */
+  retainedCodexProviderTable?: RetainedCodexProviderTable;
   artifacts: {
     config: CodexRestoreConfigResult;
     catalog: CodexRestoreCatalogResult;
@@ -243,10 +292,42 @@ function historyPreflightRefusalEnvelope(historyError: string): CodexNativeResto
   return result;
 }
 
+/**
+ * How a restore may proceed given what the history preflight says.
+ *
+ * The preflight answers one question — may conversation history be rewritten — and this
+ * translates it into the separate question the restore actually needs answered: may
+ * OpenCodex routing come out of `config.toml`, and what has to stay if it does.
+ */
+export type RestoreHistoryDisposition =
+  | { kind: "proceed" }
+  | { kind: "stand-down"; retainProviderTable: boolean }
+  | { kind: "refuse"; reason: string };
+
+export function resolveRestoreHistoryDisposition(
+  removeProviderTable: boolean | undefined,
+  reason: string | null = preflightCodexHistoryInjection(false, false),
+): RestoreHistoryDisposition {
+  if (!reason) return { kind: "proceed" };
+  // Every other reason still means the history state itself is wrong — a missing store, an
+  // unreadable rollout, an integrity failure. Those keep the hard refusal and the
+  // compensating rollback they have always had.
+  if (reason !== HISTORY_RELABEL_STANDS_DOWN) return { kind: "refuse", reason };
+  // The rows stay tagged `opencodex` either way, because the native writer owns them.
+  // Retaining the table is what keeps those conversations openable; the explicit flag is
+  // the user accepting that they will not be.
+  return { kind: "stand-down", retainProviderTable: removeProviderTable !== true };
+}
+
+export interface RestoreConfigOptions {
+  /** Strip `[model_providers.opencodex]` too, accepting that tagged threads stop opening. */
+  removeProviderTable?: boolean;
+}
+
 /** The config/profile half of a native restore, reported as one artifact. */
-function restoreCodexConfigInline(kind = "sync"): CodexRestoreConfigResult {
+function restoreCodexConfigInline(kind = "sync", options: RestoreConfigOptions = {}): CodexRestoreConfigResult {
   const preImages = captureCodexPreImages();
-  const result = restoreCodexConfigInlineImpl(kind);
+  const result = restoreCodexConfigInlineImpl(kind, options);
   if (result.state === "failed") {
     const compensated = restoreCodexPreImages(preImages);
     if (!compensated.complete) throw new CodexPartialWriteError(compensated.unrestored);
@@ -254,11 +335,25 @@ function restoreCodexConfigInline(kind = "sync"): CodexRestoreConfigResult {
   return result;
 }
 
-function restoreCodexConfigInlineImpl(kind: string): CodexRestoreConfigResult {
+function restoreCodexConfigInlineImpl(kind: string, options: RestoreConfigOptions): CodexRestoreConfigResult {
   try {
     beforeRestoreConfigForTests?.(kind);
-    const historyError = preflightCodexHistoryInjection(false, false);
-    if (historyError) return { state: "failed", changed: false, action: "failed", message: `Codex configuration and journal preserved: ${historyError}.` };
+    const disposition = resolveRestoreHistoryDisposition(options.removeProviderTable);
+    if (disposition.kind === "refuse") {
+      return { state: "failed", changed: false, action: "failed", message: `Codex configuration and journal preserved: ${disposition.reason}.` };
+    }
+    // Captured unconditionally, not only when the stand-down is already known.
+    //
+    // Two different paths need bytes that only exist before the write. The journal restore
+    // replays the pre-injection config, which never contained our table, and then deletes
+    // the journal. And Codex can paginate DURING the write: the post-write re-check below
+    // then sees a stand-down that the pre-write check did not, at which point the table has
+    // already been stripped and there is nothing left to read. Both are cheap to prevent
+    // and impossible to repair afterwards, so the read happens once, here.
+    //
+    // The one caller that must not capture is the explicit removal flag: it is the user
+    // accepting that tagged conversations stop opening.
+    const capturedBlock = options.removeProviderTable === true ? null : readOcxProviderTableBlock();
     const journal = restoreJournalState();
     if (journal.unverified) {
       return {
@@ -267,13 +362,51 @@ function restoreCodexConfigInlineImpl(kind: string): CodexRestoreConfigResult {
       };
     }
     const restored = journal.configRestored
-      ? { success: true, message: "Codex config restored from opencodex journal." }
-      : removeCodexConfig({ preserveProfile: journal.profileRestored || journal.profileChanged });
+      ? { success: true, message: "Codex config restored from opencodex journal.", retainedProviderTable: undefined as string[] | undefined }
+      : removeCodexConfig({
+          preserveProfile: journal.profileRestored || journal.profileChanged,
+          // The history question was resolved above; hand the answer down rather than making
+          // the transform re-derive it, which refused the explicit-removal path outright.
+          historyDisposition: disposition.kind === "stand-down"
+            ? disposition.retainProviderTable ? "stand-down-retain" : "stand-down-remove"
+            : "refuse-on-any",
+        });
+    let retainedLines = restored.retainedProviderTable ?? null;
     if (restored.success) {
       // A successful journal/fallback write can race native history migration too.
       // Refuse here while preimage compensation and the remove transaction can roll back.
-      const finalHistoryError = preflightCodexHistoryInjection(false, false);
-      if (finalHistoryError) return { state: "failed", changed: false, action: "failed", message: `Codex configuration and journal preserved: ${finalHistoryError}.` };
+      // A stand-down observed now is the same stand-down that was already accounted for —
+      // it must not undo a routing removal that has already reached disk.
+      const settled = resolveRestoreHistoryDisposition(options.removeProviderTable);
+      if (settled.kind === "refuse") {
+        return { state: "failed", changed: false, action: "failed", message: `Codex configuration and journal preserved: ${settled.reason}.` };
+      }
+      // One re-attach covers three cases that all need the same bytes on disk: the journal
+      // path, which wrote a config without our table; the migration race, where the strip ran
+      // before anyone knew a table was needed; and the ordinary planned retention, where
+      // `removeCodexConfig` already put it back and this is a no-op. Re-attaching is
+      // idempotent — it checks for the table before appending — so the three do not have to
+      // be told apart here.
+      if (settled.kind === "stand-down" && settled.retainProviderTable && capturedBlock !== null) {
+        retainedLines = retainOcxProviderTableOnDisk(capturedBlock) ?? retainedLines;
+      }
+    }
+    if (restored.success && retainedLines !== null) {
+      return {
+        state: "partial",
+        changed: true,
+        action: "routing-restored-provider-retained",
+        message: journal.configRestored
+          ? "Codex config restored from opencodex journal. Kept [model_providers.opencodex] so conversations already"
+            + " tagged opencodex still open; remove it with 'ocx restore --remove-codex-provider-table'"
+            + " (those conversations stop opening)."
+          : restored.message,
+        retained: {
+          reason: HISTORY_RELABEL_STANDS_DOWN,
+          lines: retainedLines,
+          followUp: RETAINED_PROVIDER_TABLE_FOLLOW_UP,
+        },
+      };
     }
     return restored.success
       ? {
@@ -336,7 +469,7 @@ function restoreCodexCatalogArtifact(
  * that lost race into the discriminated `desired_enabled` skip.
  */
 export async function restoreNativeCodexAsync(
-  options: { revalidateDesiredState?: boolean } = {},
+  options: { revalidateDesiredState?: boolean; removeProviderTable?: boolean } = {},
 ): Promise<CodexNativeRestoreResult> {
   try {
     return await restoreNativeCodexAsyncImpl(options);
@@ -347,7 +480,7 @@ export async function restoreNativeCodexAsync(
 }
 
 async function restoreNativeCodexAsyncImpl(
-  options: { revalidateDesiredState?: boolean },
+  options: { revalidateDesiredState?: boolean; removeProviderTable?: boolean },
 ): Promise<CodexNativeRestoreResult> {
   const activeProvider = currentExternalCodexModelProvider();
   if (activeProvider) {
@@ -368,8 +501,12 @@ async function restoreNativeCodexAsyncImpl(
     if (shouldSyncCodexOnStart(loadConfig())) return desiredEnabledRestoreSkip();
   }
 
-  const historyError = preflightCodexHistoryInjection(false, false);
-  if (historyError) return historyPreflightRefusalEnvelope(historyError);
+  const disposition = resolveRestoreHistoryDisposition(options.removeProviderTable);
+  if (disposition.kind === "refuse") return historyPreflightRefusalEnvelope(disposition.reason);
+  // A stand-down spawns no history Worker. The preflight the Worker would run first has
+  // already answered, and the rows stay tagged `opencodex` on purpose — which is exactly
+  // why the provider table has to survive the config half.
+  const historyStandsDown = disposition.kind === "stand-down";
 
   const eligibility = codexWriteCoordinationEligibility({
     coordinatorPath: () =>
@@ -420,7 +557,7 @@ async function restoreNativeCodexAsyncImpl(
         const preImages = captureCodexPreImages();
         let restored: CodexRestoreConfigResult;
         try {
-          restored = restoreCodexConfigInline(eligibility.kind);
+          restored = restoreCodexConfigInline(eligibility.kind, options);
           // Throw inside N so the published remove transition rolls back too.
           if (restored.state === "failed") throw new CodexRestoreRefusal(restored);
         } catch (error) {
@@ -463,20 +600,34 @@ async function restoreNativeCodexAsyncImpl(
     if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
       return desiredEnabledRestoreSkip();
     }
-    config = restoreCodexConfigInline(eligibility.kind);
+    config = restoreCodexConfigInline(eligibility.kind, options);
   }
 
   if (config.state === "failed") return failedConfigRestoreEnvelope(config);
   const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
-  const outcome = await runCodexHistoryJob({
-    ...resolveCodexHistoryJobTarget(),
-    ...(options.revalidateDesiredState ? { expectedDesiredEnabled: false } : {}),
-    operation: deriveCodexHistoryOperation({ direction: "restore", resumeHistory: true, legacyMode: false }),
-  });
+  // Re-asked after the config half, because the store can paginate mid-transaction. Deciding
+  // the history job from the pre-write answer alone would spawn a Worker whose own preflight
+  // is now guaranteed to refuse, and report that refusal as a restore failure on a home that
+  // was in fact restored.
+  const historyStoodDown = historyStandsDown
+    || resolveRestoreHistoryDisposition(options.removeProviderTable).kind === "stand-down";
+  const outcome: CodexHistoryJobOutcome = historyStoodDown
+    ? { kind: "skipped" }
+    : await runCodexHistoryJob({
+      ...resolveCodexHistoryJobTarget(),
+      ...(options.revalidateDesiredState ? { expectedDesiredEnabled: false } : {}),
+      operation: deriveCodexHistoryOperation({ direction: "restore", resumeHistory: true, legacyMode: false }),
+    });
   if (transitionReceipt) {
     resolveCodexHistoryTransition(transitionReceipt, outcome);
   }
-  const history: CodexRestoreHistoryResult = outcome.kind === "converged"
+  const history: CodexRestoreHistoryResult = historyStoodDown
+    ? {
+        state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0,
+        message: `Codex resume history was left to Codex's native writer (${HISTORY_RELABEL_STANDS_DOWN});`
+          + " existing threads keep the provider they are tagged with and no rollout byte was read or written.",
+      }
+    : outcome.kind === "converged"
     ? {
         state: "ok", changed: outcome.rows > 0 || outcome.files > 0, rows: outcome.rows, files: outcome.files, ejectedRows: 0,
         message: outcome.rows > 0
@@ -500,14 +651,24 @@ async function restoreNativeCodexAsyncImpl(
     : config.message;
   const success = catalog.state !== "failed"
     && history.state !== "failed";
+  // A stood-down relabel is not a failure, but it is something the operator has to be told:
+  // their existing conversations keep the provider they are tagged with, and nothing will
+  // ever change that from this side. Printing only the config half would be the same
+  // partial-success-reported-as-success problem this change exists to end.
+  const historyNote = history.state === "failed"
+    ? ` ⚠️ ${history.message}`
+    : historyStoodDown ? ` ${history.message}` : "";
   return {
     success,
-    message: `${base}${history.state === "failed" ? ` ⚠️ ${history.message}` : ""}`,
+    message: `${base}${historyNote}`,
+    ...(config.retained ? { retainedCodexProviderTable: config.retained } : {}),
     artifacts: { config, catalog, history },
   };
 }
 
-export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateDesiredState?: boolean } = {}): CodexNativeRestoreResult {
+export function restoreNativeCodex(
+  options: { skipHistory?: boolean; revalidateDesiredState?: boolean; removeProviderTable?: boolean } = {},
+): CodexNativeRestoreResult {
   const activeProvider = currentExternalCodexModelProvider();
   if (activeProvider) {
     removeJournal();
@@ -516,14 +677,18 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
   if (options.revalidateDesiredState && shouldSyncCodexOnStart(loadConfig())) {
     return desiredEnabledRestoreSkip();
   }
-  const historyError = preflightCodexHistoryInjection(false, false);
-  if (historyError) return historyPreflightRefusalEnvelope(historyError);
+  const disposition = resolveRestoreHistoryDisposition(options.removeProviderTable);
+  if (disposition.kind === "refuse") return historyPreflightRefusalEnvelope(disposition.reason);
+  const historyStandsDown = disposition.kind === "stand-down";
   // Captured before the config half: a successful journal restore DELETES the journal, and
   // restoring the config can drop `model_catalog_json`. Either one would hide the routed
   // catalog we actually wrote (#1798).
   const journaledCatalogPath = journaledInjectedCatalogPath();
-  const config = restoreCodexConfigInline();
+  const config = restoreCodexConfigInline("sync", options);
   if (config.state === "failed") return failedConfigRestoreEnvelope(config);
+  // Same mid-transaction pagination re-check as the async path.
+  const historyStoodDown = historyStandsDown
+    || resolveRestoreHistoryDisposition(options.removeProviderTable).kind === "stand-down";
   const catalog = restoreCodexCatalogArtifact(options.revalidateDesiredState === true, journaledCatalogPath);
   // Design B (loopback) steady state: threads are already tagged openai, so prove the
   // no-op with a readonly probe instead of write-opening a DB the Codex app may hold
@@ -537,12 +702,18 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
   }
   // `skipHistory` is how the async wrapper takes this work for itself: the
   // native files come down here, and history runs in the Worker under H.
-  const rawHistory = options.skipHistory
+  const rawHistory = options.skipHistory || historyStoodDown
     ? { rows: 0, files: 0 }
     : syncCodexHistoryProvider("openai", undefined, undefined, {
         skipWhenProvablyNoop,
       });
-  const history: CodexRestoreHistoryResult = options.skipHistory
+  const history: CodexRestoreHistoryResult = historyStoodDown
+    ? {
+        state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0,
+        message: `Codex resume history was left to Codex's native writer (${HISTORY_RELABEL_STANDS_DOWN});`
+          + " existing threads keep the provider they are tagged with and no rollout byte was read or written.",
+      }
+    : options.skipHistory
     ? { state: "skipped", changed: false, rows: 0, files: 0, ejectedRows: 0, message: "History restoration runs asynchronously." }
     : rawHistory.failed
       ? failedHistoryRestore(rawHistory.failureReason, undefined, rawHistory)
@@ -561,7 +732,8 @@ export function restoreNativeCodex(options: { skipHistory?: boolean; revalidateD
     : config.message;
   return {
     success: catalog.state !== "failed" && history.state !== "failed",
-    message,
+    message: historyStoodDown ? `${message} ${history.message}` : message,
+    ...(config.retained ? { retainedCodexProviderTable: config.retained } : {}),
     artifacts: { config, catalog, history },
   };
 }

package/src/codex/inject.ts

@@ -40,7 +40,7 @@ import {
   removeJournal,
   writeJournal,
 } from "./journal";
-import { preflightCodexHistoryInjection } from "./history-provider";
+import { HISTORY_RELABEL_STANDS_DOWN, preflightCodexHistoryInjection } from "./history-provider";
 import {
   describeHistoryJobFailure,
   deriveCodexHistoryOperation,
@@ -158,17 +158,13 @@ export interface CodexInjectResult {
    */
   historyPreflightFailureReason?: string;
   status?: "skipped";
+  /** Busy write lock, emitted by `codexInjectLockOutcome` and undeclared here until #4809. */
+  retryable?: boolean;
   /** `hub-gated` is the hub-role gate (#4236), distinct from the user's own OFF switch. */
   skippedReason?: "desired_disabled" | "desired_enabled" | "hub-gated";
   nativeSubagentDefaultsWarning?: string;
 }
 
-/**
- * The one history preflight reason that is permanent rather than operational: Codex owns
- * paginated rollout ordinals, so no retry makes the legacy relabel protocol available again.
- */
-const HISTORY_RELABEL_STANDS_DOWN = "history_paginated_requires_native_writer";
-
 class CodexHistoryPreflightRefusal extends Error {}
 let historyArtifactStageForTests: ((stage: string) => void) | undefined;
 export function setHistoryArtifactStageForTests(hook: typeof historyArtifactStageForTests): void {
@@ -373,7 +369,7 @@ async function injectCodexConfigImpl(
     content =
       content.trimEnd() +
       "\n" +
-      buildProviderTableBlockForTarget(routingTarget, websocketsEnabled(config ?? {}));
+      buildProviderTableBlockForTarget(routingTarget, websocketsEnabled(config ?? {}), config?.codexProviderDisplayName);
     // 3) Keep existing `openai`-tagged threads reaching the proxy (see above). Ownership rules
     // are the Design B ones: a user's own root line is never replaced.
     if (keepRootOverrideAlongsideTable) {
@@ -434,6 +430,7 @@ async function injectCodexConfigImpl(
     catalogPath,
     websocketsEnabled(config ?? {}),
     config?.fastMode,
+    config?.codexProviderDisplayName,
   );
   content = applyEol(content, eol);
 
@@ -496,7 +493,7 @@ async function injectCodexConfigImpl(
    */
   if (hadOcxProviderTableOnDisk && !providerTableMode) {
     content = applyEol(
-      content.trimEnd() + "\n" + buildProviderTableBlockForTarget(routingTarget, websocketsEnabled(config ?? {})),
+      content.trimEnd() + "\n" + buildProviderTableBlockForTarget(routingTarget, websocketsEnabled(config ?? {}), config?.codexProviderDisplayName),
       eol,
     );
   }

package/src/codex/lineage.ts

@@ -14,9 +14,11 @@
  *
  * What it is for, and what it is not for:
  *
- * - FIRST PLACEMENT. A child with no binding of its own may start where its family is already
- *   warm; see `pickLineageServingAccount` in ./routing. Once bound, the child is an ordinary
- *   binding, so a later move of the parent does not drag it.
+ * - FIRST PLACEMENT. Largely subsumed by cohort keying (#4780): a member of a tree that any
+ *   other member has already bound resolves to that same binding, so there is nothing to place.
+ *   `pickLineageServingAccount` in ./routing remains for the one case cohort keying cannot
+ *   unify -- a session-less chain whose parent is not recorded in this scope -- and is gated on
+ *   the parent's key actually differing from this request's.
  * - COST ATTRIBUTION. {@link codexThreadLineageLookup} and {@link codexLineageRootForRequest}
  *   answer which root workflow a conversation belongs to, so a grandchild's spend aggregates
  *   onto the root. No budget is implemented here.
@@ -155,30 +157,83 @@ export function codexConversationKeyFor(familyId: string, threadId: string): str
     .digest("base64url")}`;
 }
 
+/**
+ * The cohort anchor's key: the same string on both sides of the derivation.
+ *
+ * A cohort is identified by one value the whole tree shares, so the key is that value keyed
+ * against itself rather than against a member. Using {@link codexConversationKeyFor} keeps one
+ * derivation in the module, which is what guarantees a lineage record's `conversationKey` stays
+ * byte-identical to the key the thread actually binds under.
+ */
+function cohortKeyFromAnchor(sessionId: string | undefined, fallbackAnchor: string): string {
+  const anchor = sessionId ?? fallbackAnchor;
+  return codexConversationKeyFor(anchor, anchor);
+}
+
+/**
+ * The cohort this request belongs to, or undefined when it names no cohort at all.
+ *
+ * The session IS the cohort, which is exactly how upstream keys the prompt cache:
+ * `prompt_cache_key()` returns `responses_metadata.session_id` (or `{source}:{parent_thread_id}`
+ * for an internal session), and `AgentControl.session_id` is the root thread's id, shared with
+ * every sub-agent spawned from that root. Two requests carrying the same `prompt_cache_key` must
+ * not be served by different accounts, and keying on the session is what makes that structural
+ * rather than a hint (#4780).
+ *
+ * Without a session there is nothing in the headers that names the tree, so the cohort is
+ * whatever the parent is already bound to. That lookup is what keeps a chain of parent-only
+ * turns converging on one key: anchoring each depth on its own parent would split the cohort
+ * again at every hop. When the parent has not been seen in this scope the parent id anchors it,
+ * which is the same key that parent derives for itself.
+ */
+function cohortConversationKey(
+  headers: Headers,
+  sessionId: string | undefined,
+  parentThreadId: string | undefined,
+  now: number,
+): string | undefined {
+  if (sessionId !== undefined) return cohortKeyFromAnchor(sessionId, sessionId);
+  if (parentThreadId === undefined) return undefined;
+  const recorded = liveLineageRecord(
+    lineageByScope.get(codexLineageScopeKey(headers)),
+    parentThreadId,
+    now,
+  );
+  return recorded?.conversationKey ?? cohortKeyFromAnchor(undefined, parentThreadId);
+}
+
 /**
  * Resolve a request's conversation identity, or undefined when it carries no bindable thread
  * identity at all.
  *
- * The set of requests that produce NO key is deliberately unchanged from the pre-#4546 rule: a
- * bare `thread-id` with neither a session nor a parent stays unbound, exactly as the Desktop
- * fallback required both halves of its pair. Only the VALUE moves, and only for requests that
- * name a parent:
+ * The set of requests that produce NO key is deliberately unchanged, through both #4546 and
+ * #4780: a bare `thread-id` with neither a session nor a parent stays unbound, exactly as the
+ * Desktop fallback required both halves of its pair. Only the VALUE moves.
+ *
+ * Every member of one tree resolves to the SAME key, because the cohort is the binding unit
+ * (#4780):
+ *
+ * - root (`session-id` + `thread-id`) -> the session's cohort key;
+ * - child and grandchild (parent + own `thread-id`) -> the same cohort key, since they carry the
+ *   same session;
+ * - parent-only (no `thread-id`) -> the same cohort key, derived from the session or, without
+ *   one, read from the parent's record.
  *
- * - root (`session-id` + `thread-id`) -> HMAC(session, thread), unchanged;
- * - child (parent + own `thread-id`) -> HMAC(session ?? parent, thread), previously the raw parent
- *   id, which is what made siblings share one entry and made a child's first turn land on a key
- *   the root had never bound;
- * - parent-only (no `thread-id`) -> the parent's OWN recorded key when this scope has one, and
- *   otherwise HMAC(session ?? parent, parent).
+ * THIS IS NOT A REVERT OF #4546 wp8, and reading it as one would flip it straight back. wp8
+ * fixed a real incoherence: a child keyed under the RAW parent id, which is a different identity
+ * from the root's own `app:HMAC(session, thread)` binding, so siblings shared an entry unrelated
+ * to the root's and a grandchild keying on its own parent landed on a key nobody had ever bound.
+ * A cohort key cannot produce that, because the root's own binding IS the cohort key: there is
+ * one identity for the tree rather than two competing ones. What wp8 additionally gave each
+ * thread -- a binding of its own -- is what #4780 deliberately gives up, and the reason is that
+ * upstream never agreed to it: `prompt_cache_key` is keyed on the session the whole tree shares,
+ * so a proxy that splits the tree makes every split member assert a warm prefix that is cold on
+ * its account.
  *
- * That last case is the one with a trap in it. A parent-only turn belongs to the parent's
- * conversation, so it has to land on the binding the parent is already using -- but the parent's
- * key is HMAC(session, thread), and HMAC(parent, parent) reproduces it only when the session id
- * and the thread id are the same string. Codex's own root happens to satisfy that, which is
- * exactly why deriving the key looks correct until a caller whose session differs from its thread
- * starts a COLD conversation on every parent-only turn and overwrites the parent's record on the
- * way through. So the recorded key wins, the session-derived key is the fallback that reproduces
- * it when the parent has not been seen in this scope, and the raw parent id is never the answer.
+ * The parent-only case keeps the trap it always had. Such a turn belongs to the parent's
+ * conversation, so it must land on the binding the parent is already using. With a session in
+ * hand that is immediate, since both derive the same cohort key. Without one, the recorded key
+ * wins and the parent id anchors the fallback; the raw parent id is never the answer.
  */
 export function codexConversationIdentity(
   headers: Headers,
@@ -190,24 +245,20 @@ export function codexConversationIdentity(
 
   if (threadId === undefined) {
     if (parentThreadId === undefined) return undefined;
-    const recorded = liveLineageRecord(
-      lineageByScope.get(codexLineageScopeKey(headers)),
-      parentThreadId,
-      now,
-    );
+    const parentOnlyKey = cohortConversationKey(headers, sessionId, parentThreadId, now);
+    if (parentOnlyKey === undefined) return undefined;
     return {
-      conversationKey: recorded?.conversationKey
-        ?? codexConversationKeyFor(sessionId ?? parentThreadId, parentThreadId),
+      conversationKey: parentOnlyKey,
       recordThreadId: parentThreadId,
       ...(sessionId !== undefined ? { sessionId } : {}),
       legacyConversationKey: parentThreadId,
       declaresParent: false,
     };
   }
-  const familyId = sessionId ?? parentThreadId;
-  if (familyId === undefined) return undefined;
+  const conversationKey = cohortConversationKey(headers, sessionId, parentThreadId, now);
+  if (conversationKey === undefined) return undefined;
   return {
-    conversationKey: codexConversationKeyFor(familyId, threadId),
+    conversationKey,
     recordThreadId: threadId,
     ...(sessionId !== undefined ? { sessionId } : {}),
     ...(parentThreadId !== undefined ? { parentThreadId } : {}),
@@ -313,7 +364,7 @@ function lineageFor(
   const parentConversationKey = parentThreadId === undefined
     ? undefined
     : parentRecord?.conversationKey
-      ?? codexConversationKeyFor(identity.sessionId ?? parentThreadId, parentThreadId);
+      ?? cohortKeyFromAnchor(identity.sessionId, parentThreadId);
   const rootSessionKey = parentConversationKey === undefined
     ? identity.conversationKey
     : parentRecord?.rootSessionKey ?? parentConversationKey;

package/src/codex/loopback-target.ts

@@ -5,6 +5,37 @@ import { NATIVE_RESERVE_MODEL } from "./catalog/native-models";
 export const CODEX_RESERVE_HELPER_UNSUPPORTED_MESSAGE =
   "Luna Reserve compatibility is only available as a conversation model, not a vision helper. Choose another vision model.";
 
+export const CODEX_RESERVE_OPT_IN_REQUIRED_MESSAGE =
+  "Luna Reserve (gpt-reserve) is not forwarded without the local Desktop authless opt-in."
+  + " OpenCodex holds no Reserve entitlement to send for this request, so the upstream would answer with a"
+  + " usage-limit error that names neither the cause nor the fix."
+  + " Enable the opt-in with 'ocx system settings --desktop-authless on' (or set codexDesktopAuthless to true"
+  + " in config.json), then retry. Choose another model to keep working without it.";
+
+/**
+ * Strict complement of {@link isCodexReserveRequestEligible} for the FLAG reason ONLY (#4940).
+ *
+ * Read the two together. This answers a narrower question: Reserve was asked for, every ingress
+ * condition eligibility requires already holds, and the single missing piece is the operator
+ * opt-in. Flipping `codexDesktopAuthless` to true therefore always turns a true here into a true
+ * from {@link isCodexReserveRequestEligible}, which is what makes it honest for the refusal to
+ * name that one setting. The other two ineligibility reasons are deliberately not covered: a
+ * client role and a non-loopback admission source are different situations, and the correct
+ * answer for both is still to forward exactly as before.
+ *
+ * Callers classify the concrete destination as canonical forward before using this predicate, the
+ * same obligation {@link isCodexReserveHelperUnsupported} carries. An operator who has aliased or
+ * routed `gpt-reserve` onto some other provider owns a path that works, and it must keep working.
+ */
+export function isCodexReserveOptInMissing(
+  config: Pick<OcxConfig, "codexDesktopAuthless" | "runtimeRole">,
+  modelId: string,
+  admission: Pick<DataPlaneAdmission, "source"> | undefined,
+): boolean {
+  return modelId === NATIVE_RESERVE_MODEL && config.codexDesktopAuthless !== true
+    && config.runtimeRole !== "client" && admission?.source === "loopback";
+}
+
 /** Callers classify the concrete destination as canonical forward before using this predicate. */
 export function isCodexReserveHelperUnsupported(
   config: Pick<OcxConfig, "codexDesktopAuthless" | "runtimeRole">,
@@ -97,3 +128,12 @@ export function isEffectiveCodexDesktopAuthless(
     && config.runtimeRole !== "client"
     && !shouldInjectApiAuthHeader(config);
 }
+
+/** Keep reporting aligned with the admission-token gate used by standalone injection. */
+export function isEffectiveCodexClientCompaction(
+  config: Pick<OcxConfig, "runtimeRole" | "hostname" | "unauthenticatedLoopbackListener" | "codexClientCompaction"> | undefined,
+): boolean {
+  return config?.codexClientCompaction === true
+    && config.runtimeRole !== "client"
+    && !shouldInjectApiAuthHeader(config);
+}

package/src/codex/main-account-hard-lock.ts

@@ -1,7 +1,8 @@
 import type { OcxConfig } from "../types";
 import { getMainPolicyQuota } from "./quota";
+import { MAIN_ACCOUNT_HARD_LOCK_PERCENT } from "./quota-types";
 
-export const MAIN_ACCOUNT_HARD_LOCK_PERCENT = 99;
+export { MAIN_ACCOUNT_HARD_LOCK_PERCENT };
 
 export interface MainAccountHardLockStatus {
   enabled: boolean;