Stop workflow-controller tests from leaking into ~/.corbits/projects

WorkflowController never threaded an override for the state-tree home, so
persist()/resume() always fell back to the real user home even when a test
passed a sandboxed one. tests/unit/workflow-controller.test.ts was the
concrete leaker: every start()/resume() call it exercised wrote a real
session directory (t-wf-controller-*) into ~/.corbits/projects.

Add an optional `home` to WorkflowControllerArgs and thread it through
persist() and resume(), then pass the test's mkdtemp'd home through the
controller and the one direct saveWorkflowState() call that skipped it.

Add scripts/guard-real-projects-dir.ts, wired into `bun run test`, which
snapshots ~/.corbits/projects before and after the suite and fails the run
if anything new appears — a backstop against this class of leak recurring
in any test, not just this file.

Author: TheGreatAxios

package.json

@@ -32,7 +32,7 @@
     "build": "bun build ./src/index.ts --outdir ./dist --target bun --external '@opentui/core-*' && bun scripts/copy-repo-plugins.ts",
     "build:bin": "bun build ./src/index.ts --compile --minify --define process.env.NODE_ENV='\"production\"' --outfile ./dist/corbits && bun scripts/copy-repo-plugins.ts",
     "typecheck": "tsc --noEmit",
-    "test": "bun test ./src ./tests ./evals",
+    "test": "bun scripts/guard-real-projects-dir.ts ./src ./tests ./evals",
     "lint": "prettier --check --cache . && eslint --cache .",
     "check": "bun run lint && bun run typecheck && bun run build && bun run test",
     "start": "bun run build && bun ./dist/index.js",

scripts/guard-real-projects-dir.ts

@@ -0,0 +1,54 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readdir } from "node:fs/promises";
+import { spawn } from "node:child_process";
+
+// Runs `bun test` and fails the run if any test wrote into the real
+// ~/.corbits/projects directory. Tests must sandbox state under a temp
+// `home` (see src/session/index.ts's `home` overrides); nothing running
+// under this wrapper is allowed to fall back to the developer's own
+// session history.
+//
+// This is a backstop, not a substitute for threading `home` correctly: a
+// leak is only caught after it already wrote into a real directory once,
+// which this script then reports and leaves in place for inspection.
+
+const projectsDir = join(homedir(), ".corbits", "projects");
+
+async function listEntries(): Promise<Set<string>> {
+  try {
+    return new Set(await readdir(projectsDir));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return new Set();
+    throw err;
+  }
+}
+
+async function main(): Promise<void> {
+  const before = await listEntries();
+
+  const args = process.argv.slice(2);
+  const child = spawn("bun", ["test", ...args], { stdio: "inherit" });
+  const testExitCode = await new Promise<number>((resolve) => {
+    child.on("exit", (code) => resolve(code ?? 1));
+  });
+
+  const after = await listEntries();
+  const leaked = [...after].filter((name) => !before.has(name));
+
+  if (leaked.length > 0) {
+    process.stderr.write(
+      `\nguard-real-projects-dir: ${leaked.length} test run wrote into the real ` +
+        `${projectsDir} instead of a sandboxed temp dir:\n` +
+        leaked.map((name) => `  ${name}`).join("\n") +
+        "\n\nA test must pass an explicit `home` (mkdtemp'd) through to any " +
+        "function that otherwise defaults to node:os homedir() — see " +
+        "tests/unit/workflow-controller.test.ts for the pattern.\n",
+    );
+    process.exit(1);
+  }
+
+  process.exit(testExitCode);
+}
+
+void main();

src/tui/workflow-controller.ts

@@ -55,6 +55,9 @@ export interface WorkflowControllerArgs {
   // The live chat director; the workflow coordinator is attached to it when a
   // workflow starts. Returns undefined before the director is built.
   getDirector: () => { setWorkflowCoordinator: SetCoordinator } | undefined;
+  // Overrides the state-tree home (defaults to the real user home). Tests
+  // pass a sandboxed dir here so persist()/resume() never touch ~/.corbits.
+  home?: string;
 }
 
 // Owns the workflow lifecycle for the TUI: starting, capability overrides,
@@ -116,13 +119,15 @@ export class WorkflowController {
     const runtime = this.runtime;
     if (runtime === undefined) return;
     const sessionId = this.args.getSessionId();
-    void saveWorkflowState(this.args.cwd, sessionId, runtime.state()).catch((err: unknown) => {
-      const reason = err instanceof Error ? err.message : String(err);
-      warnWorkflowPersistenceFailure(
-        join(sessionDir(this.args.cwd, sessionId), "workflow.json"),
-        reason,
-      );
-    });
+    void saveWorkflowState(this.args.cwd, sessionId, runtime.state(), this.args.home).catch(
+      (err: unknown) => {
+        const reason = err instanceof Error ? err.message : String(err);
+        warnWorkflowPersistenceFailure(
+          join(sessionDir(this.args.cwd, sessionId, this.args.home), "workflow.json"),
+          reason,
+        );
+      },
+    );
   }
 
   private attach(workflow: Workflow): void {
@@ -178,7 +183,7 @@ export class WorkflowController {
 
   // Restore a persisted workflow for the current session, if any.
   async resume(): Promise<void> {
-    const state = await loadWorkflowState(this.args.cwd, this.args.getSessionId());
+    const state = await loadWorkflowState(this.args.cwd, this.args.getSessionId(), this.args.home);
     if (state === null || state.completed || state.stack.length === 0) return;
     const rootName = state.stack[0]?.workflow;
     const workflow = rootName !== undefined ? findWorkflow(rootName) : undefined;

tests/unit/workflow-controller.test.ts

@@ -22,6 +22,7 @@ async function withController(
     c: WorkflowController,
     director: { coordinator: WorkflowCoordinator | undefined },
     cwd: string,
+    home: string,
   ) => void | Promise<void>,
 ): Promise<void> {
   const cwd = await mkdtemp(join(tmpdir(), "wf-controller-"));
@@ -38,9 +39,10 @@ async function withController(
         director.coordinator = c;
       },
     }),
+    home,
   });
   try {
-    await fn(controller, director, cwd);
+    await fn(controller, director, cwd, home);
   } finally {
     await flushWorkflowStateWrites(cwd, "session-1", home);
     await rm(cwd, { recursive: true, force: true });
@@ -127,13 +129,13 @@ test("history() entry after workflow completion contains the workflow name and s
 });
 
 test("resume() restores an on-disk workflow snapshot for the session", async () => {
-  await withController([], async (controller, director, cwd) => {
+  await withController([], async (controller, director, cwd, home) => {
     const workflow = findWorkflow("review");
     expect(workflow).toBeDefined();
     const runtime = new WorkflowRuntime(new Map());
     runtime.start(workflow!);
     runtime.advance();
-    await saveWorkflowState(cwd, "session-1", runtime.state());
+    await saveWorkflowState(cwd, "session-1", runtime.state(), home);
 
     await controller.resume();
     expect(controller.isActive()).toBe(true);