@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/extensions/job/session.ts

@@ -4,18 +4,30 @@
  * Each session owns one registry file per project, but a job is still owned by
  * the session that started it. To tell a live owner from a dead one — so a new
  * session can adopt a dead peer's records instead of reaping them blindly —
- * each session writes a small heartbeat marker (its session id, pid, and
- * last-seen time) beside the registry while it runs jobs. Adoption reads those
+ * each session writes a small heartbeat marker (its session id, pid, the process's
+ * start time, and last-seen time) beside the registry. Adoption reads those
  * markers, so a live peer's jobs are left alone and a dead peer's are taken
  * over.
  *
+ * The heartbeat only ticks while a job runs, because that is when the repaint
+ * clock runs: a session that has finished its work stops writing, and its marker
+ * ages. That is why age alone is not death — the rule is the roster's own
+ * (`lib/session-roster.ts`'s `live` / `quiet` / `gone`), read here over a
+ * marker, and *only* `gone` lets another session take anything over. A marker
+ * whose process is alive is evidence of an owner, not litter, so pruning keeps
+ * it; the start token is what tells an idle session apart from a reused pid.
+ *
  * Markers are best-effort: a missing directory or an unwritable file degrades
- * to "owner dead", which is the conservative default. The liveness rule is pure
- * (`isSessionAlive`) so it is unit-tested without real processes.
+ * to "no marker", which reads as an owner that is gone — the conservative
+ * default for adoption. The rule is pure (`sessionStateOf`) so it is unit-tested
+ * without real processes, and `createOwnership` is that rule wired to one
+ * runtime's directory, clock, and seams: the state of a peer, this session's own
+ * marker, and the pruning of the markers that are left.
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { type RosterSeams, type RosterState, rosterStateOf } from "../../lib/session-roster.ts";
 import { sessionMarkerPath } from "./paths.ts";
 
 /** Prefix shared by every marker file, so log/registry files are never parsed. */
@@ -27,6 +39,14 @@ export interface SessionMarker {
 	sessionId: string;
 	/** Host process pid, checked for liveness before trusting the timestamp. */
 	pid: number;
+	/**
+	 * That process's start time, when the platform can say.
+	 *
+	 * A pid that is alive may be a different program than the one the marker named, and
+	 * nothing cheaper than the start time tells them apart — so this is what keeps a
+	 * reused pid from reading as an idle session forever.
+	 */
+	startToken?: string;
 	/** Millisecond timestamp of the last heartbeat. */
 	updatedAt: number;
 }
@@ -39,16 +59,33 @@ function parseMarker(raw: unknown): SessionMarker | undefined {
 	if (typeof marker.sessionId !== "string" || typeof marker.pid !== "number" || typeof marker.updatedAt !== "number") {
 		return undefined;
 	}
-	return { sessionId: marker.sessionId, pid: marker.pid, updatedAt: marker.updatedAt };
+	return {
+		sessionId: marker.sessionId,
+		pid: marker.pid,
+		...(typeof marker.startToken === "string" && marker.startToken !== "" ? { startToken: marker.startToken } : {}),
+		updatedAt: marker.updatedAt,
+	};
 }
 
 /** Write (or refresh) a session's marker. Failures are non-fatal for the caller. */
-export function touchSessionMarker(dir: string, sessionId: string, pid: number, now: number): void {
+export function touchSessionMarker(
+	dir: string,
+	sessionId: string,
+	pid: number,
+	now: number,
+	startToken?: string,
+): void {
 	try {
 		mkdirSync(dir, { recursive: true });
 		const path = sessionMarkerPath(dir, sessionId);
 		const tmp = `${path}.tmp`;
-		writeFileSync(tmp, JSON.stringify({ sessionId, pid, updatedAt: now } satisfies SessionMarker), "utf-8");
+		const marker: SessionMarker = {
+			sessionId,
+			pid,
+			...(startToken === undefined ? {} : { startToken }),
+			updatedAt: now,
+		};
+		writeFileSync(tmp, JSON.stringify(marker), "utf-8");
 		renameSync(tmp, path);
 	} catch {
 		// A marker is best-effort; a missing one reads as a dead owner.
@@ -70,7 +107,7 @@ export function removeSessionMarker(dir: string, sessionId: string): void {
 		const path = sessionMarkerPath(dir, sessionId);
 		if (existsSync(path)) unlinkSync(path);
 	} catch {
-		// Best-effort; a leftover marker expires on its own.
+		// Best-effort; a leftover marker is reaped when its session is gone.
 	}
 }
 
@@ -94,23 +131,99 @@ export function listSessionMarkers(dir: string): SessionMarker[] {
 }
 
 /**
- * Whether a marker still represents a live session: it must exist, its pid must
- * be alive, and its heartbeat must be within `ttlMs`. A missing marker is dead.
+ * What a marker says about its session: `live`, `quiet`, or `gone`.
+ *
+ * The rule is the roster's, asked over a marker, so `session-bus`, the board's page, and
+ * this extension cannot answer "is that session around" three ways. A dead pid is `gone`
+ * however fresh the heartbeat; a live pid with an aged heartbeat is `quiet`, which is the
+ * ordinary state of a session that has finished its jobs; and a pid that has since been
+ * reused is `gone` once the start token disagrees. A missing marker is `gone`: no file is
+ * no evidence of an owner.
  */
-export function isSessionAlive(
+export function sessionStateOf(
 	marker: SessionMarker | undefined,
 	now: number,
 	ttlMs: number,
-	isAlive: (pid: number) => boolean,
-): boolean {
-	if (!marker) return false;
-	if (marker.pid > 0 && !isAlive(marker.pid)) return false;
-	return now - marker.updatedAt <= ttlMs;
+	seams: RosterSeams = {},
+): RosterState {
+	if (marker === undefined) return "gone";
+	return rosterStateOf(
+		{
+			lastSeen: marker.updatedAt,
+			// A marker naming no usable process is judged by its heartbeat alone, which is the
+			// roster's answer for a record that cannot say which process owns it.
+			...(marker.pid > 0 ? { pid: marker.pid } : {}),
+			...(marker.startToken === undefined ? {} : { startToken: marker.startToken }),
+		},
+		now,
+		ttlMs,
+		seams,
+	);
 }
 
-/** Delete markers whose owner is no longer alive. */
-export function pruneSessionMarkers(dir: string, now: number, ttlMs: number, isAlive: (pid: number) => boolean): void {
+/**
+ * Delete the markers of sessions that are gone.
+ *
+ * A marker whose process is alive is kept, including one whose heartbeat has aged: that is
+ * what every idle session's marker looks like, and removing it would let a peer adopt a
+ * session that is still there. Only a session that has really gone — a dead pid, or a
+ * reused one — loses its marker.
+ */
+export function pruneSessionMarkers(dir: string, now: number, ttlMs: number, seams: RosterSeams = {}): void {
 	for (const marker of listSessionMarkers(dir)) {
-		if (!isSessionAlive(marker, now, ttlMs, isAlive)) removeSessionMarker(dir, marker.sessionId);
+		if (sessionStateOf(marker, now, ttlMs, seams) === "gone") removeSessionMarker(dir, marker.sessionId);
 	}
 }
+
+/** What the ownership rule needs from the runtime it serves. */
+export interface OwnershipOptions {
+	/** The directory the markers sit in. */
+	directory(): string;
+	/** This session's id; it is never `gone`. */
+	sessionId(): string;
+	/** The clock the rule is read against. */
+	now(): number;
+	/** How old a beat may be before the marker's pid is re-checked for reuse. */
+	ttlMs(): number;
+	/** Whether a pid is still running. */
+	alive(pid: number): boolean;
+	/** That pid's start time, when the platform can say. */
+	startToken(pid: number): string | undefined;
+}
+
+/** One runtime's view of the sessions that own jobs. */
+export interface Ownership {
+	/** `live`, `quiet`, or `gone` for the session that owns a job. */
+	state(owner: string): RosterState;
+	/** Write this session's marker, naming its process and that process's start time. */
+	touch(): void;
+	/** Drop the markers of sessions that are gone, keeping a live or a quiet one. */
+	prune(): void;
+}
+
+/**
+ * Wire the rule to one runtime: what a peer's session is, this session's own marker, and
+ * the pruning of the markers nobody owns any more.
+ */
+export function createOwnership(options: OwnershipOptions): Ownership {
+	const seams = (): RosterSeams => ({ alive: options.alive, token: options.startToken });
+	// This process's token cannot change while the session runs, and on a platform without
+	// `ps` the ask costs a failed spawn, so it is asked once and kept, missing or not.
+	let token: string | undefined;
+	let asked = false;
+	const ownToken = (): string | undefined => {
+		if (!asked) {
+			asked = true;
+			token = options.startToken(process.pid);
+		}
+		return token;
+	};
+	return {
+		state: (owner) =>
+			owner === options.sessionId()
+				? "live"
+				: sessionStateOf(readSessionMarker(options.directory(), owner), options.now(), options.ttlMs(), seams()),
+		touch: () => touchSessionMarker(options.directory(), options.sessionId(), process.pid, options.now(), ownToken()),
+		prune: () => pruneSessionMarkers(options.directory(), options.now(), options.ttlMs(), seams()),
+	};
+}

package/extensions/job/store.ts

@@ -1,11 +1,11 @@
 /**
  * Durable job storage: the on-disk registry that outlives a session.
  *
- * The live process table (the `Job` map, including the `owned` child handles)
- * stays in the runtime because process events mutate it; this owns the parts
- * that survive a session — the registry directory, the id counter, the atomic
- * write of this session's own registry file, and the trusted artifact-path
- * rules. Each session writes only its own file, so peers never race.
+ * The live table (the `Job` map) stays in the runtime and the handles stay in
+ * `child.ts`, because process events mutate both; this owns the parts that
+ * survive a session — the registry directory, the id counter, the atomic write of
+ * this session's own registry file, and the trusted artifact-path rules. Each
+ * session writes only its own file, so peers never race.
  *
  * Persistence is best-effort: an unwritable registry must never break a job that
  * is otherwise running fine.
@@ -101,8 +101,8 @@ export function createJobStore(initialDir = registryDirFor(process.cwd())): JobS
 	};
 }
 
-/** Strip runtime-only fields for persistence. */
-export function toRecord(job: Job): JobRecord {
+/** Strip runtime-only fields for persistence: the record, with or without a live handle. */
+export function toRecord(job: JobRecord & { owned?: boolean }): JobRecord {
 	const { owned: _owned, ...record } = job;
 	return record;
 }

package/extensions/job/tools.ts

@@ -34,7 +34,7 @@ import {
 import type { JobsRuntime } from "./runtime.ts";
 import { JobParams, normalizeCall, type JobArgs, type JobCall } from "./schema.ts";
 import { toRecord } from "./store.ts";
-import { jobTail, type JobResultInput } from "./tui.ts";
+import { jobTail, type JobResultInput } from "./render.ts";
 import type { JobDetails, JobRecord } from "./types.ts";
 
 export const TOOL_NAME = "job";
@@ -73,7 +73,7 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 			try {
 				switch (call.action) {
 					case "start": {
-						const job = runtime.start(
+						const job = await runtime.start(
 							{
 								command: call.command,
 								cwd: call.cwd,
@@ -145,7 +145,7 @@ export function registerTools(pi: ExtensionAPI, runtime: JobsRuntime): void {
 					case "kill": {
 						const before = runtime.get(call.id);
 						if (!before) return errorResult("kill", `no job "${call.id}".`);
-						const job = runtime.kill(call.id, call.signal);
+						const job = await runtime.kill(call.id, call.signal);
 						if (!job) return errorResult("kill", `no job "${call.id}".`);
 						const wasRunning = before.status === "running";
 						return textResult(

package/extensions/job/types.ts

@@ -59,6 +59,53 @@ export interface Job extends JobRecord {
 	owned: boolean;
 }
 
+export interface StartOptions {
+	command: string;
+	cwd?: string;
+	label?: string;
+	wake?: boolean;
+	detached?: boolean;
+	/** Give the child a stdin pipe, so `send` can write to it while it runs here. */
+	stdin?: boolean;
+	/** Auto-kill the job after this many milliseconds (SIGTERM, escalating to SIGKILL). */
+	timeoutMs?: number;
+}
+
+export interface WaitResult {
+	job: Job;
+	timedOut: boolean;
+	cancelled: boolean;
+}
+
+/** A job's log as `logs` returns it: the model-facing render plus the raw tail. */
+export interface LogResult {
+	job: Job;
+	/** Model-facing render of the tail, including status header/truncation note. */
+	text: string;
+	/** Sanitized tail lines, for the `/jobs` log pane. */
+	lines: string[];
+	truncated: boolean;
+	/** True when earlier log lines exist beyond the returned window. */
+	more: boolean;
+}
+
+export interface SendOptions {
+	/** Text written to the job's stdin. */
+	input?: string;
+	/** Append a newline to `input`; defaults to true. */
+	newline?: boolean;
+	/** End the job's stdin after writing, so the child sees EOF. */
+	eof?: boolean;
+}
+
+export interface SendResult {
+	job: Job;
+	/** Characters of `input` written, excluding any newline this call added. */
+	sent: number;
+	/** True when this call ended the job's stdin. */
+	closed: boolean;
+}
+
 /** Registry file contents. One file exists per session. */
 export interface RegistryFile {
 	version: 1;

package/extensions/job/{tui.ts → view/jobs-screen.ts}

@@ -1,80 +1,26 @@
 /**
- * Terminal rendering for jobs' `/jobs` screen.
+ * The `/jobs` screen: a dismissible list with a focused detail pane and a log
+ * view, drawn as a `DockListScreen`.
  *
- * `JobListComponent` is the dismissible `/jobs` screen with a focused detail
- * pane and a log view. It is stateless with respect to time: elapsed values are
- * computed from `Date.now()` at render, so the command can refresh the screen
- * without rebuilding the component.
+ * It is stateless with respect to time: elapsed values are computed from
+ * `Date.now()` at render, so the command can refresh the screen without
+ * rebuilding the component. The frame, the navigation keys, the y/N
+ * confirmation, and the log pane come from the shared `DockListScreen`, so this
+ * module owns only the job vocabulary: the rows, the focus block, the counts,
+ * the hints, and what the verbs do.
  *
- * The frame, the navigation keys, the y/N confirmation, and the log pane come
- * from the shared `DockListScreen`, so this module owns only the job vocabulary:
- * the row, the focus block, the counts, the hints, and what the verbs do.
- *
- * Log text arrives already sanitized by the runtime, so no untrusted escape
- * sequence reaches the terminal through here.
+ * Full-screen surfaces live under `view/` and load on first use: the `/jobs`
+ * command imports this module behind its TUI branch, so registration never
+ * pays for it. See `docs/extensions/job.md`.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { formatDuration, sanitizeUntrustedLine } from "../../lib/format.ts";
-import type { ScreenHint, ViewportRowsSource } from "../../lib/tui/chrome.ts";
-import { DockListScreen, type DetailContents } from "../../lib/tui/dock-screen.ts";
-import { SEPARATORS } from "../../lib/tui/glyphs.ts";
-import { statusRow, type StatusRow } from "../../lib/tui/rows.ts";
-import type { TailResultInput } from "../../lib/tui/tool.ts";
-import { paint } from "../../lib/tui/tokens.ts";
-import {
-	compareJobs,
-	elapsedMs,
-	formatJobDetail,
-	jobCounts,
-	shortLabel,
-	statusGlyphChar,
-	statusRole,
-	type JobCounts,
-} from "./format.ts";
-import type { JobRecord } from "./types.ts";
-
-/** One job row: selection marker, status glyph, id, label, and a right-aligned
- *  elapsed value, tagged `peer` when another session owns it. `statusRow` owns
- *  the clipping and the alignment. */
-function jobRow(
-	job: JobRecord,
-	theme: Theme,
-	width: number,
-	options: Pick<StatusRow, "selected" | "marker"> & { foreign?: boolean } = {},
-): string {
-	const elapsed = formatDuration(elapsedMs(job, Date.now()));
-	return statusRow(theme, width, {
-		...options,
-		glyph: statusGlyphChar(job.status),
-		glyphRole: statusRole(job.status),
-		label: `${job.id}  ${shortLabel(job)}`,
-		labelRole: options.selected ? "accent" : "label",
-		// The tag rides the right-aligned cell, which survives a narrow terminal.
-		trailing: options.foreign ? `${elapsed}${SEPARATORS.item}peer` : elapsed,
-	});
-}
-
-/** Input for the transcript result: a themed job list or a log tail. */
-export type JobResultInput =
-	| { kind: "list"; jobs: JobRecord[]; more: number; sessionId?: string }
-	| { kind: "logs"; lines: string[]; earlier: number };
-
-/** Map the job vocabulary onto the shared transcript tail block. */
-export function jobTail(input: JobResultInput): TailResultInput<JobRecord> {
-	if (input.kind === "logs") {
-		return { kind: "lines", lines: input.lines, earlier: input.earlier, earlierLabel: "lines" };
-	}
-	return {
-		kind: "list",
-		rows: input.jobs,
-		more: input.more,
-		rowLine: (job, width, theme) => {
-			const foreign = input.sessionId !== undefined && job.sessionId !== input.sessionId;
-			return jobRow(job, theme, width, { marker: false, foreign });
-		},
-	};
-}
+import { sanitizeUntrustedLine } from "../../../lib/format.ts";
+import type { ScreenHint, ViewportRowsSource } from "../../../lib/tui/chrome.ts";
+import { DockListScreen, type DetailContents } from "../../../lib/tui/dock-screen.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { compareJobs, formatJobDetail, jobCounts, type JobCounts, jobRow, shortLabel } from "../format.ts";
+import type { JobRecord } from "../types.ts";
 
 export interface JobListCallbacks {
 	/** This session's id: a record with another id belongs to a peer session. */
@@ -161,8 +107,8 @@ export class JobListComponent extends DockListScreen<JobRecord> {
 			"Esc close",
 			"↑/↓ or j/k select",
 			{ text: "Enter or l logs", color: "accent" },
-			{ text: "d or K kill", color: "warning" },
-			{ text: "x clear finished", color: "warning" },
+			{ text: "d or K kill", color: "warn" },
+			{ text: "x clear finished", color: "warn" },
 			"PgUp/PgDn",
 		];
 	}

package/extensions/job/waiters.ts

@@ -1,11 +1,22 @@
 /**
- * Waiter bookkeeping for the `wait` action.
+ * The `wait` action: waiter bookkeeping, and the promise a caller waits on.
  *
  * `wait` registers a resolver per job; a job's completion (or a kill/clear)
  * wakes every waiter for that id. Kept separate from the runtime so the map and
  * its cleanup rules are testable on their own and the runtime holds one field.
+ * The race the caller sees — the record, the timeout, or an abort — is here for
+ * the same reason: it is bookkeeping, not a decision about a record.
  */
 
+/** Default `wait` timeout, for a caller that names none. */
+export const DEFAULT_WAIT_MS = 30_000;
+
+/** Why a `wait` stopped waiting; the caller reads the record itself. */
+export interface WaitOutcome {
+	timedOut: boolean;
+	cancelled: boolean;
+}
+
 /** Resolvers waiting on a job id. */
 export interface Waiters {
 	/** Register `resolve` for `id`; returns a function that removes it again. */
@@ -44,3 +55,35 @@ export function createWaiters(): Waiters {
 		},
 	};
 }
+
+/**
+ * Resolve when `id` settles, or when the timeout or the abort signal wins.
+ *
+ * One promise, one cleanup: the timer is cleared, the abort listener removed, and
+ * the waiter dropped, whichever of the three settles it.
+ */
+export function waitFor(
+	waiters: Waiters,
+	id: string,
+	options: { timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<WaitOutcome> {
+	return new Promise<WaitOutcome>((resolve) => {
+		let settled = false;
+		let remove = (): void => {};
+		const finish = (timedOut: boolean, cancelled: boolean): void => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			options.signal?.removeEventListener("abort", onAbort);
+			remove();
+			resolve({ timedOut, cancelled });
+		};
+		const resolveWaiter = (): void => finish(false, false);
+		const onAbort = (): void => finish(false, true);
+		const timer = setTimeout(() => finish(true, false), options.timeoutMs ?? DEFAULT_WAIT_MS);
+
+		remove = waiters.add(id, resolveWaiter);
+		if (options.signal?.aborted) onAbort();
+		else options.signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}

package/extensions/memory/commands.ts

@@ -10,12 +10,10 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { withPolledScreen } from "../../lib/screen-session.ts";
 import { messageOf } from "./errors.ts";
 import { formatHealth, memoryHealth } from "./doctor.ts";
 import { formatNotice, scopeLabel } from "./format.ts";
 import type { MemoryRuntime } from "./runtime.ts";
-import { MemoryPickerComponent } from "./tui.ts";
 import { MEMORY_SCOPES, type MemoryScope } from "./types.ts";
 
 /** How often the open picker re-checks the stores for an external edit. */
@@ -55,6 +53,10 @@ async function openPicker(pi: ExtensionAPI, runtime: MemoryRuntime, ctx: Extensi
 		return;
 	}
 
+	// The dock screen and its poll loop are the TUI's: the plain listing above and
+	// registration load neither.
+	const { withPolledScreen } = await import("../../lib/screen-session.ts");
+	const { MemoryPickerComponent } = await import("./view/memory-picker.ts");
 	await withPolledScreen(
 		pi,
 		ctx,

package/extensions/memory/{tui.ts → view/memory-picker.ts}

@@ -25,17 +25,17 @@ import {
 	type TuiMouseEvent,
 	type TuiMouseEventResult,
 } from "@earendil-works/pi-tui";
-import { sanitizeLine } from "../../lib/format.ts";
-import { ConfirmState } from "../../lib/tui/confirm.ts";
-import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../lib/tui/cursor.ts";
-import { dockListFrame, editorTheme, 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 { messageOf } from "./errors.ts";
-import { scopeLabel, type MemoryEntries } from "./format.ts";
-import type { MemoryScope } from "./types.ts";
+import { sanitizeLine } from "../../../lib/format.ts";
+import { ConfirmState } from "../../../lib/tui/confirm.ts";
+import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../../lib/tui/cursor.ts";
+import { dockListFrame, editorTheme, 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 { messageOf } from "../errors.ts";
+import { scopeLabel, type MemoryEntries } from "../format.ts";
+import type { MemoryScope } from "../types.ts";
 
 /** Note limit enforced by the `memory` tool; the picker mirrors it so a save is never rejected late. */
 const MAX_NOTE_CHARS = 500;
@@ -521,7 +521,7 @@ export class MemoryPickerComponent implements Component {
 							"Esc close",
 							{ text: "Enter/e edit", color: "accent" },
 							{ text: "a add", color: "accent" },
-							{ text: "d forget", color: "warning" },
+							{ text: "d forget", color: "warn" },
 							"m merge",
 							"p move",
 							"s/Tab scope",

package/extensions/plan/commands.ts

@@ -2,7 +2,7 @@
  * Slash command for the plan-mode extension.
  *
  * `/plan` toggles plan mode, or enters it and sends an optional task;
- * `Ctrl+Alt+P` toggles too. Four subcommands are reserved: `/plan review [path]`
+ * Shift+Tab toggles too, through bytefly's editor. Four subcommands are reserved: `/plan review [path]`
  * opens a plan in the browser (and sends saved comments to the model as a
  * refinement), `/plan share [stop]` prints or revokes the link a teammate opens,
  * `/plan list` shows the plans directory, newest first with Enter opening a
@@ -15,11 +15,11 @@ import { READ_ONLY_SUMMARY } from "../../lib/plan-entry.ts";
 import { qrLines } from "../../lib/qr.ts";
 import { withRailsSuppressed } from "../../lib/rails.ts";
 import { feedbackSummary } from "./feedback.ts";
-import { PlanIndexComponent, formatPlanIndex } from "./plan-index.ts";
-import { runBrowserReview } from "./review.ts";
+import { runBrowserReview } from "./review-lazy.ts";
 import type { PlanRuntime } from "./runtime.ts";
 import type { PlanSummary } from "./plans.ts";
-import { createPlanWebReview, NO_SERVER_DEPS, type PlanWebReview } from "./web.ts";
+import { createLazyPlanWebReview, NO_SERVER_DEPS } from "./web-lazy.ts";
+import type { PlanWebReview } from "./web.ts";
 
 const ENABLED_NOTICE = `Plan mode enabled — ${READ_ONLY_SUMMARY}.`;
 const DISABLED_NOTICE = "Plan mode disabled — full access restored.";
@@ -28,7 +28,7 @@ const SHARE_PREFIX = "share";
 const LIST_PREFIX = "list";
 const CANCEL_PREFIX = "cancel";
 
-/** Notice text for the current mode; shared by `/plan` and the `Ctrl+Alt+P` shortcut. */
+/** Notice text for the current mode; shared by `/plan` and the toggle request. */
 export function planModeNotice(enabled: boolean): string {
 	return enabled ? ENABLED_NOTICE : DISABLED_NOTICE;
 }
@@ -126,7 +126,8 @@ async function reviewInBrowser(
 	const file = path ? await runtime.plans.read(ctx.cwd, path) : await runtime.plans.latest(ctx.cwd);
 	if (!file) {
 		if (path) ctx.ui.notify(`Plan review: no plan file at ${path}`, "error");
-		else ctx.ui.notify("Plan review: no plan to review; write one with write_plan or pass a path.", "warning");
+		else
+			ctx.ui.notify("Plan review: no plan to review; write one with `plan` action `write` or pass a path.", "warning");
 		return;
 	}
 	// The server is loopback-only, so a remote turn cannot drive it.
@@ -161,7 +162,7 @@ async function reviewInBrowser(
 		return;
 	}
 	const message = runtime.isEnabled()
-		? `The user reviewed the plan ${result.plan.relativePath} in the browser and left feedback:\n${summary}\nStay in plan mode, revise the plan (write_plan, reusing plan_path), then call exit_plan_mode again.`
+		? `The user reviewed the plan ${result.plan.relativePath} in the browser and left feedback:\n${summary}\nStay in plan mode, revise the plan (\`plan\` action \`write\`, reusing plan_path), then call \`plan\` action \`exit\` again.`
 		: `The user reviewed the plan ${result.plan.relativePath} in the browser and left feedback:\n${summary}\nUpdate the plan file to address the feedback.`;
 	if (ctx.isIdle()) await pi.sendUserMessage(message);
 	else await pi.sendUserMessage(message, { deliverAs: "followUp" });
@@ -187,6 +188,7 @@ async function openPlanIndex(
 	const summaries = await summarise();
 
 	if (ctx.mode !== "tui") {
+		const { formatPlanIndex } = await import("./plan-index.ts");
 		ctx.ui.notify(formatPlanIndex(summaries, dir), "info");
 		return;
 	}
@@ -195,6 +197,7 @@ async function openPlanIndex(
 	let selected: (PlanSummary | undefined) | undefined;
 	// A dock list shares the editor slot with the goal and todo rails, so it takes
 	// the dock to itself for as long as it is open, like the other list screens.
+	const { PlanIndexComponent } = await import("./plan-index.ts");
 	await withRailsSuppressed(pi, () =>
 		ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
 			const component = new PlanIndexComponent({
@@ -219,7 +222,7 @@ async function openPlanIndex(
 export function registerCommands(
 	pi: ExtensionAPI,
 	runtime: PlanRuntime,
-	web: PlanWebReview = createPlanWebReview(runtime.plans, NO_SERVER_DEPS),
+	web: PlanWebReview = createLazyPlanWebReview(runtime.plans, NO_SERVER_DEPS),
 ): void {
 	pi.registerCommand("plan", {
 		description:
@@ -259,7 +262,7 @@ export function registerCommands(
 				return;
 			}
 
-			// No task: toggle, exactly like Ctrl+Alt+P.
+			// No task: toggle, exactly like Shift+Tab.
 			if (!prompt) {
 				runtime.toggle(ctx);
 				ctx.ui.notify(planModeNotice(runtime.isEnabled()), "info");

package/extensions/plan/format.ts

@@ -5,10 +5,16 @@
  * the cap diagnosis, the preview, and the merge summary in one place.
  */
 
-import { SET_PLAN_STEPS_TOOL } from "./runtime.ts";
 import { MAX_STEP_LENGTH, MAX_STEPS, type PlanStep, type StepUpdate } from "./steps.ts";
 import type { TodoMerge } from "./todos.ts";
 
+/**
+ * How every message names the tick-off call. One spelling, because the tool is now
+ * one verb among five and a message that still spelled the old name would teach the
+ * model a tool that no longer exists.
+ */
+export const TICK_CALL = "`plan` action `steps`";
+
 /** Lines of plan shown in an unexpanded result. */
 const PREVIEW_LINES = 8;
 
@@ -80,7 +86,7 @@ export function mergeSummary(merged: TodoMerge, steps: PlanStep[]): string {
 		merged.deferred > 0 ? `${merged.deferred} deferred, list full` : "",
 	].filter(Boolean);
 	const suffix = notes.length > 0 ? ` (${notes.join(", ")})` : "";
-	const tick = `Tick each one off in the file with ${SET_PLAN_STEPS_TOOL} as you finish it, passing the step's text as \`expected\`.`;
+	const tick = `Tick each one off in the file with ${TICK_CALL} as you finish it, passing the step's text as \`expected\`.`;
 	const touched =
 		merged.stale > 0
 			? ` ${merged.stale} older item${merged.stale === 1 ? "" : "s"} no longer match${merged.stale === 1 ? "es" : ""} this plan but ${merged.stale === 1 ? "was" : "were"} left alone: ${merged.stale === 1 ? "it was" : "they were"} started or finished, so check ${merged.stale === 1 ? "it" : "them"} yourself.`