@gavin-hu/my-pi-agent 0.12.0 → 0.13.0

package/extensions/plan/README.md

@@ -42,19 +42,28 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   `<repo-root>/.pi/plans/<YYYY-MM-DD-HHmm>-<slug>.md` (or `<agent-dir>/plans`
   outside a repository). The plans directory is self-ignoring, so plan files
   never show up as untracked files or in `rewind` snapshots.
+- **A discoverable index.** `/plan list` walks the plans directory and shows
+  every plan with its title, modified time, and step progress, newest first — in
+  the TUI as a docked list where `Enter` opens the plan's review, elsewhere as a
+  notice with each plan's path. The directory stays the index: no registry file,
+  one bounded read per plan.
 - **A shape that reads.** `write_plan` documents a canonical outline — a
   `# <Title>`, then `## Goal`, `## Context`, `## Approach`, `## Steps`,
   `## Risks`, and `## Verification` — and the model is guided to follow it. This
   is guidance only: any markdown is accepted, stored, and rendered as written.
 - **Trackable steps.** Steps are written as `- [ ]` checkboxes in the `## Steps`
-  section; approval seeds them into `todo`.
+  section; approval seeds them into `todo`, with the `## Verification` section as
+  the last item so the definition of done travels with the work. A plan with more
+  than 50 top-level steps is refused rather than truncated, so approval never
+  drops a step you reviewed.
 - **A navigable review.** The review screen splits the body at its headings,
   names the section you are in, and jumps between sections with `n`/`p`.
 - **What changed since the last review.** After a refinement, the review screen
   names how many sections changed, marks the current one in the scroll row, and
   the browser outline dots each changed section, so a re-review does not mean
-  re-reading the whole plan. The baseline is what the previous review in this
-  session showed; a resumed session starts without markers.
+  re-reading the whole plan. The baseline is one digest per heading section of
+  what the previous review showed, kept as a session entry, so a resumed session
+  or a `/tree` restore marks only what changed on its own branch.
 - **Kept current.** After approval, `set_plan_steps` flips the checkboxes of
   the steps you name in the file, so the plan mirrors what has actually been
   done. Pass the step's text as `expected` and an update whose step number moved
@@ -83,19 +92,28 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
   nested sub-bullets are treated as notes. The list is a merge, not a
   replacement: existing items keep their place and status, a step whose text is
   already there is skipped, and the tool's item cap defers the rest instead of
-  dropping anything. A plan without a `Steps` heading keeps the older rule — the
-  shallowest list in the document — so prose bullets in a plan that follows the
-  outline never become todos.
-- **Branch-aware.** The enabled flag is a custom session entry, so `/resume` and
-  `/tree` restore the right mode.
+  dropping anything. The plan's `## Verification` section follows as the **last**
+  todo item, summarized on one line (`Verify: …`) — it is not a plan step, so it is
+  ticked in the todo list rather than with `set_plan_steps`, and it never counts
+  against the 50-step cap. A plan without a `Steps` heading keeps the older rule —
+  the shallowest list in the document — so prose bullets in a plan that follows the
+  outline never become todos, and its verification bullets are already covered.
+- **Goal-aware.** While planning, the injected context restates an active
+  session goal as one bullet, so the plan is designed against the objective
+  instead of beside it. On approval, when the session has no goal at all, the user
+  is offered one confirm to record the plan's title as the goal — never replacing
+  an existing goal, and with no extra model call.
+- **Branch-aware.** The enabled flag and the review baseline are custom session
+  entries, so `/resume` and `/tree` restore the right mode and keep the
+  changed-section markers.
 
 ## Tools
 
 | Tool | Active | Purpose |
 |---|---|---|
 | `enter_plan_mode` | normal mode | Ask to enter plan mode; empty schema, confirmed with `ctx.ui.confirm`. |
