@dreki-gg/pi-plan-mode 0.16.0 → 0.17.1

package/extensions/plan-mode/effects/filesystem.ts

@@ -0,0 +1,65 @@
+/**
+ * FileSystem service — the single seam for plan-mode disk I/O.
+ *
+ * Storage programs depend on this `Context.Tag` rather than touching
+ * `node:fs/promises` directly, which makes them trivially testable and keeps
+ * all failure modes typed (`PlanReadError` / `PlanWriteError`).
+ */
+
+import { Context, Effect } from 'effect';
+import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
+import { PlanReadError, PlanWriteError } from '../errors.js';
+import { writeFileAtomic } from '../storage/atomic-write.js';
+
+export interface FileSystemService {
+  readonly readFileString: (path: string) => Effect.Effect<string, PlanReadError>;
+  readonly writeFileString: (path: string, data: string) => Effect.Effect<void, PlanWriteError>;
+  readonly writeFileAtomic: (path: string, data: string) => Effect.Effect<void, PlanWriteError>;
+  readonly makeDir: (path: string) => Effect.Effect<void, PlanWriteError>;
+  readonly listDirectories: (path: string) => Effect.Effect<string[], PlanReadError>;
+  readonly removeFile: (path: string) => Effect.Effect<void, PlanWriteError>;
+}
+
+export class FileSystem extends Context.Tag('PlanMode/FileSystem')<
+  FileSystem,
+  FileSystemService
+>() {}
+
+export const nodeFileSystemService: FileSystemService = {
+  readFileString: (path) =>
+    Effect.tryPromise({
+      try: () => readFile(path, 'utf-8'),
+      catch: (cause) => new PlanReadError({ path, cause }),
+    }),
+
+  writeFileString: (path, data) =>
+    Effect.tryPromise({
+      try: () => writeFile(path, data, 'utf-8'),
+      catch: (cause) => new PlanWriteError({ path, cause }),
+    }),
+
+  writeFileAtomic: (path, data) => writeFileAtomic(path, data),
+
+  makeDir: (path) =>
+    Effect.tryPromise({
+      try: async () => {
+        await mkdir(path, { recursive: true });
+      },
+      catch: (cause) => new PlanWriteError({ path, cause }),
+    }),
+
+  listDirectories: (path) =>
+    Effect.tryPromise({
+      try: async () => {
+        const entries = await readdir(path, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+      },
+      catch: (cause) => new PlanReadError({ path, cause }),
+    }),
+
+  removeFile: (path) =>
+    Effect.tryPromise({
+      try: () => unlink(path),
+      catch: (cause) => new PlanWriteError({ path, cause }),
+    }),
+};

package/extensions/plan-mode/effects/runtime.ts

@@ -0,0 +1,24 @@
+/**
+ * Live Effect runtime for the plan-mode extension.
+ *
+ * Build the layer once inside the extension entry and run storage programs
+ * through the `runPlanIO` bridge so the imperative pi event handlers keep their
+ * `await fn(...)` shape.
+ */
+
+import { Effect, Layer } from 'effect';
+import { FileSystem, nodeFileSystemService } from './filesystem.js';
+
+export function makeRuntimeLayer(): Layer.Layer<FileSystem> {
+  return Layer.succeed(FileSystem, nodeFileSystemService);
+}
+
+/** Build a bridge that runs storage programs against the live filesystem layer. */
+export function makePlanRuntime() {
+  const layer = makeRuntimeLayer();
+  return function runPlanIO<A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> {
+    return Effect.runPromise(program.pipe(Effect.provide(layer)));
+  };
+}
+
+export type RunPlanIO = ReturnType<typeof makePlanRuntime>;

package/extensions/plan-mode/errors.ts

@@ -0,0 +1,105 @@
+/**
+ * Tagged errors for plan-mode disk I/O and JSONL validation.
+ *
+ * These replace ad-hoc `throw new Error(...)` so storage programs surface
+ * typed, inspectable failures. They are mapped back to user-facing strings at
+ * the tool boundary via `errorMessage`.
+ */
+
+import { Data } from 'effect';
+
+export class PlanReadError extends Data.TaggedError('PlanReadError')<{
+  readonly path: string;
+  readonly cause: unknown;
+}> {
+  get message(): string {
+    return `Failed to read ${this.path}: ${causeMessage(this.cause)}`;
+  }
+}
+
+export class PlanWriteError extends Data.TaggedError('PlanWriteError')<{
+  readonly path: string;
+  readonly cause: unknown;
+}> {
+  get message(): string {
+    return `Failed to write ${this.path}: ${causeMessage(this.cause)}`;
+  }
+}
+
+export class JsonlParseError extends Data.TaggedError('JsonlParseError')<{
+  readonly path: string;
+  readonly line: number;
+  readonly cause?: unknown;
+}> {
+  get message(): string {
+    return `Invalid JSONL in ${this.path} at line ${this.line}: ${causeMessage(this.cause)}`;
+  }
+}
+
+export class JsonlValidationError extends Data.TaggedError('JsonlValidationError')<{
+  readonly path: string;
+  readonly line: number;
+  readonly reason: string;
+}> {
+  get message(): string {
+    return `Invalid record in ${this.path} at line ${this.line}: ${this.reason}`;
+  }
+}
+
+export class MissingMetaRecord extends Data.TaggedError('MissingMetaRecord')<{
+  readonly path: string;
+}> {
+  get message(): string {
+    return `${this.path} is missing meta record`;
+  }
+}
+
+export class TaskNotFound extends Data.TaggedError('TaskNotFound')<{
+  readonly planDir: string;
+  readonly taskId: string;
+}> {
+  get message(): string {
+    return `Task not found: ${this.taskId}`;
+  }
+}
+
+export class TasksFileNotFound extends Data.TaggedError('TasksFileNotFound')<{
+  readonly planDir: string;
+}> {
+  get message(): string {
+    return `No tasks.jsonl found in ${this.planDir}`;
+  }
+}
+
+export type PlanStorageError =
+  | PlanReadError
+  | PlanWriteError
+  | JsonlParseError
+  | JsonlValidationError
+  | MissingMetaRecord
+  | TaskNotFound
+  | TasksFileNotFound;
+
+export function causeMessage(cause: unknown): string {
+  if (cause instanceof Error) return cause.message;
+  return String(cause);
+}
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'object' && error !== null && 'message' in error) {
+    const message = (error as { message?: unknown }).message;
+    if (typeof message === 'string') return message;
+  }
+  return String(error);
+}
+
+/** Convert any error (including tagged errors) into a native Error for the tool boundary. */
+export function toNativeError(error: unknown): Error {
+  if (error instanceof Error) return error;
+  const native = new Error(errorMessage(error));
+  if (typeof error === 'object' && error !== null && '_tag' in error) {
+    native.name = String((error as { _tag: unknown })._tag);
+  }
+  return native;
+}

package/extensions/plan-mode/index.ts

@@ -28,21 +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', {
@@ -52,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;
@@ -60,7 +65,7 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
-  registerPreviewPrototypeTool(pi);
+  registerPreviewPrototypeTool(pi, runPlanIO);
 
   registerUpdateTaskTool(pi, {
     getPlan: () => state.plan,
@@ -71,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);
     },
@@ -92,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) {
@@ -115,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);
     },
   });
 
@@ -126,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');
     },
@@ -210,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',
@@ -224,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);
@@ -247,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);
@@ -278,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;
@@ -351,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

@@ -63,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);