@bitkyc08/opencodex 2.67.0-preview.20260926 → 2.68.0-preview.20260927

package/src/server/management/sibling-guard.ts

@@ -0,0 +1,60 @@
+import { siblingOfLivePort } from "../../codex/sibling-start";
+import { CODEX_RESTART_PATH } from "../../lib/codex-restart-contract";
+
+/**
+ * Management mutations a sibling instance refuses (`src/codex/sibling-start.ts`).
+ *
+ * The owner-level gates stop the writers a sibling reaches on its own: startup sync, catalog
+ * convergence, owned-catalog refresh, the Claude roster, system env and the stop teardown. These
+ * routes reach shared client state through paths those gates do not cover, so the sibling's own
+ * management API refuses them outright: toggling or stripping the live owner's Codex, Grok or Claude
+ * integrations, rewriting client files at this port, the Codex prompt layers and `[features]`
+ * written into the shared `config.toml`, killing the user's Codex app-servers, joining a link (which
+ * writes the shared catalog and restarts as a client), staging or switching the physical native-main
+ * login, baking the machine service, PATH shim or tray from this home, replacing the global package
+ * (the live proxy drains on its package-tree refresh), Codex's own log database, and the
+ * archived-session cleanup, cleanup-policy run and trash restore that rewrite the shared CODEX_HOME.
+ *
+ * Everything else stays open: every read, `POST /api/stop`, `POST /api/system/restart`, and the
+ * own-home mutations (providers, keys, settings). `PUT /api/settings` is allowed because it carries
+ * own-home settings; its shared fan-out is gated in `syncEnabledClientIntegrations`. So is
+ * `PUT /api/storage/cleanup-policy`; the scheduled runs it enables stand down in
+ * `maybeRequestStorageCleanupPolicyRun` (`src/storage/policy-job.ts`).
+ *
+ * Paths are compared through this table and a variable, never as a quoted pathname equality:
+ * `tests/helpers/management-route-scan.ts` reads that form as a route declaration, and this file
+ * declares no route of its own.
+ */
+export const SIBLING_REFUSED_MANAGEMENT_PATHS: readonly { readonly path: string; readonly children: boolean }[] = [
+  { path: "/api/sync", children: false },
+  { path: "/api/client-integrations", children: true },
+  { path: "/api/native-integrations", children: true },
+  { path: "/api/claude-desktop", children: true },
+  { path: "/api/claude-code", children: false },
+  { path: "/api/grok/apply", children: false },
+  { path: "/api/grok/selection", children: false },
+  { path: "/api/codex-prompt", children: true },
+  { path: CODEX_RESTART_PATH, children: false },
+  { path: "/api/link/join", children: false },
+  { path: "/api/native-main-profiles", children: true },
+  { path: "/api/codex-auth/main", children: true },
+  { path: "/api/startup-action", children: false },
+  { path: "/api/windows-tray", children: false },
+  { path: "/api/update/run", children: false },
+  { path: "/api/v2", children: false },
+  { path: "/api/codex-auth/features", children: true },
+  { path: "/api/storage/codex-logs", children: true },
+  // Archived-session cleanup, its policy run and trash restore rewrite the shared CODEX_HOME.
+  { path: "/api/storage/cleanup", children: false },
+  { path: "/api/storage/cleanup-policy/run", children: false },
+  { path: "/api/storage/trash/restore", children: false },
+];
+
+const READ_METHODS: ReadonlySet<string> = new Set(["GET", "HEAD"]);
+
+/** True when this process is a sibling and the request would mutate shared client state. */
+export function siblingRefusesManagementRequest(method: string, pathname: string): boolean {
+  if (siblingOfLivePort() === null || READ_METHODS.has(method.toUpperCase())) return false;
+  return SIBLING_REFUSED_MANAGEMENT_PATHS.some(entry =>
+    pathname === entry.path || (entry.children && pathname.startsWith(`${entry.path}/`)));
+}

package/src/server/management/storage-log-guard-routes.ts

@@ -11,7 +11,8 @@ import {
   type CodexLogGuardMutationResult,
   type CodexLogGuardStatus,
 } from "../../codex/log-guard/protection";
