refactor(testkit): move shared test helpers to the repo root

Author: TheGreatAxios

.github/workflows/ci.yml

@@ -85,15 +85,15 @@ jobs:
 
   # The suite is sharded so the slowest slice, not the whole suite, sets the
   # wall clock. Four time-balanced shards split the same
-  # ./src ./e2e ./evals ./scripts union via bun's --shard=k/4, balanced by
+  # ./src ./e2e ./evals ./scripts ./testkit union via bun's --shard=k/4, balanced by
   # the checked-in per-file durations in scripts/ci-timings.json (--timings).
   # Every shard still goes through check:projects-dir-guard: the guard
   # forwards the path union plus the shard flags to the suite it wraps, so the
   # gate covers the same tests as before, all of them sandboxed.
   #
   # Timings refresh policy: regenerate scripts/ci-timings.json by running the
   # full union locally with --update-timings (same seeded flags as `test`):
-  #   bun run check:projects-dir-guard ./src ./e2e ./evals ./scripts \
+  #   bun run check:projects-dir-guard ./src ./e2e ./evals ./scripts ./testkit \
   #     --timings=./scripts/ci-timings.json --update-timings
   # Regen when the slowest shard's Test step skews more than ~20% above a
   # quarter of the one-process suite time (shards drifting apart means the
@@ -151,7 +151,7 @@ jobs:
       # `bun run test:paths <paths> --shard=k/4
       # --timings=./scripts/ci-timings.json`.
       - name: Test
-        run: bun run check:projects-dir-guard ./src ./e2e ./evals ./scripts --shard=${{ matrix.shard }} --timings=./scripts/ci-timings.json
+        run: bun run check:projects-dir-guard ./src ./e2e ./evals ./scripts ./testkit --shard=${{ matrix.shard }} --timings=./scripts/ci-timings.json
 
   # Cross-shard pollution detector: the shards above split the path union,
   # but the union is not the isolation domain — a mock.module leak across

AGENTS.md

@@ -32,11 +32,11 @@ When refactoring replaces an old path, delete the old one. No back-compat shims,
 
 - Add or update tests with every behavior change.
 - Bug fixes start with a failing test that reproduces the bug. Do not start by patching.
-- Co-located `src/**/*.test.ts` for module logic · `src/testkit/` shared test helpers · `fixtures/` fixture repos · `e2e/` scenario runs over the production agent loop (fixture-repo seeding, scripted inference via `@intx/inference-testing`, `runUntilDone`/`runUntilSuspended`/`sendOperatorTurn` drivers — see `e2e/harness.ts`; the session plumbing lives in `e2e/integration-harness.ts`).
+- Co-located `src/**/*.test.ts` for module logic · `testkit/` shared test helpers (repo root, shared by unit and e2e) · `fixtures/` fixture repos · `e2e/` scenario runs over the production agent loop (fixture-repo seeding, scripted inference via `@intx/inference-testing`, `runUntilDone`/`runUntilSuspended`/`sendOperatorTurn` drivers — see `e2e/harness.ts`; the session plumbing lives in `e2e/integration-harness.ts`).
 - Unit vs e2e split: keep parser tables, race/atomicity tests, and small pure-function contracts co-located unit tests; put multi-step agent-loop orchestration (permission flows, compaction end-to-end, subagent lanes, credential recovery) in `e2e/` where a scripted model reply replaces pages of per-file fakes. Do not pin constants or `record.decisions` diagnostics — assert the behavior the contract exposes.
 - e2e v1 non-goals: TUI overlay/PTY driving, race tests, parser tables, crash-atomicity, and any second agent-loop stack — the integration harness already is one.
 - A test must not depend on another file having run, or on the default file order. It must pass under `bun test ./src ./e2e ./evals ./scripts --randomize`. If a test mutates module-level state or calls `mock.module`, it must restore that state itself (`afterEach`/`afterAll`), not rely on the process happening to reset it. When capturing a module's real exports to restore later, shallow-copy them (`{ ...moduleNamespace }`) at capture time, whether the namespace came from `await import(path)` or a static `import * as ns from "path"` — Bun mutates the live namespace object in place when the module is mocked, so holding a bare reference to it (either form) silently turns into the mocked exports.
