@bitkyc08/opencodex 2.55.0 → 2.57.0

package/src/server/workflow-refusal.ts

@@ -0,0 +1,84 @@
+/**
+ * The one place that knows how this proxy refuses a turn on its own workflow budget.
+ *
+ * It is a module rather than two inline blocks because the two call sites -- the HTTP admission
+ * check in `src/server/index.ts` and the pre-dispatch ceiling check in
+ * `src/server/responses/core.ts` -- had drifted into saying different things about the same
+ * refusal, and because the non-obvious part below has to be stated once and not twice.
+ */
+import { formatErrorResponse } from "../bridge";
+import {
+  addFinalRequestLog,
+  markLocalRequestLogRefusal,
+  type RequestLogContext,
+} from "./request-log";
+import {
+  WORKFLOW_LOCAL_REFUSAL_HEADER,
+  workflowDenialSummary,
+  recordWorkflowRefusalEvent,
+  type WorkflowDenial,
+} from "../lib/workflow-budget";
+
+/**
+ * What a caller needs to hand over for the refusal to become a row on `/api/logs`.
+ *
+ * The HTTP admission check refuses before the body is parsed, so its `logCtx` still carries the
+ * `unknown` model and provider the caller seeded it with. That is the honest record -- this
+ * request genuinely never resolved either -- and it is the same placeholder the native
+ * passthrough path already writes. Skipping the row entirely was the worse option: an operator
+ * reading the logs saw no trace at all of a request the proxy had refused.
+ */
+export interface WorkflowRefusalLog {
+  readonly requestId: string;
+  readonly start: number;
+  readonly logCtx: RequestLogContext;
+}
+
+/**
+ * Build the 429 for a refusal this proxy made itself.
+ *
+ * The status and type arguments below do not reach the client: `classifyError` rewrites every
+ * 429 to `rate_limit_error` / `rate_limit_exceeded`, so the body is shaped exactly like a
+ * provider rate limit. That is a deliberate wire contract -- changing it would change how every
+ * client retries -- which leaves two places to carry the truth. The message names the ceiling
+ * that fired and says no provider was contacted, and the header carries the machine-readable
+ * name. Nothing upstream sets that header, so its presence is conclusive.
+ *
+ * The row is where an operator actually looks, so it gets the same treatment #4639 established:
+ * `terminalSource: "synthetic"`, a local reason, and an error code naming the ceiling. Pass
+ * `logCtx` when the caller is inside a turn that will write its own row, or `refusalLog` when
+ * the refusal happens before any row exists and this is the only chance to write one.
+ */
+export function workflowRefusalResponse(
+  reason: WorkflowDenial,
+  logCtx?: RequestLogContext,
+  refusalLog?: WorkflowRefusalLog,
+  rootId?: string,
+): Response {
+  const summary = workflowDenialSummary(reason);
+  // Only a caller that decided the refusal ITSELF passes a root id. admitWorkflowTurn already
+  // records its own denials, so passing one there would double-count them.
+  if (rootId) recordWorkflowRefusalEvent(rootId, reason);
+  const recordOn = logCtx ?? refusalLog?.logCtx;
+  if (recordOn) {
+    markLocalRequestLogRefusal(recordOn, summary.code);
+    // A locally assigned code wins in addFinalRequestLog, so this is what names the ceiling in
+    // the logs column rather than the generic rate-limit classification a 429 would get.
+    recordOn.errorCode = summary.code;
+  }
+  if (refusalLog) {
+    addFinalRequestLog(refusalLog.requestId, refusalLog.start, refusalLog.logCtx, 429, {
+      closeReason: "terminal",
+    });
+  }
+  const refusal = formatErrorResponse(
+    429,
+    reason === "workflow-sends-exhausted" ? "workflow_budget_exhausted" : "queue_capacity_exceeded",
+    summary.message,
+  );
+  refusal.headers.set(WORKFLOW_LOCAL_REFUSAL_HEADER, summary.code);
+  // Without this a browser dashboard cannot read the header at all: the data plane never sets
+  // Access-Control-Expose-Headers, so a cross-origin reader sees only the CORS-safelisted ones.
+  refusal.headers.set("Access-Control-Expose-Headers", WORKFLOW_LOCAL_REFUSAL_HEADER);
+  return refusal;
+}

package/src/service/windows-ops.ts