-import { scanStorage } from "../../storage/scanner";
+import { scanStorageAsync, type StorageReport } from "../../storage/scanner";
+import { noteStorageMutationCompleted, storageMutationEpoch } from "../../storage/storage-mutation-coordinator";
 import { jsonResponse } from "../auth-cors";
 import {
   managementBodyTooLargeResponse,
@@ -104,6 +105,67 @@ async function readProtectMode(ctx: ManagementContext): Promise<"compat" | "quie
   return mode;
 }
 
+/**
+ * Concurrent GET /api/storage requests for the same CODEX_HOME share one walk; nothing is
+ * cached past it. A walk is joined only while no storage mutation has completed since it
+ * started, so a read issued after a cleanup, restore, policy run or Log Guard change always
+ * rescans instead of receiving sizes observed before it.
+ */
+interface StorageScanFlight {
+  epoch: number;
+  promise: Promise<StorageReport>;
+}
+const storageScanFlights = new Map<string, StorageScanFlight>();
+
+export function sharedStorageScan(
+  codexHome: string,
+  scan: (codexHome: string) => Promise<StorageReport> = scanStorageAsync,
+): Promise<StorageReport> {
+  const epoch = storageMutationEpoch();
+  const pending = storageScanFlights.get(codexHome);
+  if (pending && pending.epoch === epoch) return pending.promise;
+  const flight: StorageScanFlight = {
+    epoch,
+    promise: scan(codexHome).finally(() => {
+      // A newer flight may already own this key; only retire our own entry.
+      if (storageScanFlights.get(codexHome) === flight) storageScanFlights.delete(codexHome);
+    }),
+  };
+  storageScanFlights.set(codexHome, flight);
+  return flight.promise;
+}
+
+/**
+ * Log Guard results that are refused before anything under CODEX_HOME is touched. Anything
+ * else (success, a database or config write failure, `busy` which compaction can report
+ * after partial progress, a post-compaction integrity failure) may have changed storage.
+ */
+const REFUSED_BEFORE_CHANGE: ReadonlySet<string> = new Set([
+  "unsupported_schema",
+  "codex_running",
+  "process_enumeration_failed",
+  "unsafe_path",
+  "trigger_collision",
+  "auto_vacuum_not_incremental",
+]);
+
+export function logGuardResultMayHaveChangedStorage(
+  result: CodexLogGuardMutationResult | CodexLogGuardCompactionResult,
+): boolean {
+  if (result.ok) return true;
+  if (result.error === "integrity_check_failed") return result.phase === "after";
+  return !REFUSED_BEFORE_CHANGE.has(result.error);
+}
+
+/** Invalidate in-flight storage scans only when the Log Guard operation may have changed storage. */
+function afterLogGuardMutation(
+  result: CodexLogGuardMutationResult | CodexLogGuardCompactionResult,
+  response: Response,
+): Response {
+  if (logGuardResultMayHaveChangedStorage(result)) noteStorageMutationCompleted();
+  return response;
+}
+
 /** Codex Log Guard diagnostics plus explicit protection and maintenance mutations. */
 export async function handleStorageLogGuardRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps } = ctx;
@@ -129,22 +191,26 @@ export async function handleStorageLogGuardRoutes(ctx: ManagementContext): Promi
     if (req.method !== "POST") return null;
     const mode = await readProtectMode(ctx);
     if (mode instanceof Response) return mode;
-    return mutationResponse(protectCodexLogs(mode, protectionDeps), ctx);
+    const result = protectCodexLogs(mode, protectionDeps);
+    return afterLogGuardMutation(result, mutationResponse(result, ctx));
   }
 
   if (url.pathname === "/api/storage/codex-logs/unprotect") {
     if (req.method !== "POST") return null;
-    return mutationResponse(unprotectCodexLogs(protectionDeps), ctx);
+    const result = unprotectCodexLogs(protectionDeps);
+    return afterLogGuardMutation(result, mutationResponse(result, ctx));
   }
 
   if (url.pathname === "/api/storage/codex-logs/repair") {
     if (req.method !== "POST") return null;
-    return mutationResponse(repairCodexLogGuardProtection(protectionDeps), ctx);
+    const result = repairCodexLogGuardProtection(protectionDeps);
+    return afterLogGuardMutation(result, mutationResponse(result, ctx));
   }
 
   if (url.pathname === "/api/storage/codex-logs/compact") {
     if (req.method !== "POST") return null;
-    return compactResponse(compactCodexLogs(deps.codexLogGuardMaintenanceDeps), ctx);
+    const result = compactCodexLogs(deps.codexLogGuardMaintenanceDeps);
+    return afterLogGuardMutation(result, compactResponse(result, ctx));
   }
 
   if (url.pathname !== "/api/storage" || req.method !== "GET") return null;
