feat(runtime): guard root switches and isolate test global state

Codify one-root-per-process: initCodemap/configureResolver throw on mid-process
root changes except audit worktree reindex (runtime-swap bracket). Validate user
config at loadUserConfig; roll beforeEach/afterEach teardown across initCodemap suites.

Author: SutuSebastian

.changeset/runtime-test-isolation.md

@@ -0,0 +1,5 @@
+---
+"@stainless-code/codemap": minor
+---
+
+`createCodemap()` and `loadUserConfig()` now fail fast: switching to a different project root in the same process throws (audit `--base` worktree reindex is exempt), and invalid config files throw at load time instead of on first resolve.

docs/architecture.md

@@ -234,13 +234,13 @@ The npm package exports **`createCodemap`**, **`Codemap`** (`query`, `index`), *
 2. **`await cm.index({ mode, files?, quiet? })`** — same pipeline as the CLI (incremental / full / targeted).
 3. **`cm.query(sql)`** — read-only SQL against `.codemap/index.db` (opens the DB per call).
 
-**Constraint:** `initCodemap` is global to the process; only one active indexed project at a time.
+**Constraint:** One project root per process — a second `initCodemap` / `createCodemap` with a different `root` throws. Audit `--base` worktree reindex brackets root swaps via `runtime-swap.ts`. Re-init on the same root is allowed.
 
 ### User config
 
 Optional **`<state-dir>/config.{ts,js,json}`** (default `.codemap/config.*`; default export: object or async factory). **`--config <path>`** overrides with an explicit file (absolute or relative to cwd). Example shape: [`codemap.config.example.json`](../codemap.config.example.json). **Self-healing (D11):** `<state-dir>/.gitignore` is reconciled to canonical on every codemap boot via **`ensureStateGitignore`** (`src/application/state-dir.ts`); JSON config is reconciled via **`ensureStateConfig`** (`src/application/state-config.ts` — prunes unknown keys with a warning, sorts alphabetically, write-only-on-drift). TS/JS configs are validate-only at load time. Bumping the canonical `STATE_GITIGNORE_BODY` constant or the Zod schema IS the migration — every consumer's project repairs itself on next boot. Single attachment point: **`src/cli/bootstrap-codemap.ts`** runs the reconcilers before `loadUserConfig`.
 