@@ -1,4 +1,5 @@
-import { chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, lstatSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { win32 } from "node:path";
 import { winswXmlPath } from "../lib/winsw";
 import { hardenSecretPath } from "../lib/windows-secret-acl";
@@ -9,7 +10,7 @@ import { existsSync, mkdirSync, mkdtempSync, rmdirSync, unlinkSync } from "node:
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { getConfigDir } from "../config";
-import { runWindowsElevatedScheduledTaskRegistration, WindowsSchtasksError } from "../lib/windows-elevation";
+import { OCX_ELEVATED_STAGING_UNREADABLE, runWindowsElevatedScheduledTaskRegistration, WindowsSchtasksError, type StagedWindowsTaskXml } from "../lib/windows-elevation";
 import { defaultWinswEntry, installWinswService, statusWinswRaw, uninstallWinswService, WINSW_SERVICE_ID, type WinswStatus } from "../lib/winsw";
 import { forgetEphemeralSecretDir, forgetEphemeralSecretPath, hardenSecretDir } from "../lib/windows-secret-acl";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
@@ -165,6 +166,197 @@ function cleanupWindowsSchedulerStage(
   if (cleanupError) throw cleanupError;
 }
 
+/** A staged payload set for one elevated registration, plus the way to remove it. */
+export interface StagedElevatedSchedulerRegistration {
+  readonly xml: StagedWindowsTaskXml;
+  readonly expectedExisting?: StagedWindowsTaskXml;
+  /** Remove every staged artifact. Idempotent, so a second call after success is a no-op. */
+  cleanup(): void;
+}
+
+export interface ElevatedSchedulerStagingDeps {
+  createStageDir?: () => string;
+  hardenDir?: (path: string) => void;
+  writePayload?: (path: string, bytes: Buffer) => void;
+  hardenPath?: (path: string) => void;
+  inspect?: (path: string) => { isSymbolicLink(): boolean; isFile(): boolean; isDirectory(): boolean };
+  removeStageDir?: (path: string) => void;
+}
+
+/**
+ * Stage the captured definitions an elevated registration needs, as files rather than
+ * as command-line payloads (#4692).
+ *
+ * A file that an administrator process will read is itself a privilege-escalation
+ * surface, so three properties have to hold together and none of them is sufficient
+ * alone:
+ *
+ * - **Access.** The directory is created fresh by `mkdtemp`, then ACL-hardened before
+ *   anything is written into it, so another local account cannot read or replace the
+ *   payload while the UAC prompt is open. Hardening the directory first is what makes
+ *   the file private from the moment it exists.
+ * - **No reparse point.** Each artifact is inspected with `lstat` and rejected unless it
+ *   is what it claims to be. `wx` already refuses to create over an existing name, which
+ *   is the atomic step here — there is no replace path to race, because every path is
+ *   inside a directory that did not exist a moment ago. The explicit check is what keeps
+ *   that guarantee from depending on a reading of `O_EXCL` semantics.
+ * - **Tamper evidence.** The digest is taken over the exact bytes written, and the
+ *   elevated script recomputes it over the bytes it reads. An ACL cannot cover this:
+ *   a process running as the same user has the same SID and can rewrite the file, so
+ *   the digest is the only thing that makes such a swap fail closed rather than
+ *   silently register a different task definition.
+ *
+ * Payloads are UTF-16LE with no BOM, and the elevated process decodes them straight into
+ * `Register-ScheduledTask`. What is hashed is therefore exactly what is registered, with
+ * no trimming step in between that the two sides could disagree about.
+ */
+export function stageElevatedSchedulerRegistration(
+  xml: string,
+  expectedExistingXml?: string,
+  deps: ElevatedSchedulerStagingDeps = {},
+): StagedElevatedSchedulerRegistration {
+  const createStageDir = deps.createStageDir
+    ?? (() => mkdtempSync(join(tmpdir(), WINDOWS_SCHEDULER_STAGE_PREFIX)));
+  const hardenDir = deps.hardenDir ?? ((path: string) => { hardenSecretDir(path, { required: true }); });
+  const writePayload = deps.writePayload ?? ((path: string, bytes: Buffer) => {
+    writeFileSync(path, bytes, { flag: "wx", mode: 0o600 });
+  });
+  const hardenPath = deps.hardenPath ?? ((path: string) => { hardenSecretPath(path, { required: true }); });
+  const inspect = deps.inspect ?? ((path: string) => lstatSync(path));
+  const removeStageDir = deps.removeStageDir ?? ((path: string) => { rmdirSync(path); });
+
+  const stageDir = createStageDir();
+  const files: string[] = [];
+  const cleanup = (): void => {
+    let failure: unknown;
+    for (const file of files.splice(0)) {
+      try {
+        unlinkSync(file);
+        forgetEphemeralSecretPath(file);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") forgetEphemeralSecretPath(file);
+        else if (failure === undefined) failure = error;
+      }
+    }
+    try {
+      removeStageDir(stageDir);
+      forgetEphemeralSecretDir(stageDir);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") forgetEphemeralSecretDir(stageDir);
+      else if (failure) throw new AggregateError([failure, error], "Elevated Task Scheduler staging cleanup failed.");
+      else failure = error;
+    }
+    if (failure) throw failure;
+  };
+
+  try {
+    try { chmodSync(stageDir, 0o700); } catch { /* required Windows ACL is authoritative */ }
+    const dirStats = inspect(stageDir);
+    if (dirStats.isSymbolicLink() || !dirStats.isDirectory()) {
+      throw new Error(`Refusing to stage an elevated Task Scheduler payload under a redirected path: ${stageDir}`);
+    }
+    hardenDir(stageDir);
+    const stage = (name: string, value: string): StagedWindowsTaskXml => {
+      const path = join(stageDir, name);
+      const bytes = Buffer.from(value, "utf16le");
+      writePayload(path, bytes);
+      files.push(path);
+      const stats = inspect(path);
+      if (stats.isSymbolicLink() || !stats.isFile()) {
+        throw new Error(`Refusing to stage an elevated Task Scheduler payload through a redirected path: ${path}`);
+      }
+      hardenPath(path);
+      return { path, sha256: createHash("sha256").update(bytes).digest("hex") };
+    };
+    return {
+      xml: stage("register.xml", xml),
+      ...(expectedExistingXml === undefined
+        ? {}
+        : { expectedExisting: stage("expected.xml", expectedExistingXml) }),
+      cleanup,
+    };
+  } catch (error) {
+    try {
+      cleanup();
+    } catch (cleanupError) {
+      throw new AggregateError(
+        [error, cleanupError],
+        "Elevated Task Scheduler staging failed and could not be cleaned up.",
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Turn an elevated registration exit code into something an operator can act on.
+ *
+ * The elevated process runs hidden, so nothing it writes survives; only the exit code
+ * crosses back. That makes an unexplained code the whole user-facing error, which is
+ * exactly what made the ENAMETOOLONG in #4692 expensive to diagnose. Staging introduces
+ * one new failure of its own — the payload is readable only by the account that created
+ * it, so an elevation answered with a different administrator's credentials cannot open
+ * it — and that one gets named along with its remedy rather than surfacing as a number.
+ */
+export function describeElevatedRegistrationFailure(
+  failureLabel: string,
+  exitCode: number,
+  stageDir: string,
+): string {
+  if (exitCode === OCX_ELEVATED_STAGING_UNREADABLE) {
+    return `${failureLabel}: the elevated process could not read the staged task definition in `
+      + `${stageDir}. That directory is readable only by the account that staged it, so this `
+      + "happens when the UAC prompt was answered with a different administrator account. "
+      + "Approve the prompt as the signed-in user, or run the command again from a session "
+      + "already elevated as that user.";
+  }
+  return `${failureLabel} with exit code ${exitCode}.`;
+}
+
+/**
+ * Stage, elevate, and clean up — on every exit, including UAC cancellation and a
+ * synchronous spawn failure.
+ *
+ * A cleanup failure never replaces the registration failure it followed: an operator
+ * told only that a temp directory could not be removed would have no idea the task was
+ * never registered.
+ */
+async function runStagedElevatedSchedulerRegistration(
+  taskName: string,
+  xml: string,
+  replace: boolean,
+  expectedExistingXml: string | undefined,
+  failureLabel: string,
+): Promise<void> {
+  const staged = stageElevatedSchedulerRegistration(xml, expectedExistingXml);
+  let failure: unknown;
+  try {
+    const exitCode = await runWindowsElevatedScheduledTaskRegistration(
+      taskName,
+      staged.xml,
+      replace,
+      staged.expectedExisting,
+    );
+    if (exitCode !== 0) {
+      failure = new Error(describeElevatedRegistrationFailure(failureLabel, exitCode, dirname(staged.xml.path)));
+    }
+  } catch (error) {
+    failure = error;
+  }
+  try {
+    staged.cleanup();
+  } catch (cleanupError) {
+    if (failure) {
+      throw new AggregateError(
+        [failure, cleanupError],
+        "Elevated Task Scheduler registration failed and its staging could not be cleaned up.",
+      );
+    }
+    throw cleanupError;
+  }
+  if (failure) throw failure;
+}
+
 export function stageWindowsSchedulerRegistrationXml(
   attemptNonce: string,
   deps: WindowsSchedulerRegistrationStageDeps = {},
@@ -294,7 +486,8 @@ export async function registerFreshWindowsSchedulerTask(
       throw error;
     }
     // Register from the captured XML string inside the elevated process. Another
-    // same-user process can mutate its own temp files, but cannot change this command.
+    // same-user process can mutate its own temp files, so the captured bytes are staged
+    // privately and the elevated script verifies their digest before registering them.
     // UAC can remain open for an arbitrary amount of time. Recheck the captured predecessor
     // before launch; the elevated helper repeats the same check after consent and before Force.
     assertReplacementPrecondition();
@@ -303,15 +496,13 @@ export async function registerFreshWindowsSchedulerTask(
       xml: string,
       replaceCurrent: boolean,
       previousXml?: string,
-    ) => {
-      const exitCode = await runWindowsElevatedScheduledTaskRegistration(
-        taskName,
-        xml,
-        replaceCurrent,
-        previousXml,
-      );
-      if (exitCode !== 0) throw new Error(`Background service install failed with exit code ${exitCode}.`);
-    });
+    ) => runStagedElevatedSchedulerRegistration(
+      taskName,
+      xml,
+      replaceCurrent,
+      previousXml,
+      "Background service install failed",
+    ));
     await elevate(TASK, expectedXml, replace, expectedExistingXml);
   }
 
@@ -501,10 +692,13 @@ export async function restoreWindowsSchedulerTaskIfAbsent(registeredXml: string)
       ) {
         throw error;
       }
-      const exitCode = await runWindowsElevatedScheduledTaskRegistration(TASK, registeredXml, false);
-      if (exitCode !== 0) {
-        throw new Error(`Task Scheduler rollback failed with exit code ${exitCode}.`);
-      }
+      await runStagedElevatedSchedulerRegistration(
+        TASK,
+        registeredXml,
+        false,
+        undefined,
+        "Task Scheduler rollback failed",
+      );
     }
     const recoveredXml = statusWindowsXml();
     if (!windowsSchedulerRegistrationMatchesSnapshot(recoveredXml, registeredXml)) {

package/src/service/windows-scheduler.ts

@@ -5,6 +5,7 @@ import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { ELEVATION_REQUEST_TIMEOUT_MS, OCX_ELEVATED_PROTOCOL_FAILED, raceWithTimeout, resolveTrustedWindowsSchtasksExe, startElevatedSchtasksCreateAndRun, runWindowsElevated, toWindowsSchtasksError, WindowsElevationError, type ElevatedSchedulerOutcome, type ElevatedSchtasksCreateAndRunExecution, type ElevatedSchtasksCreateAndRunResult } from "../lib/windows-elevation";
 import { statusWinswRaw } from "../lib/winsw";
+import { decodeWindowsTextBytes, type WindowsTextDecodeOptions } from "../lib/windows-text";
 import { isTestHomeGuardArmed } from "../lib/test-home-guard";
 import { TASK, windowsServiceScriptPath, windowsLauncherVbsPath, windowsTaskXmlPath, writeServiceInstallState } from "./state";
 import { buildWindowsSchtasksCreateArgs, windowsTaskRegistrationOwnedByAttempt, windowsTaskRegistrationHealthy } from "./windows-taskxml";
@@ -16,28 +17,34 @@ import { WINSW_SERVICE_ID } from "../lib/winsw";
  * Decode schtasks stdout. `/query /xml` emits UTF-16LE (often with BOM) because the
  * registered task document is UTF-16; reading that as UTF-8 makes every health check
  * fail ("registration present but unhealthy") and rolls back a successful elevated create.
+ *
+ * Redirected output is NOT always UTF-16. Its encoding follows the console output code
+ * page of the spawning process tree rather than the XML declaration, so on a zh-CN host
+ * (ACP/OEMCP 936) the bytes are GBK — including inside a no-console background service.
+* Decoding those as UTF-8 turned a CJK account name in
+ * `<SessionStateChangeTrigger><UserId>` into U+FFFD, the trigger scope then failed to
+ * match the correctly resolved `[SID, MACHINE\<name>]`, and `ocx service repair`
+* aborted at its recognition gate on a registration OpenCodex had itself created. The
+ * same mojibake rolled back fresh installs at post-create verification (#4691).
+ *
+ * The fix is entirely in byte decoding, before any XML is parsed. The trigger scope stays
+ * an exact identity comparison: forgiving a replacement character there would let two
+ * different non-ASCII accounts collapse to the same value, which is a worse failure than
+ * the refusal it replaces.
+ *
+ * `decodeWindowsTextBytes` is the decoder this project already built for this class
+ * (UTF-16 -> strict UTF-8 -> the locale's legacy code page), and it already fixed the
+ * sibling `whoami`/PowerShell decode in `src/lib/windows-user-principal.ts` (#2914, and
+ * #722 for CP949). This call site was the last one still ending in a lossy UTF-8 decode.
  */
-export function decodeSchtasksOutput(buffer: Buffer): string {
-  if (buffer.length === 0) return "";
-  const bomUtf16Le = buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe;
-  const bomUtf16Be = buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff;
-  const looksUtf16Le = buffer.length >= 4
-    && buffer[1] === 0x00
-    && buffer[3] === 0x00
-    && buffer[0] !== 0x00;
-  if (bomUtf16Le || looksUtf16Le) {
-    return buffer.toString("utf16le").replace(/^\uFEFF/, "").trim();
-  }
-  if (bomUtf16Be) {
-    // Swap pairs then decode as utf16le.
-    const swapped = Buffer.alloc(buffer.length - 2);
-    for (let i = 2; i + 1 < buffer.length; i += 2) {
-      swapped[i - 2] = buffer[i + 1]!;
-      swapped[i - 1] = buffer[i]!;
-    }
-    return swapped.toString("utf16le").trim();
-  }
-  return buffer.toString("utf8").replace(/^\uFEFF/, "").trim();
+export function decodeSchtasksOutput(
+  buffer: Buffer,
+  options: WindowsTextDecodeOptions = {},
+): string {
+  // `options` exists so a test can pin the code page; every production call passes the
+  // buffer alone and uses the active Intl locale, which is available to a service with no
+  // console because the selection reads the process locale rather than a console handle.
+  return decodeWindowsTextBytes(buffer, options);
 }
 
 function runFile(file: string, args: string[]): string {

package/src/service.ts

@@ -19,7 +19,7 @@ export { decodeSchtasksOutput, setQuerySchtasksForTests, formatWindowsSchedulerS
 export type { WindowsSchedulerXmlState } from "./service/windows-taskxml";
 export { buildWindowsServiceScript, buildWindowsSchtasksCreateArgs, buildWindowsSchtasksCreateArgsForXml, buildWindowsLauncherVbs, buildWindowsTaskXml, buildWindowsTaskXmlDocument, windowsTaskRegistrationOwnedByAttempt, windowsTaskRegistrationHealthy, readWindowsSchedulerXmlState } from "./service/windows-taskxml";
 export type { WindowsSchedulerRegistrationStageDeps, FreshWindowsSchedulerRegistrationDeps, RemoveNativeWindowsServiceDeps } from "./service/windows-ops";
-export { windowsListenPort, winswListenPort, writeServiceDefinitionFile, definitionCarriesCredential, stageWindowsSchedulerRegistrationXml, registerFreshWindowsSchedulerTask, removeNativeWindowsServiceForScheduler, assertWindowsNativeServiceAccountSupported, isWindowsSchedulerEndBenign, stopWindows, stopWindowsChecked, classifyWindowsServiceStop } from "./service/windows-ops";
+export { windowsListenPort, winswListenPort, writeServiceDefinitionFile, definitionCarriesCredential, stageWindowsSchedulerRegistrationXml, stageElevatedSchedulerRegistration, describeElevatedRegistrationFailure, registerFreshWindowsSchedulerTask, removeNativeWindowsServiceForScheduler, assertWindowsNativeServiceAccountSupported, isWindowsSchedulerEndBenign, stopWindows, stopWindowsChecked, classifyWindowsServiceStop } from "./service/windows-ops";
 export type { ServiceRepairVerb, RepairServiceDeps } from "./service/repair";
 export { repairService } from "./service/repair";
 export type { ServiceInstallPreparationDeps, FreshWindowsSchedulerInstallDeps, ServiceStopOutcome, ServiceUninstallOutcome } from "./service/orchestration";

package/src/types/config.ts

@@ -882,6 +882,36 @@ export interface OcxConfig {
      * binding under either setting -- neither is a cache-affinity preference.
      */
     cacheAffinity?: boolean;
+    /**
+     * Operator-declared quota domains: groups of credential ids that demonstrably share
+     * one upstream usage limit (#4546, wp6). Members of one group count once toward
+     * available capacity, and a quota refusal inside a group is never answered by
+     * rotating to another member -- the limit is the same, so the move would pay a cold
+     * prefix for zero new capacity.
+     *
+     * Declared groups speak only to quota. Sharing a usage limit says nothing about
+     * prompt-cache compatibility, which keeps its own provider-documented domain.
+     * Absent or empty means no declared grouping, so an unconfigured install behaves
+     * exactly as before.
+     *
+     * A declaration has to mean exactly one thing, so the config rejects the spellings
+     * that could mean two. Credential ids are provider-scoped elsewhere (the auth store
+     * keys an account by provider and id), so each member is written
+     * `"<provider>:<credential-id>"` -- a bare `"acct-1"` names one credential per
+     * provider and would merge unrelated domains. The provider segment is matched
+     * case-insensitively through the usual aliases, so `chatgpt:` and `codex:` both mean
+     * OpenAI. Group ids must be unique, `credentials` must be non-empty, and a credential
+     * may belong to at most one group; a declaration that breaks any of those is rejected
+     * on write and dropped with a warning on load, never resolved by list order.
+     */
+    credentialGroups?: Array<{
+      /** Operator-chosen group identifier; only equality matters. */
+      id: string;
+      /** Provider-qualified credential ids (`"<provider>:<credential-id>"`), non-empty. */
+      credentials: string[];
+      /** Free-text provenance note for the operator's own records. */
+      note?: string;
+    }>;
   };
   /** Active pool account id for next session. undefined = main (passthrough as-is). */
   activeCodexAccountId?: string;
@@ -981,6 +1011,7 @@ export type OcxAccountPoolQuotaWindow = "five-hour" | "weekly" | "max-utilizatio
 
 export type OcxComboStrategy = "failover" | "round-robin" | "random" | "least-used" | "reset-window";
 export type OcxComboDefaultEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
+export type OcxComboDefaultEffortMode = "fallback" | "force";
 
 /**
  * How a combo derives the reasoning ladder it publishes to the picker.
@@ -1016,8 +1047,10 @@ export interface OcxComboConfig {
   cooldownMs?: number;
   /** Maximum wait for an eligible target cooldown to expire before failing closed. Default 0; range 0..600000, per selection attempt. */
   waitForCooldownMs?: number;
-  /** Used when the client omits reasoning.effort. null/omitted leaves the target default unchanged. */
+  /** Used as a fallback when the client omits reasoning.effort, or as an override in `force` mode. null/omitted leaves the target default unchanged. */
   defaultEffort?: OcxComboDefaultEffort | null;
+  /** `force` makes the combo default override a valid client effort. Omitted / `fallback` preserves client precedence. */
+  defaultEffortMode?: OcxComboDefaultEffortMode;
   /**
    * Picker-ladder derivation policy. Omitted / `"strict"` keeps the legacy rule where an
    * explicitly empty target ladder suppresses the whole combo's effort control.

package/src/types/request.ts

@@ -154,9 +154,11 @@ export interface OcxAssistantMessage {
   model?: string;
   timestamp: number;
   /**
-   * Kiro `reasoningContent.redactedContent` for THIS assistant turn — an opaque encrypted blob
-   * Kiro replays to preserve model reasoning across turns. Provider-specific and unrenderable, so
-   * it rides the message rather than a content part: any other adapter simply ignores it.
+   * Kiro's encrypted reasoning blob for THIS assistant turn — the opaque value from the turn's
+   * `reasoningContentEvent` (`signature` for the GPT-5.6 family, `redactedContent` for the base64
+   * shape), tagged with the wire field it must be replayed on (see kiro/reasoning.ts). Kiro
+   * replays it to preserve model reasoning across turns. Provider-specific and unrenderable, so it
+   * rides the message rather than a content part: any other adapter simply ignores it.
    */
   kiroRedactedReasoning?: string;
 }
@@ -317,8 +319,9 @@ export type AdapterEvent =
   // opaque redacted_thinking blocks. Both must be replayed verbatim or tool-use turns 400.
   | { type: "thinking_signature"; signature: string }
   | { type: "redacted_thinking"; data: string }
-  // Kiro reasoning round-trip: the encrypted `redactedContent` blob for the CURRENT assistant turn.
-  // Never rendered — it only rides the reasoning item's envelope so the next request can replay it.
+  // Kiro reasoning round-trip: the encrypted reasoning blob for the CURRENT assistant turn, tagged
+  // with the wire field it arrived on. Never rendered — it only rides the reasoning item's envelope
+  // so the next request can replay it verbatim.
   | { type: "kiro_redacted_reasoning"; data: string }
   | { type: "reasoning_raw_delta"; text: string }
   | { type: "tool_call_start"; id: string; name: string; providerMetadata?: OcxProviderOpaqueToolCallMetadata }

package/src/types/tools.ts

@@ -67,6 +67,30 @@ const CODE_MODE_HELPER_TOOL_NAMES = [
  */
 export const CODE_MODE_EXEC_TOOL_NAME = "exec";
 
+/**
+ * Spellings that may never be MANUFACTURED as a bare alias for a namespaced tool.
+ *
+ * A bare alias is an ordinary compatibility affordance -- providers echo a namespaced tool
+ * without its prefix, and restoring the identity needs the bare spelling registered. For these
+ * six it is also an authorization decision, because a declared-name set is what
+ * `normalizeDeclaredToolName` and `declaresCodeModeExec` read: bare `exec` turns nested-helper
+ * normalization on for a catalog that never declared the shell, bare `exec_command` or
+ * `shell_command` turns it off for one that did, and the rest are accepted as declared calls the
+ * caller only ever authorized under a namespace.
+ *
+ * This is a property of the SPELLING, not of the namespace that declared it and not of the reason
+ * the alias was being added. It lives here, beside the names it protects, because every site that
+ * builds a declared-name set has to apply the same list -- the two that kept their own copies each
+ * drifted, once to a single namespace and once to a single name.
+ *
+ * A genuine namespace-free declaration is NOT covered: that is the caller declaring the tool, not
+ * a namespace being discarded to synthesize a bare name.
+ */
+export const NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES: ReadonlySet<string> = new Set<string>([
+  CODE_MODE_EXEC_TOOL_NAME,
+  ...CODE_MODE_HELPER_TOOL_NAMES,
+]);
+
 /**
  * Normalizes provider-emitted tool names against declared tool catalogs.
  *

package/src/types.ts

@@ -16,6 +16,7 @@ export {
   isAllowedToolChoice,
   toolChoiceToolPredicate,
   declaresCodeModeExec,
+  NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES,
 } from "./types/tools";
 
 export type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode } from "./types/wire";
@@ -74,6 +75,7 @@ export type {
   OcxAccountPoolQuotaWindow,
   OcxComboStrategy,
   OcxComboDefaultEffort,
+  OcxComboDefaultEffortMode,
   OcxComboReasoningEffortMode,
   OcxComboTarget,
   OcxComboConfig,

package/src/update/index.ts

@@ -481,6 +481,16 @@ export async function runUpdate(): Promise<void> {
         "    After the update: close the Codex app, run 'ocx doctor', then run 'ocx stop' once to retry.",
       );
     }
+    if (decision.reason === "history-deferred") {
+      // Not the same warning: nothing was restored here. Saying "history metadata is
+      // incomplete" would imply config and catalog came back, and an operator who
+      // believed that would not know a teardown is still owed.
+      console.warn(
+        "⚠️  The shared teardown was refused by the Codex history preflight and restored nothing.\n" +
+        "    Config, catalog, history and provenance were preserved, and the teardown receipt was kept.\n" +
+        "    The proxy is down, so the update continues; close the Codex app and run 'ocx stop' once afterwards to finish the restore.",
+      );
+    }
   }
 
   console.log(`Updating${latest ? ` to v${latest}` : ""}…\n$ ${bin} ${cmdArgs.join(" ")}`);

package/src/update/stop-contract.d.mts

@@ -1,2 +1,3 @@
 /** Declaration for the plain-ESM stop contract shared with `bin/ocx.mjs`. */
 export declare const STOP_HISTORY_INCOMPLETE_EXIT_CODE: 79;
+export declare const STOP_HISTORY_DEFERRED_EXIT_CODE: 80;

package/src/update/stop-contract.mjs

@@ -13,3 +13,22 @@
  * the child's code faithfully enough to propagate the confusion.
  */
 export const STOP_HISTORY_INCOMPLETE_EXIT_CODE = 79;
+
+/**
+ * The exit code `ocx stop` uses to say "the proxy is down and the shared teardown was
+ * refused before it changed anything" (#4718).
+ *
+ * This is NOT 79. Seventy-nine means the teardown ran: config and catalog came back to
+ * their native values and only the Codex history metadata could not be finalized, so the
+ * receipt is discharged. Eighty means the Codex history preflight refused FIRST, so
+ * config, catalog, history and provenance are all untouched, the client is still routed
+ * at the proxy that just stopped, and the receipt stays outstanding for a later stop.
+ *
+ * Collapsing the two would be a data-loss bug in the quiet direction: a caller reading 79
+ * discharges an obligation that was never performed.
+ *
+ * Eighty sits in the same unoccupied window as 79 — above `sysexits.h` (64-78), below
+ * `128 + signal`, and outside 0, 1, 2, 4, 64 and 130, which are the codes this CLI and its
+ * dispatcher already emit.
+ */
+export const STOP_HISTORY_DEFERRED_EXIT_CODE = 80;

package/src/update/stop-decision.d.mts

@@ -6,5 +6,5 @@ export declare function decidePostStopUpdate(input: {
   teardownOutstanding?: boolean;
 }): {
   proceed: boolean;
-  reason: "stop-failed" | "runtime-state" | "teardown-outstanding" | "proxy-live" | "proxy-unknown" | "history-only" | "ok";
+  reason: "stop-failed" | "runtime-state" | "teardown-outstanding" | "proxy-live" | "proxy-unknown" | "history-only" | "history-deferred" | "ok";
 };

package/src/update/stop-decision.mjs

@@ -1,4 +1,4 @@
-import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "./stop-contract.mjs";
+import { STOP_HISTORY_DEFERRED_EXIT_CODE, STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "./stop-contract.mjs";
 
 /**
  * May an update replace package files after `ocx stop` returned?
@@ -22,13 +22,22 @@ import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "./stop-contract.mjs";
  *   absence, and replacing files under a live server leaves it running a mix of old and
  *   new modules.
  * - `ok` / `history-only` — proceed; the second also prints the manifest warning.
+ * - `history-deferred` — proceed; the stop is down but restored nothing, because the
+ *   Codex history preflight refused first (#4718). The receipts it kept are the ONLY
+ *   obligations it left, which the child proved before choosing this status, so
+ *   `teardownOutstanding` seeing them is expected rather than disqualifying. Every other
+ *   gate still applies: runtime records and a live or unreadable endpoint abort exactly
+ *   as they do for a clean stop, because package replacement under a live server is the
+ *   danger this function exists to prevent, and a history refusal says nothing about it.
  */
 export function decidePostStopUpdate({ status, hasRuntimeState, liveness, teardownOutstanding = false }) {
   const historyOnly = status === STOP_HISTORY_INCOMPLETE_EXIT_CODE;
-  if (status !== 0 && !historyOnly) return { proceed: false, reason: "stop-failed" };
+  const historyDeferred = status === STOP_HISTORY_DEFERRED_EXIT_CODE;
+  if (status !== 0 && !historyOnly && !historyDeferred) return { proceed: false, reason: "stop-failed" };
   if (hasRuntimeState) return { proceed: false, reason: "runtime-state" };
-  if (teardownOutstanding) return { proceed: false, reason: "teardown-outstanding" };
+  if (teardownOutstanding && !historyDeferred) return { proceed: false, reason: "teardown-outstanding" };
   if (liveness === "live") return { proceed: false, reason: "proxy-live" };
   if (liveness !== "dead") return { proceed: false, reason: "proxy-unknown" };
+  if (historyDeferred) return { proceed: true, reason: "history-deferred" };
   return { proceed: true, reason: historyOnly ? "history-only" : "ok" };
 }