-| `write_plan` | plan mode | Save the plan: `title` (file-name slug), `content` (full markdown in the documented outline), optional `plan_path` to overwrite a refinement. Returns the absolute path. |
-| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. |
+| `write_plan` | plan mode | Save the plan: `title` (file-name slug), `content` (full markdown in the documented outline), optional `plan_path` to overwrite a refinement. Returns the absolute path. A plan with more than 50 top-level steps in its `Steps` section is refused, with the cap and the fix named, and nothing is written. |
+| `exit_plan_mode` | plan mode | Read the plan file (`plan_path`) and present it for approval. Refuses a file whose step list is over the cap, before the review screen. |
 | `set_plan_steps` | normal mode | Keep an approved plan current: set the checkboxes of the given top-level steps (`updates`, each a 1-based `step` in the order `exit_plan_mode` listed, plus `status`, and optionally `expected` — the step's text, so a reordered plan is refused) to `pending` or `completed` in one write. Only the checkboxes change, and a reopened step drops its `[DONE:n]` marker. |
 
 ### Commands and flags
@@ -105,6 +123,7 @@ How the `write_plan` and `exit_plan_mode` calls and their results look in the tr
 | `enter_plan_mode` tool | the model, before a non-trivial task | `ctx.ui.confirm` |
 | `/plan` | the user | immediate |
 | `/plan <prompt>` | the user, with the task | immediate |
+| `/plan list` | the user, browsing the plans directory | immediate |
 | `/plan review [path]` | the user, reviewing a plan in the browser | immediate |
 | `Ctrl+Alt+P` | the user | immediate |
 | `--plan` | the user, at launch | immediate |
@@ -143,7 +162,7 @@ actions (`a approve & run` in `success`, `r refine` in `accent`).
 mounted and opens an inline editor beneath it (`Enter` submits, an empty buffer
 does nothing, `Esc` returns to the plan); `Esc` keeps planning and tells the
 model the plan was not approved. When the plan changed since the previous review
-in this session, a summary line under the title names how many sections changed
+on this branch, a summary line under the title names how many sections changed
 and the scroll row appends `· changed` to the current section. Scroll with `↑`/`↓` or `j`/`k`, `space`/`b` or
 `PgUp`/`PgDn`, `d`/`u`, `g`/`G`, and the mouse wheel. Press `n`/`p` to jump to
 the next or previous heading; the scroll row names the current section when the
@@ -321,7 +340,7 @@ file and returns them to the model.
   links, an active-section highlight, and a per-section comment count; the panel
   above it reports the `Steps` section's progress (`n/m`, the same list approval
   seeds) and total comments. A
-  section that changed since the previous review in this session carries a dot
+  section that changed since the previous review on this branch carries a dot
   (its `title` and accessible label say so); an unchanged plan shows none.
 - **Inline threads.** A comment renders directly under the block it anchors to,
   labelled and indented as a thread, so it reads in place and the plan keeps one
