@llblab/pi-kit 0.24.1 → 0.26.0

package/AGENTS.md

@@ -20,7 +20,7 @@
 
 - Start work from `BACKLOG.md` and inspect the included package manifests before changing pins or resource paths.
 - Keep `dependencies`, `bundledDependencies`, Pi resource paths, README inventory, tests, and lockfile synchronized.
-- Bundle every included Pi package so npm installation is self-contained under this package's module root.
+- Bundle every included Pi package so npm installation is self-contained under this package's module root. Keep repository-local `legacy-peer-deps=true` so host-provided Pi peers are not resolved into the kit's lockfile; Pi supplies them at runtime.
 - Expose only resources declared by each included package. Prefer published distribution entrypoints over source entrypoints when both exist.
 - Do not copy extension source, Skills, or documentation into this repository.
 - Preserve package independence: a kit release may advance any subset of included extensions without forcing lockstep extension releases.

package/BACKLOG.md

@@ -1,3 +1,7 @@
 # Backlog
 
-No open items.
+The 0.26.0 composition is recorded in [CHANGELOG.md](./CHANGELOG.md). Package pins, resource order and bundled runtime ownership remain authoritative in `package.json`.
+
+## Carried checks
+
+- **Installed 0.26.0 smoke (operator-owned):** After separately authorized installation/reload, check the exact released kit's terminal controls and optional Telegram rendering with disposable State Flow storage. Packed SDK validation does not certify the operator's running clients. Do not reconnect Telegram, change Pi settings or use live memory/usage/Recipe stores as fixtures without separate authorization.

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.26.0: Pi 1.0 Cohort and Memory-Inert State Flow
+
+- `Usage and Fast`: Advances Codex Usage to `0.12.0` and Claude Usage to `0.2.0`, sharing one persistent `/fast` command. Codex uses provider-level priority preference; Claude permits the Opus family. Both preserve quota coordination and redraw the terminal status without a quota request; backend capability and billing still apply.
+- `Pi 1.0 Cohort`: Advances Actors to `0.54.0`, Clean Room to `0.3.0` and Grow Loop to `0.9.0`, requiring Pi 1.0.0 or newer and including their MIT licenses. Exact pins, bundled packages, explicit resource order and runtime ownership remain intact; Telegram and portable Skills retain their existing pins.
+- `Memory-Inert State Flow`: Advances the exact State Flow pin to published `0.24.0`, fixing Pi 1.0 token-estimation compatibility. Off performs no automatic memory work and cancels owned pending operations without erasing accepted data. Read-only inspections validate current private authority; superseded Active preserves Passive's selected history. MIT LICENSE is included in the member package.
+
+## 0.25.0 - 2026-10-02
+
+- `State Flow Modes`: Advances the exact State Flow pin from `0.21.0` to `0.23.0`. Adds sparse-state handling and session-owned modes; new sessions now default to Off while retained choices and explicit global policy survive. Telegram adds mode radios and scope explanations, with opt-in barrier diagnostics. No State Flow memory is erased by switching modes.
+- `Claude Subscription Usage`: Adds the independently released `@llblab/pi-claude-usage@0.1.1` as an eighth bundled member and seventh extension entrypoint. It shows Claude Pro/Max quota windows using Pi Anthropic OAuth, with shared cross-instance refresh and optional Telegram status. Existing Codex Usage stays at `0.10.0`.
+- `Host Peer Isolation`: Repository-local npm peer settings keep Pi-provided packages out of the kit lockfile and validation audit; Pi continues to supply them at runtime. The six unchanged member pins, existing resource order, Skill ownership and Pi minimum remain unchanged; the new Claude entrypoint is inserted explicitly.
+
 ## 0.24.1 - 2026-09-26
 
 - `Follower Thread Hotfix`: Advances the exact Telegram pin to `0.51.5`. Telegram `/new` in a follower Thread now replaces that follower's session while the leader durably authorizes the Thread binding handoff; automatic follower restore reports why it could not reconnect. Package membership, load order, and other pins remain unchanged.

