Inject home into session dual-read and test isolation

Legacy sessions are discovered under cwd and the shared git project root so
worktree resumes find main-repo .agent-state. Optional home on store, workflow
state, and seeded approvals keeps unit tests out of the real ~/.corbits tree.

Author: TheGreatAxios

docs/IMPLEMENTATION.md

@@ -309,7 +309,8 @@ Session runtime state lives under the global projects tree (not in the repo):
 
 - `~/.corbits/projects/<project-key>/<session-id>/run.json` — `RunState`
 - `~/.corbits/projects/<project-key>/<session-id>/context/` — git-backed conversation context (`@intx/storage-isogit`)
-- Project key: slug + short hash of the git toplevel realpath (or workspace realpath when not a git tree), so main + worktrees share resume history
+- Project key: slug + short hash of the shared git root (from `--git-common-dir`, so main + linked worktrees share one key; workspace realpath when not a git tree)
+
 - Migration: if a session exists only under in-repo `.agent-state/<session-id>/`, it is moved into the global tree on open/list
 - Atomic JSON writes with schema validation on load
 

src/permission/store.ts

@@ -10,10 +10,11 @@ import { sessionDir } from "../session/index.js";
 import { SETTINGS_DIR_NAME } from "../branding.js";
 
 // Approvals are remembered per session, alongside the run state.
