@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/skills/swarm/references/development-swarm.md

@@ -0,0 +1,189 @@
+# Development Swarms
+
+Use this reference when two or more implementation participants can own disjoint mutation zones and one integrator can reconcile them. Keep generic actor execution and lifecycle behavior in `actors`.
+
+## Admission test
+
+Use a development swarm only when all are true:
+
+- the accepted direction is stable enough to partition;
+- each participant can receive a meaningful bounded scope;
+- shared contracts have one named owner;
+- work can be isolated from the shared target while in progress;
+- one integrator owns merge order and final validation.
+
+Do not parallelize implementation when tasks need the same central files, semantic ordering dominates wall-clock time, or the likely conflicts would invalidate the decomposition. Use planning or review first.
+
+## Coordinator role separation
+
+In a host-coordinator topology, the current Pi instance owns the declarative outcome and participant graph rather than acting as the default implementation worker. It may receive intent through Telegram or another companion extension, but transport does not become a gateway or gain hidden instance-creation authority; participant creation remains an explicit actor-kernel Run.
+
+The coordinator should:
+
+- Translate high-level intent into bounded task cards and dependency edges.
+- Keep user authority, shared contracts, integration order, and final validation local.
+- Remain available for checkpoints, permissions, conflicts, and changing evidence.
+- Consume terminal handoffs, durable artifacts, and Trace attention instead of mirroring participant work.
+- Check overdue work on an evidence-based timer; never replace event-driven completion with a rapid polling loop.
+
+A participant should:
+
+- Own one concrete execution or evidence boundary.
+- Avoid global orchestration and undeclared participant creation.
+- Return a bounded handoff that lets the coordinator decide without replaying the entire task.
+
+Use one ordinary Run under `actors` when only one worker is delegated. Activate this development-swarm protocol when two or more participants, parallel ownership, or explicit integration edges exist. Keep trivial single-boundary work inline when delegation overhead has no compensating value.
+
+## Reasoning profiles
+
+| Role | Default | Raise or fan out when |
+| --- | --- | --- |
+| Bounded implementation author | Reasoning off | The card explicitly owns unresolved diagnosis or design judgement |
+| Reviewer | Medium reasoning, clean context | Stakes require independent lenses or repeated judges |
+| Synthesizer / integrator | Medium reasoning | Evidence conflicts, shared contracts move, or merge order is semantic |
+| Coordinator | Sufficient for decomposition and decisions | Scope, authority, or architecture remains unresolved |
+
+Prefer independent review after implementation over asking one author thread to implement, retain all local assumptions, and then certify itself. When risk justifies the cost, use multiple independent reviewers: different lenses increase breadth, while repeated judges increase confidence. Preserve minority high-impact findings and merge only evidence-backed conclusions.
+
+More reviewers are not automatically better. Do not fan out when they would inspect unstable code, share contaminated context, repeat one unsupported claim, or exceed the value of the decision. Never change an already-running participant solely to enforce a newer profile; add a fresh review boundary if evidence remains open.
+
+## Decompose by ownership
+
+Prefer mutation-zone ownership over broad feature labels.
+
+```text
+behavior owner  → production behavior in one domain
+test owner      → regressions and fixtures for that domain
+docs owner      → affected agent/user contract
+integrator      → shared contracts, merge, final checks
+```
+
+A participant may own both behavior and its tests when separating them would force synchronized edits. What matters is one owner per writable surface and an explicit integration edge.
+
+## Task card
+
+Every participant receives one task card before mutation:
+
+```markdown
+# Task Card
+
+Goal:
+Non-goals:
+Allowed files or logical scope:
+Avoided files or shared contracts:
+Execution profile:
+Isolation mode: exclusive paths | isolated worktree | artifact-only
+Shared surfaces reserved for integrator:
+Expected artifact or patch:
+Required evidence:
+Checks:
+Escalate when:
+Handoff destination:
+```
+
+A useful task card names the smallest scope that can independently reach a validation boundary. It does not ask a participant to "help with" a broad project area. Participants must restate scope before editing and record discovered out-of-scope work rather than performing it.
+
+`swarm/development-tasking` can generate and critique one card when the goal, allowed scope, avoided scope, checks, model, and tools are already known.
+
+## Write ownership
+
+- Give each writable file or logical contract one owner.
+- Treat schemas, public APIs, central configuration, migrations, and specifications as exclusive even when textual merges look easy.
+- Parallel readers may inspect a stable shared target.
+- Isolate concurrent mutation through the repository's existing branch/workspace mechanism.
+- Use bounded lock evidence when ownership is not otherwise obvious. A lock records intent; it does not authorize scope expansion.
+- Release ownership at terminal handoff or explicitly transfer it through the integrator.
+
+If a participant discovers that another scope must change, it emits a dependency or conflict report and stops that edge. The coordinator either transfers ownership, serializes the work, or replans.
+
+## Isolation modes
+
+- `Exclusive paths`: Writers share one worktree only when their complete writable path sets are disjoint and the shared baseline remains stable.
+- `Isolated worktree`: Use when compilation, generated files, imports, or likely dependencies can touch shared repository state.
+- `Artifact-only`: Use for reports, inventories, proposed patches, fixtures, or reviews that the integrator applies later.
+
+The integrator exclusively owns `BACKLOG.md`, `CHANGELOG.md`, lockfiles, generated metadata, public schemas, release manifests, and cross-domain configuration by default. A task card may transfer one of these surfaces to another participant, but never create concurrent ownership. Authors report required shared-surface changes in handoff instead of applying them outside scope.
+
+## Coordinator checkpoints
+
+A checkpoint preserves useful local context while requesting one decision:
+
+```markdown
+# Coordinator Checkpoint
+
+Task:
+Current scope:
+Question:
+Why a coordinator decision is required:
+Options and evidence:
+Recommended option:
+Risk if guessed:
+State that must be preserved:
+```
+
+Use checkpoints for scope changes, product choices, shared-contract decisions, permissions, or conflict policy. The coordinator answers only the bounded question. If the participant cannot resume with preserved context, retain the checkpoint as a handoff and start a clean replacement explicitly.
+
+## Handoff
+
+Every participant returns:
+
+```markdown
+# Handoff
+
+Task:
+Status: complete | degraded | blocked
+Summary:
+Touched scope:
+Behavior or contract changes:
+Checks and results:
+Artifacts or patch identity:
+Dependencies discovered:
+Risks and unresolved questions:
+Integrator invariants:
+```
+
+A successful process exit without the expected patch, artifact, or evidence is not a successful handoff. Preserve partial work as degraded evidence when it is useful and safe to integrate.
+
+## Conflict evidence
+
+Distinguish three conflict classes:
+
+- **Textual conflict:** edits overlap mechanically.
+- **Semantic conflict:** edits merge but depend on incompatible meanings.
+- **Architecture conflict:** the decomposition or accepted direction is wrong.
+
+Each affected owner reports:
+
+```markdown
+# Conflict Report
+
+Task and owned scope:
+Conflicting scope:
+Intent:
+Invariant that must survive:
+Change made:
+Evidence:
+Safe-to-discard portion:
+Proposed resolution:
+```
+
+The integrator resolves from both reports. Architecture conflicts stop affected work and return to planning. Do not let participants recursively negotiate until their independent intent is lost.
+
+## Integration protocol
+
+The named integrator:
+
+1. freezes new author mutations and preserves every terminal handoff before integration;
+2. reads task cards, handoffs, dependency edges, and conflict reports;
+3. verifies each result stayed within scope;
+4. integrates in dependency order, one ownership edge at a time;
+5. resolves conflicts while preserving stated invariants;
+6. runs checks after risky edges and the full agreed validation at the end;
+7. obtains fresh review for conflict-resolved or shared-contract changes;
+8. reports integrated tasks, rejected or deferred work, checks, and residual risks.
+
+Do not treat a clean merge, participant-local tests, or a collection of terminal Runs as integrated completion. Completion requires retained shared state plus coordinator-owned validation evidence.
+
+## Stop conditions
+
+Stop and replan when ownership overlaps, an exclusive contract lacks one owner, task cards cannot be independently validated, an out-of-scope dependency is required, architecture conflict appears, or no integrator can validate the retained result. Prefer a smaller serial cohort over parallel diff chaos.