-- Never call `mock.module` directly. Bun runs every test file in one process, so a `mock.module` call without its own teardown stays installed for the rest of the run and silently replaces the real module for other files — producing failures in files the change never touched, with no obvious link to the cause and no signal from `tsc` or a per-file run (CL-6967). Use `withMockedModule`/`withMockedModuleDuring` from `src/testkit/mock-module.ts`, which capture the real module and register their own restore. The oxlint plugin (`corbits/no-bare-mock-module` in `.oxlintrc.json` / `scripts/oxlint-plugin-corbits.js`) rejects bare `mock.module` calls in `*.test.ts` files.
+- Never call `mock.module` directly. Bun runs every test file in one process, so a `mock.module` call without its own teardown stays installed for the rest of the run and silently replaces the real module for other files — producing failures in files the change never touched, with no obvious link to the cause and no signal from `tsc` or a per-file run (CL-6967). Use `withMockedModule`/`withMockedModuleDuring` from `testkit/mock-module.ts`, which capture the real module and register their own restore. The oxlint plugin (`corbits/no-bare-mock-module` in `.oxlintrc.json` / `scripts/oxlint-plugin-corbits.js`) rejects bare `mock.module` calls in `*.test.ts` files.
 - A test earns its place only if a real behavior change can fail it. Document copy, brand colors, marketing assets, and splash text are not behavior: assertions that pin an asset's literal wording, an exact palette hex/ANSI value, or rendered copy fail on copy/design edits and catch no regressions — assert the contract instead (parsing, formatting, ranges, aliases, invariants). Tests are code too: pinning a source file's own text is the same trap. This bar is a review and authorship rule, not a linter shape match.
 
 ## Build & Validation

CONTRIBUTING.md

@@ -34,7 +34,7 @@ These match the local development loop. CI splits the same path union into
 four time-balanced `--shard=k/4` slices via `test:paths` (balanced by the
 checked-in per-file durations in `scripts/ci-timings.json`) rather than
 running the one-process `bun run test` suite. Regenerate that file with
