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

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}`);
+}

package/extensions/worktree/guard.ts

@@ -8,7 +8,8 @@
  *   1. file edits that resolve outside the active worktree (absolute paths);
  *   2. a shell command whose working directory leaves the worktree;
  *   3. git commands redirected at the main checkout;
- *   4. (optional) commands whose text cannot be statically verified.
+ *   4. (optional) commands whose text cannot be statically verified;
+ *   5. the un-re-rooted `powershell` tool, which has no guard of its own.
  */
 
 import { homedir } from "node:os";
@@ -224,8 +225,12 @@ function pathEscapes(root: string, raw: string): boolean {
 	return !isInside(root, resolve(root, expanded.path));
 }
 
-/** Check 4: constructs whose text does not spell out the git command that runs. */
-function looksUnparsable(command: string): boolean {
+/**
+ * Constructs whose text does not spell out the git command that runs. Exported
+ * so the `tool_call` handler counts exactly the commands this check would have
+ * refused, instead of guessing at a second list.
+ */
+export function isUnverifiable(command: string): boolean {
 	return /\$\(|`|\$\{!|\beval\b|\b(?:sh|bash|zsh|dash|ksh)\s+-c\b/.test(command);
 }
 
@@ -360,6 +365,7 @@ function redirectionEscapes(root: string, command: string, config: WorktreeConfi
 	for (const segment of splitSegments(command)) {
 		for (const redirect of redirectionTargets(segment)) {
 			if (redirect.write ? !checkWrites : !checkReads) continue;
+			if (isNullDevice(redirect.target)) continue;
 			if (pathEscapes(root, redirect.target)) {
 				return `${redirect.write ? "Output" : "Input"} redirection to \"${redirect.target}\" leaves the active worktree.`;
 			}
@@ -368,6 +374,15 @@ function redirectionEscapes(root: string, command: string, config: WorktreeConfi
 	return undefined;
 }
 
+/**
+ * The null device discards the stream instead of writing a file, so a redirect
+ * there escapes nothing — and `2>/dev/null` is too common to refuse. Quotes are
+ * stripped because the target keeps them as written.
+ */
+function isNullDevice(raw: string): boolean {
+	return raw.replace(/^(['"])(.*)\1$/, "$2") === "/dev/null";
+}
+
 /** Commands that wrap another command, so a following assignment is still a prefix. */
 const COMMAND_WRAPPERS = new Set(["sudo", "doas", "env", "command", "builtin", "exec", "nohup", "nice", "time"]);
 
@@ -532,6 +547,37 @@ function cdRedirect(root: string, words: ShellWord[]): string | undefined {
 	return undefined;
 }
 
+// ---------------------------------------------------------------------------
+// The powershell tool (check 5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Refuse the `powershell` tool while isolated.
+ *
+ * Pi's `powershell` tool is neither re-rooted nor guarded: it is not in
+ * `ROOT_TOOL_NAMES`, and its language is a second grammar — backtick escapes,
+ * `Set-Location`, `$env:GIT_DIR`, `--%` — so `analyzeBashCommand` would be
+ * guessing. Inside a worktree its relative paths therefore resolve at the main
+ * checkout, the checkout isolation exists to protect.
+ *
+ * Re-rooting it without a parser would be worse than refusing it: it would look
+ * isolated while every one of those forms still walks out. So the isolated
+ * session refuses the tool, the same answer plan mode gives, and
+ * `guard.blockPowershell: false` is the documented opt-out — which `gaps.ts`
+ * reports and `doctor` shows as `degraded`.
+ */
+export function guardPowershellTool(config: WorktreeConfig): GuardBlock | undefined {
+	if (!config.guard.blockPowershell) return undefined;
+	return {
+		block: true,
+		reason:
+			"Refusing to run powershell inside an isolated worktree: it is not re-rooted or guarded, " +
+			"so relative paths and git would run against the main checkout. " +
+			"Use bash, which is re-rooted and guarded, or exit the worktree first. " +
+			"(worktree.guard.blockPowershell turns this refusal off.)",
+	};
+}
+
 /** Checks 2-4 for a bash command while isolated. */
 export function analyzeBashCommand(command: string, root: string, config: WorktreeConfig): GuardBlock | undefined {
 	if (config.guard.blockGitRedirects) {
@@ -553,7 +599,7 @@ export function analyzeBashCommand(command: string, root: string, config: Worktr
 		return { block: true, reason: `${redirect} Exit the worktree to operate on the main checkout.` };
 	}
 
-	if (config.guard.blockUnparsableCommands && looksUnparsable(command)) {
+	if (config.guard.blockUnparsableCommands && isUnverifiable(command)) {
 		return {
 			block: true,
 			reason:

package/extensions/worktree/handoff.ts

@@ -0,0 +1,55 @@
+/**
+ * The handoff an exit leaves behind: what the branch holds, and the command that
+ * finishes the task.
+ *
+ * `AGENTS.md` ends a worktree task with a merge into the main checkout, or a pull
+ * request. The exit already decides the branch's fate and keeps one that holds
+ * commits; this says how many, whether the default branch already contains them,
+ * and the exact commands — so the next step is read, not remembered.
+ *
+ * Pure: the caller has the facts, this shapes them. The tool never commits, merges,
+ * pushes, or opens a pull request, because each of those acts on a checkout the
+ * session is no longer isolated in.
+ */
+
+/** What a leaving worktree hands back to the main checkout. */
+export interface Handoff {
+	/** The worktree branch, when the session had one. */
+	branch: string | null;
+	/** The branch a merge would target, when it could be resolved. */
+	base: string | null;
+	/** Commits on the branch that the base does not contain. */
+	ahead: number;
+	/** Whether the base already contains every commit on the branch. */
+	merged: boolean;
+}
+
+/** Pluralized commit count, e.g. `1 commit` / `3 commits`. */
+function commits(count: number): string {
+	return `${count} commit${count === 1 ? "" : "s"}`;
+}
+
+/**
+ * The `Handoff:` block: one headline and, only when there is something to do, the
+ * two commands. A merged or empty branch prints no command — inviting a merge of
+ * work that is already in the base is how a branch gets merged twice.
+ */
+export function handoffLines(handoff: Handoff): string[] {
+	if (!handoff.branch) return ["Handoff: the worktree had no branch to hand off."];
+
+	if (handoff.base === null) {
+		return [
+			`Handoff: branch ${handoff.branch} holds ${commits(handoff.ahead)}; its base branch could not be resolved.`,
+		];
+	}
+	if (handoff.merged || handoff.ahead === 0) {
+		const state = handoff.merged ? `is merged into ${handoff.base}` : `has no commits beyond ${handoff.base}`;
+		return [`Handoff: ${handoff.branch} ${state} — nothing to merge.`];
+	}
+
+	return [
+		`Handoff: ${handoff.branch} is ${commits(handoff.ahead)} ahead of ${handoff.base}.`,
+		`  merge:  git switch ${handoff.base} && git merge --no-ff ${handoff.branch}`,
+		`  or PR:  gh pr create --head ${handoff.branch} --fill`,
+	];
+}

package/extensions/worktree/index.ts

@@ -26,7 +26,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
 import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { canonicalize, checkCheckout, repoRoot, unlockWorktree } from "./git.ts";
-import { analyzeBashCommand, guardFileTool } from "./guard.ts";
+import { analyzeBashCommand, guardFileTool, guardPowershellTool, isUnverifiable } from "./guard.ts";
 import {
 	enterWorktree,
 	findInactiveOverrides,
@@ -50,7 +50,9 @@ import {
 	getInactiveOverrides,
 	getRoot,
 	getSkipOverrides,
+	noteUnverifiableCommand,
 	publishWorktree,
+	resetDiagnostics,
 	setActive,
 	setBaseCwd,
 	setInactiveOverrides,
@@ -88,6 +90,7 @@ export function registerWorktree(pi: ExtensionAPI, { entryPath, createBuiltin }:
 		setBaseCwd(ctx.cwd);
 		setActive(null);
 		clearConfigCache();
+		resetDiagnostics();
 
 		// A child `pi` process (subagent) inherits an active worktree. Bind to
 		// it without creating, locking, or persisting anything; the parent owns
@@ -203,8 +206,15 @@ export function registerWorktree(pi: ExtensionAPI, { entryPath, createBuiltin }:
 		const config = configFor(state.repoRoot);
 		if (event.toolName === "bash") {
 			const command = (event.input as { command?: string }).command ?? "";
-			return analyzeBashCommand(command, state.path, config);
+			const block = analyzeBashCommand(command, state.path, config);
+			// A command the guard lets through unverified is the one gap the transcript
+			// cannot show, so count it for `/worktree` instead of losing it.
+			if (!block && isUnverifiable(command)) noteUnverifiableCommand();
+			return block;
 		}
+		// The Windows shell has no re-rooting and no guard, so it is refused rather
+		// than checked; the switch that allows it is reported as a gap.
+		if (event.toolName === "powershell") return guardPowershellTool(config);
 		return guardFileTool(event.toolName, event.input, state.path, config);
 	});
 

package/extensions/worktree/runtime.ts

@@ -29,6 +29,8 @@ let active: WorktreeState | null = null;
 let baseCwd = process.cwd();
 let inactiveOverrides: string[] = [];
 let gitignoreOffered = false;
+/** Commands this session let through although the guard could not verify them. */
+let unverifiableCommands = 0;
 const configCache = new Map<string, WorktreeConfig>();
 
 export function getActive(): WorktreeState | null {
@@ -68,6 +70,24 @@ export function markGitignoreOffered(): void {
 	gitignoreOffered = true;
 }
 
+/**
+ * Count a bash command the guard let through without being able to verify it.
+ * Session-scoped on purpose: it is the one gap a user cannot see in the
+ * transcript, so `/worktree` reports how often it happened.
+ */
+export function noteUnverifiableCommand(): void {
+	unverifiableCommands += 1;
+}
+
+export function getUnverifiableCommands(): number {
+	return unverifiableCommands;
+}
+
+/** Forget the previous session's diagnostics; called from `session_start`. */
+export function resetDiagnostics(): void {
+	unverifiableCommands = 0;
+}
+
 /** Cached config for the hot `tool_call` path; cleared on enter and exit. */
 export function configFor(root: string): WorktreeConfig {
 	let config = configCache.get(root);

package/extensions/worktree/status.ts

@@ -6,9 +6,10 @@
 import { basename } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "./config.ts";
+import { gapLines, isolationGaps } from "./gaps.ts";
 import { canonicalize, type CheckoutCheck, defaultBranch, listManagedWorktrees, repoRoot } from "./git.ts";
 import { reconcileRegistry, statusOf, type CheckoutStatus } from "./registry.ts";
-import { getActive, getInactiveOverrides } from "./runtime.ts";
+import { configFor, getActive, getInactiveOverrides, getUnverifiableCommands } from "./runtime.ts";
 import type { WorktreeState } from "./state.ts";
 
 export function worktreeLabel(state: WorktreeState): string {
@@ -79,7 +80,7 @@ function relativeDay(at: number): string {
 	return `${days}d ago`;
 }
 
-/** Human-readable status: current worktree, override conflicts, managed worktrees. */
+/** Human-readable status: current worktree, override conflicts, gaps, managed worktrees. */
 export async function worktreeStatus(pi: ExtensionAPI, ctx: ExtensionContext): Promise<string> {
 	const current = getActive();
 	const lines: string[] = [];
@@ -93,6 +94,18 @@ export async function worktreeStatus(pi: ExtensionAPI, ctx: ExtensionContext): P
 	if (inactive.length > 0) {
 		lines.push("", `Isolation not active for: ${inactive.join(", ")} (their default implementation is in use).`);
 	}
+	if (current) {
+		// What isolation does not cover, from the same rules `doctor` reports: a gap
+		// the user cannot see is a gap they cannot weigh.
+		const gaps = isolationGaps({
+			platform: process.platform,
+			activeTools: pi.getActiveTools(),
+			config: configFor(current.repoRoot),
+			unverifiableCommands: getUnverifiableCommands(),
+		});
+		const gapBlock = gapLines(gaps);
+		if (gapBlock.length > 0) lines.push("", "Not isolated:", ...gapBlock);
+	}
 
 	const root = current?.repoRoot ?? (await repoRoot(pi, ctx.cwd));
 	if (root) {

package/extensions/worktree/tools.ts

@@ -75,7 +75,8 @@ export function registerTools(pi: ExtensionAPI): void {
 		label: "Exit worktree",
 		description:
 			"Leave the current git worktree and return to the main checkout. The worktree is removed when clean; with " +
-			"uncommitted changes or new commits the user chooses whether to keep it.",
+			"uncommitted changes or new commits the user chooses whether to keep it. The result names the branch's " +
+			"commits and the merge or pull-request command that finishes it.",
 		promptSnippet: "Leave the current git worktree and return to the main checkout.",
 		promptGuidelines: [
 			"Use exit_worktree after work started with enter_worktree; it is the only way back to the main checkout.",
@@ -93,7 +94,7 @@ export function registerTools(pi: ExtensionAPI): void {
 				ctx.ui.notify(`Exited worktree ${worktreeLabel(result.state)}`, "info");
 				return {
 					content: [{ type: "text", text: result.output }],
-					details: { state: result.state, removed: result.removed },
+					details: { state: result.state, removed: result.removed, handoff: result.handoff },
 				};
 			} catch (error) {
 				if (isWorktreeCancelled(error)) {