pi-minimal-footer 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-08
+
+### Fixed
+
+- Run Git queries only while the extension owns a live TUI footer; explicit enable resumes querying
+- Reject Git refresh and fetch timeout settings above Node's maximum timer delay, preserving the 91- and 17-second fallbacks
+- Replace fixed sleeps in Git fetch jitter tests with bounded waits for child completion and retry scheduling
+
+### Changed
+
+- Keep the README user-focused; move compatibility and plugin API details to the developer guide
+- Document the rationale for brief Git pulses and live-footer refresh ownership
+- Pulse the whole Git section bold for one second when divergence changes, replacing the two-user-submission count highlight; preserve unsynced/synced foreground colors and cancel the pulse on disposal
+
+### Added
+
+- Opt-in `minFooter.gitFetch` background fetch on footer startup and every five minutes with ±⅛ jitter; silent failures, no interactive credential prompts, configurable `gitFetchTimeoutSeconds` (default 17), and cancellation on footer disposal
+
 ## [0.5.3] - 2026-10-07
 
 ### Changed
@@ -216,7 +234,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.5.3...HEAD
+[Unreleased]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.5.3...v0.6.0
 [0.5.3]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.5.0...v0.5.1

package/README.md

@@ -35,10 +35,7 @@ pi install npm:pi-minimal-footer
 pi install npm:@ryu-cz/pi-minimal-footer
 ```
 
-`pi-minimal-footer` remains the original, unscoped release path. The scoped
-`@ryu-cz/pi-minimal-footer` package is an official mirror intended to improve
-package indexing; it is not a separate extension. The scoped name is an
-indexing workaround, not a guaranteed fix for pi.dev catalog search.
+The scoped package is an official mirror, not a separate extension.
 
 ## Commands
 
@@ -63,6 +60,8 @@ Edit `minFooter` in Pi's agent `settings.json` (normally `~/.pi/agent/settings.j
     "showContext": true,
     "powerlineSeparator": true,
     "gitRefreshSeconds": 91,
+    "gitFetch": false,
+    "gitFetchTimeoutSeconds": 17,
     "maxUsageBarCells": 10
   }
 }
@@ -70,14 +69,16 @@ Edit `minFooter` in Pi's agent `settings.json` (normally `~/.pi/agent/settings.j
 
 - `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 `` and sync arrows also need compatible glyphs; hide Git data with `showGitBranch: false` if needed.
-- `gitRefreshSeconds`: local Git refresh interval; positive integer seconds; default/fallback `91`; no remote fetch.
+- `gitRefreshSeconds`: local refresh interval; `1`–`2147483` seconds; default `91`.
+- `gitFetch`: background fetch on startup, then roughly 5 minutes after each attempt completes; failures are silent; default `false`.
+- `gitFetchTimeoutSeconds`: fetch timeout; `1`–`2147483` seconds; default `17`. Invalid timer settings use their defaults.
 - `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`.
 
 ## Reading the footer
 
 ### Git
 
-Counts require a configured upstream. Unsynced branches use the theme's normal foreground; synced branches are dim. Changed counts stay bold until two subsequent user messages; further changes restart the highlight.
+Counts require a configured upstream. Unsynced branches use normal text color; synced branches are dim. Count changes pulse the whole Git section bold for one second; further changes restart the pulse.
 
 ### Context
 
@@ -92,8 +93,28 @@ Counts require a configured upstream. Unsynced branches use the theme's normal f
 - **Cached data:** dim after a refresh failure.
 - 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.
+- Virtual/routed models show model and context usage, but no subscription bar.
 
-Implemented adapters: **OpenAI Codex, Claude OAuth, GitHub Copilot, Gemini CLI, MiniMax, Kimi Coding, and OpenCode Go**. Uses Pi's existing credentials; ordinary Claude API keys do not expose subscription usage. Authenticated endpoints remain unverified live; see [verification limits](VISION.md).
+#### Adapters
+
+Adapters use Pi's existing credentials; ordinary Claude API keys do not expose subscription usage.
+
+*Authenticated endpoints remain unverified live; see [verification limits](VISION.md).*
+
+Implemented adapters:
+ - **OpenAI Codex**
+ - **Claude OAuth**
+ - **GitHub Copilot**
+ - **Gemini CLI**
+ - **MiniMax**
+ - **Kimi Coding**
+ - **OpenCode Go**
+
+### Extension statuses
+
+Provided by other extensions; hidden with `showSkills: false`. Narrow terminals may shorten or omit them.
+
+Only one footer extension can be active. For plugin integration, see [VISION.md](VISION.md#plugin-integration).
 
 ## Development & design
 
@@ -103,7 +124,7 @@ Install from source:
 pi install git:github.com/Ryu-CZ/pi-minimal-footer
 ```
 
