@iislee/opencodex 2.11.0

package/src/server/management/shared.ts

@@ -0,0 +1,277 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { CatalogModel } from "../../codex/catalog";
+import { catalogModelSlug, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../../codex/catalog";
+import {
+  DEFAULT_SUBAGENT_MODELS,
+  codexAutoStartEnabled,
+  hasOwnProvider,
+  isValidProviderName,
+  multiAgentGuidanceEnabled,
+  providerBaseUrlConfigError,
+  providerHeadersConfigError,
+  saveConfigPreservingClaudeCode,
+} from "../../config";
+import {
+  clearLoginState,
+  getLoginStatus,
+  isPublicOAuthProvider,
+  listOAuthProviders,
+  startLoginFlow,
+  submitManualLoginCode,
+  upsertOAuthProvider,
+} from "../../oauth";
+import { removeCredential } from "../../oauth/store";
+import { providerDestinationResolvedError } from "../../lib/destination-policy";
+import { enrichProviderFromCatalog, listKeyLoginProviders } from "../../oauth/key-providers";
+import { deriveProviderPresets } from "../../providers/derive";
+import { providerCodexAccountMode } from "../../providers/registry";
+import { routedSlug, slugEquals } from "../../providers/slug-codec";
+import { clearProviderQuotaCache, fetchProviderQuotaReports } from "../../providers/quota";
+import { isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers";
+import { clearThreadAccountMap } from "../../codex/routing";
+import { primeCodexPoolQuotas } from "../../codex/auth-api";
+import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap, providerContextCaps, setAllProviderContextCaps, setGlobalContextCapValue, setProviderContextCap } from "../../providers/context-cap";
+import { resolveCodexHomeDir } from "../../codex/home";
+import { readUsageEntries } from "../../usage/log";
+import { getUsageDebugLogEntries } from "../../usage/debug";
+import { parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
+import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
+import { getProviderRegistryEntry, providerMatchesRegistryTransport } from "../../providers/registry";
+import { getDebugLogEntries } from "../../lib/debug-log-buffer";
+import { getInjectionDebugLogEntries } from "../../lib/injection-debug-log";
+import {
+  clearDebugSettings,
+  clearDebugSetting,
+  getDebugSettings,
+  setDebugSettings,
+  type DebugFlag,
+} from "../../lib/debug-settings";
+import type { OcxClaudeCodeConfig, OcxClaudeDesktopProfile, OcxConfig, OcxCustomModel, OcxProviderConfig } from "../../types";
+import type { DesktopProfileModel } from "../../claude/desktop-profile";
+import { drainAndShutdown } from "../lifecycle";
+import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
+import { estimateComboCost, estimateRequestCost, effectiveServiceTier, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
+import type { PersistedUsageAttempt } from "../../usage/log";
+import { isAllowedRequestOrigin, jsonResponse, providerManagementConfigError, publicProviderBaseUrl, safeConfigDTO } from "../auth-cors";
+import { applySystemEnvToggle } from "../system-env";
+
+
+export function isPlainRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export function parseDebugLogQuery(url: URL): { after: number; limit: number } {
+  const after = Number(url.searchParams.get("after") ?? url.searchParams.get("since") ?? "0");
+  const limit = Number(url.searchParams.get("limit") ?? "500");
+  return {
+    after: Number.isFinite(after) && after > 0 ? after : 0,
+    limit: Number.isFinite(limit) && limit > 0 ? Math.min(limit, 2000) : 500,
+  };
+}
+
+// ---- /api/logs display metrics (devlog/_plan/260720_toks_speed_price_columns/020) ----
+// Derived at response time only; NEVER persisted to the request log or usage.jsonl.
+
+export type MetricUnavailableReason =
+  | "usage_missing" | "usage_unsupported" | "output_missing" | "invalid_duration"
+  | "price_unmatched" | "invalid_cache_breakdown"
+  | "invalid_usage" | "combo_attempt_unavailable";
+
+export type TokPerSecondResult =
+  | { kind: "value"; value: number; estimated: boolean }
+  | { kind: "unavailable"; reason: MetricUnavailableReason };
+
+export type CostEstimateReason = "usage_estimated" | "cache_detail_missing" | "expected_price_overlay";
+
+export type CostResult =
+  | { kind: "value"; estimate: NonNullable<ReturnType<typeof estimateRequestCost>>; estimateReasons: CostEstimateReason[] }
+  | { kind: "unavailable"; reason: MetricUnavailableReason };
+
+export type MetricSource = Pick<RequestLogEntry, "provider" | "model" | "durationMs" | "usageStatus" | "usage" | "requestedServiceTier" | "configuredServiceTier" | "responseServiceTier"> & {
+  attempts?: readonly PersistedUsageAttempt[];
+};
+
+export function tokPerSecondResult(entry: Pick<MetricSource, "durationMs" | "usageStatus" | "usage">): TokPerSecondResult {
+  if (!entry.usage) return { kind: "unavailable", reason: "usage_missing" };
+  if (entry.usageStatus === "unsupported") return { kind: "unavailable", reason: "usage_unsupported" };
+  const value = tokensPerSecond(entry.usage.outputTokens, entry.durationMs);
+  if (value === null) {
+    return {
+      kind: "unavailable",
+      reason: entry.usage.outputTokens <= 0 ? "output_missing" : "invalid_duration",
+    };
+  }
+  return { kind: "value", value, estimated: entry.usageStatus === "estimated" || entry.usage.estimated === true };
+}
+
+export function unavailableCostReason(entry: MetricSource): MetricUnavailableReason {
+  // Normalizer-first classification: the landed normalizer recovers legacy
+  // cachedInputTokens=read+write rows via retry, so a raw read+write>input
+  // pre-check would misclassify recoverable rows (020 audit blocker #2).
+  if (!entry.usage && !entry.attempts?.length) return "usage_missing";
+  if (entry.usageStatus === "unsupported") return "usage_unsupported";
+  if (entry.attempts?.length) return "combo_attempt_unavailable";
+  if (!entry.usage) return "usage_missing";
+  if (!normalizeCostTokens(entry.usage)) {
+    const effectiveRead = entry.usage.cacheReadInputTokens ?? entry.usage.cachedInputTokens ?? 0;
+    const effectiveWrite = entry.usage.cacheCreationInputTokens ?? 0;
+    const finite = [entry.usage.inputTokens, entry.usage.outputTokens, effectiveRead, effectiveWrite]
+      .every(v => Number.isFinite(v) && v >= 0);
+    return finite ? "invalid_cache_breakdown" : "invalid_usage";
+  }
+  return "price_unmatched";
+}
+
+export function costResult(entry: MetricSource): CostResult {
+  const tier = effectiveServiceTier(entry);
+  const estimate = entry.attempts?.length
+    ? estimateComboCost(entry.attempts, undefined, tier)
+    : estimateRequestCost({ provider: entry.provider, model: entry.model, usage: entry.usage, usageStatus: entry.usageStatus, serviceTier: tier });
+  if (!estimate) return { kind: "unavailable", reason: unavailableCostReason(entry) };
+  const estimateReasons = [
+    entry.usageStatus === "estimated" || entry.usage?.estimated ? "usage_estimated" as const : undefined,
+    entry.usage && entry.usage.cachedInputTokens === undefined
+      && entry.usage.cacheReadInputTokens === undefined
+      && entry.usage.cacheCreationInputTokens === undefined ? "cache_detail_missing" as const : undefined,
+    estimate.price?.source === "expected" || estimate.attempts?.some(a => a.price.source === "expected")
+      ? "expected_price_overlay" as const : undefined,
+  ].filter((reason): reason is CostEstimateReason => reason !== undefined);
+  return { kind: "value", estimate, estimateReasons };
+}
+
+export function requestLogDto(entry: RequestLogEntry): Record<string, unknown> {
+  return {
+    ...entry,
+    displayMetrics: {
+      tokPerSecond: tokPerSecondResult(entry),
+      cost: costResult(entry),
+    },
+    ...(entry.attempts?.length
+      ? {
+        attempts: entry.attempts.map(attempt => ({
+          ...attempt,
+          displayMetrics: {
+            tokPerSecond: tokPerSecondResult(attempt),
+            cost: costResult({ ...attempt, attempts: undefined, requestedServiceTier: entry.requestedServiceTier, configuredServiceTier: entry.configuredServiceTier, responseServiceTier: entry.responseServiceTier }),
+          },
+        })),
+      }
+      : {}),
+  };
+}
+
+/**
+ * Live routed-provider models for the proxy's /api/* and /v1/models endpoints. Delegates to the
+ * canonical, TTL-cached `gatherRoutedModels` (single source of truth) — so the GUI/codex endpoints
+ * share the same fetch, the same per-provider cache (dedups Codex's frequent /v1/models polling),
+ * and the same stale fallback when a provider blips, instead of a parallel uncached copy.
+ */
+export async function fetchAllModels(config: OcxConfig): Promise<CatalogModel[]> {
+  const { gatherRoutedModels } = await import("../../codex/catalog");
+  return gatherRoutedModels(config);
+}
+
+export interface GrokCandidateModel {
+  id: string;
+  contextWindow?: number;
+  native: boolean;
+}
+
+/**
+ * The model list `syncGrokConfig` would inject, BEFORE the user's exclusions. The Grok
+ * page needs this to show a switch for a model the user has already excluded — such a
+ * model is absent from the fence, so readGrokStatus alone could never list it. Built
+ * from the same two sources as the sync so the two can never disagree.
+ */
+export async function fetchGrokCandidateModels(config: OcxConfig): Promise<GrokCandidateModel[]> {
+  const { filterCatalogVisibleModels, nativeOpenAiContextWindow, visibleNativeSlugs } = await import("../../codex/catalog");
+  const routed = filterCatalogVisibleModels(await fetchAllModels(config), config);
+  return [
+    ...visibleNativeSlugs(config).map(id => {
+      const contextWindow = nativeOpenAiContextWindow(id);
+      return { id, native: true, ...(contextWindow !== undefined ? { contextWindow } : {}) };
+    }),
+    ...routed.map(m => ({
+      id: m.alias ?? `${m.provider}/${m.id}`,
+      native: false,
+      ...(m.contextWindow !== undefined ? { contextWindow: m.contextWindow } : {}),
+    })),
+  ];
+}
+
+export function stripRegistryOnlyStaticHeaders(name: string, provider: OcxProviderConfig): OcxProviderConfig {
+  const entry = providerMatchesRegistryTransport(name, provider) ? getProviderRegistryEntry(name) : undefined;
+  if (!entry?.staticHeaders || !provider.headers) return provider;
+  const headerEntries = Object.entries(provider.headers);
+  const staticEntries = Object.entries(entry.staticHeaders);
+  if (headerEntries.length !== staticEntries.length) return provider;
+  const matchesRegistryStaticHeaders = staticEntries.every(([key, value]) => provider.headers?.[key] === value);
+  if (!matchesRegistryStaticHeaders) return provider;
+  const { headers: _headers, ...rest } = provider;
+  return rest;
+}
+
+/** Shared Desktop profile DTO builder for the management API and CLI. */
+export async function buildClaudeDesktopState(config: OcxConfig, stored?: OcxClaudeDesktopProfile) {
+  const { filterCatalogVisibleModels, nativeOpenAiContextWindow, desktopVisibleNativeSlugs } = await import("../../codex/catalog");
+  const { DESKTOP_SUPPORTS_1M_THRESHOLD } = await import("../../claude/desktop-3p");
+  const { reconcileDesktopProfile, renderDesktopProfile } = await import("../../claude/desktop-profile");
+  const routed = filterCatalogVisibleModels(await fetchAllModels(config), config);
+  const profileModels: DesktopProfileModel[] = [
+    // Native rows carry their real context window from the same accessor the Grok sync
+    // uses — otherwise Sol's 372k and gpt-5.5's 272k render as blank on Desktop.
+    ...desktopVisibleNativeSlugs(config).map(id => {
+      const contextWindow = nativeOpenAiContextWindow(id);
+      return { route: `native/${id}`, label: `${id} (native)`,
+        ...(contextWindow !== undefined ? { contextWindow } : {}) };
+    }),
+    ...routed.map(model => ({
+      route: `${model.provider}/${model.id}`,
+      label: `${model.id} (${model.provider})`,
+      ...(typeof model.contextWindow === "number" ? { contextWindow: model.contextWindow } : {}),
+    })),
+  ];
+  const profile = reconcileDesktopProfile(stored ?? config.claudeCode?.desktopProfile, profileModels);
+  if (config.claudeCode?.desktopNativeModels === false) {
+    for (const route of Object.keys(profile.assignments)) {
+      if (route.startsWith("native/")) delete profile.assignments[route];
+    }
+    for (const family of ["opus", "fable", "sonnet", "haiku"] as const) {
+      const current = profile.defaults[family];
+      if (current?.startsWith("native/")) {
+        profile.defaults[family] = Object.keys(profile.assignments)
+          .filter(route => profile.assignments[route]?.family === family)
+          .sort()[0] ?? null;
+      }
+    }
+  }
+  const available = new Set(profileModels.map(model => model.route));
+  const modelByRoute = new Map(profileModels.map(model => [model.route, model]));
+  // Effort support: routed models with a non-empty reasoningEfforts ladder support effort;
+  // native models always support it (Anthropic native effort).
+  const effortByRoute = new Map<string, boolean>();
+  for (const m of routed) {
+    effortByRoute.set(`${m.provider}/${m.id}`, Array.isArray(m.reasoningEfforts) && m.reasoningEfforts.length > 0);
+  }
+  for (const id of desktopVisibleNativeSlugs(config)) {
+    effortByRoute.set(`native/${id}`, true);
+  }
+  const models = Object.keys(profile.assignments).sort().map(route => ({
+    route,
+    label: modelByRoute.get(route)?.label ?? route,
+    available: available.has(route),
+    ...(modelByRoute.get(route)?.contextWindow ? { contextWindow: modelByRoute.get(route)!.contextWindow } : {}),
+    effortSupported: effortByRoute.get(route) ?? false,
+    // Read-only view of the 1M capability the written Desktop config already emits,
+    // derived from the SAME threshold so the dashboard chip can never disagree.
+    supports1m: (modelByRoute.get(route)?.contextWindow ?? 0) >= DESKTOP_SUPPORTS_1M_THRESHOLD,
+    assignment: profile.assignments[route]!,
+  }));
+  return {
+    profile,
+    models,
+    rendered: renderDesktopProfile(profile, profileModels),
+    port: config.port,
+  };
+}

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

@@ -0,0 +1,90 @@
+/**
+ * /api/github/star and /api/update/badge — the two cheap polls behind the
+ * sidebar's GitHub star and update controls.
+ *
+ * Both ride the standard management gate (auth + origin check happen before
+ * dispatch), and both are scalar-only: a star state enum, a repo slug, version
+ * strings, and a fixed error code. No GitHub token, account login, or raw `gh`/npm
+ * output is ever serialized here — starring runs through the user's own `gh` CLI and
+ * this surface only learns the yes/no answer. `gh` writes the authenticated account
+ * name to stderr, so that output is discarded at the source rather than forwarded.
+ *
+ * The star POST additionally refuses agent-driven programmatic callers. Management
+ * auth proves the caller reached the admin token, not that a person chose to star:
+ * a coding agent runs on the user's machine and can read that token from disk, so
+ * the CLI's "ask the user" deferral would be bypassable with one `curl` here.
+ *
+ * The dashboard button must keep working even when the proxy itself was started by
+ * an agent, which is the common case — the person is at the browser, not at the
+ * spawning shell. A GUI click is therefore distinguished by its browser session
+ * evidence (a same-origin `Origin` plus the minted CSRF header, both already
+ * verified by the management auth gate) rather than by the proxy's own env.
+ */
+import { jsonResponse } from "../auth-cors";
+import { agentDrivenMarkers, isAgentDriven } from "../../cli/agent-driven";
+import type { ManagementContext } from "./context";
+
+/**
+ * True when this request carries the browser-session evidence a dashboard click
+ * always has: an `Origin` (only a browser sends one) plus the per-session CSRF
+ * token, which `requireManagementAuth` has already matched against the minted
+ * session before dispatch. A shell/HTTP caller holding only the admin token has
+ * neither, which is exactly the case the agent guard is aimed at.
+ */
+function hasBrowserSessionEvidence(req: Request): boolean {
+  return !!req.headers.get("Origin")?.trim()
+    && !!req.headers.get("x-opencodex-csrf-token")?.trim()
+    && !!req.headers.get("x-opencodex-gui-origin")?.trim();
+}
+
+// Known edge, deliberately fail-closed: a non-loopback operator dashboard signs in
+// with the raw admin token instead of a minted GUI session, so its clicks carry no
+// CSRF header. If that proxy was *also* started from an agent shell, the button is
+// refused and the response names the one-line `gh` command to run by hand. A
+// service-run proxy (`OCX_SERVICE`, the usual remote setup) is not agent-driven and
+// is unaffected.
+
+export async function handleSidebarRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url } = ctx;
+
+  if (url.pathname === "/api/github/star" && req.method === "GET") {
+    const { getStarStatus } = await import("../../github/star-state");
+    return jsonResponse(await getStarStatus());
+  }
+
+  if (url.pathname === "/api/github/star" && req.method === "POST") {
+    const { STAR_REPO, STAR_REPO_URL, starRepository } = await import("../../github/star-state");
+    // Starring uses the user's GitHub identity, so consent must come from the
+    // account owner. An agent-driven caller without browser-session evidence
+    // cannot have obtained it, and must relay the question instead of answering
+    // it with an HTTP call.
+    if (isAgentDriven() && !hasBrowserSessionEvidence(req)) {
+      return jsonResponse({
+        ok: false,
+        state: "not-starred",
+        repo: STAR_REPO,
+        url: STAR_REPO_URL,
+        code: "agent_consent_required",
+        message:
+          `Refused: agent session detected (${agentDrivenMarkers().slice(0, 3).join(", ")}) and this request `
+          + `carries no dashboard session. Starring writes to the user's own GitHub account, so ask the user `
+          + `directly as a required Yes/No choice — not a soft aside, and no answer is not a No, so re-ask `
+          + `it unchanged while it is open — and only if they say yes run: `
+          + `gh api -X PUT /user/starred/${STAR_REPO}`,
+      }, 403);
+    }
+    const result = await starRepository();
+    return jsonResponse({
+      ...result.status,
+      ok: result.ok,
+      ...(result.code ? { code: result.code } : {}),
+    });
+  }
+
+  if (url.pathname === "/api/update/badge" && req.method === "GET") {
+    const { readUpdateBadge } = await import("../../update/badge");
+    return jsonResponse(readUpdateBadge());
+  }
+
+  return null;
+}

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

@@ -0,0 +1,179 @@
+/**
+ * Dashboard memory-card drain-and-restart (#563).
+ *
+ * Longer than POST /api/stop's short drain: waits up to 60s for active turns,
+ * then respawns. Never runs restoreNativeCodex / stripGrokConfig — this is a
+ * recycle to reclaim RSS, not a teardown.
+ *
+ * Respawn policy (matches real supervisor configs in src/service.ts):
+ * - Supervised child (`OCX_SERVICE=1` + viable service): exit(1) so
+ *   failure-only supervisors (systemd Restart=on-failure, WinSW onfailure,
+ *   Task Scheduler ERRORLEVEL loop) bring the proxy back.
+ * - Otherwise: detached `ocx start --port <live>` (bypasses ensure's
+ *   codexAutoStart gate), mark recycle so exit cleanup keeps injection, exit(0).
+ *   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 (ensure/tray daemons set the marker without a
+ *   real supervisor). Log only a stable errno code — never the raw message
+ *   (paths in ENOENT often include the OS username).
+ */
+import { spawn } from "node:child_process";
+import {
+  drainAndShutdown,
+  getActiveTurnCount,
+  getServerListenPort,
+  isDraining,
+  markRecyclingForExit,
+  setDraining,
+} from "../lifecycle";
+import { isServiceViable } from "../../service";
+import { readRuntimePort } from "../../config";
+
+/** Fixed v1 drain window for the memory-card action (not config-driven). */
+export const MEMORY_DRAIN_RESTART_MS = 60_000;
+
+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>;
+  markRecycling?: () => void;
+  exitProcess?: (code: number) => void;
+  schedule?: (fn: () => void | Promise<void>, ms: number) => void;
+  isDraining?: () => boolean;
+  setDraining?: (value: boolean) => void;
+  getActiveTurnCount?: () => number;
+  listenPort?: () => number | undefined;
+}
+
+let restartIo: SystemRestartIo = {};
+/** Prevents double-scheduling in the 200ms window before drainAndShutdown sets draining. */
+let restartAccepted = false;
+
+/** Test seam — reset between tests. */
+export function setSystemRestartIoForTests(io: SystemRestartIo = {}): void {
+  restartIo = io;
+  restartAccepted = false;
+}
+
+function resolveListenPort(): number | undefined {
+  const live = getServerListenPort();
+  if (live) return live;
+  const runtime = readRuntimePort(process.pid);
+  if (runtime && runtime.port > 0) return runtime.port;
+  return undefined;
+}
+
+function isSupervisedServiceChild(io: SystemRestartIo = {}): boolean {
+  if (process.env.OCX_SERVICE !== "1") return false;
+  // Presence is not enough: stale/missing service assets report installed but will not
+  // respawn after exit(1). Dashboard status/recovery must fall through to detached start.
+  return (io.isServiceViable ?? isServiceViable)();
+}
+
+/** Stable, path-free spawn failure label for logs (never interpolate err.message). */
+function spawnFailureCode(err: unknown): string {
+  if (err && typeof err === "object" && "code" in err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (typeof code === "string" && code.length > 0 && code.length <= 64) return code;
+  }
+  return "spawn_failed";
+}
+
+function spawnDetachedStart(port?: number): 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)));
+  }
+  return new Promise<void>((resolve, reject) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(process.execPath, args, {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env: { ...process.env, OCX_SERVICE: "1" },
+      });
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    let settled = false;
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      fn();
+    };
+    child.once("error", (err) => {
+      finish(() => reject(err));
+    });
+    child.once("spawn", () => {
+      finish(() => {
+        child.unref();
+        resolve();
+      });
+    });
+  });
+}
+
+/**
+ * Accept a drain-and-restart request. Returns immediately; the drain +
+ * respawn runs on a short timer so the HTTP response can flush first.
+ * Idempotent while already draining: returns the accepted shape again.
+ */
+export function acceptSystemRestart(io: SystemRestartIo = restartIo): {
+  accepted: true;
+  alreadyDraining: boolean;
+  activeTurnCount: number;
+  drainTimeoutMs: number;
+} {
+  const alreadyDraining = restartAccepted || (io.isDraining ?? isDraining)();
+  const activeTurnCount = (io.getActiveTurnCount ?? getActiveTurnCount)();
+  const schedule = io.schedule ?? ((fn, ms) => { setTimeout(() => { void fn(); }, ms); });
+
+  if (!alreadyDraining) {
+    restartAccepted = true;
+    // Reject new data-plane traffic immediately (503), before the 200ms response-flush delay.
+    (io.setDraining ?? setDraining)(true);
+    schedule(async () => {
+      const drain = io.drainAndShutdown ?? drainAndShutdown;
+      await drain(undefined, MEMORY_DRAIN_RESTART_MS);
+      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);
+      } catch (err) {
+        console.warn(
+          `⚠️  Drain-and-restart spawn failed (${spawnFailureCode(err)}); exiting without replacement`,
+        );
+        // Listen socket is already stopped; do not markRecycling — no child to inherit fences.
+        // ensure/tray children inherit OCX_SERVICE=1 without an installed service; clear it so
+        // syncCleanup can restore Codex/Grok fences instead of leaving clients pointed at a dead port.
+        delete process.env.OCX_SERVICE;
+        exitProcess(1);
+        return;
+      }
+      (io.markRecycling ?? markRecyclingForExit)();
+      exitProcess(0);
+    }, 200);
+  }
+
+  return {
+    accepted: true,
+    alreadyDraining,
+    activeTurnCount,
+    drainTimeoutMs: MEMORY_DRAIN_RESTART_MS,
+  };
+}

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

