@bitkyc08/opencodex 2.37.0 → 2.39.0-preview.20260901

package/src/integrations/journal.ts

@@ -19,7 +19,18 @@ import { atomicWriteFile } from "../config";
 import { ensureDir, fingerprint, integrationsDir, type OwnershipRecord } from "./ownership";
 import { isIntegrationClientId, type IntegrationClientId } from "./registry";
 
-export type OperationKind = "apply" | "disable" | "refresh" | "restore";
+/**
+ * `overwrite` is deliberately distinct from `apply`. Both write our block, but
+ * only one of them replaced something the user or another tool had put there,
+ * and the rollback list is exactly where that distinction matters.
+ *
+ * This union is re-declared, not imported, in two other places -- the management
+ * route envelope and the GUI adapter -- because neither imports across that
+ * boundary. `tests/integrations-journal.test.ts` asserts the three agree, since
+ * nothing else can: a kind persisted here and missing there renders as a raw
+ * key with no type error anywhere.
+ */
+export type OperationKind = "apply" | "disable" | "refresh" | "restore" | "overwrite";
 
 /**
  * Tagged so "the file did not exist" and "the snapshot was collected" stay

package/src/integrations/registry.ts

@@ -11,7 +11,11 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import {
+  ClientPathError,
   EXPORT_CLIENTS,
+  asideAccountDir,
+  asideConfigPath,
+  asideHomeDir,
   dshConfigPath,
   dshHomeDir,
   gajaeConfigPath,
@@ -52,6 +56,86 @@ export interface IntegrationClientSpec {
   sourcePreservingYaml?: { path: readonly string[] };
   /** Coordinate the complete mutation through a sibling config lock. */
   writerLock?: { suffix: ".lock" };
