@oh-my-pi/pi-coding-agent 16.1.3 → 16.1.4

package/dist/types/modes/components/cache-invalidation-marker.d.ts

@@ -6,20 +6,33 @@ export interface CacheInvalidation {
     reprocessedTokens: number;
 }
 /**
- * Decide whether `current` turn lost the prompt cache that `prev` established.
+ * Decide whether `current` turn lost a *working* prompt cache that `prev` was
+ * reusing.
  *
  * The provider reports a warm prefix as `cacheRead`; a model/thinking/tool/
  * system-prompt change (or a history rewrite) breaks the prefix, so the next
- * request reads nothing from cache and re-pays for the whole prompt. We detect
- * that as: the previous turn cached a meaningful prefix, yet this turn's
+ * request reads nothing from cache and re-pays for the whole prompt. We flag
+ * only the transition where a demonstrably warm cache goes cold: the previous
+ * turn must have actually READ a meaningful prefix back, and this turn's
  * `cacheRead` collapsed to zero while it still reprocessed a non-trivial prompt.
- * Returns `undefined` (no marker) for the first turn, tiny contexts, turns
- * that reused any cache, and — crucially — turns on providers with *implicit*
- * best-effort caching. Only an explicit, prefix-controlled cache (Anthropic /
- * Bedrock `cache_control`) re-creates the prefix on a cold turn (`cacheWrite >
- * 0`); implicit caches (Google / OpenAI / Fireworks) report `cacheWrite: 0` and
- * drop `cacheRead` to zero intermittently as routine propagation noise that
- * self-heals the next turn, so flagging it would be a false positive.
+ *
+ * Requiring a prior warm read is deliberate. A turn that merely WROTE the prefix
+ * (`cacheRead` 0) has not proven the cache is live — that is the session's first
+ * request, or a re-write after expiry — so a following cold turn there is
+ * expected, not an invalidation the user caused (e.g. a long-running first tool
+ * call outliving the provider's 5-minute cache TTL surfaced a spurious "cache
+ * miss" right under the opening message). It also collapses a run of consecutive
+ * cold turns to the single marker at the moment the cache actually broke, instead
+ * of repeating the banner on every turn while it re-warms.
+ *
+ * Returns `undefined` (no marker) for the first turn, turns whose predecessor
+ * never read a warm prefix, tiny contexts, turns that reused any cache, and —
+ * crucially — turns on providers with *implicit* best-effort caching. Only an
+ * explicit, prefix-controlled cache (Anthropic / Bedrock `cache_control`)
+ * re-creates the prefix on a cold turn (`cacheWrite > 0`); implicit caches
+ * (Google / OpenAI / Fireworks) report `cacheWrite: 0` and drop `cacheRead` to
+ * zero intermittently as routine propagation noise that self-heals the next
+ * turn, so flagging it would be a false positive.
  */
 export declare function detectCacheInvalidation(prev: Usage | undefined, current: Usage): CacheInvalidation | undefined;
 /**

package/dist/types/modes/components/status-line/component.d.ts

@@ -34,9 +34,8 @@ export declare class StatusLineComponent implements Component {
     dispose(): void;
     invalidate(): void;
     /**
-     * Background-refresh the Anthropic OAuth quota report. Guarded by a 5-min
-     * TTL on both success (cache lifetime) and error (backoff). Exposed
-     * (non-private) so unit tests can verify the backoff invariant.
+     * Startup redraws only arm a short-delayed task; timeout releases the render
+     * cadence while a late successful fetch can still refresh the cached segment.
      */
     refreshUsageInBackground(): void;
     /**

package/dist/types/sdk.d.ts

@@ -262,6 +262,18 @@ export declare function discoverSessionExtensionPaths(options: Pick<CreateAgentS
  * repeated. Keep this the single source of the discovery branch logic.
  */
 export declare function loadSessionExtensions(options: Pick<CreateAgentSessionOptions, "disableExtensionDiscovery" | "additionalExtensionPaths">, cwd: string, settings: Settings, eventBus: EventBus): Promise<LoadExtensionsResult>;
