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

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

@@ -2,6 +2,7 @@ import { Effect, Either, Option } from 'effect';
 import { FileSystem } from '../effects/filesystem.js';
 import { JsonlParseError, JsonlValidationError, PlanWriteError } from '../errors.js';
 import { decodePlanManifestEntry } from '../schema.js';
+import type { PlanStatus } from '../types.js';
 
 const MANIFEST_DIR = '.plans';
 const MANIFEST_PATH = '.plans/plans.jsonl';
@@ -9,10 +10,16 @@ const MANIFEST_PATH = '.plans/plans.jsonl';
 export interface PlanManifestEntry {
   _type: 'plan';
   name: string;
-  status: 'in-progress' | 'done';
+  status: PlanStatus;
   title: string;
   created_at: string;
   completed_at: string | null;
+  reason?: string;
+}
+
+/** A status is terminal (closed) when it is anything other than in-progress. */
+export function isTerminalStatus(status: PlanStatus): boolean {
+  return status !== 'in-progress';
 }
 
 type ReadError = JsonlParseError | JsonlValidationError;
@@ -62,7 +69,7 @@ export function writePlansManifest(
 
 export function upsertPlanEntry(
   name: string,
-  updates: { status: 'in-progress' | 'done'; title?: string },
+  updates: { status: PlanStatus; title?: string; reason?: string },
 ): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
   return Effect.gen(function* () {
     const entries = yield* readPlansManifest();
@@ -75,10 +82,42 @@ export function upsertPlanEntry(
       status: updates.status,
       title: updates.title ?? existing?.title ?? 'Untitled plan',
       created_at: existing?.created_at ?? now,
-      completed_at: updates.status === 'done' ? now : null,
+      // Terminal statuses record a completion timestamp; reopening clears it.
+      completed_at: isTerminalStatus(updates.status) ? (existing?.completed_at ?? now) : null,
+      reason: updates.reason ?? existing?.reason,
     };
     if (index === -1) entries.push(entry);
     else entries[index] = entry;
     yield* writePlansManifest(entries);
   });
 }
+
+/**
+ * Reconcile a plan's registry status from its task state.
+ *
+ * The registry `status` is a PROJECTION of task state, not a parallel flag.
+ * Call this wherever tasks are written so completion is never coupled to a
+ * formal in-session execution run (see FEEDBACK #1). `finalizable` means every
+ * active task is resolved AND no deferred follow-ups remain.
+ *
+ * Guard: a manually-set terminal status (`superseded` / `abandoned`) is never
+ * auto-overridden — only `in-progress` ⇄ `done` is derived from tasks.
+ */
+export function reconcilePlanStatus(
+  name: string,
+  finalizable: boolean,
+  title?: string,
+): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const entries = yield* readPlansManifest();
+    const existing = entries.find((entry) => entry.name === name);
+    // Reconcile only reflects task state for KNOWN plans; never conjure an
+    // entry for an unregistered plan (orphans are surfaced, not auto-created).
+    if (!existing) return;
+    // Do not resurrect / clobber an explicitly closed plan.
+    if (existing.status === 'superseded' || existing.status === 'abandoned') return;
+    const status: PlanStatus = finalizable ? 'done' : 'in-progress';
+    if (existing.status === status) return; // no change
+    yield* upsertPlanEntry(name, { status, title });
+  });
+}

package/extensions/plan-mode/tools/plan-status.ts

@@ -13,9 +13,22 @@ import { Type } from 'typebox';
 import type { TaskStatus } from '../types.js';
 import type { ResolvedPlan } from '../resolve-plan.js';
 