+  /**
+   * Derive the config path AND the detect directory from one resolution, for a
+   * client whose paths depend on mutable state rather than only env and home.
+   *
+   * Only Aside needs this. Its two paths both come from the account id in
+   * `accounts.json`, so calling `configPath` and `detectDir` in sequence can
+   * straddle an account switch and check one account's install while writing
+   * another's catalog. Reading the id once and deriving both paths from it
+   * removes the window instead of narrowing it.
+   */
+  resolvePaths?: (env?: NodeJS.ProcessEnv, home?: string) => { configPath: string; detectDir: string };
+  /**
+   * Where the client's config WOULD live, for a client whose real path cannot
+   * be resolved yet.
+   *
+   * Only a client with `resolvePaths` needs this, and only because that
+   * resolution can legitimately fail on a machine where the client has never
+   * run. Aside's account id comes from a manifest the app writes at first
+   * launch, so a never-signed-in install has no account directory and no id --
+   * which is "not installed", not "we cannot verify this file".
+   *
+   * The value is a location to SHOW, never a location to write: it names the
+   * account root without an account, so it cannot be mistaken for a real
+   * catalog. `resolveIntegrationPaths` still throws for callers that mutate.
+   */
+  unresolvedPathHint?: (env?: NodeJS.ProcessEnv, home?: string) => string;
+}
+
+/**
+ * The one place that turns a client id into the pair of paths an operation uses.
+ *
+ * A caller that resolves `configPath` and `detectDir` separately is correct for
+ * every client whose paths are a pure function of env and home, and wrong for
+ * one that reads mutable state. Routing both through here lets such a client fix
+ * that for itself without every call site learning why.
+ */
+export function resolveIntegrationPaths(
+  clientId: IntegrationClientId,
+  env: NodeJS.ProcessEnv = process.env,
+  home: string = homedir(),
+): { configPath: string; detectDir: string } {
+  const spec = INTEGRATION_CLIENTS[clientId];
+  if (spec.resolvePaths) return spec.resolvePaths(env, home);
+  return { configPath: spec.configPath(env, home), detectDir: spec.detectDir(env, home) };
+}
+
+/**
+ * The location to name when resolution refused, or `""` when there is none.
+ *
+ * A read-only surface reporting "unresolvable" with an empty path told the user
+ * nothing they could act on, and for Aside it also reported the wrong thing: an
+ * absent account manifest is the ordinary state of an installed-but-never-run
+ * Aside, and the honest answer there is that it is not signed in.
+ *
+ * `""` is a sentinel, not a path: it is what `readIntegrationState` reads to
+ * decide between not-installed and cannot-verify. A config path is never
+ * legitimately empty, and a hint is always an absolute `join` result, so the two
+ * cannot be confused.
+ */
+export function unresolvedPathHintFor(
+  clientId: IntegrationClientId,
+  env: NodeJS.ProcessEnv = process.env,
+  home: string = homedir(),
+): string {
+  const spec = INTEGRATION_CLIENTS[clientId];
+  if (!spec.unresolvedPathHint) return "";
+  try {
+    return spec.unresolvedPathHint(env, home);
+  } catch (error) {
+    /*
+     * Only a path refusal is absorbed. An unqualified catch here would also
+     * swallow a TypeError from a future implementor's typo, an
+     * ERR_INVALID_ARG_TYPE out of `join`, or an EACCES from a resolver that
+     * touches the filesystem -- turning a programming error into a silently
+     * degraded badge. `readIntegrationState` narrows the same way at its own
+     * catch, and this is the matching half.
+     */
+    if (!(error instanceof ClientPathError)) throw error;
+    return "";
+  }
 }
 
 /**
@@ -149,6 +233,34 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
     // is set. Same choice as OMP, whose detect signal is `ompAgentDir`.
     detectDir: (env = process.env, home = homedir()) => primeAgentDir(env, home),
   },
+  aside: {
+    id: "aside",
+    configPath: (env = process.env, home = homedir()) => asideConfigPath(env, home),
+    /*
+     * The ACCOUNT directory, not `~/.aside`. Aside's CLI creates `~/.aside/cli`
+     * for its own update check before any account exists, so the outer directory
+     * is present on a machine that never signed in, and writing a catalog for an
+     * account that does not exist is worse than reporting absent.
+     */
+    detectDir: (env = process.env, home = homedir()) => asideAccountDir(env, home),
+    /*
+     * Both paths from ONE account read. The two resolvers above each consult
+     * the account manifest, so a switch landing between them would let an
+     * operation verify one account's install and then write another's catalog.
+     */
+    resolvePaths: (env = process.env, home = homedir()) => {
+      const detectDir = asideAccountDir(env, home);
+      return { configPath: join(detectDir, "models.json"), detectDir };
+    },
+    /*
+     * The account ROOT, with no account under it. Aside writes `accounts.json`
+     * at first launch, so its absence is the ordinary state of an Aside that has
+     * been installed and never signed into -- and a page that answered "cannot
+     * verify" with an empty path for that case named nothing the user could go
+     * look at.
+     */
+    unresolvedPathHint: (env = process.env, home = homedir()) => join(asideHomeDir(env, home), "u"),
+  },
 };
 
 export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] =

package/src/integrations/state.ts

@@ -19,7 +19,12 @@ import {
   semanticProtectedContributionFingerprint,
   validRefreshablePaths,
 } from "./ownership-policy";
-import { INTEGRATION_CLIENTS, type IntegrationClientId } from "./registry";
+import {
+  INTEGRATION_CLIENTS,
+  resolveIntegrationPaths,
+  unresolvedPathHintFor,
+  type IntegrationClientId,
+} from "./registry";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 
 export type IntegrationState = "absent" | "current" | "stale" | "conflict" | "unsafe";
