@bitkyc08/opencodex 2.55.0 → 2.57.0

package/src/lib/state-store-registrations.ts

@@ -21,7 +21,7 @@ import {
 } from "../combos/failover";
 import { reconcileComboWarningMemos } from "../combos/request";
 import { reconcileComboRotationState } from "../combos/resolve";
-import { reconcileComboRecall } from "../server/responses/combo-session-recall";
+import { reconcileComboRecall, sweepExpiredComboRecall } from "../server/responses/combo-session-recall";
 import { listLiveComboTargetKeys } from "../combos/types";
 import {
   listLiveConfigOwnershipRoots,
@@ -112,7 +112,11 @@ export const STATE_STORE_REGISTRATIONS = [
   { name: "model-cache-history", reconcileGeneration: reconcileModelCacheGeneration },
   { name: "pool-rotation", reconcileGeneration: reconcilePoolRotationState },
   { name: "combo-rotation", reconcileGeneration: reconcileComboRotationState },
-  { name: "combo-session-recall", reconcileGeneration: reconcileComboRecall },
+  {
+    name: "combo-session-recall",
+    sweepExpired: sweepExpiredComboRecall,
+    reconcileGeneration: reconcileComboRecall,
+  },
   { name: "guardian-backoff", reconcileGeneration: reconcileGuardianBackoff },
   { name: "codex-reauth", reconcileGeneration: reconcileCodexReauthState },
   { name: "oauth-reauth", reconcileGeneration: reconcileOAuthReauthState },

package/src/lib/test-home-guard.ts

@@ -20,7 +20,7 @@
  *    how this incident happened.
  */
 import { homedir } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { realpathSync } from "node:fs";
 
 const GUARD_ENV = "OCX_TEST_HOME_GUARD";
@@ -152,3 +152,87 @@ export function assertNotRealCodexHomeUnderTest(dir: string): void {
     + "Point CODEX_HOME at a temp directory for this test before writing native auth.json.",
   );
 }
+
+/**
+ * The trees a removal must never reach, and the reason each one is named.
+ *
+ * The writer guard above cannot help here. `rmSync` is plain `node:fs`: it calls no writer of
+ * ours, so no assertion of ours runs, and by the time anything could observe the damage the
+ * directory is already gone. On 2026-09-15 that is exactly what happened — a test resolved the
+ * process-global config directory and removed it, taking every OAuth login, the Codex account
+ * store, the service tokens and a 372MB usage ledger with it.
+ */
+const PROTECTED_TREES: ReadonlyArray<{ path: string; lexical: string; label: string }> = [
+  { path: PROTECTED_HOME, lexical: resolve(join(REAL_HOME, ".opencodex")), label: "the real OpenCodex home" },
+  { path: PROTECTED_CODEX_HOME, lexical: resolve(join(REAL_HOME, ".codex")), label: "the real Codex home" },
+  {
+    path: PROTECTED_LAUNCH_AGENTS,
+    lexical: resolve(join(REAL_HOME, "Library", "LaunchAgents")),
+    label: "the real LaunchAgents directory",
+  },
+];
+const PROTECTED_REAL_HOME = canonicalize(REAL_HOME);
+const LEXICAL_REAL_HOME = resolve(REAL_HOME);
+
+/** Canonical paths whose removal is refused. Exported so the guard's tests cannot drift off them. */
+export function protectedRemovalTreesForTests(): readonly string[] {
+  return [PROTECTED_REAL_HOME, ...PROTECTED_TREES.map(tree => tree.path)];
+}
+
+/** Whether `child` sits strictly below `parent`, both already canonicalized. */
+function isInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/**
+ * Why removing `target` is refused, or `null` when it is not a protected location.
+ *
+ * Three relations are refused, not one. Equality alone would still permit
+ * `rmSync(getConfigPath())` against a live `config.json`, and it would permit
+ * `rmSync(homedir())`, which takes the protected tree with it. So a target is refused when it
+ * IS a protected tree, when it sits INSIDE one, or when it is an ANCESTOR of one.
+ *
+ * Canonicalization is what makes a symlink useless as a bypass: a temp path that merely points
+ * at the real home resolves to the real home before any comparison happens.
+ */
+export function protectedRemovalReason(target: string): string | null {
+  // Both spellings are judged, not just the canonical one. Canonicalization is what defeats a
+  // symlink alias, but it also resolves the target away: if `~/.opencodex` is itself a link,
+  // the literal path a caller passed is the thing that gets unlinked, and only the lexical
+  // form still names it. Upstream Codex makes the same distinction in its writable-root
+  // handling, keeping logical and resolved forms side by side rather than collapsing to one.
+  for (const candidate of [canonicalize(target), resolve(target)]) {
+    if (candidate === PROTECTED_REAL_HOME || candidate === LEXICAL_REAL_HOME) {
+      return `the real home directory (${PROTECTED_REAL_HOME})`;
+    }
+    for (const tree of PROTECTED_TREES) {
+      for (const protectedPath of [tree.path, tree.lexical]) {
+        if (candidate === protectedPath) return `${tree.label} (${protectedPath})`;
+        if (isInside(protectedPath, candidate)) return `a path inside ${tree.label} (${protectedPath})`;
+        if (isInside(candidate, protectedPath)) return `an ancestor of ${tree.label} (${protectedPath})`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Throw before a removal that would reach a protected tree.
+ *
+ * Deliberately NOT gated on {@link isTestHomeGuardArmed}. Arming happens in `tests/preload.ts`,
+ * which Bun loads from the `bunfig.toml` it finds in the CURRENT WORKING DIRECTORY — so a run
+ * started outside the repository arms nothing, leaves OPENCODEX_HOME unset, and resolves the
+ * developer's real home. That unarmed run is precisely the one that caused the incident, so the
+ * refusal has to hold without it. Nothing in production calls this; the callers are test
+ * helpers, where the only cost of an unconditional check is a path comparison.
+ */
+export function assertRemovalOutsideProtectedTrees(target: string): void {
+  const reason = protectedRemovalReason(target);
+  if (reason === null) return;
+  throw new Error(
+    `refusing to remove ${reason} from a test process: "${target}" resolves there. `
+    + "Create the directory this test owns with createTempHome() from tests/helpers/temp-home "
+    + "and remove that handle instead (see devlog 260730_codex_rs_upstream_v2_live_handoff/070).",
+  );
+}

package/src/lib/upstream-retry.ts

@@ -2,10 +2,10 @@
  * Retry guard for upstream fetches that die on stale pooled keep-alive sockets.
  *
  * chatgpt.com (Cloudflare) closes idle keep-alive connections server-side; Bun's fetch pool
- * reuses the half-closed socket and the request write fails with ECONNRESET before any
- * response bytes arrive. Retrying on a fresh connection is safe for our replayable
- * (string-body) upstream requests, because fetch() rejects only before response headers —
- * a caught error here means no response was ever received.
+ * reuses the half-closed socket and a request can fail before response headers arrive.
+ * A pre-header rejection does not prove that the origin did not process the request.
+ * Mechanically reusable bytes do not make a model POST idempotent: an ambiguous reset
+ * becomes a terminal, non-replayable response unless the operation is explicitly safe.
  *
  * Deliberately narrow: timeouts, aborts, ECONNREFUSED/DNS/TLS failures, and HTTP error
  * statuses (returned as Response, never thrown) are NOT retried. Mid-stream SSE resets are
@@ -36,19 +36,66 @@ export function isNonReplayableResponse(response: Response): boolean {
   return nonReplayableResponses.has(response);
 }
 
+/**
+ * The narrower marker: responses this proxy synthesized as a replay refusal.
+ *
+ * {@link isNonReplayableResponse} answers "must not be sent again", which the WebSocket
+ * post-send verdicts share. This one answers "the upstream never said this", and that is the
+ * question a quota recorder or a `Retry-After` synthesizer has to ask. Both were written for
+ * a status that only ever arrived from a provider, so a synthetic 429 reads to them as a
+ * credential that rate-limited us and as a wait worth honouring -- one writes a cooldown
+ * against a credential that refused nothing, the other instructs the client to send the turn
+ * again. A marker rather than a body check, because it has to be answerable before the body
+ * is read and cannot be spoofed by an upstream that happens to echo the code.
+ */
+const replayRefusalResponses = new WeakSet<Response>();
+
+export function markReplayRefusalResponse(response: Response): void {
+  replayRefusalResponses.add(response);
+}
+
+export function isReplayRefusalResponse(response: Response): boolean {
+  return replayRefusalResponses.has(response);
+}
+
 /** Origin never produced a response event; the turn may still be executing. */
 export const UPSTREAM_NO_RESPONSE_CODE = "upstream_no_response";
 /** Transport closed after the send, before any response event. */
 export const UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE = "upstream_closed_before_response";
+/**
+ * This proxy refused to replay a pre-header fetch rejection.
+ *
+ * Distinct from {@link UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE}, which the Codex WebSocket
+ * transport settles as a 502 after the create frame was already sent. Both are ambiguous,
+ * but only this one is a refusal this process made before any response existed, so it
+ * follows the send-budget precedent and answers 429: the Codex client is configured with
+ * `retry_429: false` and `retry_5xx: true` over four attempts, so a 5xx here multiplies
+ * the duplicate send the refusal exists to prevent. See
+ * structure/transports/responses.md#ambiguous-connection-reset-replay-boundary.
+ */
+export const UPSTREAM_RESET_REPLAY_REFUSED_CODE = "upstream_reset_replay_refused";
 const NON_REPLAYABLE_UPSTREAM_CODES: ReadonlySet<string> = new Set([
   UPSTREAM_NO_RESPONSE_CODE,
   UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE,
+  UPSTREAM_RESET_REPLAY_REFUSED_CODE,
 ]);
 
 export function isNonReplayableUpstreamCode(code: unknown): boolean {
   return typeof code === "string" && NON_REPLAYABLE_UPSTREAM_CODES.has(code);
 }
 
+/**
+ * True for the one non-replayable code this proxy owns end to end. The status it carries is
+ * a local decision, so a re-wrapping formatter must restate it rather than inherit the
+ * caller's upstream-shaped status.
+ */
+export function isReplayRefusalCode(code: unknown): boolean {
+  return code === UPSTREAM_RESET_REPLAY_REFUSED_CODE;
+}
+
+/** Client-facing status for {@link UPSTREAM_RESET_REPLAY_REFUSED_CODE}. */
+export const REPLAY_REFUSED_STATUS = 429;
+
 // 1 initial + 2 retries: the pool may hold more than one stale socket.
 const RESET_RETRY_MAX_ATTEMPTS = 3;
 const RESET_RETRY_BASE_DELAY_MS = 150;
@@ -139,7 +186,11 @@ export interface RetryBackoffOptions {
    * first instead of silently lengthening every adapter's backoff.
    */
   retryAfterIsLowerBound?: boolean;
-  /** Hard ceiling for an honoured `Retry-After`, so an hour-long wait cannot park a request. */
+  /**
+   * The wait deadline a caller applies to an honoured `Retry-After`. The delay itself is
+   * never shortened: an instruction longer than the deadline is a reason to END with the
+   * upstream answer, not to send early. Kept for callers that still pass it.
+   */
   retryAfterCeilingMs?: number;
 }
 
@@ -305,10 +356,10 @@ export function retryBackoffDelayMs(attempt: number, opts: RetryBackoffOptions):
   // A provider that names a wait is stating when it will serve again; sending earlier is a
   // request we already know will be refused, and refusing it twice is the retry storm the
   // header exists to prevent. The local maximum bounds our OWN exponential backoff and has no
-  // business shortening someone else's instruction. The ceiling is separate: it stops an
-  // hour-long Retry-After from parking a request forever.
-  const ceiling = opts.retryAfterCeilingMs ?? RETRY_AFTER_CEILING_MS;
-  return Math.min(Math.max(retryAfter, jittered), ceiling);
+  // business shortening someone else's instruction, so the instruction is returned in full.
+  // Whether the request can afford to wait that long is the caller's deadline decision --
+  // fetchWithTransientRetry ends with the upstream answer rather than retrying early.
+  return Math.max(retryAfter, jittered);
 }
 
 export function cancelResponseBodyBestEffort(res: Response): void {
@@ -348,22 +399,42 @@ export async function fetchWithAttemptDeadline(
 }
 
 export interface ResetRetryOptions {
+  /**
+   * Opt in only when repeating this operation cannot duplicate upstream effects.
+   * This permits reset retries, not extra sends: attempts and onSendsConsumed still
+   * bound and count every physical send. A string body is not replay-safety proof.
+   */
+  replaySafe?: boolean;
   abortSignal?: AbortSignal;
   /** Short host/path label for the retry warn log (no secrets/query strings). */
   label?: string;
   /** Total upstream sends allowed, including the first one. Not a per-layer retry count. */
   attempts?: number;
+  /**
+   * Reports how many upstream sends this call actually consumed, so a caller that spans
+   * several legs of one request (initial send, then a 429/account-recovery refetch) can
+   * keep them on ONE budget instead of handing each leg a fresh one.
+   *
+   * It lives on the RESET options, not on the transient ones, because every leg that falls
+   * back to reset-only retry -- the non-policy adapter initial send, and every
+   * `rebuildAndRefetch` recovery kind whose provider has no transient policy -- was not merely
+   * uncounted but UNCOUNTABLE: the callback existed on a type those call sites never reach.
+   */
+  onSendsConsumed?: (sends: number) => void;
 }
 
 export interface TransientRetryOptions extends ResetRetryOptions {
   /** Test seam: per-attempt slow budget override (defaults to TRANSIENT_RETRY_SLOW_ATTEMPT_MS). */
   slowAttemptMs?: number;
   /**
-   * Reports how many upstream sends this call actually consumed, so a caller that spans
-   * several legs of one request (initial send, then a 429/account-recovery refetch) can
-   * keep them on ONE budget instead of handing each leg a fresh one.
+   * How long this caller can wait on an honoured `Retry-After`, defaulting to
+   * {@link RETRY_AFTER_CEILING_MS}. It is a deadline, never a clamp: an instruction inside it
+   * is slept in full, and an instruction past it ends the call with the upstream answer and
+   * its `Retry-After` intact rather than sending early at a provider that already said it
+   * would refuse. A caller with a shorter budget than a minute says so and is not parked past
+   * it; a caller that can genuinely wait longer says so and is not cut short.
    */
-  onSendsConsumed?: (sends: number) => void;
+  retryAfterCeilingMs?: number;
 }
 
 export type UpstreamSendRecovery = "connection-reset" | "transient-5xx";
@@ -424,9 +495,9 @@ export function applyUpstreamRecoveryInit<T extends RequestInit>(
 }
 
 /**
- * Run `doFetch`, retrying only connection-reset-shaped rejections (see
- * isConnectionResetError) with jittered backoff. The caller's thunk must be replay-safe
- * (string body); every retry is logged so persistent resets stay visible.
+ * Run `doFetch` within one send budget. Connection-reset-shaped rejections are
+ * terminal by default; only an explicitly replay-safe operation receives reset retries
+ * with jittered backoff. HTTP responses retain the caller's existing retry policy.
  */
 export async function fetchWithResetRetry(
   doFetch: ReplayableFetch,
@@ -442,6 +513,10 @@ export async function fetchWithResetRetry(
   let sawReset = false;
   for (let attempt = 0; attempt < attempts; attempt++) {
     if (opts.abortSignal?.aborted) throw abortError(opts.abortSignal);
+    // Reported before the await, one physical send at a time: a send that rejects has still
+    // been made, and this helper leaves through four exits (return, reset give-up, non-reset
+    // rethrow, abort), so a per-send report is the only shape that is correct on all of them.
+    opts.onSendsConsumed?.(1);
     try {
       return await doFetch(attempt === 0 ? firstRecovery : "connection-reset");
     } catch (err) {
@@ -453,6 +528,20 @@ export async function fetchWithResetRetry(
         if (sawReset) throw new UpstreamRetryEvidenceError([], err, true);
         throw err;
       }
+      if (opts.replaySafe !== true) {
+        // Return evidence instead of throwing a generic transport error: outer catches
+        // otherwise turn it into a replayable 502 and a combo/account recovery resends it.
+        // The WeakSet protects in-process recovery; the code survives JSON re-wrapping.
+        // Never expose the raw exception, which can contain credentials or request data.
+        const response = new Response(JSON.stringify({ error: {
+          type: "upstream_error",
+          code: UPSTREAM_RESET_REPLAY_REFUSED_CODE,
+          message: "The upstream connection closed before a response was received. The request may already have been processed; automatic replay was stopped.",
+        } }), { status: REPLAY_REFUSED_STATUS, headers: { "content-type": "application/json" } });
+        markResponseNonReplayable(response);
+        markReplayRefusalResponse(response);
+        return response;
+      }
       if (attempt === attempts - 1) throw err;
       sawReset = true;
       lastError = err;
@@ -469,9 +558,9 @@ export async function fetchWithResetRetry(
 }
 
 /**
- * fetchWithResetRetry plus a transient-5xx status retry layer, PRE-STREAM only: a
- * returned Response has by definition not been relayed to the client yet, so replaying
- * the (string-body) request is safe. The failed attempt's body is cancelled before the
+ * fetchWithResetRetry plus the caller-selected transient-5xx policy, PRE-STREAM only.
+ * A received HTTP error follows that policy; an ambiguous reset's non-replayable
+ * verdict always stops it. The failed attempt's body is cancelled before the
  * retry; every returned response (ok, non-transient, aborted, slow, exhausted) keeps
  * its body intact. Honors Retry-After via retryBackoffDelayMs.
  *
@@ -504,13 +593,22 @@ export async function fetchWithTransientRetry(
   // more send -- the loop condition alone was never enough, because every later recovery leg
   // called this helper again and the floor funded each of them.
   const remaining = () => Math.max(0, budget - sent);
+  // The inner reset layer now has its own `onSendsConsumed`, and these are the same physical
+  // sends `countedFetch` already counts. Forwarding the reporter down the `remaining()` path
+  // would report each of them twice, which is how a four-send cap becomes a two-send cap. One
+  // send is counted once, by the outermost layer that owns the budget.
+  const innerResetOptions = (): ResetRetryOptions => ({
+    ...opts,
+    attempts: remaining(),
+    onSendsConsumed: undefined,
+  });
   // Reported in `finally` rather than at each exit: this function returns from five places
   // and throws from one, and a caller sharing the budget across request legs must be told the
   // real count on every one of them.
   try {
   if (budget === 0) throw new SendBudgetExhaustedError(opts.label);
   let attemptStart = Date.now();
-  let res = await fetchWithResetRetry(countedFetch, { ...opts, attempts: remaining() });
+  let res = await fetchWithResetRetry(countedFetch, innerResetOptions());
   for (let attempt = 0; sent < budget; attempt++) {
     // A non-replayable gateway status was settled after the request body had already left
     // for the origin; retrying it here is the automatic resend the marker exists to forbid.
@@ -519,6 +617,19 @@ export async function fetchWithTransientRetry(
     // a response whose body we just cancelled.
     if (opts.abortSignal?.aborted) return res;
     if (Date.now() - attemptStart > slowAttemptMs) return res;
+    const instructedDelay = retryAfterDelayMs(res.headers);
+    // The deadline is the CALLER'S, not this module's default. Reading the constant directly
+    // broke it in both directions: a caller with a 30s budget slept the full 45s an upstream
+    // asked for, and a caller that could genuinely wait 120s was handed the error back for a
+    // 90s instruction it was willing to honour.
+    const waitDeadlineMs = opts.retryAfterCeilingMs ?? RETRY_AFTER_CEILING_MS;
+    if (instructedDelay !== undefined && instructedDelay > waitDeadlineMs) {
+      // Honouring the stated wait would park this request past the deadline it can commit
+      // to, and sleeping only up to the deadline is a send the provider already said it will
+      // refuse. End here instead: the caller receives the upstream answer with its
+      // Retry-After intact and applies its own policy, exactly as on the direct path.
+      return res;
+    }
     console.warn(
       `[upstream-retry] transient ${res.status}${opts.label ? ` (${opts.label})` : ""} — retrying (${sent + 1}/${budget})`,
     );
@@ -535,7 +646,7 @@ export async function fetchWithTransientRetry(
     attemptStart = Date.now();
     transientStatuses.push(res.status);
     try {
-      res = await fetchWithResetRetry(countedFetch, { ...opts, attempts: remaining() }, "transient-5xx");
+      res = await fetchWithResetRetry(countedFetch, innerResetOptions(), "transient-5xx");
     } catch (err) {
       // Keep the prior 5xx evidence attached: the origin already responded, so
       // this rejection is not pre-connection and must not classify as neutral.

package/src/lib/windows-elevation.ts

@@ -250,6 +250,21 @@ export const OCX_ELEVATED_PROTOCOL_FAILED = 13;
 /** Windows ERROR_CANCELLED — reserved for UAC denial; never emitted by the elevated script. */
 export const OCX_ELEVATED_UAC_CANCELLED = 1223;
 
+/**
+ * The elevated process could not read a staged payload (#4692).
+ *
+ * `hardenSecretPath` grants the staging account and strips inheritance, so a split-token
+ * elevation of the same user reads the file and an elevation answered with a DIFFERENT
+ * administrator's credentials does not. The elevated side cannot explain that itself: it
+ * runs hidden, so its stderr goes nowhere and only the exit code survives the boundary.
+ * Without a code of its own the operator would be told "exit code 1" for a cause that
+ * names its own remedy — the same undiagnosable failure this change set exists to remove.
+ *
+ * Deliberately outside OCX_ELEVATED_PROTOCOL_CODES: that list is the create-and-run
+ * transaction's alphabet, and this code belongs to the registration path.
+ */
+export const OCX_ELEVATED_STAGING_UNREADABLE = 14;
+
 export const OCX_ELEVATED_PROTOCOL_CODES = [
   OCX_ELEVATED_SUCCESS,
   OCX_ELEVATED_CREATE_FAILED,
@@ -645,36 +660,83 @@ export function runWindowsElevated(file: string, args: string[]): Promise<number
 }
 
 /**
- * Register one scheduled-task definition without exposing a mutable XML pathname to
- * the elevated process. The XML bytes are fixed in the encoded PowerShell command
- * before UAC; Register-ScheduledTask receives that string directly after elevation.
+ * A task definition staged for the elevated process.
+ *
+ * The bytes live in a freshly created, ACL-hardened private directory, and the digest is
+ * taken over exactly those bytes by the caller that validated them. The elevated script
+ * reads the file once, hashes what it read, and refuses unless the digest matches, so a
+ * pathname is no longer a promise about content — it is a claim the receiver checks.
+ */
+export interface StagedWindowsTaskXml {
+  /** Path inside the caller's hardened staging directory. */
+  readonly path: string;
+  /** Lowercase hex SHA-256 of the staged bytes (UTF-16LE, no BOM). */
+  readonly sha256: string;
+}
+
+/**
+ * Read a staged payload, prove it is the one that was validated, and decode it.
+ *
+ * One read: the bytes that are hashed are the same array that is decoded and registered.
+ * Hashing a path and then reopening it would reintroduce the swap window this check
+ * exists to close.
+ */
+const READ_STAGED_TASK_XML = "function Read-OcxStagedTaskXml([string]$path, [string]$expectedHash) {"
+  // An unreadable payload is a diagnosable condition, not a generic throw: a hidden
+  // elevated process has nowhere to print, so the cause has to ride the exit code.
+  + " try { $bytes = [IO.File]::ReadAllBytes($path) }"
+  + " catch [System.UnauthorizedAccessException] { exit " + OCX_ELEVATED_STAGING_UNREADABLE + " }"
+  + " catch [System.Security.SecurityException] { exit " + OCX_ELEVATED_STAGING_UNREADABLE + " };"
+  + " $sha = [Security.Cryptography.SHA256]::Create();"
+  + " try { $actual = [BitConverter]::ToString($sha.ComputeHash($bytes)).Replace('-', '').ToLowerInvariant() } finally { $sha.Dispose() };"
+  + " if ($actual -cne $expectedHash) { throw 'Task Scheduler staged payload failed its integrity check.' };"
+  + " return [Text.Encoding]::Unicode.GetString($bytes) }";
+
+/**
+ * Register one scheduled-task definition from staged, digest-verified bytes.
+ *
+ * The payloads used to be embedded as base64(utf16le) inside an inner PowerShell script
+ * that was itself base64(utf16le)-encoded into `-EncodedCommand`. Two layers of base64
+ * over UTF-16 cost about 14.2 command-line characters per XML character, and a
+ * replacement carries two payloads, so a ~2 KB task definition pushed the outer command
+ * past the Windows limit and the spawn failed with ENAMETOOLONG before UAC ever
+ * appeared (#4692). On a host where the trigger scope exports as an account name the
+ * re-register path runs on every repair, so repair could never succeed.
+ *
+ * The command now carries two paths and two 64-character digests, so its length no
+ * longer depends on the size of the XML at all.
+ *
+ * The original design goal was "immutable bytes, never a caller-writable pathname".
+ * That goal is kept by different means rather than abandoned: the staging directory is
+ * private and ACL-hardened, the files are created exclusively so nothing can be waiting
+ * at the path, and the digest makes a same-account swap during the UAC prompt fail
+ * closed instead of registering something else. An ACL alone could not do that last
+ * part, because a process running as the same user has the same SID.
+ *
+ * The replacement precondition is unchanged: the elevated process still re-queries the
+ * live registration and compares it to the captured predecessor before passing -Force.
  */
 export function runWindowsElevatedScheduledTaskRegistration(
   taskName: string,
-  xml: string,
+  xml: StagedWindowsTaskXml,
   replace = false,
-  expectedExistingXml?: string,
+  expectedExisting?: StagedWindowsTaskXml,
 ): Promise<number> {
-  if (replace && !expectedExistingXml?.trim()) {
+  if (replace && !expectedExisting) {
     throw new Error("Elevated Task Scheduler replacement requires a captured existing definition.");
   }
-  const xmlBase64 = Buffer.from(xml, "utf16le").toString("base64");
-  const expectedExistingBase64 = expectedExistingXml === undefined
-    ? null
-    : Buffer.from(expectedExistingXml, "utf16le").toString("base64");
   const powerShellPath = windowsPowerShell();
   const powerShellDirectory = powerShellPath.replace(/[\\/][^\\/]+$/, "");
   const scheduledTasksModule = `${powerShellDirectory}\\Modules\\ScheduledTasks\\ScheduledTasks.psd1`;
   const inner = [
     `$taskName = ${psSingleQuote(taskName)}`,
-    `$xmlBase64 = ${psSingleQuote(xmlBase64)}`,
-    "$xml = [Text.Encoding]::Unicode.GetString([Convert]::FromBase64String($xmlBase64))",
+    READ_STAGED_TASK_XML,
+    `$xml = Read-OcxStagedTaskXml ${psSingleQuote(xml.path)} ${psSingleQuote(xml.sha256)}`,
     `$module = Microsoft.PowerShell.Core\\Import-Module -Name ${psSingleQuote(scheduledTasksModule)} -PassThru -Force -ErrorAction Stop`,
     "$registerTask = $module.ExportedCommands['Register-ScheduledTask']",
     "if ($null -eq $registerTask) { throw 'Trusted ScheduledTasks module does not export Register-ScheduledTask.' }",
     ...(replace ? [
-      `$expectedBase64 = ${psSingleQuote(expectedExistingBase64!)}`,
-      "$expectedXml = [Text.Encoding]::Unicode.GetString([Convert]::FromBase64String($expectedBase64))",
+      `$expectedXml = Read-OcxStagedTaskXml ${psSingleQuote(expectedExisting!.path)} ${psSingleQuote(expectedExisting!.sha256)}`,
       `$schtasks = ${psSingleQuote(resolveTrustedWindowsSchtasksExe())}`,
       "$currentXml = & $schtasks /query /tn $taskName /xml 2>$null | Out-String",
       "if ($LASTEXITCODE -ne 0) { throw 'Task Scheduler replacement precondition could not be read.' }",