@hank-warren/pi-statusline 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @hank-warren/pi-statusline
 
+## 0.10.0
+
+### Minor Changes
+
+- Let other extensions provide custom statusline items as in-process functions through the `pi-statusline:custom-items:request` event, without shell commands or a process spawn on each refresh.
+
+  Registered items receive the same session payload as command items and share their refresh scheduler, timeouts, failure grace period, and output sanitization. Providers can return `null` to hide an item, receive an abort signal on timeout, and replace an existing registration by id.
+
+  The `/statusline` custom item list identifies extension-provided rows and persists their enabled state. Settings can pin their order and override refresh intervals and timeouts; existing command items keep priority when an id collides. Providers are discovered at interactive session start and whenever `/statusline` opens, independently of extension load order.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -104,7 +104,9 @@ Requires a Nerd Font new enough to include the codicon brand glyphs (v3.5.0+); o
 
 ## Custom items
 
-Everything above is built in. **Custom items** are the escape hatch: each one runs a shell command, and its output becomes a segment on line 1, after the usage meters and before the worktree line. This is how a personal metric — a self-hosted quota pool, a deploy status, an on-call flag — gets onto the statusline without being packaged for everybody else.
+Everything above is built in. **Custom items** are the escape hatch: each one produces one line, and that line becomes a segment on line 1, after the usage meters and before the worktree line. This is how a personal metric — a self-hosted quota pool, a deploy status, an on-call flag — gets onto the statusline without being packaged for everybody else.
+
+A value comes from one of two places: a **shell command** you configure (below), or a **function another extension registers** ([Providing an item from an extension](#providing-an-item-from-an-extension)). They share one scheduler, one timeout, one failure grace and one row in `/statusline`.
 
 The contract is deliberately [Claude Code's status line](https://docs.claude.com/en/docs/claude-code/statusline) contract: a command, JSON about the session on **stdin**, one line on **stdout**, ANSI colors passed through. A script written for Claude Code runs here mostly unchanged (see [differences](#differences-from-claude-codes-status-line)).
 
@@ -136,12 +138,72 @@ By hand, items live under `customItems` in `~/.pi/agent/statusline-settings.json
 | `refreshInterval` | no | Seconds between forced re-runs, on top of the event-driven ones. Omit for event-driven only. |
 | `timeout` | no | Seconds before the command is killed. Default `5`, capped at `30`. |
 | `enabled` | no | `false` hides the item and stops it running. This is the one field `/statusline` writes. |
-| `type` | no | Accepted for entries pasted from Claude Code, where it is `"command"`. Any other value is preserved but not run. |
+| `type` | no | `"command"` (the default, and what an entry pasted from Claude Code carries) or `"extension"` for an item another extension provides. Any other value is preserved but not run. |
 
 Items render in configuration order, each as its own ` | `-separated segment.
 
 **The file is read when a session starts and whenever `/statusline` opens.** After editing it by hand, open `/statusline` and press Esc to load the change into the running session; nothing watches the file.
 
+### Providing an item from an extension
+
+A command is the right escape hatch for a one-off script, and the wrong shape for anything that wants to be a package: the script has to be on `PATH` on every host, it is updated by whatever put it there rather than by pi, its config lives outside any package, and it costs a process spawn per refresh for a value that could be a function call.
+
+So an extension can provide the value directly. pi-statusline emits one event carrying a `register` callback; nothing here imports a provider, and a provider imports nothing from here — the event name is the whole coupling.
+
+```ts
+export default function myProvider(pi: ExtensionAPI): void {
+  pi.events?.on("pi-statusline:custom-items:request", (payload) => {
+    const register = (payload as { register?: unknown }).register as
+      | ((item: {
+          id: string;
+          run: (payload: Record<string, unknown>, signal: AbortSignal) => Promise<string | null>;
+          refreshInterval?: number;
+          timeoutMs?: number;
+        }) => boolean)
+      | undefined;
+    if (typeof register !== "function") return;
+
+    const accepted = register({
+      id: "quota",
+      refreshInterval: 60,
+      timeoutMs: 5_000,
+      run: async (_session, signal) => {
+        const response = await fetch("http://localhost:9000/quota", { signal });
+        if (!response.ok) throw new Error(`quota feed ${response.status}`);
+        const { remaining } = (await response.json()) as { remaining: number };
+        return remaining > 0 ? `\u001b[32m${remaining}%\u001b[0m` : null;
+      },
+    });
+    // Refused only for an unusable `id` or `run`. Nothing else reports it, so a
+    // provider that drops this sees a segment that simply never appears.
+    if (!accepted) throw new Error("pi-statusline refused the quota item");
+  });
+}
+```
+
+The contract is the command contract, minus the process:
+
+- `payload` is **exactly the JSON a command gets on stdin**, already parsed, and built fresh for each run — a script ported into an extension reads the same fields.
+- The return value is the segment: one line, [sanitised the same way](#what-the-command-should-print) and capped at 120 characters. `null`, `undefined` or `""` hides the item.
+- **Throwing is failing.** The message is what `/statusline` shows, and it counts against the same three-failure grace as a non-zero exit.
+- `signal` aborts at `timeoutMs` (default 5s, capped at 30s). A run that ignores it is not awaited past the deadline; its late value is dropped.
+- `register` is idempotent on `id`: registering again replaces the function and cancels the run in flight, so a provider can re-register whenever its configuration changes.
+- `register` **returns `false`** if the `id` is empty or `run` is not a function. It never throws — a throw here would be reported as *your* extension failing rather than as a registration pi-statusline refused — and a refused item has no row and no error anywhere, so the boolean is the only place a typo is visible.
+
+**The event is emitted when a session starts and again every time `/statusline` opens**, in interactive mode only. A provider therefore does not have to load before pi-statusline — subscribe in your factory and the request will come.
+
+There is no `unregister`. A registration lives as long as **pi-statusline's own** extension instance, not the provider's: re-registering the same `id` replaces it, and everything is discarded when pi-statusline reloads. A provider that is unloaded mid-session without pi-statusline reloading leaves its `run` behind, still being called on the refresh interval — in practice a `/reload` reloads both, so this is a note rather than a caveat.
+
+The settings file still owns **order and enabled**:
+
+| Entry in `statusline-settings.json` | What happens |
+|---|---|
+| none | the item is appended after your own, switched on |
+| `{ "id": "quota", "type": "extension" }` | binds there: your position, your `enabled`, and any `refreshInterval`/`timeout` you name overrides the provider's |
+| an entry with a `command` and the same `id` | **conflict.** Your command keeps running and the row reads `id also provided by an extension — remove one`; an extension never silently takes over a row you wrote |
+
+Switching an extension's item off in `/statusline` writes `{ "id": "quota", "type": "extension", "enabled": false }` to the file — that entry is also how you give it a fixed position among your other items. Rows for these items are tagged `(extension)` in the submenu.
+
 ### When a command runs
 
 - at session start,
@@ -186,7 +248,7 @@ The **first line of stdout** becomes the segment. Anything after it is ignored
 
 Failures never reach the agent — the statusline is best-effort and stays silent. A failing item keeps its last good value for up to three consecutive failures, then drops it. That grace is deliberate in both directions: one blip (a laptop between networks) should not blank a working display, and a value that has quietly gone stale is worse than an empty slot, because the number stays plausible while describing a world that has moved on.
 
-To see what an item is doing, open `/statusline` → **Custom item list**. Each row shows its current value, or why there isn't one: `disabled`, `missing command`, `exit 3: …`, `timed out after 5s`, `empty output`, or `no value yet`. Enter toggles an item on or off; commands themselves are edited in the file.
+To see what an item is doing, open `/statusline` → **Custom item list**. Each row shows its current value, or why there isn't one: `disabled`, `exit 3: …`, `timed out after 5s`, `empty output`, `no value yet`, or — for an entry with no command — `no command; waiting for an extension to register this id`. Enter toggles an item on or off; commands themselves are edited in the file.
 
 ### Keep it fast
 

package/custom.ts

@@ -4,12 +4,20 @@ import { platform } from "node:process";
 /**
  * User-defined statusline segments, modelled on Claude Code's `statusLine`.
  *
- * Each item is a shell command that receives a JSON snapshot of the session on
- * stdin and prints one line to stdout. That contract is deliberately the same
- * one Claude Code uses, so an existing statusline script mostly ports over; the
- * differences are that pi renders each item as one *segment* of line 1 rather
- * than owning the whole row, and that the payload's usage numbers are remaining
- * percentages (see `custom-items.md` in the README).
+ * An item's value comes from one of two places. The original is a **shell
+ * command** that receives a JSON snapshot of the session on stdin and prints
+ * one line to stdout — deliberately Claude Code's contract, so an existing
+ * statusline script mostly ports over; the differences are that pi renders each
+ * item as one *segment* of line 1 rather than owning the whole row, and that
+ * the payload's usage numbers are remaining percentages (see the README).
+ *
+ * The second is a **function another extension registers** over `pi.events`,
+ * which gets the same payload as an object and returns the same one line. That
+ * exists because a command forces anything serious onto PATH, into a config
+ * file outside any package, and into a process spawn per refresh, for a value
+ * the host could compute in-process. Both kinds run through one scheduler here:
+ * there is no second code path for turn ends, intervals, overlap, timeouts or
+ * the failure grace.
  */
 
 /** How long a command may run before it is killed, when it names no timeout. */
@@ -31,9 +39,66 @@ export const EVENT_MIN_INTERVAL_MS = 1_000;
  * broken loses it.
  */
 export const FAILURE_GRACE = 3;
-/** Longest rendered value kept from a command, before the line is truncated. */
+/** Longest rendered value kept from an item, before the line is truncated. */
 export const MAX_OUTPUT_WIDTH = 120;
 
+/**
+ * The event pi-statusline emits to collect items from other extensions.
+ *
+ * This name is the entire coupling between the statusline and a provider:
+ * nothing here imports a provider, and a provider imports nothing from here.
+ * Changing the string is a breaking change for every provider in the wild.
+ */
+export const CUSTOM_ITEMS_REQUEST_EVENT = "pi-statusline:custom-items:request";
+
+/**
+ * A registered item's value function.
+ *
+ * `payload` is the object the command path serialises onto stdin, built fresh
+ * for each run. `signal` aborts at the item's timeout; a run that ignores it is
+ * simply not awaited past the deadline. Returning `null`/`undefined`/`""` hides
+ * the item, and throwing is a failure, counted exactly like a non-zero exit.
+ */
+export type CustomItemRun = (
+	payload: Record<string, unknown>,
+	signal: AbortSignal,
+) => string | null | undefined | Promise<string | null | undefined>;
+
+/** What a provider passes to `register`. */
+export interface CustomItemRegistration {
+	/** Stable name, in the same namespace as a command item's `id`. */
+	id: string;
+	run: CustomItemRun;
+	/** Seconds between forced re-runs; the settings entry wins when it names one. */
+	refreshInterval?: number;
+	/** Milliseconds before the run is abandoned; capped at {@link MAX_TIMEOUT_MS}. */
+	timeoutMs?: number;
+}
+
+/** The payload of {@link CUSTOM_ITEMS_REQUEST_EVENT}. */
+export interface CustomItemsRequest {
+	/**
+	 * Returns whether the registration was accepted.
+	 *
+	 * A rejected one is dropped silently *here* on purpose — see
+	 * {@link CustomItemsTracker.register} — so the boolean is the only signal a
+	 * provider gets that its `id` or `run` was unusable. Ignoring it means a typo
+	 * shows up as a segment that never appears, with nothing to read anywhere.
+	 */
+	register(registration: CustomItemRegistration): boolean;
+}
+
+/** Shown for an entry that names no command and has no registration yet. */
+export const UNBOUND_ERROR = "no command; waiting for an extension to register this id";
+/**
+ * Shown when an id is claimed by both a command entry and a registration.
+ *
+ * The command keeps running: the file is the user's, and an extension must not
+ * be able to take over a row somebody wrote by hand. Saying so is the whole
+ * remedy — deleting either side resolves it.
+ */
+export const COLLISION_ERROR = "id also provided by an extension \u2014 remove one";
+
 /**
  * One configured item.
  *
@@ -46,23 +111,45 @@ export const MAX_OUTPUT_WIDTH = 120;
 export interface CustomItem {
 	id: string;
 	enabled: boolean;
-	/** Absent when the entry is not runnable; `error` then says why. */
+	/** Where the value comes from; drives the `(extension)` tag in the submenu. */
+	kind: "command" | "extension";
+	/** Absent for an extension item, or when the entry is not runnable. */
 	command?: string;
+	/** Bound from a registration; absent until a provider claims this id. */
+	run?: CustomItemRun;
 	/** Seconds between forced re-runs. Absent means event-driven only. */
 	refreshInterval?: number;
 	timeoutMs: number;
+	/**
+	 * Whether `timeoutMs` came from the entry's own `timeout` rather than from a
+	 * default. A registration may only supply the timeout the file left unsaid.
+	 */
+	timeoutExplicit?: boolean;
 	/** Why this entry cannot run, shown in the `/statusline` submenu. */
 	error?: string;
-	/** The on-disk entry, preserved for round-tripping. */
-	source: unknown;
+	/**
+	 * Set when the entry can never run as written — not an object, or a `type`
+	 * this version does not implement. The submenu refuses to enable those, and
+	 * only those: an entry still waiting for its provider is perfectly valid.
+	 */
+	blocked?: boolean;
+	/** The on-disk entry, preserved for round-tripping. Absent when synthesised. */
+	source?: unknown;
 }
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** Positive finite seconds, or undefined for anything unusable. */
-function positiveSeconds(value: unknown): number | undefined {
+/**
+ * A positive finite number, or undefined for anything unusable.
+ *
+ * The same check serves both units: seconds off a settings entry and the
+ * milliseconds a registration names. Callers pass the validated result on
+ * rather than the raw input, so a future normalisation here cannot be
+ * silently bypassed by one of them.
+ */
+function positiveNumber(value: unknown): number | undefined {
 	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return undefined;
 	return value;
 }
@@ -92,7 +179,15 @@ export function normalizeCustomItems(value: unknown): CustomItem[] {
 		if (!isPlainObject(entry)) {
 			const id = uniqueId(fallbackId, taken);
 			taken.add(id);
-			items.push({ id, enabled: false, timeoutMs: DEFAULT_TIMEOUT_MS, error: "not an object", source: entry });
+			items.push({
+				id,
+				enabled: false,
+				kind: "command",
+				timeoutMs: DEFAULT_TIMEOUT_MS,
+				error: "not an object",
+				blocked: true,
+				source: entry,
+			});
 			return;
 		}
 		const rawId = entry.id;
@@ -100,26 +195,54 @@ export function normalizeCustomItems(value: unknown): CustomItem[] {
 		taken.add(id);
 		// `enabled` is the menu's field; everything else is the user's.
 		const enabled = entry.enabled !== false;
-		const timeoutSeconds = positiveSeconds(entry.timeout);
+		const timeoutSeconds = positiveNumber(entry.timeout);
 		const timeoutMs = Math.min(
 			timeoutSeconds === undefined ? DEFAULT_TIMEOUT_MS : timeoutSeconds * 1000,
 			MAX_TIMEOUT_MS,
 		);
-		const refreshInterval = positiveSeconds(entry.refreshInterval);
-		const base = { id, enabled, timeoutMs, source: entry, ...(refreshInterval ? { refreshInterval } : {}) };
+		const refreshInterval = positiveNumber(entry.refreshInterval);
+		const base = {
+			id,
+			enabled,
+			timeoutMs,
+			source: entry,
+			...(timeoutSeconds === undefined ? {} : { timeoutExplicit: true }),
+			...(refreshInterval ? { refreshInterval } : {}),
+		};
 		// Claude Code's `statusLine` carries `type: "command"`, so a pasted entry
-		// may too. That value is accepted; any other is not a mistake this version
-		// can judge, so the entry is kept and flagged rather than run or dropped.
-		const type = entry.type ?? "command";
-		if (type !== "command") {
-			items.push({ ...base, enabled: false, error: `unsupported type: ${String(type)}` });
+		// may too. `"extension"` is this package's own, and optional: an entry with
+		// no command is an extension slot whether or not it says so. Any other value
+		// is not a mistake this version can judge, so the entry is kept and flagged
+		// rather than run or dropped.
+		const hasCommand = typeof entry.command === "string" && entry.command.trim().length > 0;
+		const type = entry.type ?? (hasCommand ? "command" : "extension");
+		if (type !== "command" && type !== "extension") {
+			items.push({
+				...base,
+				kind: "command",
+				enabled: false,
+				error: `unsupported type: ${String(type)}`,
+				blocked: true,
+			});
 			return;
 		}
-		if (typeof entry.command !== "string" || entry.command.trim().length === 0) {
-			items.push({ ...base, enabled: false, error: "missing command" });
+		if (!hasCommand) {
+			// Not an error yet: a provider may register this id later in the session,
+			// and the entry is what reserves its position and enabled state.
+			items.push({ ...base, kind: "extension", error: UNBOUND_ERROR });
 			return;
 		}
-		items.push({ ...base, command: entry.command });
+		if (type === "extension") {
+			items.push({
+				...base,
+				kind: "command",
+				enabled: false,
+				error: "an extension item must not name a command",
+				blocked: true,
+			});
+			return;
+		}
+		items.push({ ...base, kind: "command", command: entry.command as string });
 	});
 	return items;
 }
@@ -132,7 +255,9 @@ export function normalizeCustomItems(value: unknown): CustomItem[] {
  * as the user wrote it rather than accumulating defaults.
  */
 export function serializeCustomItems(items: readonly CustomItem[]): unknown[] {
-	return items.map((item) => {
+	// A registration with no entry of its own has no on-disk form until the user
+	// toggles it, which is what creates the entry; it must never be written here.
+	return items.filter((item) => item.source !== undefined).map((item) => {
 		if (!isPlainObject(item.source)) return item.source;
 		const entry = { ...item.source };
 		if (item.enabled) delete entry.enabled;
@@ -197,10 +322,20 @@ export function sanitizeOutput(raw: string): string {
 export interface CustomItemState {
 	id: string;
 	enabled: boolean;
-	/** Sanitized first line of stdout; absent when there is nothing to show. */
+	/** Where the value comes from, for the submenu's `(extension)` tag. */
+	kind: "command" | "extension";
+	/** Sanitized first line of output; absent when there is nothing to show. */
 	value?: string;
 	/** Configuration or run failure, whichever applies. */
 	error?: string;
+	/**
+	 * True when `error` describes the entry itself rather than its last run. A
+	 * configuration problem outranks "disabled" in the submenu, because the item
+	 * is off *because* of it; a run failure does not.
+	 */
+	configError?: boolean;
+	/** True when the entry can never run as written, so it must not be enabled. */
+	blocked?: boolean;
 	/** When the value was produced, as epoch ms. */
 	updatedAt?: number;
 	running: boolean;
@@ -212,6 +347,12 @@ export interface CustomItemsTrackerOptions {
 	spawn?: SpawnFn;
 	now?: () => number;
 	onChange?: () => void;
+	/**
+	 * Called after a registration is accepted. The tracker cannot know whether
+	 * the footer is live or whether items are switched on, so the extension does
+	 * the timer and refresh work and this is the notification that it is needed.
+	 */
+	onRegister?: () => void;
 	cwd?: string;
 	schedule?: (callback: () => void, intervalMs: number) => unknown;
 	cancel?: (handle: unknown) => void;
@@ -248,11 +389,17 @@ const TICK_FLOOR_MS = 1_000;
  * lower refresh rate instead of a pile of processes.
  */
 export class CustomItemsTracker {
+	/** Entries exactly as configured on disk. */
+	private configured: CustomItem[] = [];
+	/** Registrations by id, in the order providers claimed them. */
+	private readonly registrations = new Map<string, CustomItemRegistration>();
+	/** The two merged: what actually renders and runs. */
 	private items: CustomItem[] = [];
 	private readonly records = new Map<string, RunRecord>();
 	private readonly spawnFn: SpawnFn;
 	private readonly now: () => number;
 	private readonly onChange?: () => void;
+	private readonly onRegister?: () => void;
 	private readonly schedule: (callback: () => void, intervalMs: number) => unknown;
 	private readonly cancel: (handle: unknown) => void;
 	private cwd: string | undefined;
@@ -264,6 +411,7 @@ export class CustomItemsTracker {
 		this.spawnFn = options.spawn ?? nodeSpawn;
 		this.now = options.now ?? Date.now;
 		this.onChange = options.onChange;
+		this.onRegister = options.onRegister;
 		this.cwd = options.cwd;
 		this.schedule = options.schedule ?? defaultSchedule;
 		this.cancel = options.cancel ?? defaultCancel;
@@ -277,7 +425,83 @@ export class CustomItemsTracker {
 	 * does not blink on every settings save.
 	 */
 	setItems(items: readonly CustomItem[]): void {
-		this.items = [...items];
+		this.configured = [...items];
+		this.recompute();
+	}
+
+	/**
+	 * Adopt an item provided by another extension.
+	 *
+	 * Idempotent on id, and it reports rather than throws: this runs inside a
+	 * provider's event handler, where a throw would surface as *that* extension
+	 * failing rather than as a registration this one refused. The return value is
+	 * how a provider learns its `id` or `run` was unusable, since nothing else
+	 * here can name an item that never got far enough to have a row.
+	 */
+	register(registration: CustomItemRegistration): boolean {
+		const id = typeof registration?.id === "string" ? registration.id.trim() : "";
+		if (id.length === 0 || typeof registration.run !== "function") return false;
+		// A re-registration replaces the function, so whatever the old one is doing
+		// is already obsolete; its record keeps the last good value so the footer
+		// does not blink while the new one produces its first.
+		if (this.registrations.has(id)) this.records.get(id)?.abort?.();
+		const refreshInterval = positiveNumber(registration.refreshInterval);
+		const timeoutMs = positiveNumber(registration.timeoutMs);
+		this.registrations.set(id, {
+			id,
+			run: registration.run,
+			...(refreshInterval === undefined ? {} : { refreshInterval }),
+			...(timeoutMs === undefined ? {} : { timeoutMs: Math.min(timeoutMs, MAX_TIMEOUT_MS) }),
+		});
+		this.recompute();
+		this.onRegister?.();
+		return true;
+	}
+
+	/**
+	 * Merge configured entries with registrations.
+	 *
+	 * The file owns order and enabled; a registration fills in the value function
+	 * and any field the file left unsaid. An id in both a command entry and a
+	 * registration is a conflict the user has to resolve, so it is shown rather
+	 * than decided silently — and the command, being the thing they wrote, wins.
+	 */
+	private recompute(): void {
+		const configuredIds = new Set(this.configured.map((item) => item.id));
+		const items = this.configured.map((item) => {
+			const registration = this.registrations.get(item.id);
+			if (item.blocked === true) return item;
+			if (item.command !== undefined) {
+				return registration === undefined ? item : { ...item, error: COLLISION_ERROR };
+			}
+			if (registration === undefined) return item;
+			const { error: _unbound, ...bound } = item;
+			// The entry's own interval wins; the registration supplies the one it
+			// left unsaid. Parenthesised because `??` binds tighter than `?:` — the
+			// grouping is load-bearing and easy to "fix" wrongly.
+			const refreshInterval = item.refreshInterval ?? registration.refreshInterval;
+			return {
+				...bound,
+				kind: "extension" as const,
+				run: registration.run,
+				...(refreshInterval === undefined ? {} : { refreshInterval }),
+				timeoutMs: item.timeoutExplicit ? item.timeoutMs : (registration.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+			};
+		});
+		for (const [id, registration] of this.registrations) {
+			if (configuredIds.has(id)) continue;
+			// No entry claims this id, so it is appended, switched on, and has no
+			// `source`: nothing is written to the settings file until it is toggled.
+			items.push({
+				id,
+				enabled: true,
+				kind: "extension",
+				run: registration.run,
+				...(registration.refreshInterval ? { refreshInterval: registration.refreshInterval } : {}),
+				timeoutMs: registration.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+			});
+		}
+		this.items = items;
 		const live = new Set(items.map((item) => item.id));
 		for (const [id, record] of this.records) {
 			if (live.has(id)) continue;
@@ -309,9 +533,11 @@ export class CustomItemsTracker {
 			return {
 				id: item.id,
 				enabled: item.enabled,
+				kind: item.kind,
+				...(item.blocked === true ? { blocked: true } : {}),
 				...(record?.value !== undefined ? { value: record.value } : {}),
 				...(item.error !== undefined
-					? { error: item.error }
+					? { error: item.error, configError: true }
 					: record?.error !== undefined
 						? { error: record.error }
 						: {}),
@@ -346,7 +572,13 @@ export class CustomItemsTracker {
 		this.tickHandle = undefined;
 	}
 
-	/** Stop everything and abandon in-flight commands. */
+	/**
+	 * Stop everything and abandon in-flight runs.
+	 *
+	 * Registrations survive: this also fires when the footer is torn down, and a
+	 * provider has no way to hear about that to register again. They die with the
+	 * extension instance instead, which is when the next request event is sent.
+	 */
 	dispose(): void {
 		this.stop();
 		for (const record of this.records.values()) record.abort?.();
@@ -367,7 +599,8 @@ export class CustomItemsTracker {
 	refresh(): void {
 		const now = this.now();
 		for (const item of this.items) {
-			if (!item.enabled || item.command === undefined) continue;
+			if (!item.enabled) continue;
+			if (item.command === undefined && item.run === undefined) continue;
 			const record = this.records.get(item.id);
 			if (record?.running) continue;
 			const minimum =
@@ -388,6 +621,67 @@ export class CustomItemsTracker {
 	}
 
 	private run(item: CustomItem): void {
+		if (item.run !== undefined) {
+			this.runRegistered(item, item.run);
+			return;
+		}
+		this.runCommand(item);
+	}
+
+	/** How long an item may run, rendered the way both paths report a timeout. */
+	private timeoutLabel(item: CustomItem): string {
+		return `timed out after ${Math.round(item.timeoutMs / 100) / 10}s`;
+	}
+
+	/**
+	 * Run a registered function under the command path's guarantees.
+	 *
+	 * The deadline is the tracker's, not the provider's: `signal` asks it to stop
+	 * and the outcome is settled regardless, so a provider that ignores the
+	 * signal costs a leaked promise rather than a stuck segment.
+	 */
+	private runRegistered(item: CustomItem, run: CustomItemRun): void {
+		const record = this.record(item.id);
+		record.lastAttempt = this.now();
+		record.running = true;
+
+		const controller = new AbortController();
+		let settled = false;
+		const finish = (outcome: { value?: string; error?: string }): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			record.abort = undefined;
+			this.settle(item, record, outcome);
+		};
+
+		const timer = setTimeout(() => {
+			controller.abort();
+			finish({ error: this.timeoutLabel(item) });
+		}, item.timeoutMs);
+		timer.unref?.();
+
+		record.abort = () => {
+			clearTimeout(timer);
+			settled = true;
+			record.running = false;
+			controller.abort();
+		};
+
+		let result: ReturnType<CustomItemRun>;
+		try {
+			result = run(this.payloadFactory(), controller.signal);
+		} catch (error) {
+			finish({ error: error instanceof Error ? error.message : String(error) });
+			return;
+		}
+		Promise.resolve(result).then(
+			(value) => finish({ value: value === null || value === undefined ? "" : sanitizeOutput(String(value)) }),
+			(error: unknown) => finish({ error: error instanceof Error ? error.message : String(error) }),
+		);
+	}
+
+	private runCommand(item: CustomItem): void {
 		const command = item.command;
 		if (command === undefined) return;
 		const record = this.record(item.id);
@@ -426,7 +720,7 @@ export class CustomItemsTracker {
 			child.kill("SIGTERM");
 			// A command ignoring SIGTERM must not outlive the session either.
 			setTimeout(() => child.kill("SIGKILL"), 500).unref?.();
-			finish({ error: `timed out after ${Math.round(item.timeoutMs / 100) / 10}s` });
+			finish({ error: this.timeoutLabel(item) });
 		}, item.timeoutMs);
 		timer.unref?.();
 

package/index.ts

@@ -14,7 +14,12 @@ import {
 } from "./cache-celebration.ts";
 import { CelebrationPreview, trackSelectedLabel } from "./celebration-preview.ts";
 import { DEFAULT_CELEBRATION_STYLE, renderCacheBadge } from "./celebration-styles.ts";
-import { CustomItemsTracker } from "./custom.ts";
+import {
+	CUSTOM_ITEMS_REQUEST_EVENT,
+	type CustomItemRegistration,
+	type CustomItemsRequest,
+	CustomItemsTracker,
+} from "./custom.ts";
 import { buildCustomItemSetupPrompt } from "./custom-setup.ts";
 import { FullRedrawScheduler } from "./redraw.ts";
 import {
@@ -246,7 +251,34 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 	const cacheCelebration = new CacheCelebrationController(() => requestRender?.());
 	let tracker: SessionWorktreeTracker | undefined;
 	const usageTracker = new UsageTracker({ onChange: () => requestRender?.() });
-	const customItems = new CustomItemsTracker({ onChange: () => requestRender?.() });
+	// One request event is answered by every provider at once, so `onRegister`
+	// fires once per item while the work it guards — sizing the timer, refreshing,
+	// redrawing — is per-tracker. Coalescing to a single microtask makes N
+	// providers cost one restart and one render instead of N, and the registrations
+	// are all in place by the time it runs, so the timer is sized once from the
+	// complete set rather than N times from a growing one.
+	let registrationSettlePending = false;
+	const customItems = new CustomItemsTracker({
+		onChange: () => requestRender?.(),
+		// A registration can arrive at any point in the session, including after
+		// the timer was sized from the items that existed without it.
+		onRegister: () => {
+			if (registrationSettlePending) return;
+			registrationSettlePending = true;
+			queueMicrotask(() => {
+				registrationSettlePending = false;
+				if (settings.showCustomItems) {
+					// restartTimer alone is a no-op when no item had asked for a timer
+					// yet, which is exactly the case a late registration creates; start
+					// covers that branch and is idempotent when the timer is already up.
+					customItems.restartTimer();
+					customItems.start();
+					customItems.refresh();
+				}
+				requestRender?.();
+			});
+		},
+	});
 	let cwdGit: GitRepositoryStatus | null = null;
 	let cwdStatusAbort: AbortController | undefined;
 	let cwdStatusInFlight: Promise<void> | undefined;
@@ -260,6 +292,26 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		});
 	};
 
+	/**
+	 * Ask every other extension for the items it wants on the statusline.
+	 *
+	 * Sent at session start rather than from this factory, because extensions
+	 * load in sequence: a factory-time emit would only ever reach providers that
+	 * happen to be configured *before* this package. By session start they have
+	 * all run, and the event fires again whenever `/statusline` opens so that a
+	 * provider which starts listening mid-session is still picked up.
+	 *
+	 * Interactive only. Custom items exist to fill footer segments, and a print
+	 * or RPC run has no footer, so asking would buy nothing and cost providers a
+	 * poll loop against a payload this extension never installs.
+	 */
+	const requestCustomItems = (): void => {
+		const request: CustomItemsRequest = {
+			register: (registration: CustomItemRegistration) => customItems.register(registration),
+		};
+		pi.events?.emit(CUSTOM_ITEMS_REQUEST_EVENT, request);
+	};
+
 	const refreshCwdStatus = (ctx: ExtensionContext): Promise<void> => {
 		if (!cwdStatusAbort) return Promise.resolve();
 		if (cwdStatusInFlight) return cwdStatusInFlight.then(() => refreshCwdStatus(ctx));
@@ -418,6 +470,9 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 			// starts from what is on disk rather than a snapshot that may be hours
 			// old and missing another session's changes.
 			applySettings(ctx, await settingsStore.load(), false);
+			// Same reason the file is re-read: the menu should show what is true now,
+			// including an item from a provider that loaded after the session began.
+			requestCustomItems();
 
 			await ctx.ui.custom<void>((tui, _theme, _keybindings, done) => {
 				const tracked = trackSelectedLabel(getSettingsListTheme());
@@ -450,6 +505,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 							customItems: createCustomItemsSubmenu(submenuHost),
 						},
 						home,
+						customItems.states(),
 					),
 					10,
 					settingsTheme,
@@ -557,6 +613,9 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		});
 
 		resetTracker(ctx);
+		// Last, so a provider that registers synchronously runs against the payload
+		// factory resetTracker just installed rather than an empty one.
+		requestCustomItems();
 	});
 
 	pi.on("tool_call", (event) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Compact Pi footer statusline with Git/worktree context, token usage, and neon celebrations for exceptional prompt-cache hits.",
   "type": "module",
   "keywords": [

package/settings-menu.ts

@@ -10,7 +10,7 @@ import {
 	truncateToWidth,
 } from "@earendil-works/pi-tui";
 import { type BooleanSettingKey, collapseHome, resolveWorktreeRoot, type StatuslineSettings } from "./settings.ts";
-import type { CustomItemState } from "./custom.ts";
+import { type CustomItem, type CustomItemState, DEFAULT_TIMEOUT_MS } from "./custom.ts";
 import { CELEBRATION_STYLE_NAMES, isCelebrationStyleName } from "./celebration-styles.ts";
 import { isThemeName, THEME_NAMES } from "./themes.ts";
 
@@ -62,11 +62,17 @@ export function aliasSummary(settings: StatuslineSettings): string {
 	return `${count} alias${count === 1 ? "" : "es"}`;
 }
 
-/** Row value for the custom-items submenu: how many items are switched on. */
-export function customItemsSummary(settings: StatuslineSettings): string {
-	const total = settings.customItems.length;
+/**
+ * Row value for the custom-items submenu: how many items are switched on.
+ *
+ * Counted from the tracker's states, not from the settings file: an item an
+ * extension provides is as real as one the file names, and it may have no entry
+ * of its own until somebody toggles it.
+ */
+export function customItemsSummary(states: readonly CustomItemState[]): string {
+	const total = states.length;
 	if (total === 0) return "none configured";
-	return `${settings.customItems.filter((item) => item.enabled).length}/${total} on`;
+	return `${states.filter((state) => state.enabled).length}/${total} on`;
 }
 
 /**
@@ -75,12 +81,9 @@ export function customItemsSummary(settings: StatuslineSettings): string {
  * than opening a form: a statusline command is a script plus a JSON entry plus
  * a test run, which is a conversation, not a field.
  */
-export function customItemRows(
-	settings: StatuslineSettings,
-	states: readonly CustomItemState[] = [],
-): SelectItem[] {
+export function customItemRows(states: readonly CustomItemState[] = []): SelectItem[] {
 	return [
-		...customItemStateRows(settings, states),
+		...customItemStateRows(states),
 		{
 			value: ADD_CUSTOM_ITEM_VALUE,
 			label: "Add custom item…",
@@ -89,31 +92,30 @@ export function customItemRows(
 	];
 }
 
-function customItemStateRows(settings: StatuslineSettings, states: readonly CustomItemState[]): SelectItem[] {
-	const byId = new Map(states.map((state) => [state.id, state]));
-	return settings.customItems.map((item) => {
-		const state = byId.get(item.id);
-		// Configuration errors outrank run errors: an item that cannot be parsed
-		// never ran, so a stale run error from a previous config would mislead.
-		const error = item.error ?? state?.error;
-		// A broken entry reads as "disabled" unless its reason wins here: it is off
-		// *because* it cannot run, and "disabled" would suggest the user chose that.
-		const detail = item.error !== undefined
-			? item.error
-			: !item.enabled
+function customItemStateRows(states: readonly CustomItemState[]): SelectItem[] {
+	return states.map((state) => {
+		// A broken or unbound entry reads as "disabled" unless its reason wins
+		// here: it is off *because* of that, and "disabled" would suggest the user
+		// chose it. A run failure is the other way round — an item switched off is
+		// off first, and whatever its last run said is history.
+		const detail = state.configError === true
+			? (state.error as string)
+			: !state.enabled
 				? "disabled"
-				: error !== undefined
-				? error
-				: state?.running === true && state.value === undefined
+				: state.error !== undefined
+				? state.error
+				: state.running && state.value === undefined
 					? "running…"
-					: state?.value !== undefined && state.value.length > 0
+					: state.value !== undefined && state.value.length > 0
 						? state.value
-						: state?.value !== undefined
+						: state.value !== undefined
 							? "empty output"
 							: "no value yet";
 		return {
-			value: item.id,
-			label: `${item.enabled ? toggleValue(true) : toggleValue(false)}  ${item.id}`,
+			value: state.id,
+			// The tag says where the value comes from, which is the one thing a row
+			// cannot otherwise show: an extension item has no command to point at.
+			label: `${toggleValue(state.enabled)}  ${state.id}${state.kind === "extension" ? "  (extension)" : ""}`,
 			description: detail,
 		};
 	});
@@ -130,6 +132,7 @@ export function buildSettingItems(
 	settings: StatuslineSettings,
 	submenus: SettingSubmenus = {},
 	home: string = homedir(),
+	customStates: readonly CustomItemState[] = [],
 ): SettingItem[] {
 	const items: SettingItem[] = [
 		{
@@ -146,8 +149,9 @@ export function buildSettingItems(
 	for (const row of BOOLEAN_ROWS) {
 		// A toggle for a segment with nothing in it is a row that does nothing;
 		// the list row below is where an item gets created, and the toggle
-		// appears once there is something to switch off.
-		if (row.id === "showCustomItems" && settings.customItems.length === 0) continue;
+		// appears once there is something to switch off — including something an
+		// extension provided, which never appears in the settings file.
+		if (row.id === "showCustomItems" && customStates.length === 0) continue;
 		items.push({
 			id: row.id,
 			label: row.label,
@@ -183,8 +187,8 @@ export function buildSettingItems(
 	items.push({
 		id: CUSTOM_ITEMS_ID,
 		label: "Custom item list",
-		description: "Enable or disable configured items; edit commands in statusline-settings.json.",
-		currentValue: customItemsSummary(settings),
+		description: "Enable or disable items, your own and extensions'; edit commands in statusline-settings.json.",
+		currentValue: customItemsSummary(customStates),
 		...(submenus.customItems ? { submenu: submenus.customItems } : {}),
 	});
 
@@ -449,11 +453,15 @@ class CustomItemsSubmenu implements Component {
 		this.list = this.buildList();
 	}
 
+	private states(): readonly CustomItemState[] {
+		return this.host.customItemStates?.() ?? [];
+	}
+
 	private buildList(selectedIndex = 0): SelectList {
-		const rows = customItemRows(this.host.getSettings(), this.host.customItemStates?.() ?? []);
+		const rows = customItemRows(this.states());
 		const list = new SelectList(rows, 10, this.host.selectTheme);
 		list.setSelectedIndex(selectedIndex);
-		list.onCancel = () => this.done(customItemsSummary(this.host.getSettings()));
+		list.onCancel = () => this.done(customItemsSummary(this.states()));
 		list.onSelect = (item) => (item.value === ADD_CUSTOM_ITEM_VALUE ? this.add() : this.toggle(item.value));
 		return list;
 	}
@@ -471,7 +479,7 @@ class CustomItemsSubmenu implements Component {
 				this.prompt = undefined;
 				// Close the whole menu before the message lands: the agent's reply
 				// renders in the transcript, which the menu is drawn over.
-				this.done(customItemsSummary(this.host.getSettings()));
+				this.done(customItemsSummary(this.states()));
 				this.host.requestCustomItem?.(value);
 			},
 			() => {
@@ -485,18 +493,34 @@ class CustomItemsSubmenu implements Component {
 	private toggle(id: string): void {
 		if (id.startsWith("\u0000")) return;
 		const settings = this.host.getSettings();
-		const index = settings.customItems.findIndex((item) => item.id === id);
-		const target = settings.customItems[index];
-		if (!target) return;
-		if (target.error !== undefined && !target.enabled) {
+		const state = this.states().find((candidate) => candidate.id === id);
+		if (!state) return;
+		if (state.blocked === true && !state.enabled) {
 			// Enabling an unparseable entry would only fail again on the next tick.
-			this.host.notify(`${id} cannot run: ${target.error}`);
+			this.host.notify(`${id} cannot run: ${state.error ?? "invalid entry"}`);
 			return;
 		}
+		const index = settings.customItems.findIndex((item) => item.id === id);
+		const target = settings.customItems[index];
 		const customItems = [...settings.customItems];
-		customItems[index] = { ...target, enabled: !target.enabled };
+		if (target) customItems[index] = { ...target, enabled: !target.enabled };
+		else {
+			// An item an extension provided has no entry until it is switched off,
+			// and that entry is also what gives it a position the user controls.
+			const entry: CustomItem = {
+				id,
+				enabled: false,
+				kind: "extension",
+				timeoutMs: DEFAULT_TIMEOUT_MS,
+				source: { id, type: "extension", enabled: false },
+			};
+			customItems.push(entry);
+		}
 		this.host.commit({ ...settings, customItems });
-		this.list = this.buildList(index);
+		// Re-read the states rather than reusing the old index: writing an entry
+		// for a registration can move it out of the appended tail and into order.
+		const selected = this.states().findIndex((candidate) => candidate.id === id);
+		this.list = this.buildList(Math.max(0, selected));
 		this.host.requestRender();
 	}