@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/extensions/plan/steps.ts

@@ -10,13 +10,16 @@
  * the digest is computed over.
  *
  * Only top-level list items become steps: nested sub-bullets are notes, and the
- * shallowest list level is treated as the plan. When the plan has a `Steps`
- * section (the canonical outline's heading), only that section's list items are
- * steps, so prose bullets elsewhere never seed the todo list or consume the
- * step cap. List items inside fenced code blocks are ignored. A `- [ ]` / `- [x]`
+ * shallowest list level is treated as the plan. An indented, marker-less line
+ * continues the item above it, so a wrapped step keeps its full text. When the
+ * plan has a `Steps` section (the canonical outline's heading), only that
+ * section's list items are steps, so prose bullets elsewhere never seed the todo
+ * list or consume the step cap. List items inside fenced code blocks are ignored. A `- [ ]` / `- [x]`
  * checkbox or a `[DONE:n]` marker sets the status.
  */
 
+import { extractSections, FENCE, HEADING, normalizeHeadingText } from "./sections.ts";
+
 /** Most steps seeded from one plan. */
 export const MAX_STEPS = 50;
 /** Longest seeded step text; longer lines are elided. */
@@ -82,26 +85,17 @@ export interface PlanStep {
 	status: "pending" | "completed";
 }
 
-/** A heading-delimited chunk of the plan, for the review screen's navigation. */
-export interface PlanSection {
-	/** Plain heading text, or `""` for the content before the first heading. */
-	title: string;
-	/** The section's markdown, including its heading line. */
-	text: string;
-	/** 0-based source line of the section's heading (0 for the preamble). */
-	line: number;
-	/** Heading level, or 0 for the preamble before the first heading. */
-	level: number;
-}
-
 /** A top-level list item located in the source. */
 interface PlanListItem {
-	/** Zero-based source line index. */
+	/** Zero-based source line index of the item's first line. */
 	line: number;
 	indent: number;
 	/** The list marker with its trailing whitespace, e.g. `1. ` or `- `. */
 	lead: string;
-	/** Item text after the marker, right-trimmed (an optional checkbox included). */
+	/**
+	 * Item text after the marker on its first line; indented continuation lines
+	 * are folded into {@link step}, so a checkbox edit rewrites only this line.
+	 */
 	raw: string;
 	step: PlanStep;
 }
@@ -109,39 +103,10 @@ interface PlanListItem {
 /** A top-level numbered or bulleted list item, capturing its parts. */
 const LIST_ITEM = /^([ \t]*)((?:\d+[.)]|[-*+])\s+)(.*\S)\s*$/;
 const CHECKBOX = /^\[([ xX])\]\s*(.*)$/;
-/**
- * A markdown heading outside a fence, capturing its level and text: up to three
- * leading spaces, a space after the hashes, and a closing hash run only when a
- * space separates it. Shared with `blocks.ts`, so the section split and the
- * browser outline read a heading line the same way, and `## C#` keeps its title.
- */
-export const HEADING = /^ {0,3}(#{1,6})\s+(.*?)(?:\s+#+)?\s*$/;
-/**
- * A markdown code-fence opener or closer (backticks or tildes). Shared with
- * `blocks.ts`: a tab-indented fence is prose for both parsers, never code for
- * one and prose for the other.
- */
-export const FENCE = /^ {0,3}(`{3,}|~{3,})/;
 const DONE_MARKER = /\[DONE:\d+\]/gi;
 
-/**
- * A heading or step label as the review surfaces compare it: inline emphasis and
- * code removed, whitespace collapsed. Exported so `blocks.ts` labels an outline
- * entry the same way `extractPlanSections` labels its section, which is what
- * lets the browser mark a changed section.
- */
-export function normalizeHeadingText(text: string): string {
-	return text
-		.replace(/\*\*([^*]+)\*\*/g, "$1")
-		.replace(/\*([^*]+)\*/g, "$1")
-		.replace(/(?<![A-Za-z0-9_])_([^_]+)_(?![A-Za-z0-9_])/g, "$1")
-		.replace(/`([^`]+)`/g, "$1")
-		.replace(/\s+/g, " ")
-		.trim();
-}
-
-/** Strip inline markdown emphasis and code, then collapse to one clean line. */
-function plainText(text: string): string {
+/** A label with its inline markers and any done marker removed. */
+function cleanLabel(text: string): string {
 	return normalizeHeadingText(text.replace(DONE_MARKER, ""));
 }
 
@@ -157,7 +122,12 @@ function parseStep(raw: string): PlanStep {
 	}
 	if (/\[DONE:\d+\]/i.test(text)) done = true;
 
-	return { content: plainText(text), status: done ? "completed" : "pending" };
+	return { content: cleanLabel(text), status: done ? "completed" : "pending" };
+}
+
+/** Leading whitespace width of a line, for continuation indent checks. */
+function indentOf(line: string): number {
+	return line.length - line.trimStart().length;
 }
 
 /** Every top-level list item, in order, before de-duplication and capping. */
@@ -165,22 +135,57 @@ function scanListItems(plan: string): PlanListItem[] {
 	const items: PlanListItem[] = [];
 	// Fences hide example lists (`- name: foo` in a YAML block) from extraction.
 	let fence: string | undefined;
+	// The item still collecting indented continuation lines, and those lines.
+	let current: { item: PlanListItem; continuation: string[] } | undefined;
+
+	/** Fold the collected continuation into the item, then close it. */
+	const finish = (): void => {
+		if (current === undefined) return;
+		if (current.continuation.length > 0) {
+			current.item.step = parseStep(`${current.item.raw} ${current.continuation.join(" ")}`);
+		}
+		current = undefined;
+	};
 
 	plan.split("\n").forEach((line, index) => {
 		const fenceMatch = line.match(FENCE);
 		if (fenceMatch) {
+			finish();
 			if (fence === undefined) fence = fenceMatch[1][0];
 			else if (fence === fenceMatch[1][0]) fence = undefined;
 			return;
 		}
 		if (fence !== undefined) return;
 
+		if (line.trim() === "") {
+			finish();
+			return;
+		}
+
 		const match = line.match(LIST_ITEM);
-		if (!match) return;
-		const step = parseStep(match[3]);
-		if (!step.content) return;
-		items.push({ line: index, indent: match[1].length, lead: match[2], raw: match[3], step });
+		if (match) {
+			finish();
+			const step = parseStep(match[3]);
+			if (!step.content) return;
+			const item: PlanListItem = { line: index, indent: match[1].length, lead: match[2], raw: match[3], step };
+			items.push(item);
+			current = { item, continuation: [] };
+			return;
+		}
+
+		// A deeper, marker-less line continues the step's paragraph; a heading,
+		// a shallow line, or a blank line ends it. `raw` stays the first line so
+		// `setStepStatuses` edits the checkbox without touching these lines.
+		if (current !== undefined && indentOf(line) > current.item.indent && !HEADING.test(line)) {
+			const text = line.trim();
+			if (text) current.continuation.push(text);
+			return;
+		}
+
+		finish();
 	});
+
+	finish();
 	return items;
 }
 
@@ -208,7 +213,7 @@ function stepsSection(plan: string): { start: number; end: number } | undefined
 		if (!heading) continue;
 		const depth = heading[1].length;
 		if (start < 0) {
-			if (plainText(heading[2]).toLowerCase() !== "steps") continue;
+			if (normalizeHeadingText(heading[2]).toLowerCase() !== "steps") continue;
 			start = index;
 			level = depth;
 			continue;
@@ -271,7 +276,7 @@ const LIST_PREFIX = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?/;
  */
 export function verificationItem(plan: string): PlanStep | undefined {
 	if (stepsSection(plan) === undefined) return undefined;
-	const section = extractPlanSections(plan).find(
+	const section = extractSections(plan).find(
 		(candidate) => candidate.level > 0 && candidate.title.toLowerCase() === "verification",
 	);
 	if (!section) return undefined;
@@ -281,7 +286,7 @@ export function verificationItem(plan: string): PlanStep | undefined {
 		// A fenced block is how the outline asks for commands; its fence lines are
 		// punctuation, not a check, so only the commands inside it are carried.
 		.filter((line) => !FENCE.test(line))
-		.map((line) => plainText(line.replace(LIST_PREFIX, "")))
+		.map((line) => cleanLabel(line.replace(LIST_PREFIX, "")))
 		.filter(Boolean);
 	if (items.length === 0) return undefined;
 	return { content: elide(`Verify: ${items.join("; ")}`), status: "pending" };
@@ -361,43 +366,6 @@ export function setStepStatuses(plan: string, updates: readonly StepEdit[]): str
 	return lines.join("\n");
 }
 
-/**
- * Sections of a plan, split at heading lines outside code fences. The content
- * before the first heading is a section titled `""`. Pi's `Markdown` renderer
- * exposes no source-line map, so the review screen renders these chunks
- * separately to know where each section begins.
- */
-export function extractPlanSections(plan: string): PlanSection[] {
-	const sections: PlanSection[] = [];
-	let current: PlanSection | undefined;
-	let fence: string | undefined;
-
-	const flush = (): void => {
-		if (current && (current.title !== "" || current.text.trim() !== "")) sections.push(current);
-		current = undefined;
-	};
-
-	plan.split("\n").forEach((line, index) => {
-		const fenceMatch = line.match(FENCE);
-		if (fenceMatch) {
-			if (fence === undefined) fence = fenceMatch[1][0];
-			else if (fence === fenceMatch[1][0]) fence = undefined;
-		} else if (fence === undefined) {
-			const heading = line.match(HEADING);
-			if (heading) {
-				flush();
-				current = { title: plainText(heading[2]), text: line, line: index, level: heading[1].length };
-				return;
-			}
-		}
-		if (current === undefined) current = { title: "", text: line, line: 0, level: 0 };
-		else current.text += `\n${line}`;
-	});
-
-	flush();
-	return sections;
-}
-
 /**
  * The plan's own objective: the first paragraph of its `## Goal` section, with
  * inline markdown and a leading list marker removed.
@@ -407,7 +375,7 @@ export function extractPlanSections(plan: string): PlanSection[] {
  * `## Goal` section, so the caller can fall back to the title.
  */
 export function goalSection(plan: string): string | undefined {
-	const section = extractPlanSections(plan).find(
+	const section = extractSections(plan).find(
 		(candidate) => candidate.level === 2 && normalizeHeadingText(candidate.title).toLowerCase() === "goal",
 	);
 	if (section === undefined) return undefined;

package/extensions/plan/tools/enter.ts

@@ -12,8 +12,8 @@ import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { callLine, detailsOrLine } from "../../../lib/tui/tool.ts";
 import { failedResult } from "../../../lib/tool-result.ts";
-import { isRemoteTurn } from "../../../lib/interaction.ts";
-import { PLAN_CONSENT, READ_ONLY_SUMMARY } from "../../../lib/plan-entry.ts";
+import { isRemoteTurn, remoteLanguage } from "../../../lib/interaction.ts";
+import { PLAN_CONSENT, PLAN_CONSENT_SHORT, PLAN_CONSENT_SHORT_ZH, READ_ONLY_SUMMARY } from "../../../lib/plan-entry.ts";
 import { ENTER_TOOL, type PlanRuntime } from "../runtime.ts";
 import type { EnterPlanModeDetails } from "../types.ts";
 
@@ -53,7 +53,12 @@ export function registerEnterTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 				);
 			}
 
-			const approved = await ctx.ui.confirm("Enter plan mode?", PLAN_CONSENT);
+			const consent = isRemoteTurn(ctx)
+				? remoteLanguage(ctx) === "zh"
+					? PLAN_CONSENT_SHORT_ZH
+					: PLAN_CONSENT_SHORT
+				: PLAN_CONSENT;
+			const approved = await ctx.ui.confirm("Enter plan mode?", consent);
 			if (!approved) {
 				return {
 					content: [{ type: "text", text: "Stayed in normal mode. Proceed, or ask the user how to continue." }],

package/extensions/plan/tools/exit.ts

@@ -3,7 +3,7 @@
  *
  * It presents the saved plan for approval, then seeds the approved steps into
  * the todo list and finalizes the session goal: a `planning` goal becomes the
- * plan's own `## Goal`, and a session with no goal is offered the same. The
+ * plan's own `## Goal`, and a session with no goal is given the same. The
  * review loop and the browser lifecycle belong to `review.ts`; the nested writes
  * belong to `todo-seed.ts` and the goal tool.
  */
@@ -19,7 +19,6 @@ import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { callLine, detailsOrLine, moreHint } from "../../../lib/tui/tool.ts";
 import { failedResult } from "../../../lib/tool-result.ts";
-import { loadConfig } from "../config.ts";
 import { feedbackSummary } from "../feedback.ts";
 import { mergeSummary, overCap, preview, verificationNote } from "../format.ts";
 import { sanitizePlanText } from "../plan-text.ts";
@@ -35,7 +34,7 @@ import { seedTodos } from "./todo-seed.ts";
 const ExitPlanModeParams = Type.Object({
 	plan_path: Type.String({
 		description:
-			"Path to the plan file written by write_plan (absolute, or relative to the working directory). The user reviews this file.",
+			"Path to the plan file written by write_plan: the absolute path it returned, or the `~/…` form it displayed. A bare name resolves inside the plans directory. The user reviews this file.",
 	}),
 });
 
@@ -52,24 +51,18 @@ interface GoalOutcome {
 /**
  * Finalise the session goal from the approved plan.
  *
- * A `planning` goal needs no dialog — approving the plan *is* the decision — and a
- * session with no goal at all gets one confirm, unless `plan.goalPrompt` is off,
- * which records the objective without asking. A final goal (`active` or
- * `achieved`) is the user's own: approving ordinary work never rewrites it.
- * Recording runs through the goal tool, so validation and the widget stay goal's,
- * and no model turn is spent.
+ * Approving the plan *is* the decision, so neither a `planning` goal nor a
+ * session with none is asked again. A final goal (`active` or `achieved`) is the
+ * user's own: approving ordinary work never rewrites it. Recording runs through
+ * the goal tool when it is registered — validation and the widget stay goal's,
+ * and no model turn is spent — and stays silent when that sibling extension is
+ * not installed, because there is nothing to report and nothing to act on.
  */
-async function finalizeGoal(ctx: ExtensionToolContext, plan: StoredPlan): Promise<GoalOutcome> {
+async function finalizeGoal(pi: ExtensionAPI, ctx: ExtensionToolContext, plan: StoredPlan): Promise<GoalOutcome> {
 	const objective = planObjective(plan);
 	const current = lastGoal(ctx.sessionManager.getBranch());
 	if (current !== null && current.status !== "planning") return { objective };
-	if (current === null) {
-		if (!ctx.hasUI) return { objective };
-		if (loadConfig(ctx.cwd).goalPrompt) {
-			const approved = await ctx.ui.confirm("Record this plan as the session goal?", objective);
-			if (!approved) return { objective };
-		}
-	}
+	if (!pi.getAllTools().some((tool) => tool.name === GOAL_TOOL)) return { objective };
 	const outcome = await ctx.executeTool(GOAL_TOOL, { objective, status: "active" });
 	const action = current === null ? "recorded" : "promoted";
 	return outcome.isError ? { objective, action, error: firstTextLine(outcome) } : { objective, action };
@@ -101,7 +94,8 @@ export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: Pl
 		annotations: { readOnlyHint: true, openWorldHint: false },
 
 		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			const planPath = (params as ExitPlanModeArgs).plan_path.trim();
+			const args = params as ExitPlanModeArgs;
+			const planPath = args.plan_path.trim();
 
 			if (!runtime.isEnabled()) {
 				return failedResult("Not in plan mode; there is no plan to approve.", {
@@ -220,7 +214,7 @@ export function registerExitTool(pi: ExtensionAPI, runtime: PlanRuntime, web: Pl
 
 			runtime.disable(ctx);
 			const { steps, merged, error } = await seedTodos(pi, ctx, decision.plan.content);
-			const goal = await finalizeGoal(ctx, decision.plan);
+			const goal = await finalizeGoal(pi, ctx, decision.plan);
 			const listing =
 				steps.length > 0
 					? `\n\n${steps

package/extensions/plan/tools/write.ts

@@ -40,7 +40,7 @@ export function registerWriteTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 		name: WRITE_PLAN_TOOL,
 		label: "Write plan",
 		description:
-			"Save the plan you designed as a markdown file under .pi/plans (project root, or the agent directory outside a " +
+			"Save the plan you designed as a markdown file in the plans directory (the agent directory, keyed by " +
 			"repository). Write the complete plan, not a summary, in this outline so it is consistent and scannable:\n\n" +
 			`${PLAN_OUTLINE}\n\n` +
 			"Each section has one job: lead it with its outcome, keep a prose section to a few bullets or two or three " +
@@ -51,10 +51,11 @@ export function registerWriteTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 			"The outline is a guide, not a form: drop Context, Approach, Visual, or Risks when there is nothing to say. " +
 			"Keep Steps and Verification — the steps are read from that section (without it, the shallowest list " +
 			"anywhere becomes the steps), and Verification becomes the last todo item. " +
-			"In Steps, each top-level bullet is one outcome in the order you will do them, and deeper bullets are notes. " +
+			"In Steps, each top-level bullet is one outcome in the order you will do them; " +
+			"an indented line continues that outcome, and a deeper bullet is a note. " +
 			"Returns the path to pass to exit_plan_mode; plan_path overwrites an existing file when refining. " +
 			`A plan with more than ${MAX_STEPS} top-level steps in its Steps section is refused, so approval never drops steps it cannot track.`,
-		promptSnippet: "Save the designed plan as a markdown file under .pi/plans.",
+		promptSnippet: "Save the designed plan as a markdown file in the plans directory.",
 		promptGuidelines: [
 			"While plan mode is active, write the full plan with write_plan, then call exit_plan_mode with the returned path.",
 			"When refining with plan_path, keep every section heading as it was: the review marks changed sections by heading, " +
@@ -88,6 +89,10 @@ export function registerWriteTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 					planPath: args.plan_path,
 				});
 				runtime.setLastPlan(ctx, file.path);
+				// A store an older version kept in the checkout was moved in by this
+				// write; say so once, where the user is looking.
+				const moved = runtime.plans.takeNotice();
+				if (moved) ctx.ui.notify(moved, "info");
 				return textResult(
 					`Wrote the plan to ${file.relativePath}. Call exit_plan_mode with plan_path: ${file.path}${stepElisionNote(summary.elided)}`,
 					{ path: file.path, relativePath: file.relativePath, bytes: file.bytes } satisfies WritePlanDetails,

package/extensions/plan/tools.ts

@@ -2,7 +2,7 @@
  * Model-facing registration for the plan-mode tools.
  *
  * `enter_plan_mode` lets the model ask to plan before touching code; it needs
- * user confirmation. `write_plan` saves the plan artifact under `.pi/plans` and
+ * user confirmation. `write_plan` saves the plan artifact in the plans directory and
  * returns its path. `cancel_plan_mode` leaves planning without approving, so a
  * phone user is never trapped in read-only mode. `exit_plan_mode` reads that file
  * back, presents it for approval (a scrollable review screen in the TUI, a select dialog elsewhere),

package/extensions/plan/tui.ts

@@ -6,9 +6,11 @@
  * the active Markdown theme, so headings, lists, code, links, and quotes match
  * the rest of the application; plan-authored control characters are stripped
  * first so the file cannot drive the terminal. Task checkboxes are recolored
- * and the footer colors the primary actions. It returns the chosen action
- * through `onClose` so the caller can act
- * only after the screen is gone and input focus is free again.
+ * and the footer colors the primary actions. Approving leaves plan mode and
+ * starts the work, so it asks `y/N` first through the shared `ConfirmState`;
+ * the plan stays mounted, and `Esc` backs out of the question before it backs
+ * out of the review. It returns the chosen action through `onClose` so the
+ * caller can act only after the screen is gone and input focus is free again.
  */
 
 import { basename } from "node:path";
@@ -35,14 +37,14 @@ import {
 	type ViewportRowsSource,
 } from "../../lib/tui/chrome.ts";
 import { isCloseKey } from "../../lib/tui/cursor.ts";
+import { ConfirmState } from "../../lib/tui/confirm.ts";
 import { gaugeBar } from "../../lib/tui/gauge.ts";
 import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { plainRule, titleRule } from "../../lib/tui/rules.ts";
 import { emptyState, checkbox } from "../../lib/tui/rows.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { planTitle, type StoredPlan } from "./plans.ts";
-import { changedSections, sanitizePlanText, type SectionDigest } from "./plan-text.ts";
-import { extractPlanSections } from "./steps.ts";
+import { changedSections, planDisplayText, type SectionDigest } from "./plan-text.ts";
 
 /** What the user chose from the read/review screen. */
 export type PlanViewAction = "approve" | "refine" | "keep" | "browser" | "cancel";
@@ -175,6 +177,8 @@ export class PlanViewComponent implements Component {
 	private cache: BodyCache | null = null;
 	/** True while the inline refine editor owns the keyboard. */
 	private editing = false;
+	/** The y/N approval question, shared with the other destructive screens. */
+	private readonly confirm = new ConfirmState();
 	/** The inline refine editor, built lazily once a TUI handle is available. */
 	private editor: Editor | null = null;
 
@@ -195,12 +199,11 @@ export class PlanViewComponent implements Component {
 		const padding = width >= MIN_PADDED_WIDTH ? BODY_PADDING : 0;
 		const base = this.options.markdownTheme ?? getMarkdownTheme();
 		const theme = planMarkdownTheme(this.theme, base);
-		const current = sanitizePlanText(this.options.plan.content);
-		const changed = changedSections(this.options.baseline, current);
-		const chunks = extractPlanSections(current);
+		const current = planDisplayText(this.options.plan.content);
+		const marks = changedSections(this.options.baseline, current);
 		const lines: string[] = [];
 		const sections: SectionOffset[] = [];
-		chunks.forEach((chunk, index) => {
+		marks.forEach(({ section: chunk, changed }, index) => {
 			// Markdown pads every line to the full width for backgrounds; this screen
 			// draws no background, so the padding is dropped.
 			const rendered = new Markdown(chunk.text, padding, 0, theme)
@@ -209,14 +212,14 @@ export class PlanViewComponent implements Component {
 			sections.push({
 				title: chunk.title,
 				offset: lines.length,
-				...(changed[index] ? { changed: true } : {}),
+				...(changed ? { changed: true } : {}),
 			});
 			lines.push(...rendered);
 			// Sections render independently, so restore the blank line a heading-only
 			// chunk omits before the next section.
-			if (index < chunks.length - 1 && lines.length > 0 && lines[lines.length - 1] !== "") lines.push("");
+			if (index < marks.length - 1 && lines.length > 0 && lines[lines.length - 1] !== "") lines.push("");
 		});
-		this.cache = { width, lines, sections, changedCount: changed.filter(Boolean).length };
+		this.cache = { width, lines, sections, changedCount: marks.filter((mark) => mark.changed).length };
 		return this.cache;
 	}
 
@@ -314,6 +317,12 @@ export class PlanViewComponent implements Component {
 			this.options.requestRender();
 			return;
 		}
+		// A pending question owns the keyboard, so a scroll key cannot slip past it
+		// and `Esc` backs out of the question rather than the review.
+		if (this.confirm.pending) {
+			if (this.confirm.resolve(data) !== undefined) this.options.requestRender();
+			return;
+		}
 		if (isCloseKey(data)) {
 			this.options.onClose("keep");
 			return;
@@ -330,8 +339,10 @@ export class PlanViewComponent implements Component {
 		else if (matchesKey(data, Key.end) || data === "G") this.scrollTo(this.maxOffset);
 		else if (data === "n") this.jumpSection(1);
 		else if (data === "p") this.jumpSection(-1);
-		else if (data === "a") this.options.onClose("approve");
-		else if (data === "r") this.startRefine();
+		else if (data === "a") {
+			this.confirm.ask("Approve and run the plan? y/N", () => this.options.onClose("approve"));
+			this.options.requestRender();
+		} else if (data === "r") this.startRefine();
 		else if (data === "w") this.options.onClose("browser");
 		else if (data === "x") this.options.onClose("cancel");
 	}
@@ -400,10 +411,13 @@ export class PlanViewComponent implements Component {
 		} else {
 			if (this.maxOffset > 0) lines.push(scrollRow(theme, w, this.offset, end, body.length, sectionLabel));
 			else lines.push("");
+			const pending = this.confirm.pending;
 			const sectionHints = sections.length > 1 ? SECTION_HINTS : [];
 			const hints: ScreenHint[] =
 				this.maxOffset > 0 ? [...PRIMARY_HINTS, ...SCROLL_HINTS, ...sectionHints] : PRIMARY_HINTS;
-			lines.push(screenHint(theme, w, hints));
+			lines.push(
+				pending ? truncateToWidth(`  ${paint(theme, "warn", pending.prompt)}`, w) : screenHint(theme, w, hints),
+			);
 		}
 		lines.push(plainRule(theme, w));
 		return lines;

package/extensions/plan/types.ts

@@ -6,6 +6,32 @@ import type { PlanAnnotation } from "./feedback.ts";
 import type { SectionDigest } from "./plan-text.ts";
 import type { StepUpdate } from "./steps.ts";
 
+/**
+ * Who is looking at a running review: the session that opened it (`owner`, the
+ * only role that can approve), or someone the link was shared with (`reviewer`,
+ * who may comment).
+ */
+export type ReviewRole = "owner" | "reviewer";
+
+/**
+ * What a review token names: its role, and — for a reviewer — the name it posts
+ * under, bound the first time that link writes.
+ */
+export interface ReviewCaller {
+	role: ReviewRole;
+	/** The reviewer's name, once this link has written; absent for the owner and
+	 * for a reviewer that has not commented yet. */
+	name?: string;
+}
+
+/**
+ * One frame on the review's event stream. `comment`, `plan`, and `share` say a
+ * page should re-read the island; `closed` ends the review for everyone, and
+ * `revoked` tells a reviewer the owner stopped sharing. The frame carries no
+ * state of its own, so the island stays the one contract.
+ */
+export type ReviewFrame = "comment" | "plan" | "share" | "closed" | "revoked";
+
 /** Persisted (custom entry) plan-mode state. */
 export interface PlanModeEntry {
 	enabled: boolean;
@@ -38,7 +64,7 @@ export interface EnterPlanModeDetails {
 export interface WritePlanDetails {
 	/** Absolute path of the written plan file. */
 	path: string;
-	/** Path relative to the working directory, when inside it. */
+	/** How the path is shown: `~`-shortened, since plans live outside the project. */
 	relativePath: string;
 	/** Size of the written plan in bytes. */
 	bytes: number;
@@ -48,7 +74,7 @@ export interface WritePlanDetails {
 export interface SetPlanStepsDetails {
 	/** Absolute path of the plan file that was updated. */
 	path: string;
-	/** Path relative to the working directory, for transcript display. */
+	/** How the path is shown: `~`-shortened. */
 	relativePath: string;
 	/** The checkbox changes that were applied, in call order. */
 	updates: StepUpdate[];
@@ -66,7 +92,7 @@ export interface ExitPlanModeDetails {
 	plan: string;
 	/** Absolute path of the reviewed plan file. */
 	planPath?: string;
-	/** Path relative to the working directory, for transcript display. */
+	/** How the path is shown: `~`-shortened. */
 	relativePath?: string;
 	/** True when the user asked to refine the plan instead of approving. */
 	refined?: boolean;

package/extensions/plan/web-chrome.ts

@@ -43,7 +43,7 @@ export const WEB_CHROME_JS = String.raw`  function setStatus(text, kind) {
     var count = annotations.length;
     label += " \u00b7 " + count + (count === 1 ? " comment" : " comments");
     if (dirty && !saved && !approved && !closed) {
-      label += " \u00b7 unsaved";
+      label += " \u00b7 " + (role === "reviewer" ? "unposted" : "unsaved");
       if (!tone) tone = "warn";
     }
     stateEl.textContent = label;
@@ -76,6 +76,7 @@ export const WEB_CHROME_JS = String.raw`  function setStatus(text, kind) {
   function lockActions() {
     if (approveButton) approveButton.disabled = true;
     if (saveButton) saveButton.disabled = true;
+    if (postButton) postButton.disabled = true;
     if (cancelButton) cancelButton.disabled = true;
   }