@bitkyc08/opencodex 2.10.0 → 2.10.1

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

@@ -23,39 +23,116 @@
  */
 import { spawn } from "node:child_process";
 import {
+  beginShutdownDrain,
   drainAndShutdown,
   getActiveTurnCount,
   getServerListenPort,
   isDraining,
+  isShutdownDraining,
   markRecyclingForExit,
-  setDraining,
+  stopServerListener,
 } from "../lifecycle";
 import { isServiceViable } from "../../service";
 import { readRuntimePort } from "../../config";
+import { withProcessRuntimeProvenance } from "../../lib/bun-runtime";
+import { findLiveProxy } from "../proxy-liveness";
 
 /** Fixed v1 drain window for the memory-card action (not config-driven). */
 export const MEMORY_DRAIN_RESTART_MS = 60_000;
+// Ordinary pinned-port start can spend 60s reclaiming a Windows ghost listener
+// and another 5s settling it. Keep one polling/scheduler margin beyond that.
+export const REPLACEMENT_READY_TIMEOUT_MS = 70_000;
+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 {
   drainAndShutdown?: typeof drainAndShutdown;
   /** True when a background service can actually respawn this process after exit(1). */
   isServiceViable?: () => boolean;
   isSupervisedServiceChild?: () => boolean;
-  /** Must resolve only after the replacement process has actually started. */
-  spawnStart?: (port?: number) => void | Promise<void>;
+  /** 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;
   exitProcess?: (code: number) => void;
   schedule?: (fn: () => void | Promise<void>, ms: number) => void;
+  scheduleDeadline?: (fn: () => void, ms: number) => () => void;
   isDraining?: () => boolean;
+  isShutdownDraining?: () => boolean;
+  beginShutdownDrain?: () => boolean;
   setDraining?: (value: boolean) => void;
   getActiveTurnCount?: () => number;
   listenPort?: () => number | undefined;
+  now?: () => number;
 }
 
 let restartIo: SystemRestartIo = {};
 /** Prevents double-scheduling in the 200ms window before drainAndShutdown sets draining. */
 let restartAccepted = false;
 
+type RestartDrainOutcome = "completed" | "rejected" | "deadline";
+type BoundedSettlementOutcome = "completed" | "rejected" | "deadline";
+
+function waitForRestartDrain(
+  drainPromise: Promise<void>,
+  deadlineMs: number,
+  now: () => number,
+  scheduleDeadline: NonNullable<SystemRestartIo["scheduleDeadline"]>,
+): Promise<RestartDrainOutcome> {
+  const remainingMs = Math.max(0, deadlineMs - now());
+  if (remainingMs === 0) {
+    // Observe any late rejection even though orchestration is already terminal.
+    void drainPromise.catch(() => {});
+    return Promise.resolve("deadline");
+  }
+  return new Promise<RestartDrainOutcome>((resolve) => {
+    let settled = false;
+    let cancelDeadline: (() => void) | undefined;
+    const finish = (outcome: RestartDrainOutcome) => {
+      if (settled) return;
+      settled = true;
+      cancelDeadline?.();
+      resolve(outcome);
+    };
+    cancelDeadline = scheduleDeadline(() => finish("deadline"), remainingMs);
+    if (settled) cancelDeadline();
+    void drainPromise.then(
+      () => finish("completed"),
+      () => finish("rejected"),
+    );
+  });
+}
+
+function waitForBoundedSettlement(
+  promise: Promise<void>,
+  timeoutMs: number,
+  scheduleDeadline: NonNullable<SystemRestartIo["scheduleDeadline"]>,
+): Promise<BoundedSettlementOutcome> {
+  return new Promise<BoundedSettlementOutcome>((resolve) => {
+    let settled = false;
+    let cancelDeadline: (() => void) | undefined;
+    const finish = (outcome: BoundedSettlementOutcome) => {
+      if (settled) return;
+      settled = true;
+      cancelDeadline?.();
+      resolve(outcome);
+    };
+    cancelDeadline = scheduleDeadline(() => finish("deadline"), timeoutMs);
+    if (settled) cancelDeadline();
+    void promise.then(
+      () => finish("completed"),
+      () => finish("rejected"),
+    );
+  });
+}
+
 /** Test seam — reset between tests. */
 export function setSystemRestartIoForTests(io: SystemRestartIo = {}): void {
   restartIo = io;
@@ -86,10 +163,62 @@ function spawnFailureCode(err: unknown): string {
   return "spawn_failed";
 }
 
-function spawnDetachedStart(port?: number): Promise<void> {
+function handoffError(code: string): NodeJS.ErrnoException {
+  const error = new Error(code) as NodeJS.ErrnoException;
+  error.code = code;
+  return error;
+}
+
+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;
+}
+
+function spawnDetachedStart(
+  port?: number,
+  waitForHealthBeforeParentExit = true,
+): Promise<void> {
   const args = [process.argv[1], "start"];
-  if (typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535) {
-    args.push("--port", String(Math.trunc(port)));
+  const expectedPort = typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535
+    ? Math.trunc(port)
+    : undefined;
+  if (expectedPort !== undefined) {
+    args.push("--port", String(expectedPort));
   }
   return new Promise<void>((resolve, reject) => {
     let child: ReturnType<typeof spawn>;
@@ -98,30 +227,113 @@ function spawnDetachedStart(port?: number): Promise<void> {
         detached: true,
         stdio: "ignore",
         windowsHide: true,
-        env: { ...process.env, OCX_SERVICE: "1" },
+        env: withProcessRuntimeProvenance({ ...process.env, OCX_SERVICE: "1" }),
       });
     } catch (err) {
       reject(err);
       return;
     }
     let settled = false;
-    const finish = (fn: () => void) => {
+    const cleanup = () => {
+      child.off("error", onError);
+      child.off("exit", onExit);
+      child.off("spawn", onSpawn);
+    };
+    const finish = (error?: unknown) => {
       if (settled) return;
       settled = true;
-      fn();
+      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();
     };
-    child.once("error", (err) => {
-      finish(() => reject(err));
-    });
-    child.once("spawn", () => {
-      finish(() => {
-        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);
   });
 }
 
+async function completeDeferredParentExitHandoff(
+  io: SystemRestartIo,
+  exitProcess: (code: number) => void,
+  port: number | undefined,
+  phase: "deadline" | "listener-stop fallback",
+): Promise<void> {
+  try {
+    await (io.spawnStart ?? spawnDetachedStart)(port, false);
+  } catch (err) {
+    console.warn(
+      `Drain-and-restart ${phase} spawn failed (${spawnFailureCode(err)}); exiting without replacement`,
+    );
+    delete process.env.OCX_SERVICE;
+    exitProcess(1);
+    return;
+  }
+  (io.markRecycling ?? markRecyclingForExit)();
+  exitProcess(0);
+}
+
+async function completeDeadlineRestartHandoff(
+  io: SystemRestartIo,
+  exitProcess: (code: number) => void,
+  port: number | undefined,
+  scheduleDeadline: NonNullable<SystemRestartIo["scheduleDeadline"]>,
+): Promise<void> {
+  const supervised = (io.isSupervisedServiceChild ?? (() => isSupervisedServiceChild(io)))();
+  if (supervised) {
+    // Failure-only supervisors ignore exit(0); intentional non-zero triggers respawn.
+    exitProcess(1);
+    return;
+  }
+
+  const stopPromise = Promise.resolve().then(
+    () => (io.stopListener ?? (() => stopServerListener()))(),
+  );
+  const stopOutcome = await waitForBoundedSettlement(
+    stopPromise,
+    DEADLINE_LISTENER_STOP_TIMEOUT_MS,
+    scheduleDeadline,
+  );
+  if (stopOutcome === "rejected") {
+    console.warn("Drain-and-restart deadline listener stop failed; continuing parent-exit handoff");
+  } else if (stopOutcome === "deadline") {
+    console.warn("Drain-and-restart deadline listener stop timed out; continuing parent-exit handoff");
+  }
+  // The ordinary child must survive parent exit: a failed/pending socket close
+  // or overdue cleanup is completed by process teardown, without a hidden mode.
+  await completeDeferredParentExitHandoff(io, exitProcess, port, "deadline");
+}
+
 /**
  * Accept a drain-and-restart request. Returns immediately; the drain +
  * respawn runs on a short timer so the HTTP response can flush first.
@@ -133,27 +345,67 @@ export function acceptSystemRestart(io: SystemRestartIo = restartIo): {
   activeTurnCount: number;
   drainTimeoutMs: number;
 } {
-  const alreadyDraining = restartAccepted || (io.isDraining ?? isDraining)();
+  const shutdownActive = io.isShutdownDraining
+    ?? io.isDraining
+    ?? isShutdownDraining;
+  const alreadyDraining = restartAccepted || shutdownActive();
   const activeTurnCount = (io.getActiveTurnCount ?? getActiveTurnCount)();
   const schedule = io.schedule ?? ((fn, ms) => { setTimeout(() => { void fn(); }, ms); });
 
   if (!alreadyDraining) {
     restartAccepted = true;
+    const now = io.now ?? Date.now;
+    const restartDeadlineMs = now() + MEMORY_DRAIN_RESTART_MS;
     // Reject new data-plane traffic immediately (503), before the 200ms response-flush delay.
-    (io.setDraining ?? setDraining)(true);
+    if (io.beginShutdownDrain) io.beginShutdownDrain();
+    else if (io.setDraining) io.setDraining(true);
+    else beginShutdownDrain();
     schedule(async () => {
+      // Preserve the live binding before drainAndShutdown (or its deadline race)
+      // closes the listener and makes both the server ref and runtime metadata stale.
+      const restartPort = (io.listenPort ?? resolveListenPort)();
       const drain = io.drainAndShutdown ?? drainAndShutdown;
-      await drain(undefined, MEMORY_DRAIN_RESTART_MS);
+      const remainingMs = Math.max(0, restartDeadlineMs - now());
+      const drainPromise = Promise.resolve().then(() => drain(undefined, remainingMs));
+      const scheduleDeadline = io.scheduleDeadline ?? ((fn, ms) => {
+        const timer = setTimeout(fn, ms);
+        return () => clearTimeout(timer);
+      });
+      const drainOutcome = await waitForRestartDrain(drainPromise, restartDeadlineMs, now, scheduleDeadline);
+      const exitProcess = io.exitProcess ?? ((code: number) => { process.exit(code); });
+      if (drainOutcome === "deadline") {
+        console.warn("Drain-and-restart deadline expired; forcing terminal restart handoff");
+        await completeDeadlineRestartHandoff(io, exitProcess, restartPort, scheduleDeadline);
+        return;
+      }
+      if (drainOutcome === "rejected") {
+        // drainAndShutdown stops the listener in finally. Even if ancillary cleanup
+        // rejects, an accepted restart must still reach replacement or terminal exit.
+        console.warn("Drain-and-restart cleanup failed; continuing terminal restart handoff");
+      }
       const supervised = (io.isSupervisedServiceChild ?? (() => isSupervisedServiceChild(io)))();
       if (supervised) {
         // Failure-only supervisors ignore exit(0); intentional non-zero triggers respawn.
         (io.exitProcess ?? ((code: number) => { process.exit(code); }))(1);
         return;
       }
-      const port = (io.listenPort ?? resolveListenPort)();
-      const exitProcess = io.exitProcess ?? ((code: number) => { process.exit(code); });
       try {
-        await (io.spawnStart ?? spawnDetachedStart)(port);
+        await (io.stopListener ?? (() => stopServerListener()))();
+      } catch {
+        console.warn("Drain-and-restart listener stop failed; continuing parent-exit handoff");
+        await completeDeferredParentExitHandoff(
+          io,
+          exitProcess,
+          restartPort,
+          "listener-stop fallback",
+        );
+        return;
+      }
+      try {
+        // A rejected drain has uncertain cleanup ownership, so it uses the same
+        // parent-exit handoff as a deadline. Only a fully completed drain waits
+        // for replacement health in the old process.
+        await (io.spawnStart ?? spawnDetachedStart)(restartPort, drainOutcome === "completed");
       } catch (err) {
         console.warn(
           `⚠️  Drain-and-restart spawn failed (${spawnFailureCode(err)}); exiting without replacement`,

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

@@ -22,6 +22,7 @@
  * dashboard drain-and-restart confirm UX — never request bodies or IDs.
  */
 import { selectEagerPath } from "../../lib/bun-stream-caps";
+import { reportedBunRuntimeSource } from "../../lib/bun-runtime";
 import { getActiveTurnCount, isDraining } from "../lifecycle";
 import { getActiveMemoryWatchdog, observedMemoryCounter } from "../memory-watchdog";
 import { responseStateMetrics } from "../../responses/state";
@@ -78,6 +79,9 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
       pid: process.pid,
       bunVersion: Bun.version,
       bunRevision: Bun.revision,
+      // Recorded at launch, not resolved now: absent means "this service predates the
+      // marker", which callers must report as unknown rather than guess.
+      bunRuntimeSource: reportedBunRuntimeSource(),
       platform: process.platform,
       uptimeSeconds: process.uptime(),
       rss: usage.rss,

package/src/server/management-api.ts

@@ -59,6 +59,9 @@ import { applySystemEnvToggle } from "./system-env";
 import type { ManagementApiDeps } from "./management/context";
 import { handleConfigRoutes } from "./management/config-routes";
 import { handleLogsUsageRoutes } from "./management/logs-usage-routes";
+import { handleRequestHistoryRoutes } from "./management/request-history-routes";
+import { handleRoutingAnalyticsRoutes } from "./management/routing-analytics-routes";
+import { handleRoutingProfileRoutes } from "./management/routing-profile-routes";
 import { handleProviderRoutes } from "./management/provider-routes";
 import { handleModelRoutes } from "./management/model-routes";
 import { handleAgentSettingsRoutes } from "./management/agent-settings-routes";
@@ -66,10 +69,14 @@ import { handleOauthAccountRoutes } from "./management/oauth-account-routes";
 import { handleComboRoutes } from "./management/combo-routes";
 import { handleSystemRoutes } from "./management/system-routes";
 import { handleSidebarRoutes } from "./management/sidebar-routes";
+import { handleIntegrationRoutes } from "./management/integration-routes";
+import { handleNativeIntegrationRoutes } from "./management/native-integration-routes";
 import type { ManagementContext } from "./management/context";
+import type { ManagementPrincipal } from "./management-auth";
 export type { ManagementApiDeps } from "./management/context";
 import { fetchAllModels } from "./management/shared";
 import { CatalogGatherBusyError } from "../codex/catalog/provider-fetch";
+import type { CatalogDisposition, ConvergeCodex } from "../codex/convergence-types";
 import { managementBodyTooLargeResponse } from "./management/body";
 
 // installed npm version instead of a stale hardcode.
@@ -81,7 +88,40 @@ export const VERSION = (() => {
   }
 })();
 
-export async function handleManagementAPI(req: Request, url: URL, config: OcxConfig, deps: ManagementApiDeps = {}): Promise<Response | null> {
+function isCatalogDisposition(value: unknown): value is CatalogDisposition {
+  if (!value || typeof value !== "object" || !("status" in value)) return false;
+  const disposition = value as Record<string, unknown>;
+  if (disposition.status === "committed") {
+    return typeof disposition.changed === "boolean"
+      && typeof disposition.degraded === "boolean"
+      && Array.isArray(disposition.notices)
+      && disposition.notices.every(notice => notice === "provider-auth" || notice === "provider-network" || notice === "fallback");
+  }
+  if (disposition.status === "skipped") {
+    return ["not-requested", "catalog-unavailable", "busy", "stale", "refused"].includes(String(disposition.reason))
+      && typeof disposition.retryable === "boolean";
+  }
+  if (disposition.status === "failed") {
+    return ["provider-auth", "provider-network", "disk"].includes(String(disposition.reason))
+      && (disposition.phase === "gather" || disposition.phase === "commit")
+      && typeof disposition.retryable === "boolean"
+      && typeof disposition.partialWrite === "boolean";
+  }
+  return false;
+}
+
+const managementConvergenceBindings = new WeakMap<object, Readonly<{
+  factory: (config: Readonly<OcxConfig>) => ConvergeCodex;
+  converge: ConvergeCodex;
+}>>();
+
+export async function handleManagementAPI(
+  req: Request,
+  url: URL,
+  config: OcxConfig,
+  deps: ManagementApiDeps = {},
+  principal?: ManagementPrincipal,
+): Promise<Response | null> {
   if (!isAllowedManagementOrigin(req, config)) {
     return jsonResponse({ error: "cross-origin request blocked" }, 403, req, config);
   }
@@ -93,13 +133,38 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
       return jsonResponse({ error: "request body too large" }, 413, req, config);
     }
   }
-  async function refreshCodexCatalogBestEffort(): Promise<void> {
-    if (deps.refreshCodexCatalog) return deps.refreshCodexCatalog();
+  async function convergeCodexCatalog(): Promise<CatalogDisposition> {
+    let convergenceInvoked = false;
+    let managementConvergeCodex: ConvergeCodex | undefined;
     try {
-      const { refreshCodexModelCatalog } = await import("../codex/refresh");
-      await refreshCodexModelCatalog(config);
+      if (!managementConvergeCodex) {
+        const factory = deps.createManagementConvergeCodex
+          ?? (await import("../codex/management-convergence")).createManagementConvergeCodex;
+        if (typeof factory !== "function") throw new TypeError("Catalog convergence factory is unavailable.");
+        let binding = managementConvergenceBindings.get(config);
+        if (!binding || binding.factory !== factory) {
+          const created = factory(config);
+          if (typeof created !== "function") throw new TypeError("Catalog convergence factory returned no function.");
+          binding = { factory, converge: created };
+          managementConvergenceBindings.set(config, binding);
+        }
+        managementConvergeCodex = binding.converge;
+      }
+      const { createCatalogConvergeRequest } = await import("../codex/catalog-admission");
+      convergenceInvoked = true;
+      const outcome = await managementConvergeCodex(createCatalogConvergeRequest({ deadlineMs: 1_000 }));
+      if (!outcome || outcome.kind !== "catalog-only" || !isCatalogDisposition(outcome.catalogRefresh)) {
+        throw new TypeError("Catalog convergence returned an invalid outcome.");
+      }
+      return outcome.catalogRefresh;
     } catch {
-      /* catalog absent */
+      return {
+        status: "failed",
+        reason: "disk",
+        phase: convergenceInvoked ? "commit" : "gather",
+        retryable: false,
+        partialWrite: convergenceInvoked,
+      };
     }
   }
 
@@ -124,13 +189,18 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
       }
     } catch { /* best-effort */ }
   }
-  const ctx: ManagementContext = { req, url, config, deps, refreshCodexCatalogBestEffort, syncClaudeAgentDefsBestEffort };
+  const ctx: ManagementContext = { req, url, config, deps, principal, convergeCodexCatalog, syncClaudeAgentDefsBestEffort };
   let routed: Response | null;
   try {
     routed = (await handleConfigRoutes(ctx))
     ??     (await handleLogsUsageRoutes(ctx))
+    ??     (await handleRequestHistoryRoutes(ctx))
+    ??     (await handleRoutingAnalyticsRoutes(ctx))
+    ??     (await handleRoutingProfileRoutes(ctx))
     ??     (await handleProviderRoutes(ctx))
     ??     (await handleModelRoutes(ctx))
+    ??     (await handleIntegrationRoutes(ctx))
+    ??     (await handleNativeIntegrationRoutes(ctx))
     ??     (await handleAgentSettingsRoutes(ctx))
     ??     (await handleOauthAccountRoutes(ctx))
     ??     (await handleComboRoutes(ctx))
@@ -154,7 +224,7 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
   if (routed) return routed;
 
   if (url.pathname === "/api/stop" && req.method === "POST") {
-    const { restoreNativeCodex } = await import("../codex/inject");
+    const { restoreNativeCodexAsync } = await import("../codex/inject");
     const { stopServiceIfInstalled, isServiceOwnershipError } = await import("../service");
     try {
       stopServiceIfInstalled();
@@ -167,7 +237,7 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
       }
       throw err;
     }
-    const restore = restoreNativeCodex();
+    const restore = await restoreNativeCodexAsync();
     // Both managed configs come down together on an explicit teardown. The daemon's own
     // syncCleanup skips this when OCX_SERVICE is set (so a crash/respawn keeps the fence),
     // which is exactly why an intentional stop has to do it here.
@@ -183,6 +253,11 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
       : { success: false, message: `Proxy stopping, but native Codex restore failed: ${restore.message}. Run \`ocx restore\`.${grokNote}` });
   }
 
+  if (url.pathname.startsWith("/api/native-main-profiles")) {
+    const { handleNativeProfileAPI } = await import("../codex/native-profile-api");
+    return handleNativeProfileAPI(req, url, config, deps.nativeProfileApi);
+  }
+
   if (url.pathname.startsWith("/api/codex-auth/")) {
     const { handleCodexAuthAPI } = await import("../codex/auth-api");
     const { ConfigMutationLockError } = await import("../config");

package/src/server/management-auth.ts

@@ -13,7 +13,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { adminApiTokenFilePath } from "../lib/admin-secrets";
-import { forgetHardenedSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
+import { forgetEphemeralSecretPath, forgetHardenedSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
 import type { OcxConfig } from "../types";
 import {
   isAllowedManagementOrigin,
@@ -95,12 +95,17 @@ function readExistingToken(path: string): string {
 export function removeManagementTokenPathBestEffort(
   path: string,
   remove: (path: string) => void = unlinkSync,
+  options?: { ephemeral?: boolean },
 ): void {
+  // Temps get the full ephemeral release (success + both timeout namespaces);
+  // stable token paths drop only the success memo — destination-keyed timeout
+  // memos are intentional anti-restall state.
+  const forget = options?.ephemeral ? forgetEphemeralSecretPath : forgetHardenedSecretPath;
   try {
     remove(path);
-    forgetHardenedSecretPath(path);
+    forget(path);
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") forgetHardenedSecretPath(path);
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") forget(path);
     /* other failures retain fail-closed state for the caller */
   }
 }
@@ -120,7 +125,8 @@ function createTokenFile(path: string): string {
     chmodSync(temporary, 0o600);
     let temporaryHardened: { ok: boolean };
     try {
-      temporaryHardened = hardenSecretPath(temporary, { required: true });
+      // Destination-keyed timeout memo (the final token path), not the temp.
+      temporaryHardened = hardenSecretPath(temporary, { required: true, timeoutMemoKey: path });
     } catch {
       temporaryHardened = { ok: false };
     }
@@ -155,7 +161,7 @@ function createTokenFile(path: string): string {
     if (fd !== null) {
       try { closeSync(fd); } catch { /* best effort */ }
     }
-    removeManagementTokenPathBestEffort(temporary);
+    removeManagementTokenPathBestEffort(temporary, unlinkSync, { ephemeral: true });
   }
 }
 
@@ -231,6 +237,38 @@ export function issueGuiSession(
   return { token, ...session };
 }
 
+/**
+ * Which credential actually authorized a management request.
+ *
+ * `admin-token` is the raw token from disk/env: anything running as the user can
+ * read it, including a coding agent. `gui-session` is a session token this process
+ * minted for a browser, and it only authorizes a mutation after the origin and the
+ * per-session CSRF token match. Consent-bearing routes must key off this value
+ * rather than off request headers, which the token holder can forge freely.
+ */
+export type ManagementPrincipal = "admin-token" | "gui-session";
+
+/**
+ * The principal for a request that already passed `requireManagementAuth`. Kept as a
+ * separate resolution (rather than a changed return type) so every existing caller
+ * keeps its `Response | null` contract; the value is derived from the same session
+ * table and the same CSRF comparison the gate uses, so the two cannot disagree.
+ */
+export function managementPrincipal(
+  req: Request,
+  state: ManagementAuthState,
+  config?: OcxConfig,
+): ManagementPrincipal | null {
+  if (!state.available) return null;
+  const actual = req.headers.get("x-opencodex-api-key")?.trim()
+    || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
+  if (!actual) return null;
+  if (equalSecret(actual, state.token)) return "admin-token";
+  if (!config) return null;
+  removeExpiredSessions(state);
+  return state.sessions.has(actual) ? "gui-session" : null;
+}
+
 export function requireManagementAuth(
   req: Request,
   state: ManagementAuthState,