@@ -238,6 +243,42 @@ export function classifyIntegration(input: {
     return { state: "unsafe", reason: "blocked-container" };
   }
   if (!hasOurFragments(input.parsed, input.contribution)) return { state: "absent" };
+
+  /*
+   * Fragments the desired contribution carries beyond the paths this record names. Both
+   * states appear whenever a client gains a second owned block:
+   *
+   *   - occupied by a value we did not write -> refuse. A refresh merges the WHOLE
+   *     contribution, so without this check applying would replace a block the user wrote
+   *     themselves and report success.
+   *   - empty -> our own block is missing, because the record predates it. Report drift so
+   *     a refresh adds it. Without this the file reads `current` forever and the second
+   *     block never arrives, which is exactly what an older installation hits on upgrade.
+   *
+   * A byte-identical value is ours in substance: adopt it instead of dead-ending a
+   * hand-merged config on a conflict the user can only resolve by deleting our own block.
+   */
+  const recordedPaths = new Set((input.record?.fragmentPaths ?? []).map(path => path.join("\u0000")));
+  let addedPathMissing = false;
+  for (const fragment of input.contribution.fragments) {
+    if (recordedPaths.has(fragment.path.join("\u0000"))) continue;
+    const observed = readPath(input.parsed, fragment.path);
+    if (observed === undefined) {
+      addedPathMissing = true;
+      continue;
+    }
+    const one = (value: unknown): string => fingerprint(canonicalContribution({
+      clientId: (input.clientId ?? input.record?.clientId) as IntegrationClientId,
+      fragments: [{ path: fragment.path, value }],
+    }));
+    if (one(observed) !== one(fragment.value)) return { state: "conflict", reason: "unowned-key" };
+  }
+  /*
+   * No record: whatever occupies our paths is not ours to touch. A byte-identical value
+   * would be ours in substance, but `stale` without a record is not actionable — the writer
+   * reads `createdContainers` off the record to decide what it may prune, so adopting a
+   * hand-merged block needs an apply path that creates one first. Refuse, exactly as before.
+   */
   if (!input.record) return { state: "conflict", reason: "unowned-key" };
   /*
    * A record proves ownership of ONE file. Change HOME, XDG_CONFIG_HOME,
@@ -286,6 +327,12 @@ export function classifyIntegration(input: {
     }
     return { state: "stale" };
   }
+  /*
+   * Checked after everything else that could refuse: an owned fragment that no longer
+   * matches, or a sibling edit in a format that cannot be rewritten safely, still wins.
+   * What is left is a block we own on paper and are merely missing on disk.
+   */
+  if (addedPathMissing) return { state: "stale" };
   const desiredFingerprint = typeof input.record.semanticBlockFingerprint === "string"
     ? fingerprint(semanticContribution(input.contribution))
     : fingerprint(canonicalContribution(input.contribution));
@@ -382,15 +429,30 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   let configPath: string;
   let installed: boolean;
   try {
-    configPath = spec.configPath(input.env, input.home);
-    installed = io.statKind(spec.detectDir(input.env, input.home)) === "dir";
+    // One resolution for both, so a client whose paths come from mutable state
+    // cannot report one account's install beside another account's config path.
+    const paths = resolveIntegrationPaths(input.clientId, input.env, input.home);
+    configPath = paths.configPath;
+    installed = io.statKind(paths.detectDir) === "dir";
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
+    /*
+     * Two different situations reach here and they are not the same answer.
+     *
+     * A relative `OPENCLAW_CONFIG_PATH` is a misconfiguration: there is nothing
+     * to name, and "cannot verify" is correct. Aside's absent account manifest
+     * is the ORDINARY state of an Aside that has been installed and never
+     * signed into, and answering that with a red danger badge and an empty path
+     * told the user their config was suspect when in fact there is no account
+     * yet. A client that can name where its config would go gets `installed:
+     * false` and that location, which reads as "not installed" in the UI.
+     */
+    const hint = unresolvedPathHintFor(input.clientId, input.env, input.home);
     return {
       clientId: input.clientId,
-      state: "unsafe",
+      state: hint ? "absent" : "unsafe",
       installed: false,
-      configPath: "",
+      configPath: hint,
       reason: "unresolvable-path",
       ...retention,
     };

package/src/integrations/writer.ts

@@ -28,7 +28,7 @@ import {
   semanticProtectedContributionFingerprint,
 } from "./ownership-policy";
 import { createdContainerPaths, mergeContribution, removeFragments } from "./merge";
-import { INTEGRATION_CLIENTS, isLoopbackOnly, type IntegrationClientId } from "./registry";
+import { INTEGRATION_CLIENTS, isLoopbackOnly, resolveIntegrationPaths, type IntegrationClientId } from "./registry";
 import { classifyIntegration, exportContextOf } from "./state";
 import type { IntegrationState } from "./state";
 import { serializeDocument, UnserializableValueError } from "./serialize";
@@ -210,8 +210,20 @@ function preflight(input: IntegrationWriteInput) {
    * whole Integrations page because one client is misconfigured.
    */
   let configPath: string;
+  let detectDir: string;
   try {
-    configPath = input.resolvedPaths?.configPath ?? spec.configPath(input.env, input.home);
+    /*
+     * Resolve the PAIR, never one half.
+     *
+     * The coordinated path hands us a frozen pair, but applyIntegration,
+     * refreshIntegration and disableIntegration are public and may be called
+     * without one. Resolving configPath here and detectDir separately later let
+     * an Aside account switch land between the two, so a direct apply could
+     * verify account 1 was installed and then write account 0's catalog.
+     */
+    const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
+    configPath = resolved.configPath;
+    detectDir = resolved.detectDir;
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
     return { failed: refuse(clientId, "unsafe", "unsafe", error.message) } as const;
@@ -248,15 +260,34 @@ function preflight(input: IntegrationWriteInput) {
   const classified = classifyIntegration({
     fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId,
   });
-  return { failed: undefined, store, io, clientId, spec, exportSpec, configPath, before, parsed, contribution, record, classified } as const;
+  return { failed: undefined, store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } as const;
 }
 
-function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: boolean): WriteOutcome {
+/**
+ * How a conflicted document is treated.
+ *
+ * `refuse` is the default and the only behavior that existed: a conflict means
+ * something we did not write occupies our paths, or our own block was edited,
+ * and guessing which one the user meant to keep is how a toggle deletes work.
+ *
+ * `overwrite` is the explicit escape hatch. It is never reached by a plain
+ * apply -- the caller has to ask for it by name -- because the whole value of
+ * the refusal is that it cannot be triggered by accident.
+ */
+type ConflictPolicy = "refuse" | "overwrite";
+
+function applyOrRefreshIntegration(
+  input: IntegrationWriteInput,
+  allowAbsent: boolean,
+  conflictPolicy: ConflictPolicy = "refuse",
+): WriteOutcome {
   const pre = preflight(input);
   if (pre.failed) return pre.failed;
-  const { store, io, clientId, spec, exportSpec, configPath, before, parsed, contribution, record, classified } = pre;
+  const { store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } = pre;
 
-  if (io.statKind(input.resolvedPaths?.detectDir ?? spec.detectDir(input.env, input.home)) !== "dir") {
+  // The detect directory preflight already resolved, so it cannot name a
+  // different account than the config path this operation is about to write.
+  if (io.statKind(detectDir) !== "dir") {
     return refuse(clientId, "not_installed", "absent", `${clientId} is not installed`);
   }
   if (isLoopbackOnly(clientId) && !isLoopbackHostname(input.config.hostname)) {
@@ -264,10 +295,20 @@ function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: bo
       `The generated ${clientId} integration is loopback-only and does not emit the admission header a non-loopback bind requires. Give it loopback access instead, through a tunnel or a local forwarder.`);
   }
   if (classified.state === "conflict") {
-    return refuse(clientId, "conflict", "conflict",
-      classified.reason === "foreign-edit"
-        ? `${configPath} changed after opencodex wrote it`
-        : `${configPath} already contains an opencodex block we did not write`);
+    if (conflictPolicy === "refuse") {
+      return refuse(clientId, "conflict", "conflict",
+        classified.reason === "foreign-edit"
+          ? `${configPath} changed after opencodex wrote it`
+          : `${configPath} already contains an opencodex block we did not write`);
+    }
+    /*
+     * The caller asked for the overwrite explicitly, so the merge below runs
+     * against the document as it stands and our block replaces whatever holds
+     * our paths. Everything that makes it recoverable is shared with apply --
+     * the snapshot, the atomic write, the compare-before-commit recheck and the
+     * journal row all come from the same commit() call -- which is why this is a
+     * policy flag on one code path rather than a second implementation.
+     */
   }
   /*
    * `unsafe` from the classifier means the document is not one we may write
@@ -313,7 +354,22 @@ function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: bo
    */
   const base = classified.state === "stale" && record
     ? removeFragments(parsed, record.fragmentPaths, new Set(record.createdContainers ?? [])).doc
-    : parsed;
+    : classified.state === "conflict" && record
+      /*
+       * A forced overwrite of a `foreign-edit` conflict drops what the previous
+       * record owned for the same reason a stale refresh does: the replacement
+       * record covers the paths we are about to write, so a path the old record
+       * owned and the new one does not would be stranded forever, unremovable by
+       * any later disable.
+       *
+       * With NO record -- an `unowned-key` conflict -- there is nothing to drop and
+       * the merge runs against the user's document directly. That is correct:
+       * createdContainerPaths then attributes every container they already had to
+       * them, so a later disable removes our leaves and leaves their structure
+       * standing.
+       */
+      ? removeFragments(parsed, record.fragmentPaths, new Set(record.createdContainers ?? [])).doc
+      : parsed;
   // Computed against the document as it stands BEFORE the merge: afterwards
   // every container exists and "did we create this?" is unanswerable.
   const created = createdContainerPaths(base, contribution);
@@ -361,7 +417,16 @@ function applyOrRefreshIntegration(input: IntegrationWriteInput, allowAbsent: bo
   const snapshot = store.captureSnapshot(clientId, opId, before);
   const at = new Date(io.now()).toISOString();
   const entry: JournalEntry = {
-    opId, clientId, kind: classified.state === "stale" ? "refresh" : "apply", at, configPath,
+    /*
+     * `overwrite` is its own kind rather than reusing `apply`. The rollback list
+     * is the one place a user goes after a mistake, and "applied" is a lie about
+     * an operation that replaced a block somebody else wrote.
+     */
+    opId, clientId,
+    kind: classified.state === "conflict"
+      ? "overwrite"
+      : classified.state === "stale" ? "refresh" : "apply",
+    at, configPath,
     snapshot, resultFingerprint: fingerprint(text), resultAbsent: false, priorRecord: record,
   };
   const refreshablePaths = refreshablePathsOf(contribution);
@@ -392,6 +457,23 @@ export function applyIntegration(input: IntegrationWriteInput): WriteOutcome {
   return applyOrRefreshIntegration(input, true);
 }
 
+/**
+ * Apply over a conflicted config, replacing whatever holds our paths.
+ *
+ * Separate from `applyIntegration` and never a flag on it: a caller has to name
+ * this function to get the behavior, so no existing call site can acquire it by
+ * passing a default through.
+ *
+ * What it does NOT relax. `unsafe` still refuses -- a blocked container means the
+ * merge would replace a value it cannot reason about, and a snapshot is not a
+ * licence for that. `not_installed` and `non_loopback` still refuse; neither is a
+ * conflict. And a non-conflict state behaves exactly as apply does, so calling
+ * this on a clean file is not a way to skip any other check.
+ */
+export function overwriteIntegration(input: IntegrationWriteInput): WriteOutcome {
+  return applyOrRefreshIntegration(input, true, "overwrite");
+}
+
 /** Refresh an owned stale block, but never create or reconnect an absent one. */
 export function refreshIntegration(input: IntegrationWriteInput): WriteOutcome {
   return applyOrRefreshIntegration(input, false);
@@ -624,10 +706,12 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
   const store = input.store ?? createIntegrationStateStore();
   const io = input.io ?? defaultIntegrationIO(store);
   const spec = INTEGRATION_CLIENTS[input.clientId];
-  const resolvedPaths = {
-    configPath: spec.configPath(env, home),
-    detectDir: spec.detectDir(env, home),
-  };
+  /*
+   * One resolution for both paths. Aside derives them from the account id in
+   * its manifest, so two independent calls could verify one account's install
+   * and then write another account's catalog if a switch landed between them.
+   */
+  const resolvedPaths = resolveIntegrationPaths(input.clientId, env, home);
   return { ...input, env, home, store, io, resolvedPaths };
 }
 
@@ -682,6 +766,13 @@ export function refreshIntegrationCoordinated(
   return coordinatedWrite(input, refreshIntegration, options);
 }
 
+export function overwriteIntegrationCoordinated(
+  input: IntegrationWriteInput,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  return coordinatedWrite(input, overwriteIntegration, options);
+}
+
 export function disableIntegrationCoordinated(
   input: IntegrationWriteInput,
   options?: CoordinatedIntegrationOptions,

package/src/lib/bounded-subprocess.ts

@@ -0,0 +1,36 @@
+export interface KillableSubprocess {
+  exited: Promise<number>;
+  kill(): unknown;
+  unref?(): unknown;
+}
+
+export interface BoundedSubprocessExit {
+  exitCode: number | null;
+  timedOut: boolean;
+}
+
+/** Kill at the deadline and abandon immediately; late exit/rejection remains observed. */
+export function waitForSubprocessExit(
+  proc: KillableSubprocess,
+  timeoutMs: number,
+): Promise<BoundedSubprocessExit> {
+  return new Promise(resolve => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const finish = (result: BoundedSubprocessExit): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      resolve(result);
+    };
+    timer = setTimeout(() => {
+      try { proc.kill(); } catch { /* already exited */ }
+      try { proc.unref?.(); } catch { /* abandonment is still authoritative */ }
+      finish({ exitCode: null, timedOut: true });
+    }, Math.max(1, timeoutMs));
+    void proc.exited.then(
+      exitCode => finish({ exitCode, timedOut: false }),
+      () => finish({ exitCode: null, timedOut: false }),
+    );
+  });
+}

package/src/lib/process-control.ts

@@ -29,6 +29,24 @@ export interface GracefulStopIo {
   waitExit?: (pid: number, timeoutMs: number) => boolean;
   env?: Record<string, string | undefined>;
   exitTimeoutMs?: number;
+  /**
+   * Nonce of the pending-teardown receipt this caller claimed.
+   *
+   * `ocx stop` sets it because it restores shared client config itself, only after
+   * proving a stopped Task Scheduler did not respawn the proxy (#3008). The nonce is what
+   * makes the deferral an owned obligation rather than a flag anyone can set: the proxy
+   * honours it only when it names the receipt actually on disk. Direct callers omit it
+   * and keep the self-contained behaviour.
+   */
+  deferSharedTeardownNonce?: string;
+  /**
+   * Endpoint the caller already resolved for this pid.
+   *
+   * `ocx stop` records this same snapshot in its pending-teardown receipt. Re-reading the
+   * runtime file here could pick up a different one, which would make the receipt name an
+   * endpoint the stop never contacted — and recovery probes exactly that endpoint.
+   */
+  runtimeEndpoint?: { hostname: string; port: number };
 }
 
 /**
@@ -67,7 +85,7 @@ export class ProxyOwnershipRefusedError extends Error {}
  */
 export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}): Promise<GracefulStopResult> {
   const readRuntime = io.readRuntime ?? readRuntimePort;
-  const runtime = readRuntime(pid);
+  const runtime = io.runtimeEndpoint ?? readRuntime(pid);
   if (!runtime?.port) return false;
   const env = io.env ?? process.env;
   const headers: Record<string, string> = {};
@@ -75,7 +93,14 @@ export async function stopProxyGracefully(pid: number, io: GracefulStopIo = {}):
   if (token) headers["x-opencodex-api-key"] = token;
   const fetchFn = io.fetchFn ?? fetch;
   try {
-    const res = await fetchFn(`http://${gracefulStopHost(runtime.hostname)}:${runtime.port}/api/stop`, {
+    // `ocx stop` asks the proxy NOT to restore shared client config: it does that itself,
+    // after verifying a stopped Task Scheduler did not respawn the proxy (#3008). Letting
+    // the child do it means a survivor found seconds later has already lost its config.
+    const stopUrl = `http://${gracefulStopHost(runtime.hostname)}:${runtime.port}/api/stop`
+      + (io.deferSharedTeardownNonce
+        ? `?deferSharedTeardown=1&teardownNonce=${encodeURIComponent(io.deferSharedTeardownNonce)}`
+        : "");
+    const res = await fetchFn(stopUrl, {
       method: "POST",
       headers,
       // Hung proxies with many CLOSE_WAIT clients can be slow to accept; give them
@@ -107,10 +132,10 @@ function drainDeadlineMs(): number {
 }
 
 /** Graceful-first stop: management-API drain, then the platform kill ladder. */
-export async function stopProxy(pid: number): Promise<void> {
+export async function stopProxy(pid: number, io: GracefulStopIo = {}): Promise<void> {
   if (!isProcessAlive(pid)) return;
-  const runtime = readRuntimePort(pid);
-  const graceful = await stopProxyGracefully(pid);
+  const runtime = io.runtimeEndpoint ?? readRuntimePort(pid);
+  const graceful = await stopProxyGracefully(pid, io);
   if (graceful === "refused") {
     // The proxy refused on purpose (foreign service owns it). Forcing would strip shared
     // config while that service keeps the proxy alive.

package/src/lib/state-store-registrations.ts

@@ -9,6 +9,7 @@ import { reconcileProviderFetchWarnings } from "../codex/catalog/provider-fetch"
 import { reconcileModelCacheGeneration } from "../codex/model-cache";
 import { reconcilePoolRotationState } from "../codex/pool-rotation";
 import { reconcileCodexQuotaAccounts } from "../codex/quota";
+import { reconcileQuotaRecovery, sweepExpiredQuotaRecovery } from "../codex/quota-401-recovery";
 import {
   listLiveCodexAccountIds,
   reconcileCodexRoutingHealth,
@@ -84,6 +85,13 @@ export const STATE_STORE_REGISTRATIONS = [
   },
   { name: "anthropic-routing-health", sweepExpired: sweepExpiredAnthropicRoutingHealth },
   { name: "xai-refresh-verdicts", sweepExpired: sweepExpiredXaiPermanentFailureVerdicts },
+  {
+    name: "codex-quota-401-recovery",
+    // Only backoff windows and abandoned leases expire. A spent fence is durable: expiring
+    // it would grant the same credential lineage a second refresh (#3019).
+    sweepExpired: sweepExpiredQuotaRecovery,
+    reconcileGeneration: context => reconcileQuotaRecovery(context.codexAccountIds),
+  },
   {
     name: "responses-continuation",
     sweepExpired: sweepExpiredResponseStates,

package/src/lib/strict-semver.ts

@@ -0,0 +1,47 @@
+// Core and build metadata are unambiguous and stay inline. The prerelease section does not:
+// the semver.org pattern for one identifier is
+//   0 | [1-9]\d* | [0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*
+// whose three alternatives overlap, and wrapping that in `(?:\.…)*` gives a regex engine an
+// exponential number of ways to split the same string. CodeQL flagged it (`js/redos`) and the
+// cost is real, not theoretical: `0.0.0-0.` followed by repetitions of `--.` took **522ms for a
+// single 125-character input** — inside the 128-char ceiling this module already enforced, and
+// inside the 96-char one its only caller uses. A length cap does not fix superlinear blowup; it
+// only decides where the curve is sampled.
+//
+// So the prerelease section is matched with one non-backtracking pass and its identifiers are
+// validated individually. Each identifier is checked by an anchored regex with no repetition of
+// an alternation, which is linear in the identifier's length.
+const STRICT_SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+
+const NUMERIC_IDENTIFIER_RE = /^(?:0|[1-9]\d*)$/;
+const ALPHANUMERIC_IDENTIFIER_RE = /^[0-9A-Za-z-]+$/;
+
+/**
+ * A prerelease identifier is either a numeric identifier with no leading zero, or an
+ * alphanumeric one that contains at least one non-digit. Empty identifiers are invalid,
+ * which is what rejects a trailing or doubled dot.
+ */
+function isPrereleaseIdentifier(part: string): boolean {
+  if (part.length === 0) return false;
+  if (NUMERIC_IDENTIFIER_RE.test(part)) return true;
+  return ALPHANUMERIC_IDENTIFIER_RE.test(part) && !/^\d+$/.test(part);
+}
+
+export interface StrictSemver {
+  readonly raw: string;
+  readonly core: readonly [bigint, bigint, bigint];
+  readonly prerelease: readonly (bigint | string)[];
+}
+
+export function parseStrictSemver(value: unknown, maxLength = 128): StrictSemver | null {
+  if (typeof value !== "string" || value.length === 0 || value.length > maxLength) return null;
+  const match = STRICT_SEMVER_RE.exec(value);
+  if (!match) return null;
+  const prereleaseParts = match[4] === undefined ? [] : match[4].split(".");
+  if (!prereleaseParts.every(isPrereleaseIdentifier)) return null;
+  return Object.freeze({
+    raw: value,
+    core: Object.freeze([BigInt(match[1]!), BigInt(match[2]!), BigInt(match[3]!)]) as readonly [bigint, bigint, bigint],
+    prerelease: Object.freeze(prereleaseParts.map(part => /^\d+$/.test(part) ? BigInt(part) : part)),
+  });
+}