+export interface InProgressSummary {
+  name: string;
+  title: string;
+  resolved: number;
+  total: number;
+}
+
 export interface PlanStatusCallbacks {
   /** Resolve the active plan, attaching from disk when none is in memory. */
   resolvePlan: (opts?: { name?: string }) => Promise<ResolvedPlan>;
+  /**
+   * List every in-progress plan with progress counts. Used to render a
+   * progress-at-a-glance table when no single plan can be resolved
+   * (multiple in-progress) — surfaces drift (e.g. a 17/17 plan still listed).
+   */
+  listInProgress?: () => Promise<InProgressSummary[]>;
 }
 
 const STATUS_GLYPH: Record<TaskStatus, string> = {
@@ -49,6 +62,25 @@ export function registerPlanStatusTool(pi: ExtensionAPI, callbacks: PlanStatusCa
     async execute(_toolCallId, params) {
       const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
       if (!plan) {
+        // Multiple in-progress plans: show a progress-at-a-glance table rather
+        // than a bare name list (FEEDBACK #5). The counts surface drift too —
+        // a fully-resolved plan still listed in-progress is a reconcile cue.
+        if (candidates.length > 1 && callbacks.listInProgress) {
+          const summaries = await callbacks.listInProgress();
+          const rows = summaries
+            .map((s) => {
+              const flag = s.total > 0 && s.resolved === s.total ? '  ⚠ done?' : '';
+              return `  ${s.resolved}/${s.total}  ${s.name} — ${s.title}${flag}`;
+            })
+            .join('\n');
+          const text =
+            `No single active plan — ${summaries.length} in-progress. Pass { plan: "<name>" } to target one.\n` +
+            `Progress:\n${rows}`;
+          return {
+            content: [{ type: 'text' as const, text }],
+            details: { active: false, candidates, in_progress: summaries },
+          };
+        }
         const hint =
           candidates.length > 1
             ? ` In-progress plans: ${candidates.join(', ')} — pass { plan: "<name>" }.`

package/extensions/plan-mode/tools/reconcile-plans.ts

@@ -0,0 +1,118 @@
+/**
+ * reconcile_plans tool — detect & repair drift between tasks and registry.
+ *
+ * Walks every plan, compares the registry `status` against the status derived
+ * from `tasks.jsonl`, and reports the diff (FEEDBACK #6). With `apply: true` it
+ * repairs the safe `in-progress` ⇄ `done` projection; orphans and
+ * registry-only plans are surfaced for a human decision but never auto-changed.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import type { RunPlanIO } from '../effects/runtime.js';
+import { applyReconcile, collectPlanDrift, type PlanDriftRow } from '../reconcile.js';
+
+function describeRow(row: PlanDriftRow): string {
+  const progress = row.hasTasks ? ` (${row.resolved}/${row.total})` : '';
+  if (row.drift === 'registry-only') {
+    return `  ⚠ ${row.name} — registry ${row.registryStatus}, no tasks.jsonl (un-trackable)`;
+  }
+  if (row.drift === 'orphan') {
+    return `  ⚠ ${row.name}${progress} — tasks.jsonl with no registry entry (orphan)`;
+  }
+  if (row.drift === 'status') {
+    return `  ✗ ${row.name}${progress} — registry ${row.registryStatus}, tasks say ${row.derivedStatus}`;
+  }
+  return `  ✓ ${row.name}${progress} — ${row.registryStatus} (in sync)`;
+}
+
+export function registerReconcilePlansTool(pi: ExtensionAPI, runPlanIO: RunPlanIO): void {
+  pi.registerTool({
+    name: 'reconcile_plans',
+    label: 'Reconcile Plans',
+    description:
+      'Walk every plan and report where the registry status disagrees with task state (drift), plus orphan task dirs and registry-only plans. Pass apply:true to repair safe in-progress↔done drift.',
+    promptSnippet: 'Detect/repair drift between tasks.jsonl and the plan registry',
+    promptGuidelines: [
+      'Use reconcile_plans to audit .plans/ when registry status looks stale (e.g. a fully-done plan still in-progress).',
+      'Run it read-only first; pass apply:true once you have reviewed the reported drift.',
+    ],
+    parameters: Type.Object({
+      apply: Type.Optional(
+        Type.Boolean({
+          description: 'Repair status-drift by projecting derived task status into the registry.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const rows = await runPlanIO(collectPlanDrift());
+      const drifted = rows.filter((row) => row.drift);
+
+      let repaired: PlanDriftRow[] = [];
+      if (params.apply) {
+        repaired = await runPlanIO(applyReconcile(rows));
+      }
+
+      const lines = rows.map(describeRow);
+      const statusDrift = drifted.filter((r) => r.drift === 'status').length;
+      const orphans = drifted.filter((r) => r.drift === 'orphan').length;
+      const registryOnly = drifted.filter((r) => r.drift === 'registry-only').length;
+
+      const header = params.apply
+        ? `Reconciled ${repaired.length} plan(s).`
+        : drifted.length === 0
+          ? 'All plans in sync.'
+          : `${drifted.length} drift issue(s) found (run with apply:true to repair status drift).`;
+
+      const summary = [
+        `status-drift ${statusDrift}`,
+        `orphan ${orphans}`,
+        `registry-only ${registryOnly}`,
+      ].join(', ');
+
+      const text = `${header}\n${summary}\n${lines.join('\n')}`;
+      return {
+        content: [{ type: 'text' as const, text }],
+        details: {
+          applied: Boolean(params.apply),
+          repaired: repaired.map((r) => r.name),
+          drift: drifted.map((r) => ({ name: r.name, kind: r.drift })),
+          total: rows.length,
+        },
+      };
+    },
+
+    renderCall(args, theme) {
+      const apply = (args as { apply?: boolean }).apply;
+      let content = theme.fg('toolTitle', theme.bold('reconcile_plans'));
+      if (apply) content += ' ' + theme.fg('warning', 'apply');
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as
+        | { applied?: boolean; repaired?: string[]; drift?: unknown[]; total?: number }
+        | undefined;
+      if (!details) return new Text(theme.fg('dim', 'Reconciled'), 0, 0);
+      const driftCount = details.drift?.length ?? 0;
+      if (details.applied) {
+        return new Text(
+          theme.fg('success', `✓ repaired ${details.repaired?.length ?? 0}`) +
+            theme.fg('muted', ` / ${details.total ?? 0} plans`),
+          0,
+          0,
+        );
+      }
+      return new Text(
+        driftCount === 0
+          ? theme.fg('success', `✓ ${details.total ?? 0} plans in sync`)
+          : theme.fg('warning', `${driftCount} drift`) +
+              theme.fg('muted', ` / ${details.total ?? 0} plans`),
+        0,
+        0,
+      );
+    },
+  });
+}

package/extensions/plan-mode/tools/update-plan.ts

@@ -0,0 +1,123 @@
+/**
+ * update_plan tool — plan-level lifecycle control.
+ *
+ * `update_task` tracks task status; this is its plan-level counterpart
+ * (FEEDBACK #2/#3). It lets an agent or user close a plan without a full
+ * execution run or hand-editing `.plans/plans.jsonl`:
+ *   - done       — completed (work shipped)
+ *   - superseded — another plan absorbed the work
+ *   - abandoned  — won't do / rejected
+ *   - in-progress — reopen
+ * `reason` is recorded for honest history (esp. superseded/abandoned).
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { StringEnum } from '@earendil-works/pi-ai';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import type { PlanStatus } from '../types.js';
+import type { RunPlanIO } from '../effects/runtime.js';
+import { readPlansManifest, upsertPlanEntry } from '../storage/plans-manifest.js';
+
+/** Normalize a plan hint (`my-plan` or `.plans/my-plan`) to a bare name. */
+function normalizeName(hint: string): string {
+  return hint
+    .replace(/^\.plans\//, '')
+    .replace(/\/+$/, '')
+    .trim();
+}
+
+export function registerUpdatePlanTool(pi: ExtensionAPI, runPlanIO: RunPlanIO): void {
+  pi.registerTool({
+    name: 'update_plan',
+    label: 'Update Plan',
+    description:
+      'Set a plan-level status (done, superseded, abandoned, or reopen to in-progress) with an optional reason. Use to close a plan without a full execution run instead of hand-editing the registry.',
+    promptSnippet: 'Close or reopen a plan (done/superseded/abandoned/in-progress) with a reason',
+    promptGuidelines: [
+      'Use update_plan to close a plan that will not be executed to completion: superseded (another plan shipped it) or abandoned (rejected / won\u2019t do).',
+      'Always pass a reason for superseded/abandoned so the registry keeps honest history.',
+      'Prefer update_task for per-task progress; update_plan is for the whole plan\u2019s lifecycle.',
+    ],
+    parameters: Type.Object({
+      plan: Type.String({ description: 'Plan name (or .plans/<name>) to update' }),
+      status: StringEnum(['in-progress', 'done', 'superseded', 'abandoned'] as const),
+      reason: Type.Optional(
+        Type.String({ description: 'Why — recorded in the registry (esp. superseded/abandoned)' }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const name = normalizeName(params.plan);
+      const manifest = await runPlanIO(readPlansManifest());
+      const existing = manifest.find((entry) => entry.name === name);
+      if (!existing) {
+        const names = manifest.map((entry) => entry.name).join(', ');
+        const notFound: Record<string, unknown> = { error: 'not_found', plan: name };
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Plan not found: ${name}. Known plans: ${names || '(none)'}`,
+            },
+          ],
+          details: notFound,
+        };
+      }
+
+      await runPlanIO(
+        upsertPlanEntry(name, {
+          status: params.status as PlanStatus,
+          title: existing.title,
+          reason: params.reason,
+        }),
+      );
+
+      const reasonSuffix = params.reason ? ` — ${params.reason}` : '';
+      const okDetails: Record<string, unknown> = {
+        plan: name,
+        from: existing.status,
+        status: params.status,
+        reason: params.reason,
+      };
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Plan ${name}: ${existing.status} → ${params.status}${reasonSuffix}`,
+          },
+        ],
+        details: okDetails,
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { plan?: string }).plan ?? 'plan';
+      const status = (args as { status?: string }).status ?? '';
+      let content = theme.fg('toolTitle', theme.bold('update_plan '));
+      content += theme.fg('accent', name);
+      if (status) content += ' ' + theme.fg('muted', status);
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as
+        | { plan?: string; from?: string; status?: string }
+        | undefined;
+      if (!details?.status) return new Text(theme.fg('dim', 'Plan updated'), 0, 0);
+      const color =
+        details.status === 'done'
+          ? 'success'
+          : details.status === 'in-progress'
+            ? 'accent'
+            : 'warning';
+      return new Text(
+        theme.fg('muted', `${details.plan ?? 'plan'} `) +
+          theme.fg('dim', `${details.from ?? ''} → `) +
+          theme.fg(color, details.status),
+        0,
+        0,
+      );
+    },
+  });
+}

package/extensions/plan-mode/tools/update-tasks.ts

@@ -0,0 +1,172 @@
+/**
+ * update_tasks tool — batch sibling of update_task.
+ *
+ * Marks several tasks done/skipped in a single call. Unlike update_task it
+ * never blocks (blocking pauses the turn, which is ambiguous mid-batch) and
+ * therefore never terminates. Each item mirrors update_task's per-task
+ * semantics: idempotent no-ops, corrections, and soft not_found handling.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { StringEnum } from '@earendil-works/pi-ai';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import type { TaskStatus } from '../types.js';
+import type { ResolvedPlan } from '../resolve-plan.js';
+
+export interface UpdateTasksCallbacks {
+  /** Resolve the active plan, attaching from disk when none is in memory. */
+  resolvePlan: (opts?: { name?: string }) => Promise<ResolvedPlan>;
+  /**
+   * Apply ALL accepted updates in one shot. The implementation mutates the
+   * in-memory tasks, then performs a SINGLE coalesced tasks.jsonl write and
+   * registry reconcile — avoiding the per-task write storm that caused file
+   * write contention with repeated update_task calls.
+   */
+  onTasksUpdated: (
+    updates: Array<{
+      taskId: string;
+      status: Exclude<TaskStatus, 'pending' | 'blocked' | 'deferred'>;
+      notes?: string;
+    }>,
+  ) => void | Promise<void>;
+}
+
+/** A non-terminating tool result — task tracking must never derail real work. */
+function soft(text: string, details: Record<string, unknown>) {
+  return { content: [{ type: 'text' as const, text }], details };
+}
+
+type ItemOutcome = 'updated' | 'noop' | 'not_found';
+
+interface ItemResult {
+  task_id: string;
+  outcome: ItemOutcome;
+  status?: 'done' | 'skipped';
+  prior?: string;
+}
+
+export function registerUpdateTasksTool(pi: ExtensionAPI, callbacks: UpdateTasksCallbacks): void {
+  pi.registerTool({
+    name: 'update_tasks',
+    label: 'Update Tasks',
+    description:
+      'Mark several plan tasks done or skipped in one call. Use when you finished multiple tasks in a turn. Cannot block — use update_task for that.',
+    promptSnippet: 'Mark multiple plan tasks done or skipped in one call',
+    promptGuidelines: [
+      'Use update_tasks to resolve several finished tasks at once instead of repeated update_task calls.',
+      'Each item is { task_id, status: done|skipped, notes? }. To block a task, use update_task instead.',
+      'Always include notes summarizing what was done or why skipped.',
+    ],
+    parameters: Type.Object({
+      updates: Type.Array(
+        Type.Object({
+          task_id: Type.String({ description: 'Task ID (for example, t-001)' }),
+          status: StringEnum(['done', 'skipped'] as const),
+          notes: Type.Optional(
+            Type.String({ description: 'What was done or why skipped' }),
+          ),
+        }),
+        { description: 'Tasks to mark, each with its own status and notes', minItems: 1 },
+      ),
+      plan: Type.Optional(
+        Type.String({
+          description:
+            'Plan name (or .plans/<name>) to target. Only needed to disambiguate when multiple plans are in-progress; otherwise the active / sole in-progress plan is used.',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
+      // No active plan is a tracking miss, not an error: return a soft result
+      // (non-terminating) so the agent keeps doing the real work.
+      if (!plan) {
+        const hint =
+          candidates.length > 1
+            ? ` Multiple in-progress plans (${candidates.join(', ')}) — pass { plan: "<name>" } to choose.`
+            : ' No in-progress plan found in .plans/plans.jsonl.';
+        return soft(`Skipped task tracking — no active plan.${hint}`, {
+          skipped: true,
+          candidates,
+        });
+      }
+
+      const results: ItemResult[] = [];
+      const accepted: Array<{ taskId: string; status: 'done' | 'skipped'; notes?: string }> = [];
+      for (const update of params.updates) {
+        const task = plan.tasks.find((candidate) => candidate.id === update.task_id);
+        if (!task) {
+          results.push({ task_id: update.task_id, outcome: 'not_found' });
+          continue;
+        }
+        // Idempotent: re-marking the same status is a no-op (safe to retry).
+        if (task.status === update.status) {
+          results.push({ task_id: update.task_id, outcome: 'noop', status: update.status });
+          continue;
+        }
+        // A different status on an already-resolved task is a CORRECTION — apply
+        // it. The plan queue recomputes from the new status.
+        results.push({
+          task_id: update.task_id,
+          outcome: 'updated',
+          status: update.status,
+          prior: task.status,
+        });
+        accepted.push({ taskId: update.task_id, status: update.status, notes: update.notes });
+      }
+
+      // SINGLE coalesced write: apply every accepted change in one callback,
+      // which performs exactly one tasks.jsonl write + one registry reconcile.
+      if (accepted.length > 0) await callbacks.onTasksUpdated(accepted);
+
+      const updated = results.filter((r) => r.outcome === 'updated');
+      const noop = results.filter((r) => r.outcome === 'noop');
+      const notFound = results.filter((r) => r.outcome === 'not_found');
+
+      const done = plan.tasks.filter((candidate) => candidate.status === 'done').length;
+      const skipped = plan.tasks.filter((candidate) => candidate.status === 'skipped').length;
+      const resolved = done + skipped;
+      const next = plan.tasks.find((candidate) => candidate.status === 'pending');
+
+      const parts = [`Updated ${updated.length} task(s).`];
+      if (noop.length) parts.push(`${noop.length} no-op.`);
+      if (notFound.length) {
+        const ids = plan.tasks.map((candidate) => candidate.id).join(', ');
+        parts.push(`Not found: ${notFound.map((r) => r.task_id).join(', ')} (valid: ${ids}).`);
+      }
+      let text = parts.join(' ');
+      text += ` Progress: ${resolved}/${plan.tasks.length}`;
+      text += next ? `\n\nNext task ${next.id}: ${next.description}` : '\n\nAll tasks resolved!';
+
+      // Never terminate: update_tasks has no blocked path, and completion is
+      // handled out-of-band by the agent_end handler in index.ts.
+      return { content: [{ type: 'text' as const, text }], details: { results } };
+    },
+
+    renderCall(args, theme) {
+      const updates = (args as { updates?: Array<{ task_id?: string }> }).updates ?? [];
+      let content = theme.fg('toolTitle', theme.bold('update_tasks '));
+      content += theme.fg('muted', updates.map((u) => u.task_id ?? '?').join(', '));
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as { results?: ItemResult[] } | undefined;
+      const results = details?.results ?? [];
+      if (results.length === 0) return new Text(theme.fg('dim', 'Updated'), 0, 0);
+      const icon: Record<string, string> = {
+        done: theme.fg('success', '✓'),
+        skipped: theme.fg('warning', '⊘'),
+      };
+      const line = results
+        .map((r) => {
+          if (r.outcome === 'not_found') return theme.fg('error', `✗ ${r.task_id}`);
+          if (r.outcome === 'noop') return theme.fg('dim', `= ${r.task_id}`);
+          return `${icon[r.status ?? ''] ?? ''} ${r.task_id}`;
+        })
+        .join('  ');
+      return new Text(line, 0, 0);
+    },
+  });
+}

package/extensions/plan-mode/types.ts

@@ -7,6 +7,12 @@ export type TaskStatus = 'pending' | 'done' | 'skipped' | 'blocked' | 'deferred'
 /** Where a task came from: the original submitted plan, or discovered during execution. */
 export type TaskOrigin = 'plan' | 'discovered';
 
+/**
+ * Plan lifecycle status. Only `in-progress` is active; `done`, `superseded`,
+ * and `abandoned` are terminal and drop out of active-plan resolution.
+ */
+export type PlanStatus = 'in-progress' | 'done' | 'superseded' | 'abandoned';
+
 export interface TaskRecord {
   _type: 'task';
   id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Two-phase planning workflow for pi — plan with claude-opus-4-6:medium, execute with gpt-5.5:low, with .plans/ file-based handoff",
   "keywords": [
     "pi-package"