package/node_modules/@llblab/pi-actors/skills/swarm/references/review-swarms.md

@@ -0,0 +1,115 @@
+# Review Swarms
+
+Use this reference for independent review, delegated audit, research synthesis, quorum judgement, and post-merge review. Generic actor execution remains owned by `actors`.
+
+## Select breadth or confidence
+
+```text
+Different lenses on one target → breadth → lens swarm
+Same exact claim, independent judges → confidence → quorum
+Important lenses each need repeated judges → breadth + confidence → lens swarms of quorums
+```
+
+Use the smallest shape that covers the decision risk. A lens swarm of quorums is reserved for high-impact security, financial, governance, migration, or release decisions.
+
+Primary Recipes:
+
+- `swarm/lens-review` for parallel risk lenses plus verification, merge, judge, and normalized result;
+- `swarm/quorum-review` for one prompt judged independently by explicitly selected models;
+- `swarm/research-synthesis` for plan, evidence map, contradictions, verification, and risk-first synthesis;
+- `swarm/architect` for competing directions and one validated smallest next slice;
+- `swarm/review-readiness` for a multi-lens ship/readiness verdict.
+
+## Lens selection
+
+Choose lenses from plausible failure modes, not from a fixed catalog. Common software lenses include correctness, architecture, security, tests, concurrency, data integrity, performance, operator UX, accessibility, maintainability, documentation, and release risk.
+
+A good lens assignment states:
+
+```markdown
+Target:
+Question or claim:
+Lens:
+Evidence required:
+Out of scope:
+Severity rule:
+Output shape:
+Stop condition:
+```
+
+Do not ask every reviewer to cover everything. Keep reviewers independent until synthesis so one early narrative does not contaminate all findings.
+
+## Quorum design
+
+A quorum keeps the target, claim, evidence standard, and output shape constant while varying independent judges. Before fanout:
+
+1. define the exact decision claim;
+2. define what counts as supporting and contradicting evidence;
+3. select the minimum successful threshold;
+4. choose concurrency and timeout bounds;
+5. preflight model and tool availability;
+6. define how partial results affect status.
+
+Provider or model failure reduces available evidence; it is not a vote. When evidence falls below threshold, mark the result degraded or insufficient data.
+
+## Research evidence
+
+Research participants separate source discovery, verification, contradiction mapping, and synthesis when stakes justify it.
+
+- Every material claim traces to a source note, inspected artifact, or explicit uncertainty.
+- Source quality and confidence remain visible.
+- Contradictory evidence is first-class output.
+- Missing source classes block overconfident synthesis.
+- Unsafe or unverifiable evidence is excluded with a reason.
+
+Do not turn a research swarm into an automatic publication pipeline. Stop at the caller's evidence and decision boundary.
+
+## Merge protocol
+
+A merger is a synthesis participant, not a formatter. It may deduplicate, rank, connect evidence, and add a grounded `merger finding`, but it may not fabricate support.
+
+For serious quorum work, use a clean-context merger. The merger receives all retained participant outputs and must produce:
+
+- status: complete, degraded, or insufficient data;
+- consensus findings and vote shape where applicable;
+- minority high-impact findings;
+- contradictions and unresolved evidence gaps;
+- merger findings, clearly labeled;
+- confidence and limitations;
+- ordered next actions.
+
+Keep raw participant outputs until the merged result is accepted. Preserve attribution for major findings. Never promote repeated low-value observations merely because they are numerous, and never discard a severe evidence-backed minority finding merely because it is unique.
+
+## Conflict and disagreement
+
+Disagreement can mean different assumptions, different evidence, ambiguous criteria, or real uncertainty. The merger records:
+
+```markdown
+Finding:
+Supporting participants and evidence:
+Contradicting participants and evidence:
+Assumption difference:
+Impact if minority view is correct:
+Resolution status:
+Next evidence needed:
+```
+
+Resolve only when evidence supports resolution. Otherwise preserve the disagreement and lower confidence.
+
+## Post-merge review
+
+Use a fresh reviewer when the merged result will drive consequential implementation or decisions. The post-merge reviewer checks the report, not the original target by default:
+
+- evidence traceability;
+- honest severity;
+- correct quorum accounting;
+- preserved minority findings;
+- unsupported merger narrative;
+- actionable next steps;
+- retained uncertainty and contradictions.
+
+Possible decisions are accept, accept with notes, revise merge, rerun bounded quorum, or escalate. Rerun only when the raw evidence or scope is genuinely insufficient, not because the verdict is inconvenient.
+
+## Completion and stop rules
+
+A review swarm is complete only when requested evidence is retained, threshold status is explicit, synthesis preserves dissent, and the coordinator can state the safe decision or next evidence slice. Stop when the claim is ambiguous, target changes during review, preflight fails, evidence is not inspectable, threshold cannot be met, or merger independence required by the stakes is unavailable.

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