-See [VISION.md](VISION.md) for design constraints, local development, provider details, and verification limits. Release history: [CHANGELOG.md](CHANGELOG.md).
+Developer guide: [VISION.md](VISION.md). Release history: [CHANGELOG.md](CHANGELOG.md).
 
 ## Credits
 

package/VISION.md

@@ -38,11 +38,12 @@ The bar and reset label have no intervening space. Reset formatting uses local c
 
 ## Git contract
 
-- Pi supplies the branch name. Query `git rev-list --left-right --count HEAD...@{upstream}` for `↑N` local-only and `↓N` upstream-only commits. Use local refs; never fetch automatically.
+- Pi supplies the branch name. Query `git rev-list --left-right --count HEAD...@{upstream}` for `↑N` local-only and `↓N` upstream-only commits. Use local refs; no remote fetch by default.
 - Query outside rendering with a one-second timeout so Git cannot block the TUI. Missing upstreams and command failures omit counts.
-- Refresh on branch-change signals and footer state updates, plus every 91 seconds while the footer is active so external commits are noticed even when Pi is idle. `minFooter.gitRefreshSeconds` accepts positive integer seconds; invalid values fall back to 91. Local-only queries permit a shorter interval than subscription usage polling without network traffic. Stop the timer on footer disposal. Ignore older query results to prevent stale counts from restarting highlights.
-- Use the theme's normal text foreground while unsynced, otherwise dim. A count change bolds the arrows/counts until two subsequent user submissions; further changes restart the window. Tool turns and extension prompts do not consume it.
+- Refresh on branch-change signals and footer state updates, plus every 91 seconds while the footer is active so external commits are noticed even when Pi is idle. `minFooter.gitRefreshSeconds` accepts integer seconds from 1 through 2,147,483 (Node's maximum timer delay); invalid values fall back to 91. Local-only queries permit a shorter interval than subscription usage polling without network traffic. Stop the timer on footer disposal. Ignore older query results to prevent stale counts from restarting highlights.
+- Use the theme's normal text foreground while unsynced, otherwise dim. A count change pulses the whole Git section (icon, branch, and counts) bold for one second to call attention without persistent emphasis or turn-count bookkeeping; this is independent of synced/unsynced foreground color. Further changes restart the timer. Expiry requests a redraw even while idle. User submissions and tool turns do not affect the pulse. Dispose cancels the timer.
 - Initial loading and working-directory changes establish an unhighlighted baseline. Zero counts hide the arrows entirely.
+- `minFooter.gitFetch` (default `false`) opts into asynchronous `git fetch --quiet` on footer startup and every five minutes with ±⅛ jitter (262.5–337.5 seconds), sampled after each completed attempt. Jitter spreads network load across sessions; local divergence polling remains independent. Disable interactive credential prompts; failures are silent and retry at the next interval. `gitFetchTimeoutSeconds` accepts integer seconds from 1 through 2,147,483 (Node's maximum timer delay), default/fallback 17. Successful fetches refresh divergence. Footer disposal clears the timer and aborts an in-flight fetch; only interactive sessions with an active footer fetch.
 
 ## Subscription usage contract
 
@@ -79,7 +80,7 @@ The comparison with [mtrojnar/pi-usage](https://github.com/mtrojnar/pi-usage) in
 
 ## Local development
 
-Requires Node.js >=22.19.0. Tests currently use Pi 1.0.3 and mock provider requests.
+Requires Node.js >=22.19.0. Local dependencies pin Pi 1.0.3; compatibility CI tests Pi 1.0.3 and 1.1.0 on Node.js 22.19.0. Provider requests are mocked. These are tested versions, not a guarantee for every intervening or future release.
 
 ```bash
 npm ci
@@ -98,9 +99,23 @@ ln -s "$PWD/extensions" ~/.pi/agent/extensions/minimal-footer
 
 For a manual install, copy `extensions/*` into `~/.pi/agent/extensions/`.
 
+### Plugin integration
+
+Use Pi's standard status API to contribute text without replacing the footer:
+
+```typescript
+ctx.ui.setStatus("my-extension", "Working");
+ctx.ui.setStatus("my-extension", "Ready"); // update the same entry
+ctx.ui.setStatus("my-extension", undefined); // remove it
+```
+
+Use a unique key. Pi requests a redraw when statuses change; no footer-specific event is needed. `showSkills` controls status visibility. Narrow terminals may truncate or omit entries to preserve model/context and usage information.
+
+Footer ownership is exclusive: another extension calling `ctx.ui.setFooter()` replaces this footer. Usage requests, new Git queries, and footer-owned timers stop on disposal; an in-flight Git query may complete, but lifecycle state refreshes alone never start one.
+
 ### Code map
 
-- `extensions/index.ts`: settings, state refresh, layout, footer lifecycle, and `/minfooter`.
+- `extensions/index.ts`: settings, plain state updates, active-footer refresh gate, layout, footer lifecycle, and `/minfooter`.
 - `extensions/lib/usage-limits.ts`: usage refresh, cache, cancellation, and bar/reset rendering.
 - `extensions/lib/usage-providers.ts`: authentication, endpoint selection, and response normalization.
 - `tests/`: lifecycle/layout regressions, Git highlighting with a temporary repository, and usage parsing tests.

package/extensions/index.ts

@@ -33,6 +33,8 @@ interface Settings {
     showContext?: boolean;
     powerlineSeparator?: boolean;
     gitRefreshSeconds?: number;
+    gitFetch?: boolean;
+    gitFetchTimeoutSeconds?: number;
     maxUsageBarCells?: number;
   };
 }
@@ -40,6 +42,8 @@ interface Settings {
 type FooterSettings = NonNullable<Settings["minFooter"]>;
 
 const execFileAsync = promisify(execFile);
+// Node clamps timer delays above this signed 32-bit millisecond limit to 1ms.
+const MAX_TIMER_SECONDS = Math.floor(2_147_483_647 / 1000);
 
 const DEFAULT_SETTINGS: FooterSettings = {
   enabled: true,
@@ -50,6 +54,8 @@ const DEFAULT_SETTINGS: FooterSettings = {
   showContext: true,
   powerlineSeparator: true,
   gitRefreshSeconds: 91,
+  gitFetch: false,
+  gitFetchTimeoutSeconds: 17,
   maxUsageBarCells: MAX_BAR_CELLS,
 };
 
@@ -83,9 +89,12 @@ function writeSettings(patch: Partial<Settings>): void {
 function readConfig(): FooterSettings {
   const s = readSettings();
   const config = { ...DEFAULT_SETTINGS, ...s.minFooter };
-  if (typeof config.gitRefreshSeconds !== "number" || !Number.isSafeInteger(config.gitRefreshSeconds) || config.gitRefreshSeconds < 1) {
+  if (typeof config.gitRefreshSeconds !== "number" || !Number.isSafeInteger(config.gitRefreshSeconds) || config.gitRefreshSeconds < 1 || config.gitRefreshSeconds > MAX_TIMER_SECONDS) {
     config.gitRefreshSeconds = 91;
   }
+  if (typeof config.gitFetchTimeoutSeconds !== "number" || !Number.isSafeInteger(config.gitFetchTimeoutSeconds) || config.gitFetchTimeoutSeconds < 1 || config.gitFetchTimeoutSeconds > MAX_TIMER_SECONDS) {
+    config.gitFetchTimeoutSeconds = 17;
+  }
   if (typeof config.maxUsageBarCells !== "number" || !Number.isSafeInteger(config.maxUsageBarCells) || config.maxUsageBarCells < 1) {
     config.maxUsageBarCells = MAX_BAR_CELLS;
   }
@@ -122,7 +131,7 @@ interface FooterState {
   context: string;
   gitSync: string;
   gitInitialized: boolean;
-  gitHighlightInputs: number;
+  gitHighlighted: boolean;
   gitRequest: number;
 }
 
@@ -145,15 +154,16 @@ async function getGitSync(cwd: string): Promise<string> {
   }
 }
 
-async function updateGitSync(state: FooterState): Promise<void> {
+async function updateGitSync(state: FooterState): Promise<boolean> {
   const cwd = state.cwd;
   const request = ++state.gitRequest;
   const gitSync = await getGitSync(cwd);
   // Refresh events can overlap; an older result must not restart the highlight.
-  if (state.cwd !== cwd || request !== state.gitRequest) return;
-  if (state.gitInitialized && state.gitSync !== gitSync) state.gitHighlightInputs = 2;
+  if (state.cwd !== cwd || request !== state.gitRequest) return false;
+  const changed = state.gitInitialized && state.gitSync !== gitSync;
   state.gitSync = gitSync;
   state.gitInitialized = true;
+  return changed;
 }
 
 function updateState(ctx: ExtensionContext, state: FooterState): void {
@@ -161,7 +171,7 @@ function updateState(ctx: ExtensionContext, state: FooterState): void {
   if (state.cwd !== cwd) {
     state.gitSync = "";
     state.gitInitialized = false;
-    state.gitHighlightInputs = 0;
+    state.gitHighlighted = false;
   }
   state.cwd = cwd;
   state.model = ctx.model?.id ?? "no-model";
@@ -254,11 +264,27 @@ export default function (pi: ExtensionAPI) {
   let enabled = config.enabled !== false;
   const state: FooterState = {
     cwd: process.cwd(), model: "no-model", context: "?", gitSync: "",
-    gitInitialized: false, gitHighlightInputs: 0, gitRequest: 0,
+    gitInitialized: false, gitHighlighted: false, gitRequest: 0,
   };
   let requestRender: (() => void) | null = null;
   let disposeFooter: (() => void) | null = null;
   const usageLimits = new UsageLimits(() => requestRender?.());
+  let gitPulseTimer: ReturnType<typeof setTimeout> | null = null;
+
+  // Pulse the whole section for one second to call attention without persistent emphasis
+  // or turn-count bookkeeping; foreground color independently shows sync state.
+  // Design contract: VISION.md#git-contract.
+  async function refreshGit(): Promise<void> {
+    if (!await updateGitSync(state) || disposeFooter === null) return;
+    if (gitPulseTimer) clearTimeout(gitPulseTimer);
+    state.gitHighlighted = true;
+    gitPulseTimer = setTimeout(() => {
+      gitPulseTimer = null;
+      state.gitHighlighted = false;
+      requestRender?.();
+    }, 1000);
+    gitPulseTimer.unref?.();
+  }
 
   function selectUsage(ctx: ExtensionContext): void {
     // The preference may remain enabled after another extension replaces our footer.
@@ -281,7 +307,7 @@ export default function (pi: ExtensionAPI) {
       // Branch changes are Pi's invalidation signal; refresh the async Git
       // divergence separately because footer rendering must remain synchronous.
       const unsub = footerData.onBranchChange(() => {
-        void updateGitSync(state).then(() => tui.requestRender());
+        void refreshGit().then(() => tui.requestRender());
         tui.requestRender();
       });
       const request = () => tui.requestRender();
@@ -295,22 +321,61 @@ export default function (pi: ExtensionAPI) {
         if (disposed) return;
         gitTimer = setTimeout(() => {
           gitTimer = null;
-          void updateGitSync(state).then(() => tui.requestRender()).finally(scheduleGitRefresh);
+          void refreshGit().then(() => tui.requestRender()).finally(scheduleGitRefresh);
         }, gitRefreshMs);
         // Do not keep a non-interactive process alive solely for footer refresh.
         gitTimer.unref?.();
       };
       scheduleGitRefresh();
+      let fetchTimer: ReturnType<typeof setTimeout> | null = null;
+      let fetchController: AbortController | null = null;
+      const fetchTimeoutMs = (config.gitFetchTimeoutSeconds ?? 17) * 1000;
+      const fetchGit = async () => {
+        if (disposed) return;
+        const cwd = state.cwd;
+        fetchController = new AbortController();
+        try {
+          // Never prompt for credentials in a background job. Jitter spreads
+          // network requests from concurrent Pi sessions; local polling stays independent.
+          await execFileAsync("git", ["-C", cwd, "fetch", "--quiet"], {
+            timeout: fetchTimeoutMs,
+            signal: fetchController.signal,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" },
+          });
+          if (!disposed && state.cwd === cwd) {
+            await refreshGit();
+            if (!disposed) tui.requestRender();
+          }
+        } catch {
+          // Offline, authentication, timeout and cancellation failures are silent.
+        } finally {
+          fetchController = null;
+          if (!disposed) {
+            fetchTimer = setTimeout(() => {
+              fetchTimer = null;
+              void fetchGit();
+            }, 5 * 60 * 1000 * (1 + (Math.random() * 2 - 1) / 8));
+            fetchTimer.unref?.();
+          }
+        }
+      };
+      if (config.gitFetch === true) void fetchGit();
       const dispose = () => {
         if (disposed) return;
         disposed = true;
         unsub();
         if (gitTimer) clearTimeout(gitTimer);
         gitTimer = null;
+        if (fetchTimer) clearTimeout(fetchTimer);
+        fetchTimer = null;
+        fetchController?.abort();
         // A superseded renderer must not stop its replacement's usage polling.
         if (requestRender === request) {
           requestRender = null;
           usageLimits.stop();
+          if (gitPulseTimer) clearTimeout(gitPulseTimer);
+          gitPulseTimer = null;
+          state.gitHighlighted = false;
         }
         if (disposeFooter === dispose) disposeFooter = null;
       };
@@ -322,15 +387,15 @@ export default function (pi: ExtensionAPI) {
             ? [...footerData.getExtensionStatuses().values()].filter((s) => s.trim())
             : [];
           const branch = config.showGitBranch ? footerData.getGitBranch() : null;
-          const syncText = state.gitHighlightInputs > 0 ? theme.bold(state.gitSync) : state.gitSync;
-          const branchText = branch ? `${branch}${syncText}` : "";
+          const branchText = branch ? ` ${branch}${state.gitSync}` : "";
+          const gitText = state.gitHighlighted ? theme.bold(branchText) : branchText;
           const statusSeparator = config.powerlineSeparator ? theme.fg("dim", "  ") : " ";
           const line = buildLine(
             width,
             config.showPath ? theme.fg("dim", abbreviateHome(state.cwd, homedir())) : "",
             statuses.length ? statusSeparator + statuses.map((status) => theme.fg("dim", status)).join(statusSeparator) : "",
-            // Keep unsynced branches readable; bold counts separately mark recent changes.
-            branchText ? theme.fg(state.gitSync ? "text" : "dim", ` ${branchText}`) : "",
+            // Pulse weight independently of the existing divergence color.
+            branchText ? theme.fg(state.gitSync ? "text" : "dim", gitText) : "",
             config.showModel ? theme.bold(state.model) : "",
             config.showContext ? theme.fg("dim", theme.bold(state.context)) : "",
             (available, maxCells = BASE_BAR_CELLS) => usageLimits.line(available, theme, maxCells),
@@ -347,25 +412,28 @@ export default function (pi: ExtensionAPI) {
     selectUsage(ctx);
   }
 
-  /** Cheap refresh: update plain state and request one render. */
+  /** Gate active work on a live footer so passive state updates cannot resurrect hidden Git queries. */
+  function refreshFooter(): void {
+    if (disposeFooter === null) return;
+    void refreshGit().then(() => requestRender?.());
+    requestRender?.();
+  }
+
   function refresh(ctx: ExtensionContext): void {
     updateState(ctx, state);
-    void updateGitSync(state).then(() => requestRender?.());
-    requestRender?.();
+    refreshFooter();
   }
 
   // ── Lifecycle events (passive; no footer re-install) ────────────────
 
   pi.on("session_start", async (_event, ctx) => {
     usageLimits.stop();
-    refresh(ctx);
+    updateState(ctx, state);
     install(ctx);
+    refreshFooter();
   });
 
-  // Count user submissions, not turn_end: one prompt can trigger many tool turns.
-  // Extension-generated prompts do not consume the user's highlight window.
-  pi.on("input", (event, ctx) => {
-    if (event.source !== "extension" && state.gitHighlightInputs > 0) state.gitHighlightInputs--;
+  pi.on("input", (_event, ctx) => {
     refresh(ctx);
   });
 
@@ -412,8 +480,9 @@ export default function (pi: ExtensionAPI) {
       else if (args === "off") enabled = false;
       else enabled = !enabled;
       writeEnabled(enabled);
-      refresh(ctx);
+      updateState(ctx, state);
       install(ctx);
+      refreshFooter();
       ctx.ui.notify(`Minimal footer ${enabled ? "enabled" : "disabled"}`, "info");
     },
   });

package/package.json

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