@gavin-hu/my-pi-agent 0.12.0 → 0.13.1

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") {

package/extensions/bytefly/panel/settings.ts

@@ -6,15 +6,16 @@
  * views, cycling, validation, and grouping — so the screen and the runtime share
  * one definition and the tests need no host.
  *
- * The catalogue is deliberately curated: one proven row family at a time. It
- * covers scalars (a boolean checkbox, an enum cycle, a short string with its own
- * rule), both scopes, both write paths, and — with `price.currency.decimals` —
- * one nested key. Arrays, nested tariffs, and credentials are still JSON edits.
+ * The catalogue covers every scalar preference: booleans, enums, short strings,
+ * and — with `doctor.timeoutMs` — a number. Each row states its own rule, so a
+ * value the screen accepts is a value the loader keeps. Arrays (`doctor.skip`),
+ * the `rates` table, and `price.peak` stay JSON edits: a list, a table, and a
+ * nested object are not one row.
  */
 
 import { configSection, configValueAt } from "../../../lib/config.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
-import { DEFAULT_CHROME_CONFIG, normalizeChromeConfig } from "../chrome.ts";
+import { DEFAULT_CHROME_CONFIG, isRailGlyph, normalizeChromeConfig } from "../chrome.ts";
 import { DEFAULT_CONFIG as DEFAULT_DOCTOR_CONFIG, normalizeConfig as normalizeDoctorConfig } from "../doctor/config.ts";
 import {
 	CURRENCY_DEFAULTS,
@@ -136,14 +137,6 @@ const ON_OFF: readonly SettingOption[] = [
 	{ value: "true", label: "On" },
 ];
 
-/** Rail glyphs offered in the curated picker; every one is one column. */
-const RAIL_OPTIONS: readonly SettingOption[] = [
-	{ value: GLYPHS.divider, label: GLYPHS.divider },
-	{ value: "│", label: "│" },
-	{ value: "┃", label: "┃" },
-	{ value: "▏", label: "▏" },
-];
-
 /** The notify section's delivery methods, labeled by the surface each reaches. */
 const METHOD_OPTIONS: readonly SettingOption[] = [
 	{ value: "auto", label: "Auto" },
@@ -160,6 +153,51 @@ const DECIMALS_OPTIONS: readonly SettingOption[] = [0, 1, 2, 3, 4].map((value) =
 	label: String(value),
 }));
 
