@bitkyc08/opencodex 2.56.0 → 2.58.0

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/ws-upstream.ts

@@ -1,3 +1,6 @@
+import { OPENAI_API_RESPONSES_URL } from "./native-response-control";
+import { isInjectionRequest } from "./native-injection-protocol";
+import type { NativeResponseControl } from "./native-response-control";
 // Upstream WebSocket transport for the ChatGPT Codex backend.
 //
 // Why this exists: the Codex backend serves the responses_websockets path from
@@ -129,6 +132,8 @@ export function codexWsUpstreamFetch(
   runtime: BunRuntimeGateInput = currentBunRuntimeIdentity(),
   onQuota?: CodexWsQuotaObserver,
   beforeDispatch?: (headers: Headers) => void,
+  nativeControl?: NativeResponseControl,
+  beforeContinuation?: () => Promise<void>,
 ): Promise<Response> {
   const prepared = prepareCodexWsRequest(url, init);
   if (!prepared) return sseFallback(url, prepareCodexHttpInit(url, init));
@@ -142,6 +147,17 @@ export function codexWsUpstreamFetch(
   }
 
   const { frameText, headers } = prepared;
+  // Never infer backend support from a model name or enable controls on a gateway.
+  const control = nativeControl?.kind === "injection"
+    ? ((prepared.canonical || url === OPENAI_API_RESPONSES_URL) && isInjectionRequest(JSON.parse(frameText)) ? nativeControl : undefined)
+    : (prepared.canonical || url === OPENAI_API_RESPONSES_URL) ? nativeControl : undefined;
+  if (control?.kind === "injection" && url === OPENAI_API_RESPONSES_URL) {
+    const beta = headers["openai-beta"];
+    if (!beta?.split(",").some(value => value.trim() === "responses_multi_agent=v1")) {
+      headers["openai-beta"] = beta ? `${beta}, responses_multi_agent=v1` : "responses_multi_agent=v1";
+    }
+  }
+
 
   // Decide before dialing. Once the socket is open the caller already holds a
   // streaming Response, so the oversized close can only be surfaced as a stream
@@ -169,7 +185,9 @@ export function codexWsUpstreamFetch(
   }
   let session: CodexWsSession;
   try {
-    const identity = codexWsReuseIdentity(url, headers, frameText, proxy);
+    // Steering keeps a private physical connection across successor responses; it
+    // must never enter the idle-socket pool or move to a different credential.
+    const identity = control ? null : codexWsReuseIdentity(url, headers, frameText, proxy);
     session = (identity ? codexWsPool.acquire(identity, wsUrl, headers, proxy) : null)
       ?? new CodexWsSession(wsUrl, headers, false, undefined, proxy);
     if (!session.busy && !session.reserve()) {
@@ -181,6 +199,8 @@ export function codexWsUpstreamFetch(
   }
   return codexWsExchange({
     session, url, init, prepared, sseFallback, onQuota, beforeDispatch,
+    nativeControl: control,
+    beforeContinuation,
     bunVersion: typeof runtime === "string" ? runtime : runtime.version,
   });
 }

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/server/stop-teardown.ts

@@ -67,7 +67,14 @@ export async function performStopTeardown(url: URL, io: StopTeardownIo = {}): Pr
   // undone (#3008).
   const grokNote = grok.ok ? "" : ` Grok config cleanup failed: ${grok.message}`;
   if (restore.success && grok.ok) {
-    return { success: true, message: "Proxy stopping, native Codex restored.", sharedTeardown: "performed" };
+    // A degraded restore is a success — routing is out and the client is no longer aimed at
+    // a port that is about to disappear — but it left a provider table behind on purpose.
+    // Reporting a bare "restored" would put the caller in exactly the position #4812
+    // describes: a config they did not expect and no idea why it is there.
+    const retained = restore.retainedCodexProviderTable
+      ? ` ${(await import("../codex/inject/restore")).describeRetainedCodexProviderTable(restore.retainedCodexProviderTable)}`
+      : "";
+    return { success: true, message: `Proxy stopping, native Codex restored.${retained}`, sharedTeardown: "performed" };
   }
   if (restore.success) {
     return {

package/src/server/ws-bridge.ts

@@ -1,3 +1,4 @@
+import type { NativeResponseControl } from "./responses/native-response-control";
 import type { ServerWebSocket } from "bun";
 import { responsesJsonEventSequence } from "./responses-json-events";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
@@ -17,6 +18,9 @@ type ResponsesTerminalReporter = (status: ResponsesTerminalStatus) => void;
 type ResponsesPayloadObserver = (payload: string) => void;
 
 export interface WsData {
+  nativeControl?: NativeResponseControl;
+  /** Content-free per-turn explanation; never a model capability assertion. */
+  nativeSteeringUnavailable?: string;
   headers?: Headers; // base inbound forward headers only; per-turn auth refresh injects current pool tokens
   /**
    * Resolved once at the handshake. Auth is handshake-time only on this path, so
@@ -229,6 +233,7 @@ export async function pumpResponsesSseToWebSocket(
   sseStream: ReadableStream<Uint8Array>,
   options: {
     isCurrent?: () => boolean;
+    untilEof?: boolean;
     onTerminal?: ResponsesTerminalReporter;
     onSsePayload?: ResponsesPayloadObserver;
   } = {},
@@ -251,6 +256,7 @@ export async function pumpResponsesSseToWebSocket(
   const decoder = new TextDecoder();
   const framer = new BoundedSseFrameBuffer();
   let terminalSeen = false;
+  let lastTerminal: ResponsesTerminalStatus | undefined;
 
   const handlePayload = (payload: string): boolean => {
     if (!isCurrent()) return true;
@@ -270,8 +276,10 @@ export async function pumpResponsesSseToWebSocket(
     }
     if (terminalSeen) return true;
     sendTextFrame(ws, payload);
-    const terminalStatus = terminalStatusFromType(type);
+    if (options.untilEof && type === "response.created") lastTerminal = undefined;
+    const terminalStatus = type === "error" && options.untilEof ? "failed" : terminalStatusFromType(type);
     if (terminalStatus) {
+      if (options.untilEof) { lastTerminal = terminalStatus; return false; }
       reportTerminal(terminalStatus);
       terminalSeen = true;
       void reader.cancel().catch(() => {});
@@ -294,6 +302,10 @@ export async function pumpResponsesSseToWebSocket(
       const payload = parseSseBlock(decoder.decode(tail));
       if (payload) handlePayload(payload);
     }
+    if (options.untilEof && lastTerminal && isCurrent() && !clientCancelled) {
+      reportTerminal(lastTerminal);
+      terminalSeen = true;
+    }
     if (!terminalSeen && isCurrent() && !clientCancelled) {
       reportTerminal("incomplete");
       sendProtocolError(ws, 502, "Upstream stream ended before response terminal event");
@@ -368,6 +380,7 @@ export async function sendResponseToWebSocket(
   response: Response,
   isCurrent: () => boolean,
   options: {
+    untilEof?: boolean;
     onTerminal?: ResponsesTerminalReporter;
     onSsePayload?: ResponsesPayloadObserver;
   } = {},
@@ -398,6 +411,7 @@ export async function sendResponseToWebSocket(
   if (contentType.includes("text/event-stream")) {
     await pumpResponsesSseToWebSocket(ws, response.body, {
       isCurrent,
+      untilEof: options.untilEof,
       onTerminal: options.onTerminal,
       onSsePayload: options.onSsePayload,
     });
@@ -420,6 +434,7 @@ export async function sendResponseToWebSocket(
   if (looksLikeSse(prefix)) {
     await pumpResponsesSseToWebSocket(ws, stream, {
       isCurrent,
+      untilEof: options.untilEof,
       onTerminal: options.onTerminal,
       onSsePayload: options.onSsePayload,
     });

package/src/service/cli.ts

@@ -1,6 +1,7 @@
 import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { restoreNativeCodexAsync } from "../codex/inject";
+import { describeRetainedCodexProviderTable } from "../codex/inject/restore";
 import { stripGrokConfig } from "../grok/inject";
 import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { statusWinswRaw, type WinswStatus } from "../lib/winsw";
@@ -291,7 +292,15 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
           break;
         }
         const restore = await restoreNativeCodexAsync();
-        if (restore.success) console.log("✅ service stopped + native Codex restored.");
+        if (restore.success) {
+          console.log("✅ service stopped + native Codex restored.");
+          // Success is not the whole answer when routing came down but the provider table
+          // stayed. Saying only "restored" here is how a user finds an unexplained
+          // opencodex table in their config weeks later (#4812).
+          if (restore.retainedCodexProviderTable) {
+            console.log(`   ${describeRetainedCodexProviderTable(restore.retainedCodexProviderTable)}`);
+          }
+        }
         else console.error(`⚠️ service stopped, but native Codex restore FAILED: ${restore.message}\nRun \`ocx restore\` (or check $CODEX_HOME/config.toml) before using native Codex.`);
         if (!restore.success) process.exitCode = 1;
         // The Grok fence is the other managed config this command owns. Leaving it behind
@@ -339,6 +348,9 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
           console.error(`⚠️ native Codex restore FAILED: ${restore.message}\nRun \`ocx restore\` before using native Codex.`);
           process.exitCode = 1;
         }
+        else if (restore.retainedCodexProviderTable) {
+          console.log(`↩️  ${describeRetainedCodexProviderTable(restore.retainedCodexProviderTable)}`);
+        }
         const grok = stripGrokConfig();
         if (grok.changed) console.log(`↩️  ${grok.message}`);
         else if (!grok.ok) {

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";