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

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.19.0
+
+### Minor Changes
+
+- 48cee24: fix(plan-mode): multi-plan / cross-session drift + silent wrong-plan writes
+
+  Real-world report from a repo with many simultaneously-in-progress plans surfaced two trust-breakers plus several rough edges (see `FEEDBACK.md`). All addressed:
+
+  - **Registry status is now a projection of task state** (🔴 #1). Plan completion was coupled to a formal in-session execution run (`state.executing`), so a plan driven to all-tasks-`done` via `update_task` in another session/model stayed `in-progress` forever. `reconcilePlanStatus` now re-derives `plans.jsonl` status from `tasks.jsonl` on every task write (in `update_task` **and** `add_task`), decoupling completion from execution mode.
+  - **Explicit `plan` hint always wins** (🔴 #7). `resolveActivePlan` returned the in-memory `state.plan` before ever consulting an explicit `{ plan: "<name>" }` argument, so once a plan was submitted in a session every `update_task` / `add_task` silently pinned to it — landing writes in the wrong `tasks.jsonl`. The hint is now resolved **before** the in-memory short-circuit and re-attaches the named plan from disk.
+  - **New `update_plan` tool** (#2/#3): close or reopen a plan (`done` / `superseded` / `abandoned` / `in-progress`) with a `reason`, instead of hand-editing the registry or smuggling status into the title.
+  - **Widened plan status** (#3): `PlanManifestEntry.status` gains `superseded` and `abandoned`, plus an optional `reason`. Only `in-progress` is active; terminal statuses drop out of resolution and are never auto-overridden by reconciliation.
+  - **New `reconcile_plans` tool** (#6): walks every plan, reports drift (registry vs. derived task status), orphan task dirs, and registry-only plans; `apply: true` repairs safe `in-progress` ⇄ `done` drift.
+  - **`clean` archives instead of deletes** (#4): closed-plan directories move to `.plans/.archive/<name>/` by default (preserving HANDOFF.md + tasks.jsonl); true deletion is gated behind `--purge`. The CLI now reads `plans.jsonl` (was `plans.json`).
+  - **Multi-plan UX** (#5): `/plan focus <name>` pins the active plan so tracking calls default to it; `plan_status` with no arg and multiple in-progress plans renders a progress table (`7/17`, `8/8 ⚠ done?`) that surfaces reconcile candidates at a glance.
+
+## 0.18.0
+
+### Minor Changes
+
+- Make `update_task` / `add_task` usable across sessions and resilient for autonomous agents.
+
+  The active plan was session-scoped: `update_task` / `add_task` only worked when a plan was submitted in the same session, restored from its entries, or handed off via the one-shot exec-pending marker. An agent executing an existing `.plans/<name>/` in a fresh session (the common plan-here / execute-there flow) hit a hard `No active plan` throw.
+
+  - **Disk-backed resolution** (`resolveActivePlan`): when nothing is attached in memory, the active plan is resolved from `.plans/plans.jsonl` — the sole in-progress plan auto-attaches (data only; does NOT enter execution mode / change tools / model). Wired into `session_start` and both tracking tools.
+  - **No hard throws on tracking calls**: `update_task` / `add_task` now return soft, non-terminating results (no active plan, unknown task id, already-resolved task) so a tracking miss never derails the real work. `update_task` is idempotent — re-marking the same status is a no-op success.
+  - **`plan` parameter**: both tools accept an optional `plan` (name or `.plans/<name>`) to disambiguate without the interactive `/plan resume` when multiple plans are in-progress.
+  - **`update_task` corrections**: a different status on an already-resolved task now applies as a correction (e.g. `done`→`skipped`, or `blocked`→`done` to unblock) and is reported as such, instead of being refused.
+  - **New `plan_status` tool**: read-only snapshot of the active plan — progress counts + every task id/status — so an agent can check what's active and which ids are valid (disk-backed; works in a fresh execution session) instead of probing with a failing `update_task`. Added to both tool sets.
+
 ## 0.17.1
 
 ### Patch Changes

package/README.md

@@ -22,8 +22,37 @@ pi install npm:@dreki-gg/pi-questionnaire
 | -------- | -------------- | ---------------------------------------------- |
 | Flag     | `--plan`       | Start pi in plan mode                          |
 | Command  | `/plan [prompt]` | Enter plan mode, optionally with a starting prompt |
+| Command  | `/plan resume` | Pick up an in-progress plan from disk          |
+| Command  | `/plan focus <name>` | Pin a plan so tracking calls default to it (multi-plan repos) |
 | Command  | `/todos`       | Show current plan progress                     |
 | Shortcut | `Ctrl+Alt+P`   | Toggle plan mode                               |
+| Tool     | `update_task`  | Mark a task done / skipped / blocked           |
+| Tool     | `add_task`     | Capture a discovered follow-up (deferred)      |
+| Tool     | `plan_status`  | Read-only snapshot; progress table when many plans are active |
+| Tool     | `update_plan`  | Close/reopen a plan: done, superseded, abandoned, in-progress |
+| Tool     | `reconcile_plans` | Detect & repair drift between tasks.jsonl and the registry |
+
+### Plan lifecycle status
+
+The registry (`.plans/plans.jsonl`) `status` is a **projection of task state**, not a
+hand-maintained flag. Marking every task `done`/`skipped` (via `update_task`, in any
+session or model) automatically flips the plan to `done` — completion is no longer
+coupled to a formal in-session execution run.
+
+| Status        | Meaning                                            | Active? |
+| ------------- | -------------------------------------------------- | ------- |
+| `in-progress` | Active, tracked, eligible for auto-resolution      | ✅      |
+| `done`        | All tasks resolved                                 | —       |
+| `superseded`  | Another plan absorbed the work                     | —       |
+| `abandoned`   | Won't do / rejected                                | —       |
+
+`superseded` / `abandoned` are set explicitly via `update_plan` (with a `reason`) and are
+never auto-overridden by task reconciliation. Only `in-progress` plans participate in
+active-plan resolution.
+
+In repos with **many** in-progress plans, an explicit `{ plan: "<name>" }` on
+`update_task` / `add_task` / `plan_status` **always** targets that plan — it is never
+silently overridden by whatever plan was last submitted in the session.
 
 ## Workflow
 
@@ -99,17 +128,23 @@ Plans start as `"in-progress"` when created and are marked `"done"` when all exe
 
 ## Cleaning completed plans
 
-Use the CLI to remove completed plan directories:
+Use the CLI to clean closed plans (`done` / `superseded` / `abandoned`). By default it
+**archives** plan directories to `.plans/.archive/<name>/` — keeping HANDOFF.md and
+tasks.jsonl as a record — rather than deleting them:
 
 ```bash
-# Preview what would be deleted
+# Preview what would be cleaned (no changes)
 npx @dreki-gg/pi-plan-mode clean --dry-run
 
-# Delete completed plans and update plans.json
+# Archive closed plans to .plans/.archive/ and update plans.jsonl
 npx @dreki-gg/pi-plan-mode clean
+
+# Permanently delete instead of archiving
+npx @dreki-gg/pi-plan-mode clean --purge
 ```
 
-In-flight plans (`"status": "in-progress"`) are never touched.
+In-flight plans (`"status": "in-progress"`) are never touched. Archiving is the default so
+that closing out a finished plan never silently destroys its handoff + task ledger.
 
 ### GitHub Actions
 
@@ -157,10 +192,11 @@ In plan mode, bash is restricted to read-only commands (ls, grep, git status, ca
 ## CLI reference
 
 ```
-pi-plan-mode clean [--dry-run]
+pi-plan-mode clean [--dry-run] [--purge]
 ```
 
-| Option      | Description                                      |
-| ----------- | ------------------------------------------------ |
-| `clean`     | Remove completed plan directories, update manifest |
-| `--dry-run` | Show what would be deleted without deleting      |
+| Option      | Description                                                        |
+| ----------- | ----------------------------------------------------------------- |
+| `clean`     | Archive closed plan directories to `.plans/.archive/`, update manifest |
+| `--dry-run` | Show what would be cleaned without changing anything              |
+| `--purge`   | Permanently delete instead of archiving                           |

package/bin/clean-plans.js

@@ -1,117 +1,143 @@
 #!/usr/bin/env node
 /**
- * CLI to clean completed plans from `.plans/`.
+ * CLI to clean closed plans from `.plans/`.
  *
  * Usage:
- *   npx @dreki-gg/pi-plan-mode clean [--dry-run]
+ *   npx @dreki-gg/pi-plan-mode clean [--dry-run] [--purge]
  *
- * Reads `.plans/plans.json`, deletes directories for plans with status "done",
- * and updates `plans.json` to remove them.
+ * Reads `.plans/plans.jsonl`, and for every plan whose status is terminal
+ * (done / superseded / abandoned):
+ *   - default:  ARCHIVES the plan directory to `.plans/.archive/<name>/`
+ *               (non-destructive — keeps HANDOFF.md + tasks.jsonl as a record)
+ *   - --purge:  permanently deletes the plan directory
+ * In both cases the entry is removed from the active `plans.jsonl` registry.
  *
  * Designed for use in GitHub Actions after merge — similar to changesets.
+ * History-preserving by default (FEEDBACK #4): closing out a finished plan must
+ * not silently destroy its handoff + task ledger.
  */
 
-import { readFileSync, writeFileSync, rmSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, rmSync, renameSync, mkdirSync, existsSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 
 const PLANS_DIR = '.plans';
-const PLANS_JSON = join(PLANS_DIR, 'plans.json');
+const ARCHIVE_DIR = join(PLANS_DIR, '.archive');
+const MANIFEST_PATH = join(PLANS_DIR, 'plans.jsonl');
+
+const TERMINAL_STATUSES = new Set(['done', 'superseded', 'abandoned']);
+
+/** Parse `.plans/plans.jsonl` into an array of plan entries. */
+function readManifest(path) {
+  const text = readFileSync(path, 'utf-8');
+  const entries = [];
+  for (const [index, raw] of text.split(/\r?\n/).entries()) {
+    if (!raw.trim()) continue;
+    try {
+      entries.push(JSON.parse(raw));
+    } catch (err) {
+      console.error(`Failed to parse ${MANIFEST_PATH} at line ${index + 1}:`, err);
+      process.exit(1);
+    }
+  }
+  return entries;
+}
+
+function writeManifest(path, entries) {
+  const content =
+    entries.map((entry) => JSON.stringify(entry)).join('\n') + (entries.length ? '\n' : '');
+  writeFileSync(path, content);
+}
 
 function main() {
   const args = process.argv.slice(2);
   const command = args[0];
 
   if (command !== 'clean') {
-    console.error('Usage: pi-plan-mode clean [--dry-run]\n');
+    console.error('Usage: pi-plan-mode clean [--dry-run] [--purge]\n');
     console.error('Commands:');
-    console.error('  clean       Remove completed plan directories and update plans.json\n');
+    console.error('  clean       Archive closed plan directories and update plans.jsonl\n');
     console.error('Options:');
-    console.error('  --dry-run   Show what would be deleted without actually deleting');
+    console.error('  --dry-run   Show what would be cleaned without changing anything');
+    console.error('  --purge     Permanently delete instead of archiving to .plans/.archive/');
     process.exit(1);
   }
 
   const dryRun = args.includes('--dry-run');
-  const plansJsonPath = resolve(PLANS_JSON);
+  const purge = args.includes('--purge');
+  const manifestPath = resolve(MANIFEST_PATH);
 
-  if (!existsSync(plansJsonPath)) {
-    console.log('No .plans/plans.json found — nothing to clean.');
+  if (!existsSync(manifestPath)) {
+    console.log(`No ${MANIFEST_PATH} found — nothing to clean.`);
     process.exit(0);
   }
 
-  /** @type {Record<string, { status: string; title: string; created: string; completed: string | null }>} */
-  let manifest;
-  try {
-    manifest = JSON.parse(readFileSync(plansJsonPath, 'utf-8'));
-  } catch (err) {
-    console.error(`Failed to parse ${PLANS_JSON}:`, err);
-    process.exit(1);
-  }
-
-  const donePlans = Object.entries(manifest).filter(([, entry]) => entry.status === 'done');
-  const inFlightPlans = Object.entries(manifest).filter(
-    ([, entry]) => entry.status === 'in-progress',
-  );
+  const entries = readManifest(manifestPath);
+  const closed = entries.filter((entry) => TERMINAL_STATUSES.has(entry.status));
+  const inFlight = entries.filter((entry) => entry.status === 'in-progress');
 
-  if (donePlans.length === 0) {
-    console.log('No completed plans to clean.');
-    if (inFlightPlans.length > 0) {
-      console.log(`\n${inFlightPlans.length} plan(s) still in progress:`);
-      for (const [name, entry] of inFlightPlans) {
-        console.log(`  ○ ${name} — ${entry.title}`);
-      }
+  if (closed.length === 0) {
+    console.log('No closed plans to clean.');
+    if (inFlight.length > 0) {
+      console.log(`\n${inFlight.length} plan(s) still in progress:`);
+      for (const entry of inFlight) console.log(`  ○ ${entry.name} — ${entry.title}`);
     }
     process.exit(0);
   }
 
-  console.log(dryRun ? 'Dry run — would clean:\n' : 'Cleaning completed plans:\n');
+  const verb = purge ? 'delete' : 'archive';
+  console.log(
+    dryRun ? `Dry run — would ${verb}:\n` : `${purge ? 'Deleting' : 'Archiving'} closed plans:\n`,
+  );
 
+  if (!dryRun && !purge && !existsSync(resolve(ARCHIVE_DIR))) {
+    mkdirSync(resolve(ARCHIVE_DIR), { recursive: true });
+  }
+
+  const remaining = [...inFlight];
   let cleaned = 0;
-  for (const [name, entry] of donePlans) {
-    const planPath = resolve(join(PLANS_DIR, name));
+  for (const entry of closed) {
+    const planPath = resolve(join(PLANS_DIR, entry.name));
     const exists = existsSync(planPath);
+    const label = `${entry.name} — ${entry.title} [${entry.status}]`;
 
     if (dryRun) {
-      console.log(`  ✓ ${name} — ${entry.title}${exists ? '' : ' (directory already missing)'}`);
-    } else {
-      if (exists) {
+      console.log(`  ✓ ${label}${exists ? '' : ' (directory already missing)'}`);
+      continue;
+    }
+
+    if (exists) {
+      if (purge) {
         rmSync(planPath, { recursive: true, force: true });
-        console.log(`  ✓ Deleted ${PLANS_DIR}/${name} — ${entry.title}`);
+        console.log(`  ✓ Deleted ${PLANS_DIR}/${entry.name} — ${label}`);
       } else {
-        console.log(`  ✓ ${name} — directory already missing, removing from manifest`);
+        const dest = resolve(join(ARCHIVE_DIR, entry.name));
+        rmSync(dest, { recursive: true, force: true }); // replace any stale archive
+        renameSync(planPath, dest);
+        console.log(`  ✓ Archived ${PLANS_DIR}/${entry.name} → ${ARCHIVE_DIR}/${entry.name}`);
       }
-      delete manifest[name];
-      cleaned++;
+    } else {
+      console.log(`  ✓ ${entry.name} — directory already missing, removing from manifest`);
     }
+    cleaned++;
   }
 
-  if (!dryRun) {
-    const remaining = Object.keys(manifest).length;
-    if (remaining === 0) {
-      rmSync(plansJsonPath, { force: true });
-      // Remove .plans/ if completely empty
-      const plansDir = resolve(PLANS_DIR);
-      try {
-        if (existsSync(plansDir) && readdirSync(plansDir).length === 0) {
-          rmSync(plansDir, { recursive: true, force: true });
-          console.log(`\nRemoved empty ${PLANS_DIR}/`);
-        }
-      } catch {
-        // Directory might have other contents
-      }
-    } else {
-      writeFileSync(plansJsonPath, JSON.stringify(manifest, null, 2) + '\n');
+  if (dryRun) {
+    console.log(`\n${closed.length} plan(s) would be cleaned.`);
+    if (inFlight.length > 0) {
+      console.log(`${inFlight.length} plan(s) still in progress (will be kept).`);
     }
+    return;
+  }
 
-    console.log(`\nCleaned ${cleaned} plan(s).`);
-    if (remaining > 0) {
-      console.log(`${remaining} plan(s) still in progress.`);
-    }
+  if (remaining.length === 0) {
+    rmSync(manifestPath, { force: true });
   } else {
-    console.log(`\n${donePlans.length} plan(s) would be cleaned.`);
-    if (inFlightPlans.length > 0) {
-      console.log(`${inFlightPlans.length} plan(s) still in progress (will be kept).`);
-    }
+    writeManifest(manifestPath, remaining);
   }
+
+  console.log(`\nCleaned ${cleaned} plan(s).`);
+  if (remaining.length > 0) console.log(`${remaining.length} plan(s) still in progress.`);
+  if (!purge) console.log(`Archived plans kept in ${ARCHIVE_DIR}/ (use --purge to delete).`);
 }
 
 main();

package/extensions/plan-mode/__tests__/add-task.test.ts

@@ -7,8 +7,14 @@ const now = '2026-05-27T12:00:00.000Z';
 interface CapturedTool {
   execute: (
     id: string,
-    params: { description: string; reason: string; details?: string; depends_on?: string[] },
-  ) => Promise<{ details?: unknown }>;
+    params: {
+      description: string;
+      reason: string;
+      details?: string;
+      depends_on?: string[];
+      plan?: string;
+    },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
 }
 
 function setup(plan: PlanData | undefined) {
@@ -21,7 +27,8 @@ function setup(plan: PlanData | undefined) {
   } as unknown as Parameters<typeof registerAddTaskTool>[0];
 
   registerAddTaskTool(pi, {
-    getPlan: () => plan,
+    // Mirrors index.ts: in-memory plan wins; disk fallback returns candidates.
+    resolvePlan: async () => ({ plan, candidates: [] }),
     onTaskAdded: (task) => {
       added.push(task);
     },
@@ -66,10 +73,11 @@ describe('add_task tool', () => {
     expect(task.description).toBe('Extract shared helper');
   });
 
-  test('throws when there is no active plan', async () => {
-    const { tool } = setup(undefined);
-    await expect(tool.execute('call-1', { description: 'x', reason: 'y' })).rejects.toThrow(
-      /No active plan/,
-    );
+  test('soft-skips (does not throw) when there is no active plan', async () => {
+    const { tool, added } = setup(undefined);
+    const result = await tool.execute('call-1', { description: 'x', reason: 'y' });
+    expect((result.details as { skipped?: boolean }).skipped).toBe(true);
+    expect(result.content?.[0]?.text).toMatch(/no active plan/i);
+    expect(added).toHaveLength(0);
   });
 });

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

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test';
+import { registerPlanStatusTool } from '../tools/plan-status.js';
+import type { PlanData, TaskRecord, TaskStatus } from '../types.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { plan?: string },
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
+}
+
+function setup(
+  plan: PlanData | undefined,
+  candidates: string[] = [],
+  inProgress?: Array<{ name: string; title: string; resolved: number; total: number }>,
+) {
+  let tool: CapturedTool | undefined;
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerPlanStatusTool>[0];
+  registerPlanStatusTool(pi, {
+    resolvePlan: async () => ({ plan, candidates }),
+    listInProgress: inProgress ? async () => inProgress : undefined,
+  });
+  return tool!;
+}
+
+const planTask = (id: string, status: TaskStatus): TaskRecord => ({
+  _type: 'task',
+  id,
+  description: `task ${id}`,
+  status,
+  origin: 'plan',
+  created_at: now,
+  updated_at: now,
+});
+
+describe('plan_status tool', () => {
+  test('summarizes progress + lists task ids and statuses', async () => {
+    const plan: PlanData = {
+      title: 'My Plan',
+      planName: 'my-plan',
+      handoff: '',
+      tasks: [
+        planTask('t-001', 'done'),
+        planTask('t-002', 'pending'),
+        planTask('t-003', 'blocked'),
+      ],
+    };
+    const tool = setup(plan);
+    const result = await tool.execute('c', {});
+
+    const text = result.content?.[0]?.text ?? '';
+    expect(text).toMatch(/My Plan \(my-plan\)/);
+    expect(text).toMatch(/1\/3 resolved/);
+    expect(text).toMatch(/blocked 1/);
+    expect(text).toMatch(/t-002 \[pending\]/);
+
+    const details = result.details as { active: boolean; task_ids: string[]; total: number };
+    expect(details.active).toBe(true);
+    expect(details.task_ids).toEqual(['t-001', 't-002', 't-003']);
+    expect(details.total).toBe(3);
+  });
+
+  test('reports no active plan (read-only, no throw) with candidates', async () => {
+    const tool = setup(undefined, ['alpha', 'beta']);
+    const result = await tool.execute('c', {});
+    expect((result.details as { active: boolean }).active).toBe(false);
+    expect(result.content?.[0]?.text).toMatch(/alpha, beta/);
+  });
+
+  test('renders a progress table when multiple plans are in-progress (FEEDBACK #5)', async () => {
+    const tool = setup(
+      undefined,
+      ['alpha', 'beta'],
+      [
+        { name: 'alpha', title: 'Alpha', resolved: 7, total: 17 },
+        { name: 'beta', title: 'Beta', resolved: 8, total: 8 },
+      ],
+    );
+    const result = await tool.execute('c', {});
+    const text = result.content?.[0]?.text ?? '';
+    expect(text).toMatch(/2 in-progress/);
+    expect(text).toMatch(/7\/17  alpha/);
+    // A fully-resolved plan still listed in-progress is flagged as a reconcile cue.
+    expect(text).toMatch(/8\/8  beta — Beta  ⚠ done\?/);
+    const details = result.details as { in_progress?: unknown[] };
+    expect(details.in_progress).toHaveLength(2);
+  });
+});

package/extensions/plan-mode/__tests__/plans-manifest.test.ts

@@ -7,6 +7,7 @@ import { tmpdir } from 'node:os';
 import { FileSystem, nodeFileSystemService } from '../effects/filesystem.js';
 import {
   readPlansManifest,
+  reconcilePlanStatus,
   upsertPlanEntry,
   writePlansManifest,
 } from '../storage/plans-manifest.js';
@@ -71,4 +72,49 @@ describe('plans.jsonl manifest', () => {
     expect(entry.status).toBe('done');
     expect(entry.completed_at).toBeString();
   });
+
+  test('records a reason for terminal statuses and clears completed_at on reopen', async () => {
+    await run(upsertPlanEntry('p', { status: 'in-progress', title: 'P' }));
+    await run(upsertPlanEntry('p', { status: 'superseded', reason: 'absorbed by q' }));
+    let [entry] = await run(readPlansManifest());
+    expect(entry.status).toBe('superseded');
+    expect(entry.reason).toBe('absorbed by q');
+    expect(entry.completed_at).toBeString();
+
+    // Reopening clears completed_at.
+    await run(upsertPlanEntry('p', { status: 'in-progress' }));
+    [entry] = await run(readPlansManifest());
+    expect(entry.status).toBe('in-progress');
+    expect(entry.completed_at).toBeNull();
+  });
+});
+
+describe('reconcilePlanStatus (registry as a projection of task state)', () => {
+  test('flips in-progress → done when finalizable', async () => {
+    await run(upsertPlanEntry('p', { status: 'in-progress', title: 'P' }));
+    await run(reconcilePlanStatus('p', true, 'P'));
+    const [entry] = await run(readPlansManifest());
+    expect(entry.status).toBe('done');
+  });
+
+  test('reopens done → in-progress when no longer finalizable', async () => {
+    await run(upsertPlanEntry('p', { status: 'done', title: 'P' }));
+    await run(reconcilePlanStatus('p', false, 'P'));
+    const [entry] = await run(readPlansManifest());
+    expect(entry.status).toBe('in-progress');
+    expect(entry.completed_at).toBeNull();
+  });
+
+  test('never overrides a manually-closed terminal status', async () => {
+    await run(upsertPlanEntry('p', { status: 'abandoned', title: 'P', reason: 'rejected' }));
+    await run(reconcilePlanStatus('p', true, 'P'));
+    const [entry] = await run(readPlansManifest());
+    expect(entry.status).toBe('abandoned');
+    expect(entry.reason).toBe('rejected');
+  });
+
+  test('is a no-op for an unknown plan (nothing created)', async () => {
+    await run(reconcilePlanStatus('ghost', true));
+    await expect(run(readPlansManifest())).resolves.toEqual([]);
+  });
 });

package/extensions/plan-mode/__tests__/reconcile-plans.test.ts

@@ -0,0 +1,83 @@
+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 { writeTasksJsonl } from '../storage/task-storage.js';
+import { readPlansManifest, upsertPlanEntry } from '../storage/plans-manifest.js';
+import { registerReconcilePlansTool } from '../tools/reconcile-plans.js';
+import type { TaskMeta, TaskRecord } from '../types.js';
+
+const runPlanIO = makePlanRuntime();
+const now = '2026-05-27T12:00:00.000Z';
+
+const meta = (name: string): TaskMeta => ({
+  _type: 'meta',
+  title: `Title ${name}`,
+  plan_name: name,
+  created_at: now,
+});
+const doneTask = (id: string): TaskRecord => ({
+  _type: 'task',
+  id,
+  description: `task ${id}`,
+  status: 'done',
+  origin: 'plan',
+  created_at: now,
+  updated_at: now,
+});
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { apply?: boolean },
+  ) => 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 registerReconcilePlansTool>[0];
+  registerReconcilePlansTool(pi, runPlanIO);
+  return tool!;
+}
+
+const originalCwd = process.cwd();
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-reconcile-tool-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('reconcile_plans tool', () => {
+  test('reports drift read-only without changing the registry', async () => {
+    await runPlanIO(writeTasksJsonl('.plans/alpha', meta('alpha'), [doneTask('t-001')]));
+    await runPlanIO(upsertPlanEntry('alpha', { status: 'in-progress', title: 'Title alpha' }));
+
+    const tool = setup();
+    const result = await tool.execute('c', {});
+    expect(result.content?.[0]?.text).toMatch(/drift issue/);
+    // Read-only: registry unchanged.
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('in-progress');
+  });
+
+  test('apply:true repairs status drift', async () => {
+    await runPlanIO(writeTasksJsonl('.plans/alpha', meta('alpha'), [doneTask('t-001')]));
+    await runPlanIO(upsertPlanEntry('alpha', { status: 'in-progress', title: 'Title alpha' }));
+
+    const tool = setup();
+    const result = await tool.execute('c', { apply: true });
+    expect((result.details as { repaired?: string[] }).repaired).toEqual(['alpha']);
+    const [entry] = await runPlanIO(readPlansManifest());
+    expect(entry.status).toBe('done');
+  });
+});