feat(windows): count atomic-replace retries so the envelope can be argued from evidence

Both plan audits wanted the 75ms retry envelope widened. Neither could show it
failing in the field, and one explicitly declined to raise its severity for
exactly that reason. Counting is the honest next step: if these stay at zero
across a release the envelope is fine, and if they do not, the change cites
numbers.

Counters live beside the retry loop, keyed by which publisher retried, with
separate retried and exhausted totals. Exposed as
GET /api/system/windows-replace-retries -- a sibling of /api/system/memory
rather than a field on it, because that payload is memory-shaped and appending
filesystem counters would make both harder to consume.

The publisher label is a closed union (ReplacePublisher), and that union is the
privacy enforcement, not privacy:scan. The scanner reads file text
(scripts/privacy-scan.ts:187) and cannot tell that a runtime string came from a
path -- a path could carry a username. A closed union makes the same mistake a
typecheck failure instead, which the new test pins with @ts-expect-error.

Scope note, stated because the plan originally overreached here: these counters
are process-local. Asserting they stay zero across the Windows suite would need
a finalizer aggregating many short-lived sharded processes, which does not
exist. Evidence comes from local runs and voluntary bug reports.

tests/system-routes.test.ts is new; handleSystemRoutes coverage previously lived
scattered in memory-watchdog.test.ts and codex-restart-route.test.ts.

Verification: bun test tests/system-routes.test.ts (9 pass), bun run typecheck
clean, bun run privacy:scan passed.

Author: lidge-jun

src/server/management/system-routes.ts

@@ -27,6 +27,7 @@ import { getActiveTurnCount, isDraining } from "../lifecycle";
 import { getActiveMemoryWatchdog, observedMemoryCounter } from "../memory-watchdog";
 import { responseStateMetrics } from "../../responses/state";
 import { appOwnedBytesSnapshot } from "../../lib/app-owned-memory";
+import { readWindowsReplaceRetryCounters } from "../../lib/windows-atomic-replace";
 import {
   SYSTEM_RESTART_EXPECTED_PID_HEADER,
   parseExpectedSystemRestartPid,
@@ -115,6 +116,20 @@ export async function handleSystemRoutes(ctx: ManagementContext): Promise<Respon
     });
   }
 
