@dreki-gg/pi-plan-mode 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.29.0
+
+### Minor Changes
+
+- ffde28d: Plan into another project's `.plans/` and stop trusting in-memory plan status.
+
+  - `submit_plan`, `revise_plan`, and `add_task` now accept an optional `target`
+    pointing at another repo's root. When set, the plan is filed into that
+    project's `.plans/` registry — handy when you're dogfooding project A, hit a
+    gap in package B (which you author), and want the plan to live and later
+    execute in B. Author-only: an external plan is never pinned as the current
+    session's active plan, and a missing/invalid target is rejected up front.
+  - The plan-mode status bar no longer renders progress counts (`📋 2/5`) or mode
+    badges from in-memory state — that data drifted from disk. The agent reads
+    real status from the ledger via `plan_status` instead.
+  - `taskman` exposes `makeNodeFileSystemService(root)` and a `root` parameter on
+    `makePlanRuntime` / `makeRuntimeLayer`, so the whole `.plans/` registry can be
+    rooted at any working directory. Default behaviour (current working directory)
+    is unchanged.
+
+### Patch Changes
+
+- Updated dependencies [ffde28d]
+  - @dreki-gg/taskman@0.4.0
+
 ## 0.28.0
 
 ### Minor Changes

package/extensions/plan-mode/__tests__/external-target-tools.test.ts

