@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/server/management/routing-profile-routes.ts

@@ -1,12 +1,20 @@
 /**
  * Routing-profile management API (RI-04).
  *
- * - `GET  /api/routing-profiles` - normalized profiles with revisions
- * - `POST /api/routing-profiles/dry-run` - deterministic dry-run evaluation
+ * - `GET    /api/routing-profiles` - normalized profiles with revisions
+ * - `PUT    /api/routing-profiles` - create or replace one validated profile
+ * - `DELETE /api/routing-profiles?id=<id>` - remove one profile
+ * - `POST   /api/routing-profiles/dry-run` - deterministic dry-run evaluation
  *   (never dispatches an upstream request)
  */
 
-import { listRoutingProfileIds, getRoutingProfile, policyPublicModelId } from "../../routing/profile";
+import {
+  getRoutingProfile,
+  listRoutingProfileIds,
+  normalizeRoutingProfile,
+  policyPublicModelId,
+  routingProfileIssues,
+} from "../../routing/profile";
 import { evaluatePolicyProfile, type PolicyCandidateEvidence, type PolicyRequestEvidence } from "../../routing/evaluator";
 import { candidateCapabilityEvidence } from "../../routing/capability";
 import { policyCandidateHealthEvidence } from "../../routing/health";
@@ -16,17 +24,20 @@ import { providerCodexAccountMode } from "../../providers/registry";
 import { getEffectiveActiveCodexAccountId } from "../../codex/routing";
 import { getAccountSet } from "../../oauth/store";
 import { OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
+import { saveConfigPreservingClaudeCode } from "../../config";
+import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
 import { isPlainRecord } from "./shared";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 import { jsonResponse } from "../auth-cors";
 import type { ManagementContext } from "./context";
-import type { OcxConfig } from "../../types";
+import type { OcxConfig, OcxRoutingProfileConfig } from "../../types";
 
 function profileDto(config: Parameters<typeof getRoutingProfile>[0], id: string): Record<string, unknown> | null {
   const profile = getRoutingProfile(config, id);
   if (!profile) return null;
   return {
     id,
+    alias: profile.alias,
     model: policyPublicModelId(id, profile),
     revision: profile.revision,
     candidates: profile.candidates,
@@ -131,8 +142,112 @@ function assembleCandidateEvidence(
   }));
 }
 
