@gavin-hu/my-pi-agent 0.14.0 → 0.15.0

package/lib/format.ts

@@ -55,6 +55,17 @@ export function formatToolCount(count: number): string {
 	return `${formatCount(n)} ${n === 1 ? "tool" : "tools"}`;
 }
 
+/**
+ * A tail bounded to `maxChars`: the end of the joined lines, with the truncation
+ * flag. The header and the truncation suffix belong to the caller, because each
+ * surface says something different about where the rest of the output lives.
+ */
+export function boundedTail(lines: readonly string[], maxChars: number): { text: string; truncated: boolean } {
+	const body = lines.join("\n");
+	if (body.length <= maxChars) return { text: body, truncated: false };
+	return { text: body.slice(body.length - maxChars), truncated: true };
+}
+
 /**
  * Replace terminal control characters (including ESC and the C1 block) with
  * spaces, keeping `\n` and `\t` for callers that render multi-line text.
@@ -96,6 +107,45 @@ export function sanitizeLine(text: string): string {
 	return sanitize(stripControlChars(text));
 }
 
+/** A string read as one sanitized line; any other value reads empty. */
+export function lineOf(value: unknown): string {
+	return typeof value === "string" ? sanitizeLine(value) : "";
+}
+
+/** Longest untrusted line kept for display; longer lines are clipped. */
+export const MAX_OUTPUT_LINE = 200;
+
+/** ESC-introduced sequences: OSC, CSI, and single-character escapes. */
+const OSC = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
+const CSI = /\u001b\[[0-?]*[ -/]*[@-~]/g;
+const OTHER_ESC = /\u001b[@-Z\\-_]/g;
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/g;
+
+/**
+ * The boundary for one line of **program output**: a log file, a child's
+ * stdout, a tailed file.
+ *
+ * Stronger than {@link sanitizeLine}, which strips control characters but leaves
+ * the printable tail of an ANSI sequence behind. This removes whole OSC, CSI,
+ * and single-character escapes first, then resolves carriage returns the way a
+ * terminal would (keep the text after the last `\r`, so progress rewrites
+ * collapse to their final state), squeezes whitespace, and clips the result.
+ *
+ * The escape-stripping has to happen before the control-character pass: once
+ * ESC has become a space, the rest of the sequence is ordinary text.
+ */
+export function sanitizeUntrustedLine(raw: string, maxLength: number = MAX_OUTPUT_LINE): string {
+	const withoutAnsi = raw.replace(OSC, "").replace(CSI, "").replace(OTHER_ESC, "");
+	const afterCr = withoutAnsi.slice(withoutAnsi.lastIndexOf("\r") + 1);
+	const cleaned = afterCr.replace(CONTROL, " ").replace(/\s+/g, " ").trim();
+	return cleaned.length > maxLength ? `${cleaned.slice(0, maxLength - 1)}…` : cleaned;
+}
+
+/** {@link sanitizeUntrustedLine} for a block of output, one entry per line. */
+export function sanitizeUntrustedText(raw: string, maxLength: number = MAX_OUTPUT_LINE): string[] {
+	return raw.split("\n").map((line) => sanitizeUntrustedLine(line, maxLength));
+}
+
 /**
  * Replace a home-directory prefix with `~`, matching at a path boundary so
  * `/home/bob` does not shorten `/home/bobby`. Separators are normalized to `/`

package/lib/git/read.ts

@@ -54,6 +54,14 @@ export async function gitDir(runGit: RunGit, cwd: string): Promise<string | unde
 	return dir || undefined;
 }
 
+/** Absolute path of the repository's common git directory, shared by its worktrees. */
+export async function gitCommonDir(runGit: RunGit, cwd: string): Promise<string | undefined> {
+	const result = await runGit(["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd });
+	if (result.code !== 0) return undefined;
+	const dir = result.stdout.trim();
+	return dir || undefined;
+}
+
 /** Resolve a revision to a full object id, or undefined when it does not exist. */
 export async function revParse(runGit: RunGit, cwd: string, rev: string): Promise<string | undefined> {
 	const result = await runGit(["rev-parse", "--verify", "--quiet", rev], { cwd });

package/lib/goal-state.ts

@@ -6,8 +6,13 @@
  * `error`, which is not a write — and the `/goal` command appends a `goal` custom
  * entry whose `data.goal` is `null` when the goal is cleared. Replaying the branch
  * in order is how another extension reads the goal without importing goal's
- * modules: `plan` restates an active goal in its planning context and offers to
- * record one when a plan is approved with none.
+ * modules: `plan` restates a pursued goal in its planning context, promotes a
+ * `planning` goal at plan exit, and offers to record one when a plan is approved
+ * with none.
+ *
+ * The status is the goal's phase: `planning` while a plan is being designed,
+ * `active` once the objective is final, `achieved` when it is done. Only `goal`
+ * writes it; the promotion out of `planning` runs through the `goal` tool.
  *
  * Stored values are re-validated and re-sanitized here. Branch data can be
  * tampered with, migrated, or written by an older version, and a reader must not
@@ -15,9 +20,10 @@
  * ignored rather than clearing a goal that is still valid.
  *
  * The entry type and the objective limit live here and are imported by `goal`, so
- * the publisher and the reader cannot drift. `goal` keeps its own reconstruction
- * (`extensions/goal/state.ts`) because it also drives the widget; this module is
- * the minimal contract other extensions may depend on.
+ * the publisher and the reader cannot drift. `goal` reads the branch through
+ * {@link lastGoal} as well — [`extensions/goal/state.ts`](../extensions/goal/state.ts)
+ * adds only the widget's active check and the open-todo count on top — so there
+ * is one replay, not two.
  */
 
 import { sanitizeLine } from "./format.ts";
@@ -29,8 +35,8 @@ export const GOAL_ENTRY_TYPE = "goal";
 /** Longest objective the goal tool accepts, and the most a reader will replay. */
 export const MAX_GOAL_OBJECTIVE = 2000;
 
-/** Whether the goal is still being pursued, or already done. */
-export type PublishedGoalStatus = "active" | "achieved";
+/** The goal's phase: being designed, final and pursued, or done. */
+export type PublishedGoalStatus = "planning" | "active" | "achieved";
 
 /** The goal as another extension may read it. */
 export interface PublishedGoal {
@@ -60,12 +66,21 @@ function readGoal(value: unknown): PublishedGoal | null | undefined {
 	if (!value || typeof value !== "object") return undefined;
 	const goal = value as { objective?: unknown; status?: unknown };
 	if (typeof goal.objective !== "string") return undefined;
-	if (goal.status !== "active" && goal.status !== "achieved") return undefined;
+	if (goal.status !== "planning" && goal.status !== "active" && goal.status !== "achieved") return undefined;
 	const objective = sanitizeLine(goal.objective);
 	if (!objective || objective.length > MAX_GOAL_OBJECTIVE) return undefined;
 	return { objective, status: goal.status };
 }
 
+/**
+ * True while the goal steers the session: `planning` or `active`, never
+ * `achieved`. Both the reminder and the plan-mode context read this, so a goal
+ * being designed is restated like one being executed.
+ */
+export function isPursuedGoal(goal: PublishedGoal | null): goal is PublishedGoal {
+	return goal?.status === "planning" || goal?.status === "active";
+}
+
 /** The last goal written on the branch, or `null` when the session has none. */
 export function lastGoal(entries: Iterable<unknown>): PublishedGoal | null {
 	let goal: PublishedGoal | null = null;

package/lib/http/headers.ts

@@ -0,0 +1,54 @@
+/**
+ * The response header sets both loopback servers answer with.
+ *
+ * One policy, declared once: the pages `file-browse` and `plan` serve are the
+ * same kind of document — a same-origin script, inline styles, and no network
+ * — so they must not drift into different envelopes, and a page that refuses to
+ * be framed cannot quietly stop doing so on one surface only.
+ *
+ * Every builder returns a fresh object, so a caller may add to a response
+ * without writing into another one. The policy itself is a code-authored
+ * constant; nothing here is model- or file-derived.
+ */
+
+/**
+ * The page policy. `default-src 'none'` makes every fetch opt-in; the inline
+ * style allowance is the page's own `<style>` block, `script-src 'self'` the
+ * same-origin client, and `connect-src 'self'` the page's own API routes.
+ *
+ * The last three directives are the ones that make a local page safe to leave
+ * open: `frame-ancestors 'none'` (with the legacy `X-Frame-Options`) stops a
+ * local page from framing the surface and clickjacking a control with a side
+ * effect, `base-uri 'self'` stops an injected `<base>` from re-pointing every
+ * relative URL, and `form-action 'none'` stops a submission anywhere.
+ */
+export const PAGE_CSP =
+	"default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; script-src 'self'; " +
+	"connect-src 'self'; frame-ancestors 'none'; base-uri 'self'; form-action 'none'";
+
+/** The security and caching headers every response carries, whatever its body. */
+function secured(contentType: string): Record<string, string> {
+	return {
+		"Content-Type": contentType,
+		"Content-Security-Policy": PAGE_CSP,
+		"X-Frame-Options": "DENY",
+		"X-Content-Type-Options": "nosniff",
+		"Referrer-Policy": "no-referrer",
+		"Cache-Control": "no-store",
+	};
+}
+
+/** Headers for a served HTML page. */
+export function pageHeaders(): Record<string, string> {
+	return secured("text/html; charset=utf-8");
+}
+
+/** Headers for a same-origin script: the page policy, with the script's own type. */
+export function scriptHeaders(): Record<string, string> {
+	return secured("text/javascript; charset=utf-8");
+}
+
+/** Headers for a JSON API reply: the same envelope, a JSON type. */
+export function jsonHeaders(): Record<string, string> {
+	return secured("application/json; charset=utf-8");
+}

package/lib/http/index.ts

@@ -0,0 +1,13 @@
+/**
+ * The loopback HTTP layer shared by `file-browse` and `plan`: the response
+ * shape, the header policy, the request-envelope helpers, and the socket seam.
+ *
+ * Import from here rather than a leaf module, so the layer reads as one kit.
+ * Value-only, like the rest of `lib/`: the only state is what a returned closure
+ * carries (`createCloser`).
+ */
+
+export * from "./headers.ts";
+export * from "./response.ts";
+export * from "./router.ts";
+export * from "./server.ts";

package/lib/http/response.ts

@@ -0,0 +1,46 @@
+/**
+ * The response shape both loopback servers answer with, and the builders that
+ * pair a body with the header set it needs.
+ *
+ * A router returns one of these instead of touching a socket, so every route is
+ * testable without a server, and `server.ts` in this directory is the only code
+ * that writes one out. The shape carries the two ways a response is not a
+ * buffered body — a file to stream and a stream to hold open — because those are
+ * properties of the answer, not of the server that serves it.
+ */
+
+import { jsonHeaders, pageHeaders } from "./headers.ts";
+
+/** One HTTP response, before it reaches a socket. */
+export interface ServeResponse {
+	/** HTTP status code. */
+	status: number;
+	/** Headers to send verbatim. */
+	headers: Record<string, string>;
+	/** The buffered body; omitted for an empty response or a streamed file. */
+	body?: string | Buffer;
+	/** When set, the server streams this file instead of `body`. */
+	filePath?: string;
+	/** When true, the server keeps the connection open as a Server-Sent Events stream. */
+	stream?: boolean;
+}
+
+/** An HTML page, with any headers the route needs to add to the page policy. */
+export function htmlResponse(status: number, body: string, extra?: Record<string, string>): ServeResponse {
+	return { status, headers: { ...pageHeaders(), ...extra }, body };
+}
+
+/** A JSON body, serialized once. */
+export function jsonResponse(status: number, value: unknown): ServeResponse {
+	return { status, headers: jsonHeaders(), body: JSON.stringify(value) };
+}
+
+/** The JSON error envelope both API surfaces share: `{ error }`. */
+export function jsonError(status: number, message: string): ServeResponse {
+	return jsonResponse(status, { error: message });
+}
+
+/** A plain-text body, for the internal-error fallback a server sends itself. */
+export function textResponse(status: number, body: string): ServeResponse {
+	return { status, headers: { ...pageHeaders(), "Content-Type": "text/plain; charset=utf-8" }, body };
+}

package/lib/http/router.ts

@@ -0,0 +1,52 @@
+/**
+ * The request-envelope helpers both loopback routers apply before a route runs:
+ * the request target, and the `Host` allowlist.
+ *
+ * Both surfaces bind `127.0.0.1`, so a `Host` naming anything else is a
+ * DNS-rebinding attempt against a local page. How strictly a missing `Host` is
+ * treated is the caller's decision: the browse server accepts one, because its
+ * router is also driven directly from tests and a plain `GET` with no header is
+ * not a rebinding, while the review server fails closed.
+ */
+
+/** The `Host` names a loopback interface, with or without a port. */
+const LOCAL_HOST = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i;
+
+/** A request target split into the parts a router matches on. */
+export interface ParsedRequestUrl {
+	/** The path, with the leading slash and no query. */
+	pathname: string;
+	/** The parsed query string. */
+	search: URLSearchParams;
+}
+
+/**
+ * Parse a raw request target (`path?query`) against a loopback base. Returns
+ * `undefined` for a target that cannot be parsed, which a router answers with
+ * `400` rather than a route.
+ */
+export function parseRequestUrl(rawUrl: string): ParsedRequestUrl | undefined {
+	try {
+		const url = new URL(rawUrl, "http://127.0.0.1");
+		return { pathname: url.pathname, search: url.searchParams };
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Whether the request's `Host` names this loopback server.
+ *
+ * With `required: false`, only a present, non-empty foreign name is refused, so
+ * a header-less request from another caller still routes. With `required: true`,
+ * a missing or non-string `Host` is refused too, so the guard cannot be skipped
+ * by omitting the header.
+ */
+export function isLocalHostHeader(
+	headers: Record<string, string | string[] | undefined>,
+	options: { required: boolean },
+): boolean {
+	const host = headers.host;
+	if (typeof host !== "string" || host === "") return !options.required;
+	return LOCAL_HOST.test(host);
+}

package/lib/http/server.ts

@@ -0,0 +1,91 @@
+/**
+ * The socket seam shared by the two loopback servers: bind, write a response
+ * out, and close.
+ *
+ * Everything here is behavior a caller cannot get right by accident: a bind on
+ * `127.0.0.1` only, an accept-level `error` listener so a transient failure
+ * cannot take the host down, a `HEAD` that sends headers and no body, a `filePath`
+ * response streamed instead of buffered, and a close that is safe to call twice
+ * and drops keep-alive connections. What each server does *around* this — SSE
+ * streams, request bodies, session settling — stays with that server.
+ */
+
+import { createReadStream } from "node:fs";
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+import type { ServeResponse } from "./response.ts";
+
+/**
+ * Bind `server` to `127.0.0.1:port` and resolve the port it actually bound
+ * (`0` asks the OS to pick one). Rejects when the bind fails, so a caller that
+ * wants a fallback can retry with another port.
+ */
+export async function bindLoopback(server: Server, port: number): Promise<number> {
+	await new Promise<void>((resolve, reject) => {
+		const onError = (error: Error) => reject(error);
+		server.once("error", onError);
+		server.listen(port, "127.0.0.1", () => {
+			server.off("error", onError);
+			resolve();
+		});
+	});
+	// An accept-level failure (EMFILE and friends) is emitted on the server, and an
+	// `error` event with no listener would take the host down mid-session. The
+	// affected request fails on its own and is answered as an error by the caller.
+	server.on("error", () => {});
+	const address = server.address();
+	return typeof address === "object" && address ? address.port : port;
+}
+
+/**
+ * Write one routed response: headers first, then no body for `HEAD`, the file
+ * for a `filePath` response, or the buffered body.
+ *
+ * A `stream` response is deliberately not handled here: keeping a connection
+ * open is the owning server's lifecycle, so it must check `stream` before
+ * calling this.
+ *
+ * `afterFlush` runs once a buffered body is on the wire, which is the point a
+ * server may resolve a session without the client seeing a dropped connection.
+ * A streamed file has no such single point, so `respond` never calls it for one.
+ */
+export function respond(
+	request: IncomingMessage,
+	response: ServerResponse,
+	result: ServeResponse,
+	afterFlush?: () => void,
+): void {
+	response.writeHead(result.status, result.headers);
+	if ((request.method ?? "GET").toUpperCase() === "HEAD") {
+		response.end(afterFlush);
+		return;
+	}
+	if (result.filePath) {
+		const stream = createReadStream(result.filePath);
+		stream.on("error", () => response.destroy());
+		stream.pipe(response);
+		return;
+	}
+	response.end(result.body ?? "", afterFlush);
+}
+
+/**
+ * An idempotent `close()` for `server`.
+ *
+ * The second call resolves at once, so a shutdown path and a stop path can both
+ * await it. `closeAllConnections` is not on the `Server` type of every supported
+ * Node version, so it is probed: without it a keep-alive connection could hold
+ * the close open.
+ */
+export function createCloser(server: Server): () => Promise<void> {
+	let closed = false;
+	return () =>
+		new Promise<void>((resolve) => {
+			if (closed) {
+				resolve();
+				return;
+			}
+			closed = true;
+			server.close(() => resolve());
+			(server as { closeAllConnections?: () => void }).closeAllConnections?.();
+		});
+}

package/lib/lines.ts

@@ -0,0 +1,77 @@
+/**
+ * Line splitting for a stream of untrusted output.
+ *
+ * A child's stdout, or a file read, arrives in arbitrary byte chunks: a chunk
+ * boundary can fall in the middle of a line, and — the case a naive
+ * `chunk.toString()` gets wrong — in the middle of a multi-byte UTF-8
+ * character. This buffers the bytes and decodes only at a newline, so a split
+ * character survives intact.
+ *
+ * `\r` is not treated as a break: a progress rewrite belongs to the sanitizer
+ * (`sanitizeUntrustedLine` in `lib/format.ts`, which keeps the text after the
+ * last carriage return), and breaking on it here would turn one rewritten line
+ * into several.
+ *
+ * Value-only: the buffer lives on the instance, so each reader owns one.
+ */
+
+/** Bytes buffered for one incomplete line before it is emitted anyway. */
+export const MAX_LINE_BYTES = 1024 * 1024;
+
+export interface LineSplitterOptions {
+	/** Emit an unfinished line once it grows past this many bytes. Default 1 MiB. */
+	maxLineBytes?: number;
+}
+
+export class LineSplitter {
+	private pending: Buffer = Buffer.alloc(0);
+	private readonly maxLineBytes: number;
+
+	constructor(options: LineSplitterOptions = {}) {
+		this.maxLineBytes = options.maxLineBytes ?? MAX_LINE_BYTES;
+	}
+
+	/** Bytes held for the unfinished line. */
+	get pendingBytes(): number {
+		return this.pending.length;
+	}
+
+	/**
+	 * Feed one chunk and take every complete line it finishes.
+	 *
+	 * A line far longer than any display can show is emitted once it reaches the
+	 * cap instead of being dropped, so a program that never prints a newline still
+	 * produces output.
+	 */
+	push(chunk: Uint8Array | string): string[] {
+		const bytes = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : Buffer.from(chunk);
+		const combined = this.pending.length > 0 ? Buffer.concat([this.pending, bytes]) : bytes;
+		const lines: string[] = [];
+		let start = 0;
+		for (let newline = combined.indexOf(0x0a); newline >= 0; newline = combined.indexOf(0x0a, start)) {
+			lines.push(combined.subarray(start, newline).toString("utf8"));
+			start = newline + 1;
+		}
+		let rest = combined.subarray(start);
+		if (rest.length > this.maxLineBytes) {
+			lines.push(rest.toString("utf8"));
+			rest = combined.subarray(0, 0);
+		}
+		// Copy, so a caller that reuses its read buffer cannot rewrite the tail.
+		this.pending = Buffer.from(rest);
+		return lines;
+	}
+
+	/** Take the unfinished line, for a stream that has ended. */
+	flush(): string[] {
+		if (this.pending.length === 0) return [];
+		const line = this.pending.toString("utf8");
+		this.pending = Buffer.alloc(0);
+		return [line];
+	}
+
+	/** Drop the unfinished line, for a source that was truncated or replaced. */
+	reset(): void {
+		this.pending = Buffer.alloc(0);
+	}
+}

package/lib/pdf.ts

@@ -0,0 +1,82 @@
+/**
+ * The optional `unpdf` seam: lazy load, module-shape handling, and text
+ * extraction, shared by `web-access` and `document`.
+ *
+ * `unpdf` bundles a server-friendly build of PDF.js, so it is imported lazily:
+ * an extension registers on every session, and a parser should load only when a
+ * read actually needs it. `web-access` treats the package as optional and
+ * reports {@link pdfGuidance} when it is absent; `document` ships it as a
+ * dependency. Both get the same loader, the same merged-pages call, and the same
+ * result unwrapping, so a PDF reads the same way through either surface.
+ *
+ * Value-only: no module state, and no import of `unpdf` until a caller asks.
+ */
+
+/** Install command for the optional PDF extractor package. */
+const UNPDF_INSTALL = "npm i unpdf";
+
+/** Model-facing guidance when the optional `unpdf` package is absent. */
+export function pdfGuidance(): string {
+	return `PDF extraction requires the optional 'unpdf' package (${UNPDF_INSTALL}).`;
+}
+
+/** Raised when `unpdf` is missing or does not expose `extractText`. */
+export class PdfUnavailableError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "PdfUnavailableError";
+	}
+}
+
+/** Extract merged page text from PDF bytes. */
+export type PdfExtractor = (bytes: Uint8Array) => Promise<string>;
+
+/** Pull the merged text out of `unpdf`'s `{ totalPages, text }` result. Pure. */
+export function pdfTextFromResult(result: unknown): string {
+	if (typeof result === "string") return result;
+	const text = (result as { text?: unknown } | undefined)?.text;
+	return typeof text === "string" ? text : "";
+}
+
+/** The `extractText` function of an imported `unpdf` module, when it exposes one. */
+function extractTextOf(module: unknown): ((bytes: Uint8Array, options?: unknown) => Promise<unknown>) | undefined {
+	if (typeof module !== "object" || module === null) return undefined;
+	const named = (module as { extractText?: unknown }).extractText;
+	if (typeof named === "function") return named as (bytes: Uint8Array, options?: unknown) => Promise<unknown>;
+	const fallback = (module as { default?: unknown }).default;
+	if (typeof fallback !== "object" || fallback === null) return undefined;
+	const nested = (fallback as { extractText?: unknown }).extractText;
+	if (typeof nested !== "function") return undefined;
+	return nested as (bytes: Uint8Array, options?: unknown) => Promise<unknown>;
+}
+
+/**
+ * Build an extractor from an imported `unpdf` module.
+ *
+ * `unpdf` exports `extractText` directly; the default-export fallback tolerates
+ * a build that wraps it. Anything else is a broken install, reported with the
+ * same error the missing-package path uses.
+ */
+export function pdfExtractorFromModule(module: unknown): PdfExtractor {
+	const extractText = extractTextOf(module);
+	if (!extractText) throw new PdfUnavailableError("The installed 'unpdf' package does not export extractText.");
+	return async (bytes) => pdfTextFromResult(await extractText(bytes, { mergePages: true }));
+}
+
+/** Load `unpdf` lazily, or throw {@link PdfUnavailableError} with install guidance. */
+export async function loadPdfExtractor(): Promise<PdfExtractor> {
+	let module: unknown;
+	try {
+		module = await import("unpdf");
+	} catch {
+		throw new PdfUnavailableError(pdfGuidance());
+	}
+	return pdfExtractorFromModule(module);
+}
+
+/** Extract merged page text from PDF bytes, using `extractor` when given. */
+export async function extractPdfText(bytes: Uint8Array, extractor?: PdfExtractor): Promise<string> {
+	if (extractor) return extractor(bytes);
+	const loaded = await loadPdfExtractor();
+	return loaded(bytes);
+}

package/lib/plan-entry.ts

@@ -0,0 +1,71 @@
+/**
+ * Plan-mode entry, shared by the extension that owns the mode and the one that
+ * offers it as a phase of the goal.
+ *
+ * Plan mode has one owner: `plan` gates the tools, persists the flag, and draws
+ * the footer. A tool context can reach it through `ctx.executeTool`, but a
+ * command context cannot (`ExtensionCommandContext` has no `executeTool`), so the
+ * request travels on `pi.events` as an in-process request/response. The caller
+ * asks the user — with the consent sentence below — and `plan` enables without a
+ * second dialog, so the session never asks twice for one decision.
+ *
+ * The consent sentence and the read-only summary live here because two
+ * extensions show them: one copy each is how a trust guarantee drifts apart.
+ * Value-only, as `lib/` must be: the state is the caller's context and a closure,
+ * never a module variable.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isPlanModeEnabled } from "./plan-state.ts";
+import { PLAN_ENTER_TOOL } from "./tool-names.ts";
+
+/** EventBus channel on which a caller asks `plan` to enable plan mode. */
+export const PLAN_ENTER_REQUEST = "my-pi-agent/plan-mode/enter";
+
+/** One clause describing the read-only guarantee, reused across prompts. */
+export const READ_ONLY_SUMMARY =
+	"write and edit are disabled, bash is limited to read-only git commands, and other mutating tools are blocked; " +
+	"subagent delegation is forced read-only, and the only file write is write_plan (under .pi/plans, or the agent " +
+	"directory outside a repository)";
+
+/**
+ * The consent question, as the user sees it. Shown by `enter_plan_mode` and by
+ * any caller that offers plan mode itself, so both describe the same guarantee.
+ */
+export const PLAN_CONSENT =
+	`Plan mode is read-only exploration: ${READ_ONLY_SUMMARY}. ` +
+	"Enter plan mode to investigate and propose an approach before making changes?";
+
+/** What a caller sends on {@link PLAN_ENTER_REQUEST}. */
+export interface PlanEnterRequest {
+	/** The caller's context; `plan` uses it for the footer status. */
+	ctx: ExtensionContext;
+	/** Called once, synchronously, with whether plan mode is on. */
+	respond(entered: boolean): void;
+}
+
+/**
+ * Ask `plan` to turn plan mode on, and report whether it is on afterwards.
+ *
+ * Resolves `true` without asking when the branch is already planning, and
+ * `false` when the `plan` tool is not registered — so `goal` loaded alone keeps
+ * working and nothing waits on a listener that is not there. The listener answers
+ * synchronously; the microtask is the fallback that guarantees resolution.
+ */
+export function requestPlanMode(
+	pi: Pick<ExtensionAPI, "events" | "getAllTools">,
+	ctx: ExtensionContext,
+): Promise<boolean> {
+	if (isPlanModeEnabled(ctx.sessionManager.getBranch())) return Promise.resolve(true);
+	if (!pi.getAllTools().some((tool) => tool.name === PLAN_ENTER_TOOL)) return Promise.resolve(false);
+	return new Promise<boolean>((resolve) => {
+		let settled = false;
+		const respond = (entered: boolean): void => {
+			if (settled) return;
+			settled = true;
+			resolve(entered);
+		};
+		pi.events.emit(PLAN_ENTER_REQUEST, { ctx, respond } satisfies PlanEnterRequest);
+		queueMicrotask(() => respond(false));
+	});
+}

package/lib/plan-state.ts

@@ -0,0 +1,34 @@
+/**
+ * The plan-mode flag as the session branch carries it.
+ *
+ * Plan mode persists one custom entry (`plan-mode`) whose `enabled` field is the
+ * last word on the branch. `plan` writes it; `rewind` reads it through this
+ * module so `/review` cannot write while planning, without importing another
+ * extension's modules.
+ *
+ * Value-only: a constant and a pure replay over untrusted branch entries.
+ */
+
+/** Custom-entry type plan mode persists. */
+export const PLAN_MODE_ENTRY_TYPE = "plan-mode";
+
+/**
+ * Whether the branch's last valid plan-mode entry is enabled.
+ *
+ * Branch data is untrusted: an entry with the wrong type, a malformed `data`, or
+ * a non-boolean `enabled` is skipped rather than read as false. The last valid
+ * entry wins, so a later disable turns it off and a `/tree` restore follows the
+ * branch it lands on.
+ */
+export function isPlanModeEnabled(entries: readonly unknown[]): boolean {
+	let enabled = false;
+	for (const raw of entries) {
+		if (!raw || typeof raw !== "object") continue;
+		const entry = raw as { type?: unknown; customType?: unknown; data?: unknown };
+		if (entry.type !== "custom" || entry.customType !== PLAN_MODE_ENTRY_TYPE) continue;
+		if (!entry.data || typeof entry.data !== "object") continue;
+		const value = (entry.data as { enabled?: unknown }).enabled;
+		if (typeof value === "boolean") enabled = value;
+	}
+	return enabled;
+}