package/README.md

@@ -12,11 +12,12 @@ Package links lead to the owning repositories for usage, documentation, issues,
 
 | Package | Version | Purpose |
 | --- | ---: | --- |
-| [`@llblab/pi-actors`](https://github.com/llblab/pi-actors) | `0.53.2` | Inspectable local Runs, reusable Recipes, persistent tools, and delegation Skills |
-| [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.2.0` | Isolated nested Pi TUI with named npm extensions and compatible model selection |
-| [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.10.0` | Compact Codex/Spark subscription-limit and Business credit-usage status |
-| [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.2` | Visible continuation scheduling and bounded worker Skills through compiled, manifest-owned resources |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.21.0` | Incremental scoped context/memory compiler with cache-stable heads, sparse acceptance reconciliation, lazy isolation, private fork memory, and optional Git backup |
+| [`@llblab/pi-actors`](https://github.com/llblab/pi-actors) | `0.54.0` | Inspectable local Runs, reusable Recipes, persistent tools, and delegation Skills |
+| [`@llblab/pi-claude-usage`](https://github.com/llblab/pi-claude-usage) | `0.2.0` | Claude subscription quota status and shared per-model Fast toggle for Opus |
+| [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.3.0` | Isolated nested Pi TUI with named npm extensions and compatible model selection |
+| [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.12.0` | Shared Codex quota/Business credit status and persistent priority Fast toggle |
+| [`@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.24.0` | Scoped context/memory compiler with memory-inert Off, safe Passive/Active reacquisition, and read-only Telegram inspections |
 | [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.51.5` | Telegram companion with follower Thread `/new`, restore diagnostics, filterable Skills, files, voice, and controls |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
@@ -24,7 +25,7 @@ Versions are exact by design. An upstream release does not change an installed k
 
 ## Install
 
-Requires **Pi 0.87.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.19.0/docs/usage.md#moving-a-store-and-the-017-format-boundary) 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.24.0/docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing installations.
 
 From npm:
 
@@ -38,18 +39,20 @@ From GitHub:
 pi install git:github.com/llblab/pi-kit
 ```
 
-Pi loads the six extension entrypoints and the Skill resources explicitly declared by the kit. The kit adds no runtime behavior and does not copy the packages' source or instructions into a new owner. State Flow remains opt-in; bundling it does not enable its state handoff mode.
+Pi loads the seven extension entrypoints and the Skill resources explicitly declared by the kit. The kit adds no runtime behavior and does not copy the packages' source or instructions into a new owner. State Flow remains opt-in; bundling it does not enable its state handoff mode.
 
 Prefer the kit instead of separately loading the same packages. If you already use individual installations or local Skill copies, use `pi config` to disable duplicate resources. Installing the kit does not remove or rewrite those installations.
 
 ## Development
 
+The `0.26.0` composition includes published Actors `0.54.0` and State Flow `0.24.0` alongside the Pi 1.0 usage, Clean Room and Grow Loop cohort. The packed bundle loads all seven extensions on Pi 1.0.0 and exercises Fast, State Flow modes and token estimation in disposable storage with no credentials or external requests. This does not certify installed-client rendering; carried checks remain in [Backlog](./BACKLOG.md).
+
 ```bash
 npm install
 npm run validate
 ```
 
-To advance an included package, update its exact version in `dependencies`, run `npm install`, synchronize bundled dependencies, declared resource paths, tests, the table above, and the changelog, then validate the packed artifact. Expose only resources declared by the published owning package; do not use version ranges or unpublished local paths.
+The repository-local `.npmrc` keeps Pi-provided peer packages out of the kit's lockfile; Pi supplies those peers at runtime. To advance an included package, update its exact version in `dependencies`, run `npm install`, synchronize bundled dependencies, declared resource paths, tests, the table above, and the changelog, then validate the packed artifact. Expose only resources declared by the published owning package; do not use version ranges or unpublished local paths.
 
 ## Security
 

package/node_modules/@llblab/pi-actors/AGENTS.md

@@ -26,6 +26,8 @@ Public Run verbs remain `spawn`, `message`, and `inspect`.
 
 ## Core Structure
 
+Require Pi ≥1.0.0 for all declared Pi peers. Keep source and packed lifecycle tests aligned with that baseline; do not restore an older host floor independently of those checks. Validation fixtures must use temporary agent directories, never write into the operator's live Recipe registry.
+
 ```text
 Pi host
   -> index.ts                         composition root

package/node_modules/@llblab/pi-actors/CHANGELOG.md

@@ -2,7 +2,10 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
-## Unreleased
+## 0.54.0: Pi 1.0 Baseline and Package Licensing
+
+- `Licensing`: Includes the MIT LICENSE in source checkouts and npm packages, preserving existing author attribution.
+- `Pi Baseline`: Requires Pi 1.0.0 or newer for both coding-agent and TUI peers. Source and installed-package lifecycle checks use the same baseline; runtime ownership, Recipe/Run semantics and persistent registries are unchanged. Stored-tool normalization tests now use a temporary agent registry rather than writing fixtures into the operator's home.
 
 ## 0.53.2: Stable Inspector Trace Sequences
 

package/node_modules/@llblab/pi-actors/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llblab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@llblab/pi-actors/README.md

@@ -19,7 +19,7 @@ This topology does not require every task to become a subagent. Short work with
 
 ## Install
 
-Requires Node.js 22.19.0 or newer and Pi 0.84.4 or newer.
+Requires Node.js 22.19.0 or newer and Pi 1.0.0 or newer.
 
 ```bash
 pi install npm:@llblab/pi-actors

package/node_modules/@llblab/pi-actors/docs/coordinator-delivery.md

@@ -191,7 +191,7 @@ Implementation is complete only when source and packed-extension tests prove:
 10. Explicit steer reaches the next safe Pi boundary once and root terminal still batches later.
 11. Overflow, corruption, journal backpressure, archive/prune races, and stale contexts fail safely.
 12. Completion flushing precedes automatic Recipe review.
-13. Pi 0.84.4 remains the exact minimum source and packed lifecycle baseline.
+13. Pi 1.0.0 is the minimum source and packed lifecycle baseline; coding-agent and TUI peers share that floor.
 
 Focused observability and delivery tests precede TypeScript/build/import checks. The acceptance checkpoint then runs full product validation, dependency audit, package dry-run, and ABCd context validation.
 

package/node_modules/@llblab/pi-actors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.53.2",
+  "version": "0.54.0",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -38,6 +38,7 @@
     "prepack": "npm run build"
   },
   "files": [
+    "LICENSE",
     "index.ts",
     "dist",
     "lib",
@@ -61,8 +62,8 @@
     "image": "https://raw.githubusercontent.com/llblab/pi-actors/main/banner.jpg"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.84.4",
-    "@earendil-works/pi-tui": ">=0.84.4"
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
+    "@earendil-works/pi-tui": ">=1.0.0"
   },
   "devDependencies": {
     "@types/node": "latest",

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

@@ -0,0 +1,23 @@
+# Agent Notes
+
+- `Registry dependency`: Use published `@llblab/pi-command-fast@^0.1.0` with aligned registry lock metadata. Local folder links are only for explicitly requested development tests; rebuild the library's `dist/` after source edits and restore registry dependency/locks before consumer publication.
+- `Pi baseline`: Every declared `@earendil-works/*` peer requires ≥1.0.0. Keep Pi peer lock identities aligned and validate against that host generation.
+- `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/Telegram. 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.
+- `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.
+- `Adaptive compact status`: Match the status representation to the server-provided quota windows.
+  - Trigger: Changing statusline formatting.
+  - Action: When both windows exist, keep the classic dual bar with 20 top steps for the 5-hour window and 20 bottom steps for the weekly window. When only one weekly window exists, show its rounded remaining percentage directly instead of using a bar.
+- `Weekly reset countdown`: Append the weekly reset countdown whenever the available weekly window exposes a reset time.
+  - Trigger: Changing reset-time normalization or statusline refresh cadence.
+  - Action: Map `five_hour` to the primary window and `seven_day` to the secondary (weekly) window; treat a sole window as weekly. Keep `d` labels rounded upward in 144-minute day-tenth steps above 24h, show 24h..1h labels in upward-rounded 6-minute hour-tenth steps, keep `m`/`s` labels floored, and hold `0s` until a successful quota refresh reports the next window.
+- `Pi auth only`: Usage is read from `https://api.anthropic.com/api/oauth/usage` with the Pi `anthropic` provider OAuth token (`sk-ant-oat…`) and the `anthropic-beta: oauth-2025-04-20` header.
+  - Trigger: Touching auth or adding usage sources.
+  - 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 minute, takeover after 90 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.

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

@@ -0,0 +1,4 @@
+# Backlog
+
+- Operator-owned terminal/optional Telegram visual smoke is separate from the packed offline Pi SDK smoke; no operator session reload was performed.
+- A live Fast speed comparison remains blocked: the authorized short Opus 5.5 sample received `429 credits_required` with `org_level_disabled`. Further live testing needs operator-managed Fast credits/permission and fresh authorization; offline capture proves request shape, not served speed.

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

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.2.0: Shared Fast Mode and Pi 1.0 Baseline
+
+- Split the monolithic extension into cohesive `lib/` domains matching Codex Usage: composition, status lifecycle, shared state, OAuth query, quota normalization, formatting, Telegram and Fast. `index.ts` now only re-exports the unchanged public API; tests follow domain owners. Quota/auth/leadership, mutex/fencing/backoff, status redraw and Fast behavior are preserved.
+- Added an argument-free `/fast` provider handler through `@llblab/pi-command-fast@^0.1.0`, sharing exactly one command with Codex Usage across load orders, duplicate dependency copies, independent sessions and reloads. Claude eligibility is restricted to the Opus family without a version allowlist; other families receive `Fast mode is supported only for Opus` without writes or quota requests, and stale unsupported overrides do not decorate status or activate the request bridge. Generic command dispatch and Codex eligibility are unchanged.
+- Persisted `speed: "fast"` solely in the current Anthropic model override; OFF deletes it. The shared JSONC helper preserves comments and unrelated configuration with atomic replacement.
+- Requires Pi ≥1.0.0 across coding-agent, AI and agent-core peers: older Anthropic transports do not expose the same assembled beta payload contract. Adapted native payloads with Fast speed and additive `fast-mode-2026-02-01` beta, preserving explicit speed and Pi-generated/configured betas through actual HTTP assembly. No provider replacement or header-default suppression.
+- Appended dim lowercase ` fast` at the final terminal status boundary, including loading/error/n/a paths, with immediate silent redraw and no quota request. OAuth quota polling, SQLite mutex, claim fencing, stale display, retry/backoff, and Telegram remain unchanged. Tests now live in `tests/`.
+
+## 0.1.1: Trusted CI Publication
+
+- Releases use the configured npm Trusted Publisher for GitHub Actions, with provenance and workflow-owned GitHub Release creation. Public-package verification now allows approximately 30 minutes for npm processing, with a 35-minute step limit, while retaining exact commit and package-inventory checks.
+- Quota polling, OAuth authentication, shared-state coordination, and statusline behavior are unchanged from 0.1.0.
+
+## 0.1.0: Claude Subscription Usage
+
+- Initial standalone release, adapted from [pi-codex-usage](https://github.com/llblab/pi-codex-usage), for Claude Pro/Max subscriptions. Reads the 5-hour and 7-day quota windows using Pi's Anthropic OAuth login; API-key-only auth reports `n/a`.
+- Shows remaining quota in a compact dual bar, with reset countdowns, animated loading, exhausted-quota highlighting, and optimistic display during refreshes or transient failures. A single available window uses a remaining percentage. Optionally mirrors the same value in the `pi-telegram` status menu.
+- Coordinates all local Pi instances through one shared `usage.json`: the leader refreshes every minute, followers normally read every 30 seconds, and takeover becomes eligible after 90 seconds. Shared failure backoff, including HTTP 429, prevents independent polling.
+- Uses an OS-backed SQLite mutex, atomic JSON writes, and on-disk claim generation/lease checks to deny requests when coordination fails and discard superseded results. Requires Node ≥22.19.0 and a local filesystem. **Upgrade from development versions:** close all old Pi sessions before starting this version; never delete or replace `mutex.sqlite` while sessions run.

package/node_modules/@llblab/pi-claude-usage/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+Copyright (c) 2026 llblab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,155 @@
+# pi-claude-usage
+
+> Pi extension for Anthropic Claude subscription usage state and optional Fast mode
+
+![Claude Usage](./banner.jpg)
+
+This extension owns **usage state + usage mode**: zero-configuration quota reporting and an optional per-model Fast preference. Shared command arbitration/JSONC editing belong to [`@llblab/pi-command-fast`](https://github.com/llblab/pi-command-fast), a normal library dependency, not another Pi extension.
+
+This repository is an adaptation of [`pi-codex-usage`](https://github.com/llblab/pi-codex-usage) for Anthropic Claude Pro/Max subscriptions. It keeps the statusline design, but reads quota from the Anthropic OAuth usage endpoint using Pi's own Anthropic login.
+
+## Start Here
+
+- [Agent Notes](./AGENTS.md)
+- [Backlog](./BACKLOG.md)
+- [Changelog](./CHANGELOG.md)
+
+## Features
+
+- 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
+- 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
+- When `pi-telegram` is available, the same compact value appears as `claude: <value>` in the `/start` menu status text
+- Missing OAuth auth, API-key-only auth, or missing quota windows are shown as `n/a`, not as an error
+- Network/provider failures keep the last good bar, then show `error` after repeated failures
+- Any number of Pi instances share one request stream, see [Shared Refresh](#shared-refresh)
+- No commands or configuration are required for quota display; the optional shared `/fast` toggles native request speed
+
+## Install
+
+Requires Pi ≥1.0.0 for the native beta-preserving Fast bridge. Older Pi (including 0.84.2) assembles Anthropic headers differently and is not supported by this release.
+
+From npm:
+
+```bash
+pi install npm:@llblab/pi-claude-usage
+```
+
+From git:
+
+```bash
+pi install git:github.com/llblab/pi-claude-usage
+```
+
+## Development
+
+The shared `@llblab/pi-command-fast@^0.1.0` dependency now resolves from npm; no sibling library checkout is required.
+
+```bash
+npm ci
+npm run validate
+```
+
+For explicitly local library experiments, a temporary folder link reads the library's built `dist/`, not TypeScript source directly. Rebuild after source edits and restore the registry dependency/lock before publishing; see [Backlog](./BACKLOG.md).
+
+## Fast mode
+
+`/fast` takes no arguments and dispatches by the current **provider**. This consumer permits Fast for the **Opus family** (`claude-opus-` model IDs), without pinning versions. Sonnet, Haiku, Fable, Mythos and other families receive `Fast mode is supported only for Opus` without config writes or quota requests. Family eligibility does not guarantee backend support: older or otherwise unsupported Opus versions can still receive an API rejection. For eligible models it persists only the following model override in Pi's canonical `models.json` (honoring `PI_CODING_AGENT_DIR`):
+
+```json
+{
+  "providers": {
+    "anthropic": {
+      "modelOverrides": {
+        "your-current-model": { "speed": "fast" }
+      }
+    }
+  }
+}
+```
+
+OFF deletes only `speed`; there is no normal/default sentinel or separate Fast config. JSONC comments, unrelated fields and other providers/models survive. State follows the selected model and restart; manual edits are reread on lifecycle refresh and every request. Stale `speed: "fast"` overrides on unsupported models do not enable the suffix or this extension's request bridge; they are preserved, not silently deleted. Remove such a stale property manually if needed.
+
+When Claude Usage and Codex Usage are loaded together, their shared library registers **one** `/fast` in either load order, across separate physical library copies. Its WeakMap is keyed by session manager; shutdown releases registrations because Pi reload reuses that identity. Unrelated providers receive a concise unsupported-provider message; invalid arguments show `Usage: /fast`. Successful toggles are silent and immediately redraw the existing terminal status without a quota request:
+
+```text
+claude ██████▀▀▀▀ 6d fast
+```
+
+Exactly lowercase ` fast` uses the existing dim/countdown role at the final terminal presentation boundary, including loading, single-window percentages, `n/a` and errors. Telegram, quota OAuth, polling, mutex, fencing and backoff are unchanged.
+
+Native request adaptation adds `speed: "fast"` without overwriting an explicit speed. It adds `fast-mode-2026-02-01` to Pi's already-assembled request `betas`, preserving automatic OAuth/thinking/streaming and configured betas; the Anthropic SDK converts that list to the final `anthropic-beta` HTTP header. Setting a replacement header earlier would suppress Pi's automatic betas, so no header replacement or custom provider/transport is used. See [Anthropic Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode).
+
+Pi 1.0.0 accepts the extra override but does not propagate `speed` to native request options, so the bridge is necessary. There is no public command unregister/conditional-visibility API: `/fast` stays listed and checks the provider and consumer model capability when invoked. A stored preference/suffix is intent, not evidence that the backend served Fast. Anthropic also requires Fast usage credits and organization-level permission; a supported model can still be rejected (for example, `429 credits_required` with `org_level_disabled`). The extension never enables billing or buys credits.
+
+## Statusline
+
+```text
+claude ██████▀▀▀▀ 6d
+```
+
+The ten-character bar encodes two twenty-step limits at once: the top quadrants show the remaining 5-hour limit and the bottom quadrants show the remaining weekly limit. If either window is exhausted, the bar keeps its shape but switches to the error background color.
+
+When the weekly reset time is available, it follows the bar. More than a day remains is shown in 144-minute day-tenth steps such as `7d`, `6.9d`, `1.1d`, rounded upward. At 24 hours and below it switches to upward-rounded hour-tenths such as `24h`, `23.7h`, `1.1h`, `1h`. Under an hour it shows floored minutes, then seconds. After the reset passes, `0s` is held until the next successful refresh.
+
+When the 5-hour window is exhausted and exposes its reset time, the statusline adds it before the weekly reset:
+
+```text
+claude ▄▄▄▄▄⠀⠀⠀⠀⠀ 5h/7d
+```
+
+If only one window is returned, the exact remaining percentage is shown:
+
+```text
+claude 67% 7d
+```
+
+Unavailable (no Anthropic subscription auth):
+
+```text
+claude n/a
+```
+
+Runtime failure, such as a network or provider error (including rate limiting of the usage endpoint):
+
+```text
+claude error
+```
+
+## 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/`.
+
+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 minute
+- 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 90s 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 90 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 one minute 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.
+
+## Telegram Status Menu
+
+If `@llblab/pi-telegram` is loaded with the public status-line provider API, this extension registers an optional `/start` menu status row while the active model uses the Anthropic provider:
+
+```text
+claude: ██████▀▀▀▀ 6d
+```
+
+If `pi-telegram` is absent or older, or the active model is not Anthropic, no Telegram row is added.
+
+## Auth
+
+The extension uses the OAuth token of Pi's `anthropic` provider (`/login` → Anthropic Claude Pro/Max) and calls `GET https://api.anthropic.com/api/oauth/usage` with the `anthropic-beta: oauth-2025-04-20` header. Pi refreshes the token as needed. Anthropic API keys are not subscription auth and do not expose these quotas.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/node_modules/@llblab/pi-claude-usage/index.ts

@@ -0,0 +1,8 @@
+/** Domain: package entrypoint. Owns: public re-exports. Excludes: composition and behavior. */
+export { default } from "./lib/extension.ts";
+export { LEADER_INTERVAL_MS, TAKEOVER_AFTER_MS, MIN_ATTEMPT_GAP_MS, readState, writeState, claimRefresh, ownsRefreshClaim, publishRefresh, nextRefreshAt, isRefreshDue, failureBackoffMs, tryAcquireLock } from "./lib/usage-store.ts";
+export type { SharedState, RefreshClaim, RefreshOutcome } from "./lib/usage-store.ts";
+export { normalizeUsagePayload, isUsageUnavailable } from "./lib/usage.ts";
+export type { ClaudeUsageReport, NormalizedRateLimitWindow, UsageQueryError } from "./lib/usage.ts";
+export { formatClaudeUsageStatusline, formatClaudeUsageBar, formatClaudeUsageStatusValue, formatWeeklyResetCountdown, formatResetCountdown, nextResetCountdownDelayMs, nextResetCountdownDelayForRemainingMs, formatClaudeUsageLoadingBar } from "./lib/status-format.ts";
+export { isStaleExtensionContextError } from "./lib/status.ts";

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

@@ -0,0 +1,30 @@
+/** Domain: extension composition. Owns: provider registration, Fast request bridge and status wiring. Excludes: quota, persistence and presentation policy. */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerFastProvider } from "@llblab/pi-command-fast";
+import { applyFastToRequest, isFastEnabled, isFastSupported, toggleFast } from "./fast.ts";
+import { ANTHROPIC_PROVIDER_ID, isAnthropicModel } from "./usage.ts";
+import { createClaudeUsageStatus } from "./status.ts";
+
+export default function claudeUsage(pi: ExtensionAPI) {
+  let releaseFast: (() => void) | undefined;
+  pi.on("before_provider_request", (event, ctx) => {
+    const model = ctx.model;
+    if (!model || !isAnthropicModel(model)) return;
+    return applyFastToRequest(event.payload, model.id, isFastEnabled(model.id));
+  });
+  pi.on("session_start", (_event, ctx) => {
+    releaseFast = registerFastProvider(pi, ctx, {
+      provider: ANTHROPIC_PROVIDER_ID,
+      toggle(commandCtx) {
+        if (!isFastSupported(commandCtx.model!.id)) {
+          commandCtx.ui.notify("Fast mode is supported only for Opus", "warning");
+          return;
+        }
+        toggleFast(commandCtx.model!.id);
+        status.fastChanged(commandCtx, commandCtx.model!);
+      },
+    });
+  });
+  pi.on("session_shutdown", () => { releaseFast?.(); releaseFast = undefined; });
+  const status = createClaudeUsageStatus(pi);
+}

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

@@ -0,0 +1,24 @@
+/** Domain: Claude Fast. Owns: provider semantics and native request beta adaptation. Excludes: quota and command ownership. */
+import { isModelOverrideValue, toggleModelOverrideValue } from "@llblab/pi-command-fast";
+
+export const FAST_BETA = "fast-mode-2026-02-01";
+export function isFastSupported(modelId: string): boolean {
+  return modelId.startsWith("claude-opus-");
+}
+const target = (id: string) => ({ provider: "anthropic", id, property: "speed", enabledValue: "fast" });
+export function isFastEnabled(modelId: string, path?: string): boolean {
+  return isFastSupported(modelId) && isModelOverrideValue(target(modelId), path);
+}
+export function toggleFast(modelId: string, path?: string): boolean {
+  return isFastSupported(modelId) && toggleModelOverrideValue(target(modelId), path);
+}
+
+/** Pi assembles automatic/configured betas before this hook; the Anthropic SDK converts betas to the HTTP header. */
+export function applyFastToRequest(payload: unknown, modelId: string, enabled: boolean): unknown {
+  if (!enabled || !isFastSupported(modelId) || !payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
+  const body = payload as Record<string, unknown>;
+  if (body.model !== modelId || ("speed" in body && body.speed !== "fast")) return undefined;
+  if ("betas" in body && !Array.isArray(body.betas)) return undefined;
+  const betas = Array.isArray(body.betas) ? body.betas : [];
+  return { ...body, speed: "fast", betas: [...new Set([...betas, FAST_BETA])] };
+}