@gavin-hu/my-pi-agent 0.17.0 → 0.18.0

package/extensions/wechat/prompt.ts

@@ -2,15 +2,15 @@
  * Pure rendering and parsing of remote dialog prompts (no I/O).
  *
  * A prompt is rendered to a WeChat message by {@link formatPrompt}; the reply is
- * interpreted by {@link parsePromptAnswer}. Hints are bilingual (Chinese and
- * English) so either reader can answer, and {@link formatPrompt} can prepend a
- * short notice when a reply was not understood. The parser is deliberately total:
+ * interpreted by {@link parsePromptAnswer}. Hints are rendered in the peer's
+ * language, and {@link formatPrompt} can prepend a short notice when a reply was
+ * not understood. The parser is deliberately total:
  * anything it cannot resolve reports `retry`, and free text on a `select` becomes
  * the {@link INTERACTION_OTHER_LABEL} option so the caller can collect it once.
  */
 
 import { INTERACTION_OTHER_LABEL, type InteractionRequest } from "../../lib/interaction.ts";
-import { sanitizeInbound } from "./format.ts";
+import { sanitizeInbound, type PeerLanguage } from "./format.ts";
 
 /** A parsed reply: a resolved answer, the "other" choice, or a retry. */
 export type PromptParse =
@@ -20,20 +20,30 @@ export type PromptParse =
 	| { kind: "cancelled" }
 	| { kind: "retry" };
 
-const SELECT_OTHER_HINT =
-	"回复编号或选项文字；其它内容作为自定义回答；回复「取消」或 cancel 跳过。\n" +
-	"Reply with a number or the option text; anything else becomes your own answer; reply cancel to dismiss.";
-const SELECT_CHOICE_HINT =
-	"回复编号或选项文字；回复「取消」或 cancel 跳过。\n" +
-	"Reply with a number or the option text; reply cancel to dismiss.";
-const CONFIRM_HINT = "回复「是」或「否」。\nReply yes or no.";
-const INPUT_HINT = "直接回复内容；回复「取消」或 cancel 跳过。\nReply with the text; reply cancel to skip.";
-const EDITOR_HINT =
-	"把内容作为一条消息发回；回复「取消」或 cancel 取消。\nSend the text as one message; reply cancel to cancel.";
+const SELECT_OTHER_HINT: Record<PeerLanguage, string> = {
+	zh: "回复编号或选项文字；其它内容作为自定义回答；回复「取消」跳过。",
+	en: "Reply with a number or the option text; anything else is your own answer; reply cancel to dismiss.",
+};
+const SELECT_CHOICE_HINT: Record<PeerLanguage, string> = {
+	zh: "回复编号或选项文字；回复「取消」跳过。",
+	en: "Reply with a number or the option text; reply cancel to dismiss.",
+};
+const CONFIRM_HINT: Record<PeerLanguage, string> = {
+	zh: "回复「是」或「否」。",
+	en: "Reply yes or no.",
+};
+const INPUT_HINT: Record<PeerLanguage, string> = {
+	zh: "直接回复内容；回复「取消」跳过。",
+	en: "Reply with the text; reply cancel to skip.",
+};
+const EDITOR_HINT: Record<PeerLanguage, string> = {
+	zh: "把内容作为一条消息发回；回复「取消」取消。",
+	en: "Send the text as one message; reply cancel to cancel.",
+};
 
 /** Sent ahead of a re-prompt when a reply could not be interpreted. */
-export const RETRY_NOTICE =
-	"没有识别到有效回复，请重新回答。\nSorry, I didn't recognize that reply — please answer again.";
+export const RETRY_NOTICE = "Sorry, I didn't recognize that reply — please answer again.";
+const RETRY_ZH = "没有识别到有效回复，请重新回答。";
 
 const CANCEL_WORDS = new Set(["取消", "退出", "cancel", "quit", "exit"]);
 const YES_WORDS = new Set(["是", "y", "yes", "1", "确认", "确定", "行", "ok", "好", "对"]);
@@ -44,24 +54,29 @@ function lines(parts: Array<string | undefined>): string {
 }
 
 /** Render a dialog prompt as a WeChat message body, optionally after a retry. */
-export function formatPrompt(request: InteractionRequest, options: { retry?: boolean } = {}): string {
-	const body = promptBody(request);
-	return options.retry ? `${RETRY_NOTICE}\n\n${body}` : body;
+export function formatPrompt(
+	request: InteractionRequest,
+	options: { retry?: boolean; language?: PeerLanguage } = {},
+): string {
+	const language = options.language ?? "en";
+	const body = promptBody(request, language);
+	const retry = language === "zh" ? RETRY_ZH : RETRY_NOTICE;
+	return options.retry ? `${retry}\n\n${body}` : body;
 }
 
-function promptBody(request: InteractionRequest): string {
+function promptBody(request: InteractionRequest, language: PeerLanguage): string {
 	switch (request.kind) {
 		case "select": {
 			const options = (request.options ?? []).map((label, index) => `${index + 1}. ${label}`);
 			const hasOther = (request.options ?? []).includes(INTERACTION_OTHER_LABEL);
-			return lines([request.title, ...options, hasOther ? SELECT_OTHER_HINT : SELECT_CHOICE_HINT]);
+			return lines([request.title, ...options, hasOther ? SELECT_OTHER_HINT[language] : SELECT_CHOICE_HINT[language]]);
 		}
 		case "confirm":
-			return lines([request.title, request.message, CONFIRM_HINT]);
+			return lines([request.title, request.message, CONFIRM_HINT[language]]);
 		case "input":
-			return lines([request.title, request.placeholder, INPUT_HINT]);
+			return lines([request.title, request.placeholder, INPUT_HINT[language]]);
 		case "editor":
-			return lines([request.title, request.prefill, EDITOR_HINT]);
+			return lines([request.title, request.prefill, EDITOR_HINT[language]]);
 	}
 }
 

package/extensions/wechat/reply-pipeline.ts

@@ -27,6 +27,8 @@ export interface ReplyPipelineDeps {
 export interface ReplyPipeline {
 	/** Add streamed text; parts go out as boundaries are crossed. */
 	push(delta: string): void;
+	/** Send the current buffer now, in order; used before a dialog or file. */
+	flush(): Promise<void>;
 	/** Send whatever is left and resolve once every part is out. */
 	finish(): Promise<void>;
 	/** Drop the unsent remainder (an aborted turn) and cancel the timer. */
@@ -106,6 +108,13 @@ export function createReplyPipeline(deps: ReplyPipelineDeps): ReplyPipeline {
 		enqueue(part);
 	}
 
+	async function flushBuffer(): Promise<void> {
+		cancelQuiet();
+		enqueue(buffer);
+		buffer = "";
+		await chain;
+	}
+
 	return {
 		push(delta: string): void {
 			if (!delta) return;
@@ -125,11 +134,10 @@ export function createReplyPipeline(deps: ReplyPipelineDeps): ReplyPipeline {
 			scheduleQuiet();
 		},
 
+		flush: flushBuffer,
+
 		async finish(): Promise<void> {
-			cancelQuiet();
-			enqueue(buffer);
-			buffer = "";
-			await chain;
+			await flushBuffer();
 		},
 
 		drop(): void {

package/extensions/worktree/git.ts

@@ -355,6 +355,11 @@ export async function inspectWork(pi: ExtensionAPI, dir: string, base?: string):
 }
 
 export interface ManagedWorktree {
+	/**
+	 * Canonical path, resolved through symlinks by `listManagedWorktrees`. Every
+	 * caller takes that as given: re-resolving it here would repeat a sync ancestor
+	 * walk the listing already paid for, once per worktree per status read.
+	 */
 	path: string;
 	branch?: string;
 	head?: string;

package/extensions/worktree/registry.ts

@@ -145,7 +145,9 @@ export function reconcileRegistry(
 	options: { persist?: boolean } = {},
 ): { registry: WorktreeRegistry; changed: boolean } {
 	const registry = loadRegistry(repoRoot, config);
-	const live = new Set(managed.map((entry) => realPathOfNearest(entry.path)));
+	// Resolve each entry once: the live set and the synthesized records both need it.
+	const resolved = managed.map((entry) => ({ entry, path: realPathOfNearest(entry.path) }));
+	const live = new Set(resolved.map((row) => row.path));
 	const byPath = new Map(registry.worktrees.map((record) => [record.path, record] as const));
 
 	let changed = false;
@@ -157,8 +159,7 @@ export function reconcileRegistry(
 			changed = true;
 		}
 	}
-	for (const entry of managed) {
-		const path = realPathOfNearest(entry.path);
+	for (const { entry, path } of resolved) {
 		if (byPath.has(path)) continue;
 		next.push({
 			path,
@@ -183,13 +184,18 @@ export interface StatusOptions {
 	record?: WorktreeRecord;
 }
 
-/** Derive one checkout's status from its git listing and registry record. */
+/**
+ * Derive one checkout's status from its git listing and registry record.
+ *
+ * `entry.path` is taken as canonical — the listing and `reconcileRegistry` are the
+ * two places a path is resolved — so this does not walk the ancestors again.
+ */
 export async function statusOf(
 	pi: ExtensionAPI,
 	entry: ManagedWorktree,
 	options: StatusOptions = {},
 ): Promise<CheckoutStatus> {
-	const path = realPathOfNearest(entry.path);
+	const path = entry.path;
 	const locked = entry.locked !== undefined;
 	const staleLock = locked && entry.locked ? isStaleLock(entry.locked) : false;
 	const base: CheckoutStatus = {

package/extensions/worktree/status.ts

@@ -10,7 +10,6 @@
 
 import { basename } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { realPathOfNearest } from "../../lib/path.ts";
 import { mapConcurrent } from "../../lib/pool.ts";
 import { loadConfig } from "./config.ts";
 import { gapLines, type IsolationGap, isolationGaps } from "./gaps.ts";
@@ -133,8 +132,7 @@ export async function worktreeSnapshot(pi: ExtensionAPI, ctx: ExtensionContext):
 		// lookup instead of a scan of every record.
 		const records = new Map(registry.worktrees.map((record) => [record.path, record]));
 		const row = async (entry: ManagedWorktree): Promise<ManagedRow> => {
-			const path = realPathOfNearest(entry.path);
-			return { entry, status: await statusOf(pi, entry, { baseRef, record: records.get(path) }) };
+			return { entry, status: await statusOf(pi, entry, { baseRef, record: records.get(entry.path) }) };
 		};
 		// Each row is up to four git reads; four at a time keeps the list in the order
 		// git reports while overlapping the waits. `statusOf` passes no `env`, which is

package/lib/README.md

@@ -18,17 +18,19 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | Module | Responsibility |
 |---|---|
 | [`browser.ts`](./browser.ts) | Cross-platform default-browser opener shared by `file-browse` and `plan`: pure `browserCommand(url, platform)` plus best-effort `openInBrowser(url, { platform, spawn })` with an injectable spawn. |
+| [`claims/`](./claims/) | Claim overlap, shared by the two things that ask "do these paths collide?" so approval and claiming cannot disagree: [`claims/overlap.ts`](./claims/overlap.ts) holds `normalizeClaimPath` (repository-relative, posix, no trailing slash — a Windows spelling reads as the same path), `claimsConflict` (a claim covers everything below it, in either direction) and `findClaimOverlap` (the first colliding pair). Used by `session-bus` when a session claims, and by plan approval when a split names its units. |
 | [`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` / `writeConfigValuesAt` / `unsetConfigValueAt` (the leaf writers preserve siblings and metadata, `writeConfigValuesAt` applies several leaves in one document pass, and the last removes one and prunes what it emptied). Includes `clampInteger` / `clampNumber` / `cleanString` / `optionalString` / `asBoolean` / `stringList` / `asRecord` / `asNumber` (the untrusted-JSON narrowing pair) / `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, plus `decodeCodePoint`, the other half of the same boundary — one numeric character reference as text, with a surrogate or out-of-range value decoded to U+FFFD. |
 | [`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. |
-| [`report.ts`](./report.ts) | The pending-report channel: `createPendingReporter` with `wake` / `pending` / `markReported` / `buildNotice` / `source` / `onWoke`, returning the handlers that report at the next turn, raise at most one triggered turn per wake window, and prune only their own notices; and `registerPendingChannel`, which binds those handlers to `session_start` / `session_tree` / `agent_start` / `agent_settled` / `before_agent_start` / `context` / `session_shutdown` around a `load` / `setStatus` / `shutdown` runtime, so the order a session starts and shuts down is written once. `job` and `watch` supply only their own arming in `onSessionStart` / `onSessionShutdown`. |
+| [`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`, `watch`, and `session-bus`, rendered by bytefly — plus `burstText`, the one assembly of the model-facing text for a burst of pending outcomes (marker, counted headline, rows, an optional `… N more`, an optional hint). |
+| [`report.ts`](./report.ts) | The pending-report channel: `createPendingReporter` with `wake` / `pending` / `markReported` / `buildNotice` / `wakeRequested` / `source` / `onWoke`, returning the handlers that report at the next turn, raise at most one triggered turn per wake window, retry a wake the running turn suppressed once `agent_settled` reports an unaborted settle, and prune only their own notices; and `registerPendingChannel`, which binds those handlers to `session_start` / `session_tree` / `agent_start` / `agent_settled` / `before_agent_start` / `context` / `session_shutdown` around a `load` / `setStatus?` / `shutdown` runtime, so the order a session starts and shuts down is written once. A `load` that resolves a repository may return a promise, which is awaited before the trigger is armed; a runtime that publishes no chip omits `setStatus`. `job`, `watch`, and `session-bus` supply only their own arming in `onSessionStart` / `onSessionShutdown` and their own `wakeRequested`. |
 | [`errors.ts`](./errors.ts) | `messageOf`: the one boundary that turns an unknown thrown value into a user-facing line (an `Error` yields its message, anything else is stringified). |
 | [`format.ts`](./format.ts) | Pure text/number formatting shared by renderers: `formatTokens`, `formatCount`, `formatDuration` (`450ms`, `3.2s`, `1m05s`, `2h03m`), `boundedTail` (the end of a joined tail with a `truncated` flag), `stripControlChars`, `sanitize`, `sanitizeLine` — the boundary for untrusted, single-line text — `lineOf` (a value read as one sanitized line), `sanitizeUntrustedLine` / `sanitizeUntrustedText` with `MAX_OUTPUT_LINE` for **program output** (OSC/CSI escapes removed whole, `\r` progress resolved, clipped), and `shortenPath`. |
 | [`timer.ts`](./timer.ts) | The three timer seams and their production defaults, each cancellable and each built so a pending timer never holds the process open: `ArmTimer` / `defaultTimer` (one shot), `RepeatTimer` / `defaultInterval` (repeating), and `abortableSleep` (resolve after a delay, reject `Error("aborted")` when a signal wins). Shared by `wechat`'s bridge and prompt channel, plan's review page, `job`'s and `watch`'s repaint clocks, `bytefly`'s working tick, the browse live channel, and the search throttle — so a test drives a deadline instead of waiting on one. |
 | [`lines.ts`](./lines.ts) | `LineSplitter`, the byte-safe splitter for a stream of program output: buffers bytes and decodes only at a newline, so a UTF-8 character split across two reads survives, and caps an over-long line instead of dropping it. Shared by `job`, `watch`, `check`, and `subagent`. |
 | [`pool.ts`](./pool.ts) | `mapConcurrent`: one async read per entry with at most `limit` calls in flight and results in input order, so a directory listing or a status sweep fans out without an unbounded burst or a per-entry round trip. Shared by `file-browse` and `worktree`. |
+| [`qr.ts`](./qr.ts) | The QR seam shared by `wechat`'s login and `plan`'s shared review link: `qrMatrix` (the module matrix), `qrLines` (Unicode half-block terminal lines of a fixed width), and `qrSvg` (inline markup a page can paste); the `qrcode` package is imported on first use, never at registration. |
 | [`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`, plus an optional `setPromptTimeout` scope for a dialog the human must read something before answering), and `remoteChannel` / `isRemoteTurn` / `supportsCustomUI` / `askHuman` (with an optional file, fallback text, digest preface, and prompt `timeoutMs`) 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`, `gitCommonDir`, `revParse`, `revParseMany` for several revisions in one call, `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. |
@@ -37,10 +39,12 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`path.ts`](./path.ts) | `isInside` (string containment) plus `realPathOfNearest` / `isInsideReal` (symlink-aware): the containment predicates the file-browse, worktree, doc, and plan guards share, and the canonical-path helper the worktree registry keys records by. |
 | [`pdf.ts`](./pdf.ts) | The optional `unpdf` seam shared by `web-access` and `file-read`: `pdfGuidance`, `PdfUnavailableError`, `pdfTextFromResult`, and the lazy `loadPdfExtractor` / `extractPdfText` (an injected extractor wins), so a missing package and a merged-pages result read the same way through either surface. |
 | [`pi-invocation.ts`](./pi-invocation.ts) | `getPiInvocation`: how to launch a nested `pi` process, shared by `subagent` and bytefly's doctor surface. |
+| [`plans/`](./plans/) | The plan document's shared shape, for plan mode and for whatever reads a plan without importing it: [`plans/sections.ts`](./plans/sections.ts) is the one fence-aware scan (`extractSections`, `replaceSection`, `teamSectionBody`, and the `HEADING` / `FENCE` / `normalizeHeadingText` vocabulary), [`plans/team.ts`](./plans/team.ts) parses and renders the `## Team` section (`PlanUnit`, `PlanTeam`, `renderTeam`, `parseTeam`, `readTeam`, `writeTeam`), [`plans/split.ts`](./plans/split.ts) decides whether a proposed split is one (`checkSplit`, its refusals by name, `SHARED_FILES`, `MAX_OWNERS`, `mergeOrder`), and [`plans/store.ts`](./plans/store.ts) holds the one directory rule (`plansDir`) the store writes to and the bus reads from. The switch lives apart in [`plans/setting.ts`](./plans/setting.ts): `SPLIT_SECTION` / `SPLIT_KEY` / `SPLIT_DEFAULT`, the `SPLIT_SETTING_ID` / `SPLIT_SETTING_LABEL` the settings row shows, `splitEnabled(cwd)` and `SPLIT_OFF_NOTE`, so the panel row, approval, and the bus read one key. |
 | [`policy.ts`](./policy.ts) | `createReadOnlyPolicy`: default-deny tool classification from `readOnlyHint` + explicit allow/deny. |
 | [`plan-state.ts`](./plan-state.ts) | The plan-mode flag replayed from the session branch: `PLAN_MODE_ENTRY_TYPE` and `isPlanModeEnabled(entries)`, so `rewind` can refuse a write while planning without importing the plan extension. |
 | [`plan-entry.ts`](./plan-entry.ts) | Plan-mode entry shared by the extension that owns the mode and the one that offers it: `READ_ONLY_SUMMARY` and `PLAN_CONSENT` (one wording for the read-only guarantee), the `PLAN_ENTER_REQUEST` channel with its `PlanEnterRequest` payload, and `requestPlanMode(pi, ctx)` — a request/response over `pi.events` that resolves `false` instead of hanging when `plan` is not loaded, so a command context (which has no `executeTool`) can still enter the mode after asking the user once. |
 | [`rails.ts`](./rails.ts) | Above-editor widget ordering (`goal` → `todo`) and dock-screen suppression, carried on `pi.events`. |
+| [`repo-key.ts`](./repo-key.ts) | The per-repository storage key that outlives one checkout: `repoKeyOf(value)` hashes an identity to `REPO_KEY_LENGTH` hex characters, and `repoKeyFor(pi, cwd)` returns `{ root, key, fromGit }` from the repository's *common* git directory, so every worktree of one repository files state under the same key, while a directory outside git keys on itself. Shared by `session-bus` (sessions, mail, claims) and `plan` (plans). |
 | [`screen-session.ts`](./screen-session.ts) | `withPolledScreen`: mount one `ctx.ui.custom` dock screen — rails suppressed for its lifetime, an optional repaint tick through an injected `RepeatTimer`, and one teardown — handing the mount the host's `tui`, `theme`, `requestRender`, `close`, and `viewportRows`. Shared by `/jobs`, `/watch`, and `/memory`, whose rails window and timer window were the same one. |
 | [`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`. |

package/lib/claims/overlap.ts

@@ -0,0 +1,43 @@
+/**
+ * Claim overlap (pure).
+ *
+ * Two things in this package need the same answer to "do these paths collide?":
+ * `session-bus` when a session claims a path, and plan approval when a proposed
+ * split names its units. They must agree, because a split that passes validation
+ * and then conflicts at claim time — or the reverse — teaches the user that a
+ * claim is arbitrary. So the predicate lives here once and both call it.
+ *
+ * A claim on a directory covers every file below it, in either direction, and a
+ * claim is always a repository-relative, posix-separated path: the caller
+ * normalizes first, because a Windows spelling (`a\b`) and a posix one (`a/b`)
+ * naming the same file must not read as two claims.
+ */
+
+/** A repository-relative path with one separator and no trailing slash. */
+export function normalizeClaimPath(raw: string): string {
+	const posix = raw.trim().replace(/\\/g, "/");
+	const trimmed = posix
+		.replace(/^\.\//, "")
+		.replace(/\/{2,}/g, "/")
+		.replace(/\/+$/, "");
+	return trimmed === "." ? "" : trimmed;
+}
+
+/** Whether one claim covers the other path in either direction. */
+export function claimsConflict(a: string, b: string): boolean {
+	const left = normalizeClaimPath(a);
+	const right = normalizeClaimPath(b);
+	// The root claim (an empty path, or ".") covers everything below it.
+	if (left === "" || right === "") return true;
+	return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+/** The first two prefixes in `paths` that collide, if any. */
+export function findClaimOverlap(paths: readonly string[]): [string, string] | undefined {
+	for (let i = 0; i < paths.length; i++) {
+		for (let j = i + 1; j < paths.length; j++) {
+			if (claimsConflict(paths[i], paths[j])) return [paths[i], paths[j]];
+		}
+	}
+	return undefined;
+}

package/lib/http/router.ts

@@ -1,16 +1,30 @@
 /**
- * The request-envelope helpers both loopback routers apply before a route runs:
- * the request target, and the `Host` allowlist.
+ * The request-envelope helpers both servers apply before a route runs: the
+ * request target, and the `Host` allowlist.
  *
- * Both surfaces bind `127.0.0.1`, so a `Host` naming anything else is a
- * DNS-rebinding attempt against a local page. How strictly a missing `Host` is
- * treated is the caller's decision: the browse server accepts one, because its
- * router is also driven directly from tests and a plain `GET` with no header is
- * not a rebinding, while the review server fails closed.
+ * A server answers to the names it was bound on and nothing else, so a `Host`
+ * naming anything else is a DNS-rebinding attempt against a page the owner
+ * opened. How strictly a missing `Host` is treated is the caller's decision: the
+ * browse server accepts one, because its router is also driven directly from
+ * tests and a plain `GET` with no header is not a rebinding, while the review
+ * server fails closed.
  */
 
-/** The `Host` names a loopback interface, with or without a port. */
-const LOCAL_HOST = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i;
+/** The names a loopback-bound server answers to. */
+export const LOOPBACK_HOSTS: readonly string[] = ["127.0.0.1", "localhost", "[::1]"];
+
+/** The host name in a `Host` header, without its port, lowercased. */
+export function hostHeaderName(host: string): string {
+	const text = host.trim().toLowerCase();
+	if (text.startsWith("[")) {
+		const end = text.indexOf("]");
+		return end > 0 ? text.slice(0, end + 1) : text;
+	}
+	const first = text.indexOf(":");
+	// No colon, or an unbracketed IPv6 address whose colons are not a port.
+	if (first <= 0 || first !== text.lastIndexOf(":")) return text;
+	return /^\d+$/.test(text.slice(first + 1)) ? text.slice(0, first) : text;
+}
 
 /** A request target split into the parts a router matches on. */
 export interface ParsedRequestUrl {
@@ -35,18 +49,31 @@ export function parseRequestUrl(rawUrl: string): ParsedRequestUrl | undefined {
 }
 
 /**
- * Whether the request's `Host` names this loopback server.
+ * Whether the request's `Host` names one of the hosts this server answers to.
  *
  * With `required: false`, only a present, non-empty foreign name is refused, so
  * a header-less request from another caller still routes. With `required: true`,
  * a missing or non-string `Host` is refused too, so the guard cannot be skipped
  * by omitting the header.
  */
-export function isLocalHostHeader(
+export function isAllowedHostHeader(
 	headers: Record<string, string | string[] | undefined>,
-	options: { required: boolean },
+	options: { hosts: readonly string[]; required: boolean },
 ): boolean {
 	const host = headers.host;
 	if (typeof host !== "string" || host === "") return !options.required;
-	return LOCAL_HOST.test(host);
+	const name = hostHeaderName(host);
+	return options.hosts.some((allowed) => hostHeaderName(allowed) === name);
+}
+
+/**
+ * Whether the request's `Host` names this loopback server. A caller that binds
+ * anything other than loopback passes its own names to
+ * {@link isAllowedHostHeader} instead.
+ */
+export function isLocalHostHeader(
+	headers: Record<string, string | string[] | undefined>,
+	options: { required: boolean },
+): boolean {
+	return isAllowedHostHeader(headers, { hosts: LOOPBACK_HOSTS, required: options.required });
 }

package/lib/http/server.ts

@@ -1,14 +1,15 @@
 /**
- * The socket seam shared by the two loopback servers: bind, write a response
- * out, and close.
+ * The socket seam shared by the browser servers: bind, write a response out,
+ * and close.
  *
  * Everything here is behavior a caller cannot get right by accident: a bind on
- * `127.0.0.1` only, an accept-level `error` listener so a transient failure
- * cannot take the host down, a `HEAD` that sends headers and no body, a `filePath`
- * response streamed instead of buffered, a `stream` response opened as an event
- * stream, and a close that is safe to call twice and drops keep-alive
- * connections. What each server does *around* this — which frames an event
- * stream carries, request bodies, session settling — stays with that server.
+ * an address the caller names (loopback unless it asked for more), an
+ * accept-level `error` listener so a transient failure cannot take the host
+ * down, a `HEAD` that sends headers and no body, a `filePath` response streamed
+ * instead of buffered, a `stream` response opened as an event stream, and a
+ * close that is safe to call twice and drops keep-alive connections. What each
+ * server does *around* this — which frames an event stream carries, request
+ * bodies, session settling — stays with that server.
  */
 
 import { createReadStream } from "node:fs";
@@ -16,15 +17,19 @@ import type { IncomingMessage, Server, ServerResponse } from "node:http";
 import type { ServeResponse } from "./response.ts";
 
 /**
- * Bind `server` to `127.0.0.1:port` and resolve the port it actually bound
- * (`0` asks the OS to pick one). Rejects when the bind fails, so a caller that
- * wants a fallback can retry with another port.
+ * Bind `server` to `host:port` and resolve the port it actually bound (`0` asks
+ * the OS to pick one). Rejects when the bind fails, so a caller that wants a
+ * fallback can retry with another port.
+ *
+ * `host` is the address the caller is about to print, never a wildcard by
+ * default: a review shared on a LAN opens exactly one address, so the link the
+ * owner sees is the whole surface.
  */
-export async function bindLoopback(server: Server, port: number): Promise<number> {
+export async function bindHost(server: Server, host: string, port: number): Promise<number> {
 	await new Promise<void>((resolve, reject) => {
 		const onError = (error: Error) => reject(error);
 		server.once("error", onError);
-		server.listen(port, "127.0.0.1", () => {
+		server.listen(port, host, () => {
 			server.off("error", onError);
 			resolve();
 		});
@@ -37,6 +42,15 @@ export async function bindLoopback(server: Server, port: number): Promise<number
 	return typeof address === "object" && address ? address.port : port;
 }
 
+/**
+ * Bind `server` to `127.0.0.1:port` and resolve the port it actually bound
+ * (`0` asks the OS to pick one). Rejects when the bind fails, so a caller that
+ * wants a fallback can retry with another port.
+ */
+export async function bindLoopback(server: Server, port: number): Promise<number> {
+	return bindHost(server, "127.0.0.1", port);
+}
+
 /**
  * Write one routed response: headers first, then no body for `HEAD`, the file
  * for a `filePath` response, or the buffered body.

package/lib/interaction.ts

@@ -20,6 +20,9 @@ import type { ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-co
 /** The host run modes, derived because the package does not export the union. */
 export type InteractionMode = ExtensionContext["mode"];
 
+/** The two languages a remote prompt is rendered in. */
+export type InteractionLanguage = "zh" | "en";
+
 /** The `ctx.ui` property a remote transport marks with the channel that owns its turn. */
 export const INTERACTION_TURN_KEY = "isRemoteTurn";
 
@@ -59,6 +62,8 @@ export interface InteractionChannel {
 	post(text: string, signal?: AbortSignal): Promise<void>;
 	/** Send a local file to the human; resolves true when delivered. */
 	postFile(path: string, name: string, signal?: AbortSignal): Promise<boolean>;
+	/** The language this channel renders prompts in, when it knows one. */
+	language?(): InteractionLanguage;
 	/**
 	 * Widen the bound on the prompts asked inside the returned scope: use it for a
 	 * dialog the human must read something before answering. Returns the restore,
@@ -91,6 +96,11 @@ export function isRemoteTurn(ctx: UIContextCarrier): boolean {
 	return remoteChannel(ctx) !== undefined;
 }
 
+/** The remote channel's prompt language, or undefined for a local turn. */
+export function remoteLanguage(ctx: UIContextCarrier): InteractionLanguage | undefined {
+	return remoteChannel(ctx)?.language?.();
+}
+
 /** Whether a full-screen `ctx.ui.custom` component may be used for this turn. */
 export function supportsCustomUI(ctx: UIContextCarrier): boolean {
 	return ctx.mode === "tui" && !isRemoteTurn(ctx);

package/lib/notice.ts

@@ -11,8 +11,10 @@
  *
  * `content` is what the model reads; `details` is never sent to the model and
  * is the renderer's whole input, so a producer states the facts once and the
- * renderer decides the look. Value-only: constants and pure functions, no
- * state.
+ * renderer decides the look. `burstText` is the one assembly of that content for
+ * a burst of pending outcomes, so a job completion, a watch match, and a bus
+ * message are laid out by the same code. Value-only: constants and pure
+ * functions, no state.
  */
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
@@ -68,6 +70,31 @@ export function noticeMessage(input: NoticeInput): NoticeMessage {
 	return { customType: NOTICE_TYPE, content: input.content, display: true, details: input.details };
 }
 
+/** The parts of one burst of pending outcomes, as the model reads them. */
+export interface BurstTextInput {
+	/** The marker embedded in the injected context, e.g. `[BACKGROUND JOBS]`. */
+	marker: string;
+	/** The counted headline without its colon, e.g. `2 background jobs finished`. */
+	headline: string;
+	/** One line per outcome, already formatted by the caller. */
+	lines: readonly string[];
+	/** A trailing count of the rows the caller left out, e.g. `… 3 more matches`. */
+	more?: string;
+	/** How to read the rest, e.g. 'Run `job logs <id>` for output.'. */
+	hint?: string;
+}
+
+/**
+ * The model-facing text of a burst: marker, counted headline, one line per
+ * outcome, and the caller's own tail. The joins and the colon live here so a
+ * `job` completion, a `watch` match, and a bus message read alike; the wording,
+ * the cap, and the hint stay with the extension that knows them.
+ */
+export function burstText(input: BurstTextInput): string {
+	const { marker, headline, lines, more, hint } = input;
+	return [marker, `${headline}:`, ...lines, ...(more ? [more] : []), ...(hint ? [hint] : [])].join("\n");
+}
+
 /** Whether a conversation message is a notice. */
 export function isNotice(message: AgentMessage): message is NoticeEntry {
 	return message.role === "custom" && (message as { customType?: string }).customType === NOTICE_TYPE;

package/lib/plan-entry.ts

@@ -25,8 +25,8 @@ export const PLAN_ENTER_REQUEST = "my-pi-agent/plan-mode/enter";
 /** One clause describing the read-only guarantee, reused across prompts. */
 export const READ_ONLY_SUMMARY =
 	"write and edit are disabled, bash is limited to read-only git commands, and other mutating tools are blocked; " +
-	"subagent delegation is forced read-only, and the only file write is write_plan (under .pi/plans, or the agent " +
-	"directory outside a repository)";
+	"subagent delegation is forced read-only, and the only file write is write_plan (a plan file in the agent " +
+	"directory)";
 
 /**
  * The consent question, as the user sees it. Shown by `enter_plan_mode` and by
@@ -36,6 +36,11 @@ export const PLAN_CONSENT =
 	`Plan mode is read-only exploration: ${READ_ONLY_SUMMARY}. ` +
 	"Enter plan mode to investigate and propose an approach before making changes?";
 
+/** The short remote consent; the full read-only summary stays in the tool docs. */
+export const PLAN_CONSENT_SHORT =
+	"Enter read-only plan mode? Writes and mutating tools are disabled until you approve a plan.";
+export const PLAN_CONSENT_SHORT_ZH = "进入只读 plan 模式？批准计划前会禁用写入和修改。";
+
 /** What a caller sends on {@link PLAN_ENTER_REQUEST}. */
 export interface PlanEnterRequest {
 	/** The caller's context; `plan` uses it for the footer status. */