pi-minimal-footer 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-07
+
+### Added
+
+- `minFooter.maxUsageBarCells` (default `10`) to cap the subscription usage bar length; use a positive integer such as `4` for a compact bar, excluding brackets and reset time
+
+### Changed
+
+- Reduce the compact subscription usage bar baseline from five to two cells before expanding into spare space up to the configured cap
+- Add one space at each footer edge, reserving those columns when fitting narrow terminals
+- Refresh README and package-gallery PNG previews with the current footer, edge padding, and live OpenAI Codex subscription usage
+
+## [0.3.3] - 2026-10-07
+
+### Changed
+
+- Add square brackets around the subscription usage bar so its beginning and end remain visible when empty
+- Randomize subscription usage fallback refreshes by ±⅛ of the four-minute interval (3.5–4.5 minutes), preserving reset-time checks and deadlines across unrelated window updates
+- Raise the subscription usage request timeout from five to nine seconds before aborting stalled authentication, fetch, or response-body waits
+
 ## [0.3.2] - 2026-10-06
 
 ### Changed
@@ -147,7 +167,8 @@ First npm-ready release.
 
 - Project scaffold — `extensions/index.ts` with basic footer structure, `package.json` with pi extension manifest, `README.md`, `LICENSE` (MIT)
 
-[Unreleased]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.2...HEAD
+[Unreleased]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.3...HEAD
+[0.3.3]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.2.0...v0.3.0

package/README.md

