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

package/lib/requirements.ts

@@ -208,6 +208,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	},
 	todo: {},
 	goal: {},
+	serve: { notes: ["Without it `/board`, `/browse`, and `/plan review` refuse, naming it."] },
 	board: {},
 	team: { notes: ["`assign` needs `session-bus` loaded to deliver a handoff; without it the card is untouched."] },
 	check: {
@@ -256,8 +257,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	"file-open": {
 		notes: [
 			"The `/open` command and its notification need an interactive UI; the `open_path` tool works without one.",
-			"Launching the OS handler is best-effort: a launcher that fails to start, or exits non-zero on macOS and Linux, is reported; Windows `explorer` can exit non-zero after a successful open.",
-			"The tool result names the target even when the launch fails.",
+			"Launching the OS handler is best-effort — a launcher that fails to start, or exits non-zero on macOS and Linux, is reported, Windows `explorer` can exit non-zero after a successful open, and the tool result names the target either way.",
 		],
 	},
 	memory: {
@@ -322,8 +322,8 @@ export interface ProbeSeams {
 	readJson: (path: string) => JsonReadResult;
 	dirs: DirSeams;
 	platform: NodeJS.Platform;
-	/** Whether the package will actually load this extension this session. */
-	isEnabled: (extension: string) => boolean;
+	/** Why this session is not loading the extension, or undefined when it loads it. */
+	disabledReason: (extension: string) => string | undefined;
 	/** Load an optional package; defaults to a real dynamic import. */
 	loadModule?: (name: string) => Promise<unknown>;
 	/** Resolve the nested-pi command; defaults to {@link getPiInvocation}. */
@@ -718,11 +718,11 @@ function configFindings(extension: string, spec: ExtensionRequirements, seams: P
 /** Probe one extension against its declaration and the current environment. */
 export async function probeExtension(extension: string, seams: ProbeSeams): Promise<ExtensionReport> {
 	const spec = REQUIREMENTS[extension];
-	const enabled = seams.isEnabled(extension);
+	const disabledReason = seams.disabledReason(extension);
 	if (!spec) {
 		return {
 			extension,
-			enabled,
+			enabled: disabledReason === undefined,
 			findings: [
 				{
 					extension,
@@ -733,16 +733,16 @@ export async function probeExtension(extension: string, seams: ProbeSeams): Prom
 			],
 		};
 	}
-	if (!enabled) {
+	if (disabledReason !== undefined) {
 		return {
 			extension,
-			enabled,
+			enabled: false,
 			findings: [
 				{
 					extension,
 					check: "state",
 					severity: "info",
-					detail: "disabled through PI_DISABLED_EXTENSIONS",
+					detail: disabledReason,
 				},
 			],
 		};
@@ -755,7 +755,7 @@ export async function probeExtension(extension: string, seams: ProbeSeams): Prom
 	for (const note of spec.notes ?? []) {
 		findings.push({ extension, check: "platform", severity: "info", detail: note });
 	}
-	return { extension, enabled, findings };
+	return { extension, enabled: true, findings };
 }
 
 /** Probes in flight at once: enough to hide spawn latency, not a burst. */

package/lib/session-label.ts

@@ -1,12 +1,14 @@
 /**
  * The session label: the one name another session addresses this one by.
  *
- * `session-bus` settles a label for every session — the Pi session name, else the
- * working directory's basename, else the id — and the board records the same name
- * on a card it claims, so the two surfaces agree on who "billing-core" is without
- * the board reading the bus. The rules are here rather than in either extension
- * because a label is a shared vocabulary: it is displayed, it is a send target, and
- * it is stored in a card file that outlives one session.
+ * Two vocabularies share this module, and neither copies the other. `session-bus`
+ * settles its own label for a session that did not ask for one — the Pi session name,
+ * else the working directory's basename, else the id. The board names a session for
+ * the team instead: the page's seat, or a preset teammate name drawn from the id, or
+ * `team-agent-` and the id's tail when every preset one is taken — one name on every
+ * surface, and one that cannot drift on a rename. The rules are here rather than in
+ * either extension because a label is a shared vocabulary: it is displayed, it is a
+ * send target, and it is stored in a card file that outlives one session.
  *
  * Value-only: no state, no I/O.
  */
@@ -42,12 +44,90 @@ export function shortId(id: string): string {
  * The bus appends a suffix when two live sessions share one; that decision belongs
  * to the registry, so this is only the name a session would pick for itself.
  */
-export function defaultLabel(sessionName: string | undefined, cwd: string, id: string): string {
+export function defaultLabel(sessionName: string | undefined, cwd: string, id = "session"): string {
 	const directory = cwd.split(/[\\/]/).filter(Boolean).at(-1);
 	const base = normalizeLabel(sessionName, normalizeLabel(directory, "session"));
 	return normalizeLabel(base, `session-${shortId(id)}`);
 }
 
+/** The prefix of the team's name for a session that is not the page's seat. */
+export const TEAM_AGENT_PREFIX = "team-agent-";
+
+/**
+ * The team's name for a session: the prefix and the id's tail.
+ *
+ * A team is addressed by id, not by a name a user chose: an id is unique, so two
+ * sessions cannot settle on one name, and a rename cannot strand the card that
+ * recorded it. The seat is the one name that is a role instead.
+ */
+export function agentLabel(id: string): string {
+	return normalizeLabel(`${TEAM_AGENT_PREFIX}${shortId(id)}`, "team-agent");
+}
+
+/**
+ * The preset teammate names a session with no name of its own draws from.
+ *
+ * Familiar English names, one or two syllables each, short enough to type as a `to`
+ * target: a teammate should read as a person, and `lily` says more than
+ * `team-agent-9f21ac` to the lead who hands it a card.
+ */
+export const TEAMMATE_NAMES = [
+	"tom",
+	"amy",
+	"lily",
+	"jack",
+	"lucy",
+	"mike",
+	"kate",
+	"sam",
+	"bob",
+	"anna",
+	"helen",
+	"peter",
+	"alice",
+	"emma",
+	"jenny",
+	"mary",
+	"linda",
+	"susan",
+	"tina",
+	"ben",
+	"may",
+	"rose",
+	"david",
+	"leo",
+] as const;
+
+/** A 32-bit FNV-1a hash, so one id always starts the draw at the same name. */
+function hashOf(text: string): number {
+	let hash = 0x811c9dc5;
+	for (let index = 0; index < text.length; index += 1) {
+		hash ^= text.charCodeAt(index);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return hash >>> 0;
+}
+
+/**
+ * The preset name a session with none of its own joins under.
+ *
+ * Its id hashes to a starting point in the list, and a name in `taken` walks on to the
+ * next free one; every name taken is `undefined`, so the caller keeps a fallback that
+ * cannot collide. Drawn from the id rather than at random, because the board writes a
+ * card before it joins: one session has to draw one name on every call and after a
+ * restart, so the card, the join, and the roster say the same word. `taken` is
+ * compared case-insensitively, the way a label is addressed.
+ */
+export function presetNameFor(id: string, taken: Iterable<string> = []): string | undefined {
+	const held = new Set([...taken].map((label) => label.toLowerCase()));
+	const start = hashOf(id) % TEAMMATE_NAMES.length;
+	for (let step = 0; step < TEAMMATE_NAMES.length; step += 1) {
+		const name = TEAMMATE_NAMES[(start + step) % TEAMMATE_NAMES.length];
+		if (!held.has(name)) return name;
+	}
+	return undefined;
+}
+
 /**
  * Pi's session name, which is the first choice for a label.
  *
@@ -62,3 +142,45 @@ export function sessionNameOf(ctx: Pick<ExtensionContext, "sessionManager">): st
 		return undefined;
 	}
 }
+
+/**
+ * The session's id, or undefined when the host does not report one.
+ *
+ * Read beside the name because they are the same fact from two sides: a name is how a
+ * person reads a session, an id is how one is filed — a bus record, a card's owner, a
+ * resume. A host that refuses the call is a session with no id, not an error.
+ */
+export function sessionIdOf(ctx: Pick<ExtensionContext, "sessionManager">): string | undefined {
+	try {
+		const id = ctx.sessionManager.getSessionId();
+		return typeof id === "string" && id !== "" ? id : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * `pi.events` channel: a session settled the label its peers address it by.
+ *
+ * Here rather than in `lib/events.ts`, the way `lib/plan-entry.ts` and `lib/http/mount.ts`
+ * keep their own: a label is this module's vocabulary, and both sides of the channel — the
+ * bus that settles one and the footer that draws it — already load this module, so the
+ * literal costs a registration graph nothing and cannot be re-typed on one side.
+ */
+export const SESSION_LABEL_CHANNEL = "my-pi-agent/session-label";
+
+/**
+ * Payload on {@link SESSION_LABEL_CHANNEL}: one session's name on the bus.
+ *
+ * Emitted by `session-bus` whenever it settles or yields a label, and read by bytefly's
+ * footer, which draws it instead of Pi's own session name: the two part company the moment
+ * the board seats a session under a preset teammate name, or a collision appends an id. The
+ * id rides along because the channel reaches every session in the process, and only the one
+ * named here is the reader's own.
+ */
+export interface SessionLabelEvent {
+	/** Pi session id the label belongs to. */
+	id: string;
+	/** The name another session addresses this one by. */
+	label: string;
+}

package/lib/session-roster.ts

@@ -4,7 +4,7 @@
  * The Team tab lists teammates, and `session-bus` owns those records. Neither
  * extension may import the other, and the board must keep working when the bus is
  * not loaded — so the records are read where the bus already put them,
- * `<agentDir>/session-bus/<repo-key>/`, as files rather than through its code. The
+ * `<agent-dir>/session-bus/<repo-key>/`, as files rather than through its code. The
  * directory names, the record fields this reader trusts, and the liveness rule live
  * here once, and `session-bus` imports them, so a layout change cannot land in one
  * copy and not the other.
@@ -158,6 +158,48 @@ async function mailCount(dir: string, stem: string): Promise<number> {
 	}
 }
 
+/**
+ * One session's own label, found by the id it belongs to.
+ *
+ * The record is filed under the repository's key, which a caller without a board store
+ * would have to resolve with git first — and a footer asking for a name that may not
+ * exist should not cost two subprocesses at every session start. So the bus root is
+ * walked instead and the record is matched on its id: a session id belongs to one
+ * session, so the first record that names it is the answer wherever the bus filed it.
+ *
+ * Every miss is ordinary: a machine with no bus, or with records for other sessions
+ * only, answers `undefined` rather than an error.
+ */
+export async function readSessionLabel(agentDir: string, id: string): Promise<string | undefined> {
+	const root = join(agentDir, BUS_DIR_NAME);
+	let keys: string[];
+	try {
+		keys = await readdir(root);
+	} catch {
+		return undefined;
+	}
+	for (const key of keys) {
+		const dir = join(root, key, SESSIONS_DIR_NAME);
+		let names: string[];
+		try {
+			names = await readdir(dir);
+		} catch {
+			continue;
+		}
+		for (const name of names) {
+			if (!name.endsWith(".json")) continue;
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(await readFile(join(dir, name), "utf-8"));
+			} catch {
+				continue;
+			}
+			if (isSessionPayload(parsed) && parsed.id === id) return parsed.label;
+		}
+	}
+	return undefined;
+}
+
 /**
  * Every session the bus has recorded for one repository, or `undefined` when the bus
  * has never been used here.

package/lib/session-tool.ts

@@ -2,7 +2,7 @@
  * The `session` tool, as the extensions that are not `session-bus` call it.
  *
  * `board` and `team` are the user's surface for the team; the bus is the transport
- * underneath, and neither may import it (`test/structure.test.ts`). So the one place
+ * underneath, and neither may import it (`test/boundaries.test.ts`). So the one place
  * that turns a call into a typed answer lives here, next to the tool's name in
  * `lib/tool-names.ts` — two copies would be two copies of the details-shape
  * knowledge, and a bus that renamed a field would be broken in one of them.
@@ -22,6 +22,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { type BusAnswer, requestOverBus } from "./bus-request.ts";
 import { messageOf } from "./errors.ts";
 import { watchingOf } from "./session-roster.ts";
 import { SESSION_TOOL } from "./tool-names.ts";
@@ -54,14 +55,30 @@ export type JoinResult = { ok: true; label: string; watching: Watching } | { ok:
 /** EventBus channel on which a caller asks `session-bus` to join the team for it. */
 export const TEAM_JOIN_REQUEST = "my-pi-agent/team-join/request";
 
+/**
+ * What a join asks for.
+ *
+ * `label` is the name to be on the team as; without one the bus settles its own. `name`
+ * is the separate question of whether that label also becomes Pi's session name — what
+ * `/resume` lists — and it is opt-in, because a join is not a rename: only
+ * `/team join <label>` means "call me this from now on". The footer needs no opt-in: it
+ * draws the label itself, so a plain join moves what the bar names this session.
+ */
+export interface TeamJoinInput {
+	label?: string;
+	wake?: boolean;
+	listen?: boolean;
+	name?: boolean;
+}
+
 /** What a caller sends on {@link TEAM_JOIN_REQUEST}. */
 export interface TeamJoinRequest {
 	/** The caller's context; the bus starts and names through it. */
 	ctx: ExtensionContext;
 	/** What to join as and how to listen. */
-	input: { label?: string; wake?: boolean; listen?: boolean };
-	/** Called once, when the bus has answered. */
-	respond(result: JoinResult): void;
+	input: TeamJoinInput;
+	/** Claimed once, with what the bus answered; the caller settles on that claim. */
+	respond(result: BusAnswer<JoinResult>): void;
 }
 
 /** What a send did. */
@@ -96,49 +113,49 @@ function nestedMessage(result: { content?: Array<{ type: string; text?: string }
 /**
  * How an extension joins the team, whatever kind of context it is holding.
  *
- * Two extensions ask — `board` when the page opens or a card is worked, `team` for
+ * Two extensions ask — `board` when the page opens or a card is claimed, `team` for
  * `/team join` — and both hold a command or a tool context, so the request is the one
  * transport that works from either.
  */
 export interface TeamJoin {
-	/** Join the team, naming this session when `label` is given. Never throws. */
-	join(ctx: ExtensionContext, label?: string): Promise<JoinResult>;
+	/** Join the team as `input.label` when given. Never throws. */
+	join(ctx: ExtensionContext, input?: TeamJoinInput): Promise<JoinResult>;
 }
 
 /** The production join, bound to one extension's `pi`. */
 export function createTeamJoin(pi: Pick<ExtensionAPI, "events" | "getAllTools">): TeamJoin {
 	return {
-		join: (ctx, label) => join(pi, ctx, label === undefined ? {} : { label }),
+		join: (ctx, input) => join(pi, ctx, input ?? {}),
 	};
 }
 
+/** What a caller is told when there is no bus to join: one sentence on both paths. */
+const NO_BUS = "the session bus is not loaded";
+
 /**
  * Join the team: on the bus, named when a label is given, and listening for mail.
  *
  * One call for all three, because that is one act — see `join` in
  * `extensions/session-bus` — and one transport for both kinds of caller: the request
- * travels on `pi.events` and the bus answers it.
+ * travels on `pi.events` and the bus answers it. Pi's session name is not one of the
+ * three: that is `input.name`, which only a caller meaning to rename asks for.
  *
  * With no bus loaded there is no listener, so the answer is the sentence the caller
  * reports rather than a promise that never settles: the `session` tool's presence is
- * the same check `lib/plan-entry.ts` makes, and the listener always answers.
+ * checked here, and the shared handshake refuses the same way if a bus is loaded but
+ * listening for nothing.
  */
 export async function join(
 	pi: Pick<ExtensionAPI, "events" | "getAllTools">,
 	ctx: ExtensionContext,
-	input: { label?: string; wake?: boolean; listen?: boolean } = {},
+	input: TeamJoinInput = {},
 ): Promise<JoinResult> {
-	if (!pi.getAllTools().some((tool) => tool.name === SESSION_TOOL)) {
-		return { ok: false, error: "the session bus is not loaded" };
-	}
-	return new Promise<JoinResult>((resolve) => {
-		let settled = false;
-		const respond = (result: JoinResult): void => {
-			if (settled) return;
-			settled = true;
-			resolve(result);
-		};
-		pi.events.emit(TEAM_JOIN_REQUEST, { ctx, input, respond } satisfies TeamJoinRequest);
+	if (!pi.getAllTools().some((tool) => tool.name === SESSION_TOOL)) return { ok: false, error: NO_BUS };
+	return requestOverBus<JoinResult, TeamJoinRequest>(pi, {
+		channel: TEAM_JOIN_REQUEST,
+		payload: (respond) => ({ ctx, input, respond }),
+		unclaimed: () => ({ ok: false, error: NO_BUS }),
+		failed: (error) => ({ ok: false, error: messageOf(error) }),
 	});
 }
 

package/lib/stray-fields.ts

@@ -18,6 +18,8 @@
  * Value-only, as `lib/` must be: the tables are the callers'.
  */
 
+import { listOf } from "./format.ts";
+
 /** The fields each action reads, keyed in the order the actions are documented. */
 export type ActionFields = Readonly<Record<string, readonly string[]>>;
 
@@ -38,8 +40,11 @@ export function strayField(action: string, args: Record<string, unknown>, fields
 	const named = (field: string): string => {
 		const taking = Object.keys(fields).filter((candidate) => fields[candidate]?.includes(field));
 		if (taking.length === 0) return `${field} belongs to no action`;
-		const verbs = taking.map((one) => `\`${one}\``).join(" and ");
-		return `${verbs} ${taking.length === 1 ? "takes" : "take"} ${stray.length === 1 ? "it" : field}`;
+		const verbs = taking.map((one) => `\`${one}\``);
+		// Two read as "a and b"; three or more take the serial comma, or the list stops saying
+		// where one verb ends and the next begins.
+		const list = verbs.length === 2 ? verbs.join(" and ") : listOf(verbs, "and");
+		return `${list} ${taking.length === 1 ? "takes" : "take"} ${stray.length === 1 ? "it" : field}`;
 	};
 	return `${action} does not act on ${stray.join(", ")}: ${stray.map(named).join("; ")}.`;
 }

package/lib/tool-names.ts

@@ -17,11 +17,12 @@ export const TODO_TOOL = "todo";
 export const GOAL_TOOL = "goal";
 
 /**
- * The `enter_plan_mode` tool. `plan` registers it, and `goal` offers the same
- * phase to the user, so the name is shared: the request channel and the
- * registration probe both look it up.
+ * The `plan` tool. `plan` registers it and `goal` offers the same phase to the user,
+ * so the name is shared: the request channel and the registration probe both look
+ * it up. Its actions are the planning verbs, so one name replaces the five tools
+ * that used to spell them.
  */
-export const PLAN_ENTER_TOOL = "enter_plan_mode";
+export const PLAN_TOOL = "plan";
 
 /** The `subagent` tool, which plan mode pins to read-only delegation. */
 export const SUBAGENT_TOOL = "subagent";
@@ -52,12 +53,6 @@ export const SUBAGENT_READ_ONLY_PARAM = "readOnly";
  */
 export const BOARD_TOOL = "board";
 
-/**
- * The one `board` action that reads. Plan mode admits it and refuses the rest, which
- * is the distinction the tool's `readOnlyHint` cannot carry: the same tool writes.
- */
-export const BOARD_READ_ACTION = "list";
-
 /**
  * The `read_doc` tool. `file-read` registers it, and the plan, rewind, and
  * subagent reader lists carry the name, so the document reader is one reader

package/lib/tui/README.md

@@ -111,17 +111,32 @@ clipped mid-word at the widths the screen runs at.
 
 Resolve colors through a [`tokens.ts`](./tokens.ts) role
 (`paint(theme, role, text)`), never a literal ANSI sequence, hex value, or Pi
-token named inline; a theme swap must re-skin every surface. Use the shared
-`selectionMarker`, `GLYPHS`, `SEPARATORS`, and `STATUS_KEYS` instead of retyping
-their literals, `screenHint` / Pi's `keyHint` for the hint row, and
-`screenFooter` for the hint row with its blank and closing rule.
+token named inline; a theme swap must re-skin every surface. The role table is
+the one place a Pi token is named, its tool vocabulary (`toolTitle`,
+`toolOutput`) included, so a renderer draws a tool block the way it draws a
+list. Use the shared `selectionMarker`, `GLYPHS`, `SEPARATORS`, and `STATUS_KEYS`
+instead of retyping their literals, `screenHint` / Pi's `keyHint` for the hint
+row, and `screenFooter` for the hint row with its blank and closing rule.
 
 A list accents the focused row's label (`labelRole: selected ? "accent" :
 "label"`); the `❯` marker alone is not enough to tell which row is live. The
-hint row colors by role, not by taste: `accent` for the screen's primary action,
-`warning` for one that discards state (a revert, a kill, a stop, a clear, a
-forget), and `error` for one that ends the session. Keys that navigate, scroll,
-or select stay dim, so a colored key is one worth a second thought.
+hint row colors by role, not by taste — `ScreenHint.color` is a `TuiRole`:
+`accent` for the screen's primary action, `warn` for one that discards state (a
+revert, a kill, a stop, a clear, a forget), and `bad` for one that ends the
+session. Keys that navigate, scroll, or select stay `faint`, so a colored key is
+one worth a second thought.
+
+## A hue identifies, a verdict judges
+
+`ok` / `warn` / `bad` say how something *is*, and a surface that shows them is
+making a judgement. `hue1`…`hue5` — blue, purple, pink, green, amber — say only
+which category a row belongs to, which is what a table or a bar needs to be
+told apart at a glance. They are the same tokens in places (green is `success`,
+amber is `warning`), so the two vocabularies do not mix on one surface: a screen
+that paints hues keeps its verdicts to the gauge, a status word, or a feedback
+line, and a hue never lands in a slot that also carries a judgement. Color is
+redundant there — the label, the order, and the printed number already say what
+the hue repeats — so nothing may be encoded by hue alone.
 
 ## Width is columns
 
@@ -160,9 +175,12 @@ hold themed strings in state unless `invalidate()` rebuilds them. A widget is
 derived from state, never authoritative.
 
 Pi renders the whole tree every frame, so a component that derives its lines from
-another one memoizes them with `RenderCache` (keyed on width and the source
-lines' identity) and drops the memo in `invalidate()`. Re-deriving every line per
-frame is what makes a long transcript feel slow.
+another one memoizes them with `RenderCache` — `lines()` keyed on width and the
+source lines' identity, or `keyed()` for a component with no inner component (a
+header's view, a footer's snapshot), keyed on the parts it read: primitives by
+value, an object such as the theme by identity — and drops the memo in
+`invalidate()`. Re-deriving every line per frame is what makes a long transcript
+feel slow.
 
 ## Focus
 

package/lib/tui/chrome.ts

@@ -16,11 +16,12 @@
  * in, and the viewport options are explicit.
  */
 
-import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth, type EditorTheme, type OverlayOptions } from "@earendil-works/pi-tui";
 import { SEPARATORS } from "./glyphs.ts";
 import { BODY_INDENT } from "./indent.ts";
 import { plainRule } from "./rules.ts";
+import { paint, type TuiRole } from "./tokens.ts";
 
 /**
  * `ctx.ui.custom` options that give a screen the whole terminal.
@@ -61,15 +62,15 @@ export function viewportRows(source: ViewportRowsSource | undefined, options: Vi
 }
 
 /**
- * One key-hint entry: plain dim text, or text in a chosen semantic color so a
- * primary action (approve, submit) stands out from the scroll hints.
+ * One key-hint entry: plain faint text, or text in a chosen role so a primary
+ * action (approve, submit) stands out from the scroll hints.
  */
-export type ScreenHint = string | { text: string; color?: ThemeColor };
+export type ScreenHint = string | { text: string; color?: TuiRole };
 
 /**
  * A key-hint footer indented by `indent` columns (default `BODY_INDENT`, which
- * hangs it under a screen's title rule), joined with ` · `. Plain hints are dim;
- * an object hint uses its color (dim when omitted). Hints are added while they
+ * hangs it under a screen's title rule), joined with ` · `. Plain hints are
+ * `faint`; an object hint names a role (`faint` when omitted). Hints are added while they
  * fit, so a narrow terminal drops whole keys instead of truncating one in half.
  * The first hint is always kept; the result is clipped to `width`.
  */
@@ -78,8 +79,8 @@ export function screenHint(theme: Theme, width: number, hints: ScreenHint[], ind
 	// Keep a column for the hint itself, however deep the caller indents.
 	const lead = " ".repeat(Math.max(0, Math.min(Math.floor(indent), target - 1)));
 	const render = (hint: ScreenHint): string =>
-		typeof hint === "string" ? theme.fg("dim", hint) : theme.fg(hint.color ?? "dim", hint.text);
-	const separator = theme.fg("dim", SEPARATORS.item);
+		typeof hint === "string" ? paint(theme, "faint", hint) : paint(theme, hint.color ?? "faint", hint.text);
+	const separator = paint(theme, "faint", SEPARATORS.item);
 	const kept: ScreenHint[] = [];
 	for (const hint of hints) {
 		const candidate = [...kept, hint].map(render).join(separator);
@@ -196,16 +197,16 @@ export function toolDetails<T extends object>(details: unknown): T | undefined {
 	return Object.keys(details).length > 0 ? (details as T) : undefined;
 }
 
-/** Minimal editor theme for an extension-owned inline editor, on semantic tokens. */
+/** Minimal editor theme for an extension-owned inline editor, on semantic roles. */
 export function editorTheme(theme: Theme): EditorTheme {
 	return {
-		borderColor: (text) => theme.fg("borderMuted", text),
+		borderColor: (text) => paint(theme, "rule", text),
 		selectList: {
-			selectedPrefix: (text) => theme.fg("accent", text),
-			selectedText: (text) => theme.fg("accent", text),
-			description: (text) => theme.fg("muted", text),
-			scrollInfo: (text) => theme.fg("dim", text),
-			noMatch: (text) => theme.fg("warning", text),
+			selectedPrefix: (text) => paint(theme, "accent", text),
+			selectedText: (text) => paint(theme, "accent", text),
+			description: (text) => paint(theme, "meta", text),
+			scrollInfo: (text) => paint(theme, "faint", text),
+			noMatch: (text) => paint(theme, "warn", text),
 		},
 	};
 }

package/lib/tui/cursor.ts

@@ -20,6 +20,7 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { viewportRows, type ViewportRowsSource } from "./chrome.ts";
 import { GLYPHS } from "./glyphs.ts";
+import { paint } from "./tokens.ts";
 
 /**
  * Rows that fit for a list of `itemCount`, reserving one extra line when the
@@ -76,11 +77,11 @@ export function wheelDelta(event: TuiMouseEvent): number | undefined {
 
 /** The `❯ ` selection marker (accent) or a same-width blank. */
 export function selectionMarker(theme: Theme, selected: boolean): string {
-	return selected ? theme.fg("accent", `${GLYPHS.prompt} `) : "  ";
+	return selected ? paint(theme, "accent", `${GLYPHS.prompt} `) : "  ";
 }
 
 /**
- * One dim, two-space-indented range row: `showing A–B of N` by default, or
+ * One faint, two-space-indented range row: `showing A–B of N` by default, or
  * `line A–B of N` for a log pane. Clipped to `width`.
  */
 export function formatRange(
@@ -90,7 +91,7 @@ export function formatRange(
 ): string {
 	const label = range.label ?? "showing";
 	const text = `  ${label} ${range.start + 1}–${range.end} of ${range.total}`;
-	return truncateToWidth(theme.fg("dim", text), Math.max(1, width));
+	return truncateToWidth(paint(theme, "faint", text), Math.max(1, width));
 }
 
 /**
@@ -247,6 +248,20 @@ export function isCloseKey(data: string): boolean {
 	return matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"));
 }
 
+/** Shift+Tab arrives as this sequence on terminals without the Kitty protocol. */
+export const SHIFT_TAB = "\u001b[Z";
+
+/**
+ * Whether `data` is Shift+Tab, in either encoding.
+ *
+ * `matchesKey` decodes the Kitty and modifyOtherKeys forms but not the legacy
+ * `\u001b[Z` one, so every screen or editor that binds Shift+Tab needs both tests;
+ * this is that one test.
+ */
+export function isShiftTab(data: string): boolean {
+	return data === SHIFT_TAB || matchesKey(data, Key.shift("tab"));
+}
+
 /**
  * The next scroll offset for a standard navigation key, or `undefined` when
  * `data` is not a navigation key.