test: give slow-work budgets one home and one rule

Four commits have now raised a Windows budget individually (3e95ba3,
217db04, 81f3f68, d2eb93d), each deciding a number on its own.
That is how you end up with 52 timeout literals and no way to tell a
justified budget from a silenced flake.

tests/helpers/test-budget.ts states the rule instead of the number.
A budget may be raised only when both hold: the wait is intrinsic to
what the test asserts, and the ablation still fails. The first without
the second is how a vacuous test gets locked in, which is the fault
this round has been chasing since 020.

The contrast is written down because it is the whole judgment: the tray
test launches PowerShell, then Bun, then rebinds the port, so the
processes ARE the proof and it gets a budget. The sidebar route tests
spawned gh incidentally while claiming route reachability, so they had
the spawn deleted instead. Same symptom, opposite treatment.

INTERNAL_DEADLINE_MS covers the case that cost the most time to see: a
deadline inside a test, shorter than the test budget, fails faster than
a timeout and reads as a logic error. WS-REBIND-01 died at 748ms
against its own hardcoded 1s while the budget was 5s.

storage-cleanup's 22 literals now come from one constant. Its slowest
test runs in ~7ms locally and blew a 20s budget on CI -- a gap of three
orders of magnitude, which is the argument for sizing these to
contention rather than to a local stopwatch.

Author: lidge-jun

tests/helpers/test-budget.ts

@@ -0,0 +1,50 @@
+/**
+ * Test budgets for work that is genuinely slow, not for making red go away.
+ *
+ * Bun's default is 5s. That is generous for a pure function and thin for anything
+ * that spawns a process, binds a server, or writes SQLite on a loaded CI runner —
+ * which is why a run of windows-latest failures kept blaming a different test each
+ * time. The blame moved; the cause did not.
+ *
+ * ## When you may raise a budget
+ *
+ * Both must hold:
+ *
+ * 1. **The wait is intrinsic to the assertion.** The tray socket-inheritance test
+ *    launches PowerShell, which launches Bun, then rebinds the port to prove the
+ *    child never inherited the listen socket. Those processes ARE the proof, so it
+ *    gets a budget. The sidebar route tests spawned `gh` only incidentally while
+ *    claiming route reachability, so they got the spawn DELETED instead. Ask which
+ *    kind you have before reaching for a number.
+ * 2. **The ablation still fails.** Revert the production behaviour the test covers
+ *    and confirm the test goes red. A budget that hides a vacuous test is worse than
+ *    the flake, because it converts a reliability signal into silence.
+ *
+ * If only (1) holds, you have not finished. If neither holds, delete the wait.
+ *
+ * ## Why these numbers
+ *
+ * They are headroom against runner contention, not measured durations. Local timings
+ * are typically two to four orders of magnitude smaller: the storage cleanup test
+ * that blew a 20s CI budget runs in ~7ms here. Sizing to the local number is what
+ * produced the original 5s failures.
+ */
+
+/** Real child process: PowerShell, a CLI smoke test, an external binary. */
+export const SPAWN_BUDGET_MS = 45_000;
+
+/** Binds a real server or opens a real socket, including restart-and-reconnect flows. */
+export const SERVER_BUDGET_MS = 30_000;
+
+/** Touches SQLite or the filesystem repeatedly. Slow on Windows for reasons outside our code. */
+export const STORE_BUDGET_MS = 30_000;
+
+/**
+ * A deadline *inside* a test, for an await that would otherwise hang forever.
+ *
+ * Keep these at least a few times under the surrounding budget. An internal deadline
+ * shorter than the test budget fails faster than a timeout and reads as a logic error:
+ * WS-REBIND-01 died at 748ms against its own hardcoded 1s while the budget was 5s, and
+ * that mismatch is exactly why it looked random rather than slow.
+ */
+export const INTERNAL_DEADLINE_MS = 15_000;

tests/server-auth.test.ts

@@ -6,6 +6,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { saveCodexAccountCredential } from "../src/codex/account-store";
 import { clearCodexWebSocketRegistry, getTrackedCodexWebSocketCountForAccount } from "../src/codex/websocket-registry";
