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

package/lib/http/serve.ts

@@ -1,16 +1,21 @@
 /**
- * One loopback server per served surface: bind, accept, route, stream, idle,
- * close.
+ * The one loopback server a session serves its pages on: bind once, dispatch by
+ * mount, stream, idle, close.
  *
- * Both browser surfaces build the same socket around `lib/http`'s pieces, so the
- * socket lives here: an extension supplies a handler that turns one request into
- * one reply, and this module owns everything the request does not decide — the
- * body cap, `HEAD` of a stream, the event-stream head, the port retry, the idle
- * grace, and a close that is safe to call twice.
+ * A session has one port, so the socket cannot belong to a page. A page *mounts* a
+ * path prefix on it — `/board`, `/files`, `/plan/<id>` — and the server owns
+ * everything a request does not decide: the longest-prefix dispatch, the body cap
+ * of whichever mount was reached, `HEAD` of a stream, the event-stream head, the
+ * port retry, and a close that is safe to call twice. A mount's handler is handed
+ * the request target *relative to its own prefix*, so a router keeps matching the
+ * paths it always matched.
  *
- * The `Host` rule stays with each router: the allowlist is per extension, and for
- * a shared review it grows while the server is up, so it cannot be passed in
- * once.
+ * The idle grace is per mount, not per socket: one page going quiet must not close
+ * another's, so a mount carries its own open-stream registry and release, and the
+ * socket closes when its last mount leaves.
+ *
+ * The `Host` rule stays with each router: the allowlist is per extension, and for a
+ * shared review it grows while the server is up, so it cannot be passed in once.
  *
  * Value-only: the only state is what a returned closure carries.
  */