-function storePath(cwd: string, sessionId: string): string {
-  return join(sessionDir(cwd, sessionId), "permissions.json");
+function storePath(cwd: string, sessionId: string, home?: string): string {
+  return join(sessionDir(cwd, sessionId, home), "permissions.json");
 }
 
+
 // Persistent project grants live next to the project's settings. The file is
 // gitignored (machine-local), so a teammate who pulls the repo never silently
 // inherits another machine's auto-approvals.
@@ -104,10 +105,15 @@ function chainObjectWrite(
   return chained;
 }
 
-export async function loadApprovals(cwd: string, sessionId: string): Promise<Approval[]> {
-  return readApprovalsField(storePath(cwd, sessionId), "approvals");
+export async function loadApprovals(
+  cwd: string,
+  sessionId: string,
+  home?: string,
+): Promise<Approval[]> {
+  return readApprovalsField(storePath(cwd, sessionId, home), "approvals");
 }
 
+
 export async function loadProjectApprovals(cwd: string): Promise<Approval[]> {
   return readApprovalsField(projectStorePath(cwd), "approvals");
 }

src/session/index.ts

@@ -76,6 +76,19 @@ function legacySessionCandidates(cwd: string, sessionId: string): string[] {
   return [underCwd, join(projectRoot, LEGACY_SESSION_BASE, sessionId)];
 }
 
+/** Legacy roots that may still hold unmigrated sessions (cwd + project root). */
+function legacySessionRoots(cwd: string): string[] {
+  const underCwd = join(cwd, LEGACY_SESSION_BASE);
+  const projectRoot = projectRootFor(cwd);
+  if (realpathSafe(projectRoot) === realpathSafe(cwd)) return [underCwd];
+  return [underCwd, join(projectRoot, LEGACY_SESSION_BASE)];
+}
+
+function legacyLatestCandidates(cwd: string): string[] {
+  return legacySessionRoots(cwd).map((base) => join(base, "latest"));
+}
+
+
 function realpathSafe(path: string): string {
   try {
     return realpathSync(path);
@@ -165,22 +178,26 @@ export async function resolveLatestSession(
       contextDir: sessionContextDir(cwd, sessionId, home),
     };
   } catch {
-    // Fall back: legacy latest symlink under .agent-state, then migrate.
-    try {
-      const legacyLink = join(cwd, LEGACY_SESSION_BASE, "latest");
-      const sessionId = await readlink(legacyLink);
-      const dir = await migrateLegacySessionIfNeeded(cwd, sessionId, home);
-      return {
-        sessionId,
-        dir,
-        contextDir: sessionContextDir(cwd, sessionId, home),
-      };
-    } catch {
-      return null;
+    // Fall back: legacy latest under cwd, then under the git project root
+    // (worktree cwd may not have its own .agent-state/latest).
+    for (const legacyLink of legacyLatestCandidates(cwd)) {
+      try {
+        const sessionId = await readlink(legacyLink);
+        const dir = await migrateLegacySessionIfNeeded(cwd, sessionId, home);
+        return {
+          sessionId,
+          dir,
+          contextDir: sessionContextDir(cwd, sessionId, home),
+        };
+      } catch {
+        // try next candidate
+      }
     }
+    return null;
   }
 }
 
+
 export type SessionSummary = {
   sessionId: string;
   task: string;
@@ -193,7 +210,7 @@ const SESSION_ID_RE =
 
 async function collectSessionIds(cwd: string, home: string): Promise<string[]> {
   const ids = new Set<string>();
-  const roots = [projectSessionsRoot(cwd, home), join(cwd, LEGACY_SESSION_BASE)];
+  const roots = [projectSessionsRoot(cwd, home), ...legacySessionRoots(cwd)];
   for (const base of roots) {
     let entries: string[];
     try {
@@ -209,6 +226,7 @@ async function collectSessionIds(cwd: string, home: string): Promise<string[]> {
   return [...ids];
 }
 
+
 /** List on-disk sessions for a project, newest first. */
 export async function listSessions(cwd: string, home: string = homedir()): Promise<SessionSummary[]> {
   const entries = await collectSessionIds(cwd, home);

src/session/runtime-assembly.test.ts

@@ -53,25 +53,26 @@ describe("buildSubAgentProvider", () => {
 
 describe("loadSeededApprovals merge order", () => {
   let cwd = "";
+  let home = "";
   let sessionId = "";
 
   afterEach(async () => {
-    if (cwd !== "" && sessionId !== "") {
-      await rm(sessionDir(cwd, sessionId), { recursive: true, force: true }).catch(() => undefined);
-    }
     if (cwd !== "") await rm(cwd, { recursive: true, force: true });
+    if (home !== "") await rm(home, { recursive: true, force: true });
     cwd = "";
+    home = "";
     sessionId = "";
   });
 
   test("orders session, then project, before empty global/provider-model layers", async () => {
     cwd = await mkdtemp(join(tmpdir(), "runtime-assembly-"));
+    home = await mkdtemp(join(tmpdir(), "runtime-assembly-home-"));
     sessionId = generateSessionId();
-    await initSessionDir(cwd, sessionId);
+    await initSessionDir(cwd, sessionId, home);
 
-    await mkdir(sessionDir(cwd, sessionId), { recursive: true });
+    await mkdir(sessionDir(cwd, sessionId, home), { recursive: true });
     await writeFile(
-      join(sessionDir(cwd, sessionId), "permissions.json"),
+      join(sessionDir(cwd, sessionId, home), "permissions.json"),
       JSON.stringify({
         approvals: [{ tool: "run_shell", pattern: "session npm *" }],
       }),
@@ -81,13 +82,14 @@ describe("loadSeededApprovals merge order", () => {
       pattern: "project npm *",
     });
 
-    const seeded = await loadSeededApprovals(cwd, sessionId);
+    const seeded = await loadSeededApprovals(cwd, sessionId, home);
 
     // Session must lead so gate first-match prefers the tighter session grant.
     // Global / provider-model layers may contain real-home entries; assert prefix only.
     expect(seeded[0]).toEqual({ tool: "run_shell", pattern: "session npm *" });
     expect(seeded[1]).toEqual({ tool: "run_shell", pattern: "project npm *" });
   });
+
 });
 
 describe("createApprovalPersist", () => {

src/session/runtime-assembly.ts

@@ -71,8 +71,12 @@ export function buildSubAgentProvider(config: SubAgentProviderConfig): SubAgentP
 // ---------------------------------------------------------------------------
 
 /** Session → project → global → provider-model merge order (first match wins in gate). */
-export async function loadSeededApprovals(cwd: string, sessionId: string): Promise<Approval[]> {
-  const sessionApprovals = await loadApprovals(cwd, sessionId);
+export async function loadSeededApprovals(
+  cwd: string,
+  sessionId: string,
+  home?: string,
+): Promise<Approval[]> {
+  const sessionApprovals = await loadApprovals(cwd, sessionId, home);
   const [projectApprovals, globalApprovals, providerModelApprovals] = await Promise.all([
     loadProjectApprovals(cwd),
     loadGlobalApprovals(),
@@ -86,6 +90,7 @@ export async function loadSeededApprovals(cwd: string, sessionId: string): Promi
   ];
 }
 
+
 /**
  * Route a gate-persisted grant to the store its scope selects.
  * Session grants never reach here — the gate keeps those in memory only.

src/workflows/state.ts

@@ -46,8 +46,9 @@ export async function saveWorkflowState(
   cwd: string,
   sessionId: string,
   state: WorkflowState,
+  home?: string,
 ): Promise<void> {
-  const path = workflowStatePath(cwd, sessionId);
+  const path = workflowStatePath(cwd, sessionId, home);
   const payload = JSON.stringify(state, null, 2);
   const run = (): Promise<void> => atomicWrite(path, payload);
   const chained = (writeChains.get(path) ?? Promise.resolve()).then(run, run);
@@ -56,16 +57,22 @@ export async function saveWorkflowState(
 }
 
 /** Await any in-flight save for this session (used by tests and shutdown paths). */
-export async function flushWorkflowStateWrites(cwd: string, sessionId: string): Promise<void> {
-  const path = workflowStatePath(cwd, sessionId);
+export async function flushWorkflowStateWrites(
+  cwd: string,
+  sessionId: string,
+  home?: string,
+): Promise<void> {
+  const path = workflowStatePath(cwd, sessionId, home);
   await (writeChains.get(path) ?? Promise.resolve());
 }
 
 export async function loadWorkflowState(
   cwd: string,
   sessionId: string,
+  home?: string,
 ): Promise<WorkflowState | null> {
-  const path = workflowStatePath(cwd, sessionId);
+  const path = workflowStatePath(cwd, sessionId, home);
+
   try {
     const raw = await readFile(path, "utf8");
     const parsed = JSON.parse(raw);

tests/unit/workflow-controller.test.ts

@@ -25,7 +25,8 @@ async function withController(
   ) => void | Promise<void>,
 ): Promise<void> {
   const cwd = await mkdtemp(join(tmpdir(), "wf-controller-"));
-  await initSessionDir(cwd, "session-1");
+  const home = await mkdtemp(join(tmpdir(), "wf-controller-home-"));
+  await initSessionDir(cwd, "session-1", home);
   const director = { coordinator: undefined as WorkflowCoordinator | undefined };
   const controller = new WorkflowController({
     cwd,
@@ -41,11 +42,13 @@ async function withController(
   try {
     await fn(controller, director, cwd);
   } finally {
-    await flushWorkflowStateWrites(cwd, "session-1");
+    await flushWorkflowStateWrites(cwd, "session-1", home);
     await rm(cwd, { recursive: true, force: true });
+    await rm(home, { recursive: true, force: true });
   }
 }
 
+
 test("starting a workflow attaches a coordinator to the director", async () => {
   await withController([], async (controller, director, _cwd) => {
     const msg = controller.start("review");

tests/unit/workflows-runtime-persistence.test.ts

@@ -10,6 +10,7 @@ import { loadWorkflowState, saveWorkflowState } from "../../src/workflows/state.
 
 test("WorkflowRuntime resumes from workflow.json written mid sub-workflow chain", async () => {
   const cwd = await mkdtemp(join(tmpdir(), "wf-runtime-persist-"));
+  const home = await mkdtemp(join(tmpdir(), "wf-runtime-persist-home-"));
   try {
     const build = findWorkflow("build");
     expect(build).toBeDefined();
@@ -23,8 +24,8 @@ test("WorkflowRuntime resumes from workflow.json written mid sub-workflow chain"
     expect(mid).toBeDefined();
     expect(mid).not.toBe(first);
 
-    await saveWorkflowState(cwd, "session-1", runtime.state());
-    const loaded = await loadWorkflowState(cwd, "session-1");
+    await saveWorkflowState(cwd, "session-1", runtime.state(), home);
+    const loaded = await loadWorkflowState(cwd, "session-1", home);
     expect(loaded).toEqual(runtime.state());
 
     const resumed = new WorkflowRuntime(new Map());
@@ -34,5 +35,6 @@ test("WorkflowRuntime resumes from workflow.json written mid sub-workflow chain"
     expect(resumed.isActive()).toBe(true);
   } finally {
     await rm(cwd, { recursive: true, force: true });
+    await rm(home, { recursive: true, force: true });
   }
 });

tests/unit/workflows-state.test.ts

@@ -18,36 +18,38 @@ const sampleState: WorkflowState = {
 
 describe("workflow state persistence", () => {
   let cwd: string;
+  let home: string;
 
   beforeEach(async () => {
     cwd = await mkdtemp(join(tmpdir(), "wf-state-"));
+    home = await mkdtemp(join(tmpdir(), "wf-state-home-"));
   });
 
   afterEach(async () => {
-    await rm(sessionDir(cwd, SESSION_ID), { recursive: true, force: true }).catch(() => undefined);
     await rm(cwd, { recursive: true, force: true });
+    await rm(home, { recursive: true, force: true });
   });
 
   test("saveWorkflowState then loadWorkflowState returns an equal object", async () => {
-    await saveWorkflowState(cwd, SESSION_ID, sampleState);
-    const loaded = await loadWorkflowState(cwd, SESSION_ID);
+    await saveWorkflowState(cwd, SESSION_ID, sampleState, home);
+    const loaded = await loadWorkflowState(cwd, SESSION_ID, home);
     expect(loaded).toEqual(sampleState);
   });
 
   test("loadWorkflowState on missing file returns null", async () => {
-    expect(await loadWorkflowState(cwd, "nope")).toBeNull();
+    expect(await loadWorkflowState(cwd, "nope", home)).toBeNull();
   });
 
   test("loadWorkflowState with truncated JSON returns null instead of throwing", async () => {
-    const dir = sessionDir(cwd, SESSION_ID);
+    const dir = sessionDir(cwd, SESSION_ID, home);
     await mkdir(dir, { recursive: true });
     await writeFile(join(dir, "workflow.json"), '{ "completed": false, "stack": [');
 
-    expect(await loadWorkflowState(cwd, SESSION_ID)).toBeNull();
+    expect(await loadWorkflowState(cwd, SESSION_ID, home)).toBeNull();
   });
 
   test("loadWorkflowState rejects invalid stepIndex values", async () => {
-    const dir = sessionDir(cwd, SESSION_ID);
+    const dir = sessionDir(cwd, SESSION_ID, home);
     await mkdir(dir, { recursive: true });
     await writeFile(
       join(dir, "workflow.json"),
@@ -57,11 +59,11 @@ describe("workflow state persistence", () => {
       }),
     );
 
-    expect(await loadWorkflowState(cwd, SESSION_ID)).toBeNull();
+    expect(await loadWorkflowState(cwd, SESSION_ID, home)).toBeNull();
   });
 
   test("loadWorkflowState rejects unknown step statuses", async () => {
-    const dir = sessionDir(cwd, SESSION_ID);
+    const dir = sessionDir(cwd, SESSION_ID, home);
     await mkdir(dir, { recursive: true });
     await writeFile(
       join(dir, "workflow.json"),
@@ -71,30 +73,30 @@ describe("workflow state persistence", () => {
       }),
     );
 
-    expect(await loadWorkflowState(cwd, SESSION_ID)).toBeNull();
+    expect(await loadWorkflowState(cwd, SESSION_ID, home)).toBeNull();
   });
 
   test("saveWorkflowState leaves no .tmp file after successful write", async () => {
-    await saveWorkflowState(cwd, SESSION_ID, sampleState);
-    const files = await readdir(sessionDir(cwd, SESSION_ID));
+    await saveWorkflowState(cwd, SESSION_ID, sampleState, home);
+    const files = await readdir(sessionDir(cwd, SESSION_ID, home));
     expect(files.filter((f) => f.includes(".tmp"))).toHaveLength(0);
   });
 
   test("saveWorkflowState overwrites a pre-existing file with well-formed JSON", async () => {
-    await saveWorkflowState(cwd, SESSION_ID, sampleState);
+    await saveWorkflowState(cwd, SESSION_ID, sampleState, home);
     const updated: WorkflowState = { ...sampleState, completed: true, stack: [] };
-    await saveWorkflowState(cwd, SESSION_ID, updated);
-    const raw = await readFile(join(sessionDir(cwd, SESSION_ID), "workflow.json"), "utf8");
+    await saveWorkflowState(cwd, SESSION_ID, updated, home);
+    const raw = await readFile(join(sessionDir(cwd, SESSION_ID, home), "workflow.json"), "utf8");
     expect(JSON.parse(raw)).toEqual(updated);
   });
 
   test("concurrent saveWorkflowState calls serialize and leave valid JSON", async () => {
     await Promise.all([
-      saveWorkflowState(cwd, SESSION_ID, sampleState),
-      saveWorkflowState(cwd, SESSION_ID, { ...sampleState, completed: true }),
-      saveWorkflowState(cwd, SESSION_ID, sampleState),
+      saveWorkflowState(cwd, SESSION_ID, sampleState, home),
+      saveWorkflowState(cwd, SESSION_ID, { ...sampleState, completed: true }, home),
+      saveWorkflowState(cwd, SESSION_ID, sampleState, home),
     ]);
-    const loaded = await loadWorkflowState(cwd, SESSION_ID);
+    const loaded = await loadWorkflowState(cwd, SESSION_ID, home);
     expect(loaded).not.toBeNull();
     expect(loaded?.stack).toEqual(sampleState.stack);
   });