@llblab/pi-kit 0.38.1 → 0.38.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.38.3: Bundled Package Updates (2026-11-01)
+
+- `Exact pins`: `@llblab/pi-state-flow` 0.27.1 → 0.27.4.
+- `Packaging`: Synchronizes the lockfile, bundle aliases and README inventory. Package membership and resource order remain unchanged; packed validation does not certify extension safety or installed-client behavior.
+
+## 0.38.2: Bundled Package Updates (2026-10-30)
+
+- `Exact pins`: `@llblab/pi-claude-usage` 0.2.4 → 0.2.5.
+- `Packaging`: Synchronizes the lockfile, bundle aliases and README inventory. Package membership and resource order remain unchanged; packed validation does not certify extension safety or installed-client behavior.
+
 ## 0.38.1: Bundled Package Updates (2026-10-29)
 
 - `Exact pins`: `@llblab/pi-claude-usage` 0.2.3 → 0.2.4; `@llblab/pi-clean-room` 0.3.0 → 0.3.1.

package/README.md

@@ -13,11 +13,11 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | Package | Version | Purpose |
 | --- | ---: | --- |
 | [`@llblab/pi-actors`](https://github.com/llblab/pi-actors) | `0.55.0` | Inspectable local Runs, reusable Recipes, persistent tools, and delegation Skills |
-| [`@llblab/pi-claude-usage`](https://github.com/llblab/pi-claude-usage) | `0.2.4` | Claude subscription quota status and shared per-model Fast toggle for Opus, mirrored in Telegram |
+| [`@llblab/pi-claude-usage`](https://github.com/llblab/pi-claude-usage) | `0.2.5` | Claude subscription quota status and shared per-model Fast toggle for Opus, mirrored in Telegram |
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.3.1` | Isolated nested Pi TUI with named npm extensions and compatible model selection |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.13.2` | OpenAI/legacy Codex subscription quota and Business credit status, with persistent priority Fast toggle mirrored in Telegram |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.9.0` | Visible continuation scheduling and bounded worker Skills through compiled, manifest-owned resources |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.27.1` | Scoped context/memory compiler with step-independent current memory, stable Passive/Active modes and visible blocked-state status |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.27.4` | Scoped context/memory compiler with step-independent current memory, stable Passive/Active modes and visible blocked-state status |
 | [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.58.3` | Telegram companion with per-prompt Steer, queued controls, Reroute/Restore, recoverable connections, previews, follower Threads, files, and voice |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
@@ -25,7 +25,7 @@ Versions are exact by design. An upstream release does not change an installed k
 
 ## Install
 
-Requires **Pi 1.0.0+** and **Node.js 22.19.0+**. State Flow requires its canonical checkpoint/tail storage format and does not convert unsupported stores in place. Preserve existing stores and consult the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.27.1/docs/usage.md#moving-a-store-and-supported-formats) before changing installations.
+Requires **Pi 1.0.0+** and **Node.js 22.19.0+**. State Flow requires its canonical checkpoint/tail storage format and does not convert unsupported stores in place. Preserve existing stores and consult the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.27.4/docs/usage.md#moving-a-store-and-supported-formats) before changing installations.
 
 From NPM:
 

package/node_modules/@llblab/pi-claude-usage/AGENTS.md

@@ -5,7 +5,7 @@
 - `Statusline-first scope`: Own usage state + usage mode; keep quota reporting zero-configuration and optional Fast on the existing terminal status.
   - Trigger: Considering commands, menus, persisted settings, or notification output.
   - Action: Prefer deleting the surface unless it is required for the optimistic TUI status widget, optional `pi-telegram` `/start` status-line mirror, or the argument-free shared `/fast`. Register only the `anthropic` provider handler through `@llblab/pi-command-fast` on session_start; release on session_shutdown. Never register the command directly or gate it on quota auth. Claude Fast eligibility is consumer-owned: permit the `claude-opus-` family without a version allowlist; warn `Fast mode is supported only for Opus` for other families without writes. Family eligibility is not proof of backend support; preserve server capability/billing errors. For rejected models, ignore stale unsupported overrides in status/request adaptation, and leave Codex eligibility unchanged. The library owns session WeakMap/reload arbitration and generic JSONC; `lib/fast.ts` owns Claude semantics; require Pi ≥1.0.0 for its assembled-beta payload contract, rather than copying upstream beta defaults. ON is `speed: "fast"` in the current model override; OFF deletes the property. Preserve existing request speed/betas, append the required Fast beta to the native assembled list rather than replacing a header, and keep Fast out of quota state. The optional Telegram row reads the active model's eligible Fast preference at render time and appends plain-text ` fast` (or shows `fast` alone without quota). Toggle redraws through the final terminal boundary without a quota request or success notification; unreadable config fails closed for Fast only.
-- `Domain boundaries`: `index.ts` is export-only; `lib/extension.ts` composes lifecycle/Fast registration and request hooks. `lib/status.ts` owns refresh orchestration and terminal timers; `usage-store.ts` owns claims/fencing/mutex, `query.ts` owns OAuth/HTTP, `usage.ts` owns quota normalization, `status-format.ts` owns presentation, and `telegram.ts` owns optional registration. Preserve mature quota/auth/leadership behavior, keep imports acyclic with no domain importing the entrypoint, and keep domain-focused tests in `tests/`. Do not merge usage extensions or redesign polling to add Fast.
+- `Domain boundaries`: `index.ts` is export-only; `lib/extension.ts` composes lifecycle/Fast registration and request hooks. `lib/status.ts` owns refresh orchestration and terminal timers; `usage-store.ts` owns claims/fencing/mutex, `query.ts` owns OAuth/HTTP, `usage.ts` owns quota normalization, `model-limit.ts` owns narrow passive subscription-error recognition and near-empty window inference, `status-format.ts` owns presentation, and `telegram.ts` owns optional registration. Preserve mature quota/auth/leadership behavior, keep imports acyclic with no domain importing the entrypoint, and keep domain-focused tests in `tests/`. Do not merge usage extensions or redesign polling to add Fast.
 - `Optimistic refresh`: Preserve the last good statusline bar during refresh and transient failures.
   - Trigger: Updating quota polling or error handling.
   - Action: Do not collapse the bar while a request is in flight; only show `n/a` or `error` after repeated failures or no usable quota.
@@ -20,4 +20,5 @@
   - Action: Do not add fallbacks, CLI probes, or API-key paths; API keys have no subscription quota, so report `n/a`. `utilization` is a used percent.
 - `Rate-limit discipline`: Quota polling must be shared across instances; HTTP 429 triggers shared backoff.
   - Trigger: Changing refresh cadence, retries, locking, or adding fetch paths.
-  - Action: Keep the single shared-state protocol in `lib/usage-store.ts`, orchestrated by `lib/status.ts` (leader refreshes every 3 minutes, takeover after 210 seconds by claiming leadership before fetching, a non-waiting OS-backed SQLite mutex around claiming and fenced publication, atomic writes, shared failure backoff). Always re-read the file for request authorization (`owner` + `claimId` + lease) and publication; do not use an in-memory ownership fallback. Lock failures and failed claim writes must deny requests. `mutex.sqlite` stores no quota or leadership data: never unlink/replace it while instances run or evict a paused holder; close or process death releases the mutex. Keep network calls outside critical sections. Instances otherwise only read the file; never add per-instance polling or probing requests.
+  - Action: Keep the single shared-state protocol in `lib/usage-store.ts`, orchestrated by `lib/status.ts` (leader refreshes every 2 minutes, takeover after 150 seconds by claiming leadership before fetching, a non-waiting OS-backed SQLite mutex around claiming and fenced publication, atomic writes, shared failure backoff). Always re-read the file for request authorization (`owner` + `claimId` + lease) and publication; do not use an in-memory ownership fallback. Lock failures and failed claim writes must deny requests. `mutex.sqlite` stores no quota or leadership data: never unlink/replace it while instances run or evict a paused holder; close or process death releases the mutex. Keep network calls outside critical sections. Followers otherwise only read the file, except for mutex-protected passive model-limit markers that never renew ownership or change request deadlines; never add per-instance polling or probing requests.
+- `Passive model-limit inference`: Observe live failed assistant messages, not chat text or historical log scans. Only native `anthropic` / `anthropic-messages` Claude models at `https://api.anthropic.com` with Pi OAuth qualify. Require the structured HTTP 429 account-limit error (`type: error`, `error.type: rate_limit_error`, and the exact `This request would exceed your account's rate limit. Please try again later.` message, whitespace normalized); ignore other throttling and billing errors. Infer zero for at most one cached window strictly below 5% remaining. If either measured window is already exhausted, infer nothing else. If both are near-empty, compare primary remaining percent with six times weekly remaining percent, preferring primary on ties; 1:6 is an empirical budget estimate, not an Anthropic guarantee. Preserve measured reports/timestamps and shared request authority; persist only a separate marker under the mutex. Redraw immediately without a quota request or blink, let followers consume the marker on normal ticks, and clear it only on a successful refresh started after the observation. Do not alter Pi's model retries.

package/node_modules/@llblab/pi-claude-usage/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.5: Reactive Quota Indicators
+
+- Added an immediate quota-display response to the specific native Anthropic subscription account-limit error. At most one window with strictly less than 5% remaining is inferred exhausted; when both are near-empty, an empirical weekly-to-five-hour budget ratio of 6:1 selects the smaller equivalent balance, preferring five-hour on ties. An already exhausted measured window leaves the other untouched. The shared signal makes no extra quota requests and preserves measured data, leadership and retry deadlines; a successful refresh started after the signal restores authoritative values. Other providers, proxies, API-key models, generic throttling and Fast credit errors do not trigger it.
+- Changed shared quota polling from every three minutes to every two minutes, with follower takeover after two minutes and thirty seconds. Shared usage-endpoint failure backoff is preserved.
+
 ## 0.2.4: Quota Polling Hotfix
 
 - Reduced shared quota polling from once a minute to once every three minutes to lower request pressure on Anthropic's usage endpoint. Follower takeover now waits three minutes and thirty seconds so multiple instances preserve the slower cadence. Shared HTTP 429 backoff and local reset countdown updates remain in place.

package/node_modules/@llblab/pi-claude-usage/README.md

@@ -18,6 +18,7 @@ This repository is an adaptation of [`pi-codex-usage`](https://github.com/llblab
 
 - Shows two counter-moving half-height markers in the statusline bar while quota is loading, then keeps the bar fresh (the countdown ticks locally)
 - Keeps the last usable bar visible during ordinary refreshes instead of replacing known quota with a loading state
+- Immediately rounds one likely exhausted near-empty window to zero on the specific native Anthropic subscription account-limit error, without making an extra quota request
 - Dual bar: the top half shows the 5-hour session window and the bottom half shows the 7-day window, 20 steps (5% each) per window
 - If only one window is returned, shows its remaining percentage and reset countdown instead of a bar
 - Shown only while the active model uses the Pi `anthropic` provider
@@ -118,23 +119,31 @@ Runtime failure, such as a network or provider error (including rate limiting of
 claude error
 ```
 
+## Passive Model-Limit Signal
+
+For the native `anthropic` provider, Claude model IDs using `anthropic-messages` at `https://api.anthropic.com` with Pi OAuth auth, the extension also observes failed assistant messages. It recognizes HTTP 429 with a JSON error envelope whose `type` is `error`, `error.type` is `rate_limit_error`, and `error.message` is exactly `This request would exceed your account's rate limit. Please try again later.` (ignoring whitespace differences). API-key models, proxies, other providers, generic throttling, Fast credit errors and errors from the usage endpoint do not trigger it.
+
+On this signal, at most one cached window with **strictly less than 5% remaining** is immediately displayed as zero. If only one window is near-empty, it is selected; a sole near-empty weekly window also qualifies. If both windows are near-empty, compare the five-hour remaining percentage with **six times the weekly remaining percentage** and select the smaller balance, preferring the five-hour window on ties. This uses an empirical estimate that one weekly budget is approximately six full five-hour budgets, not an official Anthropic quota guarantee. For example, 2% five-hour versus 1% weekly selects five-hour (2 versus 6), while 4% five-hour versus 0.5% weekly selects weekly (4 versus 3). Exactly 5% and larger balances are unchanged. If either measured window is already exhausted, the other window is not additionally zeroed. Existing exhausted-window colors and reset countdowns are reused.
+
+This is a display inference, not an authoritative quota measurement: the error itself does not identify the exhausted window. The measured `report` and `updatedAt` remain unchanged. A separate `modelRateLimitedAt` marker is shared under the existing mutex without changing ownership, the lease, or retry deadlines. The receiving instance redraws immediately; other instances pick it up on their normal file-read ticks (within 30 seconds). A successful quota refresh started after the signal clears it; an already-in-flight response or another failure cannot erase it. No extra quota request is made, and Pi's model retry behavior is unchanged.
+
 ## Shared Refresh
 
-The extension ships an export-only [`index.ts`](./index.ts) and a flat domain DAG under `lib/`, matching Codex Usage's layout. [`extension.ts`](./lib/extension.ts) composes lifecycle/Fast wiring; [`status.ts`](./lib/status.ts) orchestrates refresh and redraw; [`usage-store.ts`](./lib/usage-store.ts) owns shared claims/fencing/mutex; [`query.ts`](./lib/query.ts) owns OAuth/HTTP; [`usage.ts`](./lib/usage.ts) normalizes quotas; [`status-format.ts`](./lib/status-format.ts) formats values; [`telegram.ts`](./lib/telegram.ts) owns optional registration; [`fast.ts`](./lib/fast.ts) adapts native Fast requests. Domains never import the entrypoint, and tests are organized by domain in `tests/`.
+The extension ships an export-only [`index.ts`](./index.ts) and a flat domain DAG under `lib/`, matching Codex Usage's layout. [`extension.ts`](./lib/extension.ts) composes lifecycle/Fast wiring; [`status.ts`](./lib/status.ts) orchestrates refresh and redraw; [`usage-store.ts`](./lib/usage-store.ts) owns shared claims/fencing/mutex; [`query.ts`](./lib/query.ts) owns OAuth/HTTP; [`usage.ts`](./lib/usage.ts) normalizes quotas; [`model-limit.ts`](./lib/model-limit.ts) recognizes the narrow passive model-error signal and derives near-empty window overrides; [`status-format.ts`](./lib/status-format.ts) formats values; [`telegram.ts`](./lib/telegram.ts) owns optional registration; [`fast.ts`](./lib/fast.ts) adapts native Fast requests. Domains never import the entrypoint, and tests are organized by domain in `tests/`.
 
 To avoid independent polling, instances coordinate through `~/.pi/agent/tmp/pi-claude-usage/usage.json` (percentages and timestamps only, no tokens):
 
-- The instance that last updated the file is the leader and refreshes it every 3 minutes
+- The instance that last updated the file is the leader and refreshes it every 2 minutes
 - Every other instance only reads the file (re-checking every ≤30s) and redraws when it changes
-- Leadership is never cached in memory: before each usage request, the instance re-reads the file and checks its `owner`, unique `claimId`, and 210s lease. Publication rechecks that claim under the lock; a superseded success or failure is discarded. Failed locks or unwritten claims never authorize a request
-- If the file is 210 seconds old (leader is closed, busy, or asleep), the first follower that obtains the mutex takes over: it re-reads the JSON, writes itself as the leader with a fresh timestamp, releases the mutex, then fetches from the server and publishes under the mutex after rechecking its claim. Its next refresh is three minutes later; JSON writes remain atomic renames
+- Leadership is never cached in memory: before each usage request, the instance re-reads the file and checks its `owner`, unique `claimId`, and 150s lease. Publication rechecks that claim under the lock; a superseded success or failure is discarded. Failed locks or unwritten claims never authorize a request
+- If the file is 150 seconds old (leader is closed, busy, or asleep), the first follower that obtains the mutex takes over: it re-reads the JSON, writes itself as the leader with a fresh timestamp, releases the mutex, then fetches from the server and publishes under the mutex after rechecking its claim. Its next refresh is two minutes later; JSON writes remain atomic renames
 - Claiming and publication use a non-waiting transaction in `mutex.sqlite`, through Node's built-in `node:sqlite` (Node ≥22.19.0, the existing package minimum). It stores no quota or leadership records and needs no extra package or service. The OS releases the lock when the connection closes or the process dies; there is no timeout-based lock stealing
 - Failures are written to the file with an exponential backoff (1 to 5 minutes; 5 to 30 minutes for HTTP 429) that applies to all instances
 - The last report stays visible for up to an hour; after that `error` is shown
 
 Coordination assumes a local filesystem and cooperating instances on the same machine. Never delete or replace `mutex.sqlite` while instances are running. Network requests do not hold the mutex; a process paused inside a short critical section keeps it until it resumes or exits, so other writers retry later without blocking the TUI. This preserves exclusion instead of stealing a live lock.
 
-**Upgrade:** Close all old instances before starting updated ones. The legacy `lock` files are ignored; old and new locking protocols must not run together. Cached `usage.json` data needs no migration.
+**Upgrade:** Close all old instances before starting updated ones. The legacy `lock` files are ignored; old and new locking protocols must not run together. Cached `usage.json` data needs no migration. Restart all instances after updating so none retain an older polling interval or ignore the passive model-limit signal.
 
 ## Telegram Status Menu
 

package/node_modules/@llblab/pi-claude-usage/lib/model-limit.ts

@@ -0,0 +1,54 @@
+/** Domain: model limit signal. Owns: narrow subscription-error recognition and near-empty window inference. Excludes: quota measurement, persistence, requests and rendering. */
+import type { ExtensionContext, MessageEndEvent } from "@earendil-works/pi-coding-agent";
+import type { ClaudeUsageReport } from "./usage.ts";
+
+/** Empirical subscription budget estimate, not an Anthropic quota guarantee. */
+const WEEKLY_TO_FIVE_HOUR_BUDGET_RATIO = 6;
+
+/** Infer at most one near-empty window, comparing balances in five-hour budget units. */
+export function applyModelRateLimit(report: ClaudeUsageReport): ClaudeUsageReport {
+  const primaryRemaining = report.primary ? 100 - report.primary.usedPercent : Infinity;
+  const secondaryRemaining = report.secondary ? 100 - report.secondary.usedPercent : Infinity;
+  if (primaryRemaining <= 0 || secondaryRemaining <= 0) return report;
+  const primaryNearEmpty = primaryRemaining < 5;
+  const secondaryNearEmpty = secondaryRemaining < 5;
+  if (!primaryNearEmpty && !secondaryNearEmpty) return report;
+  const selected = primaryNearEmpty && (!secondaryNearEmpty ||
+    primaryRemaining <= WEEKLY_TO_FIVE_HOUR_BUDGET_RATIO * secondaryRemaining)
+    ? "primary" : "secondary";
+  return { ...report, [selected]: { ...report[selected], usedPercent: 100 } };
+}
+
+const ACCOUNT_RATE_LIMIT_MESSAGE = "This request would exceed your account's rate limit. Please try again later.";
+
+/** This display signal does not prove which quota window is exhausted. */
+export function isSubscriptionRateLimit(
+  message: MessageEndEvent["message"],
+  model: ExtensionContext["model"],
+  usingOAuth: boolean,
+): boolean {
+  if (
+    !usingOAuth ||
+    !model ||
+    model.provider !== "anthropic" ||
+    model.api !== "anthropic-messages" ||
+    model.baseUrl.replace(/\/+$/, "") !== "https://api.anthropic.com" ||
+    !model.id.startsWith("claude-") ||
+    message.role !== "assistant" ||
+    message.provider !== model.provider ||
+    message.api !== model.api ||
+    message.model !== model.id ||
+    message.stopReason !== "error"
+  ) return false;
+  const match = message.errorMessage?.match(/^(?:Error:\s*)?429\s+(\{[\s\S]*\})\s*$/);
+  if (!match) return false;
+  try {
+    const body = JSON.parse(match[1]);
+    return body?.type === "error" &&
+      body.error?.type === "rate_limit_error" &&
+      typeof body.error.message === "string" &&
+      body.error.message.replace(/\s+/g, " ").trim() === ACCOUNT_RATE_LIMIT_MESSAGE;
+  } catch {
+    return false;
+  }
+}

package/node_modules/@llblab/pi-claude-usage/lib/status.ts

@@ -2,10 +2,11 @@
 import { join } from "node:path";
 import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { isFastEnabled } from "./fast.ts";
-import { claimRefresh, isRefreshDue, nextRefreshAt, ownsRefreshClaim, publishRefresh, readState, MIN_ATTEMPT_GAP_MS, type SharedState } from "./usage-store.ts";
+import { claimRefresh, isRefreshDue, nextRefreshAt, ownsRefreshClaim, publishRefresh, readState, recordModelRateLimit, MIN_ATTEMPT_GAP_MS, type SharedState } from "./usage-store.ts";
 import { isAnthropicModel, type ClaudeUsageModel, type ClaudeUsageReport } from "./usage.ts";
 import { DUAL_BAR_WIDTH, formatClaudeUsageBar, formatClaudeUsageStatusline, formatStatuslineLoading, formatStatuslineProblem, nextResetCountdownDelayMs } from "./status-format.ts";
 import { queryUsage } from "./query.ts";
+import { applyModelRateLimit, isSubscriptionRateLimit } from "./model-limit.ts";
 import { claudeUsageTelegramStatusLine, registerClaudeUsageTelegramStatusLine } from "./telegram.ts";
 
 const DEFAULT_TIMEOUT_MS = 15_000;
@@ -187,12 +188,12 @@ export function createClaudeUsageStatus(pi: ExtensionAPI) {
       state?.report &&
       state.updatedAt !== undefined &&
       Date.now() - state.updatedAt < STALE_REPORT_MAX_AGE_MS
-        ? state.report
+        ? state.modelRateLimitedAt !== undefined ? applyModelRateLimit(state.report) : state.report
         : undefined;
     if (usable) {
-      const key = `report:${state?.updatedAt}`;
+      const key = `report:${state?.updatedAt}:${state?.modelRateLimitedAt ?? ""}`;
       if (!force && shown.key === key) return;
-      const blink = shown.report
+      const blink = state?.modelRateLimitedAt === undefined && shown.report
         ? formatClaudeUsageBar(shown.report) !== formatClaudeUsageBar(usable)
         : false;
       shown = { key, report: usable, updatedAt: state?.updatedAt };
@@ -210,7 +211,7 @@ export function createClaudeUsageStatus(pi: ExtensionAPI) {
   };
 
   /**
-   * When this instance is due (leader after 3 minutes, anyone after 210 seconds) it
+   * When this instance is due (leader after 2 minutes, anyone after 150 seconds) it
    * claims leadership under the lock (owner and timestamp, so no other
    * instance is due), then fetches, then stamps the outcome. Failures are
    * published with a backoff so other instances do not pile on.
@@ -333,6 +334,17 @@ export function createClaudeUsageStatus(pi: ExtensionAPI) {
     }
   });
 
+  pi.on("message_end", (event, ctx) => {
+    const message = event.message;
+    if (message.role !== "assistant" || message.provider !== "anthropic" || message.stopReason !== "error") return;
+    const model = ctx.modelRegistry.find(message.provider, message.model);
+    if (!model || !isSubscriptionRateLimit(message, model, ctx.modelRegistry.isUsingOAuth(model))) return;
+    if (recordModelRateLimit(stateDir) && isAnthropicModel(ctx.model)) {
+      syncFast(ctx.model);
+      renderState(ctx, loadState(), true);
+    }
+  });
+
   pi.on("session_shutdown", (_event, ctx) => {
     clearUsageStatusline(ctx);
     unregisterTelegramStatusLine?.();

package/node_modules/@llblab/pi-claude-usage/lib/usage-store.ts

@@ -4,6 +4,7 @@ import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import type { ClaudeUsageReport } from "./usage.ts";
+import { applyModelRateLimit } from "./model-limit.ts";
 
 // --- Shared Refresh ---
 
@@ -17,7 +18,7 @@ import type { ClaudeUsageReport } from "./usage.ts";
  * atomic renames; short critical sections use an OS-backed SQLite mutex.
  */
 
-export const LEADER_INTERVAL_MS = 3 * 60_000;
+export const LEADER_INTERVAL_MS = 2 * 60_000;
 /** The leader is considered gone after missing its slot by 30 seconds. */
 export const TAKEOVER_AFTER_MS = LEADER_INTERVAL_MS + 30_000;
 /** Minimum pause between two fetch attempts of the same instance. */
@@ -44,6 +45,8 @@ export type SharedState = {
   failures?: number;
   /** No instance should fetch before this time. */
   retryNotBefore?: number;
+  /** Passive model-error signal; never replaces the measured report or its timestamp. */
+  modelRateLimitedAt?: number;
 };
 
 export function readState(dir: string): SharedState | undefined {
@@ -126,6 +129,19 @@ export function ownsRefreshClaim(
   return matchesClaim(current, claim, now ?? Date.now());
 }
 
+/** A passive observation changes neither refresh ownership nor the shared retry deadline. */
+export function recordModelRateLimit(dir: string, now?: number): boolean {
+  const release = tryAcquireLock(dir);
+  if (!release) return false;
+  try {
+    const current = readState(dir);
+    if (!current?.report || applyModelRateLimit(current.report) === current.report) return false;
+    return writeState(dir, { ...current, modelRateLimitedAt: now ?? Date.now() });
+  } finally {
+    release();
+  }
+}
+
 /** A late success OR failure must not overwrite a successor's state. */
 export function publishRefresh(
   dir: string,
@@ -145,6 +161,10 @@ export function publishRefresh(
         claimedAt: at,
         updatedAt: at,
         report: outcome.report,
+        // A request already in flight when the model failed cannot clear its signal.
+        ...(current?.modelRateLimitedAt !== undefined &&
+          current.modelRateLimitedAt >= (current.claimedAt ?? Infinity)
+          ? { modelRateLimitedAt: current.modelRateLimitedAt } : {}),
       });
     }
     const failures = (current?.failures ?? 0) + 1;

package/node_modules/@llblab/pi-claude-usage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-claude-usage",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "private": false,
   "description": "Minimal Pi extension that shows Anthropic Claude subscription usage limits using Pi OAuth auth",
   "keywords": [

package/node_modules/@llblab/pi-state-flow/AGENTS.md

@@ -13,7 +13,7 @@ The [relocation ledger](docs/agent-contract-relocation.md) maps every pre-compac
 - Artifacts name exact registered source paths; observe only regular non-symlink files, never discover directories or read unrelated bodies. Preserve hidden per-scope provenance, exact-owner compilation, stable fingerprint checks and separate Skill hashes; unavailable sources are not proof of deletion. See [artifact routing](docs/architecture.md#artifact-routing).
 - Preserve session config/runtime, per-scope metadata, lineage and provenance outside model-patchable state; decode legacy mode evidence read-only, never mix representations or normalize storage eagerly. See [storage and identity](docs/architecture.md#storage-and-identity) and [mode compatibility](docs/compatibility.md#mode-configuration-compatibility).
 - Keep one opaque composed causal lineage, anchored checkpoint/tail materialization, configured hot-history folding and independent owner revisions; never invent earlier history or rebuild discarded offsets. Historical reads are observational, and `effective[n]`/owner materializations select the same causal boundary. See [temporal model](docs/architecture.md#temporal-model) and [model tools](docs/architecture.md#model-tools).
-- Keep the [internal semantic-module contract](docs/semantic-module-contract.md) package-owned and separate from storage/native authority. Module candidates are not accepted publications; immutable means main-agent read-only, not producer-frozen. Preserve the single intent-first engine and current dialect; no runtime discovery/public ABI or automatic inference follows from a module identity.
+- Keep the [internal semantic-module contract](docs/semantic-module-contract.md) package-owned and separate from storage/native authority. Module candidates are not accepted publications; immutable means main-agent read-only, not producer-frozen. Preserve the single intent-first engine and current dialect; no runtime discovery, public registration authority or automatic inference follows from an internal module identity.
 - Keep the [public module registration boundary](docs/public-module-contract.md) native-host-scoped and revocable. A registration/catalog grants no source, private or publication authority. Follow its explicit compatibility decision before admitting external stored roots; unavailable-module data must never be dropped through filtering or normalization. Pi remains the loader.
 
 ## Publication and lifecycle