@@ -0,0 +1,17 @@
+# Agent Notes
+
+- `Statusline-first scope`: Keep this extension zero-configuration and focused on compact status surfaces.
+  - Trigger: Considering commands, menus, persisted settings, or notification output.
+  - Action: Prefer deleting the surface unless it is required for the optimistic TUI status widget or the optional `pi-telegram` `/start` status-line mirror.
+
+- `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: Treat the secondary window as weekly in dual-window responses and the sole window as weekly in single-window responses. 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.

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

@@ -0,0 +1,8 @@
+# Backlog
+
+## Pending Release Verification
+
+- [x] Fix stale extension context usage after session replacement or reload. Source: GitHub issue #1. Timers must not keep using captured stale `ctx` after Pi session lifecycle changes.
+- [x] Make usage refresh cache/in-flight state model-aware for Codex vs Spark. A regular Codex cache or request must not temporarily render Spark as `n/a` after model switching.
+- [x] Preserve the active `codex`/`spark` label for failure states. Spark failures should render `spark n/a` or `spark error`, not `codex ...`.
+- [x] Replace the visually full startup/request placeholder with counter-moving upper/lower in-bar loading markers. Keep the last usable active-bucket bar visible during ordinary refreshes, and hold provisional zero-usage reports behind the loader until confirmed stable.

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

@@ -0,0 +1,80 @@
+# Changelog
+
+## Unreleased
+
+## 0.9.1: Clear Weekly Quota Status
+
+- Replaced the unified single-window bar with an explicit remaining-quota percentage. Impact: weekly-only OpenAI responses now render as compact text such as `codex 67% 7d`, making both the remaining quota and reset time immediately readable without decoding a bar.
+- Preserved the classic dual-tier bar for responses that still expose both 5-hour and weekly windows. Impact: older or account-specific server response shapes retain the dense two-limit display while the status adapts directly to available information.
+
+## 0.9.0: Adaptive Weekly Quota Bar
+
+- Added server-driven quota-window display selection. Impact: responses containing both 5-hour and weekly windows keep the classic dual-tier bar, while responses containing only the new weekly window use all 40 bar steps as one unified quota scale instead of leaving one tier empty.
+- Added single-window reset countdown and redraw scheduling. Impact: the weekly reset time remains visible and updates at the correct countdown boundaries regardless of whether OpenAI returns the weekly limit as the primary or secondary window.
+- Extended provisional full-quota stabilization to single-window responses. Impact: transient 0%-used weekly reports remain behind the loading indicator until confirmed, matching the existing dual-window safety behavior.
+
+## 0.8.2: Quota Loading Hotfix
+
+- Replaced the static empty request placeholder with fixed-width upper and lower markers that move in opposite directions through their respective quota bars, reverse at the ends, and randomly start from either mirrored endpoint phase, using the normal themed bar background. Impact: motion distinguishes startup and model-bucket loading from 100% available quota while preserving the dual-window visual language.
+- Kept the last usable active-bucket report visible while refreshing, including when returning from another model bucket, and stabilized first reports claiming both windows are completely unused for 15 seconds with one-second retries. Impact: routine polling remains visually stable while transient provider initialization values stay behind the loader instead of appearing as false 100% availability.
+
+## 0.8.1: Stale Context Hotfix
+
+- Fixed stale extension context crashes from delayed statusline timers after Pi session replacement or reload. Impact: timers now ignore stale `ctx` failures instead of letting issue #1 crash Pi after idle/session lifecycle changes.
+- Fixed Codex/Spark refresh state to key in-flight usage lookups by active quota bucket and only reuse cached reports that contain the active bucket. Impact: switching between regular Codex and Spark no longer temporarily renders the active bucket as unavailable because of a stale request/cache.
+- Fixed Spark failure labels. Impact: Spark unavailable/error states now render with the `spark` label instead of falling back to `codex`.
+- Added regression coverage for active-bucket cache reuse and stale extension context error detection.
+
+## 0.8.0: Spark Model Usage Status
+
+- Added active-bucket status support for `GPT-5.3-Codex-Spark`. Impact: selecting the Spark Codex subscription model now shows the parallel Spark rate-limit bucket with a `spark` label, while regular Codex models keep the existing `codex` bucket/status behavior.
+- Added parsing for backend `additional_rate_limits`, including the Spark `GPT-5.3-Codex-Spark` / `codex_bengalfox` limit. Impact: Spark quota can be shown from the same Pi-auth usage response path as normal Codex quota instead of relying only on app-server fallback.
+
+## 0.7.0: Exhausted Quota Visibility
+
+- Added exhausted-quota warning background for the statusline quota bar. Impact: when either the 5-hour or weekly Codex window has 0% remaining, the bar keeps its shape but switches from the selected background to the error background for faster visual detection.
+- Added exhausted-primary countdown display for cases where the 5-hour Codex window has 0% remaining and exposes a reset time. Impact: the statusline keeps the normal ten-cell dual bar and appends `<5-hour-reset>/<weekly-reset>` countdowns, so operators can see both how long to wait for short-window recovery and how much weekly quota remains.
+- Fixed quota-bar rounding so a truly empty segment state is shown only when a quota window has 0% remaining, while any positive sub-5% remainder still renders as one visible step. Impact: the statusline now distinguishes exhausted Codex limits from tiny remaining quota without changing normal round-to-nearest behavior elsewhere.
+
+## 0.6.0: Telegram Status Integration
+
+- Added optional `pi-telegram` status-menu integration through the public Telegram status-line provider API. When `pi-telegram` is available and the active model is an OpenAI Codex subscription model, the `/start` menu status text now includes `codex: <value>` using the same compact quota bar and reset countdown value as the terminal statusline. Impact: Telegram operators can see Codex quota/reset state in the main control menu without any extra configuration, while non-Codex models and missing `pi-telegram` installs stay unchanged.
+
+## 0.5.2: Sub-Day Reset Countdown And JPEG Banner
+
+- Refined the weekly reset countdown below 24 hours to use upward-rounded 6-minute hour-tenth steps (`24h`, `23.7h`, `20.1h`, `20h`, `19.9h`, …, `1h`) instead of coarse whole-hour floors. Impact: the statusline gives more useful sub-day reset timing without growing wider than one decimal place.
+- Replaced the package/banner artwork from PNG to JPEG and updated package metadata plus README image references. Impact: the package ships the new compressed banner asset consistently across npm and Pi extension listings.
+
+## 0.5.1: Non-Codex Bucket Hotfix
+
+- Fixed non-Codex app-server quota buckets so Spark-only or unrelated limits are ignored instead of being displayed as Codex quota.
+
+## 0.5.0: Weekly Reset Countdown
+
+- Added refresh request coalescing so repeated statusline events share one quota lookup instead of spawning parallel provider/fallback requests. Impact: transient failures and busy session-tree updates no longer amplify Codex usage polling work.
+- Hardened quota parsing and failure classification by accepting array-shaped app-server rate limits, treating `n/a` as valid only when every failed source reports an unavailable auth/plan/quota state, and adding `node:test` coverage for normalization, bar formatting, and failure classification. Impact: real fallback/runtime failures are surfaced as `error` while expected unavailable states still show `n/a`.
+- Added a weekly reset countdown after the quota bar when the secondary Codex window exposes a reset timestamp, including 144-minute day-tenth steps, exact boundary redraw scheduling, hour/minute/second bucket formatting, and `0s` holdover until the next successful quota refresh. Impact: the statusline now shows both remaining quota and time until the weekly bucket cycles.
+
+## 0.4.1: Stable Startup Bar
+
+- Fixed the initial empty statusline bar to use ten non-trimmed blank glyph cells through the same formatting path as the populated quota bar. Impact: the footer background stays at ten cells during startup before the first quota values arrive.
+
+## 0.4.0
+
+- Expanded the dual statusline bar to ten glyphs with 20 steps per quota window, moved its status key near the start of the footer status order, and draws the bar on the themed selected background. Impact: 5-hour and weekly limits now move in 5% increments for 40 total discrete points while empty cells no longer blend into the terminal background.
+
+## 0.3.5
+
+- Refined the compact statusline bar with quadrant glyphs, darker bar coloring, and blink-on-segment-change behavior. Impact: Codex quota changes are easier to notice while routine refreshes stay visually stable.
+
+## 0.3.4
+
+- Added package banner metadata and README hero image. Impact: Pi/package listings can show the Codex Usage banner while npm packages include the image asset.
+
+## Fork baseline
+
+- Imported `extensions/pi-codex-usage` from `narumiruna/pi-extensions` as a standalone `@llblab/pi-codex-usage` package. Impact: the extension can be installed and maintained independently.
+- Removed command-driven report output and narrowed the extension to a zero-configuration statusline widget. Impact: runtime behavior is automatic while `openai-codex` is active.
+- Ignored additional returned buckets such as Spark-specific limits. Impact: the statusline only represents primary Codex 5-hour and weekly quota windows.
+- Replaced textual percentages with a fixed-width separated-sextant bar. Impact: both 5-hour and weekly remaining quota are encoded in five statusline characters.
+- Kept the last good bar during refresh and transient failures, with a short successful-redraw blink. Impact: the footer no longer shifts or collapses during polling.

package/node_modules/@llblab/pi-codex-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-codex-usage/README.md

@@ -0,0 +1,113 @@
+# pi-codex-usage
+
+> Minimal zero-configuration Pi extension for showing primary ChatGPT Codex usage limits in the statusline
+
+![Codex Usage](./banner.jpg)
+
+This repository is a minimal fork of [`narumiruna/pi-extensions/extensions/pi-codex-usage`](https://github.com/narumiruna/pi-extensions/tree/main/extensions/pi-codex-usage). It keeps the auth and quota-fetching path, but intentionally narrows the interface to the Codex quota windows returned by OpenAI.
+
+## 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 the active Codex/Spark quota bucket is loading, then refreshes every 30 seconds
+- Keeps the last usable active-bucket bar visible during ordinary refreshes instead of replacing known quota with a loading state
+- Statusline output adapts to the response: weekly-only limits show an explicit remaining percentage and reset countdown, while dual-window limits keep the compact themed bar
+- Regular Codex subscription models show the primary `codex` quota bucket
+- `GPT-5.3-Codex-Spark` shows the parallel Spark quota bucket with the `spark` label
+- When `pi-telegram` is available, the same compact value appears as `codex: <value>` or `spark: <value>` in the `/start` menu status text for active OpenAI Codex subscription models
+- Additional returned buckets unrelated to the active Codex/Spark model are ignored
+- Pi OpenAI Codex provider auth is used first
+- Codex CLI app-server remains available as a fallback
+- Missing auth, subscription, plan, or quota windows are shown as `n/a`, not as an error
+- Successful updates briefly redraw the bar only when a 5% segment changes
+- Network/provider failures keep the last good bar briefly, then show `error`
+- No commands or configuration are required
+
+## Install
+
+From npm:
+
+```bash
+pi install npm:@llblab/pi-codex-usage
+```
+
+From git:
+
+```bash
+pi install git:github.com/llblab/pi-codex-usage
+```
+
+## Statusline
+
+Regular Codex usage:
+
+```text
+codex ██████▀▀▀▀ 6d
+```
+
+Spark model usage:
+
+```text
+spark ██████████ 7d
+```
+
+When OpenAI returns only the weekly window, the status shows the exact rounded remaining percentage and reset countdown directly:
+
+```text
+codex 67% 7d
+```
+
+When both windows exist, the ten-character bar encodes two twenty-step limits at once: the top quadrants show the 5-hour limit and the bottom quadrants show the weekly limit, with each step representing 5%. If either quota window is exhausted, the bar keeps its shape but switches to the error background color.
+
+Before the first usable report for the active quota bucket arrives, two half-height markers move through the same fixed-width themed bar. The upper 5-hour marker travels opposite the lower weekly marker; both reverse smoothly at the ends, and each loader run randomly starts from one of the two mirrored endpoint phases. Their motion distinguishes loading from 100% remaining quota while preserving the normal bar background. A first report claiming both windows are completely unused is treated as provisional for 15 seconds and retried every second, because providers can briefly emit zeroed windows while initializing. Once a usable report exists, refresh requests preserve that last good bar.
+
+When the weekly reset time is available, it follows either the single-window percentage or the dual-window bar. More than a day remains is shown in 144-minute day-tenth steps such as `7d`, `6.9d`, `6.6d`, `5.1d`, `5d`, `3.7d`, `3d`, `2d`, `1.9d`, `1.5d`, and `1.1d`, rounded upward to the next tenth. At 24 hours and below it switches to upward-rounded 6-minute hour-tenth steps such as `24h`, `23.7h`, `20.1h`, `20h`, `19.9h`, `1.4h`, `1.3h`, `1.2h`, `1.1h`, and `1h`. Under an hour it switches to floored minutes, and under a minute to seconds. After the reset timestamp passes, `0s` is held until the next successful quota refresh reports the new weekly window.
+
+When the 5-hour window is exhausted and exposes its own reset time, the statusline adds the 5-hour reset before the weekly reset:
+
+```text
+codex ▄▄▄▄▄⠀⠀⠀⠀⠀ 5h/7d
+```
+
+The ten-character dual bar stays unchanged. The first countdown is the 5-hour reset, and the second countdown after `/` is the weekly reset.
+
+Unavailable because Codex auth or subscription quota is not available:
+
+```text
+codex n/a
+```
+
+Runtime failure, such as a network or provider error:
+
+```text
+codex error
+```
+
+## 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. The row is shown only while the active model uses the OpenAI Codex subscription provider:
+
+```text
+codex: ██████▀▀▀▀ 6d
+spark: ██████████ 7d
+```
+
+The value is the same compact quota bar plus weekly reset countdown used by the terminal statusline, and the label follows the active Codex/Spark model. If `pi-telegram` is absent, older, or the active model is not a Codex subscription model, no Telegram row is added.
+
+## Auth
+
+The extension tries usage sources in this order:
+
+1. Pi's `openai-codex` provider auth
+2. `codex app-server --listen stdio://`
+
+OpenAI API keys are not ChatGPT Codex subscription auth and do not expose these quotas.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).