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

package/extensions/web-access/fetch/tool.ts

@@ -27,7 +27,7 @@ import { charLength } from "../text.ts";
 import { oneLine } from "../transcript.ts";
 import { createPageCache, type PageCache } from "./cache.ts";
 import type { WebFetchConfig } from "./config.ts";
-import { findPassages } from "./find.ts";
+import { findPassages, type Passage } from "./find.ts";
 import { formatMatches, formatPage } from "./format.ts";
 import { runFetch, type FetchDeps, type PageResult } from "./page.ts";
 import { resolveRequest, WebFetchOutput, WebFetchParams, type FetchResponse, type WebFetchArgs } from "./schema.ts";
@@ -85,29 +85,33 @@ async function loadPage(
 function pageResult(loaded: LoadedPage, request: FetchRequest): { response: FetchResponse; text: string } {
 	const { page, cached, fetchedAt } = loaded;
 	const finding = request.find.length > 0;
-	const matches = finding
-		? findPassages(page.text, request.find, {
-				mode: request.mode,
-				contextChars: request.contextChars,
-				maxMatches: request.maxMatches + 1,
-			})
-		: [];
-	// Request one extra so a full list proves more hits exist; only the cap is shown.
-	const matchesTruncated = finding && matches.length > request.maxMatches;
-	const visibleMatches = matchesTruncated ? matches.slice(0, request.maxMatches) : matches;
 
 	let formatted: { body: string; text: string; truncated: boolean };
 	let nextIndex: number;
+	let matches: Passage[] = [];
+	let matchesTruncated = false;
+
 	if (finding) {
-		formatted = formatMatches({
+		// Request one extra so a full list proves more hits exist; only the cap is shown.
+		const found = findPassages(page.text, request.find, {
+			mode: request.mode,
+			contextChars: request.contextChars,
+			maxMatches: request.maxMatches + 1,
+		});
+		const cappedByMaxMatches = found.length > request.maxMatches;
+		const rendered = formatMatches({
 			finalUrl: page.finalUrl,
 			title: page.title,
 			status: page.status,
 			contentType: page.contentType,
-			matches: visibleMatches,
+			matches: cappedByMaxMatches ? found.slice(0, request.maxMatches) : found,
 			find: request.find,
-			truncated: matchesTruncated,
+			maxChars: request.maxChars,
+			cappedByMaxMatches,
 		});
+		formatted = rendered;
+		matches = rendered.included;
+		matchesTruncated = rendered.truncated;
 		// Find results are not paged, so the caller keeps reading from the same offset.
 		nextIndex = request.startIndex;
 	} else {
@@ -136,7 +140,7 @@ function pageResult(loaded: LoadedPage, request: FetchRequest): { response: Fetc
 		nextIndex,
 		truncated: formatted.truncated,
 		cached,
-		matches: visibleMatches,
+		matches,
 		matchesTruncated,
 		fetchedAt,
 		error: "",
@@ -192,9 +196,6 @@ export function registerFetchTool(pi: ExtensionAPI, deps: FetchToolDeps = {}): v
 		parameters: WebFetchParams,
 		outputSchema: WebFetchOutput,
 		annotations: { readOnlyHint: true, openWorldHint: true },
-		// The page cache is shared in-memory state created per registration, so
-		// sibling calls must not run concurrently (matches web_search's throttle).
-		executionMode: "sequential",
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const config = loadFetchConfig(ctx.cwd);

package/extensions/web-access/http.ts

@@ -3,10 +3,12 @@
  *
  * No `curl`, no dependencies: one `fetch` call per request (with optional
  * manual redirect handling) with a combined caller-signal and timeout, optional
- * request body, and a size cap. `HttpRunner` is the seam tests use to avoid the
- * network.
+ * request body, and a size cap enforced while the body is read. `HttpRunner` is
+ * the seam tests use to avoid the network.
  */
 
+import { bomCharset, charsetOf, decodeBytes } from "./charset.ts";
+
 /** A request to send. */
 interface HttpRequest {
 	url: string;
@@ -15,7 +17,7 @@ interface HttpRequest {
 	/** Raw request body (for example a JSON-RPC payload). */
 	body?: string;
 	timeoutMs: number;
-	/** Maximum response size in bytes; larger responses raise `HttpTooLargeError`. */
+	/** Maximum response size in bytes, enforced while the body is read. */
 	maxBytes?: number;
 	/** Redirect handling: `"follow"` (default) or `"manual"` to inspect each hop. */
 	redirect?: "follow" | "manual";
@@ -63,6 +65,48 @@ export class HttpUnavailableError extends Error {
 	}
 }
 
+/**
+ * Concatenate chunks into one buffer. `total` is the caller's running byte count,
+ * so the allocation happens once rather than growing an array per chunk.
+ */
+function concatChunks(chunks: Uint8Array[], total: number): Uint8Array {
+	const merged = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		merged.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return merged;
+}
+
+/**
+ * Read a response body to completion, aborting the read as soon as it exceeds
+ * `maxBytes`. `response.arrayBuffer()` would buffer a whole chunked or
+ * compressed response first, which is the case the cap exists to prevent.
+ */
+async function readCappedBody(response: Response, maxBytes?: number): Promise<Uint8Array> {
+	if (!response.body) {
+		const bytes = new Uint8Array(await response.arrayBuffer());
+		if (maxBytes !== undefined && bytes.byteLength > maxBytes) throw new HttpTooLargeError(maxBytes);
+		return bytes;
+	}
+
+	const reader = response.body.getReader();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (maxBytes !== undefined && total > maxBytes) {
+			await reader.cancel().catch(() => undefined);
+			throw new HttpTooLargeError(maxBytes);
+		}
+		chunks.push(value);
+	}
+	return concatChunks(chunks, total);
+}
+
 /**
  * Create a runner backed by `fetch`.
  *
@@ -103,11 +147,8 @@ export function createFetchRunner(fetchImpl: typeof fetch = globalThis.fetch): H
 				throw new HttpTooLargeError(request.maxBytes);
 			}
 
-			const bytes = new Uint8Array(await response.arrayBuffer());
-			if (request.maxBytes !== undefined && bytes.byteLength > request.maxBytes) {
-				throw new HttpTooLargeError(request.maxBytes);
-			}
-			const body = new TextDecoder().decode(bytes);
+			const bytes = await readCappedBody(response, request.maxBytes);
+			const body = decodeBytes(bytes, bomCharset(bytes) ?? charsetOf(contentType));
 			const location = response.headers.get("location") ?? undefined;
 
 			return {

package/extensions/web-access/search/facts.ts

@@ -0,0 +1,38 @@
+/**
+ * What `web_search` resolved to, published for `doctor`.
+ *
+ * The provider registry, each provider's `isConfigured`, and the `auto`
+ * resolution rule all live in this extension, so this module is where the facts
+ * for a diagnostic come from. It publishes a summary only — the key itself never
+ * leaves the extension, just the variable name and whether a literal key exists.
+ *
+ * `endpoint` is deliberately null for the providers without a configurable
+ * endpoint: probing an API host would report a 401 as a failure for a provider
+ * that works, and there is nothing for the user to fix.
+ */
+
+import type { WebSearchProviderEvent } from "../../../lib/events.ts";
+import type { WebSearchConfig } from "./config.ts";
+import { DEFAULT_PROVIDER_ID, resolveProvider } from "./registry.ts";
+
+/**
+ * The facts for one session's config. `reason` distinguishes an explicit choice
+ * from the auto rule, so a report can tell "you asked for this and it is not
+ * configured" from "this is the keyless fallback".
+ */
+export function providerFacts(config: WebSearchConfig): WebSearchProviderEvent {
+	const provider = resolveProvider(config);
+	// `auto` only leaves the keyless default when another provider is configured,
+	// so the resolved id tells the two apart.
+	const reason: WebSearchProviderEvent["reason"] =
+		config.provider !== "auto" ? "explicit" : provider.id === DEFAULT_PROVIDER_ID ? "default" : "configured";
+	return {
+		provider: provider.id,
+		reason,
+		configured: provider.isConfigured(config),
+		// Only SearXNG's base URL is a setting a user can get wrong.
+		endpoint: provider.id === "searxng" && config.endpoint !== "" ? config.endpoint : null,
+		apiKeyEnv: config.apiKeyEnv || null,
+		keyConfigured: config.apiKey.trim() !== "",
+	};
+}

package/extensions/web-access/search/tool.ts

@@ -8,6 +8,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { WEB_SEARCH_PROVIDER_CHANNEL } from "../../../lib/events.ts";
 import { loadSearchConfig } from "../config.ts";
 import { oneLine } from "../transcript.ts";
 import { reuseText } from "../../../lib/tui/chrome.ts";
@@ -21,6 +22,7 @@ import {
 } from "../../../lib/tui/tool.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { expandHint, SEPARATORS } from "../../../lib/tui/glyphs.ts";
+import { providerFacts } from "./facts.ts";
 import { formatResults } from "./format.ts";
 import { createThrottle, runSearch, type SearchDeps } from "./search.ts";
 import { resolveRequest, WebSearchOutput, WebSearchParams, type SearchResponse, type WebSearchArgs } from "./schema.ts";
@@ -32,6 +34,17 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 	// without any module-level state.
 	const runDeps: SearchDeps = { http: deps.http, throttle: deps.throttle ?? createThrottle() };
 
+	// Publish what this session resolved to, so `doctor` can report the provider,
+	// its key, and its endpoint without importing this extension. Accounting only:
+	// a bus listener that throws must not break the tool.
+	pi.on("session_start", (_event, ctx) => {
+		try {
+			pi.events.emit(WEB_SEARCH_PROVIDER_CHANNEL, providerFacts(loadSearchConfig(ctx.cwd)));
+		} catch {
+			// Diagnostics are best-effort.
+		}
+	});
+
 	pi.registerTool({
 		name: TOOL_NAME,
 		label: "Web search",

package/extensions/web-access/text.ts

@@ -3,24 +3,63 @@
  *
  * Character budgets are counted in code points, not UTF-16 units, so a slice
  * never splits a CJK character or an emoji, and a declared limit is honoured for
- * the text the model sees. `web_search` and `web_fetch` measure and slice here
- * rather than re-deriving `Array.from` at each site.
+ * the text the model sees. Everything here walks the string in place: a
+ * multi-megabyte page is never materialised as an array of one-character
+ * strings, which is what `Array.from(text)` would cost on every call.
  */
 
-/** Split text into code points (an array of one-code-point strings). */
-export function toChars(text: string): string[] {
-	return Array.from(text);
-}
+const SURROGATE = /[\uD800-\uDFFF]/;
 
 /** Length of text in code points. */
 export function charLength(text: string): number {
-	return Array.from(text).length;
+	// A native scan with no allocation covers the common all-BMP page.
+	if (!SURROGATE.test(text)) return text.length;
+
+	let count = 0;
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		if (code >= 0xd800 && code <= 0xdbff) {
+			const next = text.charCodeAt(i + 1);
+			if (next >= 0xdc00 && next <= 0xdfff) i++;
+		}
+		count++;
+	}
+	return count;
+}
+
+/**
+ * Slice text by code-point offsets, like `Array.from(text).slice(from, to).join("")`
+ * without building the array. Out-of-range offsets clamp, and `to` defaults to
+ * the end of the string.
+ */
+export function sliceChars(text: string, from: number, to: number = Number.POSITIVE_INFINITY): string {
+	const start = Math.max(0, Math.floor(from));
+	const end = Math.max(start, Math.floor(to));
+	if (start === 0 && end >= text.length) return text;
+
+	let startIndex = text.length;
+	let endIndex = text.length;
+	let codePoint = 0;
+	for (let i = 0; i < text.length; i++) {
+		if (codePoint === start && startIndex === text.length) startIndex = i;
+		if (codePoint === end) {
+			endIndex = i;
+			break;
+		}
+		const code = text.charCodeAt(i);
+		if (code >= 0xd800 && code <= 0xdbff) {
+			const next = text.charCodeAt(i + 1);
+			if (next >= 0xdc00 && next <= 0xdfff) i++;
+		}
+		codePoint++;
+	}
+	return text.slice(startIndex, endIndex);
 }
 
 /** Truncate to `maxChars` code points, appending `marker` when anything was cut. */
 export function truncateChars(text: string, maxChars: number, marker = "…"): string {
-	const points = toChars(text);
-	if (points.length <= maxChars) return text;
-	if (maxChars <= marker.length) return marker;
-	return `${points.slice(0, maxChars - marker.length).join("")}${marker}`;
+	if (charLength(text) <= maxChars) return text;
+	const markerLength = charLength(marker);
+	if (maxChars <= markerLength) return marker;
+	return `${sliceChars(text, 0, maxChars - markerLength)}${marker}`;
 }

package/extensions/worktree/README.md

@@ -23,11 +23,16 @@ How the `list_worktrees` call and its result look in the transcript — the call
 ## What it does
 
 - `enter_worktree` creates `<repo>/.pi/worktrees/<name>` on branch
-  `worktree-<name>` (or enters an existing worktree by `path`) and rebinds the
-  session's working root to it.
+  `worktree-<name>` cut from `origin/main` (which can lag the local `main`), or
+  enters an existing worktree by `path`, and rebinds the session's working root
+  to it.
 - `exit_worktree` returns to the main checkout. A clean worktree is removed
   automatically; one with uncommitted changes or new commits prompts (or is
-  kept in non-interactive mode). A branch that still holds work (uncommitted
+  kept in non-interactive mode). Its result ends with a **handoff**: the branch,
+  how many commits it holds beyond the merge target, whether that target already
+  contains them, and the `git merge --no-ff` and `gh pr create` commands that
+  finish the task. The tool never commits, merges, pushes, or opens the PR. A
+  branch that still holds work (uncommitted
   changes, or commits not reachable from the recorded base) is never
   force-deleted, even with `remove: true`.
 - While isolated, `read`/`write`/`edit`/`bash`/`grep`/`find`/`ls` all resolve
@@ -56,14 +61,32 @@ changes; a branch that still holds work is kept. Declining a confirmation
 (entering an outside path, exiting a worktree with work) is reported as normal
 feedback, not an error.
 
+`/worktree status` (and `list_worktrees`) reports the active worktree, any
+override that is not re-rooted, what isolation does not cover, and the managed
+worktrees:
+
+```text
+Not isolated:
+  ! shell       runs in the main checkout; Pi has no mutable session cwd
+  powershell    allowed by worktree.guard.blockPowershell: false; not re-rooted or guarded
+  unverifiable  $(...), backticks, eval, and sh -c pass through (blockUnparsableCommands is off); 2 ran this session
+```
+
+`powershell` appears only on Windows, with that tool active, and only when
+`guard.blockPowershell` lets it through — by default the guard refuses the call
+instead, so there is no gap to report. `unverifiable` appears only while
+`guard.blockUnparsableCommands` is off; its trailing count is this session's,
+reset at session start. `doctor` reports the `powershell` switch as `degraded`
+when it is off and notes the two structural gaps, which no setting closes.
+
 The model surface mirrors this with four tools:
 
 | Tool | Usage |
 |---|---|
 | `enter_worktree` | `name` to create a worktree, or `path` to enter an existing one. Errors if already isolated. |
-| `exit_worktree` | optional `remove` and `keepBranch`. Returns the clean/keep/remove decision. |
+| `exit_worktree` | optional `remove` and `keepBranch`. Returns the clean/keep/remove decision and a `handoff` (`branch`, `base`, `ahead`, `merged`). |
 | `prune_worktrees` | no parameters. Removes eligible managed worktrees and reports the rest. |
-| `list_worktrees` | no parameters. Read-only status: active root, inactive overrides, managed worktrees. |
+| `list_worktrees` | no parameters. Read-only status: active root, inactive overrides, isolation gaps, managed worktrees. |
 
 ## Configuration
 
@@ -87,7 +110,8 @@ The `worktree` section of the shared `bytefly.json` (global document, then
     "blockReadEscapes": false,
     "blockGitRedirects": true,
     "blockSymlinkEscapes": true,
-    "blockUnparsableCommands": false
+    "blockUnparsableCommands": false,
+    "blockPowershell": true
   }
 }
 ```
@@ -118,7 +142,8 @@ variable, `~user`, a backtick) is treated as escaping. File-descriptor
 duplications (`2>&1`, `>&-`), heredocs, and here-strings are not treated as
 paths, and options are only recognized in real argument position, so
 `git log --grep='--git-dir=/tmp/x'` and `git log -C` are not false positives.
-`GIT_DIR=`/`GIT_WORK_TREE=` are refused both as a command prefix and when
+The null device is exempt: `>/dev/null` and `< /dev/null` write and read nothing,
+so they are allowed. `GIT_DIR=`/`GIT_WORK_TREE=` are refused both as a command prefix and when
 exported (`export GIT_DIR=/main`), and a `sh -c`/`bash -c` sub-command is refused
 when `blockUnparsableCommands` is enabled.
 
@@ -126,6 +151,15 @@ This guard covers the built-in file tools and these common shell forms. It
 cannot contain a program that computes and writes an absolute path itself (for
 example a script or an inlined interpreter).
 
+Windows `powershell` is refused outright while the session is isolated rather
+than parsed. It is not one of the tools this extension re-roots, and its language
+is a second grammar — backtick escapes, `Set-Location`, `$env:GIT_DIR`, `--%` —
+so the bash checks would be guessing about a shell that starts in the main
+checkout. Refusing it is the same answer plan mode gives, and `bash` (re-rooted
+and guarded) stays available. `guard.blockPowershell: false` allows the tool
+again; that is a deliberate trade, so it is reported: `/worktree` lists the gap
+and `doctor` reports the switch as `degraded`.
+
 ## Gitignored files
 
 A worktree is a fresh checkout, so untracked, gitignored files such as `.env`
@@ -187,13 +221,22 @@ use, falling back to directory mtime for a worktree with no record.
   writes are guarded (relative paths are not isolated), and `list_worktrees`
   reports it. `skipOverrides` is read at load time, from the process working
   directory.
+- `git branch --merged main` calls a worktree branch merged whenever it matches
+  its base, so a worktree that never committed looks landed while its
+  uncommitted work is still there. Read `git -C <path> status` before removing
+  one; `list_worktrees` reports the same clean/merged flags.
 - The guard is best-effort at the shell level: command substitution, `eval`, and
   `sh -c` are only covered when `blockUnparsableCommands` is enabled, and real
-  isolation of arbitrary shell writes needs an OS sandbox.
+  isolation of arbitrary shell writes needs an OS sandbox. `/worktree` names the
+  gap and counts the commands that passed through it this session.
 - Only the model's `bash` tool is re-rooted and guarded. A shell command the
   user runs directly (`!` in the TUI / the `user_bash` event) is not re-rooted
   and still runs in the main checkout; Pi has no mutable session cwd to change
-  that. `/worktree` and `list_worktrees` report the active root.
+  that. `/worktree` and `list_worktrees` report the active root, and list the
+  shell under `Not isolated:` on every status read.
+- Windows `powershell` is refused while isolated, or — with
+  `guard.blockPowershell: false` — allowed and unguarded. There is no third
+  state: a parsed PowerShell command that keeps the tool.
 
 ## Non-goals
 
@@ -202,19 +245,19 @@ use, falling back to directory mtime for a worktree with no record.
   knows about. It does not rename, rebase, merge, or push branches.
 - **No user-shell re-rooting.** A shell the user runs directly (`!` /
   `user_bash`) is not isolated.
-- **No Windows `powershell` surface.** The overrides guard the POSIX `bash`
-  tool only.
+- **No PowerShell guard.** `powershell` is refused while isolated, not parsed;
+  teaching the guard a second grammar belongs with an OS sandbox, not here.
 
 ## Pi integration
 
 | Contract | Detail |
 |---|---|
 | Registration | The default export calls `registerWorktree`: root-tool overrides, the `--worktree` flag, lifecycle listeners, model tools, and the `/worktree` command. Nothing long-lived starts at load. |
-| Tools | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees` via `registerTool`. All `executionMode: "sequential"`. Annotations: `enter_worktree` destructive + open-world; `exit_worktree`/`prune_worktrees` destructive; `list_worktrees` read-only. No `outputSchema`; structured state is returned in tool-result `details`. |
-| Built-in overrides | `read`/`write`/`edit`/`bash`/`grep`/`find`/`ls` are re-registered under the same names with `defaultActive: false`; each spreads the built-in definition and replaces only `execute`. `skipOverrides` is applied at load time. |
+| Tools | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees` via `registerTool`. All `executionMode: "sequential"`. Annotations: `enter_worktree` destructive + open-world; `exit_worktree`/`prune_worktrees` destructive; `list_worktrees` read-only. No `outputSchema`; structured state is returned in tool-result `details` — `exit_worktree` carries `{ state, removed, handoff }`, where `handoff` is `{ branch, base, ahead, merged }`. |
+| Built-in overrides | `read`/`write`/`edit`/`bash`/`grep`/`find`/`ls` are re-registered under the same names with `defaultActive: false`; each spreads the built-in definition and replaces only `execute`. `skipOverrides` is applied at load time. `powershell` is deliberately not overridden: it cannot be re-rooted without a guard, so the `tool_call` handler refuses it (see `guard.blockPowershell`). |
 | Commands | `/worktree` via `registerCommand`, with argument completions for the subcommands and exit flags. |
 | Flags | `--worktree` via `registerFlag`. |
-| Events | `session_start` (bind inherited env, restore or refuse recorded state, read the flag), `session_shutdown` (release the lock, clear status), `before_agent_start` (set the prompt cwd and worktree section), `tool_call` (guard). |
+| Events | `session_start` (bind inherited env, restore or refuse recorded state, read the flag), `session_shutdown` (release the lock, clear status), `before_agent_start` (set the prompt cwd and worktree section), `tool_call` (guard file tools and `bash`, refuse `powershell`, and count a command it lets through unverified). |
 | State | The binding is a custom session entry (`worktree`) written with `pi.appendEntry` and rebuilt from `ctx.sessionManager.getBranch()` on `session_start`. `.pi/worktrees/index.json` is a disposable managed-record cache, reconciled against `git worktree list`. Child processes inherit `PI_WORKTREE_*` env. |
 | UI/events | Status chip via `ctx.ui.setStatus`; `worktree:changed` published on `pi.events`. |
 
@@ -229,6 +272,14 @@ use, falling back to directory mtime for a worktree with no record.
 - **Two layers: re-root and guard.** Re-rooting relative paths is not enough on
   its own — an absolute path, `cd`, or `git -C` still escapes. The guard runs
   centrally from the `tool_call` handler, so nested tool calls are covered too.
+- **A gap the user cannot see is a gap they cannot weigh.** Re-rooting is not
+  isolating: Pi has no mutable session cwd, so the user's own `!` shell stays in
+  the main checkout, an unverifiable command passes by default, and `powershell`
+  would run unguarded if it were allowed. Those rules live in `gaps.ts` as data,
+  the status text renders them, and the `tool_call` handler counts the one gap the
+  transcript cannot show: a command the guard let through without verifying it.
+  The two gaps a setting can close are closed — `powershell` is refused, and an
+  opt-out is reported by the status and by `doctor`.
 - **Core model: Checkout / Managed record / Binding.** A *Checkout* is a real
   `git worktree` and git is authoritative about it. A *Managed record* is
   provenance and usage in a disposable index. A *Binding* is this session's
@@ -245,6 +296,12 @@ use, falling back to directory mtime for a worktree with no record.
 - **Never force out work.** `exit_worktree` never force-deletes a branch that
   still holds uncommitted changes or commits not reachable from the recorded
   base, even with `remove: true`.
+- **A handoff is read, not performed.** The exit reports the branch's state and
+  the command that finishes it, because a merge touches the main checkout and can
+  conflict — the user should be the one in that state. The merge target is
+  `origin/HEAD`'s branch, falling back to the main checkout's own branch when the
+  repository has no remote; when neither resolves, the block names the branch and
+  prints no command rather than guessing `main`.
 - **Lock, then prune.** Entering a managed worktree takes a `git worktree lock`
   so a concurrent sweep cannot remove it; prune releases stale locks first and
   keeps any worktree it cannot safely remove, with a reason.
@@ -262,10 +319,12 @@ use, falling back to directory mtime for a worktree with no record.
 | `lifecycle.ts` | Barrel: `enterWorktree` / `exitWorktree` / `pruneWorktrees` / status |
 | `errors.ts` | Cancellation error that distinguishes a user decline from a failure |
 | `enter.ts` / `exit.ts` / `prune.ts` | The lifecycle phases |
+| `handoff.ts` | The `Handoff:` block an exit leaves: the branch's lead, whether the base contains it, and the merge or PR command. |
 | `tools.ts` / `commands.ts` | Model tools / slash commands |
 | `root-tools.ts` | Load-time built-in overrides bound to the active root |
 | `git.ts` | Git plumbing (shared runner + read helpers) |
-| `guard.ts` | Path, shell, and git-redirect isolation checks |
+| `guard.ts` | Path, shell, and git-redirect isolation checks, plus the `powershell` refusal |
+| `gaps.ts` | The isolation gaps a session carries, and how they read (pure) |
 | `include.ts` | `.worktreeinclude` matcher and copy |
 | `config.ts` / `state.ts` / `status.ts` | Config, session entry shape, status text |
 | `registry.ts` | Disposable managed-worktree index + derived status |

package/extensions/worktree/config.ts

@@ -20,6 +20,15 @@ export interface WorktreeGuardConfig {
 	blockSymlinkEscapes: boolean;
 	/** Block commands whose git behavior cannot be verified. Default: false */
 	blockUnparsableCommands: boolean;
+	/**
+	 * Refuse the `powershell` tool while isolated. Default: true
+	 *
+	 * Pi's `powershell` tool is neither re-rooted nor guarded — a second grammar
+	 * (backtick escapes, `Set-Location`, `$env:GIT_DIR`) would need a second parser —
+	 * so inside a worktree its relative paths resolve at the main checkout. Refusing
+	 * it is the only honest isolation; `false` allows it and is reported as a gap.
+	 */
+	blockPowershell: boolean;
 }
 
 export interface WorktreeConfig {
@@ -57,6 +66,7 @@ export const DEFAULT_CONFIG: WorktreeConfig = {
 		blockGitRedirects: true,
 		blockSymlinkEscapes: true,
 		blockUnparsableCommands: false,
+		blockPowershell: true,
 	},
 };
 
@@ -81,6 +91,7 @@ function normalizeGuard(raw: unknown, base: WorktreeGuardConfig): WorktreeGuardC
 		blockGitRedirects: booleanOr(value.blockGitRedirects, base.blockGitRedirects),
 		blockSymlinkEscapes: booleanOr(value.blockSymlinkEscapes, base.blockSymlinkEscapes),
 		blockUnparsableCommands: booleanOr(value.blockUnparsableCommands, base.blockUnparsableCommands),
+		blockPowershell: booleanOr(value.blockPowershell, base.blockPowershell),
 	};
 }
 

package/extensions/worktree/exit.ts

@@ -6,7 +6,17 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "./config.ts";
 import { WorktreeCancelledError } from "./errors.ts";
-import { deleteBranch, inspectWork, lockWorktree, unlockWorktree, worktreeRemove } from "./git.ts";
+import {
+	currentBranch,
+	defaultBranch,
+	deleteBranch,
+	inspectWork,
+	isBranchMerged,
+	lockWorktree,
+	unlockWorktree,
+	worktreeRemove,
+} from "./git.ts";
+import { handoffLines, type Handoff } from "./handoff.ts";
 import { removeRecord, touchRecord } from "./registry.ts";
 import { applyWorktreeEnv, clearConfigCache, getActive, publishWorktree, setActive, setStatus } from "./runtime.ts";
 import { persistState, type WorktreeState } from "./state.ts";
@@ -17,11 +27,30 @@ export interface ExitOptions {
 	keepBranch?: boolean;
 }
 
+/**
+ * What the branch holds and how to finish it, computed after the outcome is known.
+ * A failed lookup degrades to the facts already in hand: an exit that succeeded
+ * must not fail because the default branch could not be read.
+ */
+async function describeHandoff(pi: ExtensionAPI, state: WorktreeState, ahead: number): Promise<Handoff> {
+	if (!state.branch) return { branch: null, base: null, ahead, merged: false };
+	try {
+		// `origin/HEAD` names the merge target when the repository has a remote; a
+		// local-only repository has none, and the main checkout's own branch is the
+		// branch a merge would actually land on.
+		const base = (await defaultBranch(pi, state.repoRoot)) ?? (await currentBranch(pi, state.repoRoot)) ?? null;
+		const merged = base ? await isBranchMerged(pi, state.repoRoot, state.branch, base) : false;
+		return { branch: state.branch, base, ahead, merged };
+	} catch {
+		return { branch: state.branch, base: null, ahead, merged: false };
+	}
+}
+
 export async function exitWorktree(
 	pi: ExtensionAPI,
 	ctx: ExtensionContext,
 	options: ExitOptions,
-): Promise<{ state: WorktreeState; removed: boolean; output: string }> {
+): Promise<{ state: WorktreeState; removed: boolean; handoff: Handoff; output: string }> {
 	const state = getActive();
 	if (!state) throw new Error("Not currently in a worktree.");
 	if (state.borrowed) {
@@ -118,5 +147,8 @@ export async function exitWorktree(
 		touchRecord(state.repoRoot, config, state.path);
 	}
 
-	return { state, removed, output: lines.join("\n") };
+	const handoff = await describeHandoff(pi, state, ahead);
+	lines.push(...handoffLines(handoff));
+
+	return { state, removed, handoff, output: lines.join("\n") };
 }

package/extensions/worktree/gaps.ts

@@ -0,0 +1,74 @@
+/**
+ * The isolation gaps a worktree session carries, as data (pure).
+ *
+ * Re-rooting is not the same as isolating: Pi has no mutable session cwd, so a
+ * shell the user runs directly still runs in the main checkout; a command whose
+ * git behavior cannot be verified passes the guard unless
+ * `blockUnparsableCommands` is set; and the Windows `powershell` tool has no
+ * worktree surface, so the guard refuses it unless `blockPowershell` is off.
+ * The README documents all three, which is no help mid-task, so the session
+ * names them where the user already looks: `/worktree` status, and `doctor`.
+ *
+ * Only the unverifiable-command gap carries a count. A `!` shell or a
+ * `powershell` call is visible in the transcript; a command the guard let
+ * through unverified is otherwise silent, so `index.ts` counts those per
+ * session and this module says how many ran.
+ */
+
+import type { WorktreeConfig } from "./config.ts";
+
+/** One surface isolation does not cover. */
+export interface IsolationGap {
+	/** Short label for the surface, e.g. `! shell`. */
+	surface: string;
+	/** What is not isolated, and why. */
+	detail: string;
+}
+
+/** The session facts the gap rules read. */
+export interface GapInput {
+	/** `process.platform`; `powershell` only exists on Windows. */
+	platform: string;
+	/** Tool names active in this session, to tell whether `powershell` is offered. */
+	activeTools: readonly string[];
+	config: WorktreeConfig;
+	/** Commands this session let through although their git behavior could not be verified. */
+	unverifiableCommands: number;
+}
+
+/** The gaps a session carries, in the order a reader should meet them. */
+export function isolationGaps(input: GapInput): IsolationGap[] {
+	const gaps: IsolationGap[] = [
+		{
+			surface: "! shell",
+			detail: "runs in the main checkout; Pi has no mutable session cwd",
+		},
+	];
+	// Only while the guard lets the tool through: refusing it closes the gap, and a
+	// switch that reopens it is exactly what this row is for.
+	if (input.platform === "win32" && input.activeTools.includes("powershell") && !input.config.guard.blockPowershell) {
+		gaps.push({
+			surface: "powershell",
+			detail: "allowed by worktree.guard.blockPowershell: false; not re-rooted or guarded",
+		});
+	}
+	if (!input.config.guard.blockUnparsableCommands) {
+		const ran = input.unverifiableCommands > 0 ? `; ${input.unverifiableCommands} ran this session` : "";
+		gaps.push({
+			surface: "unverifiable",
+			detail: `$(...), backticks, eval, and sh -c pass through (blockUnparsableCommands is off)${ran}`,
+		});
+	}
+	return gaps;
+}
+
+/**
+ * The rendered `Not isolated:` block: one indented line per gap, labels padded
+ * to the longest one. No gaps, no lines — a section that says nothing should
+ * not be printed.
+ */
+export function gapLines(gaps: readonly IsolationGap[]): string[] {
+	if (gaps.length === 0) return [];
+	const column = Math.max(...gaps.map((gap) => gap.surface.length));
+	return gaps.map((gap) => `  ${gap.surface.padEnd(column)}  ${gap.detail}`);
+}