-`bun run check:projects-dir-guard ./src ./e2e ./evals ./scripts
+`bun run check:projects-dir-guard ./src ./e2e ./evals ./scripts ./testkit
 --timings=./scripts/ci-timings.json --update-timings` when the slowest
 shard skews more than ~20% above a quarter of the one-process suite time,
 or proactively whenever slow files land — see `.github/workflows/ci.yml`

bunfig.toml

@@ -1,5 +1,5 @@
 [test]
-preload = ["./src/testkit/preload.ts"]
+preload = ["./testkit/preload.ts"]
 pathIgnorePatterns = [
   "fixtures/**",
   "eval/tasks/**",

docs/IMPLEMENTATION.md

@@ -560,11 +560,11 @@ Run all three before declaring work complete.
 
 ## Testing
 
-- **Unit tests** are co-located with source as `*.test.ts` (e.g. `config.test.ts`, `director.test.ts`, `prompts.test.ts`, `renderer.test.ts`, `permission/permission.test.ts`, each `plugins/*.test.ts`, and TUI tests under `tui/`). Shared test helpers live in `src/testkit/`.
+- **Unit tests** are co-located with source as `*.test.ts` (e.g. `config.test.ts`, `director.test.ts`, `prompts.test.ts`, `renderer.test.ts`, `permission/permission.test.ts`, each `plugins/*.test.ts`, and TUI tests under `tui/`). Shared test helpers live in `testkit/` (repo root, shared by unit and e2e).
 - **`fixtures/`** holds fixture repos and comparison assets (e.g. `demo-comparison/`, `multi-file-service/`).
 - **`e2e/`** holds scenario tests driven over the production agent loop with scripted models (`@intx/inference-testing`) — fixture-repo seeding, `runUntilDone`/`runUntilSuspended`/`sendOperatorTurn` drivers (see `e2e/harness.ts`), and the reactor permission / multi-turn exercises formerly under `tests/integration/`.
 - **Capability evals** (`evals/capability/`) are **not** the integration harness: they drive the product path (`corbits exec` / `runExec`) with real models against fixture copies and objective `verify.sh` graders. Case format + loader tests live under `evals/capability/`; run with `bun run eval:capability` (see `evals/capability/README.md`). Use `--baseline` to detect improve/regress across models or commits.
-- **TUI tests** are co-located `*.test.ts` files under `src/tui/` (e.g. `shell.test.ts`, `runner-host.test.ts`, `stream.test.ts`), run as part of `bun test` along with everything else; there is no separate `test:tui` script. `bunfig.toml` preloads `src/testkit/preload.ts` for every test file, which strips ambient env (`COLORTERM`, `CORBITS_*`, telemetry) and hard-fails when `rg` is absent.
+- **TUI tests** are co-located `*.test.ts` files under `src/tui/` (e.g. `shell.test.ts`, `runner-host.test.ts`, `stream.test.ts`), run as part of `bun test` along with everything else; there is no separate `test:tui` script. `bunfig.toml` preloads `testkit/preload.ts` for every test file, which strips ambient env (`COLORTERM`, `CORBITS_*`, telemetry) and hard-fails when `rg` is absent.
 - **Parallel local runs** — `bun run test:parallel [N]` (default 4 workers) runs the same seeded suite with `--parallel=N`, wrapped in an output-stall watchdog (`scripts/test-parallel.ts`). Bun 1.4.x intermittently livelocks under `--parallel` (one worker spins at 100 % CPU holding a zombie git child while the main process idles; no output, no summary — upstream oven-sh/bun#36235), and `bun test` has no run-level timeout, so a stalled run hangs forever. The watchdog kills the suite's own process group after 90 s of silence and retries up to 3 times; a child that exits on its own (pass or fail) is never retried. CI keeps sharded sequential runs (`test:paths`) and does not use `--parallel`.
 
 ## Deployment

e2e/crash-finalize.test.ts

@@ -5,7 +5,7 @@ import { describe, expect, test } from "bun:test";
 
 import { generateSessionId, sessionDir } from "../src/session/index.js";
 import type { RunState } from "../src/session/state.js";
-import { createTempDirs } from "../src/testkit/temporary-dirs.js";
+import { createTempDirs } from "../testkit/temporary-dirs.js";
 
 const FIXTURE = join(
   import.meta.dirname,

e2e/git-push-scoped.test.ts

@@ -18,7 +18,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { afterEach, beforeEach, describe, expect, it } from "bun:test";
-import { initTemporaryGitRepo } from "../src/testkit/temporary-git-repo.js";
+import { initTemporaryGitRepo } from "../testkit/temporary-git-repo.js";
 
 const SCRIPT = join(import.meta.dir, "../bin/git-push-scoped");
 

e2e/harness.ts

@@ -22,7 +22,7 @@ import {
   createPermissionGate,
   type PermissionGate,
 } from "../src/permission/gate.js";
-import { initTemporaryGitRepo } from "../src/testkit/temporary-git-repo.js";
+import { initTemporaryGitRepo } from "../testkit/temporary-git-repo.js";
 import {
   closeIntegrationSession,
   openIntegrationSession,

e2e/reactor-approval-suspend.test.ts

@@ -15,7 +15,7 @@ import {
   runUntilSuspended,
   toolDoneEvents,
 } from "./integration-harness.js";
-import { defined } from "../src/testkit/defined.js";
+import { defined } from "../testkit/defined.js";
 
 const CURL_CALL = {
   name: "run_shell",

e2e/signal-helpers.ts

@@ -1,4 +1,4 @@
-import { createTempDirs } from "../src/testkit/temporary-dirs.js";
+import { createTempDirs } from "../testkit/temporary-dirs.js";
 
 /**
  * Reads a spawned fixture's stdout pipe until the first chunk containing