+import { INTERNAL_DEADLINE_MS, SERVER_BUDGET_MS } from "./helpers/test-budget";
 import { clearAccountNeedsReauth, clearAccountQuota, getAccountQuota, isAccountNeedsReauth, markAccountNeedsReauth, updateAccountQuota } from "../src/codex/auth-api";
 import {
   CODEX_THREAD_AFFINITY_IDLE_TTL_MS,
@@ -1294,7 +1295,7 @@ describe("server local API auth", () => {
       if (globalThis.fetch === matrixFetch) globalThis.fetch = originalGlobalFetch;
       await upstream.stop(true);
     }
-  }, { timeout: 30_000 });
+  }, { timeout: SERVER_BUDGET_MS });
 
   test("internal web-search and vision never forward a non-ChatGPT bearer as Direct sidecar auth", async () => {
     if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
@@ -2109,7 +2110,7 @@ describe("server local API auth", () => {
         // WebSocket, and waits for a two-hop retry across accounts — a second of that on a
         // contended runner is optimistic. The assertions below are unchanged; only the
         // room to reach them grew.
-        setTimeout(() => reject(new Error("websocket retry timed out")), 15_000);
+        setTimeout(() => reject(new Error("websocket retry timed out")), INTERNAL_DEADLINE_MS);
       });
       expect(harness.dispatches).toEqual(["acct-pool-a", "acct-pool-b"]);
       expect(registrySnapshots).toEqual([[1, 0], [0, 1]]);

tests/storage-cleanup.test.ts

@@ -25,6 +25,7 @@ import {
   selectOldestPercent,
   type ExecuteCleanupOptions,
 } from "../src/storage/cleanup";
+import { STORE_BUDGET_MS } from "./helpers/test-budget";
 
 const OLD = new Date("2026-01-01T00:00:00Z");
 const MID = new Date("2026-02-01T00:00:00Z");
@@ -418,7 +419,7 @@ describe("executeArchivedCleanup", () => {
       try { logsRead?.close(); } catch { /* */ }
       try { memoriesRead?.close(); } catch { /* */ }
     }
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("rolls back staged renames when a later rename fails", () => {
     home = buildHome();
@@ -639,7 +640,7 @@ describe("executeArchivedCleanup", () => {
     const ids = state.query<{ id: string }, []>("SELECT id FROM threads").all().map(r => r.id);
     state.close();
     expect(ids).toEqual(["active"]);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("threads read failure leaves every file and database unchanged", () => {
     home = buildHome({ withSatelliteStores: true });
@@ -666,7 +667,7 @@ describe("executeArchivedCleanup", () => {
     expect(Buffer.compare(beforeGoals, readFileSync(join(home, "goals_1.sqlite")))).toBe(0);
     expect(Buffer.compare(beforeMemories, readFileSync(join(home, "memories_1.sqlite")))).toBe(0);
     expect(Buffer.compare(beforeState, readFileSync(join(home, "state_5.sqlite")))).toBe(0);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   // Windows CI: injected satellite rollback paths (especially goals) can measure 6–13s
   // there and trip bun's default 5s harness timeout.
@@ -723,7 +724,7 @@ describe("executeArchivedCleanup", () => {
       expect(stateAfter.query("SELECT id, rollout_path, archived FROM threads ORDER BY id").all()).toEqual(threads);
       stateAfter.close();
     },
-    { timeout: 30_000 },
+    { timeout: STORE_BUDGET_MS },
   );
 
   test("satellite restore failure keeps recovery trashDir and manifest", () => {
@@ -922,7 +923,7 @@ describe("executeArchivedCleanup", () => {
         job_key: (expected as { job_key: string }).job_key,
       });
     }
-  }, { timeout: 30_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("permanent cleanup works with logs-only satellite store", () => {
     home = buildHome({ satellites: "logs" });
@@ -1012,7 +1013,7 @@ describe("executeArchivedCleanup", () => {
       "active", "tmid", "tnew", "told",
     ]);
     state.close();
-  }, { timeout: 30_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   // Windows CI: same multi-satellite restore profile as above (timed out at 5s on PR #558).
   test("concurrent consolidate enqueue watermark change is preserved on restore", () => {
@@ -1050,7 +1051,7 @@ describe("executeArchivedCleanup", () => {
       "active", "tmid", "tnew", "told",
     ]);
     state.close();
-  }, { timeout: 30_000 });
+  }, { timeout: STORE_BUDGET_MS });
 });
 
 describe("listTrashEntries + restoreTrashEntry", () => {
@@ -1441,7 +1442,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
       has_user_event: 1,
       archived: 1,
     });
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test.each([
     ["failAfterStateCommit", { failAfterStateCommit: true }, "db_reconcile_failed"],
@@ -1498,7 +1499,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
       expect(logsAfter.query("SELECT COUNT(*) AS n FROM logs WHERE thread_id='told'").get()).toEqual({ n: 1 });
       logsAfter.close();
     },
-    { timeout: 20_000 },
+    { timeout: STORE_BUDGET_MS },
   );
 
   test("late failure after logs commit keeps metadata, persists pending sections, and resume preserves pre-existing rows", () => {
@@ -1602,7 +1603,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
       goals.query("SELECT COUNT(*) AS n FROM thread_goals WHERE thread_id IN ('told','tmid','tnew')").get(),
     ).toEqual({ n: 2 }); // fixture seeds told+tmid only
     goals.close();
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("leftover-stage failure never restages files and retry accepts destinations", () => {
     // Regression for reverse-move failure after metadata compensation: restage
@@ -1660,7 +1661,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
       logsAfter.query("SELECT ts, target FROM logs WHERE id=1").get(),
     ).toEqual({ ts: 42, target: "pre" });
     logsAfter.close();
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("initial restore-pending write failure moves no files", () => {
     home = buildHome({ withSatelliteStores: true });
@@ -1684,7 +1685,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
     expect(retried.ok).toBe(true);
     expect(retried.count).toBe(3);
     expect(existsSync(stage)).toBe(false);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("interrupted pending update preserves the previous valid marker", () => {
     home = buildHome({ withSatelliteStores: true });
@@ -1721,7 +1722,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
     expect(retried.ok).toBe(true);
     expect(retried.error).toBeUndefined();
     expect(existsSync(stage)).toBe(false);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("crash after file move retries without dest_exists or fs_failed", () => {
     home = buildHome({ withSatelliteStores: true });
@@ -1747,7 +1748,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
     expect(retried.error).not.toBe("fs_failed");
     expect(retried.count).toBe(3);
     expect(existsSync(stage)).toBe(false);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("mid-move failure keeps placed dest, marker, and resumes without dest_exists", () => {
     // First rename succeeds, second throws. Do not reverse the first file or drop
@@ -1801,7 +1802,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
     expect(existsSync(join(home, "archived_sessions", "rollout-old.jsonl"))).toBe(true);
     expect(existsSync(join(home, "archived_sessions", "rollout-mid.jsonl"))).toBe(true);
     expect(existsSync(join(home, "archived_sessions", "rollout-new.jsonl"))).toBe(true);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("malformed restore-pending.json is not treated as a fresh restore", () => {
     home = buildHome({ withSatelliteStores: true });
@@ -1819,7 +1820,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
     expect(existsSync(join(stage, "rollout-old.jsonl"))).toBe(true);
     expect(existsSync(join(home, "archived_sessions", "rollout-old.jsonl"))).toBe(false);
     expect(readFileSync(join(stage, "restore-pending.json"), "utf8")).toBe("{not-valid-json");
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("resume with owed satellite sections and missing backup fails closed", () => {
     home = buildHome({ withSatelliteStores: true });
@@ -1850,7 +1851,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
     expect(failed.error).toBe("db_reconcile_failed");
     expect(existsSync(stage)).toBe(true);
     expect(existsSync(join(stage, "manifest.json"))).toBe(true);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("resume with owed logs section but missing logs in backup fails closed", () => {
     home = buildHome({ withSatelliteStores: true });
@@ -1881,7 +1882,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
     expect(existsSync(stage)).toBe(true);
     expect(existsSync(join(stage, "manifest.json"))).toBe(true);
     expect(existsSync(join(stage, "restore-pending.json"))).toBe(true);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("failed tombstone rename keeps stage recoverable and listed", () => {
     home = buildHome();
@@ -1905,7 +1906,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
     expect(retried.ok).toBe(true);
     expect(existsSync(stage)).toBe(false);
     expect(listTrashEntries(home)).toEqual([]);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("tombstone delete failure reports success without phantom trash entry", () => {
     home = buildHome();
@@ -1925,7 +1926,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
     const trashRoot = join(home, ".trash");
     const tombstones = readdirSync(trashRoot).filter(n => n.startsWith(".tombstone-"));
     expect(tombstones.length).toBe(1);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("cleanup rejects overlap with accepted restore-pending destinations after state-commit failure", () => {
     home = buildHome({ withSatelliteStores: true });
@@ -1961,7 +1962,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
     const retry = restoreTrashEntry(trashId, { codexHome: home });
     expect(retry.ok).toBe(true);
     expect(existsSync(join(home, restoredRel))).toBe(true);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("cleanup rejects overlap with accepted restore-pending destinations after file-move failure", () => {
     home = buildHome();
@@ -1996,7 +1997,7 @@ describe("listTrashEntries + restoreTrashEntry", () => {
 
     const retry = restoreTrashEntry(trashId, { codexHome: home });
     expect(retry.ok).toBe(true);
-  }, { timeout: 20_000 });
+  }, { timeout: STORE_BUDGET_MS });
 
   test("percent preview backfills past pending oldest archive for manual cleanup", () => {
     home = buildHome();

tests/windows-tray.test.ts

@@ -19,6 +19,7 @@ import {
 } from "../src/tray/windows";
 import { handleManagementAPI } from "../src/server/management-api";
 import type { OcxConfig } from "../src/types";
+import { INTERNAL_DEADLINE_MS, SPAWN_BUDGET_MS } from "./helpers/test-budget";
 
 const entry: WindowsTrayEntry = {
   bun: "C:\\사용자 공간\\%TEMP% ! ^ ( ) & 검증\\bun.exe",
@@ -257,8 +258,8 @@ describe("Windows tray packaging and command safety", () => {
   // round the sidebar route tests were fixed by DELETING their real `gh` spawn, because
   // spawning a binary was incidental to what those tests claimed. The distinction is
   // whether the wait is intrinsic to the assertion. Here it is; there it was not.
-  const PID_FILE_WAIT_MS = 20_000;
-  const TRAY_LAUNCH_TIMEOUT_MS = 45_000;
+  const PID_FILE_WAIT_MS = INTERNAL_DEADLINE_MS;
+  const TRAY_LAUNCH_TIMEOUT_MS = SPAWN_BUDGET_MS;
 
   test("launches the detached tray host without retaining the proxy listen socket", async () => {
     if (process.platform !== "win32") return;