@@ -386,14 +405,15 @@ file and returns them to the model.
   Git Bash (`bash`), which must be installed for any shell command to run.
 - The read-only guarantee is a guard rail against accidental writes, not a
   security boundary (see [Security](#security)).
-- The plans directory is the only index; there is no registry and no persisted
-  plan metadata.
-- Changed markers need a prior review of the same plan in the same session. A
-  resumed or new session has no baseline, so it shows no markers rather than
-  marking the whole plan as changed.
-- Approval tracks at most 50 steps, and a step longer than 200 characters is
-  shortened in the todo list and the approval listing. `write_plan` reports both
-  cases when they apply; the plan file itself always keeps the full text.
+- The plans directory is the only index. `/plan list` walks it on every open and
+  keeps no registry, so it sees an external edit or a hand-copied plan
+  immediately; it lists a file over the 256 KiB plan limit without reading it,
+  and does not index the agent directory's plans while a worktree is active.
+- Approval tracks at most 50 steps: `write_plan` refuses a larger plan, and
+  `exit_plan_mode` refuses to present one, so no reviewed step is silently
+  dropped. A step longer than 200 characters is shortened in the todo list and
+  the approval listing — a display rule only, because the plan file always keeps
+  the full text.
 - Browser review needs a local browser: the server is loopback-only, so a remote
   turn cannot drive it.
 - A browser that never connects leaves the review waiting until the user
@@ -415,9 +435,9 @@ file and returns them to the model.
 | Integration point | How |
 |---|---|
 | Tools | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps` registered with `executionMode: "sequential"`. `enter_plan_mode` is active normally with `readOnlyHint: true`; `write_plan` (`readOnlyHint: false`) and `exit_plan_mode` (`readOnlyHint: true`) are `defaultActive: false`. `set_plan_steps` is active normally (`readOnlyHint: false`, `idempotentHint: true`); the read-only policy default-denies it in plan mode. Each returns typed `details` (`EnterPlanModeDetails`, `WritePlanDetails`, `ExitPlanModeDetails`, `SetPlanStepsDetails`), and `ExitPlanModeDetails` carries the review's `annotations` when a browser approval or save supplied comments; no `outputSchema`/`structuredContent`. |
-| Commands and flags | `/plan` (toggle, or enter and send a task), `/plan review [path]` (browser review), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
-| State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })` and rebuilt from `ctx.sessionManager.getBranch()`; the last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. The content each review showed is kept in runtime memory (keyed by resolved path) for the changed markers. |
-| Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context; `context` keeps only the newest plan context while enabled and drops stale ones otherwise. |
+| Commands and flags | `/plan` (toggle, or enter and send a task), `/plan list` (plans index), `/plan review [path]` (browser review), `--plan` launch flag, `Ctrl+Alt+P` shortcut. |
+| State | Enabled flag and the tools it hid persisted with `pi.appendEntry("plan-mode", { enabled, removed })`, and each review's baseline persisted with `pi.appendEntry("plan-baseline", { path, sections })` as one digest per heading section; both rebuilt from `ctx.sessionManager.getBranch()`, so `/resume` and `/tree` restore the mode and the changed markers of the branch they land on. Plan never writes a goal itself: an approval offer records one through `ctx.executeTool("goal", { objective })`. A review that shows the same content appends nothing. The last plan path lives in runtime memory for the footer chip, and a bare `/plan review` falls back to the newest plan file in the directory. |
+| Hooks | `tool_call` blocks non-read-only calls and forces `subagent` read-only; `before_agent_start` injects the hidden `[PLAN MODE ACTIVE]` context, with an active session goal read from the branch through `lib/goal-state.ts`; `context` keeps only the newest plan context while enabled and drops stale ones otherwise. |
 | Lifecycle | `session_start`/`session_tree` restore state; `session_shutdown` clears the footer status and closes any browser review server. |
 
 ## Design notes
@@ -456,12 +476,21 @@ file and returns them to the model.
   channel; no import from that extension) and the steps are merged into them.
   A rejected seed reports the nested tool's own reason in the approval message
   instead of failing silently.
+- **A cap is enforced where it can still be fixed.** Both refusal points —
+  `write_plan` and `exit_plan_mode` — sit before the write and before the review,
+  because those are the moments the model can still regroup the steps. A note on
+  a successful write would arrive after the file existed and the review had
+  already listed every step, which is exactly when the overflow becomes lost
+  work.
 - **Changed markers compare what was shown, not revisions on disk.** A review
-  result is only meaningful next to the text the reviewer already read, so the
-  runtime keeps the content each review presented (keyed by resolved path) and
-  `changedSections` diffs section title and text against it. Stored feedback is
+  result is only meaningful next to the text the reviewer already read, so every
+  review marks the sections it presented (keyed by resolved path) and
+  `plan-text.ts` compares the next plan against those digests. Stored feedback is
   stripped from both sides, so a review comment never reads as an edit, and the
-  same helper feeds the terminal summary and the browser outline.
+  same helper feeds the terminal summary and the browser outline. The digests are
+  a session entry rather than the previous text, so the markers survive a resume
+  without copying the plan file into the branch, and the reader and the writer
+  share one normalization so a tab cannot read as a change.
 - **The outline guides, it does not enforce.** `write_plan` documents the
   canonical shape in its description and stores whatever markdown it is given;
   no section is required and nothing is rewritten. That keeps the model free to
@@ -514,12 +543,14 @@ file and returns them to the model.
 | `git-bash.ts` | `checkReadOnlyGit`: the pure allowlist that restricts `bash` to read-only git commands. |
 | `plans.ts` | Plan-file store: slug/stamp naming, directory resolution, containment, atomic `write`/`setSteps`/`saveFeedback`, and `read`/`latest`. |
 | `todos.ts` | Approval-time todo merge (pure): the last list replayed from the branch, and the merge of the plan's steps into it with the cap respected. |
-| `steps.ts` | Plan-document structure (pure): the outline, step extraction and the `Steps`-section scope, heading sections, the section diff, and the checkbox edit. |
-| `runtime.ts` | Enabled state, tool gating, persistence, control-tool identity, footer status, the review baseline. |
+| `steps.ts` | Plan-document structure (pure): the outline, step extraction and the `Steps`-section scope, heading sections, and the checkbox edit. |
+| `plan-text.ts` | The plan text a review shows and compares: `sanitizePlanText`, the one normalization both sides use, the per-section `sectionDigests`, and `changedSections`. |
+| `runtime.ts` | Enabled state, tool gating, persistence (mode and review baseline), control-tool identity, footer status. |
 | `tools.ts` | `enter_plan_mode`, `write_plan`, `exit_plan_mode`, and `set_plan_steps`: schemas, results, transcripts, and the approval-time todo seed. |
 | `review.ts` | The review gate: one decision from the TUI screen, a dialog, or the browser, the shared browser lifecycle, and the "mark what was shown" baseline rule. |
 | `commands.ts` | `/plan` (enter, optional task) and the `/plan review [path]` browser subcommand. |
 | `tui.ts` | `PlanViewComponent` (sectioned Markdown body, changed-section summary and marker, section jump, scroll gauge, approve/refine/browser/keep). |
+| `plan-index.ts` | `/plan list`: the notice text and the docked index screen (title, step progress, age, focused path; Enter reviews). |
 | `blocks.ts` | Source-line block model (fence-aware headings, paragraphs, list items, code, quotes, tables, rules, blanks). |
 | `feedback.ts` | Browser-comment codec: `stripFeedback`, `parseFeedback`, `formatFeedback`, `feedbackSummary`, and payload validation. |
 | `web.ts` | `createPlanWebReview`: the loopback server, the section outline (with changed-section flags) and code highlighting, and the save/approve/cancel/abort session. |

package/extensions/plan/commands.ts

@@ -2,22 +2,26 @@
  * Slash command for the plan-mode extension.
  *
  * `/plan` toggles plan mode, or enters it and sends an optional task;
- * `Ctrl+Alt+P` toggles too. `/plan review [path]` is the one reserved
- * subcommand: it opens the plan in the browser, and when the user saves their
- * comments sends them to the model as a refinement request.
+ * `Ctrl+Alt+P` toggles too. Two subcommands are reserved: `/plan review [path]`
+ * opens a plan in the browser (and sends saved comments to the model as a
+ * refinement), and `/plan list` shows the plans directory, newest first, with
+ * Enter opening a review.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isRemoteTurn } from "../../lib/interaction.ts";
 import { feedbackSummary } from "./feedback.ts";