+    /**
+   * Windows atomic-replace retry counters.
+   *
+   * A sibling route rather than a field on /api/system/memory: that payload is
+   * memory-shaped, and appending unrelated filesystem counters to it makes both
+   * harder to consume.
+   *
+   * Keys are a closed union of publisher labels (ReplacePublisher), never a
+   * path — a path could carry a username. The type is what enforces that; a
+   * text scan cannot see a runtime value.
+   */
+  if (url.pathname === "/api/system/windows-replace-retries" && req.method === "GET") {
+    return jsonResponse({ counters: readWindowsReplaceRetryCounters() });
+  }
   if (url.pathname === "/api/system/restart" && req.method === "POST") {
     const expectedPid = parseExpectedSystemRestartPid(
       req.headers.get(SYSTEM_RESTART_EXPECTED_PID_HEADER),

tests/system-routes.test.ts

@@ -0,0 +1,131 @@
+/**
+ * GET /api/system/windows-replace-retries.
+ *
+ * The Windows atomic replace retries EBUSY/EPERM/EACCES twice, about 75ms of
+ * tolerance in total. Both plan audits wanted that envelope widened; neither
+ * could show it failing in the field. These counters exist to answer that with
+ * evidence instead of intuition, so the endpoint's whole job is to report
+ * whether the retry path ever fires.
+ *
+ * Scope note: the counters are process-local. A CI assertion that they stay
+ * zero across the suite would need a finalizer that aggregates many short-lived
+ * sharded processes, which does not exist. This file covers the route.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { handleManagementAPI } from "../src/server/management-api";
+import {
+  readWindowsReplaceRetryCounters,
+  renameAtomicFile,
+  resetWindowsReplaceRetryCountersForTests,
+  type ReplacePublisher,
+} from "../src/lib/windows-atomic-replace";
+import type { OcxConfig } from "../src/types";
+
+function config(): OcxConfig {
+  return {
+    port: 10100,
+    defaultProvider: "openai",
+    providers: {
+      openai: {
+        adapter: "openai-chat",
+        baseUrl: "https://api.example.test/v1",
+        apiKey: "sk-secret-value",
+        defaultModel: "gpt-test",
+      },
+    },
+  };
+}
+
+/** A rename that fails with a Windows sharing violation `failures` times, then succeeds. */
+function flakyIo(failures: number, code = "EBUSY") {
+  let seen = 0;
+  return {
+    platform: "win32" as NodeJS.Platform,
+    rename: () => {
+      if (seen++ < failures) {
+        const error = new Error(code) as NodeJS.ErrnoException;
+        error.code = code;
+        throw error;
+      }
+    },
+    sleep: () => {},
+  };
+}
+
+afterEach(() => {
+  resetWindowsReplaceRetryCountersForTests();
+});
+
+describe("windows replace retry counters", () => {
+  test("a clean replace records nothing", () => {
+    renameAtomicFile("a", "b", flakyIo(0), "config");
+    expect(readWindowsReplaceRetryCounters()).toEqual({});
+  });
+
+  test("a transient sharing violation is counted and then succeeds", () => {
+    renameAtomicFile("a", "b", flakyIo(1), "prompt-journal");
+    expect(readWindowsReplaceRetryCounters()).toEqual({
+      "prompt-journal": { retried: 1, exhausted: 0 },
+    });
+  });
+
+  test("exhausting the envelope rethrows and is counted separately", () => {
+    expect(() => renameAtomicFile("a", "b", flakyIo(99), "config-ownership")).toThrow();
+    // Two retries then the throw: the envelope is 2, not unbounded.
+    expect(readWindowsReplaceRetryCounters()).toEqual({
+      "config-ownership": { retried: 2, exhausted: 1 },
+    });
+  });
+
+  test("a non-Windows error is not retried and not counted", () => {
+    const io = { ...flakyIo(99, "ENOENT") };
+    expect(() => renameAtomicFile("a", "b", io, "config")).toThrow();
+    expect(readWindowsReplaceRetryCounters()).toEqual({});
+  });
+
+  test("POSIX never retries even on a matching code", () => {
+    const io = { ...flakyIo(99), platform: "linux" as NodeJS.Platform };
+    expect(() => renameAtomicFile("a", "b", io, "config")).toThrow();
+    expect(readWindowsReplaceRetryCounters()).toEqual({});
+  });
+
+  test("publisher labels are a closed set, so a path can never become a key", () => {
+    // The union is the privacy enforcement: privacy:scan reads file text and
+    // cannot tell that a runtime string came from a path. If this list ever
+    // grows, it grows deliberately and in review.
+    const publishers: ReplacePublisher[] = ["config", "prompt-journal", "config-ownership"];
+    for (const publisher of publishers) renameAtomicFile("a", "b", flakyIo(1), publisher);
+    expect(Object.keys(readWindowsReplaceRetryCounters()).sort()).toEqual(
+      ["config", "config-ownership", "prompt-journal"],
+    );
+    // @ts-expect-error a path is not a ReplacePublisher
+    renameAtomicFile("a", "b", flakyIo(0), "C:\\Users\\someone\\.opencodex");
+  });
+});
+
+describe("GET /api/system/windows-replace-retries", () => {
+  test("reports the snapshot", async () => {
+    renameAtomicFile("a", "b", flakyIo(1), "config");
+    const req = new Request("http://127.0.0.1:10100/api/system/windows-replace-retries", { headers: { Host: "127.0.0.1:10100" } });
+    const res = await handleManagementAPI(req, new URL(req.url), config());
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(200);
+    const body = await res!.json() as { counters: Record<string, { retried: number; exhausted: number }> };
+    expect(body.counters).toEqual({ config: { retried: 1, exhausted: 0 } });
+  });
+
+  test("an empty snapshot is an empty object, not an error", async () => {
+    const req = new Request("http://127.0.0.1:10100/api/system/windows-replace-retries", { headers: { Host: "127.0.0.1:10100" } });
+    const res = await handleManagementAPI(req, new URL(req.url), config());
+    expect(res!.status).toBe(200);
+    expect(await res!.json()).toEqual({ counters: {} });
+  });
+
+  test("the route is GET-only", async () => {
+    const req = new Request("http://127.0.0.1:10100/api/system/windows-replace-retries", { method: "POST" });
+    const res = await handleManagementAPI(req, new URL(req.url), config());
+    // Either unmatched (null) or a non-200 — never a successful mutation.
+    expect(res === null || res.status !== 200).toBe(true);
+  });
+});