@@ -0,0 +1,133 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chdir } from 'node:process';
+import { mkdtemp, rm, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { makePlanRuntime, writeTasksJsonl, upsertPlanEntry } from '@dreki-gg/taskman';
+import type { TaskMeta, TaskRecord } from '@dreki-gg/taskman';
+import { registerRevisePlanTool } from '../tools/revise-plan.js';
+import { registerAddTaskTool } from '../tools/add-task.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: Record<string, unknown>,
+  ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
+}
+
+function captureTool(register: (pi: unknown) => void): CapturedTool {
+  let tool: CapturedTool | undefined;
+  register({ registerTool: (config: CapturedTool) => (tool = config) });
+  return tool!;
+}
+
+/** Seed an in-progress plan with one done task into a target repo's .plans/. */
+async function seedPlan(targetDir: string): Promise<void> {
+  const io = makePlanRuntime(targetDir);
+  const meta: TaskMeta = { _type: 'meta', title: 'Gap', plan_name: 'gap', created_at: now };
+  const task: TaskRecord = {
+    _type: 'task',
+    id: 't-001',
+    description: 'done work',
+    details: '',
+    status: 'done',
+    origin: 'plan',
+    created_at: now,
+    updated_at: now,
+  };
+  await io(writeTasksJsonl('.plans/gap', meta, [task]));
+  await io(upsertPlanEntry('gap', { status: 'in-progress', title: 'Gap' }));
+}
+
+const originalCwd = process.cwd();
+let cwdDir: string;
+let targetDir: string;
+
+beforeEach(async () => {
+  cwdDir = await mkdtemp(join(tmpdir(), 'plan-mode-ext-cwd-'));
+  targetDir = await mkdtemp(join(tmpdir(), 'plan-mode-ext-target-'));
+  chdir(cwdDir);
+  await seedPlan(targetDir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(cwdDir, { recursive: true, force: true });
+  await rm(targetDir, { recursive: true, force: true });
+});
+
+describe('revise_plan — external target', () => {
+  test('rewrites the plan in the target repo and does not pin session state', async () => {
+    let pinned = false;
+    const tool = captureTool((pi) =>
+      registerRevisePlanTool(pi as never, makePlanRuntime(), {
+        resolvePlan: async () => ({ plan: undefined, candidates: [] }),
+        onPlanRevised: () => {
+          pinned = true;
+        },
+      }),
+    );
+
+    const res = await tool.execute('c', {
+      plan: 'gap',
+      title: 'Gap (revised)',
+      target: targetDir,
+    });
+
+    const manifest = await readFile(join(targetDir, '.plans', 'plans.jsonl'), 'utf-8');
+    expect(manifest).toContain('Gap (revised)');
+    expect(res.content?.[0]?.text).toMatch(/revised/);
+    expect((res.details as { target?: string }).target).toBe(targetDir);
+    expect(pinned).toBe(false);
+  });
+});
+
+describe('add_task — external target', () => {
+  test('appends a deferred task to the target plan, bypassing session callbacks', async () => {
+    let sessionCalled = false;
+    const tool = captureTool((pi) =>
+      registerAddTaskTool(pi as never, {
+        resolvePlan: async () => {
+          sessionCalled = true;
+          return { plan: undefined, candidates: [] };
+        },
+        onTaskAdded: () => {
+          sessionCalled = true;
+        },
+      }),
+    );
+
+    const res = await tool.execute('c', {
+      description: 'Fix the gap edge case',
+      reason: 'found while dogfooding',
+      plan: 'gap',
+      target: targetDir,
+    });
+
+    const tasks = await readFile(join(targetDir, '.plans', 'gap', 'tasks.jsonl'), 'utf-8');
+    expect(tasks).toContain('Fix the gap edge case');
+    expect(tasks).toContain('deferred');
+    expect(res.content?.[0]?.text).toMatch(/Captured follow-up t-002/);
+    expect(sessionCalled).toBe(false);
+  });
+
+  test('soft-skips when the plan does not exist in the target', async () => {
+    const tool = captureTool((pi) =>
+      registerAddTaskTool(pi as never, {
+        resolvePlan: async () => ({ plan: undefined, candidates: [] }),
+        onTaskAdded: () => {},
+      }),
+    );
+
+    const res = await tool.execute('c', {
+      description: 'x',
+      reason: 'y',
+      plan: 'nonexistent',
+      target: targetDir,
+    });
+
+    expect(res.content?.[0]?.text).toMatch(/plan not found/i);
+    expect((res.details as { skipped?: boolean }).skipped).toBe(true);
+  });
+});

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

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { chdir } from 'node:process';
-import { mkdtemp, rm } from 'node:fs/promises';
+import { mkdtemp, rm, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { makePlanRuntime } from '@dreki-gg/taskman';
@@ -20,6 +20,7 @@ interface SubmitParams {
   tasks: Array<{ id: string; description: string; details?: string }>;
   initiative?: string;
   depends_on_plans?: string[];
+  target?: string;
 }
 interface CapturedTool {
   execute: (
@@ -28,14 +29,14 @@ interface CapturedTool {
   ) => Promise<{ content?: Array<{ text: string }>; details?: unknown }>;
 }
 
-function setup(): CapturedTool {
+function setup(onPlanSubmitted: () => void = () => {}): CapturedTool {
   let tool: CapturedTool | undefined;
   const pi = {
     registerTool: (config: CapturedTool) => {
       tool = config;
     },
   } as unknown as Parameters<typeof registerSubmitPlanTool>[0];
-  registerSubmitPlanTool(pi, runPlanIO, { onPlanSubmitted: () => {} });
+  registerSubmitPlanTool(pi, runPlanIO, { onPlanSubmitted });
   return tool!;
 }
 
@@ -136,3 +137,42 @@ describe('submit_plan tool — initiative + plan deps', () => {
     expect(result.content?.[0]?.text).not.toMatch(/initiative/i);
   });
 });
+
+describe('submit_plan tool — external target', () => {
+  test('files the plan into the target repo, not cwd, and does not pin session state', async () => {
+    const targetDir = await mkdtemp(join(tmpdir(), 'plan-mode-target-'));
+    try {
+      let pinned = false;
+      const tool = setup(() => {
+        pinned = true;
+      });
+
+      const result = await tool.execute('c', baseParams({ target: targetDir }));
+
+      // Plan landed in the target repo's registry.
+      const targetManifest = await readFile(join(targetDir, '.plans', 'plans.jsonl'), 'utf-8');
+      expect(targetManifest).toContain('auth-jwt');
+      const tasks = await readFile(join(targetDir, '.plans', 'auth-jwt', 'tasks.jsonl'), 'utf-8');
+      expect(tasks).toContain('t-001');
+
+      // Nothing leaked into the current working directory.
+      await expect(
+        readFile(join(dir, '.plans', 'plans.jsonl'), 'utf-8'),
+      ).rejects.toThrow();
+
+      // Author-only: the active-plan callback is NOT invoked for external targets.
+      expect(pinned).toBe(false);
+      expect(result.content?.[0]?.text).toMatch(/filed into/);
+      expect((result.details as { target?: string }).target).toBe(targetDir);
+    } finally {
+      await rm(targetDir, { recursive: true, force: true });
+    }
+  });
+
+  test('rejects a target directory that does not exist', async () => {
+    const tool = setup();
+    await expect(
+      tool.execute('c', baseParams({ target: join(dir, 'does-not-exist') })),
+    ).rejects.toThrow(/does not exist/);
+  });
+});

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

@@ -0,0 +1,73 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { mkdir, writeFile as writeFileFs } from 'node:fs/promises';
+import {
+  resolvePlanTarget,
+  assertTargetReceived,
+  assertTargetTaskAppended,
+} from '../target.js';
+
+let dir: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-target-'));
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('resolvePlanTarget', () => {
+  test('returns undefined for absent / empty / whitespace input', async () => {
+    expect(await resolvePlanTarget(undefined)).toBeUndefined();
+    expect(await resolvePlanTarget('')).toBeUndefined();
+    expect(await resolvePlanTarget('   ')).toBeUndefined();
+  });
+
+  test('resolves an existing absolute directory', async () => {
+    expect(await resolvePlanTarget(dir)).toBe(dir);
+  });
+
+  test('resolves a relative path against cwd', async () => {
+    const rel = relative(process.cwd(), dir);
+    expect(await resolvePlanTarget(rel)).toBe(dir);
+  });
+
+  test('expands a leading ~ to the home directory', async () => {
+    expect(await resolvePlanTarget('~')).toBe(homedir());
+  });
+
+  test('throws when the target does not exist', async () => {
+    await expect(resolvePlanTarget(join(dir, 'nope'))).rejects.toThrow(/does not exist/);
+  });
+
+  test('throws when the target is a file, not a directory', async () => {
+    const file = join(dir, 'file.txt');
+    await writeFile(file, 'x');
+    await expect(resolvePlanTarget(file)).rejects.toThrow(/not a directory/);
+  });
+});
+
+describe('stale-target guards', () => {
+  test('assertTargetReceived throws when the target tasks file is absent', async () => {
+    await expect(assertTargetReceived(dir, '.plans/gap')).rejects.toThrow(
+      /does not support external targets/,
+    );
+  });
+
+  test('assertTargetReceived passes when the target tasks file exists', async () => {
+    await mkdir(join(dir, '.plans', 'gap'), { recursive: true });
+    await writeFileFs(join(dir, '.plans', 'gap', 'tasks.jsonl'), '{"_type":"meta"}\n');
+    await expect(assertTargetReceived(dir, '.plans/gap')).resolves.toBeUndefined();
+  });
+
+  test('assertTargetTaskAppended throws when the task id is not in the target file', async () => {
+    await mkdir(join(dir, '.plans', 'gap'), { recursive: true });
+    await writeFileFs(join(dir, '.plans', 'gap', 'tasks.jsonl'), '{"id":"t-001"}\n');
+    await expect(assertTargetTaskAppended(dir, '.plans/gap', 't-002')).rejects.toThrow(
+      /external targets/,
+    );
+    await expect(assertTargetTaskAppended(dir, '.plans/gap', 't-001')).resolves.toBeUndefined();
+  });
+});

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

@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test';
+import { updateUI } from '../ui.js';
+import { PlanModeState } from '../state.js';
+import type { PlanData, TaskRecord } from '../types.js';
+
+function makePlan(): PlanData {
+  const done: TaskRecord = {
+    _type: 'task',
+    id: 't-001',
+    description: 'Done work',
+    details: '',
+    status: 'done',
+    created_at: '2026-01-01T00:00:00Z',
+    updated_at: '2026-01-01T00:00:00Z',
+  };
+  const pending: TaskRecord = { ...done, id: 't-002', status: 'pending' };
+  return { title: 'T', planName: 'test', handoff: '# H', tasks: [done, pending] };
+}
+
+function makeCtx() {
+  const statusCalls: Array<[string, unknown]> = [];
+  const widgetCalls: Array<[string, unknown]> = [];
+  const ctx = {
+    ui: {
+      theme: { fg: (_role: string, text: string) => text },
+      setStatus: (id: string, value: unknown) => statusCalls.push([id, value]),
+      setWidget: (id: string, value: unknown) => widgetCalls.push([id, value]),
+    },
+  } as unknown as Parameters<typeof updateUI>[1];
+  return { ctx, statusCalls, widgetCalls };
+}
+
+describe('updateUI', () => {
+  test('never renders plan progress from memory — status is always cleared', () => {
+    const cases: Array<Partial<PlanModeState>> = [
+      { executing: true, plan: makePlan() },
+      { executing: false, planEnabled: false, plan: makePlan() },
+      { planEnabled: true },
+      {},
+    ];
+
+    for (const overrides of cases) {
+      const state = Object.assign(new PlanModeState(), overrides);
+      const { ctx, statusCalls, widgetCalls } = makeCtx();
+
+      updateUI(state, ctx);
+
+      expect(statusCalls).toEqual([['plan-mode', undefined]]);
+      expect(widgetCalls).toEqual([['plan-todos', undefined]]);
+    }
+  });
+});

package/extensions/plan-mode/target.ts

@@ -0,0 +1,107 @@
+/**
+ * Resolve an optional external `target` working directory for the write tools
+ * (submit_plan / revise_plan / add_task).
+ *
+ * The use-case: while working in repo A you discover a gap in package B (which
+ * you author) and want to file the plan straight into B's `.plans/` registry so
+ * it becomes a first-class local plan there. The `target` points at B's repo
+ * root (NOT its `.plans/` dir).
+ *
+ * Returns `undefined` when no target is given (caller uses the default,
+ * cwd-bound runtime). When a target is given it is expanded (`~`), resolved to
+ * an absolute path, and validated to be an existing directory — a missing or
+ * non-directory target throws so we never silently create `.plans/` inside a
+ * typo'd path.
+ */
+
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
+
+/** Expand a leading `~` / `~/` to the user's home directory. */
+function expandHome(input: string): string {
+  if (input === '~') return homedir();
+  if (input.startsWith('~/') || input.startsWith('~\\')) {
+    return resolve(homedir(), input.slice(2));
+  }
+  return input;
+}
+
+/**
+ * Resolve and validate an external target directory.
+ *
+ * @returns the absolute target dir, or `undefined` when `target` is empty/absent.
+ * @throws  when the resolved path does not exist or is not a directory.
+ */
+export async function resolvePlanTarget(target?: string): Promise<string | undefined> {
+  const trimmed = target?.trim();
+  if (!trimmed) return undefined;
+
+  const expanded = expandHome(trimmed);
+  const absolute = isAbsolute(expanded) ? expanded : resolve(process.cwd(), expanded);
+
+  let stats;
+  try {
+    stats = await stat(absolute);
+  } catch {
+    throw new Error(
+      `target directory does not exist: ${absolute}. Pass the repo root of the project whose .plans/ should receive this plan.`,
+    );
+  }
+  if (!stats.isDirectory()) {
+    throw new Error(`target is not a directory: ${absolute}. Pass the repo root, not a file.`);
+  }
+  return absolute;
+}
+
+/**
+ * Verify that an external-target write actually landed under `targetDir`.
+ *
+ * Routing to an external root relies on the loaded `@dreki-gg/taskman` honoring
+ * the `root` argument to `makePlanRuntime`. An OLD/stale taskman build silently
+ * ignores it and writes to the current working directory instead — reporting
+ * success while misfiling the plan. This converts that silent fallback into a
+ * loud, actionable failure.
+ *
+ * @throws when `<targetDir>/<planDir>/tasks.jsonl` was not created.
+ */
+export async function assertTargetReceived(targetDir: string, planDir: string): Promise<void> {
+  const marker = resolve(targetDir, planDir, 'tasks.jsonl');
+  let body: string;
+  try {
+    body = await readFile(marker, 'utf-8');
+  } catch {
+    throw staleTargetError(targetDir, marker);
+  }
+  if (body.length === 0) throw staleTargetError(targetDir, marker);
+}
+
+/**
+ * Like {@link assertTargetReceived} but for an append: confirm the freshly
+ * written `taskId` is actually present in the target plan's tasks file. Reads
+ * the file directly (not via a runtime) so a stale taskman cannot mask the
+ * fallback by reading from cwd.
+ */
+export async function assertTargetTaskAppended(
+  targetDir: string,
+  planDir: string,
+  taskId: string,
+): Promise<void> {
+  const marker = resolve(targetDir, planDir, 'tasks.jsonl');
+  let body = '';
+  try {
+    body = await readFile(marker, 'utf-8');
+  } catch {
+    throw staleTargetError(targetDir, marker);
+  }
+  if (!body.includes(`"${taskId}"`)) throw staleTargetError(targetDir, marker);
+}
+
+function staleTargetError(targetDir: string, marker: string): Error {
+  return new Error(
+    `External-target write did not land in ${targetDir} (${marker} missing or unchanged). ` +
+      'The loaded @dreki-gg/taskman build does not support external targets (root param) — ' +
+      'restart pi so it reloads the rebuilt taskman, then retry. ' +
+      "Note: the write may have gone to the current project's .plans/ instead — check and clean up there.",
+  );
+}

package/extensions/plan-mode/tools/add-task.ts

@@ -9,9 +9,17 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Text } from '@earendil-works/pi-tui';
 import { Type } from 'typebox';
+import { Effect as E } from 'effect';
 import type { TaskRecord } from '../types.js';
 import type { ResolvedPlan } from '../resolve-plan.js';
-import { nextTaskId } from '@dreki-gg/taskman';
+import {
+  nextTaskId,
+  makePlanRuntime,
+  resolvePlanByName,
+  appendDeferredTask,
+  loadPlanData,
+} from '@dreki-gg/taskman';
+import { resolvePlanTarget, assertTargetTaskAppended } from '../target.js';
 
 export interface AddTaskCallbacks {
   /** Resolve the active plan, attaching from disk when none is in memory. */
@@ -45,6 +53,12 @@ export function registerAddTaskTool(pi: ExtensionAPI, callbacks: AddTaskCallback
         description:
           'Plan name (or .plans/<name>) to target. Required — always scope the capture explicitly so it never lands in the wrong plan.',
       }),
+      target: Type.Optional(
+        Type.String({
+          description:
+            "Optional path to ANOTHER project's repo root whose .plans/ holds the plan. Use when capturing a follow-up against a plan you filed into a package you author. The plan must already exist there.",
+        }),
+      ),
     }),
 
     async execute(_toolCallId, params) {
@@ -58,6 +72,54 @@ export function registerAddTaskTool(pi: ExtensionAPI, callbacks: AddTaskCallback
           'add_task requires an explicit { plan } — pass the plan name so the follow-up is never misfiled onto an unrelated in-progress plan.',
         );
       }