+import { PlanIndexComponent, formatPlanIndex } from "./plan-index.ts";
 import { READ_ONLY_SUMMARY } from "./policy.ts";
 import { runBrowserReview } from "./review.ts";
 import type { PlanRuntime } from "./runtime.ts";
+import type { PlanSummary } from "./plans.ts";
 import { createPlanWebReview, type PlanWebReview } from "./web.ts";
 
 const ENABLED_NOTICE = `Plan mode enabled — ${READ_ONLY_SUMMARY}.`;
 const DISABLED_NOTICE = "Plan mode disabled — full access restored.";
 const REVIEW_PREFIX = "review";
+const LIST_PREFIX = "list";
 
 /** Notice text for the current mode; shared by `/plan` and the `Ctrl+Alt+P` shortcut. */
 export function planModeNotice(enabled: boolean): string {
@@ -30,6 +34,14 @@ function reviewTarget(args: string): string | undefined {
 	return target === "" ? undefined : target;
 }
 
+/**
+ * Whether a command line is the reserved `list` subcommand. Exact match only, so
+ * `list the untracked files` stays a task instead of silently listing plans.
+ */
+function isListSubcommand(prompt: string): boolean {
+	return prompt.toLowerCase() === LIST_PREFIX;
+}
+
 /**
  * Whether a command line is the reserved `review` subcommand. Bare `review`
  * always is; a path after it is, but `review the auth flow` stays a task, so a
@@ -68,10 +80,10 @@ async function reviewInBrowser(
 		return;
 	}
 
-	const previous = runtime.reviewed(file.path);
+	const baseline = runtime.reviewed(file.path);
 	const result = await runBrowserReview(web, ctx.cwd, file, {
 		canApprove: false,
-		previous,
+		baseline,
 		// Mark only once the page is actually open: a failed start must not consume
 		// the baseline for a plan nobody saw.
 		onOpened: (session) => {
@@ -100,6 +112,47 @@ async function reviewInBrowser(
 	else await pi.sendUserMessage(message, { deliverAs: "followUp" });
 }
 
+/**
+ * `/plan list`: show the plans directory, newest first. The TUI gets a docked
+ * list whose Enter opens the focused plan's review; every other mode gets the
+ * same facts as a notice, with each plan's path.
+ */
+async function openPlanIndex(
+	pi: ExtensionAPI,
+	runtime: PlanRuntime,
+	web: PlanWebReview,
+	ctx: ExtensionContext,
+): Promise<void> {
+	const dir = await runtime.plans.dirFor(ctx.cwd);
+	const summarise = async (): Promise<Awaited<ReturnType<typeof runtime.plans.index>>> => runtime.plans.index(ctx.cwd);
+	const summaries = await summarise();
+
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(formatPlanIndex(summaries, dir), "info");
+		return;
+	}
+
+	// The review runs after the screen closes, so the input focus is free again.
+	let selected: (PlanSummary | undefined) | undefined;
+	await ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+		const component = new PlanIndexComponent({
+			summaries,
+			dir,
+			theme,
+			onSelect: (summary) => {
+				selected = summary;
+				done();
+			},
+			onClose: () => done(),
+			reload: summarise,
+			requestRender: () => tui.requestRender(),
+			viewportRows: () => tui.terminal?.rows,
+		});
+		return component;
+	});
+	if (selected) await reviewInBrowser(pi, runtime, web, selected.path, ctx);
+}
+
 export function registerCommands(
 	pi: ExtensionAPI,
 	runtime: PlanRuntime,
@@ -107,16 +160,22 @@ export function registerCommands(
 ): void {
 	pi.registerCommand("plan", {
 		description:
-			"Toggle plan mode (read-only exploration), enter it with an optional task, or review a plan in the browser",
+			"Toggle plan mode (read-only exploration), enter it with an optional task, list saved plans, or review one in the browser",
 		getArgumentCompletions: (prefix) => {
 			const text = prefix.trimStart();
 			if (text.includes(" ")) return null;
-			return REVIEW_PREFIX.startsWith(text) ? [{ value: REVIEW_PREFIX, label: REVIEW_PREFIX }] : null;
+			const subcommands = [LIST_PREFIX, REVIEW_PREFIX].filter((name) => name.startsWith(text));
+			return subcommands.length > 0 ? subcommands.map((value) => ({ value, label: value })) : null;
 		},
 		handler: async (args, ctx) => {
 			const prompt = args.trim();
 
-			// `/plan review [path]` is a reserved subcommand; everything else is a task.
+			// `/plan list` and `/plan review [path]` are reserved subcommands;
+			// everything else is a task.
+			if (isListSubcommand(prompt)) {
+				await openPlanIndex(pi, runtime, web, ctx);
+				return;
+			}
 			if (isReviewSubcommand(prompt)) {
 				await reviewInBrowser(pi, runtime, web, reviewTarget(prompt), ctx);
 				return;

package/extensions/plan/index.ts

@@ -21,7 +21,10 @@ import { Key } from "@earendil-works/pi-tui";
 import { fileURLToPath } from "node:url";
 import { hasPathInput } from "./path-guard.ts";
 import { isExtensionEnabled } from "../../lib/env.ts";
+import { sanitizeLine } from "../../lib/format.ts";
+import { lastGoal, type PublishedGoal } from "../../lib/goal-state.ts";
 import { ASK_USER_QUESTION_TOOL, SUBAGENT_READ_ONLY_PARAM, SUBAGENT_TOOL } from "../../lib/tool-names.ts";
+import { clip } from "../../lib/tui/columns.ts";
 import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { planModeNotice, registerCommands } from "./commands.ts";
 import { checkReadOnlyGit } from "./git-bash.ts";
@@ -39,15 +42,34 @@ import { createPlanWebReview } from "./web.ts";
 /** Marker embedded in the injected prompt and used to filter stale context. */
 export const PLAN_MODE_MARKER = "[PLAN MODE ACTIVE]";
 
-/** Injected each turn while planning: the facts and the next action, not the tool contracts. */
-export const PLAN_MODE_CONTEXT = `${PLAN_MODE_MARKER}
-You are in plan mode: read-only exploration for safe code analysis.
+/**
+ * Longest goal text restated here. `goal` injects the full objective every turn
+ * regardless of plan mode, so this line is a short pointer; the clip is what keeps
+ * the whole context inside the prompt-budget ceiling.
+ */
+const GOAL_CONTEXT_CHARS = 64;
 
-- Do not modify anything except the plan file: while planning, ${READ_ONLY_SUMMARY}.
-- bash is git-only: read-only commands (git status, git diff, git log) may be chained with && or ;, but pipes, substitution, and redirection are blocked and powershell is unavailable. The cwd is already the project root, so do not prefix commands with cd; use read, grep, find, and ls for files.
-- Investigate and design a concrete plan, then save it with write_plan and call exit_plan_mode with the returned plan_path for approval.
-- Delegate broad exploration with subagent; while planning it is forced read-only.
-- To choose between approaches, ask with ${ASK_USER_QUESTION_TOOL} before finalizing.`;
+/**
+ * Injected each turn while planning: the facts and the next action, not the tool
+ * contracts. An active session goal becomes one extra bullet, so a plan is
+ * designed against the objective instead of beside it.
+ */
+export function planModeContext(goal?: PublishedGoal | null): string {
+	const lines = [
+		PLAN_MODE_MARKER,
+		"You are in plan mode: read-only exploration for safe code analysis.",
+		"",
+		`- Do not modify anything except the plan file: while planning, ${READ_ONLY_SUMMARY}.`,
+		"- bash is git-only: read-only commands (git status, git diff, git log) may be chained with && or ;, but pipes, substitution, and redirection are blocked and powershell is unavailable. The cwd is already the project root, so do not prefix commands with cd; use read, grep, find, and ls for files.",
+		"- Investigate and design a concrete plan, then save it with write_plan and call exit_plan_mode with the returned plan_path for approval.",
+		"- Delegate broad exploration with subagent; while planning it is forced read-only.",
+		`- To choose between approaches, ask with ${ASK_USER_QUESTION_TOOL} before finalizing.`,
+	];
+	if (goal?.status === "active") {
+		lines.push(`- Current session goal: ${clip(sanitizeLine(goal.objective), GOAL_CONTEXT_CHARS)}`);
+	}
+	return lines.join("\n");
+}
 
 /** This extension entry file, as Pi records it for our tool registrations. */
 function extensionEntryPath(): string | undefined {
@@ -158,10 +180,12 @@ export default function planMode(pi: ExtensionAPI): void {
 		return reason ? { block: true, reason } : undefined;
 	});
 
-	// Tell the model it is planning.
-	pi.on("before_agent_start", () => {
+	// Tell the model it is planning, and restate an active goal so the plan is
+	// designed against it. Reads the branch, so no extra model call is involved.
+	pi.on("before_agent_start", (_event, ctx) => {
 		if (!runtime.isEnabled()) return undefined;
-		return { message: { customType: "plan-mode-context", content: PLAN_MODE_CONTEXT, display: false } };
+		const goal = lastGoal(ctx.sessionManager.getBranch());
+		return { message: { customType: "plan-mode-context", content: planModeContext(goal), display: false } };
 	});
 
 	// Keep stale plan-mode context out of later, non-plan turns (for example after /resume).

package/extensions/plan/plan-index.ts

@@ -0,0 +1,234 @@
+/**
+ * The `/plan list` surface: the plan index as a notice, and as a docked list
+ * screen.
+ *
+ * A plan is a file, and the plans directory is its only index, so this module
+ * presents what `PlanStore.index` walked: the title, the modified time, and how
+ * far its steps got, newest first. Enter on the screen hands the focused plan
+ * back to the caller, which reuses the browser review; every other mode gets the
+ * same facts as one line per plan, with the path to reopen.
+ *
+ * Derived state only: the summaries are passed in, a reload replaces them, and a
+ * render reads them — like the `/memory` picker.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Key, matchesKey, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import { sanitizeLine, shortenPath } from "../../lib/format.ts";
+import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../lib/tui/cursor.ts";
+import { dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { emptyState, listRow } from "../../lib/tui/rows.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import type { PlanSummary } from "./plans.ts";
+
+/** Rows the screen shows when the terminal height is unknown. */
+const DEFAULT_ROWS = 14;
+/** Fixed rows around the list: header, summary, blank, range, detail, hint, blank. */
+const CHROME = 7;
+/** Longest title a row draws before the trailing meta wins the column. */
+const TITLE_WIDTH = 56;
+
+/**
+ * How long ago a plan was modified: `today`, `3d ago`, `2mo ago`, `1y ago`.
+ * Coarse on purpose — a list row compares plans, it does not time them.
+ */
+export function relativeAge(modifiedMs: number, nowMs: number): string {
+	const days = Math.floor(Math.max(0, nowMs - modifiedMs) / 86_400_000);
+	if (days < 1) return "today";
+	if (days < 30) return `${days}d ago`;
+	const months = Math.floor(days / 30);
+	if (months < 12) return `${months}mo ago`;
+	return `${Math.floor(days / 365)}y ago`;
+}
+
+/** `3/7 steps`, `2/2 steps`, or `steps unknown` for a file the store would not have written. */
+function stepsText(summary: PlanSummary): string {
+	if (!summary.steps) return "steps unknown";
+	return `${summary.steps.done}/${summary.steps.total} steps`;
+}
+
+/** Local `YYYY-MM-DD HH:mm`, matching the stamp the file name carries. */
+function localTime(ms: number): string {
+	const date = new Date(ms);
+	const pad = (value: number): string => String(value).padStart(2, "0");
+	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+/**
+ * The non-TUI listing: one line per plan with its title, step progress, modified
+ * time, and path, newest first. The directory is named once in the header.
+ */
+export function formatPlanIndex(summaries: readonly PlanSummary[], dir: string): string {
+	const where = sanitizeLine(shortenPath(dir));
+	if (summaries.length === 0) {
+		return `No plans in ${where} yet; write_plan saves one there.`;
+	}
+	const lines = summaries.map(
+		(summary) =>
+			`  ${sanitizeLine(summary.title)} — ${stepsText(summary)} — ${localTime(summary.modified)} — ${sanitizeLine(summary.relativePath)}`,
+	);
+	return [`Plans (${summaries.length}) — ${where}`, ...lines].join("\n");
+}
+
+export interface PlanIndexOptions {
+	summaries: readonly PlanSummary[];
+	/** Directory the plans live in, for the header. */
+	dir: string;
+	theme: Theme;
+	/** Enter on the focused plan; the caller opens its review after the screen closes. */
+	onSelect: (summary: PlanSummary) => void;
+	onClose: () => void;
+	/** `r`: re-read the directory. Resolves with the new rows. */
+	reload: () => Promise<readonly PlanSummary[]>;
+	requestRender: () => void;
+	viewportRows?: ViewportRowsSource;
+	/** Clock for the relative ages; defaults to the wall clock. */
+	now?: () => number;
+}
+
+/** Docked `/plan list` screen: the plans directory, newest first. */
+export class PlanIndexComponent implements Component {
+	private readonly cursor: ListCursor;
+	private summaries: readonly PlanSummary[];
+	private notice: string | undefined;
+	private componentFocused = false;
+
+	constructor(private readonly options: PlanIndexOptions) {
+		this.summaries = options.summaries;
+		this.cursor = new ListCursor(() => options.requestRender());
+		// A screen can take its first key before it is drawn; keep the cursor valid.
+		this.cursor.sync(this.summaries.length);
+	}
+
+	/** Replace the rows after a reload, keeping the focused plan if it is still there. */
+	private setSummaries(next: readonly PlanSummary[]): void {
+		this.summaries = next;
+		this.cursor.sync(next.length);
+		this.cursor.selected = Math.min(this.cursor.selected, Math.max(0, next.length - 1));
+		this.requestRender();
+	}
+
+	private requestRender(): void {
+		this.options.requestRender();
+	}
+
+	private reload(): void {
+		void this.options
+			.reload()
+			.then((next) => {
+				this.setSummaries(next);
+				this.notice = next.length === 0 ? "No plans yet." : undefined;
+			})
+			.catch((error: unknown) => {
+				this.notice = `Could not read the plans directory: ${error instanceof Error ? error.message : String(error)}`;
+				this.requestRender();
+			});
+	}
+
+	handleInput(data: string): void {
+		if (isCloseKey(data) || data === "q") {
+			this.options.onClose();
+			return;
+		}
+		if (this.notice !== undefined) this.notice = undefined;
+
+		if (navigateList(data, this.cursor, this.summaries.length)) {
+			this.requestRender();
+			return;
+		}
+		// The hint advertises `g`/`G`, so bind them to the ends.
+		if (data === "g" || data === "G") {
+			this.cursor.set(data === "g" ? 0 : this.summaries.length - 1, this.summaries.length);
+			this.requestRender();
+			return;
+		}
+		if (data === "r") {
+			this.reload();
+			return;
+		}
+		if (matchesKey(data, Key.enter)) {
+			const focused = this.summaries[this.cursor.selected];
+			if (focused) this.options.onSelect(focused);
+		}
+	}
+
+	/** Wheel scrolling moves the selection, matching the other list screens. */
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		return scrollList(event, this.cursor, this.summaries.length);
+	}
+
+	/** Rows are built per render from the current theme and summaries; nothing is memoized. */
+	invalidate(): void {}
+
+	get focused(): boolean {
+		return this.componentFocused;
+	}
+
+	set focused(value: boolean) {
+		this.componentFocused = value;
+	}
+
+	private row(summary: PlanSummary, selected: boolean, width: number): string {
+		const now = (this.options.now ?? Date.now)();
+		const trailing = `${stepsText(summary)} · ${relativeAge(summary.modified, now)}`;
+		return listRow(this.options.theme, width, {
+			selected,
+			label: clip(sanitizeLine(summary.title), TITLE_WIDTH),
+			labelRole: selected ? "accent" : "label",
+			trailing,
+			trailingRole: "meta",
+		});
+	}
+
+	private summaryLine(width: number): string {
+		const { theme } = this.options;
+		const count = this.summaries.length;
+		const text = `${paint(theme, "accent", "Plans")} ${paint(theme, "meta", `· ${count} ${count === 1 ? "plan" : "plans"}`)}`;
+		const where = paint(theme, "faint", ` · ${sanitizeLine(shortenPath(this.options.dir))}`);
+		return clip(`  ${text}${where}`, width);
+	}
+
+	private detailLines(width: number): string[] {
+		const focused = this.summaries[this.cursor.selected];
+		if (!focused) return [];
+		const { theme } = this.options;
+		const path = paint(theme, "meta", sanitizeLine(focused.relativePath));
+		const time = paint(theme, "faint", ` · modified ${localTime(focused.modified)}`);
+		return [clip(`  ${path}${time}`, width)];
+	}
+
+	render(width: number): string[] {
+		const { theme } = this.options;
+		const w = Math.max(1, width);
+		this.cursor.visible = fitRows(this.options.viewportRows, this.summaries.length, CHROME, DEFAULT_ROWS);
+		this.cursor.sync(this.summaries.length);
+
+		const body: string[] = [];
+		if (this.summaries.length === 0) {
+			body.push(...emptyState(theme, w, { label: "No plans yet. write_plan saves one under .pi/plans." }));
+		} else {
+			const { start, end } = this.cursor.window(this.summaries.length);
+			for (let index = start; index < end; index++) {
+				body.push(this.row(this.summaries[index], index === this.cursor.selected, w));
+			}
+		}
+
+		const hint =
+			this.notice !== undefined
+				? clip(`  ${paint(theme, "meta", this.notice)}`, w)
+				: screenHint(theme, w, ["Esc close", { text: "Enter review", color: "accent" }, "r reload", "↑/↓", "g/G"]);
+
+		return dockListFrame({
+			header: titleRule(theme, w, "Plan index"),
+			summary: this.summaryLine(w),
+			body,
+			range: this.cursor.clipped(this.summaries.length)
+				? formatRange(theme, w, { ...this.cursor.window(this.summaries.length), total: this.summaries.length })
+				: undefined,
+			detail: this.detailLines(w),
+			hint,
+		});
+	}
+}