-**Validation:** **`codemapUserConfigSchema`** ([Zod](https://zod.dev)) — strict object (unknown keys are rejected). **`defineConfig({ ... })`**, **`parseCodemapUserConfig`**, and **`resolveCodemapConfig`** (CLI and merged `createCodemap({ config })`) all go through the same schema. Invalid config throws **`TypeError`** with a short path/message list.
+**Validation:** **`codemapUserConfigSchema`** ([Zod](https://zod.dev)) — strict object (unknown keys are rejected). **`defineConfig({ ... })`**, **`parseCodemapUserConfig`**, **`loadUserConfig`**, and **`resolveCodemapConfig`** (CLI and merged `createCodemap({ config })`) all go through the same schema. Invalid config throws **`TypeError`** with a short path/message list.
 
 **Exports:** `codemapUserConfigSchema`, `parseCodemapUserConfig`, `defineConfig`, and **`CodemapUserConfig`** (inferred type) from the package entry — see **`src/config.ts`** / **`dist/index.d.mts`**.
 

docs/plans/runtime-test-isolation.md

@@ -1,6 +1,6 @@
 # PR 3 — runtime guards & test isolation
 
-> **Status:** open (not started) · **PR:** 3 of 3 · **Effort:** S–M
+> **Status:** open (in progress) · **PR:** 3 of 3 · **Effort:** S–M
 >
 > **Orchestrator:** [`security-hardening-orchestrator.md`](./security-hardening-orchestrator.md)
 >
@@ -34,12 +34,12 @@
 
 | ID  | Task                                                     | Status  | Verify                         |
 | --- | -------------------------------------------------------- | ------- | ------------------------------ |
-| 5.1 | `runtime-swap.ts` + audit worktree bracket               | pending | `bun test src/runtime.test.ts` |
-| 5.2 | `initCodemap` / `configureResolver` throw on root switch | pending | runtime tests                  |
-| 5.3 | `resetCodemapForTest` + `installCodemapTestTeardown`     | pending | —                              |
-| 5.4 | Teardown rollout on `initCodemap` test suites            | pending | affected `*.test.ts`           |
-| 5.5 | `loadUserConfig` → `parseCodemapUserConfig` at load      | pending | `bun test src/config.test.ts`  |
-| 5.6 | `api.ts` + architecture: throws-on-root-switch           | pending | —                              |
+| 5.1 | `runtime-swap.ts` + audit worktree bracket               | done    | `bun test src/runtime.test.ts` |
+| 5.2 | `initCodemap` / `configureResolver` throw on root switch | done    | runtime tests                  |
+| 5.3 | `resetCodemapForTest` + `installCodemapTestTeardown`     | done    | —                              |
+| 5.4 | Teardown rollout on `initCodemap` test suites            | done    | affected `*.test.ts`           |
+| 5.5 | `loadUserConfig` → `parseCodemapUserConfig` at load      | done    | `bun test src/config.test.ts`  |
+| 5.6 | `api.ts` + architecture: throws-on-root-switch           | done    | —                              |
 | 5.s | Commit + PR + CI                                         | pending | `bun run check`                |
 
 ---

docs/plans/security-hardening-orchestrator.md

@@ -24,8 +24,8 @@
 | PR    | Plan                                                            | Status                                                                              | Blocks                              |
 | ----- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
 | **1** | lifted → [`architecture.md`](../architecture.md) (plan retired) | **merged** ([#180](https://github.com/stainless-code/codemap/pull/180) · `a5caca8`) | —                                   |
-| **2** | lifted → [`architecture.md`](../architecture.md) (plan retired) | **PR open** (`fix/impact-inpath-homonyms`)                                          | —                                   |
-| **3** | [`runtime-test-isolation.md`](./runtime-test-isolation.md)      | **pending**                                                                         | PR **1** merged (PR **2** optional) |
+| **2** | lifted → [`architecture.md`](../architecture.md) (plan retired) | **merged** ([#181](https://github.com/stainless-code/codemap/pull/181) · `aae172f`) | —                                   |
+| **3** | [`runtime-test-isolation.md`](./runtime-test-isolation.md)      | **in progress** (`fix/runtime-test-isolation`)                                      | PR **1** merged (PR **2** optional) |
 
 | — | — | **deferred** | golden `schema.test.ts` + path guards |
 | — | — | **skip** | atomic `ensureStateConfig` writes |
@@ -64,17 +64,17 @@ Evaluated 2026-06 against [roadmap § Floors](../roadmap.md#floors-v1-product-sh
 
 ## Session log
 
-| Date       | Event       | Notes                                                                        |
-| ---------- | ----------- | ---------------------------------------------------------------------------- |
-| 2026-06-10 | Triage      | ROI on 7 slices; 3-PR program adopted.                                       |
-| 2026-06-10 | PR 1 impl   | PR **1** committed on `fix/security-hardening-wave1`; harden pass in flight. |
-| 2026-06-05 | PR 1 harden | `/harden-pr full` — plan retired; contracts in architecture/glossary.        |
-| 2026-06-05 | PR 1 merge  | [#180](https://github.com/stainless-code/codemap/pull/180) → `a5caca8`.      |
-| 2026-06-05 | PR 2 start  | `fix/impact-inpath-homonyms` — `inPath` + homonym walks in impact-engine.    |
-| 2026-06-05 | PR 2 harden | `/harden-pr full` — plan retired; CLI/MCP/docs parity.                       |
-| —          | PR 2 merge  | _PR URL · merge SHA_                                                         |
-| —          | PR 3 start  | _from `main`_                                                                |
-| —          | PR 3 merge  | _fill · close orchestrator_                                                  |
+| Date       | Event       | Notes                                                                         |
+| ---------- | ----------- | ----------------------------------------------------------------------------- |
+| 2026-06-10 | Triage      | ROI on 7 slices; 3-PR program adopted.                                        |
+| 2026-06-10 | PR 1 impl   | PR **1** committed on `fix/security-hardening-wave1`; harden pass in flight.  |
+| 2026-06-05 | PR 1 harden | `/harden-pr full` — plan retired; contracts in architecture/glossary.         |
+| 2026-06-05 | PR 1 merge  | [#180](https://github.com/stainless-code/codemap/pull/180) → `a5caca8`.       |
+| 2026-06-05 | PR 2 start  | `fix/impact-inpath-homonyms` — `inPath` + homonym walks in impact-engine.     |
+| 2026-06-05 | PR 2 harden | `/harden-pr full` — plan retired; CLI/MCP/docs parity.                        |
+| 2026-06-05 | PR 2 merge  | [#181](https://github.com/stainless-code/codemap/pull/181) → `aae172f`.       |
+| 2026-06-05 | PR 3 start  | `fix/runtime-test-isolation` — root guards + test teardown + config validate. |
+| —          | PR 3 merge  | _fill · close orchestrator_                                                   |
 
 ---
 

scripts/agent-eval/parse-agent-log.test.ts

@@ -11,6 +11,7 @@ import { join } from "node:path";
 
 import { resolveCodemapConfig } from "../../src/config";
 import { initCodemap } from "../../src/runtime";
+import { installCodemapTestTeardown } from "../../src/test-helpers/runtime-reset";
 import { resolveGoldenQuery } from "../query-golden/resolve-golden-query";
 import { compareLogArms, summarizeLogComparison } from "./compare-live-logs";
 import { runLiveMcpArm } from "./live-mcp-arm";
@@ -43,6 +44,8 @@ import {
   traditionalToolSequence,
 } from "./traditional-probe";
 
+installCodemapTestTeardown();
+
 const sampleLog = join(
   import.meta.dir,
   "../../fixtures/agent-eval/sample-cursor-log.json",

src/api.test.ts

@@ -4,6 +4,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { createCodemap } from "./api";
+import { installCodemapTestTeardown } from "./test-helpers/runtime-reset";
+
+installCodemapTestTeardown();
 
 describe("createCodemap", () => {
   test("query runs against the index database", async () => {

src/api.ts

@@ -45,7 +45,9 @@ export interface CodemapInitOptions {
  * and returns a {@link Codemap} handle.
  *
  * @remarks
- * Only one Codemap project per process: `initCodemap` is global; the last `createCodemap()` wins.
+ * One project root per process: a second `createCodemap()` with a different `root` throws.
+ * Re-initializing the same root is allowed. Audit `--base` worktree reindex is the only
+ * production path that may temporarily switch roots (`runtime-swap.ts`).
  */
 export async function createCodemap(
   options: CodemapInitOptions = {},

src/application/affected-engine.test.ts

@@ -4,6 +4,10 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+import { installCodemapTestTeardown } from "../test-helpers/runtime-reset";
+
+installCodemapTestTeardown();
+
 import { resolveCodemapConfig } from "../config";
 import { closeDb, createTables, openDb } from "../db";
 import { initCodemap } from "../runtime";

src/application/audit-engine.ts

@@ -9,6 +9,7 @@ import {
   getTsconfigPath,
   initCodemap,
 } from "../runtime";
+import { enterRuntimeSwap, exitRuntimeSwap } from "../runtime-swap";
 import { openCodemapDatabase } from "../sqlite-db";
 import {
   isGitRepo,
@@ -456,6 +457,7 @@ export function makeWorktreeReindex(): ReindexFn {
       // to <worktree>/.codemap/index.db via the default state-dir.
       const savedConfig = getCodemapConfig();
       let wtDb;
+      enterRuntimeSwap();
       try {
         const wtUser = await loadUserConfig(worktreePath, undefined);
         initCodemap(resolveCodemapConfig(worktreePath, wtUser));
@@ -466,6 +468,7 @@ export function makeWorktreeReindex(): ReindexFn {
         wtDb?.close();
         initCodemap(savedConfig);
         configureResolver(getProjectRoot(), getTsconfigPath());
+        exitRuntimeSwap();
       }
     });
     // Catch on the chain itself so one failed reindex doesn't poison the

src/application/boundary-rules.test.ts

@@ -4,6 +4,10 @@ import { writeFileSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+import { installCodemapTestTeardown } from "../test-helpers/runtime-reset";
+
+installCodemapTestTeardown();
+
 import { resolveCodemapConfig } from "../config";
 import { closeDb, createTables, openDb, reconcileBoundaryRules } from "../db";
 import { initCodemap } from "../runtime";