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

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

@@ -171,13 +171,41 @@ export function windowSegment(snapshot: StatusSnapshot, theme: Theme): Segment |
 }
 
 export function costSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
-	if (snapshot.usage.cost === 0) return null;
+	const { cost } = snapshot.usage;
+	if (cost === 0) return null;
 	return {
 		id: "cost",
 		weight: 2,
 		droppable: true,
 		separator: faint(theme, CONFIG.separators.item),
-		forms: [paint(theme, "meta", formatCost(snapshot.usage.cost, snapshot.currency))],
+		forms: [paint(theme, "meta", formatCost(cost, snapshot.currency))],
+	};
+}
+
+/**
+ * Child-run spend, next to the session's own cost and never inside it: a
+ * subagent runs in its own process, so its tokens are not the session's. The
+ * roll-up covers the ledger's retained window (the last 500 runs).
+ */
+export function delegationSegment(snapshot: StatusSnapshot, theme: Theme): Segment | null {
+	const { runs, usage } = snapshot.delegation;
+	if (runs === 0) return null;
+	const icon = CONFIG.icons.delegation;
+	const cost = formatCost(usage.cost, snapshot.currency);
+	// Detailed first; the run count survives longer than the price, because "some
+	// delegation happened" is the part a narrow bar can still say.
+	const forms = [
+		`${paint(theme, "meta", `${icon} ${runs} · ${cost}`)}`,
+		`${paint(theme, "meta", `${icon} ${cost}`)}`,
+		paint(theme, "meta", `${icon} ${runs}`),
+		paint(theme, "meta", icon),
+	];
+	return {
+		id: "delegation",
+		weight: 4,
+		droppable: true,
+		separator: faint(theme, CONFIG.separators.item),
+		forms,
 	};
 }
 

package/extensions/bytefly/footer/types.ts

@@ -32,6 +32,7 @@ export interface UsageTotals {
 	output: number;
 	cacheRead: number;
 	cacheWrite: number;
+	/** Cost in the configured currency: rated in CNY mode, Pi's recorded amount in USD mode. */
 	cost: number;
 }
 
@@ -69,6 +70,17 @@ export interface StatusSnapshot {
 	/** Latest cache hit rate as a percentage, or `null` when unknown. */
 	cacheHitRate: number | null;
 	providerCount: number;
+	/**
+	 * What this session's delegated child runs spent, priced like `usage` but kept
+	 * apart from it: the session total never includes child spend.
+	 */
+	delegation: DelegationTotals;
+}
+
+/** Child-run totals: how many runs finished, and what the retained window spent. */
+export interface DelegationTotals {
+	runs: number;
+	usage: UsageTotals;
 }
 
 /** One renderable piece of a line. */

package/extensions/bytefly/header/component.ts

@@ -17,6 +17,7 @@ import { keyHintText } from "../../../lib/tui/glyphs.ts";
 import { BODY_INDENT } from "../../../lib/tui/indent.ts";
 import { RULE_GLYPH } from "../../../lib/tui/rules.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
+import { updateMarker } from "../update/format.ts";
 import { HEADER_CONFIG, type HelpEntry } from "./config.ts";
 
 /** The header's shape, resolved once per apply so `render` stays cheap. */
@@ -27,6 +28,8 @@ export interface HeaderView {
 	halfBlocks: boolean;
 	/** Columns of left margin: Pi's output pad, so the nameplate sits on the transcript margin. */
 	pad: number;
+	/** A newer published version of this package, when one is known. */
+	latest?: string;
 }
 
 /** The mark block is four columns on both rows, so the identity column aligns. */