@@ -9,9 +9,9 @@
 
 An opinionated, compact one-line footer for [Pi](https://github.com/earendil-works/pi).
 
-Path and branch on the left; extension statuses, model, context, and subscription usage bar on the right. Shrinks to fit narrow terminals. Interactive terminal UI only.
+Path and branch on the left; extension statuses, model, context, and subscription usage bar on the right. Shrinks to fit narrow terminals, with one space of padding at each edge. Interactive terminal UI only.
 
-![Footer preview: ~/git/project   main        🧠 Karpathy  🪽 Icarus  model · 42/200k · ⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀↻1d8h](media/github-preview.png)
+![Footer preview: ~/git/project   main        🧠 Karpathy  🪽 Icarus  model · 42/200k · [⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀]↻1d8h](media/github-preview.png)
 
 ## Install
 
@@ -44,20 +44,22 @@ Edit `minFooter` in Pi's agent `settings.json` (normally `~/.pi/agent/settings.j
     "showPath": true,
     "showModel": true,
     "showContext": true,
-    "powerlineSeparator": true
+    "powerlineSeparator": true,
+    "maxUsageBarCells": 10
   }
 }
 ```
 
 - `showSkills` shows **extension status text**, not installed skills. The footer does not add the example statuses itself.
 - Set `powerlineSeparator` to `false` for plain spaces instead of `` / `` if your font lacks those glyphs. The git icon `` also needs a compatible font; hide it with `showGitBranch: false` if needed.
+- `maxUsageBarCells` caps the Braille bar length (excluding brackets and reset time). Use a positive integer, e.g. `4` for a compact bar; invalid values fall back to `10`.
 - Context `42/200k` means tokens used / context window. `?` means Pi has not reported usage yet, including immediately after compaction.
 
 ## Reading subscription usage
 
-`⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀↻1d8h` shows **subscription allowance used**, not context usage.
+`[⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀]↻1d8h` shows **subscription allowance used**, not context usage.
 
-- Bar: 5–10 cells, expanding into spare space; green below 85%, amber from 85%, red from 92%. Dim means cached after a refresh failure. Very narrow terminals may show fewer cells or only the reset label.
+- Bar: shown as `[cells]` with 2–10 cells by default, expanding into spare space up to `maxUsageBarCells` (or fewer when the cap is below 2); green below 85%, amber from 85%, red from 92%. The brackets keep the bar’s beginning and end visible even when it is empty. Dim means cached after a refresh failure. Very narrow terminals may show fewer cells or only the reset label.
 - Reset: local `↻HH:mm` through 24 hours; whole days/hours above 24 hours (`↻1d8h`); whole days above 10 days (`↻12d`). Remaining durations round down. No reset reported means bar only.
 - Shows the shortest available usage window for the selected provider. Missing credentials, unsupported/local models, or absent limits hide the usage bar. Custom proxy endpoints are not polled.
 

package/VISION.md

@@ -55,7 +55,7 @@ Reuse Pi's selected-provider credentials. Copilot uses the GitHub login token fr
 ### Refresh and failure behavior
 
 - Consume passive Codex response headers/stream events and Claude quota headers when available.
-- Otherwise fetch on startup/provider switch, then every four minutes without a fresh response update; also refresh at the reported reset time.
+- Otherwise fetch on startup/provider switch, then roughly every four minutes without a fresh response update. Sample independent uniform ±⅛ jitter (3.5–4.5 minutes) for each attempt or fresh displayed-window update to spread fallback requests across sessions. Keep that deadline across unrelated window updates; a reported reset time still triggers an earlier refresh.
 - Merge partial windows. A weekly-only signal must not replace a cached shorter window or postpone its refresh.
 - Bound authentication, fetch, and response-body parsing by a shared five-second timeout. Release stalled work so polling can recover.
 - Provider switches clear usage immediately, cancel pending work, and invalidate late results. Gemini model switches also refresh model-specific usage.

package/extensions/index.ts

@@ -30,6 +30,7 @@ interface Settings {
     showModel?: boolean;
     showContext?: boolean;
     powerlineSeparator?: boolean;
+    maxUsageBarCells?: number;
   };
 }
 
@@ -43,6 +44,7 @@ const DEFAULT_SETTINGS: FooterSettings = {
   showModel: true,
   showContext: true,
   powerlineSeparator: true,
+  maxUsageBarCells: MAX_BAR_CELLS,
 };
 
 function settingsPath(): string {
@@ -74,7 +76,11 @@ function writeSettings(patch: Partial<Settings>): void {
 
 function readConfig(): FooterSettings {
   const s = readSettings();
-  return { ...DEFAULT_SETTINGS, ...s.minFooter };
+  const config = { ...DEFAULT_SETTINGS, ...s.minFooter };
+  if (typeof config.maxUsageBarCells !== "number" || !Number.isSafeInteger(config.maxUsageBarCells) || config.maxUsageBarCells < 1) {
+    config.maxUsageBarCells = MAX_BAR_CELLS;
+  }
+  return config;
 }
 
 function writeEnabled(v: boolean): void {
@@ -141,12 +147,14 @@ const MIN_STATUS_WIDTH = 12;
 function buildLine(
   width: number, path: string, statuses: string, branch: string, model: string, context: string,
   usage: (available: number, maxCells?: number) => string | null,
-  statusSeparator: string, locationSeparator: string,
+  statusSeparator: string, locationSeparator: string, maxUsageBarCells: number,
 ): string {
   if (width <= 0) return "";
+  if (width <= 2) return " ".repeat(width);
+  width -= 2;
   let core = [model, context].filter(Boolean).join(MODEL_GAP);
   // Budget the compact bar first; its expanded size must not drive truncation decisions.
-  const usageBar = usage(width) ?? "";
+  const usageBar = usage(width, Math.min(BASE_BAR_CELLS, maxUsageBarCells)) ?? "";
   const usageGapWidth = usageBar && core ? USAGE_GAP.length : 0;
   const coreBudget = Math.max(0, width - visibleWidth(usageBar) - usageGapWidth);
   if (usageBar && coreBudget < MIN_TEXT_WIDTH) {
@@ -182,11 +190,11 @@ function buildLine(
     // A dropped left group needs no divider; those columns belong to the usage bar instead.
     const interGroupGapWidth = left && right ? LOCATION_GAP_WIDTH : 0;
     const spareWidth = Math.max(0, width - visibleWidth(left) - visibleWidth(right) - interGroupGapWidth);
-    const expandedUsageBar = usage(visibleWidth(usageBar) + spareWidth, MAX_BAR_CELLS) ?? usageBar;
+    const expandedUsageBar = usage(visibleWidth(usageBar) + spareWidth, maxUsageBarCells) ?? usageBar;
     const expandedCore = [core, expandedUsageBar].filter(Boolean).join(USAGE_GAP);
     right = [fittedStatuses, expandedCore].filter(Boolean).join(statusSeparator);
   }
-  return left + " ".repeat(Math.max(0, width - visibleWidth(left) - visibleWidth(right))) + right;
+  return " " + left + " ".repeat(Math.max(0, width - visibleWidth(left) - visibleWidth(right))) + right + " ";
 }
 
 // ── Extension ─────────────────────────────────────────────────────────
@@ -251,6 +259,7 @@ export default function (pi: ExtensionAPI) {
             (available, maxCells = BASE_BAR_CELLS) => usageLimits.line(available, theme, maxCells),
             statusSeparator,
             config.powerlineSeparator ? theme.fg("dim", "  ") : " ",
+            config.maxUsageBarCells ?? MAX_BAR_CELLS,
           );
           return [line];
         },

package/extensions/lib/usage-limits.ts

@@ -6,14 +6,15 @@ import { parseUsageWindows, record, shortest, supportedOrigin, usageRequest, win
 import type { UsageWindow } from "./usage-providers.js";
 
 const REFRESH_MS = 4 * 60_000;
-const REQUEST_TIMEOUT_MS = 5000;
+const REFRESH_JITTER_MS = REFRESH_MS / 8;
+const REQUEST_TIMEOUT_MS = 9000;
 const HOUR_MS = 60 * 60_000;
 const DAY_MS = 24 * HOUR_MS;
 const CELL_STEPS = 8;
 const PARTIAL_CELL_FILLS = ["", "⡀", "⣀", "⣄", "⣤", "⣦", "⣶", "⣷"];
 
 // Start compact so extra precision never steals space from the other footer fields.
-export const BASE_BAR_CELLS = 5;
+export const BASE_BAR_CELLS = 2;
 export const MAX_BAR_CELLS = 10;
 
 function formatResetLabel(resetAt: number | null, now: number): string {
@@ -115,6 +116,7 @@ export class UsageLimits {
   private updatedAt: Record<string, number> = {};
   private stale = false;
   private attemptedAt = 0;
+  private refreshDelay = REFRESH_MS;
   private timer: ReturnType<typeof setTimeout> | null = null;
   private request: AbortController | null = null;
 
@@ -178,17 +180,23 @@ export class UsageLimits {
       // Only a response for the displayed window supersedes its background refresh.
       this.cancelRequest();
       this.stale = false;
+      this.randomizeRefresh();
     }
     this.schedule();
     this.render();
   }
 
+  private randomizeRefresh(): void {
+    this.refreshDelay = REFRESH_MS + (Math.random() * 2 - 1) * REFRESH_JITTER_MS;
+  }
+
   private schedule(): void {
     if (this.timer) clearTimeout(this.timer);
     this.timer = null;
     if (!this.ctx || this.request) return;
     const selected = this.selectedWindow();
-    let next = Math.max(this.attemptedAt, selected ? this.updatedAt[selected[0]] : 0) + REFRESH_MS;
+    // Keep the sampled deadline when unrelated windows reschedule the timer.
+    let next = Math.max(this.attemptedAt, selected ? this.updatedAt[selected[0]] : 0) + this.refreshDelay;
     const resetAt = selected?.[1].resetAt;
     if (resetAt != null && resetAt > this.attemptedAt) next = Math.min(next, resetAt);
     this.timer = setTimeout(() => { this.timer = null; void this.poll(); }, Math.max(1, next - Date.now()));
@@ -205,6 +213,7 @@ export class UsageLimits {
     // Identity checks below keep late responses from restoring a replaced provider's usage.
     this.request = controller;
     this.attemptedAt = Date.now();
+    this.randomizeRefresh();
     const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
     timeout.unref();
     try {
@@ -237,14 +246,15 @@ export class UsageLimits {
     if (!this.ctx || !window) return null;
     const now = Date.now();
     const resetLabel = formatResetLabel(window.resetAt, now);
-    if (width < (resetLabel.length || 1)) return null;
-    const cells = Math.min(maxCells, Math.max(0, width - resetLabel.length));
+    // Reserve two columns for brackets so an empty bar still has clear edges.
+    if (width < (resetLabel.length || 1) + 3) return null;
+    const cells = Math.min(maxCells, Math.max(1, width - resetLabel.length - 2));
     const steps = Math.round(window.used / 100 * cells * CELL_STEPS);
     const filled = "⣿".repeat(Math.floor(steps / CELL_STEPS)) + PARTIAL_CELL_FILLS[steps % CELL_STEPS];
     const empty = "⠀".repeat(cells - Math.ceil(steps / CELL_STEPS));
     const stale = this.stale || (window.resetAt !== null && now >= window.resetAt);
     const color = stale ? "dim" : window.used >= 92 ? "error" : window.used >= 85 ? "warning" : "success";
     const bar = cells ? theme.fg(color, filled) + theme.fg("dim", empty) : "";
-    return bar + theme.fg("dim", resetLabel);
+    return theme.fg("dim", "[") + bar + theme.fg("dim", "]") + theme.fg("dim", resetLabel);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-minimal-footer",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "An opinionated minimal footer extension for Pi — clean status line with path, extension statuses, model, and context usage.",
   "keywords": [
     "pi-package",