@@ -25,6 +30,7 @@ import {
 import type { ArmTimer } from "../timer.ts";
 import { jsonHeaders } from "./headers.ts";
 import { type ServeResponse, textResponse } from "./response.ts";
+import { parseRequestUrl } from "./router.ts";
 import { bindHost, createCloser, openEventStream, respond } from "./server.ts";
 import { createSinks, type EventSink, type IdleGrace, type SinkRegistry } from "./sink.ts";
 
@@ -32,7 +38,7 @@ import { createSinks, type EventSink, type IdleGrace, type SinkRegistry } from "
 export interface LoopbackRequest {
 	/** Upper-cased method, e.g. `GET`. */
 	method: string;
-	/** The request target, path and query. */
+	/** The request target, path and query, relative to the mount's prefix. */
 	url: string;
 	/** Headers exactly as the socket carried them; the router applies its `Host` rule. */
 	headers: IncomingHttpHeaders;
@@ -57,35 +63,67 @@ export interface LoopbackReply {
 /** One request in, one reply out. A throw is answered as a plain 500. */
 export type LoopbackHandler = (request: LoopbackRequest) => Promise<LoopbackReply> | LoopbackReply;
 
-export interface LoopbackOptions {
-	/** The address to bind; defaults to `127.0.0.1`. */
-	host?: string;
-	/** Ports tried in order, so a remembered port can fall back to an OS-chosen one. */
-	ports: readonly number[];
+/** One page's claim on a path prefix. */
+export interface ServedMount {
+	/** The prefix it answers under: `/board`, or `""` for the whole origin. */
+	prefix: string;
 	handler: LoopbackHandler;
-	/** Largest body accepted; absent, no body is read and a route sees `""`. */
+	/** Largest body accepted here; absent, no body is read and a route sees `""`. */
 	maxBodyBytes?: number;
-	/** Grace after the last event stream leaves; omitted, the server waits for `close()`. */
+	/** Grace after this mount's last stream leaves; omitted, it waits for `release()`. */
 	idle?: IdleGrace;
-	/** The timer the idle grace is armed on. */
+	/** The timer this mount's idle grace is armed on. */
 	timer?: ArmTimer;
 }
 
-/** A bound loopback server. */
-export interface LoopbackServer {
+/** A prefix served on a running server. */
+export interface Mount {
+	/** The normalized prefix, e.g. `/board`. */
+	base: string;
+	/** The port the server bound. */
+	port: number;
+	/** `http://<host>:<port>`, the address this mount is reached on. */
+	origin: string;
+	/**
+	 * End this mount's streams and free its prefix. Idempotent, and the server closes
+	 * with its last mount.
+	 */
+	release(): Promise<void>;
+}
+
+export interface ServeOptions {
+	/** The address to bind; defaults to `127.0.0.1`. */
+	host?: string;
+	/** Ports tried in order, so a remembered port can fall back to an OS-chosen one. */
+	ports: readonly number[];
+}
+
+/** A bound server, before any page has mounted on it. */
+export interface ServedServer {
 	/** The port it actually bound. */
 	port: number;
 	/** `http://<host>:<port>`, the address the caller prints. */
 	origin: string;
 	/**
-	 * End every open stream, stop the idle grace, and close the socket. Idempotent.
-	 *
-	 * A last frame is the caller's to send before it calls this: closing is not a
-	 * conclusion, and only the route knows what its readers were waiting for.
+	 * Add one prefix. `undefined` means the prefix is already taken, which a caller
+	 * reports rather than lets two pages answer as one.
+	 */
+	mount(spec: ServedMount): Mount | undefined;
+	/**
+	 * End every mount's streams and close the socket. Idempotent, and what the last
+	 * mount's release does on its own.
 	 */
 	close(): Promise<void>;
 }
 
+/** One prefix as the server holds it: its spec, its streams, and its mount handle. */
+interface Route {
+	spec: ServedMount;
+	base: string;
+	sinks: SinkRegistry;
+	mount: Mount;
+}
+
 /** The one refusal this layer answers itself: a body it will not read. */
 const BODY_TOO_LARGE: ServeResponse = {
 	status: 413,
@@ -99,6 +137,10 @@ const STREAM_WITHOUT_SINK: ServeResponse = textResponse(500, "Internal error");
 /** A handler that threw, or a socket that failed after its head was written. */
 const INTERNAL_ERROR: ServeResponse = textResponse(500, "Internal error");
 
+/** A prefix no mount claims, and a target no URL parser accepts. */
+const NOT_FOUND: ServeResponse = textResponse(404, "Nothing is served at this path.");
+const MALFORMED: ServeResponse = textResponse(400, "Malformed request URL.");
+
 /**
  * Bind the first port that answers, falling back in order. Rejects with the last
  * bind error, so a caller can still name the reason (`EADDRINUSE` and friends).
@@ -115,6 +157,31 @@ async function bindFirst(server: Server, host: string, ports: readonly number[])
 	throw failure instanceof Error ? failure : new Error(`could not bind ${host}`);
 }
 
+/** One prefix, spelled the way dispatch compares it: no trailing slash, a leading one. */
+function normalizeBase(prefix: string): string {
+	const trimmed = prefix.replace(/\/+$/, "");
+	if (trimmed === "" || trimmed === "/") return "";
+	return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+/** Whether `base` is a prefix of `pathname` at a segment boundary; `""` covers everything. */
+function prefixCovers(base: string, pathname: string): boolean {
+	return base === "" || pathname === base || pathname.startsWith(`${base}/`);
+}
+
+/**
+ * The mount a path belongs to: the longest prefix that covers it, so `/plan/a` wins
+ * over a bare `/plan` and a root mount is the fallback rather than the rival.
+ */
+function routeFor(routes: Map<string, Route>, pathname: string): Route | undefined {
+	let best: Route | undefined;
+	for (const route of routes.values()) {
+		if (!prefixCovers(route.base, pathname)) continue;
+		if (best === undefined || route.base.length > best.base.length) best = route;
+	}
+	return best;
+}
+
 /**
  * Read a request body, stopping at `limit`. An oversize body is reported rather
  * than destroyed, so it can still be answered 413 over the open socket instead of
@@ -157,22 +224,45 @@ function once(fn: (() => void) | undefined): (() => void) | undefined {
 	};
 }
 
-/** Route one request: read, dispatch, then answer, stream, or refuse. */
+/**
+ * Route one request: pick the mount, read, dispatch, then answer, stream, or refuse.
+ *
+ * A request that names a prefix without its slash is redirected to the slashed form,
+ * because a page's own links are relative to its directory and `/board` is not one.
+ */
 async function answer(
 	request: IncomingMessage,
 	response: ServerResponse,
-	options: LoopbackOptions,
-	sinks: SinkRegistry,
+	routes: Map<string, Route>,
+	redirect: (to: string) => ServeResponse,
 ): Promise<void> {
 	const method = request.method ?? "GET";
-	const body = options.maxBodyBytes === undefined ? "" : await readBody(request, options.maxBodyBytes);
+	const target = request.url ?? "/";
+	const parsed = parseRequestUrl(target);
+	if (!parsed) {
+		respond(request, response, MALFORMED);
+		return;
+	}
+	const route = routeFor(routes, parsed.pathname);
+	if (route === undefined) {
+		respond(request, response, NOT_FOUND);
+		return;
+	}
+	if (route.base !== "" && parsed.pathname === route.base) {
+		respond(request, response, redirect(`${route.base}/${parsed.search.toString() === "" ? "" : `?${parsed.search}`}`));
+		return;
+	}
+	const rest = target.slice(route.base.length);
+	const url = rest === "" ? "/" : rest.startsWith("?") ? `/${rest}` : rest;
+	const limit = route.spec.maxBodyBytes;
+	const body = limit === undefined ? "" : await readBody(request, limit);
 	if (body === undefined) {
 		respond(request, response, BODY_TOO_LARGE);
 		return;
 	}
 	let reply: LoopbackReply;
 	try {
-		reply = await options.handler({ method, url: request.url ?? "/", headers: request.headers, body });
+		reply = await route.spec.handler({ method, url, headers: request.headers, body });
 	} catch {
 		reply = { result: INTERNAL_ERROR };
 	}
@@ -186,7 +276,7 @@ async function answer(
 	// the client would otherwise wait on frames it asked not to get.
 	if (reply.openSink !== undefined && method.toUpperCase() !== "HEAD") {
 		openEventStream(response, reply.result);
-		const sink = sinks.open(response);
+		const sink = route.sinks.open(response);
 		const detach = reply.openSink(sink);
 		let closed = false;
 		const finish = (): void => {
@@ -205,33 +295,67 @@ async function answer(
 }
 
 /** Start a server on the first port that binds, and close it idempotently. */
-export async function serveLoopback(options: LoopbackOptions): Promise<LoopbackServer> {
+export async function serveHttp(options: ServeOptions): Promise<ServedServer> {
 	const host = options.host ?? "127.0.0.1";
-	const sinks = createSinks({ idle: options.idle, timer: options.timer });
+	const routes = new Map<string, Route>();
+	let closed = false;
+	let closeServer: (() => Promise<void>) | undefined;
+
+	const close = async (): Promise<void> => {
+		if (closed) return;
+		closed = true;
+		// Streams end first: a connected page must not hold the close open.
+		const open = [...routes.values()];
+		routes.clear();
+		for (const route of open) route.sinks.endAll();
+		await closeServer?.();
+	};
+
 	const server = createServer((request, response) => {
 		// A page that walks away mid-frame must not take the session down.
 		response.on("error", () => {});
-		void answer(request, response, options, sinks).catch(() => {
+		void answer(request, response, routes, (to) => ({
+			status: 301,
+			headers: { ...jsonHeaders(), Location: to },
+			body: "",
+		})).catch(() => {
 			// A route that failed after its head was written can only be cut off; ending
 			// the socket beats a client waiting on a reply that will not come.
 			if (!response.writableEnded) response.end();
 		});
 	});
 	const port = await bindFirst(server, host, options.ports);
-	// The socket is bound but no page may ever read it: a server that asked for a first
-	// grace arms it here, so a browser that never came up cannot hold the port all session.
-	sinks.start();
-	const closeServer = createCloser(server);
-	let closed = false;
+	closeServer = createCloser(server);
+	const origin = `http://${host}:${port}`;
+
 	return {
 		port,
-		origin: `http://${host}:${port}`,
-		close: async () => {
-			if (closed) return;
-			closed = true;
-			// Streams end first: a connected page must not hold the close open.
-			sinks.endAll();
-			await closeServer();
+		origin,
+		mount(spec) {
+			const base = normalizeBase(spec.prefix);
+			if (routes.has(base)) return undefined;
+			const sinks = createSinks({ idle: spec.idle, timer: spec.timer });
+			const route: Route = {
+				spec: { ...spec, prefix: base },
+				base,
+				sinks,
+				mount: {
+					base,
+					port,
+					origin,
+					release: async () => {
+						if (!routes.delete(base)) return;
+						sinks.endAll();
+						if (routes.size === 0) await close();
+					},
+				},
+			};
+			routes.set(base, route);
+			// A mount that asked for a first grace arms it here, so a browser that never
+			// came up cannot hold the prefix for the rest of the session.
+			sinks.start();
+			return route.mount;
 		},
+		close,
 	};
 }

package/lib/http/server.ts

@@ -1,9 +1,9 @@
 /**
- * The socket primitives `serveLoopback` is built from: bind, write a response
- * out, and close.
+ * The socket primitives `serveHttp` is built from: bind, write a response out, and
+ * close.
  *
  * Internal to the layer: an extension starts a server through
- * `serveLoopback`, which composes these, so this module is reached from `lib/http`
+ * `serveHttp`, which composes these, so this module is reached from `lib/http`
  * and its own suite — not from the barrel. Everything here is behavior a caller
  * cannot get right by accident: a bind on an address the caller names (loopback
  * unless it asked for more), an accept-level `error` listener so a transient

package/lib/lazy.ts

@@ -0,0 +1,45 @@
+/**
+ * One async load, run at most once.
+ *
+ * A surface a command needs but registration does not — a browser page, a
+ * review server, a screen — is imported through this: `get()` runs the loader
+ * and remembers the value, and `peek()` answers the value already loaded, or
+ * `undefined`, so a shutdown path never starts a load the session never used.
+ *
+ * A rejected load is not remembered. A transient failure can be retried, and a
+ * caller that sees the error can ask again; the alternative would make one bad
+ * import permanent for the process.
+ *
+ * State lives in this closure, not at module scope, because `lib/` is loaded
+ * with isolated module caches and is value-only.
+ */
+
+/** A value loaded on first use, with a way to ask whether it is already here. */
+export interface Lazy<T> {
+	/** Load the value, or return the one already loaded; concurrent calls share one load. */
+	get(): Promise<T>;
+	/** The loaded value, or `undefined` before a load and after a failed one. */
+	peek(): T | undefined;
+}
+
+export function lazy<T>(load: () => Promise<T>): Lazy<T> {
+	let loaded = false;
+	let value: T;
+	let pending: Promise<T> | undefined;
+	const get = (): Promise<T> => {
+		if (loaded) return Promise.resolve(value);
+		pending ??= load().then(
+			(result) => {
+				loaded = true;
+				value = result;
+				return result;
+			},
+			(error: unknown) => {
+				pending = undefined;
+				throw error;
+			},
+		);
+		return pending;
+	};
+	return { get, peek: () => (loaded ? value : undefined) };
+}

package/lib/plan-entry.ts

@@ -16,21 +16,26 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type BusAnswer, requestOverBus } from "./bus-request.ts";
 import { isPlanModeEnabled } from "./plan-state.ts";
-import { PLAN_ENTER_TOOL } from "./tool-names.ts";
+import { PLAN_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";
 
+/** EventBus channel on which a caller asks `plan` to flip the mode. */
+export const PLAN_TOGGLE_REQUEST = "my-pi-agent/plan-mode/toggle";
+
 /** 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 (a plan file in the agent " +
-	"directory)";
+	"subagent delegation is forced read-only, and the only file write is the plan file, saved by the `plan` tool's " +
+	"`write` action in the agent directory";
 
 /**
- * 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.
+ * The consent question, as the user sees it. Shown by the `plan` tool's `enter`
+ * action 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}. ` +
@@ -52,12 +57,19 @@ export function planModeRefusal(action: string): string {
 	return `Plan mode is read-only. Approve the plan before ${action}.`;
 }
 
-/** What a caller sends on {@link PLAN_ENTER_REQUEST}. */
-export interface PlanEnterRequest {
+/** What a caller sends on {@link PLAN_ENTER_REQUEST} or {@link PLAN_TOGGLE_REQUEST}. */
+export interface PlanModeRequest {
 	/** 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;
+	/** Claimed once, with whether plan mode is on; the caller settles on that claim. */
+	respond(enabled: BusAnswer<boolean>): void;
+}
+
+/**
+ * Whether the `plan` extension registered its tool in this session.
+ */
+export function isPlanExtensionLoaded(pi: Pick<ExtensionAPI, "getAllTools">): boolean {
+	return pi.getAllTools().some((tool) => tool.name === PLAN_TOOL);
 }
 
 /**
@@ -65,23 +77,36 @@ export interface PlanEnterRequest {
  *
  * 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.
+ * working and nothing waits on a listener that is not there. The listener claims
+ * synchronously; the shared handshake is what guarantees a 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));
+	if (!isPlanExtensionLoaded(pi)) return Promise.resolve(false);
+	return requestOverBus<boolean, PlanModeRequest>(pi, {
+		channel: PLAN_ENTER_REQUEST,
+		payload: (respond) => ({ ctx, respond }),
+		unclaimed: () => false,
+	});
+}
+
+/**
+ * Ask `plan` to flip the mode, and report the state it left behind.
+ *
+ * A toggle has no branch precondition: the owner reads the flag it persisted and
+ * resolves the opposite. `undefined` means nothing is listening (the `plan`
+ * extension is not loaded), so the caller can leave its own key alone.
+ */
+export function requestPlanToggle(
+	pi: Pick<ExtensionAPI, "events">,
+	ctx: ExtensionContext,
+): Promise<boolean | undefined> {
+	return requestOverBus<boolean | undefined, PlanModeRequest>(pi, {
+		channel: PLAN_TOGGLE_REQUEST,
+		payload: (respond) => ({ ctx, respond }),
+		unclaimed: () => undefined,
 	});
 }

package/lib/plans/paths.ts

@@ -0,0 +1,82 @@
+/**
+ * Where a plan lives, and which paths may be read or written as one.
+ *
+ * A plan file is the artifact a card is executed against, so two extensions have to
+ * agree about it: `plan` writes and reads the store, and `board` records the file a
+ * card promises. The store is `<agent-dir>/plans/<repo-key>` for a repository and
+ * `<agent-dir>/plans` outside one — the key is the same one `repo-key.ts` hands
+ * every other per-repository store, which is why the keyed branch lives here rather
+ * than in either caller.
+ *
+ * The rules are one body for the same reason: a copy of `isContainedPlan` that
+ * dropped the symlink half would look identical at a glance and would be the one
+ * that let a link inside the store point outside it. `plan` passes a path here
+ * before it writes; `board` passes the path it is about to record, and asks whether
+ * it is a plan of this repository.
+ *
+ * Value-only: no module state, and the only I/O is the `lstat` a symlink check needs.
+ */
+
+import { lstatSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { isInside, isInsideReal } from "../path.ts";
+import type { RepoKey } from "../repo-key.ts";
+
+/** The agent-directory entry plans are filed under. */
+export const PLANS_DIR_NAME = "plans";
+
+/** The plan store: `<agent-dir>/plans`, or `<agent-dir>/plans/<key>` inside a repository. */
+export function plansDir(agentDir: string, key?: string): string {
+	return key === undefined ? join(agentDir, PLANS_DIR_NAME) : join(agentDir, PLANS_DIR_NAME, key);
+}
+
+/**
+ * The store for a resolved repository: keyed when git answered, unkeyed outside one.
+ *
+ * The `fromGit` branch lives here and nowhere else — that is the line a copy gets wrong,
+ * and both the plan tool and the board reach it through this one function.
+ */
+export function plansDirFor(agentDir: string, repo: Pick<RepoKey, "key" | "fromGit">): string {
+	return plansDir(agentDir, repo.fromGit ? repo.key : undefined);
+}
+
+/** A plan file name: markdown and not a dotfile, so the self-ignore file is never a target. */
+export function isPlanFileName(path: string): boolean {
+	const name = basename(path);
+	return name.toLowerCase().endsWith(".md") && !name.startsWith(".");
+}
+
+/**
+ * Whether `path` may be read, written, or deleted as a plan. Beyond lexical
+ * containment (shared with the other path guards through `lib/path.ts`), this
+ * rejects dotfiles (including the directory's own `.gitignore`) and resolves
+ * symlinks, so a link placed inside the plans directory cannot redirect a read
+ * or write outside it.
+ */
+export function isContainedPlan(dir: string, path: string): boolean {
+	if (!isInside(dir, path) || !isPlanFileName(path)) return false;
+	try {
+		// A symlink itself must never be the target; a missing file is a new plan.
+		if (lstatSync(path).isSymbolicLink()) return false;
+	} catch {
+		// Missing (ENOENT) is expected; any other error falls through to the
+		// real-path check, which rejects the path if it cannot be resolved.
+	}
+	return isInsideReal(dir, dirname(path));
+}
+
+/**
+ * Resolve a `plan_path` argument against the store.
+ *
+ * A plan lives outside the project, so a path relative to the working directory
+ * can no longer name one. Absolute paths and the `~/…` form the tools display are
+ * accepted, and a bare name resolves inside the store — which is what a reader of
+ * a tool result has in hand.
+ */
+export function resolvePlanArg(dir: string, planPath: string): string {
+	const text = planPath.trim();
+	if (text === "~") return homedir();
+	if (text.startsWith("~/") || text.startsWith(`~${sep}`)) return resolve(homedir(), text.slice(2));
+	return isAbsolute(text) ? resolve(text) : resolve(dir, text);
+}

package/lib/policy.ts

@@ -10,24 +10,27 @@
  * `write`/`edit` being the only mutators.
  *
  * No host dependency beyond the annotation type: the caller supplies the
- * annotation lookup, and the one reader name comes from `tool-names.ts`, so this
- * module stays value-only.
+ * annotation lookup, the one reader name comes from `tool-names.ts`, and which board
+ * actions read comes from `board/actions.ts`, so this module stays value-only.
  */
 
 import type { ToolAnnotations } from "@earendil-works/pi-coding-agent";
-import { BOARD_READ_ACTION, READ_DOC_TOOL } from "./tool-names.ts";
+import { isBoardReadAction } from "./board/actions.ts";
+import { READ_DOC_TOOL } from "./tool-names.ts";
 
 /**
  * Whether a call to the `board` tool only reads it.
  *
- * The board is one tool over ten actions, so its `readOnlyHint` says "may write" and
+ * The board is one tool over many actions, so its `readOnlyHint` says "may write" and
  * cannot answer this. The action can, and it travels in the call's input — and in the
  * result's `details`, which is all a `tool_execution_end` event carries. Plan mode
- * asks before the call and the todo nudge after it, so the answer lives here once.
+ * asks before the call and the todo nudge after it, so the answer lives here once —
+ * and the answer is the board's own table, because an action list kept here is a list
+ * that drifts.
  */
 export function isBoardRead(call: unknown): boolean {
 	if (typeof call !== "object" || call === null) return false;
-	return (call as { action?: unknown }).action === BOARD_READ_ACTION;
+	return isBoardReadAction((call as { action?: unknown }).action);
 }
 
 /**

package/lib/report.ts

@@ -147,8 +147,9 @@ export interface PendingChannelOptions {
  * The order inside `session_start` is the contract: the reporter forgets the
  * previous session's busy window, the runtime loads the records, and only then
  * is the report trigger armed — a reload or a replaced session reuses the same
- * runtime. A shutdown clears the trigger before the runtime releases the table it
- * was calling into.
+ * runtime, so a runtime that can settle an outcome while loading holds what it
+ * settled until this arms. A shutdown clears the trigger before the runtime
+ * releases the table it was calling into.
  */
 export function registerPendingChannel(
 	pi: Pick<ExtensionAPI, "on">,