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

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)) {

package/lib/README.md

@@ -19,19 +19,20 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`config.ts`](./config.ts) | Config loading, two ways: `loadConfigFile` for a whole file, and the shared `bytefly.json` (`SHARED_CONFIG_FILE`) via `configSection` / `configValueAt` / `loadConfigSection` (global, then project), plus the atomic `writeConfigFile` / `writeConfigSection` / `writeConfigValue` / `writeConfigValueAt` (the last two edit one leaf, flat or nested, preserving siblings and metadata). Includes `clampInteger` / `clampNumber` / `cleanString` / `asRecord` / `readJson` / `readJsonResult`. |
 | [`env.ts`](./env.ts) | Env-var contracts shared across extensions: the worktree environment (`ENV_ROOT`, `worktreeRoot`, `resolveEffectiveCwd`) used by worktree, file-browse, job, and rewind, plus `isExtensionEnabled` / `ENV_DISABLED_EXTENSIONS` for the package-wide disable list. |
 | [`escape.ts`](./escape.ts) | `escapeHtml`: the single HTML text/attribute escape used by the browse page renderers and the Markdown and syntax highlighters. |
-| [`events.ts`](./events.ts) | Inter-extension `pi.events` channels and payloads: `JOB_FINISHED_CHANNEL` and `JobFinishedEvent`, published by `job` and consumed by bytefly's notify capability. |
+| [`events.ts`](./events.ts) | Inter-extension `pi.events` channels and payloads: `JOB_FINISHED_CHANNEL` / `JobFinishedEvent` (published by `job`, consumed by bytefly's notify capability), `SUBAGENT_FINISHED_CHANNEL` / `SubagentFinishedEvent` (published by `subagent`, consumed by bytefly's footer roll-up), and `WEB_SEARCH_PROVIDER_CHANNEL` / `WebSearchProviderEvent` (published by `web-access` at session start, consumed by bytefly's doctor so it can report the resolved provider without importing the extension — the key itself is never in the payload). |
 | [`notice.ts`](./notice.ts) | The shared transcript notice: `NOTICE_TYPE`, the `NoticeDetails` / `NoticeItem` shape, `noticeMessage` (the `display: true` message both send paths accept), `isNotice`, and `pruneStaleNotices` — posted by `job` and `watch`, rendered by bytefly. |
 | [`format.ts`](./format.ts) | Pure text/number formatting shared by renderers: `formatTokens`, `formatCount`, `formatDuration` (`450ms`, `3.2s`, `1m05s`, `2h03m`), `stripControlChars`, `sanitize`, `sanitizeLine` — the boundary for untrusted, single-line text — and `shortenPath`. |
 | [`interaction.ts`](./interaction.ts) | Turn-affinity prompt contract: the channel a remote transport marks on the UI context it owns (`INTERACTION_TURN_KEY`), the `InteractionChannel` interface (`request` / `post` / `postFile`), and `remoteChannel` / `isRemoteTurn` / `supportsCustomUI` / `askHuman` (with an optional file, fallback text, and digest preface) plus the shared “Other” label. |
 | [`git/`](./git/) | Shared git plumbing. [`git/runner.ts`](./git/runner.ts) is the `RunGit` seam (`createExecRunner` with timeout/env handling, `runGitOrThrow`, `GitError`); [`git/read.ts`](./git/read.ts) holds the read helpers (`repoRoot`, `repoRootFor`, `gitDir`, `revParse`, `hasCommits`, `currentBranch`); [`git/index.ts`](./git/index.ts) is the barrel. |
 | [`highlight.ts`](./highlight.ts) | First-party, escape-first syntax tokenizer (`detectLanguage`, `fenceLanguage`, `highlightLines`, `HighlightLanguage`, `TokenClass`) for js/ts, json, css, html, shell, python, java, yaml, and sql; shared by `file-browse` and plan's code blocks. |
-| [`tui/`](./tui/) | The Bytefly terminal design system shared by every interactive surface: [`tui/tokens.ts`](./tui/tokens.ts) (semantic role -> theme color, `paint`), [`tui/glyphs.ts`](./tui/glyphs.ts) (`GLYPHS`, `SEPARATORS`, `STATUS_KEYS`, `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, `GLYPH_GAP` — the vocabulary both sides of a status must agree on), [`tui/chrome.ts`](./tui/chrome.ts) (`screenHint`, `dockListFrame` (the docked-list frame), `viewportRows`, `FULL_SCREEN_OVERLAY`, `reuseText`, `editorTheme`), [`tui/rules.ts`](./tui/rules.ts) (the rule glyph `RULE_GLYPH`, and `plainRule` / `titleRule` / `centeredRule`), [`tui/indent.ts`](./tui/indent.ts) (the transcript block indent: `BODY_INDENT`, an optional rail prefix that a wrapped call line is kept out of, and `bodyLines` / `indentBlockLines` / `indentedLines`), [`tui/rows.ts`](./tui/rows.ts) (`listRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`), [`tui/columns.ts`](./tui/columns.ts) (`splitRow`, `fitCells`, `flowCells`, `padTo`, `clip`, `clipMiddle`), [`tui/gauge.ts`](./tui/gauge.ts) (`computeGauge`, `gaugeRole`, `gaugeBar`), [`tui/line-pane.ts`](./tui/line-pane.ts) (`LinePane`, the scrollable log/match pane), [`tui/status-controller.ts`](./tui/status-controller.ts) (`createStatusController`, the footer chips `job` and `watch` share), [`tui/tool.ts`](./tui/tool.ts) (`toolCallTitle`, the width-safe `ToolCallText` / `reuseCallText`, sanitized `errorLine` / `rejectionLine`, `moreHint`, `syncElapsedTimer`, `elapsedSuffix` — the tool-transcript kit), [`tui/render-cache.ts`](./tui/render-cache.ts) (`RenderCache`: the per-instance line memo a component that derives its lines from another component's output renders through, so a repeat frame is one comparison), and [`tui/cursor.ts`](./tui/cursor.ts) (scroll and navigation: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` (by index) and `IdCursor` (by stable id) state). |
+| [`tui/`](./tui/) | The Bytefly terminal design system shared by every interactive surface, whose conventions are its own doc, [`tui/README.md`](./tui/README.md). Modules: [`tui/tokens.ts`](./tui/tokens.ts) (semantic role -> theme color, `paint`), [`tui/glyphs.ts`](./tui/glyphs.ts) (`GLYPHS`, `SEPARATORS`, `STATUS_KEYS`, `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, `GLYPH_GAP` — the vocabulary both sides of a status must agree on), [`tui/chrome.ts`](./tui/chrome.ts) (`screenHint`, `dockListFrame` (the docked-list frame), `viewportRows`, `FULL_SCREEN_OVERLAY`, `reuseText`, `editorTheme`), [`tui/rules.ts`](./tui/rules.ts) (the rule glyph `RULE_GLYPH`, and `plainRule` / `titleRule` / `centeredRule`), [`tui/indent.ts`](./tui/indent.ts) (the transcript block indent: `BODY_INDENT`, an optional rail prefix that a wrapped call line is kept out of, and `bodyLines` / `indentBlockLines` / `indentedLines`), [`tui/rows.ts`](./tui/rows.ts) (`listRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`), [`tui/columns.ts`](./tui/columns.ts) (`splitRow`, `fitCells`, `flowCells`, `padTo`, `clip`, `clipMiddle`), [`tui/gauge.ts`](./tui/gauge.ts) (`computeGauge`, `gaugeRole`, `gaugeBar`), [`tui/line-pane.ts`](./tui/line-pane.ts) (`LinePane`, the scrollable log/match pane), [`tui/status-controller.ts`](./tui/status-controller.ts) (`createStatusController`, the footer chips `job` and `watch` share), [`tui/tool.ts`](./tui/tool.ts) (`toolCallTitle`, the width-safe `ToolCallText` / `reuseCallText`, sanitized `errorLine` / `rejectionLine`, `moreHint`, `syncElapsedTimer`, `elapsedSuffix` — the tool-transcript kit), [`tui/render-cache.ts`](./tui/render-cache.ts) (`RenderCache`: the per-instance line memo a component that derives its lines from another component's output renders through, so a repeat frame is one comparison), and [`tui/cursor.ts`](./tui/cursor.ts) (scroll and navigation: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` (by index) and `IdCursor` (by stable id) state). |
 | [`path.ts`](./path.ts) | `isInside` (string containment) plus `realPathOfNearest` / `isInsideReal` (symlink-aware): the containment predicates the file-browse, worktree, and doc guards share. |
 | [`pi-invocation.ts`](./pi-invocation.ts) | `getPiInvocation`: how to launch a nested `pi` process, shared by `subagent` and bytefly's doctor surface. |
 | [`policy.ts`](./policy.ts) | `createReadOnlyPolicy`: default-deny tool classification from `readOnlyHint` + explicit allow/deny. |
 | [`rails.ts`](./rails.ts) | Above-editor widget ordering (`goal` → `todo`) and dock-screen suppression, carried on `pi.events`. |
-| [`requirements.ts`](./requirements.ts) | Per-extension runtime prerequisite table plus a pure `probeExtension(seams)` over injected seams (exec, config reads, optional imports): bytefly's doctor surface reports on it and the extensions that own a dependency format their errors from it. |
+| [`requirements.ts`](./requirements.ts) | Per-extension runtime prerequisite table plus a pure `probeExtension(seams)` over injected seams (exec, config reads, optional imports, the published search provider, env, and a refresh-only reachability probe): bytefly's doctor surface reports on it and the extensions that own a dependency format their errors from it. A check kind is either a prerequisite (`binary`, `module`, `state`, `invocation`, `notify`, `provider`) or a `safety` switch whose off value trades a protection away, read from `bytefly.json` global-then-project. |
 | [`shell.ts`](./shell.ts) | Shell escape rule shared by the worktree isolation guard and plan mode's read-only git guard: `SHELL_ESCAPABLE`, `isShellEscapable`, `hasShellEscape`. |
+| [`goal-state.ts`](./goal-state.ts) | The published `goal` state replayed from the session branch: `PublishedGoal`, `GOAL_ENTRY_TYPE`, `MAX_GOAL_OBJECTIVE`, and `lastGoal(entries)` (the last valid goal, skipping a rejected call and honouring an explicit clear), so `plan` can restate an active goal while planning and offer to record one on approval — with no extension importing another's modules. |
 | [`todo-state.ts`](./todo-state.ts) | The published `todo` state replayed from the session branch: `ExistingTodo` and `lastTodos(entries)` (the last valid list, skipping a rejected call), so `plan` can merge an approved plan's steps into it and `goal` can name the items still open when a goal is marked achieved — with no extension importing another's modules. |
 | [`tool-names.ts`](./tool-names.ts) | Tool names and one parameter name that more than one extension must agree on, so an orchestrating `ctx.executeTool()` call or schema probe breaks the build on a rename. |
 | [`web/`](./web/) | The Bytefly web brand system shared by the browser surfaces: [`web/tokens.ts`](./web/tokens.ts) (palette derived from the Bytefly terminal themes, scales, and the `tok-*` map), [`web/base.ts`](./web/base.ts), [`web/components.ts`](./web/components.ts), [`web/layout.ts`](./web/layout.ts), [`web/runtime.ts`](./web/runtime.ts) (`WEB_THEME_STORAGE_KEY`, `THEME_JS`, `THEME_TOGGLE_JS`), [`web/markup.ts`](./web/markup.ts), and the [`web/index.ts`](./web/index.ts) barrel. |
@@ -47,8 +48,9 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
   glyph and the `setStatus` key are one contract, not two literals. Tool names
   shared by an orchestrating tool and the tool it calls — and parameter names
   one extension probes on another — live in `tool-names.ts`.
-- **A color is a role, not a token.** Draw through [`tui/tokens.ts`](./tui/tokens.ts)
-  (`paint(theme, role, text)`) so a theme swap re-skins every surface; the
-  primitives in `tui/` already do, and a new one should too. The one exception is
-  Pi's tool-rendering vocabulary (`toolOutput`, `toolTitle`), which stays direct:
-  those tokens style a tool block, and no role maps to them.
+- **A color is a role, not a token.** The rules and the primitives are in
+  [`tui/README.md`](./tui/README.md#color-is-a-role): draw through
+  [`tui/tokens.ts`](./tui/tokens.ts) (`paint(theme, role, text)`) so a theme swap
+  re-skins every surface. The one exception is Pi's tool-rendering vocabulary
+  (`toolOutput`, `toolTitle`), which stays direct: those tokens style a tool
+  block, and no role maps to them.

package/lib/events.ts

@@ -10,7 +10,9 @@
  *
  * The bus carries no state. `rails.ts` and `worktree` publish their own channels
  * from the modules that own them; a channel crosses an extension boundary only
- * when the payload is the whole contract, which is the case here.
+ * when the payload is the whole contract, which is the case here: `job` publishes
+ * a finished job for bytefly's notify capability, and `subagent` publishes a
+ * finished child run for bytefly's footer roll-up.
  */
 
 /** EventBus channel: a background job reached a terminal state. */
@@ -25,6 +27,89 @@ export const JOB_FINISHED_CHANNEL = "my-pi-agent/job-finished";
  */
 export type FinishedJobStatus = "exited" | "failed" | "killed" | "unknown";
 
+/** EventBus channel: a `watch` wake match fired while the agent was idle. */
+export const WATCH_MATCH_CHANNEL = "my-pi-agent/watch-match";
+
+/**
+ * Payload on {@link WATCH_MATCH_CHANNEL}: what a wake match saw.
+ *
+ * Emitted by `watch` and consumed by bytefly's notify capability, so the two can
+ * agree on an alert without `watch` learning about delivery methods. The line is
+ * **raw** — the matched text is arbitrary file or process output — and the
+ * consumer sanitizes it before it reaches a notification, exactly as it does for a
+ * job label. `count` covers the whole wake cycle, so one notification can say how
+ * many lines matched while the body describes the newest one.
+ */
+export interface WatchMatchEvent {
+	/** How many matches were pending when the wake fired. */
+	count: number;
+	/** The watcher that matched, e.g. `w3`. */
+	watcherId: string;
+	/** Its label, e.g. `build`. */
+	label: string;
+	/** The newest matched line, unsanitized. */
+	line: string;
+}
+
+/** EventBus channel: one subagent run finished (a child `pi` process exited). */
+export const SUBAGENT_FINISHED_CHANNEL = "my-pi-agent/subagent-finished";
+
+/**
+ * Payload on {@link SUBAGENT_FINISHED_CHANNEL}: what one finished child run spent.
+ *
+ * It carries the *pricing inputs* rather than a total, because the consumer prices
+ * them with the same rate table and currency as the session's own cost, and a
+ * currency change must re-price them rather than leave a figure in the old unit.
+ * `recordedCost` is Pi's own dollar figure for the child's assistant calls.
+ *
+ * A run that produced no assistant message (an unknown agent, a spawn failure)
+ * publishes nothing: there is no spend to account for.
+ */
+export interface SubagentFinishedEvent {
+	/** Agent that ran, e.g. `explorer`. */
+	agent: string;
+	/** Provider and model the child reported, when it reported one. */
+	provider: string | null;
+	model: string | null;
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	/** Pi's recorded cost for the child's calls, in USD. */
+	recordedCost: number;
+	/** Epoch ms when the run finished, or `null` when unknown. */
+	at: number | null;
+	/** Child process exit code; a model-level failure still exits 0. */
+	exitCode: number;
+}
+
+/** EventBus channel: `web-access` resolved its search provider for this session. */
+export const WEB_SEARCH_PROVIDER_CHANNEL = "my-pi-agent/web-search-provider";
+
+/**
+ * Payload on {@link WEB_SEARCH_PROVIDER_CHANNEL}: what `web_search` will use.
+ *
+ * `web-access` owns the provider registry, each provider's `isConfigured`, and the
+ * `auto` resolution rule, so it is the only place those facts can come from: this
+ * event is how `doctor` learns them without importing an extension. The key
+ * itself is never published — only the variable name and whether a literal key is
+ * configured — so a diagnostic can never leak a secret into a log or a notice.
+ */
+export interface WebSearchProviderEvent {
+	/** Resolved backend id, e.g. `searxng`. */
+	provider: string;
+	/** Why this provider won: an explicit choice, one that is configured, or the keyless default. */
+	reason: "explicit" | "configured" | "default";
+	/** Whether the resolved provider's configuration is enough to call it. */
+	configured: boolean;
+	/** URL a refresh may probe, when the provider has a configurable endpoint. */
+	endpoint: string | null;
+	/** Environment variable a key would come from, when the provider takes one. */
+	apiKeyEnv: string | null;
+	/** Whether a literal key is configured, so a missing variable is not the whole story. */
+	keyConfigured: boolean;
+}
+
 /** Payload on {@link JOB_FINISHED_CHANNEL}: one job that just stopped. */
 export interface JobFinishedEvent {
 	/** Job id, e.g. `j3`. */

package/lib/goal-state.ts

@@ -0,0 +1,95 @@
+/**
+ * The published goal state, read back from the session branch (pure).
+ *
+ * `goal` publishes its objective two ways: every `goal` tool result carries the
+ * goal in `details` — a rejected call carries the unchanged goal *and* an
+ * `error`, which is not a write — and the `/goal` command appends a `goal` custom
+ * entry whose `data.goal` is `null` when the goal is cleared. Replaying the branch
+ * in order is how another extension reads the goal without importing goal's
+ * modules: `plan` restates an active goal in its planning context and offers to
+ * record one when a plan is approved with none.
+ *
+ * Stored values are re-validated and re-sanitized here. Branch data can be
+ * tampered with, migrated, or written by an older version, and a reader must not
+ * pass escapes or unbounded text onward; anything that fails validation is
+ * ignored rather than clearing a goal that is still valid.
+ *
+ * The entry type and the objective limit live here and are imported by `goal`, so
+ * the publisher and the reader cannot drift. `goal` keeps its own reconstruction
+ * (`extensions/goal/state.ts`) because it also drives the widget; this module is
+ * the minimal contract other extensions may depend on.
+ */
+
+import { sanitizeLine } from "./format.ts";
+import { GOAL_TOOL } from "./tool-names.ts";
+
+/** Custom-entry type `goal` uses to persist a goal set outside the tool. */
+export const GOAL_ENTRY_TYPE = "goal";
+
+/** Longest objective the goal tool accepts, and the most a reader will replay. */
+export const MAX_GOAL_OBJECTIVE = 2000;
+
+/** Whether the goal is still being pursued, or already done. */
+export type PublishedGoalStatus = "active" | "achieved";
+
+/** The goal as another extension may read it. */
+export interface PublishedGoal {
+	/** The objective, sanitized to a single line. */
+	objective: string;
+	status: PublishedGoalStatus;
+}
+
+/** Minimal shape of a session entry, used for runtime narrowing. */
+interface BranchEntryLike {
+	type?: string;
+	customType?: string;
+	data?: unknown;
+	message?: {
+		role?: string;
+		toolName?: string;
+		details?: unknown;
+	};
+}
+
+/**
+ * A stored goal value: `undefined` when it cannot be read, `null` for an explicit
+ * clear, otherwise the validated goal.
+ */
+function readGoal(value: unknown): PublishedGoal | null | undefined {
+	if (value === null) return null;
+	if (!value || typeof value !== "object") return undefined;
+	const goal = value as { objective?: unknown; status?: unknown };
+	if (typeof goal.objective !== "string") return undefined;
+	if (goal.status !== "active" && goal.status !== "achieved") return undefined;
+	const objective = sanitizeLine(goal.objective);
+	if (!objective || objective.length > MAX_GOAL_OBJECTIVE) return undefined;
+	return { objective, status: goal.status };
+}
+
+/** The last goal written on the branch, or `null` when the session has none. */
+export function lastGoal(entries: Iterable<unknown>): PublishedGoal | null {
+	let goal: PublishedGoal | null = null;
+	for (const raw of entries) {
+		const entry = raw as BranchEntryLike;
+
+		// The `/goal` command records a custom entry; the tool records a result below.
+		// Both replay in branch order, so the last write wins.
+		if (entry?.type === "custom" && entry.customType === GOAL_ENTRY_TYPE) {
+			const data = entry.data as { goal?: unknown } | null | undefined;
+			if (!data || typeof data !== "object" || !("goal" in data)) continue;
+			const next = readGoal(data.goal);
+			if (next !== undefined) goal = next;
+			continue;
+		}
+
+		if (entry?.type !== "message") continue;
+		const message = entry.message;
+		if (message?.role !== "toolResult" || message.toolName !== GOAL_TOOL) continue;
+		const details = message.details as { goal?: unknown; error?: unknown } | undefined;
+		if (!details || details.error) continue;
+		if (!("goal" in details)) continue;
+		const next = readGoal(details.goal);
+		if (next !== undefined) goal = next;
+	}
+	return goal;
+}