@@ -154,7 +220,7 @@ export async function handleStorageLogGuardRoutes(ctx: ManagementContext): Promi
   // silently folded into CODEX_HOME totals.
   let storage;
   try {
-    storage = scanStorage();
+    storage = await sharedStorageScan(resolveCodexHomeDir());
   } catch {
     const fallback = {
       codexHome: resolveCodexHomeDir(),

package/src/server/management/system-restart.ts

@@ -14,14 +14,28 @@
  *   Installed-but-stale/missing service assets are NOT treated as supervised —
  *   exit(1) would leave the proxy dead with `Service: installed, stale or missing
  *   service assets` and a /healthz timeout.
- * - If detached spawn fails (sync throw or pre-start `error`): exit(1) without
- *   markRecycling — after drain the listen socket is already closed, so a latch
- *   reset cannot recover serving. Clear inherited `OCX_SERVICE` so exit cleanup
- *   can restore Codex/Grok fences when a stale service marker has no viable
- *   supervisor. Log only a stable errno code — never the raw message
+ * - The replacement is spawned by `src/server/restart-replacement.ts`: it carries
+ *   `OCX_RESTART_PARENT_PID` and its output goes to the bounded `restart-handoff.log`.
+ *   Only after a completed drain (the handoff waits for health) is a replacement that
+ *   exits before it answers retried, twice, inside the readiness budget. A deadline,
+ *   failed-drain or listener-stop-fallback handoff resolves on spawn and exits: the
+ *   replacement's own parent wait and port reclaim cover it, and any other early exit
+ *   there is not retried.
+ * - If detached spawn fails (sync throw, pre-start `error`, or every attempt exited
+ *   early): exit(1) without markRecycling — after drain the listen socket is already
+ *   closed, so a latch reset cannot recover serving. Clear inherited `OCX_SERVICE`
+ *   so exit cleanup can restore Codex/Grok fences when a stale service marker has no
+ *   viable supervisor. Log only a stable errno code — never the raw message
  *   (paths in ENOENT often include the OS username).
+ * - Except after a committed client connection (a join into a Child): Codex already
+ *   routes to the client runtime the next start serves on this port, so the failed
+ *   handoff still marks recycling and exit cleanup keeps that routing instead of
+ *   silently falling back to native Codex.
+ * - Desktop-supervised child (the desktop app spawned it with `OCX_DESKTOP_SUPERVISED=1`
+ *   and is still its parent): no spawn. Mark recycle and exit 75; the app sees the exit
+ *   and starts the replacement itself, so it keeps owning, stopping and quitting it.
+ *   Checked before the service rule: that app, not a service manager, is the parent.
  */
-import { spawn } from "node:child_process";
 import {
   acquireTemporaryDrain,
   beginShutdownDrain,
@@ -34,25 +48,22 @@ import {
   stopServerListener,
 } from "../lifecycle";
 import { isServiceViable } from "../../service";
+import { readClientConnectionState } from "../../client/state";
+import { withSiblingMarker } from "../../codex/sibling-start";
+import { issueSiblingHandoff } from "../../codex/sibling-handoff";
 import { readRuntimePort } from "../../config/process-state";
-import { withProcessRuntimeProvenance } from "../../lib/bun-runtime";
-import { selfLaunchArgv } from "../../lib/self-launch-argv";
 import { spendLedgerRestartEnvironment } from "../../lib/spend-ledger-owner";
 import {
+  DESKTOP_RESTART_EXIT_CODE,
+  DESKTOP_SUPERVISED_ENV,
   MEMORY_DRAIN_RESTART_MS,
-  REPLACEMENT_READY_TIMEOUT_MS,
+  isDesktopSupervised,
 } from "../../lib/system-restart-contract";
-import { findLiveProxy } from "../proxy-liveness";
+import { spawnReplacementStart } from "../restart-replacement";
 
 export { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../../lib/system-restart-contract";
+export { waitForReplacementReady, type ReplacementReadinessIo } from "../restart-replacement";
 export const DEADLINE_LISTENER_STOP_TIMEOUT_MS = 5_000;
-const REPLACEMENT_READY_POLL_MS = 150;
-
-export interface ReplacementReadinessIo {
-  findLive?: typeof findLiveProxy;
-  now?: () => number;
-  sleep?: (ms: number) => Promise<void>;
-}
 
 export interface SystemRestartIo {
   acquireTemporaryDrain?: () => { release(): void } | null;
@@ -60,11 +71,15 @@ export interface SystemRestartIo {
   /** True when a background service can actually respawn this process after exit(1). */
   isServiceViable?: () => boolean;
   isSupervisedServiceChild?: () => boolean;
+  /** True when the desktop app that spawned this process starts its replacement after exit 75. */
+  isDesktopSupervised?: () => boolean;
   /** Ordinary start; deadline handoff may defer health until parent exit releases OS locks. */
   spawnStart?: (port?: number, waitForHealthBeforeParentExit?: boolean) => void | Promise<void>;
   /** Idempotent listener close; must settle before an ordinary start is spawned. */
   stopListener?: () => void | Promise<void>;
   markRecycling?: () => void;
+  /** True once a client connection has committed (a join into a Child); read only after a failed handoff. */
+  isClientConnected?: () => boolean;
   exitProcess?: (code: number) => void;
   schedule?: (fn: () => void | Promise<void>, ms: number) => void;
   scheduleDeadline?: (fn: () => void, ms: number) => () => void;
@@ -161,7 +176,8 @@ export function setSystemRestartIoForTests(io: SystemRestartIo = {}): void {
   explicitShutdownRequested = false;
 }
 
-function resolveListenPort(): number | undefined {
+/** The port this process is listening on, or undefined when that cannot be established. */
+export function resolveListenPort(): number | undefined {
   const live = getServerListenPort();
   if (live) return live;
   const runtime = readRuntimePort(process.pid);
@@ -185,131 +201,67 @@ function spawnFailureCode(err: unknown): string {
   return "spawn_failed";
 }
 
-function handoffError(code: string): NodeJS.ErrnoException {
-  const error = new Error(code) as NodeJS.ErrnoException;
-  error.code = code;
-  return error;
+/**
+ * After a failed handoff, keep Codex routing when a client connection has committed.
+ *
+ * `connectClient` already pointed Codex at the client runtime that the next start (a service
+ * relaunch, the desktop app, or `ocx start`) serves on this same port. Restoring native Codex here
+ * would be a silent local fallback while client state says connected. An unreadable state is not
+ * proof of a join, so it keeps today's restore.
+ */
+function keepRoutingForCommittedClient(io: SystemRestartIo): void {
+  let connected = false;
+  try {
+    connected = (io.isClientConnected ?? (() => readClientConnectionState().kind === "connected"))();
+  } catch {
+    connected = false;
+  }
+  if (connected) (io.markRecycling ?? markRecyclingForExit)();
 }
 
-export async function waitForReplacementReady(
-  expectedPid: number | undefined,
-  parentPid: number,
-  expectedPort: number | undefined,
-  io: ReplacementReadinessIo = {},
-): Promise<boolean> {
-  const findLive = io.findLive ?? findLiveProxy;
-  const now = io.now ?? Date.now;
-  const sleep = io.sleep ?? Bun.sleep;
-  const deadline = now() + REPLACEMENT_READY_TIMEOUT_MS;
-  while (now() < deadline) {
-    try {
-      const live = await findLive({
-        deadlineAt: deadline,
-        nowFn: now,
-        sleepFn: sleep,
-      });
-      // A probe that began within budget can still return after it. Never accept
-      // delayed health as proof once the shared absolute handoff budget expired.
-      if (now() >= deadline) return false;
-      if (
-        live
-        && live.pid !== null
-        && live.pid !== parentPid
-        && (expectedPid === undefined || live.pid === expectedPid)
-        && (expectedPort === undefined || live.port === expectedPort)
-      ) {
-        return true;
-      }
-    } catch {
-      // A not-yet-bound replacement is indistinguishable from a transient
-      // liveness failure here; keep polling inside the one bounded window.
-    }
-    const remainingMs = deadline - now();
-    if (remainingMs <= 0) break;
-    await sleep(Math.min(REPLACEMENT_READY_POLL_MS, remainingMs));
-  }
-  return false;
+/**
+ * Hand the restart to the desktop app that spawned this process: keep Codex routing for the
+ * replacement it starts on this port, and exit with the code it restarts on. False when nothing
+ * supervises this process that way, and then nothing happened.
+ */
+function handOffToDesktop(io: SystemRestartIo, exitProcess: (code: number) => void): boolean {
+  if (!(io.isDesktopSupervised ?? isDesktopSupervised)()) return false;
+  (io.markRecycling ?? markRecyclingForExit)();
+  exitProcess(DESKTOP_RESTART_EXIT_CODE);
+  return true;
+}
+
+/**
+ * The replacement's environment before `spawnReplacementStart` adds the restart-parent marker and
+ * the runtime provenance: never under a service marker, a sibling's replacement stays a sibling,
+ * and only a parent-exit handoff marks the bounded spend-ledger lease wait.
+ */
+export function replacementStartEnvironment(
+  waitForHealthBeforeParentExit: boolean,
+  parentPid: number = process.pid,
+): NodeJS.ProcessEnv {
+  // A sibling's replacement stays a sibling even if the owner is down while it probes.
+  const sourceEnv: NodeJS.ProcessEnv = withSiblingMarker(process.env, issueSiblingHandoff);
+  delete sourceEnv.OCX_SERVICE;
+  // A detached replacement is not the desktop app's child; it must never exit to an app that is not waiting on it.
+  delete sourceEnv[DESKTOP_SUPERVISED_ENV];
+  return spendLedgerRestartEnvironment(
+    sourceEnv,
+    waitForHealthBeforeParentExit ? undefined : parentPid,
+  );
 }
 
 function spawnDetachedStart(
   port?: number,
   waitForHealthBeforeParentExit = true,
 ): Promise<void> {
-  const args = ["start"];
-  const expectedPort = typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535
-    ? Math.trunc(port)
-    : undefined;
-  if (expectedPort !== undefined) {
-    args.push("--port", String(expectedPort));
+  let env: NodeJS.ProcessEnv;
+  try {
+    env = replacementStartEnvironment(waitForHealthBeforeParentExit);
+  } catch (err) {
+    return Promise.reject(err);
   }
-  const launchArgs = selfLaunchArgv(args);
-  return new Promise<void>((resolve, reject) => {
-    let child: ReturnType<typeof spawn>;
-    try {
-      const sourceEnv: NodeJS.ProcessEnv = { ...process.env };
-      delete sourceEnv.OCX_SERVICE;
-      const env = spendLedgerRestartEnvironment(
-        sourceEnv,
-        waitForHealthBeforeParentExit ? undefined : process.pid,
-      );
-      child = spawn(process.execPath, launchArgs, {
-        detached: true,
-        stdio: "ignore",
-        windowsHide: true,
-        env: withProcessRuntimeProvenance(env),
-      });
-    } catch (err) {
-      reject(err);
-      return;
-    }
-    let settled = false;
-    const cleanup = () => {
-      child.off("error", onError);
-      child.off("exit", onExit);
-      child.off("spawn", onSpawn);
-    };
-    const finish = (error?: unknown) => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      if (error !== undefined) {
-        if (child.exitCode === null && child.signalCode === null) {
-          try { child.kill(); } catch { /* best-effort failed-start cleanup */ }
-        }
-        try { child.unref(); } catch { /* best-effort */ }
-        reject(error);
-        return;
-      }
-      child.unref();
-      resolve();
-    };
-    const onError = (err: Error) => { finish(err); };
-    const onExit = () => { finish(handoffError("child_exit")); };
-    const onSpawn = () => {
-      if (!waitForHealthBeforeParentExit) {
-        // A deadline may have been caused by native-main ownership cleanup.
-        // Let the ordinary child survive parent exit, which releases those OS locks.
-        finish();
-        return;
-      }
-      void waitForReplacementReady(child.pid, process.pid, expectedPort).then(
-        ready => {
-          if (!ready) {
-            console.warn(
-              "Drain-and-restart replacement is still alive after the readiness window; allowing it to continue after parent exit",
-            );
-          }
-          // Never kill a live ordinary start at its valid reclaim boundary. Parent
-          // exit is the final resource release the child may still be waiting for.
-          finish();
-        },
-        err => finish(err),
-      );
-    };
-    child.once("error", onError);
-    child.once("exit", onExit);
-    child.once("spawn", onSpawn);
-  });
+  return spawnReplacementStart({ port, waitForHealth: waitForHealthBeforeParentExit, env });
 }
 
 async function completeDeferredParentExitHandoff(
@@ -327,6 +279,7 @@ async function completeDeferredParentExitHandoff(
       `Drain-and-restart ${phase} spawn failed (${spawnFailureCode(err)}); exiting without replacement`,
     );
     delete process.env.OCX_SERVICE;
+    keepRoutingForCommittedClient(io);
     exitProcess(1);
     return;
   }
@@ -342,6 +295,7 @@ async function completeDeadlineRestartHandoff(
   canHandoff: () => boolean = () => true,
 ): Promise<void> {
   if (!canHandoff()) return;
+  if (handOffToDesktop(io, exitProcess)) return;
   const supervised = (io.isSupervisedServiceChild ?? (() => isSupervisedServiceChild(io)))();
   if (supervised) {
     // Failure-only supervisors ignore exit(0); intentional non-zero triggers respawn.
@@ -455,6 +409,7 @@ export function acceptSystemRestart(io: SystemRestartIo = restartIo, admission:
         // rejects, an accepted restart must still reach replacement or terminal exit.
         console.warn("Drain-and-restart cleanup failed; continuing terminal restart handoff");
       }
+      if (handOffToDesktop(io, exitProcess)) return;
       const supervised = (io.isSupervisedServiceChild ?? (() => isSupervisedServiceChild(io)))();
       if (supervised) {
         // Failure-only supervisors ignore exit(0); intentional non-zero triggers respawn.
@@ -487,8 +442,10 @@ export function acceptSystemRestart(io: SystemRestartIo = restartIo, admission:
         );
         // Listen socket is already stopped; do not markRecycling — no child to inherit fences.
         // No replacement inherited the routing. Clear a stale service marker so
-        // this unsupervised parent restores clients after the failed handoff.
+        // this unsupervised parent restores clients after the failed handoff — unless a
+        // committed client connection already owns that routing.
         delete process.env.OCX_SERVICE;
+        keepRoutingForCommittedClient(io);
         exitProcess(1);
         return;
       }

package/src/server/management/system-routes.ts

@@ -217,7 +217,7 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
       };
     }
     if (req.method === "GET") {
-      return jsonResponse(service.readState(), 200, req, config);
+      return jsonResponse(await service.readState(), 200, req, config);
     }
     return jsonResponse(await service.performRestart(), 200, req, config);
   }

package/src/server/management-api.ts

@@ -88,7 +88,11 @@ import type { CatalogDisposition, ConvergeCodex } from "../codex/convergence-typ
 import { normalizeCatalogDisposition } from "../codex/catalog-refresh-status";
 import { managementBodyTooLargeResponse } from "./management/body";
 import { handleSessionRoutes } from "./management/session-routes";
+import { siblingRefusesManagementRequest } from "./management/sibling-guard";
+import { siblingOfLivePort, siblingSkipMessage } from "../codex/sibling-start";
 import { packageVersion } from "../lib/package-version";
+import { isLocalAccountSwitchPath } from "../lib/local-account-switch-capability";
+import { readVerifiedAccountSwitchBody } from "./local-account-switch-auth";
 
 // installed npm version instead of a stale hardcode.
 const MANAGEMENT_VERSION_FALLBACK = "0.0.0";
@@ -213,6 +217,19 @@ export async function handleManagementAPI(
   if (!isAllowedManagementOrigin(req, config)) {
     return jsonResponse({ error: "cross-origin request blocked" }, 403, req, config);
   }
+  if (principal === "local-account-switch-capability") {
+    if (req.method !== "PUT" || !isLocalAccountSwitchPath(url.pathname) || url.search !== "") {
+      return jsonResponse({ error: "account switch capability scope mismatch" }, 403, req, config);
+    }
+    if (req.headers.has("content-encoding")) {
+      return jsonResponse({ error: "content encoding is not supported" }, 415, req, config);
+    }
+    const verified = await readVerifiedAccountSwitchBody(req);
+    if (verified.status !== 200) {
+      return jsonResponse({ error: "account switch body rejected" }, verified.status, req, config);
+    }
+    req = new Request(req.url, { method: req.method, headers: req.headers, body: Buffer.from(verified.body) });
+  }
   // Management bodies are small JSON (provider names, key ids, settings). Reject oversized
   // payloads before any handler buffers them — the data plane has its own decompression cap.
   if (req.method === "POST" || req.method === "PUT" || req.method === "PATCH") {
@@ -297,6 +314,10 @@ export async function handleManagementAPI(
     guiSessionIssuance: requestIngress.guiSessionIssuance ?? null,
     convergeCodexCatalog, syncClaudeAgentDefsBestEffort,
   };
+  // Before any route module, including the link, native-main and codex-auth dispatch below.
+  if (siblingRefusesManagementRequest(req.method, url.pathname)) {
+    return jsonResponse({ error: siblingSkipMessage(), code: "sibling_instance" }, 409, req, config);
+  }
   let routed: Response | null | undefined;
   try {
     routed = handleSessionRoutes(ctx)
@@ -364,9 +385,16 @@ export async function handleManagementAPI(
     // outcome. This process cannot verify its own post-exit respawn window; only the
     // receipt-backed parent `ocx stop` can, which is what the deferral exists for.
     const { deferralMatchesReceipt } = await import("../config/pending-teardown");
-    const { deferralHonored, performStopTeardown } = await import("./stop-teardown");
+    const { deferralHonored, desktopSupervisedStopRefusal, performStopTeardown } = await import("./stop-teardown");
+    // The desktop app would start this proxy again within seconds; refuse before anything is
+    // touched and point at its tray, whose Stop it honours (#3008 refuses an undone stop the same way).
+    const desktopRefusal = desktopSupervisedStopRefusal(principal);
+    if (desktopRefusal) return jsonResponse(desktopRefusal, 409, req, config);
     const holdsReceipt = deferralHonored(url, deferralMatchesReceipt);
-    const respawnRisk = holdsReceipt ? "none" : installedServiceRespawnRisk();
+    // A sibling never runs under a service manager, and the installed service is the live
+    // owner's: asking the manager to stop from here would refuse, or boot the owner's job out.
+    const sibling = siblingOfLivePort() !== null;
+    const respawnRisk = holdsReceipt || sibling ? "none" : installedServiceRespawnRisk();
     if (respawnRisk === "respawnable") {
       return jsonResponse({
         success: false,
@@ -400,7 +428,7 @@ export async function handleManagementAPI(
     }
     let serviceStop: import("../service").ServiceStopOutcome;
     try {
-      serviceStop = stopServiceIfInstalledDetailed();
+      serviceStop = sibling ? "absent" : stopServiceIfInstalledDetailed();
     } catch (err) {
       if (isServiceOwnershipError(err)) {
         // The installed service belongs to another CODEX_HOME/OPENCODEX_HOME: it would respawn

package/src/server/management-auth.ts

@@ -72,6 +72,7 @@ import {
   type GuiSessionRequestContext,
 } from "./gui-session";
 import { hasLocalDesktopSnapshotCapability } from "./local-desktop-snapshot-auth";
+import { hasLocalAccountSwitchCapability } from "./local-account-switch-auth";
 export type { GuiSessionBootstrap, GuiSessionRequestContext } from "./gui-session";
 
 const LOCAL_READ_REPLAY_LIMIT = 256;
@@ -337,6 +338,7 @@ export type ManagementPrincipal =
   | "gui-pair-capability"
   | "local-read-capability"
   | "local-desktop-snapshot-capability"
+  | "local-account-switch-capability"
   | "local-provider-reload-capability"
   | "local-aside-sync-capability"
   | "system-restart-capability";
@@ -564,6 +566,7 @@ function resolveManagementAdmission(
   else if (hasLocalAsideSyncCapability(req, local)) principal = "local-aside-sync-capability";
   else if (hasLocalProviderReloadCapability(req, local)) principal = "local-provider-reload-capability";
   else if (hasLocalDesktopSnapshotCapability(req, local)) principal = "local-desktop-snapshot-capability";
+  else if (hasLocalAccountSwitchCapability(req, local)) principal = "local-account-switch-capability";
   else if (hasLocalReadCapability(req, local)) principal = "local-read-capability";
   else if (hasGuiPairCapability(req, local)) principal = "gui-pair-capability";
   else if (state.available) {