@bitkyc08/opencodex 2.56.0 → 2.57.0

package/src/server/responses/run-turn-execution.ts

@@ -12,14 +12,15 @@ import {
   adapterNeedsForcedContinuation,
   adapterResponseReachedServingTerminal,
 } from "./core-replay";
-import { sealRequestAttemptIdentity, noteAttemptSend, recordAttemptCredentialSource } from "../request-log";
+import { sealRequestAttemptIdentity, recordAttemptCredentialSource } from "../request-log";
 import { waitForProviderRequestSlot, RequestPacingQueueOverloadError } from "../../providers/request-pacing";
 import type { AdapterEventQueue } from "../../adapters/run-turn-queue";
 import type { AttemptRecoveryKind } from "../../usage/log";
 import { providerFetch } from "./fetch-helpers";
 import { normalizeLogConversationId } from "../request-log-conversation";
 import type { AdapterEvent, OcxProviderContinuationState } from "../../types";
-import { adapterFailureFromMessage } from "../../lib/errors";
+import { adapterFailureFromMessage, SEND_BUDGET_EXHAUSTED_CODE } from "../../lib/errors";
+import { SendBudgetExhaustedError } from "../../lib/upstream-retry";
 import {
   GENERIC_OAUTH_MAX_FAILOVERS_PER_REQUEST,
   isGenericOAuthFailoverEnabled,
@@ -65,6 +66,8 @@ export async function executeResponsesRunTurn(
     | "applyFailoverSnapshot"
     | "resolveSelectionAdapter"
     | "adapter"
+    | "noteRoutedAttemptSend"
+    | "bindKeyUsageFromBridge"
   >,
   sidecarState: Pick<ResponsesSidecarAuth, "routedCompaction">,
   responseEffects: Pick<
@@ -74,7 +77,10 @@ export async function executeResponsesRunTurn(
     | "continuationStateForResponse"
     | "notifyResponseComplete"
   >,
-  sendBudgetState: Pick<ResponsesSendBudget, "adapterSendBudget" | "reserveCredentialHop">,
+  sendBudgetState: Pick<
+    ResponsesSendBudget,
+    "adapterDispatchBudget" | "reserveCredentialHop" | "pendingHopPermit"
+  >,
   completionPolicy: Pick<ResponsesCompletionPolicy, "emptyCompletionGuardEnabled">,
 ): Promise<Response> {
   const { options, logCtx, config } = requestContext;
@@ -94,7 +100,7 @@ export async function executeResponsesRunTurn(
     rememberKiroDeliveredFinalAnswer,
     responseStateOptions,
   } = requestState;
-  const { adapterSendBudget, reserveCredentialHop } = sendBudgetState;
+  const { adapterDispatchBudget, reserveCredentialHop } = sendBudgetState;
   const { emptyCompletionGuardEnabled } = completionPolicy;
   const {
     cancelResponseCompletion,
@@ -140,7 +146,7 @@ export async function executeResponsesRunTurn(
           await waitForProviderRequestSlot(route.providerName, route.provider, route.modelId, runTurnAbort.signal);
         }
         await refreshRunTurnSelection();
-        noteAttemptSend(logCtx.activeAttempt, logCtx.usageLogInputTokens, recovery);
+        transportState.noteRoutedAttemptSend(logCtx.usageLogInputTokens, recovery);
         const runTurnProviderFetch = providerFetch(
           route.provider,
           options.codexWsRuntimeIdentity,
@@ -162,7 +168,7 @@ export async function executeResponsesRunTurn(
             providerFetch: runTurnProviderFetch,
             // The only way the request budget reaches a transport the adapter owns. Without it
             // a Cursor turn's inner ladder was three physical sends the cap read as one.
-            ...(adapterSendBudget ? { sendBudget: adapterSendBudget } : {}),
+            ...(adapterDispatchBudget ? { sendBudget: adapterDispatchBudget } : {}),
           },
           targetQueue.push,
         );
@@ -175,10 +181,22 @@ export async function executeResponsesRunTurn(
               retryable: true,
               message: err.message,
             }
-          : {
-              type: "error",
-              message: err instanceof Error ? err.message : String(err),
-            });
+          : err instanceof SendBudgetExhaustedError
+            // A structured terminal, not a bare message. The turn is already committed to an
+            // SSE response by the time most of these arrive, so the only way to carry "this
+            // proxy refused" to the client is on the event itself -- an unstructured message
+            // is inferred back to 502, which the Codex client retries.
+            ? {
+                type: "error",
+                status: 429,
+                errorType: "rate_limit_error",
+                code: SEND_BUDGET_EXHAUSTED_CODE,
+                message: err.message,
+              }
+            : {
+                type: "error",
+                message: err instanceof Error ? err.message : String(err),
+              });
       } finally {
         // Cursor assigns a stable conversation id inside runTurn on the first headerless
         // turn; backfill so Logs can filter/total that opening request (#330 / #522).
@@ -192,6 +210,11 @@ export async function executeResponsesRunTurn(
     const rotateRunTurnAdapterOnPreflight429 = async (
       error: Extract<AdapterEvent, { type: "error" }>,
     ): Promise<boolean> => {
+      // Our own refusal wears a 429 now, and rotating on it would record a cooldown against an
+      // account that never rate-limited anything -- a fake quota signal that outlives the
+      // request and misroutes later ones. The passthrough path has never had this problem
+      // because it answers before any rotation arm is reached.
+      if (error.code === SEND_BUDGET_EXHAUSTED_CODE) return false;
       const status = error.status ?? adapterFailureFromMessage(error.message).httpStatus;
       if (
         status !== 429
@@ -258,8 +281,11 @@ export async function executeResponsesRunTurn(
         });
         sealRequestAttemptIdentity(logCtx.activeAttempt, logCtx.provider, rotatedAdapter.name, logCtx.accountLogLabel);
         recordAttemptCredentialSource(logCtx.activeAttempt, route.providerName, route.provider, rotatedAdapter.name);
-        // The caller replays the turn on this rotation, so the reservation is now confirmed.
-        hop.permit?.use();
+        // The caller replays the turn on this rotation, and a runTurn adapter dispatches through
+        // its own reservation ladder -- Cursor reserves once per physical send. Confirming here
+        // would leave that ladder to charge the same replay a second time (#4709), so hand the
+        // reservation down and let the send that actually happens spend it.
+        sendBudgetState.pendingHopPermit = hop.permit;
         return true;
       } catch {
         hop.permit?.release();
@@ -270,16 +296,24 @@ export async function executeResponsesRunTurn(
       firstSource: AsyncIterable<AdapterEvent>,
     ): Promise<AsyncIterable<AdapterEvent>> => {
       let source = firstSource;
-      while (true) {
-        const preflight = await preflightAdapterEvents(source);
-        if (!preflight.error || !(await rotateRunTurnAdapterOnPreflight429(preflight.error))) {
-          return preflight.stream;
+      try {
+        while (true) {
+          const preflight = await preflightAdapterEvents(source);
+          if (!preflight.error || !(await rotateRunTurnAdapterOnPreflight429(preflight.error))) {
+            return preflight.stream;
+          }
+          const retryQueue = createAdapterEventQueue({
+            onBacklogExceeded: () => runTurnAbort.abort(),
+          });
+          void runTurnAttempt(retryQueue, "oauth-account-429");
+          source = retryQueue.stream();
         }
-        const retryQueue = createAdapterEventQueue({
-          onBacklogExceeded: () => runTurnAbort.abort(),
-        });
-        void runTurnAttempt(retryQueue, "oauth-account-429");
-        source = retryQueue.stream();
+      } finally {
+        // A handed-down hop reservation belongs to the replay this loop dispatched, and the
+        // loop only leaves after that replay's first event has arrived -- so the adapter has
+        // already reserved if it was ever going to. Dropping the reference here keeps an
+        // adapter that reserves nothing from leaving a free send for an unrelated later leg.
+        sendBudgetState.pendingHopPermit = undefined;
       }
     };
     // The empty-completion retry re-runs the turn against a fresh queue: the
@@ -340,6 +374,7 @@ export async function executeResponsesRunTurn(
           stallTimeoutSec: config.stallTimeoutSec,
           hideThinkingSummary: parsed.options.hideThinkingSummary,
           declaredToolNames,
+          enforceDeclaredToolNames: inboundWire !== "chat" && inboundWire !== "anthropic",
           toolParameterSchemas,
           ...(options.onFirstOutput ? { onFirstOutput: options.onFirstOutput } : {}),
           ...(routedCompaction ? { compaction: true } : {}),
@@ -349,11 +384,7 @@ export async function executeResponsesRunTurn(
           onUsage: usage => {
             // Raw adapter usage, pre wire-normalization: the bridged SSE now always carries
             // zero-default detail objects, so provenance must come from here (cache_detail_missing).
-            logCtx.usageFromBridge = true;
-            if (usage) {
-              logCtx.usage = usage;
-              if (logCtx.activeAttempt) logCtx.activeAttempt.usage = usage;
-            }
+            transportState.bindKeyUsageFromBridge(usage);
           },
           onCompletedResponse: (response: Record<string, unknown>, providerState?: OcxProviderContinuationState) => {
             commitReasoningReplayServingRoute();
@@ -414,17 +445,14 @@ export async function executeResponsesRunTurn(
       hideThinkingSummary: parsed.options.hideThinkingSummary,
       toolNsMap,
       declaredToolNames,
+      enforceDeclaredToolNames: inboundWire !== "chat" && inboundWire !== "anthropic",
       toolParameterSchemas,
       freeformToolNames,
       toolSearchToolNames,
       ...(routedCompaction ? { compaction: true } : {}),
       onProviderState: state => { providerState = state; },
       onUsage: usage => {
-        logCtx.usageFromBridge = true;
-        if (usage) {
-          logCtx.usage = usage;
-          if (logCtx.activeAttempt) logCtx.activeAttempt.usage = usage;
-        }
+        transportState.bindKeyUsageFromBridge(usage);
       },
     });
     if (!routedCompaction) {

package/src/server/responses/sidecar-execution.ts

@@ -35,7 +35,7 @@ import { bindRouteReasoningReplayScope, adapterNeedsForcedContinuation } from ".
 import { namespacedToolName } from "../../types";
 import { providerFetch } from "./fetch-helpers";
 import type { AttemptRecoveryKind } from "../../usage/log";
-import { noteAttemptSend, recordAdapterReasoning, recordAdapterTier } from "../request-log";
+import { recordAdapterReasoning, recordAdapterTier } from "../request-log";
 import { normalizeLogConversationId } from "../request-log-conversation";
 import { rememberResponseState } from "../../responses/state";
 import { trackStreamLifetime } from "../lifecycle";
@@ -65,6 +65,8 @@ export async function executeResponsesSidecars(
     | "commitResolvedOAuthSelection"
     | "resolveSelectionAdapter"
     | "oauthDispatch"
+    | "noteRoutedAttemptSend"
+    | "bindKeyUsageFromBridge"
   >,
   sidecarState: Pick<ResponsesSidecarAuth, "routedCompaction" | "openAiSidecar">,
   responseEffects: Pick<
@@ -322,7 +324,7 @@ export async function executeResponsesSidecars(
       ...(vidPlan ? { videoPlan: vidPlan } : {}),
       forwardHeaders: requestState.selectedForwardHeaders,
       onAttemptSend: (recovery?: AttemptRecoveryKind) =>
-        noteAttemptSend(logCtx.activeAttempt, logCtx.usageLogInputTokens, recovery),
+        transportState.noteRoutedAttemptSend(logCtx.usageLogInputTokens, recovery),
       abortSignal: options.abortSignal,
       maxRounds: imgPlan && vidPlan
         ? clampImageMaxRounds(Math.min(config.images?.maxRounds ?? 3, config.images?.videoMaxRounds ?? 2))
@@ -352,11 +354,7 @@ export async function executeResponsesSidecars(
         if (!logCtx.conversationId && parsed._cursorConversationId) {
           logCtx.conversationId = normalizeLogConversationId(parsed._cursorConversationId);
         }
-        logCtx.usageFromBridge = true;
-        if (usage) {
-          logCtx.usage = usage;
-          if (logCtx.activeAttempt) logCtx.activeAttempt.usage = usage;
-        }
+        transportState.bindKeyUsageFromBridge(usage);
       },
       on429: rotateSidecarProviderOn429,
       retryOn429Policy: rateLimitRetryPolicyFor(route.provider),
@@ -432,13 +430,9 @@ export async function executeResponsesSidecars(
         recordAdapterTier(logCtx, request);
       },
       onAttemptSend: (recovery?: AttemptRecoveryKind) =>
-        noteAttemptSend(logCtx.activeAttempt, logCtx.usageLogInputTokens, recovery),
+        transportState.noteRoutedAttemptSend(logCtx.usageLogInputTokens, recovery),
       onUsage: usage => {
-        logCtx.usageFromBridge = true;
-        if (usage) {
-          logCtx.usage = usage;
-          if (logCtx.activeAttempt) logCtx.activeAttempt.usage = usage;
-        }
+        transportState.bindKeyUsageFromBridge(usage);
       },
       recordSidecarOutcome: wsPlan.forwardSidecar?.recordOutcome,
       connectTimeoutMs: config.connectTimeoutMs ?? 200_000,

package/src/server/responses/terminal-guard.ts

@@ -13,6 +13,9 @@ const PLAN_OR_COMPLETION_RE = /(?:\b(?:i(?:'|’)m going to|i will|i(?:'|’)ll|
 const WAITING_FOR_USER_RE = /(?:[?？]\s*$|需要我|请(?:确认|选择|提供)|是否|要不要|可以吗|\b(?:do you want|should i|which file|please confirm|please provide)\b)/iu;
 const EXPLICIT_CONTINUE_RE = /^(?:继续|接着|往下|go on|continue|proceed|keep going)\s*[.!。！]?$/iu;
 const MAX_ANNOUNCEMENT_CHARS = 280;
+const MAX_RETAINED_EVENTS = 1_024;
+// JavaScript string code units, not UTF-8 bytes or a process-wide memory limit.
+const MAX_RETAINED_CONTENT_CHARS = 64 * 1_024;
 
 export const TERMINAL_GUARD_NUDGE =
   "你刚才只描述了计划，没有执行任何工具。不要再次解释计划，现在立即调用必要工具执行用户任务。" +
@@ -195,7 +198,17 @@ function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined):
   };
 }
 
-/** Preserve normal terminals, but withhold one suspicious no-tool terminal for a bounded re-ask. */
+/**
+ * Forward adapter events and re-ask only short, suspicious no-tool completions.
+ * Retention is bounded per turn; tools or overflow disable analysis without truncating output.
+ * Reported usage from completed legs survives a continuation-factory failure. Unreported
+ * usage stays absent, and source-iteration failures propagate to the caller's transport handler.
+ *
+ * @param options Initial stream, parsed history, and continuation callback. The caller owns
+ * provider opt-in; the continuation limit defaults to one and is clamped to at most two.
+ * @yields Unchanged content events, internal assistant boundaries, and terminal events with
+ * accumulated reported usage when available. Returning the iterator closes its active source.
+ */
 export async function* guardTerminalEventStream(options: GuardedEventStreamOptions): AsyncGenerator<AdapterEvent> {
   const maxContinuations = Math.max(0, Math.min(2, Math.floor(options.maxAutoContinuations ?? 1)));
   let parsed = options.parsed;
@@ -205,6 +218,10 @@ export async function* guardTerminalEventStream(options: GuardedEventStreamOptio
 
   while (true) {
     const seen: AdapterEvent[] = [];
+    let retainedContentChars = 0;
+    let retainedText = "";
+    let analysisEnabled = (options.adapterName === "anthropic" || options.adapterName === "openai-chat")
+      && continuations < maxContinuations;
     let terminalSeen = false;
     for await (const event of source) {
       // Liveness markers and tool argument fragments are passed through to the bridge, but
@@ -216,7 +233,7 @@ export async function* guardTerminalEventStream(options: GuardedEventStreamOptio
       }
       if (event.type === "done") {
         terminalSeen = true;
-        const analysis = (options.adapterName === "anthropic" || options.adapterName === "openai-chat")
+        const analysis = analysisEnabled
           ? analyzeTerminalTurn(parsed, seen)
           : { decision: "pass" as const };
         const normalStop = event.stopReason !== "max_tokens" && event.stopReason !== "content_filter";
@@ -224,11 +241,17 @@ export async function* guardTerminalEventStream(options: GuardedEventStreamOptio
           accumulatedUsage = mergeUsage(accumulatedUsage, event.usage);
           continuations += 1;
           parsed = buildContinuationRequest(parsed, seen);
+          seen.length = 0;
+          retainedText = "";
           yield { type: "assistant_boundary" };
           try {
             source = await options.continuation(parsed);
           } catch (error) {
-            yield { type: "error", message: error instanceof Error ? error.message : String(error) };
+            yield {
+              type: "error",
+              message: error instanceof Error ? error.message : String(error),
+              ...(accumulatedUsage ? { usage: accumulatedUsage } : {}),
+            };
             return;
           }
           break;
@@ -243,7 +266,45 @@ export async function* guardTerminalEventStream(options: GuardedEventStreamOptio
         yield usage ? { ...event, usage } : event;
         return;
       }
-      seen.push(event);
+      if (analysisEnabled) {
+        if (event.type === "tool_call_start") {
+          // A real tool call permanently rules out a no-tool continuation for this turn.
+          analysisEnabled = false;
+        } else if (
+          event.type === "text_delta"
+          || event.type === "thinking_delta"
+          || event.type === "thinking_signature"
+          || event.type === "redacted_thinking"
+        ) {
+          const content = event.type === "text_delta"
+            ? event.text
+            : event.type === "thinking_delta"
+              ? event.thinking
+              : event.type === "thinking_signature"
+                ? event.signature
+                : event.data;
+          if (
+            seen.length >= MAX_RETAINED_EVENTS
+            || content.length > MAX_RETAINED_CONTENT_CHARS - retainedContentChars
+          ) {
+            analysisEnabled = false;
+          } else {
+            retainedContentChars += content.length;
+            if (event.type === "text_delta") retainedText += content;
+            // Match analyzeTerminalTurn's trimmed-text semantics, including split padding.
+            if (retainedText.trim().length > MAX_ANNOUNCEMENT_CHARS) {
+              analysisEnabled = false;
+            } else {
+              seen.push(event);
+            }
+          }
+        }
+        if (!analysisEnabled) {
+          // Never rebuild a continuation from truncated thinking or a partial turn.
+          seen.length = 0;
+          retainedText = "";
+        }
+      }
       yield event;
     }
     if (!terminalSeen) return;

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

@@ -1,7 +1,7 @@
 import { collectAmbiguousDottedAliases, dottedAliasIsUnambiguous, wireToolInnerName } from "../responses/tool-name-aliases";
 import {
-  CODE_MODE_EXEC_TOOL_NAME,
   dottedToolName,
+  NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES,
   namespacedToolName,
   normalizeDeclaredToolName,
 } from "../types";
@@ -104,10 +104,14 @@ function addWireToolName(
   if (dottedAliasIsUnambiguous(namespace, name) && !ambiguousDottedAliases?.has(dotted)) {
     names.add(dotted);
   }
-  // `exec` is the one name that also switches on nested-helper normalization, so a bare alias
-  // for a namespaced MCP tool would silently authorize `exec_command`/`shell_command`/
-  // `apply_patch`/`view_image` the request never declared. Every other inner name keeps the bare alias.
-  if (name !== CODE_MODE_EXEC_TOOL_NAME) names.add(name);
+  // The code-mode helper spellings do not get a bare alias for a namespaced tool. Bare `exec`
+  // switches nested-helper normalization on for a catalog that never declared the shell; bare
+  // `exec_command`/`shell_command` switch it off for one that did; bare `write_stdin`/
+  // `apply_patch`/`view_image` are simply accepted as declared under a name the caller only ever
+  // authorized inside a namespace. This guard named only `exec` and let the other five through,
+  // which is the same drift the bridge-side copy had; both now read one list
+  // (src/types/tools.ts). Every other inner name keeps the bare alias.
+  if (!NAMESPACED_BARE_ALIAS_EXCLUDED_NAMES.has(name)) names.add(name);
 }
 
 /**

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)) {