Keep Flow auto preparation read-only until a real session write occurs

Initialization paths should classify intent without creating workspace
state. Move legacy-session migration workspace creation behind the
legacy-file existence check so `flow_auto_prepare` no longer triggers
`.flow` directory creation as a side effect.

Update regression tests to assert classification remains read-only for
root and root-like worktree inputs.

Constraint: Flow session docs and state must still be materialized on first write path
Rejected: Create .flow during every read attempt | causes incorrect side effects and root-path mkdir failures
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep session-discovery calls side-effect free; reserve workspace creation for write paths
Tested: bun run check; end-to-end tool lifecycle sanity run for worktree '/' and '///'
Not-tested: Manual OpenCode UI session after app restart on all supported host OSes

Author: vriesdcrv

src/runtime/session-workspace.ts

@@ -81,30 +81,30 @@ export async function writeSessionFile(worktree: string, session: Session): Prom
 }
 
 export async function migrateLegacySessionIfNeeded(worktree: string): Promise<void> {
-  await ensureWorkspace(worktree);
-
   if (await readActiveSessionId(worktree)) {
     return;
   }
 
   const legacySessionPath = getLegacySessionPath(worktree);
+  let raw: string;
 
   try {
-    const raw = await readFile(legacySessionPath, "utf8");
-    const session = SessionSchema.parse(JSON.parse(raw));
-
-    await writeSessionFile(worktree, session);
-    await renderSessionDocs(worktree, session);
-    await writeActiveSessionId(worktree, session.id);
-    await rm(legacySessionPath, { force: true });
-    await rm(getLegacyDocsDir(worktree), { recursive: true, force: true });
+    raw = await readFile(legacySessionPath, "utf8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
       return;
     }
 
     throw error;
   }
+
+  const session = SessionSchema.parse(JSON.parse(raw));
+  await ensureWorkspace(worktree);
+  await writeSessionFile(worktree, session);
+  await renderSessionDocs(worktree, session);
+  await writeActiveSessionId(worktree, session.id);
+  await rm(legacySessionPath, { force: true });
+  await rm(getLegacyDocsDir(worktree), { recursive: true, force: true });
 }
 
 export async function resolveActiveSessionId(worktree: string): Promise<string | null> {

tests/runtime.test.ts

@@ -606,7 +606,7 @@ describe("runtime transitions", () => {
     expect(parsed.goal).toBe("Improve Flow recovery behavior");
   });
 
-  test("flow_auto_prepare falls back to context.directory when worktree resolves to root", async () => {
+  test("flow_auto_prepare classification is read-only when worktree resolves to root", async () => {
     const directory = makeTempDir();
     const tools = createTestTools();
 
@@ -618,10 +618,10 @@ describe("runtime transitions", () => {
 
     expect(parsed.status).toBe("ok");
     expect(parsed.mode).toBe("start_new_goal");
-    await expect(readFile(join(directory, ".flow", ".gitignore"), "utf8")).resolves.toContain("sessions/");
+    await expect(readFile(join(directory, ".flow", ".gitignore"), "utf8")).rejects.toThrow();
   });
 
-  test("flow_auto_prepare treats root-like worktree aliases as root and falls back to context.directory", async () => {
+  test("flow_auto_prepare classification is read-only for root-like worktree aliases", async () => {
     const directory = makeTempDir();
     const tools = createTestTools();
 
@@ -633,7 +633,7 @@ describe("runtime transitions", () => {
 
     expect(parsed.status).toBe("ok");
     expect(parsed.mode).toBe("start_new_goal");
-    await expect(readFile(join(directory, ".flow", ".gitignore"), "utf8")).resolves.toContain("sessions/");
+    await expect(readFile(join(directory, ".flow", ".gitignore"), "utf8")).rejects.toThrow();
   });
 
   test("flow_plan_start persists under context.directory when worktree resolves to root", async () => {