@dreki-gg/pi-plan-mode 0.18.0 → 0.20.0

package/extensions/plan-mode/__tests__/schema.test.ts

@@ -177,6 +177,25 @@ describe('plan manifest entry schema', () => {
     ).toBe(true);
   });
 
+  test('accepts terminal statuses (superseded / abandoned) with a reason', () => {
+    for (const status of ['done', 'superseded', 'abandoned'] as const) {
+      expect(
+        isOk(
+          {
+            _type: 'plan',
+            name: 'plan',
+            status,
+            title: 'Plan',
+            created_at: now,
+            completed_at: now,
+            reason: 'another plan shipped it',
+          },
+          decodePlanManifestEntry,
+        ),
+      ).toBe(true);
+    }
+  });
+
   test('rejects an invalid status', () => {
     expect(
       isOk(

package/extensions/plan-mode/__tests__/update-plan.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chdir } from 'node:process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { makePlanRuntime } from '../effects/runtime.js';
+import { readPlansManifest, upsertPlanEntry } from '../storage/plans-manifest.js';
+import { registerUpdatePlanTool } from '../tools/update-plan.js';
+
+const runPlanIO = makePlanRuntime();
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { plan: string; status: string; reason?: string },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
+}
+
+function setup(): CapturedTool {
+  let tool: CapturedTool | undefined;
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerUpdatePlanTool>[0];
+  registerUpdatePlanTool(pi, runPlanIO);
+  return tool!;
+}
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-update-plan-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('update_plan tool', () => {
+  test('closes a plan as superseded with a reason', async () => {
+    await runPlanIO(upsertPlanEntry('p', { status: 'in-progress', title: 'P' }));
+    const tool = setup();
+    const result = await tool.execute('c', {
+      plan: 'p',
+      status: 'superseded',
+      reason: 'absorbed by q',
+    });
+    expect(result.content?.[0]?.text).toMatch(/in-progress → superseded/);
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('superseded');
+    expect(entry.reason).toBe('absorbed by q');
+  });
+
+  test('accepts a .plans/<name> hint', async () => {
+    await runPlanIO(upsertPlanEntry('p', { status: 'in-progress', title: 'P' }));
+    const tool = setup();
+    await tool.execute('c', { plan: '.plans/p', status: 'abandoned', reason: 'rejected' });
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('abandoned');
+  });
+
+  test('reports not_found for an unknown plan (no throw)', async () => {
+    const tool = setup();
+    const result = await tool.execute('c', { plan: 'ghost', status: 'done' });
+    expect((result.details as { error?: string }).error).toBe('not_found');
+  });
+});

package/extensions/plan-mode/__tests__/update-tasks.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, test } from 'bun:test';
+import { registerUpdateTasksTool } from '../tools/update-tasks.js';
+import type { PlanData, TaskRecord, TaskStatus } from '../types.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: {
+      updates: Array<{ task_id: string; status: 'done' | 'skipped'; notes?: string }>;
+      plan?: string;
+    },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown; terminate?: boolean }>;
+}
+
+function setup(plan: PlanData | undefined, candidates: string[] = []) {
+  let tool: CapturedTool | undefined;
+  const updates: Array<{ taskId: string; status: string; notes?: string }> = [];
+  // Count how many times the coalesced write callback fires — must be ≤ 1 per call.
+  let writeCount = 0;
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerUpdateTasksTool>[0];
+
+  registerUpdateTasksTool(pi, {
+    resolvePlan: async () => ({ plan, candidates }),
+    onTasksUpdated: (batch) => {
+      writeCount += 1;
+      for (const { taskId, status, notes } of batch) {
+        const target = plan?.tasks.find((candidate) => candidate.id === taskId);
+        if (target) target.status = status;
+        updates.push({ taskId, status, notes });
+      }
+    },
+  });
+
+  return { tool: tool!, updates, getWriteCount: () => writeCount };
+}
+
+const basePlan = (tasks: TaskRecord[]): PlanData => ({
+  title: 'Plan',
+  planName: 'plan',
+  handoff: '',
+  tasks,
+});
+const planTask = (id: string, status: TaskStatus = 'pending'): TaskRecord => ({
+  _type: 'task',
+  id,
+  description: `task ${id}`,
+  status,
+  origin: 'plan',
+  created_at: now,
+  updated_at: now,
+});
+
+describe('update_tasks tool', () => {
+  test('marks multiple pending tasks (mixed statuses) in a SINGLE write and reports progress', async () => {
+    const { tool, updates, getWriteCount } = setup(
+      basePlan([planTask('t-001'), planTask('t-002'), planTask('t-003')]),
+    );
+    const result = await tool.execute('c', {
+      updates: [
+        { task_id: 't-001', status: 'done', notes: 'a' },
+        { task_id: 't-002', status: 'skipped', notes: 'b' },
+      ],
+    });
+    expect(updates).toEqual([
+      { taskId: 't-001', status: 'done', notes: 'a' },
+      { taskId: 't-002', status: 'skipped', notes: 'b' },
+    ]);
+    // The whole point of the batch tool: one coalesced write, not one per task.
+    expect(getWriteCount()).toBe(1);
+    expect(result.content?.[0]?.text).toMatch(/Progress: 2\/3/);
+    expect(result.terminate).toBeUndefined();
+  });
+
+  test('soft-skips (no throw) when there is no active plan', async () => {
+    const { tool, updates } = setup(undefined, ['alpha', 'beta']);
+    const result = await tool.execute('c', { updates: [{ task_id: 't-001', status: 'done' }] });
+    expect((result.details as { skipped?: boolean }).skipped).toBe(true);
+    expect(result.content?.[0]?.text).toMatch(/alpha, beta/);
+    expect(updates).toHaveLength(0);
+  });
+
+  test('no write when every item is a no-op or not_found', async () => {
+    const { tool, getWriteCount } = setup(basePlan([planTask('t-001', 'done')]));
+    await tool.execute('c', {
+      updates: [
+        { task_id: 't-001', status: 'done' },
+        { task_id: 't-999', status: 'done' },
+      ],
+    });
+    expect(getWriteCount()).toBe(0);
+  });
+
+  test('mixed batch: valid applied, unknown id reported as not_found', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001'), planTask('t-002')]));
+    const result = await tool.execute('c', {
+      updates: [
+        { task_id: 't-001', status: 'done' },
+        { task_id: 't-999', status: 'done' },
+      ],
+    });
+    expect(updates).toEqual([{ taskId: 't-001', status: 'done', notes: undefined }]);
+    const details = result.details as { results?: Array<{ task_id: string; outcome: string }> };
+    expect(details.results?.find((r) => r.task_id === 't-999')?.outcome).toBe('not_found');
+  });
+
+  test('idempotent: re-marking the same status is a per-item no-op', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001', 'done'), planTask('t-002')]));
+    const result = await tool.execute('c', {
+      updates: [
+        { task_id: 't-001', status: 'done' },
+        { task_id: 't-002', status: 'done' },
+      ],
+    });
+    expect(updates).toEqual([{ taskId: 't-002', status: 'done', notes: undefined }]);
+    const details = result.details as { results?: Array<{ task_id: string; outcome: string }> };
+    expect(details.results?.find((r) => r.task_id === 't-001')?.outcome).toBe('noop');
+  });
+
+  test('corrects an already-resolved task (done → skipped)', async () => {
+    const { tool, updates } = setup(basePlan([planTask('t-001', 'done')]));
+    await tool.execute('c', { updates: [{ task_id: 't-001', status: 'skipped' }] });
+    expect(updates).toEqual([{ taskId: 't-001', status: 'skipped', notes: undefined }]);
+  });
+});