@@ -0,0 +1,117 @@
+/**
+ * /api/system/* — service-process runtime/memory introspection (#314 WP3)
+ * and the memory-card drain-and-restart action (#563).
+ *
+ * Rides the standard management gate: every /api/* request already passed
+ * the independent management-auth gate + the origin check before dispatch, so these
+ * routes add no auth of their own. NEVER expose this data on the
+ * unauthenticated /healthz surface.
+ *
+ * The payload is scalar-only (numbers, enum strings, booleans): no paths, no
+ * tokens, no account identifiers. `external` and `arrayBuffers` keep Windows
+ * diagnostics honest when RSS/working-set counters under-report committed
+ * retention. `jscHeap` (bun:jsc heapStats) is useful context, but on Bun 1.3.14
+ * it is not a standalone leak discriminator. `responseState` attributes growth
+ * further: it is the proxy's previous_response_id continuation store, so a
+ * growing responseState.totalBytes under rising observed memory points at
+ * conversation retention rather than the runtime allocator. Spill counts,
+ * payload-byte totals, tombstones, and failure counters remain finite scalars;
+ * response ids, filenames, digests, paths, and payload content never leave the owner.
+ *
+ * `activeTurnCount` / `isDraining` are scalar lifecycle counters for the
+ * dashboard drain-and-restart confirm UX — never request bodies or IDs.
+ */
+import { selectEagerPath } from "../../lib/bun-stream-caps";
+import { getActiveTurnCount, isDraining } from "../lifecycle";
+import { getActiveMemoryWatchdog, observedMemoryCounter } from "../memory-watchdog";
+import { responseStateMetrics } from "../../responses/state";
+import { appOwnedBytesSnapshot } from "../../lib/app-owned-memory";
+import { jsonResponse } from "../auth-cors";
+import { getInspectionCounters } from "../relay";
+import type { ManagementContext } from "./context";
+import { acceptSystemRestart } from "./system-restart";
+
+const ENDPOINT_SAMPLE_LIMIT = 60;
+
+export async function handleSystemRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url, config } = ctx;
+  if (url.pathname === "/api/system/memory" && req.method === "GET") {
+    const usage = process.memoryUsage();
+    let jscHeap: { heapSize: number; heapCapacity: number; objectCount: number } | null = null;
+    try {
+      const { heapStats } = await import("bun:jsc");
+      const stats = heapStats();
+      jscHeap = {
+        heapSize: stats.heapSize,
+        heapCapacity: stats.heapCapacity,
+        objectCount: stats.objectCount,
+      };
+    } catch {
+      /* non-Bun tooling or unavailable introspection — omit the discriminator */
+    }
+	    const watchdogInstance = getActiveMemoryWatchdog();
+	    const observed = observedMemoryCounter({
+	      rss: usage.rss,
+	      external: usage.external,
+	      arrayBuffers: usage.arrayBuffers,
+	    });
+    const watchdog = watchdogInstance
+      ? (() => {
+        const snap = watchdogInstance.snapshot();
+	        return {
+	          warnThresholdBytes: snap.warnThresholdBytes,
+	          lastWarnAt: snap.lastWarnAt,
+	          observedBytes: snap.observedBytes,
+	          observedMetric: snap.observedMetric,
+	          samples: snap.samples.slice(-ENDPOINT_SAMPLE_LIMIT),
+	        };
+      })()
+      : null;
+    const streamMode = config.streamMode ?? "auto";
+    /**
+     * No request-specific rewrite context exists on this route, so report the
+     * effective no-client-rewrite baseline. Individual rewrite requests still
+     * stay on tee even when this baseline says eager.
+     */
+    const eagerRelay = selectEagerPath(process.platform, false, streamMode);
+    return jsonResponse({
+      pid: process.pid,
+      bunVersion: Bun.version,
+      bunRevision: Bun.revision,
+      platform: process.platform,
+      uptimeSeconds: process.uptime(),
+      rss: usage.rss,
+      heapUsed: usage.heapUsed,
+	      heapTotal: usage.heapTotal,
+	      external: usage.external,
+	      arrayBuffers: usage.arrayBuffers,
+	      observedBytes: observed.observedBytes,
+	      observedMetric: observed.observedMetric,
+	      jscHeap,
+      responseState: responseStateMetrics(),
+      appOwnedBytes: appOwnedBytesSnapshot(),
+      inspectionCounters: getInspectionCounters(),
+      streamMode,
+      eagerRelay,
+      watchdog,
+      activeTurnCount: getActiveTurnCount(),
+      isDraining: isDraining(),
+    });
+  }
+
+  if (url.pathname === "/api/system/restart" && req.method === "POST") {
+    // Longer informed drain than /api/stop; does not tear down Codex/Grok injection.
+    const result = acceptSystemRestart();
+    return jsonResponse({
+      success: true,
+      message: result.alreadyDraining
+        ? "Drain already in progress."
+        : "Draining in-flight requests, then restarting.",
+      activeTurnCount: result.activeTurnCount,
+      drainTimeoutMs: result.drainTimeoutMs,
+      alreadyDraining: result.alreadyDraining,
+    }, 202, req, config);
+  }
+
+  return null;
+}