+/**
+ * A text rule for a whole number inside an inclusive range.
+ *
+ * The bounds are the loader's own (`doctor.timeoutMs` is clamped to 100-30000),
+ * so an accepted value is never silently clamped on the next read. `maxLength`
+ * only stops a runaway buffer; `validate` is the rule.
+ */
+function integerRule(min: number, max: number): TextRule {
+	return {
+		maxLength: String(max).length + 2,
+		validate(raw) {
+			const text = raw.trim();
+			if (!/^\d+$/.test(text)) return `Use a whole number, ${min} to ${max}.`;
+			const value = Number(text);
+			if (value < min || value > max) return `Out of range: ${min} to ${max}.`;
+			return undefined;
+		},
+	};
+}
+
+/**
+ * A text rule for a money amount inside an inclusive range: a whole number or a
+ * decimal with up to four places, matching the loader's clamp for `price.budget`.
+ * `0` is a legitimate value (the guardrail is off), so it is not rejected.
+ */
+function amountRule(min: number, max: number): TextRule {
+	return {
+		maxLength: 16,
+		validate(raw) {
+			const text = raw.trim();
+			if (!/^\d+(?:\.\d{1,4})?$/.test(text)) return `Use an amount like 5 or 2.50, ${min} to ${max}.`;
+			const value = Number(text);
+			if (!Number.isFinite(value) || value < min || value > max) return `Out of range: ${min} to ${max}.`;
+			return undefined;
+		},
+	};
+}
+
+/** The rail's rule: the loader drops anything that is not one column. */
+const RAIL_RULE: TextRule = {
+	maxLength: 4,
+	validate: (raw) =>
+		isRailGlyph(raw) ? undefined : "Use exactly one column: a single glyph, with no spaces or control characters.",
+};
+
 /** The v1 catalogue, in screen order. */
 export const SETTING_ROWS: readonly SettingDescriptor[] = [
 	{
@@ -185,6 +223,54 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		options: ON_OFF,
 		config: { section: "notify", path: ["enabled"] },
 	},
+	{
+		id: "notify.turnFinished",
+		group: "notifications",
+		label: "Turn finished",
+		description: "Announce it when a full agent run settles.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "notify", path: ["turnFinished"] },
+	},
+	{
+		id: "notify.needsInput",
+		group: "notifications",
+		label: "Needs input",
+		description: "Announce it when the agent opens a prompt and waits for an answer.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "notify", path: ["needsInput"] },
+	},
+	{
+		id: "notify.jobFinished",
+		group: "notifications",
+		label: "Job finished",
+		description: "Announce it when a background job or watcher settles.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "notify", path: ["jobFinished"] },
+	},
+	{
+		id: "notify.matchFound",
+		group: "notifications",
+		label: "Watcher matched",
+		description: "Announce it when a `watch` whose `wake` is on matches while the agent is idle.",
+		source: "bytefly",
+		kind: "boolean",
+		fallback: "true",
+		json: "boolean",
+		options: ON_OFF,
+		config: { section: "notify", path: ["matchFound"] },
+	},
 	{
 		id: "notify.method",
 		group: "notifications",
@@ -223,6 +309,19 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		options: ON_OFF,
 		config: { section: "doctor", path: ["proactive"] },
 	},
+	{
+		id: "doctor.timeoutMs",
+		group: "diagnostics",
+		label: "Probe timeout",
+		description: "How long one doctor probe may take, in milliseconds; 100 to 30000.",
+		source: "bytefly",
+		kind: "text",
+		fallback: String(DEFAULT_DOCTOR_CONFIG.timeoutMs),
+		json: "number",
+		options: [],
+		text: integerRule(100, 30_000),
+		config: { section: "doctor", path: ["timeoutMs"] },
+	},
 	{
 		id: "price.currency.code",
 		group: "pricing",
@@ -258,15 +357,29 @@ export const SETTING_ROWS: readonly SettingDescriptor[] = [
 		options: DECIMALS_OPTIONS,
 		config: { section: "price", path: ["currency", "decimals"] },
 	},
+	{
+		id: "price.budget",
+		group: "pricing",
+		label: "Session budget",
+		description: "Warn once when the session's cost reaches this amount; 0 is off. It never stops a turn.",
+		source: "bytefly",
+		kind: "text",
+		fallback: "0",
+		json: "number",
+		options: [],
+		text: amountRule(0, 10_000_000),
+		config: { section: "price", path: ["budget"] },
+	},
 	{
 		id: "chrome.rail",
 		group: "transcript",
 		label: "Rail glyph",
-		description: "The single-column glyph that leads a tool result or notice body.",
+		description: "The single-column glyph that leads a tool result or notice body, e.g. ╎ │ ┃ ▏.",
 		source: "bytefly",
-		kind: "enum",
+		kind: "text",
 		fallback: GLYPHS.divider,
-		options: RAIL_OPTIONS,
+		options: [],
+		text: RAIL_RULE,
 		config: { section: "chrome", path: ["rail"] },
 	},
 	{

package/extensions/bytefly/update/cache.ts

@@ -0,0 +1,73 @@
+/**
+ * The published-version answer, cached on disk with the time it was read.
+ *
+ * The check already fires once per session, which leaves two gaps: a session open
+ * for days never re-reads npm, and every new session pays for a request it made
+ * minutes earlier. A timestamp is what fixes the second, so the cache lives in the
+ * agent directory rather than in memory — one entry, one window, shared by every
+ * session that starts inside it.
+ *
+ * A cache can only ever be a miss. An absent, unreadable, or wrong-typed file
+ * reads as `undefined` and the caller fetches; nothing here throws, because a
+ * stale file must never become a session error.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeConfigFile } from "../../../lib/config.ts";
+import { parseVersion } from "./version.ts";
+
+/** The file name under `<agentDir>/bytefly/`. */
+export const UPDATE_CACHE_FILE = "update.json";
+
+/** How long a cached answer is reused before the next session re-reads npm. */
+export const UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** One cached answer: the newest published version and when it was read. */
+export interface UpdateCacheEntry {
+	/** The version npm's `latest` tag pointed at. */
+	latest: string;
+	/** Epoch milliseconds of the read that produced `latest`. */
+	checkedAt: number;
+}
+
+/** Where the cache lives for an agent directory. */
+export function updateCachePath(agentDir: string): string {
+	return join(agentDir, "bytefly", UPDATE_CACHE_FILE);
+}
+
+/** Read the cache; a missing, corrupt, or mistyped entry is `undefined`. */
+export function readUpdateCache(path: string): UpdateCacheEntry | undefined {
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown> | undefined;
+		if (!raw || typeof raw !== "object") return undefined;
+		const latest = typeof raw.latest === "string" ? raw.latest.trim() : "";
+		const checkedAt = typeof raw.checkedAt === "number" && Number.isFinite(raw.checkedAt) ? raw.checkedAt : 0;
+		if (!parseVersion(latest) || checkedAt <= 0) return undefined;
+		return { latest, checkedAt };
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Write the cache atomically (a sibling temp file, then a rename). The caller
+ * treats a throw as a miss: a read-only agent directory must not break a session.
+ */
+export function writeUpdateCache(path: string, entry: UpdateCacheEntry): void {
+	writeConfigFile(path, { latest: entry.latest, checkedAt: entry.checkedAt });
+}
+
+/**
+ * Whether an entry is still inside the window. The boundary is inclusive: an
+ * entry read exactly `ttlMs` ago is reused, so the window never flickers.
+ */
+export function isFresh(
+	entry: UpdateCacheEntry | undefined,
+	now: number,
+	ttlMs: number = UPDATE_CACHE_TTL_MS,
+): boolean {
+	if (!entry) return false;
+	const age = now - entry.checkedAt;
+	return age >= 0 && age <= ttlMs;
+}

package/extensions/bytefly/update/format.ts

@@ -1,32 +1,87 @@
 /**
- * Wording for the update check: the header marker and the one transcript notice.
+ * Wording for the update check: the header marker, the one transcript notice, and
+ * the answer an explicit re-check prints.
  *
- * Both read the same two facts — the version this session loaded and the version
- * the registry publishes — and neither adds a third. The marker is the shortest
- * honest form (`↑0.12.0`), and the notice names the command instead of printing
- * a changelog link the notice renderer cannot open.
+ * All three read the same two facts — the version this session loaded and the
+ * version the registry publishes — and none adds a third. The marker is the
+ * shortest honest form (`↑0.12.0`); the notice names the command and the release
+ * URL as text, because the notice renderer has no link support; and the re-check
+ * says what it just found, including the two cases it cannot answer (offline, and
+ * a registry it could not read).
  */
 
+import pkg from "../../../package.json";
 import { noticeMessage, type NoticeMessage } from "../../../lib/notice.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import type { UpdateOutcome } from "./state.ts";
 
 /** The header marker: an up arrow and the newest version, e.g. `↑0.12.0`. */
 export function updateMarker(latest: string): string {
 	return `${GLYPHS.update}${latest}`;
 }
 
+/**
+ * The release page for a version, or `undefined` when this checkout does not name
+ * a GitHub repository. Derived from `package.json` so a rename cannot leave a dead
+ * link behind in the notice.
+ */
+export function releaseUrl(version: string): string | undefined {
+	const url = (pkg.repository as { url?: string } | undefined)?.url ?? "";
+	const base = url.replace(/\.git$/, "");
+	if (!/^https:\/\/github\.com\/[^/]+\/[^/]+$/.test(base)) return undefined;
+	return `${base}/releases/tag/v${version}`;
+}
+
 /** The single notice a session posts when a newer version is published. */
 export function updateNotice(current: string, latest: string): NoticeMessage {
+	const release = releaseUrl(latest);
+	const command = "pi update --extensions";
 	return noticeMessage({
-		content: `bytefly ${latest} is available (current ${current}). Run \`pi update --extensions\` to update.`,
+		content:
+			`bytefly ${latest} is available (current ${current}). Run \`${command}\` to update.` +
+			(release ? ` Release notes: ${release}` : ""),
 		details: {
 			source: "bytefly",
 			title: `${latest} is available`,
 			severity: "info",
-			items: [
-				{ label: "current", detail: `v${current}` },
-				{ label: "update", detail: "pi update --extensions" },
-			],
+			items: release
+				? [
+						{ label: "current", detail: `v${current}` },
+						{ label: "update", detail: command },
+						{ label: "release", detail: release },
+					]
+				: [
+						{ label: "current", detail: `v${current}` },
+						{ label: "update", detail: command },
+					],
 		},
 	});
 }
+
+/**
+ * What `/bytefly update` prints. The background check is silent because nobody
+ * asked; here someone did, so a skip and a failed read are answers too.
+ */
+export function updateOutcomeText(
+	outcome: UpdateOutcome,
+	current: string,
+): { text: string; severity: "info" | "warning" } {
+	switch (outcome.kind) {
+		case "offline":
+			return { text: "bytefly: the update check was skipped (PI_OFFLINE is set).", severity: "info" };
+		case "failed":
+			return {
+				text: "bytefly: could not read the published version — check the network and try again.",
+				severity: "warning",
+			};
+		case "current":
+			return { text: `bytefly: up to date — v${outcome.latest} is the newest published version.`, severity: "info" };
+		case "available": {
+			const release = releaseUrl(outcome.latest);
+			return {
+				text: `bytefly: v${outcome.latest} is available (current ${current}).${release ? ` ${release}` : ""}`,
+				severity: "info",
+			};
+		}
+	}
+}

package/extensions/bytefly/update/register.ts

@@ -1,6 +1,6 @@
 /**
- * The update check's lifecycle: read the published version once per interactive
- * session, record it when it is newer, and announce it once per load.
+ * The update check's lifecycle: reuse the cached answer or read the registry once
+ * per interactive session, record a newer version, and announce it once per load.
  *
  * The request is fired without awaiting. Pi awaits `session_start` handlers, so
  * a slow registry would otherwise hold the first prompt; Pi's own version check
@@ -8,49 +8,106 @@
  * version is silent, and a generation counter keeps a request that resolves
  * after shutdown from writing into the next session's state.
  *
- * `/bytefly` and `doctor` do not report this: an available update is not a
- * prerequisite problem, and the header plus one notice are the whole surface.
+ * A cached answer with a timestamp is what makes a long-lived session different
+ * from a fresh one: a session that starts inside the window reuses the last read
+ * instead of repeating it, and `recheck()` ignores the window so `/bytefly update`
+ * can look again without a restart. `/bytefly` and `doctor` do not report the
+ * version: an available update is not a prerequisite problem.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import pkg from "../../../package.json";
 import { isOffline } from "../../../lib/env.ts";
+import { isFresh, readUpdateCache, updateCachePath, writeUpdateCache, type UpdateCacheEntry } from "./cache.ts";
 import { fetchLatestVersion } from "./check.ts";
 import { updateNotice } from "./format.ts";
-import type { UpdateSource } from "./state.ts";
+import type { UpdateOutcome, UpdateSource } from "./state.ts";
 import { isNewerVersion } from "./version.ts";
 
-/** Test seams; production uses the registry read and `PI_OFFLINE`. */
+/** The cache, as the lifecycle sees it: read on start, written after a read. */
+export interface UpdateCache {
+	/** The last recorded answer, or `undefined` for a miss. */
+	read(): UpdateCacheEntry | undefined;
+	/** Record an answer; a throw is treated as a miss. */
+	write(entry: UpdateCacheEntry): void;
+}
+
+/** What `registerUpdate` returns, so the panel can re-run the check on demand. */
+export interface UpdateHandle {
+	/** Read the registry now, ignoring the cache window. Never throws. */
+	recheck(): Promise<UpdateOutcome>;
+}
+
+/** Test seams; production uses the registry read, `PI_OFFLINE`, and the agent dir. */
 export interface UpdateDeps {
 	/** Replace the registry read; a rejection counts as no answer. */
 	fetchLatest?: () => Promise<string | undefined>;
 	/** Replace the `PI_OFFLINE` check. */
 	isOffline?: () => boolean;
+	/** Replace the disk cache. */
+	cache?: UpdateCache;
+	/** Replace the clock the cache timestamp is read from. */
+	now?: () => number;
 	/** Called once a newer version is recorded, so a mounted surface repaints. */
 	onUpdate?: () => void;
 }
 
+/** The on-disk cache under the agent directory, built lazily so it is per call. */
+function diskCache(): UpdateCache {
+	return {
+		read: () => readUpdateCache(updateCachePath(getAgentDir())),
+		write: (entry) => {
+			try {
+				writeUpdateCache(updateCachePath(getAgentDir()), entry);
+			} catch {
+				// A read-only agent directory costs the next session one request, nothing more.
+			}
+		},
+	};
+}
+
 /**
  * Register the check. `updates` is the same store the header reads, so recording
  * a version and calling `onUpdate` is what puts the marker on screen.
  */
-export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: UpdateDeps = {}): void {
+export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: UpdateDeps = {}): UpdateHandle {
 	const readLatest = deps.fetchLatest ?? (() => fetchLatestVersion());
 	const offline = deps.isOffline ?? isOffline;
+	const cache = deps.cache ?? diskCache();
+	const now = deps.now ?? Date.now;
 	// A session is announced at most once per load, even if `session_start` fires
 	// again after a resume or a session replacement.
 	let announced = false;
 	let generation = 0;
 
+	/** Record a newer version and repaint the marker. */
+	const paint = (latest: string): void => {
+		if (!isNewerVersion(latest, pkg.version)) return;
+		updates.set(latest);
+		deps.onUpdate?.();
+	};
+
+	/** The once-per-load transcript notice, posted only for a strictly newer version. */
+	const announce = (latest: string): void => {
+		if (announced || !isNewerVersion(latest, pkg.version)) return;
+		announced = true;
+		pi.sendMessage(updateNotice(pkg.version, latest));
+	};
+
+	/** One answer, from the cache or the registry: paint the marker, announce it once. */
+	const record = (entry: UpdateCacheEntry): void => {
+		paint(entry.latest);
+		announce(entry.latest);
+	};
+
 	const check = async (token: number): Promise<void> => {
 		try {
 			const latest = await readLatest();
 			if (latest === undefined || token !== generation) return;
-			if (announced || !isNewerVersion(latest, pkg.version)) return;
-			announced = true;
-			updates.set(latest);
-			deps.onUpdate?.();
-			pi.sendMessage(updateNotice(pkg.version, latest));
+			const entry = { latest, checkedAt: now() };
+			cache.write(entry);
+			record(entry);
 		} catch {
 			// A background check never surfaces an error: the session does not know it ran.
 		}
@@ -60,7 +117,19 @@ export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: Up
 		// The marker lives in bytefly's header and the notice in a transcript, so a
 		// non-interactive run has nothing to draw and makes no request.
 		if (ctx.mode !== "tui") return;
-		if (announced || offline()) return;
+		if (offline()) {
+			// No request, so the window does not matter: the cached answer is the best
+			// one available, and the marker is advisory.
+			const cached = cache.read();
+			if (cached) record(cached);
+			return;
+		}
+		const cached = cache.read();
+		if (cached && isFresh(cached, now())) {
+			record(cached);
+			return;
+		}
+		if (announced) return;
 		void check(generation);
 	});
 
@@ -69,4 +138,21 @@ export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: Up
 		generation++;
 		updates.set();
 	});
+
+	return {
+		async recheck() {
+			if (offline()) return { kind: "offline" };
+			let latest: string | undefined;
+			try {
+				latest = await readLatest();
+			} catch {
+				return { kind: "failed" };
+			}
+			if (latest === undefined) return { kind: "failed" };
+			cache.write({ latest, checkedAt: now() });
+			// The caller prints the answer, so this path never posts a notice.
+			paint(latest);
+			return isNewerVersion(latest, pkg.version) ? { kind: "available", latest } : { kind: "current", latest };
+		},
+	};
 }