package/extensions/plan-mode/constants.ts

@@ -16,6 +16,8 @@ export const PLAN_TOOLS = [
   'search_skills',
   'subagent',
   'plan_status',
+  'update_plan',
+  'reconcile_plans',
 ];
 
 export const EXEC_TOOLS = [
@@ -24,8 +26,11 @@ export const EXEC_TOOLS = [
   'edit',
   'write',
   'update_task',
+  'update_tasks',
   'add_task',
   'plan_status',
+  'update_plan',
+  'reconcile_plans',
 ];
 
 // ── Model + thinking presets ─────────────────────────────────────────────────

package/extensions/plan-mode/index.ts

@@ -26,24 +26,28 @@ import {
   EXEC_MODEL,
   EXEC_THINKING,
 } from './constants.js';
-import type { ThinkingLevel } from './types.js';
+import type { ThinkingLevel, TaskStatus } 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 { upsertPlanEntry, reconcilePlanStatus } 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 { activeTasksResolved, deferredTasks, isPlanFinalizable } from './task-status.js';
 import { enterPlanMode, exitPlanMode, switchModel } from './phase-transitions.js';
 import { resumePlan, executeInNewSession } from './resume.js';
 import { resolveActivePlan } from './resolve-plan.js';
+import { collectPlanDrift } from './reconcile.js';
 import { registerSubmitPlanTool } from './tools/submit-plan.js';
 import { registerPreviewPrototypeTool } from './tools/preview-prototype.js';
 import { registerUpdateTaskTool } from './tools/update-task.js';
+import { registerUpdateTasksTool } from './tools/update-tasks.js';
 import { registerAddTaskTool } from './tools/add-task.js';
 import { registerPlanStatusTool } from './tools/plan-status.js';
+import { registerUpdatePlanTool } from './tools/update-plan.js';
+import { registerReconcilePlansTool } from './tools/reconcile-plans.js';
 import { isSafeCommand, isPlanPath } from './utils.js';
 
 export default function planMode(pi: ExtensionAPI): void {
@@ -69,15 +73,64 @@ export default function planMode(pi: ExtensionAPI): void {
 
   registerPreviewPrototypeTool(pi, runPlanIO);
 
+  // Shared task-write closure: mutate the in-memory task, persist tasks.jsonl,
+  // and re-derive registry status. Used by both update_task and update_tasks.
+  const onTaskUpdated = async (
+    taskId: string,
+    status: Exclude<TaskStatus, 'pending'>,
+    notes?: string,
+  ) => {
+    if (!state.plan || !state.planDir) return;
+    const task = state.plan.tasks.find((candidate) => candidate.id === taskId);
+    if (!task) return;
+    task.status = status;
+    task.updated_at = new Date().toISOString();
+    if (notes) task.notes = notes;
+    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,
+      ),
+    );
+    // FEEDBACK #1: registry status is a projection of task state. Re-derive it
+    // on every task write so completion is decoupled from in-session execution
+    // — cross-session / disk-tracked task updates now close the plan too.
+    await runPlanIO(
+      reconcilePlanStatus(
+        state.plan.planName,
+        isPlanFinalizable(state.plan.tasks),
+        state.plan.title,
+      ),
+    );
+    state.persist(pi);
+  };
+
   registerUpdateTaskTool(pi, {
     resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
-    onTaskUpdated: async (taskId, status, notes) => {
+    onTaskUpdated,
+  });
+
+  registerUpdateTasksTool(pi, {
+    resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
+    // Coalesced batch write: mutate every task in memory first, then perform a
+    // SINGLE tasks.jsonl write + ONE registry reconcile. This is the whole point
+    // of update_tasks — repeated single-task writes caused file-write contention.
+    onTasksUpdated: async (updates) => {
       if (!state.plan || !state.planDir) return;
-      const task = state.plan.tasks.find((candidate) => candidate.id === taskId);
-      if (!task) return;
-      task.status = status;
-      task.updated_at = new Date().toISOString();
-      if (notes) task.notes = notes;
+      const now = new Date().toISOString();
+      for (const { taskId, status, notes } of updates) {
+        const task = state.plan.tasks.find((candidate) => candidate.id === taskId);
+        if (!task) continue;
+        task.status = status;
+        task.updated_at = now;
+        if (notes) task.notes = notes;
+      }
       await runPlanIO(
         writeTasksJsonl(
           state.planDir,
@@ -85,19 +138,40 @@ export default function planMode(pi: ExtensionAPI): void {
             _type: 'meta',
             title: state.plan.title,
             plan_name: state.plan.planName,
-            created_at: state.plan.tasks[0]?.created_at ?? task.updated_at,
+            created_at: state.plan.tasks[0]?.created_at ?? now,
           },
           state.plan.tasks,
         ),
       );
+      await runPlanIO(
+        reconcilePlanStatus(
+          state.plan.planName,
+          isPlanFinalizable(state.plan.tasks),
+          state.plan.title,
+        ),
+      );
       state.persist(pi);
     },
   });
 
   registerPlanStatusTool(pi, {
     resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
+    listInProgress: async () => {
+      const rows = await runPlanIO(collectPlanDrift());
+      return rows
+        .filter((row) => row.registryStatus === 'in-progress')
+        .map((row) => ({
+          name: row.name,
+          title: row.title ?? row.name,
+          resolved: row.resolved ?? 0,
+          total: row.total ?? 0,
+        }));
+    },
   });
 
+  registerUpdatePlanTool(pi, runPlanIO);
+  registerReconcilePlansTool(pi, runPlanIO);
+
   registerAddTaskTool(pi, {
     resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
     onTaskAdded: async (task) => {
@@ -115,6 +189,15 @@ export default function planMode(pi: ExtensionAPI): void {
           state.plan.tasks,
         ),
       );
+      // A new deferred follow-up means the plan is no longer finalizable: re-open
+      // it in the registry if it had been auto-marked done.
+      await runPlanIO(
+        reconcilePlanStatus(
+          state.plan.planName,
+          isPlanFinalizable(state.plan.tasks),
+          state.plan.title,
+        ),
+      );
       state.persist(pi);
     },
   });
@@ -122,13 +205,33 @@ export default function planMode(pi: ExtensionAPI): void {
   // ── Commands ──────────────────────────────────────────────────────────────
   pi.registerCommand('plan', {
     description:
-      'Enter plan mode, optionally with a starting prompt. Use "/plan resume" to pick up an existing plan.',
+      'Enter plan mode, optionally with a starting prompt. "/plan resume" picks up an existing plan; "/plan focus <name>" pins the active plan for tracking calls.',
     handler: async (args, ctx) => {
       const trimmed = args?.trim();
       if (trimmed === 'resume') {
         await resumePlan(state, pi, ctx, runPlanIO);
         return;
       }
+      // "/plan focus <name>" — pin a plan so update_task / add_task / plan_status
+      // default to it without repeating { plan: "<name>" } on every call (#5).
+      if (trimmed?.startsWith('focus')) {
+        const name = trimmed.slice('focus'.length).trim();
+        if (!name) {
+          ctx.ui.notify('Usage: /plan focus <name>', 'info');
+          return;
+        }
+        // Clear any stale in-memory plan so the hint re-attaches from disk.
+        state.plan = undefined;
+        state.planDir = undefined;
+        const { plan, candidates } = await resolveActivePlan(state, pi, runPlanIO, { name });
+        if (plan) {
+          ctx.ui.notify(`Focused plan: ${plan.title} (${plan.planName})`, 'info');
+        } else {
+          const hint = candidates.length ? ` In-progress: ${candidates.join(', ')}.` : '';
+          ctx.ui.notify(`No plan named "${name}".${hint}`, 'error');
+        }
+        return;
+      }
       if (state.planEnabled || state.executing) {
         await exitPlanMode(state, pi, ctx);
         return;

package/extensions/plan-mode/reconcile.ts

@@ -0,0 +1,141 @@
+/**
+ * Drift detection + repair between `tasks.jsonl` reality and registry status.
+ *
+ * Drift happens in both directions (FEEDBACK #6):
+ *   - tasks all done but registry `in-progress` (completion never recorded), and
+ *   - registry `in-progress`/`done` disagreeing with task state generally.
+ *
+ * It also surfaces two un-trackable classes:
+ *   - registry-only plans (an entry with no `tasks.jsonl` directory), and
+ *   - orphan task dirs (a `tasks.jsonl` with no registry entry).
+ *
+ * `collectPlanDrift` is a pure read; `applyReconcile` repairs only the safe
+ * `in-progress` ⇄ `done` projection and never touches terminal statuses.
+ */
+
+import { Effect } from 'effect';
+import { FileSystem } from './effects/filesystem.js';
+import type {
+  JsonlParseError,
+  JsonlValidationError,
+  MissingMetaRecord,
+  PlanWriteError,
+} from './errors.js';
+import { readPlansManifest, reconcilePlanStatus } from './storage/plans-manifest.js';
+import { readTasksJsonl } from './storage/task-storage.js';
+import { isPlanFinalizable } from './task-status.js';
+import type { PlanStatus } from './types.js';
+
+const PLANS_DIR = '.plans';
+
+export interface PlanDriftRow {
+  name: string;
+  /** Registry status, or `undefined` when there is a task dir but no entry. */
+  registryStatus?: PlanStatus;
+  title?: string;
+  /** Derived from tasks: `done` when finalizable, else `in-progress`. */
+  derivedStatus?: 'in-progress' | 'done';
+  /** Resolved/total task counts when a tasks.jsonl exists. */
+  resolved?: number;
+  total?: number;
+  /** True when a `tasks.jsonl` snapshot was found for this plan. */
+  hasTasks: boolean;
+  /**
+   * Drift class:
+   *   - 'status'        : registry status disagrees with derived task status
+   *   - 'registry-only' : registry entry but no tasks.jsonl dir
+   *   - 'orphan'        : tasks.jsonl dir but no registry entry
+   *   - undefined       : in sync
+   */
+  drift?: 'status' | 'registry-only' | 'orphan';
+}
+
+type CollectError = JsonlParseError | JsonlValidationError | MissingMetaRecord;
+
+/** Walk every plan (registry + task dirs) and classify drift. Pure read. */
+export function collectPlanDrift(): Effect.Effect<PlanDriftRow[], CollectError, FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    const manifest = yield* readPlansManifest();
+    const dirs = yield* Effect.orElseSucceed(fs.listDirectories(PLANS_DIR), () => [] as string[]);
+    // Ignore dotfile dirs like `.archive`.
+    const taskDirs = new Set(dirs.filter((name) => !name.startsWith('.')));
+
+    const rows: PlanDriftRow[] = [];
+    const seen = new Set<string>();
+
+    for (const entry of manifest) {
+      seen.add(entry.name);
+      const snapshot = yield* readTasksJsonl(`${PLANS_DIR}/${entry.name}`);
+      if (!snapshot) {
+        rows.push({
+          name: entry.name,
+          registryStatus: entry.status,
+          title: entry.title,
+          hasTasks: false,
+          drift: 'registry-only',
+        });
+        continue;
+      }
+      const total = snapshot.tasks.length;
+      const resolved = snapshot.tasks.filter(
+        (t) => t.status === 'done' || t.status === 'skipped',
+      ).length;
+      const derivedStatus = isPlanFinalizable(snapshot.tasks) ? 'done' : 'in-progress';
+      // Terminal statuses (superseded/abandoned) are intentional — never drift.
+      const isTerminalManual = entry.status === 'superseded' || entry.status === 'abandoned';
+      const drift = !isTerminalManual && entry.status !== derivedStatus ? 'status' : undefined;
+      rows.push({
+        name: entry.name,
+        registryStatus: entry.status,
+        title: entry.title,
+        derivedStatus,
+        resolved,
+        total,
+        hasTasks: true,
+        drift,
+      });
+    }
+
+    // Orphan task dirs: have tasks.jsonl but no registry entry.
+    for (const name of taskDirs) {
+      if (seen.has(name)) continue;
+      const snapshot = yield* readTasksJsonl(`${PLANS_DIR}/${name}`);
+      if (!snapshot) continue;
+      const total = snapshot.tasks.length;
+      const resolved = snapshot.tasks.filter(
+        (t) => t.status === 'done' || t.status === 'skipped',
+      ).length;
+      rows.push({
+        name,
+        title: snapshot.meta.title,
+        derivedStatus: isPlanFinalizable(snapshot.tasks) ? 'done' : 'in-progress',
+        resolved,
+        total,
+        hasTasks: true,
+        drift: 'orphan',
+      });
+    }
+
+    return rows;
+  });
+}
+
+/**
+ * Repair `status`-class drift by projecting derived status into the registry.
+ * Orphans and registry-only rows are reported but not auto-fixed (they need a
+ * human decision). Returns the rows that were repaired.
+ */
+export function applyReconcile(
+  rows: PlanDriftRow[],
+): Effect.Effect<PlanDriftRow[], CollectError | PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const repaired: PlanDriftRow[] = [];
+    for (const row of rows) {
+      if (row.drift !== 'status' || !row.derivedStatus) continue;
+      yield* reconcilePlanStatus(row.name, row.derivedStatus === 'done', row.title);
+      repaired.push(row);
+    }
+    return repaired;
+  });
+}

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