+      // External target: resolve + append against that repo's .plans/ via a
+      // target-scoped runtime, bypassing the cwd-bound session callbacks.
+      const targetDir = await resolvePlanTarget(params.target);
+      if (targetDir) {
+        const io = makePlanRuntime(targetDir);
+        const resolved = await io(resolvePlanByName({ name: params.plan }));
+        if (!resolved.planName || !resolved.planDir) {
+          const hint = resolved.candidates.length
+            ? ` In-progress in ${targetDir}: ${resolved.candidates.join(', ')}.`
+            : ` No such plan in ${targetDir}/.plans/.`;
+          return {
+            content: [
+              { type: 'text' as const, text: `Skipped follow-up capture — plan not found.${hint}` },
+            ],
+            details: { skipped: true, candidates: resolved.candidates, target: targetDir },
+          };
+        }
+        const { task, deferred } = await io(
+          E.gen(function* () {
+            const added = yield* appendDeferredTask(resolved.planDir!, {
+              description: params.description,
+              reason: params.reason,
+              details: params.details,
+              depends_on: params.depends_on,
+            });
+            const reloaded = yield* loadPlanData(resolved.planDir!);
+            const count = reloaded?.tasks.filter((t) => t.status === 'deferred').length ?? 1;
+            return { task: added, deferred: count };
+          }),
+        );
+        // Fail loudly if an old/stale taskman silently appended to cwd instead.
+        await assertTargetTaskAppended(targetDir, resolved.planDir!, task.id);
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Captured follow-up ${task.id}: ${task.description} into ${targetDir}/${resolved.planDir} (deferred for review). ${deferred} follow-up(s) pending there. Continue with the planned tasks — do not implement this now.`,
+            },
+          ],
+          details: {
+            task_id: task.id,
+            description: task.description,
+            reason: params.reason,
+            target: targetDir,
+          },
+        };
+      }
+
       const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
       // No active plan is a tracking miss, not an error — return a soft,
       // non-terminating result so real work continues.

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

@@ -26,7 +26,10 @@ import {
 import { reconcileInitiativeForPlan, reconcileInitiativeStatus } from '@dreki-gg/taskman';
 import { isPlanFinalizable } from '@dreki-gg/taskman';
 import { toKebabCase } from '@dreki-gg/taskman';
+import { makePlanRuntime, resolvePlanByName, loadPlanData } from '@dreki-gg/taskman';
 import type { RunPlanIO } from '@dreki-gg/taskman';
+import { Effect as E } from 'effect';
+import { resolvePlanTarget, assertTargetReceived } from '../target.js';
 import type { PlanData, TaskMeta, TaskRecord } from '../types.js';
 
 export interface RevisePlanCallbacks {
@@ -53,6 +56,12 @@ export function registerRevisePlanTool(
     ],
     parameters: Type.Object({
       plan: Type.String({ description: 'Plan name (or .plans/<name>) to revise' }),
+      target: Type.Optional(
+        Type.String({
+          description:
+            "Optional path to ANOTHER project's repo root whose .plans/ holds the plan being revised. Use when the plan was filed into a package you author. Author-only: the revised plan is NOT pinned as this session's active plan.",
+        }),
+      ),
       title: Type.Optional(Type.String({ description: 'New human-readable plan title' })),
       handoff: Type.Optional(Type.String({ description: 'New markdown content for HANDOFF.md' })),
       tasks: Type.Optional(
@@ -92,7 +101,23 @@ export function registerRevisePlanTool(
           'revise_plan requires an explicit { plan } — pass the plan name so the rewrite is never applied to an unrelated in-progress plan.',
         );
       }
-      const { plan, candidates } = await callbacks.resolvePlan({ name: params.plan });
+      // Resolve an optional external target. When set, resolve + rewrite the
+      // plan against that repo's .plans/ via a target-scoped runtime, and do
+      // not touch this session's active-plan state (author-only).
+      const targetDir = await resolvePlanTarget(params.target);
+      const io: RunPlanIO = targetDir ? makePlanRuntime(targetDir) : runPlanIO;
+
+      const { plan, candidates } = targetDir
+        ? await io(
+            E.gen(function* () {
+              const resolved = yield* resolvePlanByName({ name: params.plan });
+              if (!resolved.planName || !resolved.planDir)
+                return { plan: undefined, candidates: resolved.candidates };
+              const loaded = yield* loadPlanData(resolved.planDir);
+              return { plan: loaded, candidates: [] as string[] };
+            }),
+          )
+        : await callbacks.resolvePlan({ name: params.plan });
       if (!plan) {
         const notFound: Record<string, unknown> = {
           error: 'not_found',
@@ -152,7 +177,7 @@ export function registerRevisePlanTool(
       const newInitiative = params.initiative ? toKebabCase(params.initiative) : undefined;
       const newDependsOn = params.depends_on_plans?.map(toKebabCase);
 
-      await runPlanIO(
+      await io(
         Effect.gen(function* () {
           yield* writeTasksJsonl(planDir, meta, tasks);
           yield* saveHandoff(planDir, newHandoff);
@@ -176,21 +201,27 @@ export function registerRevisePlanTool(
         }),
       );
 
-      callbacks.onPlanRevised(planDir, revised);
+      // Fail loudly if an old/stale taskman silently routed the write to cwd.
+      if (targetDir) await assertTargetReceived(targetDir, planDir);
+
+      // Author-only: only re-pin the active plan when revising in the current
+      // project (an external plan stays a local plan in its own repo).
+      if (!targetDir) callbacks.onPlanRevised(planDir, revised);
 
       const changed = [
         params.title ? 'title' : undefined,
         params.handoff ? 'handoff' : undefined,
         params.tasks ? 'tasks' : undefined,
       ].filter(Boolean);
+      const location = targetDir ? `${targetDir}/${planDir}` : planDir;
       return {
         content: [
           {
             type: 'text' as const,
-            text: `Plan "${newTitle}" revised (${changed.join(', ') || 'no changes'}) in ${planDir}.`,
+            text: `Plan "${newTitle}" revised (${changed.join(', ') || 'no changes'}) in ${location}.`,
           },
         ],
-        details: { planDir, plan: revised, changed },
+        details: { planDir, plan: revised, changed, target: targetDir },
       };
     },
 

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

@@ -12,8 +12,10 @@ import { upsertPlanEntry } from '@dreki-gg/taskman';
 import { readInitiativesManifest } from '@dreki-gg/taskman';
 import { reconcileInitiativeForPlan } from '@dreki-gg/taskman';
 import type { RunPlanIO } from '@dreki-gg/taskman';
+import { makePlanRuntime } from '@dreki-gg/taskman';
 import { toKebabCase } from '@dreki-gg/taskman';
 import { readHeadCommit } from '../git.js';
+import { resolvePlanTarget, assertTargetReceived } from '../target.js';
 import { detectPreconditionGaps, formatPreconditionRejection } from '../precondition-guard.js';
 import type { PlanData, TaskMeta, TaskRecord } from '../types.js';
 
@@ -76,6 +78,12 @@ export function registerSubmitPlanTool(
           }),
         ),
       ),
+      target: Type.Optional(
+        Type.String({
+          description:
+            "Optional path to ANOTHER project's repo root (not its .plans/ dir). When set, the plan is filed into that project's .plans/ registry instead of the current one — useful when you find a gap in a package you author and want the plan to live (and later execute) there. Author-only: the plan is NOT pinned as the active plan in this session.",
+        }),
+      ),
     }),
 
     async execute(_toolCallId, params) {
@@ -91,12 +99,19 @@ export function registerSubmitPlanTool(
         };
       }
 
+      // Resolve an optional external target. When set, the plan is filed into
+      // that repo's .plans/ registry via a target-scoped runtime, its base
+      // commit comes from that repo's HEAD, and we do NOT pin it as this
+      // session's active plan (author-only).
+      const targetDir = await resolvePlanTarget(params.target);
+      const io: RunPlanIO = targetDir ? makePlanRuntime(targetDir) : runPlanIO;
+
       const planName = toKebabCase(params.name);
       const planDir = `.plans/${planName}`;
       const initiative = params.initiative ? toKebabCase(params.initiative) : undefined;
       const dependsOnPlans = params.depends_on_plans?.map(toKebabCase);
       const now = new Date().toISOString();
-      const baseCommit = await readHeadCommit();
+      const baseCommit = await readHeadCommit(targetDir ?? process.cwd());
       const meta: TaskMeta = {
         _type: 'meta',
         title: params.title,
@@ -122,7 +137,7 @@ export function registerSubmitPlanTool(
         base_commit: baseCommit,
       };
 
-      const unknownInitiative = await runPlanIO(
+      const unknownInitiative = await io(
         Effect.gen(function* () {
           yield* writeTasksJsonl(planDir, meta, tasks);
           yield* saveHandoff(planDir, params.handoff);
@@ -140,21 +155,26 @@ export function registerSubmitPlanTool(
         }),
       );
 
-      callbacks.onPlanSubmitted(planDir, plan);
+      // Fail loudly if an old/stale taskman silently routed the write to cwd.
+      if (targetDir) await assertTargetReceived(targetDir, planDir);
+
+      // Author-only: only pin as the active plan when filed in the current
+      // project. A plan filed into an external repo is a first-class local plan
+      // *there* — pinning a non-local path here would corrupt session state.
+      if (!targetDir) callbacks.onPlanSubmitted(planDir, plan);
 
       const linkSuffix = initiative
         ? ` Linked to initiative "${initiative}"${
             unknownInitiative ? ' (no initiatives.jsonl entry yet — create it with submit_initiative)' : ''
           }.`
         : '';
+      const location = targetDir ? `${targetDir}/${planDir}` : planDir;
+      const text = targetDir
+        ? `Plan "${params.title}" filed into ${location} with ${tasks.length} tasks. It is a local plan in that project — execute it from that directory.${linkSuffix}`
+        : `Plan "${params.title}" saved with ${tasks.length} tasks in ${planDir}. Execute when ready.${linkSuffix}`;
       return {
-        content: [
-          {
-            type: 'text' as const,
-            text: `Plan "${params.title}" saved with ${tasks.length} tasks in ${planDir}. Execute when ready.${linkSuffix}`,
-          },
-        ],
-        details: { planDir, plan, initiative, depends_on_plans: dependsOnPlans },
+        content: [{ type: 'text' as const, text }],
+        details: { planDir, plan, initiative, depends_on_plans: dependsOnPlans, target: targetDir },
       };
     },
 

package/extensions/plan-mode/ui.ts

@@ -1,27 +1,18 @@
 /**
  * Plan mode UI — status bar and task widget rendering.
+ *
+ * The plan-mode status bar entry is intentionally always cleared: any progress
+ * indicator would be derived from in-memory `state.plan`, which drifts from the
+ * source of truth on disk. The agent reads real status from `tasks.jsonl` via
+ * the `plan_status` tool instead of trusting a memory-rendered badge.
  */
 
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
 import type { PlanModeState } from './state.js';
 
-export function updateUI(state: PlanModeState, ctx: ExtensionContext): void {
-  const { theme } = ctx.ui;
-
-  if (state.executing && state.plan) {
-    const done = state.plan.tasks.filter((task) => task.status === 'done').length;
-    const total = state.plan.tasks.length;
-    ctx.ui.setStatus('plan-mode', theme.fg('accent', `📋 exec ${done}/${total}`));
-  } else if (state.plan && !state.planEnabled) {
-    const done = state.plan.tasks.filter((task) => task.status === 'done').length;
-    const total = state.plan.tasks.length;
-    ctx.ui.setStatus('plan-mode', theme.fg('muted', `📋 ${done}/${total}`));
-  } else if (state.planEnabled) {
-    ctx.ui.setStatus('plan-mode', theme.fg('warning', '📝 plan'));
-  } else {
-    ctx.ui.setStatus('plan-mode', undefined);
-  }
-
-  // Task list lives in plan.jsonl — no widget needed.
+export function updateUI(_state: PlanModeState, ctx: ExtensionContext): void {
+  // Never render plan state from memory — clear both the status entry and the
+  // (unused) task widget.
+  ctx.ui.setStatus('plan-mode', undefined);
   ctx.ui.setWidget('plan-todos', undefined);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.28.0",
+  "version": "0.29.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"
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@dreki-gg/pi-command-sandbox": "^0.3.0",
-    "@dreki-gg/taskman": "^0.3.0",
+    "@dreki-gg/taskman": "^0.4.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {