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

package/extensions/bytefly/footer/register.ts

@@ -10,7 +10,7 @@
  */
 
 import { homedir } from "node:os";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { SUBAGENT_FINISHED_CHANNEL } from "../../../lib/events.ts";
 import { budgetBody, budgetNotice, budgetState } from "./budget.ts";
 import { createSnapshotReader, type SnapshotReader } from "./collect/snapshot.ts";
@@ -32,6 +32,30 @@ export function registerFooter(pi: ExtensionAPI, deps: FooterDeps = {}): void {
 	const delegation = createDelegationLedger();
 	pi.events.on(SUBAGENT_FINISHED_CHANNEL, (event) => delegation.note(event));
 
+	// The label a peer knows this session by, once the follower below reports one; `null` is
+	// no record, and the bar keeps Pi's own session name.
+	let rosterLabel: string | null = null;
+	/** Whether this session's label is being followed: a tree change re-installs, it is not new. */
+	let followed = false;
+	const followLabel = (ctx: ExtensionContext): void => {
+		if (followed) return;
+		followed = true;
+		// Loaded where it is used: the follower walks the bus's layout on disk and subscribes to
+		// its label, and the registration graph is a budget that may only fall.
+		void import("./collect/label.ts")
+			.then(({ followRosterLabel }) =>
+				followRosterLabel({
+					pi,
+					ctx,
+					agentDir: getAgentDir(),
+					sink: (label) => {
+						rosterLabel = label;
+					},
+				}),
+			)
+			.catch(() => {});
+	};
+
 	/** The installed reader and the budget it was priced with, while a footer is up. */
 	let budget: { limit: number; read: SnapshotReader } | undefined;
 	/** One warning per session: the notice stays in scrollback, and a re-install must not repeat it. */
@@ -41,8 +65,11 @@ export function registerFooter(pi: ExtensionAPI, deps: FooterDeps = {}): void {
 
 	const install = (ctx: ExtensionContext): void => {
 		if (ctx.mode !== "tui") return;
+		// Not awaited: a footer is installed synchronously, and the bar draws Pi's name until the
+		// label lands — which is what a session with no record shows anyway.
+		followLabel(ctx);
 		const config = loadByteflyConfig(ctx.cwd);
-		const read = createSnapshotReader(config, delegation);
+		const read = createSnapshotReader(config, delegation, () => rosterLabel);
 		budget = { limit: config.budget, read };
 
 		ctx.ui.setFooter((tui, _theme, footerData) =>
@@ -57,9 +84,11 @@ export function registerFooter(pi: ExtensionAPI, deps: FooterDeps = {}): void {
 	};
 
 	pi.on("session_start", (_event, ctx) => {
-		// A new session in this process starts from zero: the ledger is not branch state,
-		// and a budget that was already reported is unreported again.
+		// A new session in this process starts from zero: the ledger is not branch state, the
+		// label belongs to the session, and a budget that was already reported is unreported again.
 		delegation.reset();
+		followed = false;
+		rosterLabel = null;
 		warned = false;
 		warnedUnpriced = false;
 		install(ctx);

package/extensions/bytefly/footer/render/footer.ts

@@ -9,14 +9,25 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
+import { RenderCache } from "../../../../lib/tui/render-cache.ts";
+import { snapshotKey } from "./key.ts";
 import { renderLine } from "./layout.ts";
 import { buildLines } from "./lines.ts";
 import type { FooterData, StatusSnapshot, TuiLike } from "../types.ts";
 
-/** A two-line, width-adaptive status bar. */
+/**
+ * A two-line, width-adaptive status bar.
+ *
+ * The bar is derived from a snapshot the reader rebuilds every frame, so it memoizes on a
+ * key rather than on the snapshot's identity: the width, the theme object (its strings are
+ * what the memo holds), and `snapshotKey`'s walk over every field the bar could draw. A
+ * frame where nothing moved costs the key and a comparison; a frame that moved pays the key
+ * as well, which is why the key is measured against the build it saves.
+ */
 class StatusBar implements Component {
 	/** Unsubscribes the branch watcher; set by `createFooter`. */
 	dispose?: () => void;
+	private readonly cache = new RenderCache();
 
 	constructor(
 		private readonly read: () => StatusSnapshot,
@@ -25,15 +36,18 @@ class StatusBar implements Component {
 	) {}
 
 	invalidate(): void {
-		// The bar recomputes from a fresh snapshot each render, so there is
-		// nothing cached to clear. Theme-dependent strings are built in render.
+		// Pi calls this on a theme change; the key holds the theme's identity too, so this
+		// is what drops themed strings a rebuild would otherwise keep.
+		this.cache.invalidate();
 	}
 
 	render(width: number): string[] {
 		const snapshot = this.read();
 		const theme = this.getTheme();
 		const target = Math.max(1, width);
-		return buildLines(snapshot, theme, this.home).map((line) => renderLine(line, target, theme));
+		return this.cache.keyed([target, theme, snapshotKey(snapshot)], () =>
+			buildLines(snapshot, theme, this.home).map((line) => renderLine(line, target, theme)),
+		);
 	}
 }
 

package/extensions/bytefly/footer/render/key.ts

@@ -0,0 +1,46 @@
+/**
+ * A key for one status snapshot: everything the bar draws, and nothing about identity.
+ *
+ * The footer repaints on every frame, and its snapshot is a fresh object each time — the
+ * reader rebuilds it from the session and the host, and prices only what moved — so a memo
+ * cannot key on the snapshot itself. It keys on this string instead, and this string is
+ * derived from the snapshot's own shape: object keys sorted, a `Map` walked as sorted
+ * entries, a list by its items, a primitive by its value.
+ *
+ * That derivation is the point. A hand-written list of the fields a bar reads is exactly
+ * the kind of list that goes stale silently — a field added to `StatusSnapshot` and
+ * forgotten here is a bar that keeps showing the old value until something else moves —
+ * whereas a walk over the object cannot miss a field that exists.
+ *
+ * Lengths prefix strings and collection sizes, so no two different snapshots can produce
+ * one key by running values together.
+ */
+
+import type { StatusSnapshot } from "../types.ts";
+
+/** The key for one snapshot: equal strings mean a frame would draw the same bar. */
+export function snapshotKey(snapshot: StatusSnapshot): string {
+	return keyPart(snapshot);
+}
+
+/** One value's part of the key, tagged by kind so `1` and `"1"` cannot collide. */
+function keyPart(value: unknown): string {
+	if (value === undefined) return "~";
+	if (value === null) return "n";
+	if (typeof value === "number") return String(value);
+	if (typeof value === "boolean") return value ? "t" : "f";
+	if (typeof value === "string") return `${value.length}:${value}`;
+	if (value instanceof Map) {
+		// Sorted, because a Map's insertion order is not a fact about what the bar draws.
+		const entries = [...value.entries()].map(([key, entry]) => `${keyPart(String(key))}=${keyPart(entry)}`);
+		entries.sort();
+		return `m${value.size}{${entries.join(",")}}`;
+	}
+	if (Array.isArray(value)) return `a${value.length}[${value.map(keyPart).join(",")}]`;
+	if (typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		const keys = Object.keys(record).sort();
+		return `o${keys.length}{${keys.map((key) => `${key}:${keyPart(record[key])}`).join(",")}}`;
+	}
+	return String(value);
+}

package/extensions/bytefly/footer/render/layout.ts

@@ -125,16 +125,26 @@ export function renderLine(spec: LineSpec, width: number, theme: Theme): string
 	const target = Math.max(1, width);
 	const states = makeStates(spec);
 
+	// Each pass keeps the line it measured, so a decision never costs a second assembly and
+	// a line that already fits never reaches `truncateToWidth` — which walks the string
+	// character by character (14 µs on a footer line, against 0.2 µs for the width scan) and
+	// is the whole reason this function was measurable per frame.
+	let line = assemble(states, target);
+	let measured = visibleWidth(line);
 	let guard = 0;
-	while (visibleWidth(assemble(states, target)) > target && guard++ < states.length * 8 + 16) {
+	while (measured > target && guard++ < states.length * 8 + 16) {
 		if (!reduceOnce(states)) break;
+		line = assemble(states, target);
+		measured = visibleWidth(line);
 	}
 	// Only once every segment is at its floor do we shrink separators, so the
 	// truncation ellipsis never replaces a separator's content and adjacent
 	// segments always keep at least one column of padding between them.
-	while (visibleWidth(assemble(states, target)) > target) {
+	while (measured > target) {
 		if (!collapseSeparator(states)) break;
+		line = assemble(states, target);
+		measured = visibleWidth(line);
 	}
 
-	return truncateToWidth(assemble(states, target), target, paint(theme, "faint", "…"));
+	return measured > target ? truncateToWidth(line, target, paint(theme, "faint", "…")) : line;
 }

package/extensions/bytefly/footer/render/lines.ts

@@ -1,13 +1,14 @@
 /**
  * Turn a `StatusSnapshot` into the two footer lines.
  *
- * Line 1 — state: left `pwd` and the session name, right the alert, the mode
- * chips, then `⎇ branch · ⑂ worktree · ⊞ 5043 · ◉ 4909`. Line 2 — meters: left
- * the context gauge and usage, right the model and thinking level.
+ * Line 1 — state: left `pwd` and the session name, right the alert, the remaining
+ * status chips, then `⎇ branch · ⑂ worktree · ◉ 4780`. Line 2 — meters: left the
+ * mode, the context gauge, and the usage; right the model and thinking level.
  *
  * The split is one job per row. The state chips change while a session runs, so
  * they ride the line with slack; the meters are the dense row, and a fact that
- * moves onto the top row is one the bottom row stops dropping to fit.
+ * moves onto the top row is one the bottom row stops dropping to fit. The mode
+ * leads the meters because it qualifies every number after it.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
@@ -19,6 +20,7 @@ import {
 	costSegment,
 	delegationSegment,
 	modelSegment,
+	modeSegment,
 	modesSegment,
 	portsSegment,
 	pwdSegment,
@@ -46,14 +48,15 @@ export function buildLines(snapshot: StatusSnapshot, theme: Theme, home: string
 			modesSegment(snapshot, theme),
 			branchSegment(snapshot, theme),
 			worktreeSegment(snapshot, theme),
-			// Last, so the two ports form one run behind the location chips. A page starting
-			// or stopping then changes the end of the line, and `⎇ branch · ⑂ worktree` stays
-			// the adjacent pair a reader scans for where the work lands.
+			// Last, so the page port rides behind the location chips. A page starting or
+			// stopping then changes the end of the line, and `⎇ branch · ⑂ worktree` stays the
+			// adjacent pair a reader scans for where the work lands.
 			portsSegment(snapshot, theme),
 		]),
 	};
 
 	const line2Left = defined([
+		modeSegment(snapshot, theme),
 		contextSegment(snapshot, theme),
 		windowSegment(snapshot, theme),
 		costSegment(snapshot, theme),

package/extensions/bytefly/footer/render/segments.ts

@@ -24,7 +24,7 @@ import {
 	thinkingColor,
 	truncateLabel,
 } from "./format.ts";
-import { compactStatus, dropStatusDetail } from "./status.ts";
+import { compactStatus } from "./status.ts";
 import type { Segment, StatusSnapshot } from "../types.ts";
 
 /** Tertiary text: paths and de-emphasized meters. */
@@ -55,7 +55,11 @@ export function pwdSegment(snapshot: StatusSnapshot, theme: Theme, home: string
 }
 
 export function sessionSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
-	const name = snapshot.sessionName ? sanitizeLine(snapshot.sessionName) : "";
+	// The roster's label first: Pi's session name is what the terminal calls this session, and
+	// the label is what a card, a handoff, and `/team` use. No record means no team, so the bar
+	// keeps the name the user knows.
+	const raw = snapshot.rosterLabel ?? snapshot.sessionName;
+	const name = raw ? sanitizeLine(raw) : "";
 	if (!name) return null;
 	const short = truncateLabel(name, CONFIG.sessionLabelMax);
 	// Brackets and a brighter token keep the session name from reading as a
@@ -101,41 +105,23 @@ export function worktreeSegment(snapshot: StatusSnapshot, theme: Theme): Segment
 }
 
 /**
- * The pages this session is serving, as one cluster.
+ * The session's page port, while anything is served on it.
  *
- * The board and file-browse chips say one thing — a page is up on this port — so they
- * share a segment, a weight, and a floor. Read separately they were a mode chip and a
- * port chip: `▤ 5043` rode the mode weight and outlived `◉ 4909` by four columns, which
- * made two facts of the same kind look like two kinds of fact. Shared, they also drop
- * together, and the surviving form is the pair of glyphs, so a bar too narrow for a port
- * still says a page is up.
+ * One server serves every page of a session, so there is one number to draw: the chip
+ * the `serve` extension publishes, with the glyph alone as the form that survives a bar
+ * too narrow for a port.
  */
 export function portsSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
-	const open = [
-		{ key: CONFIG.boardStatusKey, icon: CONFIG.icons.board },
-		{ key: CONFIG.browseStatusKey, icon: CONFIG.icons.browse },
-	]
-		.filter((entry) => snapshot.statuses.has(entry.key))
-		.map((entry) => ({
-			icon: paint(theme, "ok", entry.icon),
-			port: chipLabel(snapshot.statuses.get(entry.key) ?? ""),
-		}));
-	if (open.length === 0) return null;
-	const joined = (separator: string): string =>
-		open
-			.map((entry) => (entry.port ? `${entry.icon} ${paint(theme, "accent", entry.port)}` : entry.icon))
-			.join(separator);
-	// Widest first: the item separator, then a single space, then the glyphs alone. A
-	// one-page session has two forms; two pages sharing a padded bar have three.
-	const forms = [
-		...new Set([joined(faint(theme, CONFIG.separators.item)), joined(" "), open.map((entry) => entry.icon).join(" ")]),
-	];
+	const chip = snapshot.statuses.get(CONFIG.httpStatusKey);
+	if (chip === undefined) return null;
+	const icon = paint(theme, "ok", CONFIG.icons.http);
+	const port = chipLabel(chip);
 	return {
 		id: "ports",
 		weight: 3,
 		droppable: true,
 		separator: faint(theme, CONFIG.separators.item),
-		forms,
+		forms: [...new Set([port ? `${icon} ${paint(theme, "accent", port)}` : icon, icon])],
 	};
 }
 
@@ -169,21 +155,36 @@ export function alertSegment(snapshot: StatusSnapshot, theme: Theme): Segment |
 	};
 }
 
+/**
+ * The mode: `≡ plan` while planning, `▶ auto` otherwise.
+ *
+ * Plan owns the flag, so the presence of its status key is what the bar reads; the
+ * mode's word and colour are the bar's own, so neither the plan file name nor a
+ * truncated chip can reach it. Planning wears `warn`, the same role the composer's
+ * border takes while it is on. It leads the resource line, before the gauge, so the
+ * mode is read before how much room is left. A session without `plan` still reads
+ * `auto`: that is the mode it is in.
+ */
+export function modeSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
+	if (snapshot.statuses.has(CONFIG.planStatusKey)) {
+		const plan = paint(theme, "warn", `${CONFIG.icons.planMode} ${CONFIG.labels.planMode}`);
+		return { id: "mode", weight: 1, droppable: false, separator: "", forms: [plan, compactStatus(plan)] };
+	}
+	const auto = paint(theme, "accent", `${CONFIG.icons.autoMode} ${CONFIG.labels.autoMode}`);
+	return { id: "mode", weight: 1, droppable: false, separator: "", forms: [auto] };
+}
+
 export function modesSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
 	const others = [...snapshot.statuses.entries()]
 		.filter(
 			([key]) =>
+				key !== CONFIG.planStatusKey &&
 				key !== CONFIG.worktreeStatusKey &&
-				key !== CONFIG.boardStatusKey &&
-				key !== CONFIG.browseStatusKey &&
+				key !== CONFIG.httpStatusKey &&
 				!isAlert(key),
 		)
 		.sort(([a], [b]) => a.localeCompare(b))
-		.map(([key, value]) => {
-			const status = sanitize(value);
-			// The plan chip trails the plan file name; the slot shows the mode only.
-			return key === CONFIG.planStatusKey ? dropStatusDetail(status) : status;
-		})
+		.map(([, value]) => sanitize(value))
 		.filter(Boolean);
 	if (others.length === 0) return null;
 	const full = others.join(faint(theme, CONFIG.separators.item));
@@ -193,7 +194,7 @@ export function modesSegment(snapshot: StatusSnapshot, theme: Theme): Segment |
 	const icons = others.map((status) => compactStatus(status)).join(" ");
 	return {
 		id: "statuses",
-		// Weight 2, ahead of the branch: a mode is stated again by the session, while
+		// Weight 2, ahead of the branch: a status is stated again by the session, while
 		// `⎇` is the only thing on the bar that says where the work will land.
 		weight: 2,
 		droppable: true,
@@ -212,7 +213,9 @@ export function contextSegment(snapshot: StatusSnapshot, theme: Theme): Segment
 	const forms = widths.map((blocks) =>
 		blocks > 0 ? `${gaugeBar(theme, { percent, blocks, role, emptyRole: "faint" })} ${percentText}` : percentText,
 	);
-	return { id: "context", weight: 1, droppable: false, separator: "", forms };
+	// The mode always leads this segment, so the separator prints on every frame;
+	// the gauge's offset is the mode's width, not whether one is present.
+	return { id: "context", weight: 1, droppable: false, separator: faint(theme, CONFIG.separators.item), forms };
 }
 
 export function windowSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {

package/extensions/bytefly/footer/render/status.ts

@@ -29,14 +29,3 @@ export function compactStatus(status: string): string {
 	const text = tokens.length === 2 && /^\d+$/.test(tokens[1]) ? `${icon}${tokens[1]}` : icon;
 	return `${prefix}${text}${suffix}`;
 }
-
-/**
- * Drop a status's trailing ` · detail` while keeping its SGR styling.
- *
- * The `plan-mode` chip carries the plan file name as detail (`≡ plan · name`);
- * the bar shows only the mode. Matching `[^ESC]*` removes the visible suffix
- * without consuming the closing reset, so the chip's color stays balanced.
- */
-export function dropStatusDetail(status: string): string {
-	return status.replace(/ · [^\x1b]*/, "");
-}

package/extensions/bytefly/footer/types.ts

@@ -84,6 +84,13 @@ export interface StatusSnapshot {
 	cwd: string;
 	/** Session name set by the user, `null` when unnamed. */
 	sessionName: string | null;
+	/**
+	 * The name peers address this session by, when the bus has recorded one.
+	 *
+	 * `null` means no record — bytefly runs without the bus and the bar keeps Pi's own
+	 * session name, which is all a session that never joined has.
+	 */
+	rosterLabel: string | null;
 	/** Branch name, `null` when not in a repository, `"detached"` on detached HEAD. */
 	branch: string | null;
 	/** Extension status texts (from `ctx.ui.setStatus`), including `worktree`. */

package/extensions/bytefly/header/component.ts

@@ -16,6 +16,7 @@ import { screenHint } from "../../../lib/tui/chrome.ts";
 import { keyHintText } from "../../../lib/tui/glyphs.ts";
 import { BODY_INDENT } from "../../../lib/tui/indent.ts";
 import { RULE_GLYPH } from "../../../lib/tui/rules.ts";
+import { RenderCache } from "../../../lib/tui/render-cache.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { HEADER_CONFIG, type HeaderHeight, type HelpEntry } from "./config.ts";
 import { identityCells } from "./identity.ts";
@@ -69,11 +70,7 @@ function helpParts(entry: HelpEntry): { key: string; description: string } {
 
 /** The themed header component. */
 export class ByteflyHeader implements Component {
-	private cachedWidth: number | null = null;
-	private cachedTheme: Theme | undefined;
-	private cachedView = "";
-	private cachedKeys = "";
-	private cachedLines: string[] = [];
+	private readonly cache = new RenderCache();
 
 	constructor(
 		private readonly getTheme: () => Theme,
@@ -82,7 +79,7 @@ export class ByteflyHeader implements Component {
 	) {}
 
 	invalidate(): void {
-		this.cachedWidth = null;
+		this.cache.invalidate();
 	}
 
 	/**
@@ -97,20 +94,7 @@ export class ByteflyHeader implements Component {
 		const view = this.view();
 		const viewKey = `${view.showVersion}:${view.halfBlocks}:${view.pad}:${view.latest ?? ""}:${view.rows ?? ""}`;
 		const keys = this.keySignature();
-		if (
-			this.cachedWidth === w &&
-			this.cachedTheme === theme &&
-			this.cachedView === viewKey &&
-			this.cachedKeys === keys
-		) {
-			return this.cachedLines;
-		}
-		this.cachedLines = this.build(w, theme, view);
-		this.cachedWidth = w;
-		this.cachedTheme = theme;
-		this.cachedView = viewKey;
-		this.cachedKeys = keys;
-		return this.cachedLines;
+		return this.cache.keyed([w, theme, viewKey, keys], () => this.build(w, theme, view));
 	}
 
 	/** The chord of every help binding, so a rebind repaints the help rows. */

package/extensions/bytefly/header/config.ts

@@ -93,7 +93,7 @@ export const HEADER_CONFIG: HeaderConfig = {
 			{ binding: "app.thinking.toggle", description: "to expand thinking" },
 			{ binding: "app.model.select", description: "to select model" },
 			{ binding: "app.model.cycleForward", description: "to cycle models" },
-			{ binding: "app.thinking.cycle", description: "to cycle thinking" },
+			{ raw: "shift+tab", description: "to toggle plan" },
 			{ binding: "app.editor.external", description: "for external editor" },
 		],
 		[

package/extensions/bytefly/index.ts

@@ -1,14 +1,15 @@
 /**
- * bytefly — the package's terminal chrome and diagnostics, composed from eleven
+ * bytefly — the package's terminal chrome and diagnostics, composed from twelve
  * feature folders: `header/` (the themed startup mark and version), `footer/`
  * (the two-line, width-adaptive status bar with its price calculation),
  * `message/` (the user-message nameplate), `notice/` (the shared transcript
  * notice renderer), `block/` (the unified tool-block frame), `separator/` (the
- * transcript turn rule), `working/` (the live run line on Pi's working row),
- * `panel/` (the unified `/bytefly` screen and its
+ * transcript turn rule), `working/` (the live run line on the composer's top
+ * border), `panel/` (the unified `/bytefly` screen and its
  * `doctor` report), `doctor/` (the `run_doctor` tool and its session-scoped
- * probe runtime), `notify/` (OS notifications for unattended runs), and
- * `update/` (Pi's package list, the host suppression, and the header marker).
+ * probe runtime), `notify/` (OS notifications for unattended runs), `mode/`
+ * (the editor's Shift+Tab plan-mode toggle and its border), and `update/` (Pi's
+ * package list, the host suppression, and the header marker).
  *
  * The header, footer, turn rule, and working line are installed
  * only in interactive (`tui`) sessions, and are always on; the user-message
@@ -22,7 +23,7 @@
  * Load with:  pi --extension ./extensions/bytefly
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
 import { registerToolBlocks } from "./block/register.ts";
 import { registerChrome } from "./chrome.ts";
@@ -87,4 +88,29 @@ export default function bytefly(pi: ExtensionAPI, deps: ByteflyDeps = {}): void
 	// the one repaint hook rather than installing a header of its own.
 	registerPiRelease(pi, piUpdates, { ...deps.release, onUpdate: () => header.refresh() });
 	registerPanel(pi, { doctor, update, discover: deps.extensions?.discover });
+
+	// Shift+Tab is a chord Pi reserves for the thinking cycle, so the mode key is
+	// an editor rather than a shortcut. It loads on the first TUI session and only
+	// when `plan` is loaded, so a session without it keeps Pi's key and pays for
+	// nothing; the mode module owns that availability check.
+	let detachModeKey: (() => void) | undefined;
+	let modeEpoch = 0;
+	const installModeKey = async (ctx: ExtensionContext): Promise<void> => {
+		const epoch = ++modeEpoch;
+		detachModeKey?.();
+		detachModeKey = undefined;
+		if (ctx.mode !== "tui") return;
+		const { attachModeKey } = await import("./mode/editor.ts");
+		// A shutdown or a newer session may land while the module loads; the stale
+		// reply must not install an editor nothing will release.
+		if (epoch !== modeEpoch) return;
+		detachModeKey = attachModeKey(pi, ctx);
+	};
+	pi.on("session_start", (_event, ctx) => installModeKey(ctx));
+	pi.on("session_tree", (_event, ctx) => installModeKey(ctx));
+	pi.on("session_shutdown", () => {
+		modeEpoch++;
+		detachModeKey?.();
+		detachModeKey = undefined;
+	});
 }

package/extensions/bytefly/mode/editor.ts

@@ -0,0 +1,115 @@
+/**
+ * The Shift+Tab chord at the main editor: the plan-mode toggle and the border
+ * that says which mode the composer is in, with the live working line riding it.
+ *
+ * Pi reserves `app.thinking.cycle` on Shift+Tab, so an extension shortcut for the
+ * key is refused. The editor is the narrower place to own it: an overlay or a
+ * picker has focus instead, so a dialog keeps its own Shift+Tab. Attaching also
+ * unsets the built-in cycle binding, because a key that acts and a key the help
+ * still claims are two different answers to the same press.
+ *
+ * Replacing Pi's editor means opting back into what that editor did:
+ * `embedWorkingStatus` is what makes the host hand the working indicator over for
+ * the top border, as Pi's own editor asks for. Without it the indicator falls back
+ * to a row above the composer, and the border would carry the mode colour alone.
+ *
+ * The mode is plan's to own; this module only asks over the shared channel and
+ * reads the branch for the border. Attach once per session and release with the
+ * returned cleanup, which reverts only the editor and binding it still owns.
+ * Without `plan` there is nothing to toggle, so attach does nothing and Pi keeps
+ * its thinking-cycle chord.
+ */
+
+import {
+	CustomEditor,
+	type ExtensionAPI,
+	type ExtensionContext,
+	type KeybindingsManager as AppKeybindingsManager,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { type EditorTheme, getKeybindings, type KeybindingsManager, type TUI } from "@earendil-works/pi-tui";
+import { isPlanExtensionLoaded, requestPlanToggle } from "../../../lib/plan-entry.ts";
+import { isPlanModeEnabled } from "../../../lib/plan-state.ts";
+import { isShiftTab } from "../../../lib/tui/cursor.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+
+/** What the editor reads on every input and frame. */
+interface ModeEditorOptions {
+	/** Ask the mode's owner to flip it. */
+	onToggle: () => void;
+	/** The branch is the truth, whoever toggled it. */
+	isPlanning: () => boolean;
+	/** The role theme, read each frame so a theme change repaints. */
+	theme: () => Theme;
+}
+
+/** The composer with Shift+Tab bound to plan mode and its border to the mode's own colour. */
+export class ModeEditor extends CustomEditor {
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		keybindings: KeybindingsManager,
+		private readonly options: ModeEditorOptions,
+	) {
+		// Pi's manager carries the resolved keybindings config on top of the TUI one;
+		// the editor only calls `matches()`, which both provide. The option is the same
+		// one Pi's own editor sets, so the working line lands on this border instead of
+		// in a row of its own above the composer.
+		super(tui, theme, keybindings as unknown as AppKeybindingsManager, { embedWorkingStatus: true });
+	}
+
+	override handleInput(data: string): void {
+		if (isShiftTab(data)) {
+			this.options.onToggle();
+			return;
+		}
+		super.handleInput(data);
+	}
+
+	override render(width: number): string[] {
+		// The two roles the footer's mode segment draws, so the bar and the composer agree.
+		const role = this.options.isPlanning() ? "warn" : "accent";
+		this.borderColor = (text) => paint(this.options.theme(), role, text);
+		return super.render(width);
+	}
+}
+
+/** The binding the editor takes over; Pi's default chord for the thinking cycle. */
+const THINKING_CYCLE = "app.thinking.cycle";
+
+/**
+ * Install the mode editor and take Shift+Tab from the thinking cycle, or return
+ * `undefined` when the `plan` extension is not loaded.
+ *
+ * Returns an idempotent cleanup. It clears the editor only while ours is the
+ * installed factory, and restores the binding only while the empty override it
+ * wrote is still there, so a later extension's editor or binding is never undone.
+ */
+export function attachModeKey(
+	pi: Pick<ExtensionAPI, "events" | "getAllTools">,
+	ctx: ExtensionContext,
+): (() => void) | undefined {
+	if (!isPlanExtensionLoaded(pi)) return undefined;
+	const factory = (tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) =>
+		new ModeEditor(tui, theme, keybindings, {
+			onToggle: () => {
+				void requestPlanToggle(pi, ctx);
+			},
+			isPlanning: () => isPlanModeEnabled(ctx.sessionManager.getBranch()),
+			theme: () => ctx.ui.theme,
+		});
+	const bindings = getKeybindings();
+	const previous = bindings.getUserBindings()[THINKING_CYCLE];
+	ctx.ui.setEditorComponent(factory);
+	bindings.setUserBindings({ ...bindings.getUserBindings(), [THINKING_CYCLE]: [] });
+
+	return () => {
+		if (ctx.ui.getEditorComponent() === factory) ctx.ui.setEditorComponent(undefined);
+		const current = bindings.getUserBindings()[THINKING_CYCLE];
+		if (!Array.isArray(current) || current.length > 0) return;
+		const restored = { ...bindings.getUserBindings() };
+		if (previous === undefined) delete restored[THINKING_CYCLE];
+		else restored[THINKING_CYCLE] = previous;
+		bindings.setUserBindings(restored);
+	};
+}