@@ -67,10 +67,17 @@ async function attach(
 /**
  * Resolve the active plan, attaching from disk when nothing is in memory.
  *
- * Order: in-memory `state.plan` → explicit `name` hint → the single
+ * Order: explicit `name` hint → in-memory `state.plan` → the single
  * in-progress plan in `.plans/plans.jsonl`. Ambiguous (multiple in-progress,
  * no hint) returns `{ plan: undefined, candidates }` so the caller can prompt
  * for a `name`.
+ *
+ * IMPORTANT (FEEDBACK #7): an explicit `name` hint ALWAYS wins over the
+ * in-memory `state.plan`. Previously `state.plan` short-circuited first, so a
+ * deliberate `{ plan: '<other>' }` was silently ignored and writes landed in
+ * whatever plan the last `submit_plan` attached — a data-corruption path. The
+ * hint is now resolved first; when it names a different plan we re-attach from
+ * disk so subsequent writes target the right `tasks.jsonl`.
  */
 export async function resolveActivePlan(
   state: PlanModeState,
@@ -78,12 +85,13 @@ export async function resolveActivePlan(
   runPlanIO: RunPlanIO,
   opts: { name?: string } = {},
 ): Promise<ResolvedPlan> {
-  if (state.plan) return { plan: state.plan, candidates: [] };
-
-  const manifest = await runPlanIO(readPlansManifest());
-
+  // ── Explicit hint wins, even over an attached in-memory plan ──────────────
   if (opts.name) {
     const hint = normalizeName(opts.name);
+    // Already the attached plan? Return the in-memory copy (freshest task state).
+    if (state.plan && state.plan.planName === hint) return { plan: state.plan, candidates: [] };
+
+    const manifest = await runPlanIO(readPlansManifest());
     const match = manifest.find((entry) => entry.name === hint);
     // A hint that names a real plan attaches regardless of status (the caller
     // asked for it explicitly); a hint that names nothing falls through to the
@@ -92,8 +100,14 @@ export async function resolveActivePlan(
       const plan = await attach(state, pi, runPlanIO, match.name);
       if (plan) return { plan, candidates: [] };
     }
+    const inProgress = manifest.filter((entry) => entry.status === 'in-progress');
+    return { plan: undefined, candidates: inProgress.map((entry) => entry.name) };
   }
 
+  // ── No hint: in-memory plan, else the single in-progress plan on disk ─────
+  if (state.plan) return { plan: state.plan, candidates: [] };
+
+  const manifest = await runPlanIO(readPlansManifest());
   const inProgress = manifest.filter((entry) => entry.status === 'in-progress');
   if (inProgress.length === 1) {
     const plan = await attach(state, pi, runPlanIO, inProgress[0]!.name);

package/extensions/plan-mode/schema.ts

@@ -36,13 +36,25 @@ export const TaskMetaSchema = Schema.Struct({
 /** A single tasks.jsonl line is either the meta record or a task record. */
 export const TasksLineSchema = Schema.Union(TaskMetaSchema, TaskRecordSchema);
 
+/**
+ * Plan lifecycle statuses.
+ *   - in-progress: active, tracked, eligible for auto-resolution
+ *   - done:        completed (all tasks resolved)
+ *   - superseded:  closed because another plan absorbed the work
+ *   - abandoned:   closed without shipping (rejected / won't do)
+ * Only `in-progress` is treated as active; the rest are terminal.
+ */
+export const PlanStatusSchema = Schema.Literal('in-progress', 'done', 'superseded', 'abandoned');
+
 export const PlanManifestEntrySchema = Schema.Struct({
   _type: Schema.Literal('plan'),
   name: Schema.String,
-  status: Schema.Literal('in-progress', 'done'),
+  status: PlanStatusSchema,
   title: Schema.String,
   created_at: Schema.String,
   completed_at: Schema.NullOr(Schema.String),
+  /** Optional human-readable reason, used for terminal statuses. */
+  reason: Schema.optional(Schema.String),
 });
 
 export const ExecPendingConfigSchema = Schema.Struct({