@@ -78,7 +81,7 @@ export class ByteflyHeader implements Component {
 		const w = Math.max(1, width);
 		const theme = this.getTheme();
 		const view = this.view();
-		const viewKey = `${view.showVersion}:${view.halfBlocks}:${view.pad}`;
+		const viewKey = `${view.showVersion}:${view.halfBlocks}:${view.pad}:${view.latest ?? ""}`;
 		const keys = this.keySignature();
 		if (
 			this.cachedWidth === w &&
@@ -106,7 +109,8 @@ export class ByteflyHeader implements Component {
 	}
 
 	private build(w: number, theme: Theme, view: HeaderView): string[] {
-		const { nameRole, chromeRole, detailRole, chromeTagline, chromeName, chromeVersion, help } = HEADER_CONFIG;
+		const { nameRole, chromeRole, detailRole, updateRole, chromeTagline, chromeName, chromeVersion, help } =
+			HEADER_CONFIG;
 		const padWidth = Math.max(0, Math.min(Math.floor(view.pad), Math.max(0, w - 1)));
 		const pad = " ".repeat(padWidth);
 		const [markTop, markBottom] = markLines(theme, view.halfBlocks);
@@ -120,11 +124,18 @@ export class ByteflyHeader implements Component {
 				: theme.bold(paint(theme, nameRole, HEADER_CONFIG.appName))
 			: version;
 		const chrome = `${paint(theme, detailRole, chromeTagline)} ${paint(theme, chromeRole, chromeName)}`;
-		const chromeVersioned = chromeVersion ? `${chrome} ${paint(theme, detailRole, `v${chromeVersion}`)}` : chrome;
-
-		// The identity rows shed as one block: chrome version, chrome line, agent.
+		const chromeWithVersion = chromeVersion ? `${chrome} ${paint(theme, detailRole, `v${chromeVersion}`)}` : chrome;
+		// The published version follows the loaded one: `v0.11.4 ↑0.12.0`.
+		const chromeWithMarker =
+			chromeVersion && view.latest
+				? `${chromeWithVersion} ${paint(theme, updateRole, updateMarker(view.latest))}`
+				: chromeWithVersion;
+
+		// The identity rows shed as one block: the update marker first, then the
+		// chrome version, the chrome line, and finally the agent.
 		const states: Array<readonly [string, string]> = [
-			[agent, chromeVersioned],
+			[agent, chromeWithMarker],
+			[agent, chromeWithVersion],
 			[agent, chrome],
 			[agent, ""],
 			["", ""],
@@ -132,7 +143,11 @@ export class ByteflyHeader implements Component {
 		const lineWidth = (cell: string): number => pad.length + MARK_WIDTH + (cell ? 1 + visibleWidth(cell) : 0);
 		const [agentCell, chromeCell] = states.find(([a, c]) => Math.max(lineWidth(a), lineWidth(c)) <= w) ?? ["", ""];
 
+		// The header owns its leading blank: Pi mounts the built-in header inside
+		// `Spacer(1)`s, but the `quietStartup: true` branch that hands this header the
+		// screen adds none, and `setHeader` swaps only the header child.
 		return [
+			"",
 			this.identityLine(pad, markTop, agentCell, w),
 			this.identityLine(pad, markBottom, chromeCell, w),
 			this.rule(theme, w, pad),

package/extensions/bytefly/header/config.ts

@@ -35,6 +35,8 @@ export interface HeaderConfig {
 	readonly chromeRole: TuiRole;
 	/** Role for the versions, the tagline, and the help descriptions. */
 	readonly detailRole: TuiRole;
+	/** Role for the update marker: an action, so the accent rather than a warning colour. */
+	readonly updateRole: TuiRole;
 	/** Role for the rule's accent lead under the mark. */
 	readonly ruleAccentRole: TuiRole;
 	/** Role for the rest of the rule. */
@@ -57,6 +59,7 @@ export const HEADER_CONFIG: HeaderConfig = {
 	nameRole: "label",
 	chromeRole: "meta",
 	detailRole: "faint",
+	updateRole: "accent",
 	ruleAccentRole: "accent",
 	ruleRole: "rule",
 	chromeTagline: "enhanced by",

package/extensions/bytefly/header/register.ts

@@ -9,21 +9,40 @@
  * `pi config` remains the way to turn all of bytefly's chrome off. The header
  * is installed only in interactive (`tui`) sessions; every other mode leaves
  * Pi's built-in header in place, which does not exist there.
+ *
+ * The update check resolves after this install, so the header reads the newest
+ * known version through `UpdateSource` and `refresh()` re-applies the last
+ * context's header once one arrives. That is the only reason the header is ever
+ * installed twice.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isAppleTerminalSession } from "@earendil-works/pi-tui";
 import { DEFAULT_HOST_PAD } from "../pad.ts";
+import { createUpdateState, type UpdateSource } from "../update/state.ts";
 import { createHeader, type HeaderView } from "./component.ts";
 import { HEADER_CONFIG } from "./config.ts";
 
-/** Register the install/restore lifecycle for the custom header. */
-export function registerHeader(pi: ExtensionAPI): void {
+/** The installed header, and the way to re-install it after a change. */
+export interface HeaderHandle {
+	/** Re-apply the last session's header, picking up the current update marker. */
+	refresh(): void;
+}
+
+/**
+ * Register the install/restore lifecycle for the custom header.
+ *
+ * `updates` is the store the update check writes, so the marker appears when a
+ * newer version is known. A test that does not exercise the marker may omit it.
+ */
+export function registerHeader(pi: ExtensionAPI, updates: UpdateSource = createUpdateState()): HeaderHandle {
 	// Half blocks misalign in Apple Terminal, so the mark falls back to a wordmark
 	// there, mirroring Pi's own built-in header.
 	const halfBlocks = !isAppleTerminalSession();
+	let last: ExtensionContext | undefined;
 
 	const apply = (ctx: ExtensionContext): void => {
+		last = ctx;
 		if (ctx.mode !== "tui") return;
 		// Bytefly's startup TUI is on only when Pi's `quietStartup` is true, which
 		// hides Pi's built-in startup header. Every other value (`false`,
@@ -36,14 +55,26 @@ export function registerHeader(pi: ExtensionAPI): void {
 		// value the tool frame and the notice inset by. An older host without
 		// `getSettings` keeps the default margin.
 		const pad = pi.getSettings?.().outputPad ?? DEFAULT_HOST_PAD;
-		const view = (): HeaderView => ({ showVersion: HEADER_CONFIG.showVersion, halfBlocks, pad });
+		const view = (): HeaderView => ({
+			showVersion: HEADER_CONFIG.showVersion,
+			halfBlocks,
+			pad,
+			latest: updates.latest(),
+		});
 		ctx.ui.setHeader(createHeader(() => ctx.ui.theme, view));
 	};
 
 	pi.on("session_start", (_event, ctx) => apply(ctx));
 	pi.on("session_tree", (_event, ctx) => apply(ctx));
 	pi.on("session_shutdown", (_event, ctx) => {
+		last = undefined;
 		if (ctx.mode !== "tui") return;
 		ctx.ui.setHeader(undefined);
 	});
+
+	return {
+		refresh() {
+			if (last) apply(last);
+		},
+	};
 }

package/extensions/bytefly/index.ts

@@ -1,5 +1,5 @@
 /**
- * bytefly — the package's terminal chrome and diagnostics, composed from ten
+ * bytefly — the package's terminal chrome and diagnostics, composed from eleven
  * 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
@@ -7,7 +7,8 @@
  * transcript turn rule), `working/` (the live elapsed counter on Pi's working
  * row), `panel/` (the unified `/bytefly` screen and its
  * `doctor` report), `doctor/` (the `run_doctor` tool and its session-scoped
- * probe runtime), and `notify/` (OS notifications for unattended runs).
+ * probe runtime), `notify/` (OS notifications for unattended runs), and
+ * `update/` (the published-version check behind the header's update marker).
  *
  * The header, footer, turn rule, and working timer are installed only in
  * interactive (`tui`) sessions, and are always on; the user-message marker,
@@ -34,6 +35,8 @@ import { type NotifyDeps, registerNotify } from "./notify/register.ts";
 import { createPadStore } from "./pad.ts";
 import { type PanelCommandDeps, registerPanel } from "./panel/commands.ts";
 import { registerTurnSeparator } from "./separator/register.ts";
+import { registerUpdate, type UpdateDeps } from "./update/register.ts";
+import { createUpdateState } from "./update/state.ts";
 import { registerWorkingTimer } from "./working/register.ts";
 
 /** Host seams, injected by tests. */
@@ -44,13 +47,18 @@ export interface ByteflyDeps {
 	doctor?: DoctorDeps;
 	/** Seams for the notify capability. */
 	notify?: NotifyDeps;
+	/** Seams for the published-version check. */
+	update?: UpdateDeps;
 }
 
 /** Register every bytefly surface; the factory only registers. */
 export default function bytefly(pi: ExtensionAPI, deps: ByteflyDeps = {}): void {
 	if (!isExtensionEnabled("bytefly")) return;
 
-	registerHeader(pi);
+	// One store per load: the update check writes the newest published version and
+	// the header reads it, so the marker and every re-install agree.
+	const updates = createUpdateState();
+	const header = registerHeader(pi, updates);
 	registerFooter(pi);
 	registerUserMessage(pi);
 	// One store per load: the tool frame and the notice record Pi's output pad and
@@ -64,6 +72,9 @@ export default function bytefly(pi: ExtensionAPI, deps: ByteflyDeps = {}): void
 	registerTurnSeparator(pi, pad);
 	registerWorkingTimer(pi);
 	const doctor = registerDoctor(pi, deps.doctor);
-	registerPanel(pi, { doctor, discover: deps.extensions?.discover });
 	registerNotify(pi, deps.notify);
+	// The returned handle is what `/bytefly update` re-runs, so the update surface is
+	// registered before the panel that offers the command.
+	const update = registerUpdate(pi, updates, { ...deps.update, onUpdate: () => header.refresh() });
+	registerPanel(pi, { doctor, update, discover: deps.extensions?.discover });
 }

package/extensions/bytefly/notify/config.ts

@@ -25,6 +25,7 @@ export const DEFAULT_NOTIFY_CONFIG: NotifyConfig = {
 	turnFinished: true,
 	needsInput: true,
 	jobFinished: true,
+	matchFound: true,
 	method: "auto",
 	title: "Pi",
 };
@@ -49,6 +50,7 @@ export function normalizeNotifyConfig(raw: Record<string, unknown> | undefined,
 		turnFinished: bool(raw.turnFinished, base.turnFinished),
 		needsInput: bool(raw.needsInput, base.needsInput),
 		jobFinished: bool(raw.jobFinished, base.jobFinished),
+		matchFound: bool(raw.matchFound, base.matchFound),
 		method: method(raw.method, base.method),
 		title: cleanString(raw.title, base.title).slice(0, MAX_TITLE_LENGTH),
 	};

package/extensions/bytefly/notify/format.ts

@@ -8,7 +8,7 @@
  */
 
 import { basename } from "node:path";
-import type { JobFinishedEvent } from "../../../lib/events.ts";
+import type { JobFinishedEvent, WatchMatchEvent } from "../../../lib/events.ts";
 import { sanitizeLine } from "../../../lib/format.ts";
 
 /** A short session label, so concurrent unattended runs can be told apart. */
@@ -37,3 +37,21 @@ export function formatJobBody(job: JobFinishedEvent): string {
 	const label = sanitizeLine(job.label);
 	return `Job ${job.id} ${verb}${code}${label ? ` · ${label}` : ""}`;
 }
+
+/** How much of a matched line an OS notification carries. */
+export const MAX_WATCH_LINE = 80;
+
+/**
+ * Body for a `watch` wake match: the newest line that matched, and how many did.
+ *
+ * The line is watched output rather than something this package wrote, so it is
+ * sanitized and clipped here — the one place a notification's text is shaped.
+ */
+export function formatWatchBody(event: WatchMatchEvent): string {
+	const count = Math.max(1, event.count);
+	const label = sanitizeLine(event.label);
+	const line = sanitizeLine(event.line).slice(0, MAX_WATCH_LINE).trimEnd();
+	const head = `${count} watched line${count === 1 ? "" : "s"} matched`;
+	const source = `${sanitizeLine(event.watcherId)}${label ? ` ${label}` : ""}`;
+	return line ? `${head} · ${source}: ${line}` : `${head} · ${source}`;
+}

package/extensions/bytefly/notify/register.ts

@@ -9,8 +9,9 @@
  *   asking for input. A prompt while idle is a command the user typed, so it
  *   does not fire;
  * - a finished background job, announced by the `job` extension on
- *   {@link JOB_FINISHED_CHANNEL}. The two extensions never import each other;
- *   the bus and its payload are the whole contract.
+ *   {@link JOB_FINISHED_CHANNEL}; and a `watch` wake match, announced by the
+ *   `watch` extension on {@link WATCH_MATCH_CHANNEL}. The three extensions never
+ *   import each other; the bus and its payload are the whole contract.
  *
  * The config is read at `session_start` and the bus subscription is a
  * long-lived resource, so it is created there too and released in an
@@ -18,10 +19,15 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { JOB_FINISHED_CHANNEL, type JobFinishedEvent } from "../../../lib/events.ts";
+import {
+	JOB_FINISHED_CHANNEL,
+	type JobFinishedEvent,
+	WATCH_MATCH_CHANNEL,
+	type WatchMatchEvent,
+} from "../../../lib/events.ts";
 import { DEFAULT_NOTIFY_CONFIG, loadNotifyConfig } from "./config.ts";
 import { defaultSeams, type NotifySeams, sendNotification } from "./dispatch.ts";
-import { formatInputBody, formatJobBody, formatTurnBody, sessionLabel } from "./format.ts";
+import { formatInputBody, formatJobBody, formatTurnBody, formatWatchBody, sessionLabel } from "./format.ts";
 import type { NotifyConfig } from "./types.ts";
 
 /** Host seams, injected by tests. */
@@ -37,12 +43,25 @@ function isJobFinished(value: unknown): value is JobFinishedEvent {
 	return typeof event.id === "string" && typeof event.label === "string" && typeof event.status === "string";
 }
 
-/** Register the three notification triggers. */
+/** Narrow an untrusted bus payload to a wake match. */
+function isWatchMatch(value: unknown): value is WatchMatchEvent {
+	if (!value || typeof value !== "object") return false;
+	const event = value as Partial<WatchMatchEvent>;
+	return (
+		typeof event.count === "number" &&
+		typeof event.watcherId === "string" &&
+		typeof event.label === "string" &&
+		typeof event.line === "string"
+	);
+}
+
+/** Register the notification triggers. */
 export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
 	const seams = deps.seams ?? defaultSeams();
 	let config: NotifyConfig = DEFAULT_NOTIFY_CONFIG;
 	let busy = false;
-	let unsubscribe: (() => void) | undefined;
+	/** Bus subscriptions: one per emitting extension, all created at session start. */
+	const unsubscribes: Array<() => void> = [];
 
 	const fire = (body: string): void => {
 		sendNotification(config, config.title, body, seams);
@@ -59,11 +78,17 @@ export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
 	pi.on("session_start", (_event, ctx) => {
 		config = loadNotifyConfig(ctx.cwd);
 		busy = false;
-		unsubscribe?.();
-		unsubscribe = pi.events.on(JOB_FINISHED_CHANNEL, (data) => {
-			if (!config.jobFinished || !isJobFinished(data)) return;
-			fire(formatJobBody(data));
-		});
+		while (unsubscribes.length > 0) unsubscribes.pop()?.();
+		unsubscribes.push(
+			pi.events.on(JOB_FINISHED_CHANNEL, (data) => {
+				if (!config.jobFinished || !isJobFinished(data)) return;
+				fire(formatJobBody(data));
+			}),
+			pi.events.on(WATCH_MATCH_CHANNEL, (data) => {
+				if (!config.matchFound || !isWatchMatch(data)) return;
+				fire(formatWatchBody(data));
+			}),
+		);
 	});
 
 	pi.on("agent_settled", (event, ctx) => {
@@ -78,8 +103,7 @@ export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
 	});
 
 	pi.on("session_shutdown", () => {
-		unsubscribe?.();
-		unsubscribe = undefined;
+		while (unsubscribes.length > 0) unsubscribes.pop()?.();
 		busy = false;
 	});
 }

package/extensions/bytefly/notify/types.ts

@@ -21,6 +21,8 @@ export interface NotifyConfig {
 	needsInput: boolean;
 	/** Notify when a background `job` finishes. */
 	jobFinished: boolean;
+	/** Notify when a `watch` wake match fires while the agent is idle. */
+	matchFound: boolean;
 	/** Delivery method; `auto` chooses by terminal and platform. */
 	method: NotifyMethod;
 	/** Notification title, e.g. `Pi`. */

package/extensions/bytefly/panel/commands.ts

@@ -1,23 +1,28 @@
 /**
- * The `/bytefly` surface: one command, `/bytefly [doctor] [settings] [extension] [refresh]`.
+ * The `/bytefly` surface: one command, `/bytefly [doctor] [settings] [update] [extension] [refresh]`.
  *
  * Without `doctor` it opens the extension screen: the dock in `tui`, the
  * grouped listing elsewhere. `settings` opens the Settings section, or prints
- * its grouped listing outside `tui` without resolving packages. With `doctor`
- * it produces the doctor report — the same text `run_doctor` returns — for the
- * whole set or one named extension; in `tui` the report is the dock screen.
- * Discovery, the doctor probe, and the dirty-to-reload confirm all live here.
- * The doctor runtime is injected by the composition root, so `run_doctor` and
- * the screen keep reading one cache.
+ * its grouped listing outside `tui` without resolving packages. `update`
+ * re-runs the published-version check and reports what it found, which is the
+ * one place a request is made on demand. With `doctor` it produces the doctor
+ * report — the same text `run_doctor` returns — for the whole set or one named
+ * extension; in `tui` the report is the dock screen. Discovery, the doctor
+ * probe, and the dirty-to-reload confirm all live here. The doctor runtime and
+ * the update handle are injected by the composition root, so `run_doctor` and
+ * the screen keep reading one cache, and the command paints the marker it finds.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import pkg from "../../../package.json";
 import { sanitizeLine } from "../../../lib/format.ts";
 import { withRailsSuppressed } from "../../../lib/rails.ts";
 import { REQUIREMENTS, type ExtensionReport } from "../../../lib/requirements.ts";
 import { formatExtension, formatReport, hasProblems } from "../doctor/format.ts";
 import type { DoctorRuntime } from "../doctor/runtime.ts";
+import { updateOutcomeText } from "../update/format.ts";
+import type { UpdateHandle } from "../update/register.ts";
 import { createSettingsStores, discoverExtensions, type DiscoveryDeps } from "../picker/discovery.ts";
 import { createExtensionsPickerRuntime, type ExtensionsPickerRuntime } from "../picker/runtime.ts";
 import type { Discovery } from "../picker/types.ts";
@@ -31,6 +36,8 @@ import type { PanelSection } from "./types.ts";
 export interface PanelCommandDeps {
 	/** The doctor runtime created by `registerDoctor`; shared with `run_doctor`. */
 	doctor: DoctorRuntime;
+	/** The update handle `registerUpdate` returns, for `/bytefly update`. */
+	update: UpdateHandle;
 	/** The picker's discovery seam. */
 	discover?: (deps: DiscoveryDeps) => Promise<Discovery>;
 	/** The Settings runtime seam. */
@@ -49,13 +56,14 @@ function selectableNames(discovery: Discovery): Set<string> {
 }
 
 /** The values a bare `/bytefly <tab>` offers, in screen order. */
-const FIRST_TOKENS = ["doctor", "settings", ...Object.keys(REQUIREMENTS), "refresh"] as const;
+const FIRST_TOKENS = ["doctor", "settings", "update", ...Object.keys(REQUIREMENTS), "refresh"] as const;
 
 /**
  * Argument completions. The host replaces the whole argument text with the
  * returned `value`, so a second token returns the full `doctor <name>` or
- * `<name> refresh` argument rather than just the word. `/bytefly settings` takes
- * no name, and `refresh` is never followed by another token.
+ * `<name> refresh` argument rather than just the word. `/bytefly settings` and
+ * `/bytefly update` take no name, and `refresh` is never followed by another
+ * token.
  */
 function completions(prefix: string): Array<{ value: string; label: string }> | null {
 	const [first = "", second, ...rest] = prefix.trimStart().split(/\s+/);
@@ -64,7 +72,7 @@ function completions(prefix: string): Array<{ value: string; label: string }> |
 		const options = FIRST_TOKENS.filter((option) => option.startsWith(first));
 		return options.length > 0 ? options.map((option) => ({ value: `${option} `, label: option })) : null;
 	}
-	if (first === "settings" || first === "refresh") return null;
+	if (first === "settings" || first === "refresh" || first === "update") return null;
 	const options = (first === "doctor" ? [...Object.keys(REQUIREMENTS), "refresh"] : ["refresh"]).filter((option) =>
 		option.startsWith(second),
 	);
@@ -72,7 +80,7 @@ function completions(prefix: string): Array<{ value: string; label: string }> |
 }
 
 /** Which bytefly surface the arguments select. */
-type PanelMode = "screen" | "doctor";
+type PanelMode = "screen" | "doctor" | "update";
 
 /** `/bytefly [doctor] [settings] [extension] [refresh]`, parsed. */
 interface PanelArgs {
@@ -85,12 +93,15 @@ interface PanelArgs {
 	refresh: boolean;
 }
 
-/** Parse `/bytefly [doctor] [settings] [extension] [refresh]`; extra tokens are ignored. */
+/** Parse `/bytefly [doctor] [settings] [update] [extension] [refresh]`; extra tokens are ignored. */
 function parseArgs(args: string): PanelArgs {
 	const parts = args.trim().split(/\s+/).filter(Boolean);
 	const refresh = parts.includes("refresh");
 	const rest = parts.filter((part) => part !== "refresh");
 	if (rest[0] === "doctor") return { mode: "doctor", section: "extensions", name: rest[1], refresh };
+	// `update` is already a refresh of the published version, so a stray `refresh`
+	// beside it is accepted and ignored rather than refused.
+	if (rest[0] === "update") return { mode: "update", section: "extensions", refresh };
 	if (rest[0] === "settings") return { mode: "screen", section: "settings", name: rest[1], refresh };
 	return { mode: "screen", section: "extensions", name: rest[0], refresh };
 }
@@ -146,6 +157,16 @@ export function registerPanel(pi: ExtensionAPI, deps: PanelCommandDeps): void {
 		};
 		const settingsNotice = (message: string): void => surfaceNotice(message, "warning");
 
+		// `/bytefly update` answers one question and resolves nothing: no package
+		// discovery, no doctor probe, no screen. It is the one path a version check
+		// takes on demand, so the request happens here and nowhere else.
+		if (mode === "update") {
+			const outcome = await deps.update.recheck();
+			const { text, severity } = updateOutcomeText(outcome, pkg.version);
+			ctx.ui.notify(text, severity);
+			return;
+		}
+
 		// Settings outside `tui` prints its grouped listing without resolving
 		// packages or probing the doctor.
 		if (section === "settings" && ctx.mode !== "tui") {