Make session persistence and doc sync boundaries explicit

Session persistence was still coupled tightly to doc generation inside
saveSession and deleteSession. This pass extracts small internal helpers
for normalization, raw file writes, docs synchronization, and raw file
removal so the boundary is explicit while public behavior stays the same.

Constraint: saveSession() and deleteSession() had to preserve current observable behavior under the runtime tests
Constraint: This pass had to remain internal to session persistence and avoid a broader lifecycle redesign
Rejected: Introduce a new public persistence API now | broader call-site migration than needed for this cleanup pass
Rejected: Leave file persistence and docs sync interleaved inline | weaker separation of concerns and harder future changes
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep raw session file persistence and docs synchronization separable so future lifecycle changes can move them independently if needed
Tested: bun test tests/runtime.test.ts
Tested: bun run check
Not-tested: Manual host-level save/reset flows outside automated tests

Author: vriesdcrv

analysis/ai-slop-cleanup-plan.md

@@ -81,3 +81,12 @@
 1. Reduce nested inline conditionals in the render helpers without changing emitted markdown.
 2. Prefer simpler section assembly over larger template-string expressions.
 3. Keep file output, headings, and formatting stable under the existing render tests.
+
+## Pass 8 Scope
+- `src/runtime/session.ts`
+- `tests/runtime.test.ts` as behavior lock
+
+## Pass 8 Smell focus
+1. Split raw session persistence from docs synchronization helpers.
+2. Keep the public behavior of `saveSession()` and `deleteSession()` unchanged.
+3. Reduce coupling by making the file-write and docs-sync boundaries explicit.

src/runtime/session.ts

@@ -8,6 +8,34 @@ function now(): string {
   return new Date().toISOString();
 }
 
+function normalizeSession(session: Session): Session {
+  return SessionSchema.parse({
+    ...session,
+    timestamps: {
+      ...session.timestamps,
+      updatedAt: now(),
+    },
+  });
+}
+
+async function writeSessionFile(worktree: string, session: Session): Promise<void> {
+  const sessionPath = getSessionPath(worktree);
+  await mkdir(worktree + "/.flow", { recursive: true });
+  await writeFile(sessionPath, JSON.stringify(session, null, 2) + "\n", "utf8");
+}
+
+async function syncSessionDocs(worktree: string, session: Session): Promise<void> {
+  await renderSessionDocs(worktree, session);
+}
+
+async function removeSessionFile(worktree: string): Promise<void> {
+  await rm(getSessionPath(worktree), { force: true });
+}
+
+async function removeSessionDocs(worktree: string): Promise<void> {
+  await deleteSessionDocs(worktree);
+}
+
 export async function loadSession(worktree: string): Promise<Session | null> {
   const sessionPath = getSessionPath(worktree);
 
@@ -24,24 +52,15 @@ export async function loadSession(worktree: string): Promise<Session | null> {
 }
 
 export async function saveSession(worktree: string, session: Session): Promise<Session> {
-  const sessionPath = getSessionPath(worktree);
-  const normalized = SessionSchema.parse({
-    ...session,
-    timestamps: {
-      ...session.timestamps,
-      updatedAt: now(),
-    },
-  });
-
-  await mkdir(worktree + "/.flow", { recursive: true });
-  await writeFile(sessionPath, JSON.stringify(normalized, null, 2) + "\n", "utf8");
-  await renderSessionDocs(worktree, normalized);
+  const normalized = normalizeSession(session);
+  await writeSessionFile(worktree, normalized);
+  await syncSessionDocs(worktree, normalized);
   return normalized;
 }
 
 export async function deleteSession(worktree: string): Promise<void> {
-  await rm(getSessionPath(worktree), { force: true });
-  await deleteSessionDocs(worktree);
+  await removeSessionFile(worktree);
+  await removeSessionDocs(worktree);
 }
 
 export function createSession(goal: string, planning?: Partial<PlanningContext>): Session {