+function storedProfile(
+  id: string,
+  raw: OcxRoutingProfileConfig,
+): OcxRoutingProfileConfig {
+  const normalized = normalizeRoutingProfile(id, raw);
+  const {
+    id: _id,
+    revision: _revision,
+    alias,
+    ...profile
+  } = normalized;
+  return alias === null ? profile : { ...profile, alias };
+}
+
+/**
+ * Rewrite config references from one public model id to another (alias change
+ * on update). Mirrors the /api/combos migration: model-valued config that
+ * still names the old alias must follow it, or requests fall through to
+ * ordinary routing and send the obsolete alias upstream.
+ */
+/**
+ * Detect a modelMap key collision that the alias migration would silently
+ * resolve by dropping one mapping: the map already contains the new public
+ * model as a key with a different target than the old-alias key's target.
+ */
+function modelMapMigrationCollision(
+  config: OcxConfig,
+  oldPublicModel: string,
+  newPublicModel: string,
+): string | null {
+  const map = config.claudeCode?.modelMap;
+  if (!map) return null;
+  if (oldPublicModel === newPublicModel) return null;
+  const oldTarget = map[oldPublicModel];
+  if (oldTarget === undefined) return null;
+  const newTarget = map[newPublicModel];
+  if (newTarget === undefined) return null;
+  if (oldTarget === newTarget) return null;
+  return `modelMap already maps \"${newPublicModel}\" to \"${newTarget}\"; renaming \"${oldPublicModel}\" (→ \"${newTarget}\") would drop one mapping. Resolve the conflict and retry.`;
+}
+
+/**
+ * Rewrite config references from one public model id to another (alias change
+ * on update). Mirrors the /api/combos migration: model-valued config that
+ * still names the old alias must follow it, or requests fall through to
+ * ordinary routing and send the obsolete alias upstream.
+ */
+function migrateProfileModelReferences(
+  config: OcxConfig,
+  oldPublicModel: string,
+  newPublicModel: string,
+): boolean {
+  if (oldPublicModel === newPublicModel) return false;
+  const migrateReference = (model: string): string => (
+    model === oldPublicModel ? newPublicModel : model
+  );
+  let shouldSyncClaudeAgentDefs = false;
+  const migrateAgentReference = (model: string): string => {
+    const migrated = migrateReference(model);
+    if (migrated !== model) shouldSyncClaudeAgentDefs = true;
+    return migrated;
+  };
+  const migrateReferences = (models: string[]): string[] => [
+    ...new Set(models.map(migrateReference)),
+  ];
+  if (config.disabledModels) {
+    config.disabledModels = migrateReferences(config.disabledModels);
+  }
+  if (config.subagentModels) {
+    config.subagentModels = [...new Set(config.subagentModels.map(migrateAgentReference))];
+  }
+  if (config.subagentModelFallback) {
+    config.subagentModelFallback = [...new Set(config.subagentModelFallback.map(migrateAgentReference))];
+  }
+  if (config.injectionModel && config.injectionModel === oldPublicModel) {
+    config.injectionModel = newPublicModel;
+  }
+  if (config.shadowCallIntercept?.model && config.shadowCallIntercept.model === oldPublicModel) {
+    config.shadowCallIntercept = { ...config.shadowCallIntercept, model: newPublicModel };
+  }
+  if (config.claudeCode) {
+    const claudeCode = { ...config.claudeCode };
+    for (const field of ["model", "smallFastModel"] as const) {
+      if (claudeCode[field]) claudeCode[field] = migrateAgentReference(claudeCode[field]);
+    }
+    if (claudeCode.tierModels) {
+      claudeCode.tierModels = Object.fromEntries(
+        Object.entries(claudeCode.tierModels).map(([tier, model]) => [tier, migrateAgentReference(model)]),
+      );
+    }
+    if (claudeCode.modelMap) {
+      // Keys are the inbound ids matched for reroute (src/claude/inbound.ts);
+      // an old-alias key must follow the rename or that request stops intercepting.
+      claudeCode.modelMap = Object.fromEntries(
+        Object.entries(claudeCode.modelMap).map(([source, model]) => [
+          migrateAgentReference(source),
+          migrateAgentReference(model),
+        ]),
+      );
+    }
+    config.claudeCode = claudeCode;
+  }
+  return shouldSyncClaudeAgentDefs;
+}
 export async function handleRoutingProfileRoutes(ctx: ManagementContext): Promise<Response | null> {
-  const { req, url, config } = ctx;
+  const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
 
   if (url.pathname === "/api/routing-profiles" && req.method === "GET") {
     const profiles = listRoutingProfileIds(config).map(id => profileDto(config, id)).filter(
@@ -141,6 +256,120 @@ export async function handleRoutingProfileRoutes(ctx: ManagementContext): Promis
     return jsonResponse({ profiles }, 200, req, config);
   }
 
+  if (url.pathname === "/api/routing-profiles" && req.method === "PUT") {
+    let rawBody: unknown;
+    try {
+      rawBody = await readManagementJsonBody(req);
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      return jsonResponse({ error: "invalid JSON body" }, 400, req, config);
+    }
+    if (!isPlainRecord(rawBody)) {
+      return jsonResponse({ error: "request body must be an object" }, 400, req, config);
+    }
+    const body = rawBody as Record<string, unknown>;
+    const id = typeof body.id === "string" ? body.id.trim() : "";
+    if (!id) {
+      return jsonResponse({ error: { code: "missing_profile_id", message: "id is required" } }, 400, req, config);
+    }
+    const mode = body.mode === "create" || body.mode === "update" ? body.mode : null;
+    if (!mode) {
+      return jsonResponse({ error: { code: "invalid_profile_mode", message: "mode must be create or update" } }, 400, req, config);
+    }
+    const exists = Object.hasOwn(config.routingProfiles ?? {}, id);
+    if (mode === "create" && exists) {
+      return jsonResponse({ error: { code: "profile_exists", message: `routing profile already exists: ${id}` } }, 409, req, config);
+    }
+    if (mode === "update" && !exists) {
+      return jsonResponse({ error: { code: "unknown_profile", message: `unknown routing profile: ${id}` } }, 404, req, config);
+    }
+    if (mode === "update") {
+      const expectedRevision = typeof body.expectedRevision === "string" && body.expectedRevision.trim()
+        ? body.expectedRevision.trim()
+        : undefined;
+      if (expectedRevision) {
+        const current = getRoutingProfile(config, id);
+        if (current && current.revision !== expectedRevision) {
+          return jsonResponse({
+            error: {
+              code: "profile_revision_conflict",
+              message: `routing profile ${id} changed since it was loaded; reload and retry`,
+              currentRevision: current.revision,
+            },
+          }, 409, req, config);
+        }
+      }
+    }
+    const issues = routingProfileIssues(id, body.profile, config, { excludeProfileId: id });
+    if (issues.length > 0) {
+      return jsonResponse({
+        error: {
+          code: "invalid_profile",
+          message: issues[0]!.message,
+          issues,
+        },
+      }, 400, req, config);
+    }
+
+    const previousProfile = mode === "update" ? getRoutingProfile(config, id) : undefined;
+    if (mode === "update" && previousProfile) {
+      const oldPublicModel = policyPublicModelId(id, previousProfile);
+      const newProfile = normalizeRoutingProfile(id, body.profile as OcxRoutingProfileConfig);
+      const newPublicModel = policyPublicModelId(id, newProfile);
+      const collision = modelMapMigrationCollision(config, oldPublicModel, newPublicModel);
+      if (collision) {
+        return jsonResponse({
+          error: { code: "alias_reference_conflict", message: collision },
+        }, 409, req, config);
+      }
+    }
+    const nextProfiles = { ...(config.routingProfiles ?? {}) };
+    nextProfiles[id] = storedProfile(id, body.profile as OcxRoutingProfileConfig);
+    config.routingProfiles = nextProfiles;
+    // An alias change on update renames the public model id; rewrite config
+    // references (disabledModels, subagentModels, injectionModel,
+    // shadowCallIntercept, claudeCode) so they follow the new alias.
+    let shouldSyncClaudeAgentDefs = false;
+    if (previousProfile) {
+      const oldPublicModel = policyPublicModelId(id, previousProfile);
+      const newPublicModel = policyPublicModelId(id, getRoutingProfile(config, id)!);
+      shouldSyncClaudeAgentDefs = migrateProfileModelReferences(config, oldPublicModel, newPublicModel);
+    }
+    const save = deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode;
+    save(config);
+    reconcileLiveStateStores();
+    const catalogRefresh = await convergeCodexCatalog();
+    if (shouldSyncClaudeAgentDefs) await syncClaudeAgentDefsBestEffort();
+    const profile = profileDto(config, id)!;
+    return jsonResponse({
+      success: true,
+      id,
+      model: profile.model,
+      profile,
+      catalogRefresh,
+    }, 200, req, config);
+  }
+
+  if (url.pathname === "/api/routing-profiles" && req.method === "DELETE") {
+    const id = url.searchParams.get("id")?.trim();
+    if (!id) {
+      return jsonResponse({ error: "id query param is required" }, 400, req, config);
+    }
+    if (!Object.hasOwn(config.routingProfiles ?? {}, id)) {
+      return jsonResponse({ error: "unknown routing profile" }, 404, req, config);
+    }
+
+    const nextProfiles = { ...(config.routingProfiles ?? {}) };
+    delete nextProfiles[id];
+    if (Object.keys(nextProfiles).length > 0) config.routingProfiles = nextProfiles;
+    else delete config.routingProfiles;
+    const saveConfigPreservingClaudeCodeSafe = deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode;
+    saveConfigPreservingClaudeCodeSafe(config);
+    reconcileLiveStateStores();
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ success: true, id, catalogRefresh }, 200, req, config);
+  }
+
   if (url.pathname === "/api/routing-profiles/dry-run" && req.method === "POST") {
     let rawBody: unknown;
     try { rawBody = await readManagementJsonBody(req); } catch (error) {

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

@@ -17,8 +17,8 @@
  * - 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
+ *   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).
  */
 import { spawn } from "node:child_process";
@@ -35,13 +35,13 @@ import {
 import { isServiceViable } from "../../service";
 import { readRuntimePort } from "../../config";
 import { withProcessRuntimeProvenance } from "../../lib/bun-runtime";
+import {
+  MEMORY_DRAIN_RESTART_MS,
+  REPLACEMENT_READY_TIMEOUT_MS,
+} from "../../lib/system-restart-contract";
 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 { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../../lib/system-restart-contract";
 export const DEADLINE_LISTENER_STOP_TIMEOUT_MS = 5_000;
 const REPLACEMENT_READY_POLL_MS = 150;
 
@@ -223,11 +223,13 @@ function spawnDetachedStart(
   return new Promise<void>((resolve, reject) => {
     let child: ReturnType<typeof spawn>;
     try {
+      const env: NodeJS.ProcessEnv = { ...process.env };
+      delete env.OCX_SERVICE;
       child = spawn(process.execPath, args, {
         detached: true,
         stdio: "ignore",
         windowsHide: true,
-        env: withProcessRuntimeProvenance({ ...process.env, OCX_SERVICE: "1" }),
+        env: withProcessRuntimeProvenance(env),
       });
     } catch (err) {
       reject(err);
@@ -411,8 +413,8 @@ export function acceptSystemRestart(io: SystemRestartIo = restartIo): {
           `⚠️  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.
+        // No replacement inherited the routing. Clear a stale service marker so
+        // this unsupervised parent restores clients after the failed handoff.
         delete process.env.OCX_SERVICE;
         exitProcess(1);
         return;

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

@@ -27,6 +27,10 @@ import { getActiveTurnCount, isDraining } from "../lifecycle";
 import { getActiveMemoryWatchdog, observedMemoryCounter } from "../memory-watchdog";
 import { responseStateMetrics } from "../../responses/state";
 import { appOwnedBytesSnapshot } from "../../lib/app-owned-memory";
+import {
+  SYSTEM_RESTART_EXPECTED_PID_HEADER,
+  parseExpectedSystemRestartPid,
+} from "../../lib/system-restart-contract";
 import { jsonResponse } from "../auth-cors";
 import { getInspectionCounters } from "../relay";
 import type { ManagementContext } from "./context";
@@ -104,6 +108,22 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
   }
 
   if (url.pathname === "/api/system/restart" && req.method === "POST") {
+    const expectedPid = parseExpectedSystemRestartPid(
+      req.headers.get(SYSTEM_RESTART_EXPECTED_PID_HEADER),
+    );
+    if (expectedPid.kind === "invalid") {
+      return jsonResponse({
+        success: false,
+        error: "Invalid restart target identity.",
+      }, 400, req, config);
+    }
+    if (expectedPid.kind === "present" && expectedPid.pid !== process.pid) {
+      return jsonResponse({
+        success: false,
+        error: "Restart target identity changed.",
+      }, 409, req, config);
+    }
+
     // Longer informed drain than /api/stop; does not tear down Codex/Grok injection.
     const result = acceptSystemRestart();
     return jsonResponse({

package/src/server/management-auth.ts

@@ -13,6 +13,14 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { adminApiTokenFilePath } from "../lib/admin-secrets";
+import {
+  SYSTEM_RESTART_CAPABILITY_HEADER,
+  SYSTEM_RESTART_EXPECTED_PID_HEADER,
+  SYSTEM_RESTART_NONCE_HEADER,
+  SYSTEM_RESTART_PATH,
+  parseExpectedSystemRestartPid,
+  verifySystemRestartCapability,
+} from "../lib/system-restart-contract";
 import { forgetEphemeralSecretPath, forgetHardenedSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
 import type { OcxConfig } from "../types";
 import {
@@ -245,20 +253,58 @@ export function issueGuiSession(
  * 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.
+ * `system-restart-capability` is a process-scoped HMAC accepted only for the exact
+ * restart route and bound to the current process PID and listening port.
  */
-export type ManagementPrincipal = "admin-token" | "gui-session";
+export type ManagementPrincipal = "admin-token" | "gui-session" | "system-restart-capability";
+
+export interface LocalManagementAuthContext {
+  attestationSecret: string;
+  pid: number;
+  port: number;
+}
+
+function hasSystemRestartCapability(
+  req: Request,
+  local: LocalManagementAuthContext | undefined,
+): boolean {
+  if (!local || req.method !== "POST") return false;
+  let path: string;
+  try {
+    path = new URL(req.url).pathname;
+  } catch {
+    return false;
+  }
+  if (path !== SYSTEM_RESTART_PATH) return false;
+  const expectedPid = parseExpectedSystemRestartPid(
+    req.headers.get(SYSTEM_RESTART_EXPECTED_PID_HEADER),
+  );
+  if (expectedPid.kind !== "present" || expectedPid.pid !== local.pid) return false;
+  return verifySystemRestartCapability(
+    local.attestationSecret,
+    req.headers.get(SYSTEM_RESTART_NONCE_HEADER),
+    req.method,
+    path,
+    local.pid,
+    local.port,
+    req.headers.get(SYSTEM_RESTART_CAPABILITY_HEADER),
+  );
+}
 
 /**
  * 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.
+ * keeps its `Response | null` contract. Browser and admin principals are derived
+ * from the same session table and CSRF comparison the gate uses; the restart
+ * principal is derived from the same process-scoped capability check.
  */
 export function managementPrincipal(
   req: Request,
   state: ManagementAuthState,
   config?: OcxConfig,
+  local?: LocalManagementAuthContext,
 ): ManagementPrincipal | null {
+  if (hasSystemRestartCapability(req, local)) return "system-restart-capability";
   if (!state.available) return null;
   const actual = req.headers.get("x-opencodex-api-key")?.trim()
     || req.headers.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
@@ -273,7 +319,9 @@ export function requireManagementAuth(
   req: Request,
   state: ManagementAuthState,
   config?: OcxConfig,
+  local?: LocalManagementAuthContext,
 ): Response | null {
+  if (hasSystemRestartCapability(req, local)) return null;
   if (!state.available) {
     return Response.json({
       error: "management API unavailable",

package/src/server/ports.ts

@@ -57,6 +57,16 @@ export type FindAvailablePortOptions = {
    * update restart cannot hop to a random ephemeral listener (PR #152 gap).
    */
   allowEphemeralFallback?: boolean;
+  /**
+   * A port this selection must never return, even when it is free (#1102).
+   *
+   * The unauthenticated loopback listener binds a fixed port from config. If the public
+   * listener took that port first — via an explicit `--port`, a `config.port` of 0, or the
+   * ephemeral fallback happening to land on it — the loopback bind would then fail with
+   * EADDRINUSE, and the startup transaction would roll back a public listener that had
+   * nothing wrong with it. Excluding the port here fails the right thing at the right time.
+   */
+  reservedPort?: number;
 };
 
 export class PortUnavailableError extends Error {
@@ -75,6 +85,12 @@ export async function findAvailablePort(
 ): Promise<number> {
   const preferRetryMs = opts.preferRetryMs ?? 0;
   const allowEphemeral = opts.allowEphemeralFallback !== false;
+  const reserved = opts.reservedPort;
+  // An explicit preference for the reserved port is a configuration mistake, not a busy
+  // socket: retrying or hopping would hide it. Refuse before probing anything.
+  if (reserved !== undefined && preferredPort === reserved) {
+    throw new PortUnavailableError(preferredPort, hostname);
+  }
   // Port 0 asks the OS to select an ephemeral port. Resolve it to that concrete
   // port here so callers never persist or advertise an unusable `:0` endpoint.
   if (preferredPort > 0 && preferRetryMs > 0) {
@@ -92,7 +108,31 @@ export async function findAvailablePort(
     throw new PortUnavailableError(preferredPort, hostname);
   }
 
-  return await new Promise((resolve, reject) => {
+  // Bounded, not recursive. The OS can hand back the reserved port, and a redraw practically
+  // always differs — but "practically always" is not a termination argument, and an unbounded
+  // async recursion has no way to stop if the assumption is ever wrong.
+  for (let attempt = 0; attempt < EPHEMERAL_REDRAW_LIMIT; attempt += 1) {
+    const port = await allocateEphemeralPort(hostname);
+    if (port !== reserved) return port;
+  }
+  throw new Error("failed to allocate an available port");
+}
+
+/** How many times an ephemeral draw may come back reserved before we give up. */
+const EPHEMERAL_REDRAW_LIMIT = 8;
+
+/** Test seam: replace the OS ephemeral allocator so the redraw path is reachable. */
+let ephemeralAllocator: ((hostname: string) => Promise<number>) | null = null;
+
+export function setEphemeralPortAllocatorForTests(
+  allocator: ((hostname: string) => Promise<number>) | null,
+): void {
+  ephemeralAllocator = allocator;
+}
+
+async function allocateEphemeralPort(hostname: string): Promise<number> {
+  if (ephemeralAllocator) return ephemeralAllocator(hostname);
+  return await new Promise<number>((resolve, reject) => {
     const server = createServer();
     server.once("error", reject);
     server.once("listening", () => {