+/**
+ * Load discovered/configured extensions and register their providers into
+ * `modelRegistry`, then discover the dynamic provider catalogs. One-shot CLIs
+ * (`omp bench`, dry-balance) build a bare {@link ModelRegistry} that only knows
+ * built-in catalog providers; without this, providers contributed by an
+ * extension (e.g. a custom OpenAI-compatible provider under
+ * `~/.omp/agent/extensions/`) never reach model resolution. Mirrors the
+ * session / `omp models` path: drain the queued provider registrations, then
+ * `refreshRuntimeProviders` so dynamically-discovered models exist before
+ * selectors are resolved.
+ */
+export declare function loadCliExtensionProviders(modelRegistry: ModelRegistry, settings: Settings, cwd: string, options?: Pick<CreateAgentSessionOptions, "disableExtensionDiscovery" | "additionalExtensionPaths">): Promise<void>;
 /**
  * Discover skills from cwd and agentDir.
  */

package/dist/types/session/agent-session.d.ts

@@ -399,6 +399,8 @@ export declare class AgentSession {
     nextToolChoiceDirective(): ToolChoiceDirective | undefined;
     /** Peek the head non-forcing pending preview invoker, for the `resolve` tool's dispatch. */
     peekPendingInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    /** Clear stale non-forcing pending preview invokers after `resolve` proves none can run. */
+    clearPendingInvokers(): void;
     /**
      * Force the next model call to target a specific active tool, then terminate
      * the agent loop. Pushes a two-step sequence [forced, "none"] so the model

package/dist/types/session/tool-choice-queue.d.ts

@@ -71,6 +71,8 @@ export declare class ToolChoiceQueue {
     registerPendingInvoker(id: string, sourceToolName: string, onInvoked: (input: unknown) => Promise<unknown> | unknown): void;
     /** Drop the pending invoker with this id (e.g. after it resolves). */
     removePendingInvoker(id: string): void;
+    /** Drop every pending preview invoker without touching hard tool-choice directives. */
+    clearPendingInvokers(): void;
     /** True when at least one non-forcing pending preview is registered. */
     get hasPendingInvoker(): boolean;
     /** The head (most-recently registered) pending invoker's handler, for resolve dispatch. */

package/dist/types/tools/index.d.ts

@@ -276,6 +276,8 @@ export interface ToolSession {
      *  tool dispatches to it so a staged preview resolves WITHOUT forcing tool_choice — the
      *  agent-loop's SoftToolRequirement lifecycle owns reminder injection and escalation. */
     peekPendingInvoker?(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    /** Clear stale pending preview markers when `resolve` cannot dispatch them. */
+    clearPendingInvokers?(): void;
     /** Peek the long-lived "standing" resolve handler registered by a mode (e.g. plan mode).
      *  Consulted by the `resolve` tool as a fallback when no queue invoker is in flight,
      *  letting modes accept `resolve` invocations without forcing the tool choice every turn. */

package/dist/types/tui/hyperlink.d.ts

@@ -5,6 +5,7 @@
  * - `"off"`: never
  * - `"auto"`: when `process.stdout.isTTY`, `NO_COLOR` is unset, and the detected terminal reports hyperlink support
  * - `"always"`: unconditionally (useful for viewers that support OSC 8 without advertising it)
+ * Before settings initialization, returns false so early render paths stay plain text.
  */
 export declare function isHyperlinkEnabled(): boolean;
 /**
@@ -23,8 +24,8 @@ export declare function urlHyperlink(url: string, displayText: string): string;
  * Wrap `displayText` in an OSC 8 hyperlink pointing at an HTTP(S) URL,
  * bypassing terminal capability auto-detection. Used for auth prompts where
  * an inert "click" label blocks login on terminals whose capabilities are
- * not advertised. Still returns plain text when the user has explicitly
- * opted out via `tui.hyperlinks=off`.
+ * not advertised. Still returns plain text before settings initialization or
+ * when the user has explicitly opted out via `tui.hyperlinks=off`.
  */
 export declare function urlHyperlinkAlways(url: string, displayText: string): string;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "16.1.3",
+	"version": "16.1.4",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -48,17 +48,17 @@
 		"@agentclientprotocol/sdk": "0.25.0",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "16.1.3",
-		"@oh-my-pi/omp-stats": "16.1.3",
-		"@oh-my-pi/pi-agent-core": "16.1.3",
-		"@oh-my-pi/pi-ai": "16.1.3",
-		"@oh-my-pi/pi-catalog": "16.1.3",
-		"@oh-my-pi/pi-mnemopi": "16.1.3",
-		"@oh-my-pi/pi-natives": "16.1.3",
-		"@oh-my-pi/pi-tui": "16.1.3",
-		"@oh-my-pi/pi-utils": "16.1.3",
-		"@oh-my-pi/pi-wire": "16.1.3",
-		"@oh-my-pi/snapcompact": "16.1.3",
+		"@oh-my-pi/hashline": "16.1.4",
+		"@oh-my-pi/omp-stats": "16.1.4",
+		"@oh-my-pi/pi-agent-core": "16.1.4",
+		"@oh-my-pi/pi-ai": "16.1.4",
+		"@oh-my-pi/pi-catalog": "16.1.4",
+		"@oh-my-pi/pi-mnemopi": "16.1.4",
+		"@oh-my-pi/pi-natives": "16.1.4",
+		"@oh-my-pi/pi-tui": "16.1.4",
+		"@oh-my-pi/pi-utils": "16.1.4",
+		"@oh-my-pi/pi-wire": "16.1.4",
+		"@oh-my-pi/snapcompact": "16.1.4",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",

package/src/cli/bench-cli.ts

@@ -25,7 +25,7 @@ import {
 } from "../config/model-resolver";
 import { Settings } from "../config/settings";
 import benchPrompt from "../prompts/bench.md" with { type: "text" };
-import { discoverAuthStorage } from "../sdk";
+import { discoverAuthStorage, loadCliExtensionProviders } from "../sdk";
 import { resolveThinkingLevelForModel, shouldDisableReasoning, toReasoningEffort } from "../thinking";
 
 const DEFAULT_RUNS = 1;
@@ -145,6 +145,23 @@ function isFirstTokenEvent(event: AssistantMessageEvent): boolean {
 	}
 }
 
+/** Final message carries visible output — non-empty text/thinking or a tool call. */
+function hasVisibleFinalContent(message: AssistantMessage): boolean {
+	return message.content.some(block => {
+		switch (block.type) {
+			case "text":
+				return block.text.length > 0;
+			case "thinking":
+				return block.thinking.length > 0;
+			case "redactedThinking":
+			case "toolCall":
+				return true;
+			default:
+				return false;
+		}
+	});
+}
+
 /**
  * Tokens/s over the generation window (duration minus TTFT) so queue/prefill
  * latency does not dilute throughput. Falls back to total duration when the
@@ -232,6 +249,18 @@ async function runBenchRequest(
 		const rawTtft = message.ttft ?? (firstTokenAt === undefined ? durationMs : firstTokenAt - startedAt);
 		const ttftMs = Number.isFinite(rawTtft) && rawTtft > 0 ? rawTtft : 0;
 		const outputTokens = Number.isFinite(message.usage.output) && message.usage.output > 0 ? message.usage.output : 0;
+		// A run that streamed no content (no delta/end event set firstTokenAt),
+		// carries no visible final content, and measured no output tokens
+		// benchmarked nothing — a genuinely empty stream (e.g. a gateway that 200s
+		// with an empty body). Surface it as a failure instead of a misleading
+		// 0-token "✓". Streaming and buffered providers that produce content keep
+		// passing even when usage is omitted.
+		if (firstTokenAt === undefined && outputTokens === 0 && !hasVisibleFinalContent(message)) {
+			return {
+				ok: false,
+				error: `provider returned no output (0 tokens, empty stream; stop reason: ${message.stopReason ?? "unknown"})`,
+			};
+		}
 		return {
 			ok: true,
 			ttftMs,
@@ -328,8 +357,10 @@ export function formatBenchTable(summary: BenchSummary): string {
 async function createDefaultRuntime(): Promise<BenchRuntime> {
 	const authStorage = await discoverAuthStorage();
 	try {
-		const settings = await Settings.init({ cwd: getProjectDir() });
+		const cwd = getProjectDir();
+		const settings = await Settings.init({ cwd });
 		const modelRegistry = new ModelRegistry(authStorage);
+		await loadCliExtensionProviders(modelRegistry, settings, cwd);
 		return {
 			modelRegistry,
 			settings,

package/src/cli/dry-balance-cli.ts

@@ -26,7 +26,7 @@ import {
 } from "../config/model-resolver";
 import { Settings } from "../config/settings";
 import dryBalanceBenchPrompt from "../prompts/dry-balance-bench.md" with { type: "text" };
-import { discoverAuthStorage } from "../sdk";
+import { discoverAuthStorage, loadCliExtensionProviders } from "../sdk";
 
 const DEFAULT_SAMPLE_COUNT = 100;
 const DEFAULT_CONCURRENCY = 32;
@@ -523,8 +523,10 @@ async function runBenchTargets(
 async function createDefaultRuntime(): Promise<DryBalanceRuntime> {
 	const authStorage = await discoverAuthStorage();
 	try {
-		const settings = await Settings.init({ cwd: getProjectDir() });
+		const cwd = getProjectDir();
+		const settings = await Settings.init({ cwd });
 		const modelRegistry = new ModelRegistry(authStorage);
+		await loadCliExtensionProviders(modelRegistry, settings, cwd);
 		return {
 			modelRegistry,
 			settings,

package/src/extensibility/plugins/manager.ts

@@ -248,11 +248,29 @@ export class PluginManager {
 	}
 
 	async #rollbackFailedInstall(
-		actualName: string,
+		actualName: string | undefined,
 		packageJsonBefore: string,
+		bunLockBefore: string | null,
 		snapshot: PluginPackageSnapshot | null,
 	): Promise<void> {
 		await Bun.write(getPluginsPackageJson(), packageJsonBefore);
+
+		// Restore (or remove) bun's lockfile. Without this, a `bun install` +
+		// `bun update` pair that successfully rewrote `bun.lock` would leave the
+		// rejected commit pinned even when validation rolls everything else back.
+		const bunLockPath = path.join(getPluginsDir(), "bun.lock");
+		if (bunLockBefore === null) {
+			await fs.promises.rm(bunLockPath, { force: true });
+		} else {
+			await Bun.write(bunLockPath, bunLockBefore);
+		}
+
+		// `actualName` may be undefined when the install failed before the dep
+		// key was resolved — package.json + bun.lock restoration above is the
+		// complete rollback in that case.
+		if (!actualName) {
+			return;
+		}
 		const packagePath = path.join(getPluginsNodeModules(), actualName);
 		await fs.promises.rm(packagePath, { recursive: true, force: true });
 		if (!snapshot) {
@@ -343,6 +361,19 @@ export class PluginManager {
 		}
 		const pkgJsonPath = getPluginsPackageJson();
 		const packageJsonBefore = await Bun.file(pkgJsonPath).text();
+		// Snapshot bun's lockfile so the rollback path can restore the pin. Every
+		// step below — `bun install`, `bun update`, feature/extension validation,
+		// runtime-config save — must either complete entirely or leave the
+		// lockfile pointing at its pre-install state. Absent before install means
+		// "remove on rollback".
+		const bunLockPath = path.join(getPluginsDir(), "bun.lock");
+		let bunLockBefore: string | null;
+		try {
+			bunLockBefore = await Bun.file(bunLockPath).text();
+		} catch (err) {
+			if (!isEnoent(err)) throw err;
+			bunLockBefore = null;
+		}
 		const depsBefore = await this.#readDeps(pkgJsonPath);
 		const packageInstallSpec = gitSource ? gitInstallSpec(spec.packageName, gitSource) : spec.packageName;
 		const existingActualName = gitSource
@@ -350,24 +381,26 @@ export class PluginManager {
 			: extractPackageName(spec.packageName);
 		const packageSnapshot = await this.#snapshotInstalledPackage(existingActualName);
 
+		// `actualName` is hoisted so the rollback handler can clean up the right
+		// node_modules entry even if a step between `bun install` and the final
+		// validation throws.
+		let actualName: string | undefined;
 		try {
-			// Run npm install
-			const proc = Bun.spawn(["bun", "install", packageInstallSpec], {
+			// Step 1: write the spec into plugins/package.json + node_modules.
+			const installProc = Bun.spawn(["bun", "install", packageInstallSpec], {
 				cwd: getPluginsDir(),
 				stdin: "ignore",
 				stdout: "pipe",
 				stderr: "pipe",
 				windowsHide: true,
 			});
-
-			const exitCode = await proc.exited;
-			if (exitCode !== 0) {
-				const stderr = await new Response(proc.stderr).text();
-				throw new Error(`npm install failed: ${stderr}`);
+			const installExit = await installProc.exited;
+			if (installExit !== 0) {
+				const stderr = await new Response(installProc.stderr).text();
+				throw new Error(`bun install failed: ${stderr}`);
 			}
 			// Resolve actual package name. npm specs encode the name (strip version);
 			// git specs do not, so diff plugins/package.json deps to find the new entry.
-			let actualName: string;
 			if (gitSource) {
 				const depsAfter = await this.#readDeps(pkgJsonPath);
 				let resolved: string | undefined;
@@ -393,8 +426,32 @@ export class PluginManager {
 			} else {
 				actualName = extractPackageName(spec.packageName);
 			}
-			const pkgPath = path.join(getPluginsNodeModules(), actualName, "package.json");
 
+			// Step 2: refresh the git lockfile pin when re-installing an existing
+			// git plugin. `bun install <spec>` is a no-op when the spec matches the
+			// lockfile entry — it never re-resolves the remote ref — so re-running
+			// `omp plugin install github:owner/repo` would silently keep the user on
+			// the original resolved commit even after upstream moved (#3063).
+			// `bun update <name>` re-resolves the ref against the remote and
+			// rewrites the pin; SHA-pinned refs stay put because the commit can't
+			// move. First-time installs skip this — the initial `bun install` already
+			// fetched HEAD. Rollback is handled by the outer catch.
+			if (gitSource && existingActualName) {
+				const updateProc = Bun.spawn(["bun", "update", actualName], {
+					cwd: getPluginsDir(),
+					stdin: "ignore",
+					stdout: "pipe",
+					stderr: "pipe",
+					windowsHide: true,
+				});
+				const updateExit = await updateProc.exited;
+				if (updateExit !== 0) {
+					const stderr = await new Response(updateProc.stderr).text();
+					throw new Error(`bun update ${actualName} failed: ${stderr}`);
+				}
+			}
+
+			const pkgPath = path.join(getPluginsNodeModules(), actualName, "package.json");
 			let pkg: { name: string; version: string; omp?: PluginManifest; pi?: PluginManifest };
 			try {
 				pkg = await Bun.file(pkgPath).json();
@@ -441,18 +498,7 @@ export class PluginManager {
 				enabled: true,
 			};
 
-			try {
-				await this.#validateInstalledExtensions(installedPlugin);
-			} catch (err) {
-				try {
-					await this.#rollbackFailedInstall(actualName, packageJsonBefore, packageSnapshot);
-				} catch (rollbackErr) {
-					const message = err instanceof Error ? err.message : String(err);
-					const rollbackMessage = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
-					throw new Error(`${message}\nRollback failed: ${rollbackMessage}`);
-				}
-				throw err;
-			}
+			await this.#validateInstalledExtensions(installedPlugin);
 
 			// Update runtime config
 			const config = await this.#ensureConfigLoaded();
@@ -464,6 +510,20 @@ export class PluginManager {
 			await this.#saveRuntimeConfig();
 
 			return installedPlugin;
+		} catch (err) {
+			try {
+				await this.#rollbackFailedInstall(
+					actualName ?? existingActualName,
+					packageJsonBefore,
+					bunLockBefore,
+					packageSnapshot,
+				);
+			} catch (rollbackErr) {
+				const message = err instanceof Error ? err.message : String(err);
+				const rollbackMessage = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
+				throw new Error(`${message}\nRollback failed: ${rollbackMessage}`);
+			}
+			throw err;
 		} finally {
 			await this.#cleanupSnapshot(packageSnapshot);
 		}

package/src/modes/components/cache-invalidation-marker.ts

@@ -4,9 +4,9 @@ import { formatNumber } from "@oh-my-pi/pi-utils";
 import { theme } from "../../modes/theme/theme";
 
 /**
- * Minimum cached prefix (read + write) the previous turn must have established
- * before a collapse on the current turn counts as an invalidation. Filters out
- * tiny contexts and providers below the cacheable-prefix floor, where a zero
+ * Minimum prefix the previous turn must have READ back from cache before a
+ * collapse on the current turn counts as an invalidation. Filters out tiny
+ * contexts and providers below the cacheable-prefix floor, where a zero
  * `cacheRead` is expected rather than a reset.
  */
 const MIN_CACHE_FOOTPRINT = 2048;
@@ -18,25 +18,41 @@ export interface CacheInvalidation {
 }
 
 /**
- * Decide whether `current` turn lost the prompt cache that `prev` established.
+ * Decide whether `current` turn lost a *working* prompt cache that `prev` was
+ * reusing.
  *
  * The provider reports a warm prefix as `cacheRead`; a model/thinking/tool/
  * system-prompt change (or a history rewrite) breaks the prefix, so the next
- * request reads nothing from cache and re-pays for the whole prompt. We detect
- * that as: the previous turn cached a meaningful prefix, yet this turn's
+ * request reads nothing from cache and re-pays for the whole prompt. We flag
+ * only the transition where a demonstrably warm cache goes cold: the previous
+ * turn must have actually READ a meaningful prefix back, and this turn's
  * `cacheRead` collapsed to zero while it still reprocessed a non-trivial prompt.
- * Returns `undefined` (no marker) for the first turn, tiny contexts, turns
- * that reused any cache, and — crucially — turns on providers with *implicit*
- * best-effort caching. Only an explicit, prefix-controlled cache (Anthropic /
- * Bedrock `cache_control`) re-creates the prefix on a cold turn (`cacheWrite >
- * 0`); implicit caches (Google / OpenAI / Fireworks) report `cacheWrite: 0` and
- * drop `cacheRead` to zero intermittently as routine propagation noise that
- * self-heals the next turn, so flagging it would be a false positive.
+ *
+ * Requiring a prior warm read is deliberate. A turn that merely WROTE the prefix
+ * (`cacheRead` 0) has not proven the cache is live — that is the session's first
+ * request, or a re-write after expiry — so a following cold turn there is
+ * expected, not an invalidation the user caused (e.g. a long-running first tool
+ * call outliving the provider's 5-minute cache TTL surfaced a spurious "cache
+ * miss" right under the opening message). It also collapses a run of consecutive
+ * cold turns to the single marker at the moment the cache actually broke, instead
+ * of repeating the banner on every turn while it re-warms.
+ *
+ * Returns `undefined` (no marker) for the first turn, turns whose predecessor
+ * never read a warm prefix, tiny contexts, turns that reused any cache, and —
+ * crucially — turns on providers with *implicit* best-effort caching. Only an
+ * explicit, prefix-controlled cache (Anthropic / Bedrock `cache_control`)
+ * re-creates the prefix on a cold turn (`cacheWrite > 0`); implicit caches
+ * (Google / OpenAI / Fireworks) report `cacheWrite: 0` and drop `cacheRead` to
+ * zero intermittently as routine propagation noise that self-heals the next
+ * turn, so flagging it would be a false positive.
  */
 export function detectCacheInvalidation(prev: Usage | undefined, current: Usage): CacheInvalidation | undefined {
 	if (!prev) return undefined;
-	const prevFootprint = prev.cacheRead + prev.cacheWrite;
-	if (prevFootprint < MIN_CACHE_FOOTPRINT) return undefined;
+	// Only flag a warm→cold transition: the previous turn must have actually read
+	// a meaningful prefix from cache. A write-only predecessor (first request, or
+	// a re-write after expiry) has not proven the cache is live, so a cold turn
+	// behind it is expected — not an invalidation worth surfacing.
+	if (prev.cacheRead < MIN_CACHE_FOOTPRINT) return undefined;
 	// Any cache reuse this turn means the prefix survived (at least partly).
 	if (current.cacheRead > 0) return undefined;
 	// Only an explicit, prefix-controlled cache re-creates the prefix on a cold

package/src/modes/components/custom-editor.test.ts

@@ -39,11 +39,12 @@ function feedGaps(editor: CustomEditor, gaps: number[]): void {
 	}
 }
 
-async function decorateInFreshProcess(text: string): Promise<string> {
+async function decorateInFreshProcess(text: string, imageLinks?: readonly string[]): Promise<string> {
 	const customEditorUrl = new URL("./custom-editor.ts", import.meta.url).href;
 	const script = `
 import { CustomEditor } from ${JSON.stringify(customEditorUrl)};
 const editor = new CustomEditor({});
+editor.imageLinks = ${JSON.stringify(imageLinks)};
 process.stdout.write(editor.decorateText(${JSON.stringify(text)}));
 `;
 	const child = await $`bun -e ${script}`.quiet().nothrow();
@@ -59,8 +60,8 @@ describe("CustomEditor placeholder decoration", () => {
 		expect(output).toBe("[Paste #1, +30 lines]");
 	});
 
-	it("renders image placeholders before theme initialization", async () => {
-		const output = await decorateInFreshProcess("[Image #1]");
+	it("renders linked image placeholders before theme and settings initialization", async () => {
+		const output = await decorateInFreshProcess("[Image #1]", ["/tmp/example.png"]);
 		expect(output).toBe("[Image #1]");
 	});
 });

package/src/modes/components/status-line/component.ts

@@ -154,6 +154,8 @@ interface ContextUsageMemo {
 }
 
 const EMPTY_MESSAGES: readonly AgentMessage[] = [];
+const STATUS_USAGE_START_DELAY_MS = 0;
+const STATUS_USAGE_REFRESH_TIMEOUT_MS = 2_000;
 
 function hasContextSegment(segments: readonly StatusLineSegmentId[]): boolean {
 	return segments.includes("context_pct") || segments.includes("context_total");
@@ -212,6 +214,7 @@ export class StatusLineComponent implements Component {
 	} | null = null;
 	#usageFetchedAt = 0;
 	#usageInFlight = false;
+	#usageStartTimer: Timer | null = null;
 	// Context-usage memo. The status line redraws on every agent event, so the
 	// hot path must not recompute context tokens unless an input changed.
 	// `getContextUsage()` anchors on the last assistant's real prompt-token
@@ -344,16 +347,24 @@ export class StatusLineComponent implements Component {
 	dispose(): void {
 		this.#disposed = true;
 		this.#onBranchChange = null;
+		this.#clearUsageStartTimer();
 		if (this.#gitWatcher) {
 			this.#gitWatcher.close();
 			this.#gitWatcher = null;
 		}
 	}
 
+	#clearUsageStartTimer(): void {
+		if (!this.#usageStartTimer) return;
+		clearTimeout(this.#usageStartTimer);
+		this.#usageStartTimer = null;
+	}
+
 	invalidate(): void {
 		this.#invalidateGitCaches();
 	}
 	#invalidateSessionCaches(): void {
+		this.#clearUsageStartTimer();
 		this.#cachedUsage = null;
 		this.#usageFetchedAt = 0;
 		this.#usageInFlight = false;
@@ -521,38 +532,73 @@ export class StatusLineComponent implements Component {
 	}
 
 	/**
-	 * Background-refresh the Anthropic OAuth quota report. Guarded by a 5-min
-	 * TTL on both success (cache lifetime) and error (backoff). Exposed
-	 * (non-private) so unit tests can verify the backoff invariant.
+	 * Startup redraws only arm a short-delayed task; timeout releases the render
+	 * cadence while a late successful fetch can still refresh the cached segment.
 	 */
 	refreshUsageInBackground(): void {
 		const now = Date.now();
-		if (this.#usageInFlight) return;
+		if (this.#usageInFlight || this.#usageStartTimer) return;
 		if (this.#usageFetchedAt > 0 && now - this.#usageFetchedAt < 5 * 60_000) return;
 		const session = this.session;
-		const fetcher = (session as { fetchUsageReports?: () => Promise<unknown> }).fetchUsageReports;
+		const fetcher = (session as { fetchUsageReports?: (signal?: AbortSignal) => Promise<unknown> }).fetchUsageReports;
 		if (typeof fetcher !== "function") return;
 		this.#usageInFlight = true;
-		void fetcher
-			.call(session)
+		this.#usageStartTimer = setTimeout(() => {
+			this.#usageStartTimer = null;
+			void this.#runUsageRefresh(session, fetcher);
+		}, STATUS_USAGE_START_DELAY_MS);
+	}
+
+	async #runUsageRefresh(session: AgentSession, fetcher: (signal?: AbortSignal) => Promise<unknown>): Promise<void> {
+		if (this.#disposed || this.session !== session) {
+			this.#usageInFlight = false;
+			return;
+		}
+		const signal = AbortSignal.timeout(STATUS_USAGE_REFRESH_TIMEOUT_MS);
+		let reportsPromise: Promise<unknown> | undefined;
+		try {
+			reportsPromise = fetcher.call(session, signal);
+			this.#applyUsageRefreshReports(session, await this.#raceUsageRefreshWithSignal(reportsPromise, signal));
+		} catch {
+			if (this.session !== session) return;
+			this.#usageFetchedAt = Date.now();
+			if (signal.aborted && reportsPromise) {
+				this.#observeLateUsageRefresh(session, reportsPromise);
+			}
+		} finally {
+			if (this.session === session) this.#usageInFlight = false;
+		}
+	}
+
+	#applyUsageRefreshReports(session: AgentSession, reports: unknown): void {
+		if (this.#disposed || this.session !== session) return;
+		this.#cachedUsage = this.#normalizeUsageReports(reports);
+		this.#usageFetchedAt = Date.now();
+	}
+
+	#observeLateUsageRefresh(session: AgentSession, reportsPromise: Promise<unknown>): void {
+		void reportsPromise
 			.then(reports => {
-				if (this.session !== session) return;
-				this.#cachedUsage = this.#normalizeUsageReports(reports);
-				this.#usageFetchedAt = Date.now();
+				this.#applyUsageRefreshReports(session, reports);
 			})
 			.catch(() => {
-				if (this.session !== session) return;
-				// Backoff on error: stamp the fetch time so the 5-min TTL guard
-				// also acts as an error budget. Without this, every render
-				// kicks off another fetch (gated only by #usageInFlight),
-				// which hammers the endpoint during a network outage / 5xx.
+				if (this.#disposed || this.session !== session) return;
 				this.#usageFetchedAt = Date.now();
-			})
-			.finally(() => {
-				if (this.session === session) this.#usageInFlight = false;
 			});
 	}
 
+	async #raceUsageRefreshWithSignal(promise: Promise<unknown>, signal: AbortSignal): Promise<unknown> {
+		if (signal.aborted) throw signal.reason;
+		const aborted = Promise.withResolvers<never>();
+		const onAbort = () => aborted.reject(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+		try {
+			return await Promise.race([promise, aborted.promise]);
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	}
+
 	#normalizeUsageReports(reports: unknown): {
 		fiveHour?: { percent: number; resetMinutes?: number };
 		sevenDay?: { percent: number; resetHours?: number };