@dreki-gg/pi-plan-mode 0.15.1 → 0.17.0

package/extensions/plan-mode/index.ts

@@ -28,20 +28,26 @@ import {
 } from './constants.js';
 import type { ThinkingLevel } from './types.js';
 import { PlanModeState } from './state.js';
+import { makePlanRuntime } from './effects/runtime.js';
 import { loadHandoff, readAndClearExecPending } from './storage/plan-storage.js';
 import { readTasksJsonl, writeTasksJsonl } from './storage/task-storage.js';
 import { upsertPlanEntry } from './storage/plans-manifest.js';
 import { updateUI } from './ui.js';
 import { buildPlanModePrompt, buildExecutionPrompt } from './prompts.js';
 import { filterExecutionMessages, filterStalePlanMessages } from './context-filter.js';
+import { activeTasksResolved, deferredTasks } from './task-status.js';
 import { enterPlanMode, exitPlanMode, switchModel } from './phase-transitions.js';
 import { resumePlan, executeInNewSession } from './resume.js';
 import { registerSubmitPlanTool } from './tools/submit-plan.js';
+import { registerPreviewPrototypeTool } from './tools/preview-prototype.js';
 import { registerUpdateTaskTool } from './tools/update-task.js';
+import { registerAddTaskTool } from './tools/add-task.js';
 import { isSafeCommand, isPlanPath } from './utils.js';
 
 export default function planMode(pi: ExtensionAPI): void {
   const state = new PlanModeState();
+  // Build the live Effect runtime once; all storage I/O runs through this bridge.
+  const runPlanIO = makePlanRuntime();
 
   // ── Flag ──────────────────────────────────────────────────────────────────
   pi.registerFlag('plan', {
@@ -51,7 +57,7 @@ export default function planMode(pi: ExtensionAPI): void {
   });
 
   // ── Tools ─────────────────────────────────────────────────────────────────
-  registerSubmitPlanTool(pi, {
+  registerSubmitPlanTool(pi, runPlanIO, {
     onPlanSubmitted: (dir, submittedPlan) => {
       state.planDir = dir;
       state.plan = submittedPlan;
@@ -59,6 +65,8 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  registerPreviewPrototypeTool(pi, runPlanIO);
+
   registerUpdateTaskTool(pi, {
     getPlan: () => state.plan,
     onTaskUpdated: async (taskId, status, notes) => {
@@ -68,15 +76,38 @@ export default function planMode(pi: ExtensionAPI): void {
       task.status = status;
       task.updated_at = new Date().toISOString();
       if (notes) task.notes = notes;
-      await writeTasksJsonl(
-        state.planDir,
-        {
-          _type: 'meta',
-          title: state.plan.title,
-          plan_name: state.plan.planName,
-          created_at: state.plan.tasks[0]?.created_at ?? task.updated_at,
-        },
-        state.plan.tasks,
+      await runPlanIO(
+        writeTasksJsonl(
+          state.planDir,
+          {
+            _type: 'meta',
+            title: state.plan.title,
+            plan_name: state.plan.planName,
+            created_at: state.plan.tasks[0]?.created_at ?? task.updated_at,
+          },
+          state.plan.tasks,
+        ),
+      );
+      state.persist(pi);
+    },
+  });
+
+  registerAddTaskTool(pi, {
+    getPlan: () => state.plan,
+    onTaskAdded: async (task) => {
+      if (!state.plan || !state.planDir) return;
+      state.plan.tasks.push(task);
+      await runPlanIO(
+        writeTasksJsonl(
+          state.planDir,
+          {
+            _type: 'meta',
+            title: state.plan.title,
+            plan_name: state.plan.planName,
+            created_at: state.plan.tasks[0]?.created_at ?? task.created_at,
+          },
+          state.plan.tasks,
+        ),
       );
       state.persist(pi);
     },
@@ -89,7 +120,7 @@ export default function planMode(pi: ExtensionAPI): void {
     handler: async (args, ctx) => {
       const trimmed = args?.trim();
       if (trimmed === 'resume') {
-        await resumePlan(state, pi, ctx);
+        await resumePlan(state, pi, ctx, runPlanIO);
         return;
       }
       if (state.planEnabled || state.executing) {
@@ -112,7 +143,7 @@ export default function planMode(pi: ExtensionAPI): void {
       const first =
         state.plan.tasks.find((task) => task.status === 'pending')?.id ?? state.plan.tasks[0]?.id;
       const kickoff = `Execute the following plan: "${state.plan.title}"\n\nTasks:\n${taskList}\n\nStart with ${first}. Call update_task after completing each task.`;
-      await executeInNewSession(ctx, state.planDir, state.plan, kickoff);
+      await executeInNewSession(ctx, runPlanIO, state.planDir, state.plan, kickoff);
     },
   });
 
@@ -123,9 +154,18 @@ export default function planMode(pi: ExtensionAPI): void {
         ctx.ui.notify('No plan yet. Use /plan to start planning.', 'info');
         return;
       }
-      const statusIcon = { pending: '○', done: '✓', skipped: '⊘', blocked: '✗' } as const;
+      const statusIcon = {
+        pending: '○',
+        done: '✓',
+        skipped: '⊘',
+        blocked: '✗',
+        deferred: '⏸',
+      } as const;
       const list = state.plan.tasks
-        .map((s) => `${s.id}. ${statusIcon[s.status]} ${s.description}`)
+        .map((s) => {
+          const marker = s.origin === 'discovered' ? ' (discovered)' : '';
+          return `${s.id}. ${statusIcon[s.status]} ${s.description}${marker}`;
+        })
         .join('\n');
       ctx.ui.notify(`Plan Progress:\n${list}`, 'info');
     },
@@ -207,10 +247,15 @@ export default function planMode(pi: ExtensionAPI): void {
 
       if (blocked.length > 0) {
         const bs = blocked[0];
-        const info = bs.notes
+        let info = bs.notes
           ? `Task ${bs.id}: ${bs.description}\nReason: ${bs.notes}`
           : `Task ${bs.id}: ${bs.description}`;
 
+        const pausedFollowups = deferredTasks(state.plan.tasks);
+        if (pausedFollowups.length > 0) {
+          info += `\n\nNote: ${pausedFollowups.length} follow-up(s) captured for later review (/plan resume).`;
+        }
+
         const choice = await ctx.ui.select(`Task blocked — ${info}\n\nWhat next?`, [
           'Skip this task',
           'Provide instructions',
@@ -221,15 +266,17 @@ export default function planMode(pi: ExtensionAPI): void {
         if (choice === 'Skip this task') {
           bs.status = 'skipped';
           bs.updated_at = new Date().toISOString();
-          await writeTasksJsonl(
-            state.planDir!,
-            {
-              _type: 'meta',
-              title: state.plan.title,
-              plan_name: state.plan.planName,
-              created_at: state.plan.tasks[0]?.created_at ?? bs.updated_at,
-            },
-            state.plan.tasks,
+          await runPlanIO(
+            writeTasksJsonl(
+              state.planDir!,
+              {
+                _type: 'meta',
+                title: state.plan.title,
+                plan_name: state.plan.planName,
+                created_at: state.plan.tasks[0]?.created_at ?? bs.updated_at,
+              },
+              state.plan.tasks,
+            ),
           );
           updateUI(state, ctx);
           state.persist(pi);
@@ -244,15 +291,17 @@ export default function planMode(pi: ExtensionAPI): void {
             bs.status = 'pending';
             bs.notes = undefined;
             bs.updated_at = new Date().toISOString();
-            await writeTasksJsonl(
-              state.planDir!,
-              {
-                _type: 'meta',
-                title: state.plan.title,
-                plan_name: state.plan.planName,
-                created_at: state.plan.tasks[0]?.created_at ?? bs.updated_at,
-              },
-              state.plan.tasks,
+            await runPlanIO(
+              writeTasksJsonl(
+                state.planDir!,
+                {
+                  _type: 'meta',
+                  title: state.plan.title,
+                  plan_name: state.plan.planName,
+                  created_at: state.plan.tasks[0]?.created_at ?? bs.updated_at,
+                },
+                state.plan.tasks,
+              ),
             );
             updateUI(state, ctx);
             state.persist(pi);
@@ -275,22 +324,76 @@ export default function planMode(pi: ExtensionAPI): void {
         }
       }
 
+      // ── Discovered follow-ups checkpoint ──
+      // Active work is done but the agent captured deferred follow-ups: keep the
+      // plan in-progress and inform the user, who decides via /plan resume.
+      const deferred = deferredTasks(state.plan.tasks);
+      if (activeTasksResolved(state.plan.tasks) && deferred.length > 0) {
+        if (state.planDir) {
+          await runPlanIO(
+            writeTasksJsonl(
+              state.planDir,
+              {
+                _type: 'meta',
+                title: state.plan.title,
+                plan_name: state.plan.planName,
+                created_at: state.plan.tasks[0]?.created_at ?? new Date().toISOString(),
+              },
+              state.plan.tasks,
+            ),
+          );
+        }
+
+        const followups = deferred
+          .map((s) => {
+            const label = `${s.id}. ⏸ ${s.description}`;
+            return s.notes ? `${label}\n   ${s.notes}` : label;
+          })
+          .join('\n');
+        const followSummary = [
+          `**Plan tasks complete — ${deferred.length} follow-up(s) discovered (kept for later)**`,
+          '',
+          'Run `/plan resume` to review and decide whether to implement them.',
+          '',
+          '## Discovered follow-ups',
+          '',
+          followups,
+        ].join('\n');
+        pi.sendMessage(
+          { customType: 'plan-followups', content: followSummary, display: true },
+          { triggerTurn: false },
+        );
+
+        const { previousModel: dpm, previousThinking: dpt } = state;
+        state.exitPreservingPlan();
+        pi.setActiveTools(EXEC_TOOLS);
+        if (dpm) await switchModel(pi, ctx, dpm);
+        if (dpt) pi.setThinkingLevel(dpt);
+        updateUI(state, ctx);
+        state.persist(pi);
+        return;
+      }
+
       // Check completion
       const allResolved = state.plan.tasks.every(
         (s) => s.status === 'done' || s.status === 'skipped',
       );
       if (allResolved) {
         if (state.planDir) {
-          await upsertPlanEntry(state.plan.planName, { status: 'done', title: state.plan.title });
-          await writeTasksJsonl(
-            state.planDir,
-            {
-              _type: 'meta',
-              title: state.plan.title,
-              plan_name: state.plan.planName,
-              created_at: state.plan.tasks[0]?.created_at ?? new Date().toISOString(),
-            },
-            state.plan.tasks,
+          await runPlanIO(
+            upsertPlanEntry(state.plan.planName, { status: 'done', title: state.plan.title }),
+          );
+          await runPlanIO(
+            writeTasksJsonl(
+              state.planDir,
+              {
+                _type: 'meta',
+                title: state.plan.title,
+                plan_name: state.plan.planName,
+                created_at: state.plan.tasks[0]?.created_at ?? new Date().toISOString(),
+              },
+              state.plan.tasks,
+            ),
           );
         }
         const done = state.plan.tasks.filter((s) => s.status === 'done').length;
@@ -335,8 +438,8 @@ export default function planMode(pi: ExtensionAPI): void {
       return;
     }
 
-    // Plan submitted — user can review plan.html then /plan-exec or type naturally.
-    // No menu needed: plan.jsonl + plan.html are the source of truth.
+    // Plan submitted — user can /plan-exec or type naturally.
+    // No menu needed: plan.jsonl + HANDOFF.md are the source of truth.
   });
 
   // ── Event: session restore ────────────────────────────────────────────────
@@ -348,16 +451,16 @@ export default function planMode(pi: ExtensionAPI): void {
     );
 
     // Check for exec-pending handoff from planning session
-    const pending = await readAndClearExecPending();
+    const pending = await runPlanIO(readAndClearExecPending());
     if (pending) {
       state.planDir = pending.planDir;
       {
-        const snapshot = await readTasksJsonl(pending.planDir);
+        const snapshot = await runPlanIO(readTasksJsonl(pending.planDir));
         state.plan = snapshot
           ? {
               title: snapshot.meta.title,
               planName: snapshot.meta.plan_name,
-              handoff: (await loadHandoff(pending.planDir)) ?? '',
+              handoff: (await runPlanIO(loadHandoff(pending.planDir))) ?? '',
               tasks: snapshot.tasks,
             }
           : undefined;

package/extensions/plan-mode/prompts.ts

@@ -18,7 +18,7 @@ Restrictions:
 Your job is to reach shared understanding before formalizing a plan:
 1. Understand the user's intent through dialogue. Push back on weak assumptions, name trade-offs, and ask clarifying questions when needed.
 2. Investigate the codebase with read-only tools. Use questionnaire when explicit choices are needed.
-3. Maintain .plans/<plan-name>/context.md with the write tool as the living planning context in caveman-lite style: professional, tight, no filler. Capture intent, decisions, constraints, open questions, and discarded options.
+3. Maintain a living .plans/<plan-name>/context.md as you converge — the planning-context skill covers what to capture and how.
 4. Only call submit_plan after the user and agent have converged on the approach.
 
 When you are ready to finalize the plan, call submit_plan with:
@@ -26,13 +26,14 @@ When you are ready to finalize the plan, call submit_plan with:
 - title: a human-readable plan title
 - handoff: a markdown document that explains what is changing, why it matters, approach, decisions, file paths, APIs, patterns, constraints, and gotchas
 - tasks: an array of tasks with id (e.g. "t-001"), description (≤60 chars), optional details, and optional depends_on task IDs
-- prototype: optional Pug markup for a creative prototype section in the generated plan.html
 
 Plan weight:
 - **Delegation plans** (different agent/human executes): include full details in each task so an executor with zero context can follow them.
 - **Self-execution plans** (you plan and execute in the same session): use lightweight checklist-style tasks — just id + description, skip details. The handoff doc carries the real context.
 
-submit_plan is finalization, not the starting point. The generated plan.html is written but not opened automatically.
+submit_plan is finalization, not the starting point. It records tasks and the handoff — it does not generate HTML.
+
+For visual/UI/layout/style work, build a prototype with preview_prototype DURING planning, before submit_plan, so the user can react to the visual before the plan hardens. The visual-prototype skill covers when and how.
 
 When facing a significant technical decision with multiple viable approaches (architecture, API design, implementation strategy), use the technical-options skill: you generate the competing proposals yourself, then use the subagent tool to fan out voting agents for evaluation. Do not delegate the entire workflow to a subagent — you are the planner, you drive the process.`;
 }
@@ -62,6 +63,7 @@ Rules:
 - Do NOT run diagnostics, linters, test suites, or skills unless a task explicitly asks for it
 - Do NOT explore the codebase beyond what the current task requires
 - Do NOT deviate from the plan — if something seems wrong, call update_task with status "blocked"
+- If you notice worthwhile work OUTSIDE the current plan, call add_task to capture it as a deferred follow-up, then keep going. Do NOT implement discovered work in this run — the user reviews follow-ups later via /plan resume.
 
 ## Current task
 ${currentTask.id}: ${currentTask.description}${currentDetails}

package/extensions/plan-mode/resume.ts

@@ -9,11 +9,13 @@ import type {
 } from '@earendil-works/pi-coding-agent';
 import type { PlanModeState } from './state.js';
 import type { PlanData } from './types.js';
+import type { RunPlanIO } from './effects/runtime.js';
 import { EXEC_THINKING, EXEC_MODEL_OPTIONS } from './constants.js';
 import { readPlansManifest } from './storage/plans-manifest.js';
 import { loadHandoff, writeExecPending } from './storage/plan-storage.js';
 import { readTasksJsonl, writeTasksJsonl } from './storage/task-storage.js';
 import { enterPlanMode } from './phase-transitions.js';
+import { reactivateForExecution } from './task-status.js';
 
 export async function pickExecutionModel(
   ctx: ExtensionContext,
@@ -26,6 +28,7 @@ export async function pickExecutionModel(
 
 export async function executeInNewSession(
   ctx: ExtensionCommandContext,
+  runPlanIO: RunPlanIO,
   dir: string,
   _planData: PlanData,
   kickoff: string,
@@ -33,7 +36,7 @@ export async function executeInNewSession(
   const selectedModel = await pickExecutionModel(ctx);
   if (!selectedModel) return;
 
-  await writeExecPending(dir, { model: selectedModel, thinking: EXEC_THINKING });
+  await runPlanIO(writeExecPending(dir, { model: selectedModel, thinking: EXEC_THINKING }));
   const parentSession = ctx.sessionManager.getSessionFile();
 
   await ctx.newSession({
@@ -48,8 +51,9 @@ export async function resumePlan(
   state: PlanModeState,
   pi: ExtensionAPI,
   ctx: ExtensionCommandContext,
+  runPlanIO: RunPlanIO,
 ): Promise<void> {
-  const manifest = await readPlansManifest();
+  const manifest = await runPlanIO(readPlansManifest());
   const inProgress = manifest.filter((entry) => entry.status === 'in-progress');
 
   if (inProgress.length === 0) {
@@ -65,7 +69,7 @@ export async function resumePlan(
 
   const planName = choice.split(' — ')[0];
   const dir = `.plans/${planName}`;
-  const snapshot = await readTasksJsonl(dir);
+  const snapshot = await runPlanIO(readTasksJsonl(dir));
 
   if (!snapshot) {
     ctx.ui.notify(`Could not load ${dir}/tasks.jsonl`, 'error');
@@ -76,7 +80,7 @@ export async function resumePlan(
   state.plan = {
     title: snapshot.meta.title,
     planName: snapshot.meta.plan_name,
-    handoff: (await loadHandoff(dir)) ?? '',
+    handoff: (await runPlanIO(loadHandoff(dir))) ?? '',
     tasks: snapshot.tasks,
   };
 
@@ -85,8 +89,9 @@ export async function resumePlan(
   ).length;
   const pendingCount = state.plan.tasks.filter((task) => task.status === 'pending').length;
   const blockedCount = state.plan.tasks.filter((task) => task.status === 'blocked').length;
+  const deferredCount = state.plan.tasks.filter((task) => task.status === 'deferred').length;
 
-  if (pendingCount === 0 && blockedCount === 0) {
+  if (pendingCount === 0 && blockedCount === 0 && deferredCount === 0) {
     ctx.ui.notify(
       `Plan "${state.plan.title}" is already complete (${doneCount}/${state.plan.tasks.length} done).`,
       'info',
@@ -96,7 +101,10 @@ export async function resumePlan(
     return;
   }
 
-  const summary = `${doneCount}/${state.plan.tasks.length} done, ${pendingCount} pending${blockedCount ? `, ${blockedCount} blocked` : ''}`;
+  const summary =
+    `${doneCount}/${state.plan.tasks.length} done, ${pendingCount} pending` +
+    (blockedCount ? `, ${blockedCount} blocked` : '') +
+    (deferredCount ? `, ${deferredCount} follow-up` : '');
   const action = await ctx.ui.select(`Resume "${state.plan.title}" (${summary}) — what next?`, [
     'Continue execution',
     'Re-plan from scratch',
@@ -119,19 +127,15 @@ export async function resumePlan(
     return;
   }
 
-  if (blockedCount > 0) {
-    for (const task of state.plan.tasks) {
-      if (task.status === 'blocked') {
-        task.status = 'pending';
-        task.updated_at = new Date().toISOString();
-      }
-    }
-    await writeTasksJsonl(dir, snapshot.meta, state.plan.tasks);
+  // Reactivate blocked tasks and discovered follow-ups so "Continue execution"
+  // picks them up — this is the moment the user decides to go ahead.
+  if (reactivateForExecution(state.plan.tasks, new Date().toISOString())) {
+    await runPlanIO(writeTasksJsonl(dir, snapshot.meta, state.plan.tasks));
   }
 
   const remaining = state.plan.tasks.filter((task) => task.status === 'pending');
   const taskList = remaining.map((task) => `${task.id}. ${task.description}`).join('\n');
   const kickoff = `Resuming plan: "${state.plan.title}"\n\nCompleted: ${doneCount}/${state.plan.tasks.length} tasks\n\nRemaining tasks:\n${taskList}\n\nContinue from ${remaining[0]?.id}. Call update_task after completing each task.`;
 
-  await executeInNewSession(ctx, dir, state.plan, kickoff);
+  await executeInNewSession(ctx, runPlanIO, dir, state.plan, kickoff);
 }

package/extensions/plan-mode/schema.ts

@@ -0,0 +1,57 @@
+/**
+ * Effect Schema definitions for plan-mode persisted records.
+ *
+ * These replace the hand-rolled type guards. Schemas are the single source of
+ * truth for record shape; the mutable TS interfaces in `types.ts` are kept for
+ * the imperative orchestration code (which mutates tasks in place) and are
+ * structurally compatible with the decoded values.
+ */
+
+import { Schema } from 'effect';
+
+export const TaskStatusSchema = Schema.Literal('pending', 'done', 'skipped', 'blocked', 'deferred');
+
+export const TaskOriginSchema = Schema.Literal('plan', 'discovered');
+
+export const TaskRecordSchema = Schema.Struct({
+  _type: Schema.Literal('task'),
+  id: Schema.String,
+  description: Schema.String,
+  details: Schema.optional(Schema.String),
+  status: TaskStatusSchema,
+  origin: Schema.optional(TaskOriginSchema),
+  depends_on: Schema.optional(Schema.mutable(Schema.Array(Schema.String))),
+  notes: Schema.optional(Schema.String),
+  created_at: Schema.String,
+  updated_at: Schema.String,
+});
+
+export const TaskMetaSchema = Schema.Struct({
+  _type: Schema.Literal('meta'),
+  title: Schema.String,
+  plan_name: Schema.String,
+  created_at: Schema.String,
+});
+
+/** A single tasks.jsonl line is either the meta record or a task record. */
+export const TasksLineSchema = Schema.Union(TaskMetaSchema, TaskRecordSchema);
+
+export const PlanManifestEntrySchema = Schema.Struct({
+  _type: Schema.Literal('plan'),
+  name: Schema.String,
+  status: Schema.Literal('in-progress', 'done'),
+  title: Schema.String,
+  created_at: Schema.String,
+  completed_at: Schema.NullOr(Schema.String),
+});
+
+export const ExecPendingConfigSchema = Schema.Struct({
+  model: Schema.Struct({ provider: Schema.String, id: Schema.String }),
+  thinking: Schema.String,
+});
+
+export const decodeTaskRecord = Schema.decodeUnknownEither(TaskRecordSchema);
+export const decodeTaskMeta = Schema.decodeUnknownEither(TaskMetaSchema);
+export const decodeTasksLine = Schema.decodeUnknownEither(TasksLineSchema);
+export const decodePlanManifestEntry = Schema.decodeUnknownEither(PlanManifestEntrySchema);
+export const decodeExecPendingConfig = Schema.decodeUnknownEither(ExecPendingConfigSchema);

package/extensions/plan-mode/storage/atomic-write.ts

@@ -1,17 +1,35 @@
+import { Effect } from 'effect';
 import { createWriteStream } from 'node:fs';
 import { open, rename, rm } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { PlanWriteError } from '../errors.js';
 
 export interface AtomicWriteOptions {
   /** Test seam: file mode for the temporary file. */
   mode?: number;
 }
 
-export async function writeFileAtomic(
+/**
+ * Atomically write `data` to `path`: write to a temp file, fsync, rename into
+ * place, then best-effort fsync the directory. Failures surface as
+ * `PlanWriteError`.
+ */
+export function writeFileAtomic(
   path: string,
   data: string | Buffer,
   options: AtomicWriteOptions = {},
+): Effect.Effect<void, PlanWriteError> {
+  return Effect.tryPromise({
+    try: () => writeFileAtomicPromise(path, data, options),
+    catch: (cause) => new PlanWriteError({ path, cause }),
+  });
+}
+
+async function writeFileAtomicPromise(
+  path: string,
+  data: string | Buffer,
+  options: AtomicWriteOptions,
 ): Promise<void> {
   const dir = dirname(path);
   const tempPath = join(dir, `.${process.pid}.${randomUUID()}.tmp`);

package/extensions/plan-mode/storage/plan-storage.ts

@@ -2,48 +2,76 @@
  * Plan disk I/O — exec-pending markers and handoff documents.
  */
 
-import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
+import { Effect, Either, Option } from 'effect';
+import { FileSystem } from '../effects/filesystem.js';
+import type { PlanWriteError } from '../errors.js';
+import { decodeExecPendingConfig } from '../schema.js';
 import type { ExecPendingConfig } from '../types.js';
 import { EXEC_PENDING_FILE } from '../constants.js';
 
-export async function writeExecPending(dir: string, config: ExecPendingConfig): Promise<void> {
-  await mkdir(dir, { recursive: true });
-  await writeFile(`${dir}/${EXEC_PENDING_FILE}`, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+const PLANS_DIR = '.plans';
+
+export function writeExecPending(
+  dir: string,
+  config: ExecPendingConfig,
+): Effect.Effect<void, PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    yield* fs.makeDir(dir);
+    yield* fs.writeFileString(
+      `${dir}/${EXEC_PENDING_FILE}`,
+      JSON.stringify(config, null, 2) + '\n',
+    );
+  });
 }
 
-export async function readAndClearExecPending(): Promise<
-  { planDir: string; config: ExecPendingConfig } | undefined
+export function readAndClearExecPending(): Effect.Effect<
+  { planDir: string; config: ExecPendingConfig } | undefined,
+  never,
+  FileSystem
 > {
-  try {
-    const entries = await readdir('.plans', { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const dir = `.plans/${entry.name}`;
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const maybeDirs = yield* Effect.option(fs.listDirectories(PLANS_DIR));
+    if (Option.isNone(maybeDirs)) return undefined;
+
+    for (const name of maybeDirs.value) {
+      const dir = `${PLANS_DIR}/${name}`;
       const markerPath = `${dir}/${EXEC_PENDING_FILE}`;
+      const maybeText = yield* Effect.option(fs.readFileString(markerPath));
+      if (Option.isNone(maybeText)) continue;
+
+      let parsed: unknown;
       try {
-        const text = await readFile(markerPath, 'utf-8');
-        const config = JSON.parse(text) as ExecPendingConfig;
-        await unlink(markerPath);
-        return { planDir: dir, config };
+        parsed = JSON.parse(maybeText.value);
       } catch {
-        // No marker in this directory
+        continue;
       }
+      const decoded = decodeExecPendingConfig(parsed);
+      if (Either.isLeft(decoded)) continue;
+
+      yield* Effect.ignore(fs.removeFile(markerPath));
+      return { planDir: dir, config: decoded.right };
     }
-  } catch {
-    // .plans/ doesn't exist
-  }
-  return undefined;
+    return undefined;
+  });
 }
 
-export async function saveHandoff(planDir: string, content: string): Promise<void> {
-  await mkdir(planDir, { recursive: true });
-  await writeFile(`${planDir}/HANDOFF.md`, content, 'utf-8');
+export function saveHandoff(
+  planDir: string,
+  content: string,
+): Effect.Effect<void, PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    yield* fs.makeDir(planDir);
+    yield* fs.writeFileString(`${planDir}/HANDOFF.md`, content);
+  });
 }
 
-export async function loadHandoff(planDir: string): Promise<string | undefined> {
-  try {
-    return await readFile(`${planDir}/HANDOFF.md`, 'utf-8');
-  } catch {
-    return undefined;
-  }
+export function loadHandoff(planDir: string): Effect.Effect<string | undefined, never, FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const maybeText = yield* Effect.option(fs.readFileString(`${planDir}/HANDOFF.md`));
+    return Option.getOrUndefined(maybeText);
+  });
 }