@cad0p/pi-usage 0.11.3 → 0.11.4

package/extensions/quota-panel.ts

@@ -1,7 +1,8 @@
 /**
  * Pi quota line — read-only quota for the providers Pi already owns.
  *
- * Surface: nothing at session start. /usage box, /usage line or /usage panel pins
+ * Surface: nothing at session start. Bare /usage shows the panel until the next
+ * prompt or a second /usage. /usage box, /usage line or /usage panel pins
  * a surface above the editor, /usage status enables the footer, and /usage hide
  * removes it. No timer or post-turn refresh runs until a surface is on.
  *
@@ -69,12 +70,49 @@ type QuotaProvider = {
   expiresInMin: number | null;
 };
 
+type LocalModelUsage = {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheCreationInputTokens?: number;
+};
+
+type LocalAccountStats = {
+  todayTokens?: number;
+  weekTokens?: number;
+  todayPrompts?: number;
+  totalPrompts?: number;
+  totalTokens?: number;
+};
+
+/**
+ * Pi's own token counts for one family, computed by the CLI from the session
+ * files. It only ever holds aggregate counts: no prompt text, no identities.
+ */
+type LocalFamilyStats = {
+  hasLocalStats?: boolean;
+  todayPrompts?: number;
+  todaySessions?: number;
+  todayTotalTokens?: number;
+  todayTokensByModel?: Record<string, number>;
+  weekTokensByModel?: Record<string, number>;
+  recentDays?: Array<{ date: string; messageCount: number }>;
+  totalPrompts?: number;
+  totalSessions?: number;
+  activeDays?: number;
+  activeDates?: string[];
+  modelUsage?: Record<string, LocalModelUsage>;
+  byAccount?: Record<string, LocalAccountStats>;
+};
+
 type QuotaReport = {
   providers: QuotaProvider[];
   generatedAt: string;
   sources: string[];
   warnings: string[];
   byFamily: Record<string, QuotaProvider[]>;
+  localStats?: Record<string, LocalFamilyStats>;
+  localStatsMeta?: { partial?: boolean } | null;
 };
 
 type Theme = {
@@ -550,6 +588,89 @@ function summarize(report: QuotaReport): string {
     .join(" · ");
 }
 
+/** Window names for the one-line account rows (same words as the Omarchy panel). */
+const WINDOW_TAG: Record<string, string> = { "5h": "session", weekly: "week", monthly: "month" };
+
+/** A reset countdown in its largest unit, so a row of three stays narrow. */
+function shortDuration(seconds: number | null): string {
+  if (seconds === null || !Number.isFinite(seconds)) return "";
+  if (seconds <= 0) return "now";
+  if (seconds >= 86400) return `${Math.floor(seconds / 86400)}d`;
+  if (seconds >= 3600) return `${Math.floor(seconds / 3600)}h`;
+  return `${Math.max(1, Math.floor(seconds / 60))}m`;
+}
+
+/** Token counts stay readable in a widget: 812, 4.1k, 1.2M. */
+function formatTokens(value: number): string {
+  const tokens = Math.max(0, Math.round(Number(value) || 0));
+  if (tokens < 1_000) return String(tokens);
+  if (tokens < 100_000) return `${(tokens / 1_000).toFixed(1)}k`;
+  if (tokens < 1_000_000) return `${Math.round(tokens / 1_000)}k`;
+  if (tokens < 1_000_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`;
+  return `${(tokens / 1_000_000_000).toFixed(1)}B`;
+}
+
+/** Model ids are long and provider-prefixed; the panel only needs the tail. */
+function shortModelName(name: string): string {
+  const text = String(name ?? "");
+  const tail = text.split("/").pop() || text;
+  return tail.length <= 22 ? tail : `${tail.slice(0, 21)}…`;
+}
+
+/**
+ * The heaviest models of the last seven days, plus how many were left out.
+ * The all-time buckets are the fallback for a report from a CLI that predates
+ * the weekly breakdown, and for a week with no usage at all.
+ */
+function topModels(usage: Record<string, LocalModelUsage> | undefined, weekUsage: Record<string, number> | undefined, limit: number) {
+  const byName = (a: { name: string; total: number }, b: { name: string; total: number }) =>
+    b.total - a.total || a.name.localeCompare(b.name);
+  const weekRows = Object.entries(weekUsage ?? {})
+    .map(([name, total]) => ({ name, total: Number(total) || 0 }))
+    .filter((row) => row.total > 0)
+    .sort(byName);
+  const rows = weekRows.length > 0
+    ? weekRows
+    : Object.entries(usage ?? {})
+        .map(([name, bucket]) => ({
+          name,
+          total:
+            (Number(bucket?.inputTokens) || 0) +
+            (Number(bucket?.outputTokens) || 0) +
+            (Number(bucket?.cacheReadInputTokens) || 0) +
+            (Number(bucket?.cacheCreationInputTokens) || 0),
+        }))
+        .sort(byName);
+  return { rows: rows.slice(0, limit), more: Math.max(0, rows.length - limit) };
+}
+
+/**
+ * The token section of one provider: today and the last seven days, then the
+ * models that account for that usage. Two lines at most, aligned with the
+ * window rows above it.
+ */
+function renderTokenRows(stats: LocalFamilyStats | undefined, labelWidth: number, theme: Theme, partial = false): string[] {
+  if (!stats || stats.hasLocalStats === false) return [];
+  const week = (stats.recentDays ?? []).reduce((sum, day) => sum + (Number(day?.messageCount) || 0), 0);
+  const today = Number(stats.todayTotalTokens) || 0;
+  const prompts = Number(stats.todayPrompts) || 0;
+  const parts = [
+    `${theme.fg("dim", "today")} ${formatTokens(today)}`,
+    `${theme.fg("dim", "7d")} ${formatTokens(week)}`,
+  ];
+  if (prompts > 0) parts.push(theme.fg("dim", `${prompts} prompt${prompts === 1 ? "" : "s"}`));
+  if (partial) parts.push(theme.fg("warning", "scan partial"));
+  const lines = [`  ${theme.fg("dim", "tokens".padEnd(labelWidth))}  ${parts.join(theme.fg("dim", " · "))}`];
+
+  const { rows, more } = topModels(stats.modelUsage, stats.weekTokensByModel, 3);
+  if (rows.length > 0) {
+    const cells = rows.map((row) => `${shortModelName(row.name)} ${formatTokens(row.total)}`);
+    if (more > 0) cells.push(theme.fg("dim", `+${more} more`));
+    lines.push(`  ${" ".repeat(labelWidth)}  ${cells.join(theme.fg("dim", " · "))}`);
+  }
+  return lines;
+}
+
 /** The account's fullest window: the one that stops its next prompt. */
 function bindingWindow(provider: QuotaProvider): QuotaWindow | null {
   let best: QuotaWindow | null = null;
@@ -579,8 +700,10 @@ function isMultiAccount(providers: QuotaProvider[], provider: QuotaProvider): bo
 /**
  * One family, many accounts: a header plus one line per account with only its
  * binding window, so fourteen keys stay fourteen lines instead of fifty-six.
+ * Each line carries the account's own tokens for today, because on a
+ * fourteen-key provider "which key burned today's quota" is the question.
  */
-function renderAccountRows(accounts: QuotaProvider[], theme: Theme): string[] {
+function renderAccountRows(accounts: QuotaProvider[], theme: Theme, stats?: LocalFamilyStats): string[] {
   const family = accounts[0].family;
   const healthy = accounts.filter((account) => account.ok).length;
   const header = `${paint(BRAND[family] ?? "#8B949E", SHORT_NAME[family] ?? accounts[0].label)} ${theme.fg("dim", `· ${healthy} of ${accounts.length} accounts ok`)}`;
@@ -600,13 +723,19 @@ function renderAccountRows(accounts: QuotaProvider[], theme: Theme): string[] {
       lines.push(`  ${label}  ${theme.fg("dim", "no rate-limit windows reported")}`);
       continue;
     }
+    // Every window on one line, each in its own band colour; the leading glyph
+    // is the fullest window's, so the column still sorts the accounts by eye.
     const band = bandFor(used);
-    const reset = window.resetsInSec === null ? "" : theme.fg("dim", ` · reset in ${humanDuration(window.resetsInSec)}`);
-    lines.push(
-      `  ${label}  ${paint(band.color, band.glyph)} ${paint(band.color, bar(used))} ` +
-        `${paint(band.color, `${used.toFixed(used < 10 ? 1 : 0)}%`.padStart(5))} ` +
-        `${theme.fg("dim", window.id)}${reset}`,
-    );
+    const cells = account.windows
+      .filter((each) => usedOf(each) !== null)
+      .map((each) => {
+        const pct = usedOf(each) as number;
+        const reset = each.resetsInSec === null ? "" : ` ${theme.fg("dim", `(${shortDuration(each.resetsInSec)})`.padEnd(5))}`;
+        return `${theme.fg("dim", WINDOW_TAG[each.id] ?? each.id)} ${paint(bandFor(pct).color, `${Math.round(pct)}%`.padStart(4))}${reset}`;
+      });
+    const today = Number(stats?.byAccount?.[account.account]?.todayTokens) || 0;
+    const tokens = today > 0 ? ` · ${formatTokens(today)} today` : "";
+    lines.push(`  ${label}  ${paint(band.color, band.glyph)} ${cells.join(theme.fg("dim", " · "))}${theme.fg("dim", tokens)}`);
   }
   return lines;
 }
@@ -617,11 +746,15 @@ function renderPanel(report: QuotaReport, theme: Theme): string[] {
   const unconfigured = report.providers.filter((provider) => provider.notConfigured === true);
   const renderedFamilies = new Set<string>();
 
+  const partialScan = report.localStatsMeta?.partial === true;
   for (const provider of active) {
+    const localStats = report.localStats?.[provider.family];
+    const labelWidth = Math.max(6, ...provider.windows.map((window) => String(window.label ?? "").length));
     if (isMultiAccount(active, provider)) {
       if (renderedFamilies.has(provider.family)) continue;
       renderedFamilies.add(provider.family);
-      lines.push(...renderAccountRows(active.filter((other) => other.family === provider.family), theme));
+      lines.push(...renderAccountRows(active.filter((other) => other.family === provider.family), theme, localStats));
+      lines.push(...renderTokenRows(localStats, labelWidth, theme, partialScan));
       continue;
     }
     const name = paint(BRAND[provider.family] ?? "#8B949E", provider.label);
@@ -644,30 +777,31 @@ function renderPanel(report: QuotaReport, theme: Theme): string[] {
       const color = kind === "transient" || kind === "throttle" ? "warning" : kind === "expired" || kind === "auth" ? "error" : "dim";
       lines.push(`  ${theme.fg(color, glyph)} ${theme.fg("warning", provider.note ?? errorCaption(provider.error))}`);
       if (isRecoverableError(provider.error) && provider.note) lines.push(`  ${theme.fg("warning", provider.note)}`);
-      continue;
-    }
-    if (provider.note) lines.push(`  ${theme.fg("warning", `~ ${provider.note}`)}`);
-    if (provider.windows.length === 0) {
+    } else if (provider.windows.length === 0) {
+      if (provider.note) lines.push(`  ${theme.fg("warning", `~ ${provider.note}`)}`);
       lines.push(`  ${theme.fg("dim", "no rate-limit windows reported")}`);
-      continue;
-    }
-
-    const width = Math.max(...provider.windows.map((window) => window.label.length));
-    for (const window of provider.windows) {
-      const used = usedOf(window);
-      const label = theme.fg("dim", window.label.padEnd(width));
-      if (used === null) {
-        lines.push(`  ${label}  ${theme.fg("dim", window.note ?? "no percentage reported")}`);
-        continue;
+    } else {
+      if (provider.note) lines.push(`  ${theme.fg("warning", `~ ${provider.note}`)}`);
+      for (const window of provider.windows) {
+        const used = usedOf(window);
+        const label = theme.fg("dim", window.label.padEnd(labelWidth));
+        if (used === null) {
+          lines.push(`  ${label}  ${theme.fg("dim", window.note ?? "no percentage reported")}`);
+          continue;
+        }
+        const band = bandFor(used);
+        const reset = window.resetsInSec === null ? "" : theme.fg("dim", ` · reset in ${humanDuration(window.resetsInSec)}`);
+        lines.push(
+          `  ${label}  ${paint(band.color, band.glyph)} ${paint(band.color, bar(used))} ` +
+            `${paint(band.color, `${used.toFixed(used < 10 ? 1 : 0)}%`.padStart(5))} ` +
+            `${theme.fg("dim", "used")}${reset}`,
+        );
       }
-      const band = bandFor(used);
-      const reset = window.resetsInSec === null ? "" : theme.fg("dim", ` · reset in ${humanDuration(window.resetsInSec)}`);
-      lines.push(
-        `  ${label}  ${paint(band.color, band.glyph)} ${paint(band.color, bar(used))} ` +
-          `${paint(band.color, `${used.toFixed(used < 10 ? 1 : 0)}%`.padStart(5))} ` +
-          `${theme.fg("dim", "used")}${reset}`,
-      );
     }
+
+    // Local token stats survive a failed quota probe: the credential may be
+    // rejected while the tokens already burned are still a fact on disk.
+    lines.push(...renderTokenRows(localStats, labelWidth, theme, partialScan));
   }
   lines.push(theme.fg("dim", `used % · read-only · ${report.generatedAt}`));
   if (unconfigured.length > 0) {
@@ -686,6 +820,11 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
   let timer: ReturnType<typeof setInterval> | null = null;
   let agentEndTimer: ReturnType<typeof setTimeout> | null = null;
   let panelVisible = false;
+  /**
+   * The panel bare `/usage` opens is a glance, not a pin: it goes away when the
+   * next prompt starts or when `/usage` is run again. `/usage panel` pins it.
+   */
+  let transientPanel = false;
   /**
    * Nothing is pinned by default. A box or line above the editor is a persistent
    * surface, and a quota command should not claim a row until asked.
@@ -933,7 +1072,17 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
     paintUi(ui);
   });
 
-  pi.on("agent_start", () => {
+  function dismissTransientPanel(ui: UiContext): void {
+    panelVisible = false;
+    transientPanel = false;
+    if (!surfaceActive()) stopPolling();
+    paintUi(ui);
+  }
+
+  pi.on("agent_start", (_event, ctx) => {
+    // SAFETY: Pi's agent_start context implements UiContext when hasUI is true.
+    const ui = ctx as unknown as UiContext;
+    if (transientPanel && panelVisible && ui?.hasUI && !disposed) dismissTransientPanel(ui);
     if (agentEndTimer) {
       clearTimeout(agentEndTimer);
       agentEndTimer = null;
@@ -1002,6 +1151,7 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
         return;
       case "panel":
         panelVisible = true;
+        transientPanel = false;
         lineVisible = false;
         boxVisible = false;
         explicitBox = false;
@@ -1048,8 +1198,15 @@ export default function quotaPanelExtension(pi: ExtensionAPI): void {
         break;
     }
 
+    // Bare /usage again while its glance is open closes it.
+    if (panelVisible && transientPanel) {
+      dismissTransientPanel(ctx);
+      return;
+    }
+
     // Bare /usage: one on-demand refresh, show the panel, report the percentages.
     panelVisible = true;
+    transientPanel = true;
     lineVisible = false;
     boxVisible = false;
     await refresh(ctx, true);

package/omarchy/cad0p.pi-usage/Agent.qml

@@ -0,0 +1,33 @@
+import QtQuick
+import Quickshell.Io
+
+// One usage record, read straight off its data file. Carried over unchanged
+// from Omarchy's built-in Agents plugin (plugins/agents/Agent.qml, MIT): a
+// record that appears in the usage directory is a provider, whoever wrote it.
+Item {
+  id: root
+  visible: false
+
+  property string agentId: ""
+  property string path: ""
+  property var record: null
+
+  FileView {
+    path: root.path
+    watchChanges: true
+    printErrors: false
+    onFileChanged: reload()
+    onLoaded: root.parse(text())
+    onLoadFailed: root.record = null
+  }
+
+  function parse(content) {
+    try {
+      var parsed = JSON.parse(String(content || ""))
+      root.record = parsed && typeof parsed === "object" ? parsed : null
+    } catch (e) {
+      console.warn("cad0p.pi-usage", "Ignoring bad usage record", root.path, e)
+      root.record = null
+    }
+  }
+}

package/omarchy/cad0p.pi-usage/Main.qml

@@ -0,0 +1,333 @@
+import QtQuick
+import Quickshell
+import Quickshell.Io
+import "UsageLogic.js" as Logic
+
+// The data side of the AI Usage panel: discover every usage record in
+// Omarchy's usage directory (pi-usage's pi-*.json and Omarchy's own
+// claude/codex/fireworks records alike), watch them, keep the per-section
+// expansion state, and trigger the publishers on demand.
+//
+// Discovery and the per-record watcher follow Omarchy's built-in Agents plugin
+// (plugins/agents/Main.qml, MIT, by Omarchy).
+Item {
+  id: root
+  visible: false
+
+  property var settings: ({})
+  // Live bar, used only to see whether the built-in Agents widget is also on
+  // it (see collectorsWanted).
+  property QtObject bar: null
+  // file:// URL of the plugin directory, so the panel can find the pi-usage
+  // CLI of the package it ships in.
+  property string pluginDir: ""
+
+  readonly property string home: Quickshell.env("HOME") || ""
+  readonly property string stateHome: Quickshell.env("XDG_STATE_HOME") || (home + "/.local/state")
+  // PI_QUOTA_OMARCHY_DIR is the writer's own override; honoring it here keeps
+  // the two ends pointed at the same directory.
+  readonly property string usageDir: Quickshell.env("PI_QUOTA_OMARCHY_DIR") || (stateHome + "/omarchy/agents/usage")
+  readonly property string uiStateDir: Logic.uiStateDirectory(stateHome, Quickshell.env("PI_USAGE_PANEL_STATE_DIR"))
+  readonly property string uiStatePath: uiStateDir + "/cad0p.pi-usage.json"
+
+  function setting(name, fallback) {
+    var value = settings ? settings[name] : undefined
+    return value === undefined || value === null ? fallback : value
+  }
+
+  // ------------------------------------------------------------- discovery
+
+  property var recordIds: []
+  property var agents: []
+  property int dataRevision: 0
+
+  Process {
+    id: listProcess
+    running: false
+    command: ["find", root.usageDir, "-maxdepth", "1", "-name", "*.json", "-printf", "%f\n"]
+
+    stdout: StdioCollector {
+      waitForEnd: true
+      onStreamFinished: root.applyListing(text)
+    }
+  }
+
+  // New records are found by listing the directory again on a slow timer and
+  // after every publisher run; each record's content is watched by its own
+  // FileView, which is what actually moves the numbers.
+  Timer {
+    interval: 60000
+    running: true
+    repeat: true
+    triggeredOnStart: true
+    onTriggered: root.rescan()
+  }
+
+  function rescan() {
+    if (!listProcess.running) listProcess.running = true
+  }
+
+  function applyListing(output) {
+    var ids = []
+    var lines = String(output || "").split("\n")
+    for (var i = 0; i < lines.length; i++) {
+      var name = lines[i].trim()
+      if (name.slice(-5) === ".json") ids.push(name.slice(0, -5))
+    }
+    ids.sort()
+    if (JSON.stringify(ids) !== JSON.stringify(recordIds)) recordIds = ids
+  }
+
+  Instantiator {
+    id: agentInstantiator
+    model: root.recordIds
+
+    delegate: Agent {
+      required property var modelData
+      agentId: modelData
+      path: root.usageDir + "/" + modelData + ".json"
+      onRecordChanged: root.recordsChanged()
+    }
+
+    onObjectAdded: (index, object) => root.rebuildAgents()
+    onObjectRemoved: (index, object) => root.rebuildAgents()
+  }
+
+  function rebuildAgents() {
+    var result = []
+    for (var i = 0; i < agentInstantiator.count; i++) {
+      var agent = agentInstantiator.objectAt(i)
+      if (agent) result.push(agent)
+    }
+    agents = result
+    recordsChanged()
+  }
+
+  function recordsChanged() {
+    dataRevision++
+    scheduleLimitsRetry()
+  }
+
+  property var retryAgentIds: []
+  property string pendingUpdateKind: ""
+  property bool pendingPublisher: false
+
+  Timer {
+    id: limitsRetry
+    interval: 30000
+    repeat: false
+    // A retry is a collector run like any other: the same switch that gates the
+    // interval timer gates this one, even if it flips while the retry waits.
+    onTriggered: if (root.collectorsWanted) root.runCollectors("limits", root.retryAgentIds)
+  }
+
+  function scheduleLimitsRetry() {
+    var records = []
+    for (var i = 0; i < agents.length; i++) {
+      var record = agents[i] ? agents[i].record : null
+      if (record) records.push(record)
+    }
+    retryAgentIds = Logic.advisedRetryIds(records, settings, collectorsWanted)
+    if (retryAgentIds.length > 0) limitsRetry.restart()
+    else limitsRetry.stop()
+  }
+
+  // Turning the collectors off (or putting the built-in widget back on the
+  // bar) cancels a retry that is already waiting.
+  onCollectorsWantedChanged: scheduleLimitsRetry()
+
+  readonly property var providers: {
+    var rev = dataRevision
+    var records = []
+    for (var i = 0; i < agents.length; i++) if (agents[i] && agents[i].record) records.push(agents[i].record)
+    return Logic.visibleProviders(records, settings)
+  }
+
+  readonly property string newestUpdate: {
+    var rev = dataRevision
+    var best = ""
+    for (var i = 0; i < agents.length; i++) {
+      var record = agents[i] ? agents[i].record : null
+      var at = record && record.updatedAt ? String(record.updatedAt) : ""
+      if (at !== "" && (best === "" || new Date(at).getTime() > new Date(best).getTime())) best = at
+    }
+    return best
+  }
+
+  // ------------------------------------------------------------ expansion
+
+  property var expandedOverrides: ({})
+
+  FileView {
+    id: uiStateFile
+    path: root.uiStatePath
+    watchChanges: false
+    atomicWrites: true
+    printErrors: false
+    onLoaded: root.expandedOverrides = Logic.parseUiState(text()).expanded
+  }
+
+  Process {
+    id: uiStateMkdir
+    running: false
+    command: ["mkdir", "-p", root.uiStateDir]
+    onExited: function(exitCode) {
+      if (exitCode === 0) uiStateFile.setText(Logic.serializeUiState({ expanded: root.expandedOverrides }))
+    }
+  }
+
+  Timer {
+    id: uiStateSave
+    interval: 400
+    repeat: false
+    onTriggered: if (!uiStateMkdir.running) uiStateMkdir.running = true
+  }
+
+  function setExpanded(id, expanded) {
+    expandedOverrides = Logic.withExpanded(expandedOverrides, String(id), expanded)
+    uiStateSave.restart()
+  }
+
+  // --------------------------------------------------------------- refresh
+  //
+  // pi-usage's records already have two writers: the systemd user timer
+  // (./install.sh --omarchy-timer) and the Pi extension on every quota
+  // refresh. A third periodic writer would only multiply the calls to the
+  // usage endpoints, so the panel never schedules piquota itself; it runs it
+  // when you ask for a refresh.
+  //
+  // Omarchy's own collectors are different: the built-in Agents widget is what
+  // runs them. "Auto" runs them here only while that widget is not on the bar,
+  // so replacing it keeps claude/codex/fireworks fresh and keeping both never
+  // doubles the work.
+
+  property string collectorsSetting: String(setting("omarchyCollectors", "Auto"))
+  property int refreshIntervalSec: Math.max(30, Number(setting("refreshIntervalSec", 900)))
+  property bool builtinOnBar: false
+  readonly property bool collectorsWanted: Logic.collectorsWanted(collectorsSetting, builtinOnBar)
+  readonly property bool refreshing: collectorProcess.running || publisherProcess.running
+
+  function updateBuiltinOnBar() {
+    var widgets = bar && typeof bar.moduleWidgets === "function" ? bar.moduleWidgets("omarchy.agents") : []
+    builtinOnBar = !!widgets && widgets.length > 0
+  }
+
+  Timer {
+    interval: root.refreshIntervalSec * 1000
+    running: root.collectorsSetting !== "Off"
+    repeat: true
+    triggeredOnStart: true
+    onTriggered: {
+      root.updateBuiltinOnBar()
+      if (root.collectorsWanted) root.runCollectors("normal")
+    }
+  }
+
+  Process {
+    id: collectorProcess
+    running: false
+    onExited: {
+      root.rescan()
+      if (root.pendingUpdateKind !== "") {
+        var kind = root.pendingUpdateKind
+        root.pendingUpdateKind = ""
+        root.runCollectors(kind)
+      }
+    }
+    stderr: StdioCollector {
+      waitForEnd: true
+      onStreamFinished: if (text.trim() !== "") console.warn("cad0p.pi-usage", text.trim())
+    }
+  }
+
+  function collectorCommand(kind, agentIds) {
+    var args = []
+    if (kind === "force") args.push("--force")
+    if (kind === "limits") args.push("--limits-only")
+    var providerSettings = settings && settings.providers ? settings.providers : {}
+    for (var id in providerSettings) {
+      if (id.indexOf("pi-") === 0) continue
+      if (providerSettings[id] && providerSettings[id].enabled === false) args.push("--except", id)
+    }
+    if (agentIds) {
+      for (var i = 0; i < agentIds.length; i++) args.push(agentIds[i])
+    }
+    // Absent on a machine without Omarchy's collectors: nothing to run.
+    return ["bash", "-c", "command -v omarchy-agent-usage-update >/dev/null 2>&1 || exit 0; exec omarchy-agent-usage-update \"$@\"", "omarchy-agent-usage-update"].concat(args)
+  }
+
+  function runCollectors(kind, agentIds) {
+    // The one choke point every collector run passes through: the interval
+    // timer, an explicit refresh and the retryAdvised retry.
+    if (!collectorsWanted) return
+    if (collectorProcess.running) {
+      pendingUpdateKind = Logic.queueUpdateKind(pendingUpdateKind, kind)
+      return
+    }
+    collectorProcess.command = collectorCommand(kind, agentIds)
+    collectorProcess.running = true
+  }
+
+  Process {
+    id: publisherProcess
+    running: false
+    onExited: {
+      root.rescan()
+      if (root.pendingPublisher) {
+        root.pendingPublisher = false
+        root.runPublisher()
+      }
+    }
+    stderr: StdioCollector {
+      waitForEnd: true
+      onStreamFinished: if (text.trim() !== "") console.warn("cad0p.pi-usage", text.trim())
+    }
+  }
+
+  function localPath(url) {
+    var text = String(url || "")
+    if (text.indexOf("file://") === 0) text = decodeURIComponent(text.slice(7))
+    return text.replace(/\/+$/, "")
+  }
+
+  // The user's timer unit first, so a manual refresh runs with exactly the
+  // environment the periodic one does (PI_QUOTA_CLAUDE_SOURCE and friends);
+  // then the CLI of the package this plugin ships in; then piquota on PATH.
+  function publisherCommand() {
+    var script = [
+      "if command -v systemctl >/dev/null 2>&1 && systemctl --user cat piquota-omarchy.service >/dev/null 2>&1; then",
+      "  exec systemctl --user start piquota-omarchy.service",
+      "fi",
+      "cli=\"$(readlink -f \"$1\" 2>/dev/null)/../../bin/piquota.js\"",
+      "if [ -f \"$cli\" ] && command -v node >/dev/null 2>&1; then exec node \"$cli\" omarchy; fi",
+      "if command -v piquota >/dev/null 2>&1; then exec piquota omarchy; fi",
+      "if [ -x \"$HOME/.local/bin/piquota\" ]; then exec \"$HOME/.local/bin/piquota\" omarchy; fi",
+      "exit 0"
+    ].join("\n")
+    return ["bash", "-c", script, "pi-usage-refresh", localPath(pluginDir)]
+  }
+
+  function runPublisher() {
+    if (publisherProcess.running) {
+      pendingPublisher = true
+      return
+    }
+    publisherProcess.command = publisherCommand()
+    publisherProcess.running = true
+  }
+
+  // r, middle click, IPC refresh: everything, now.
+  function refreshAll() {
+    updateBuiltinOnBar()
+    runPublisher()
+    if (collectorsWanted) runCollectors("force")
+  }
+
+  // Opening the panel wants the numbers that go stale on the wire; Omarchy's
+  // collectors reuse their recent transcript scans in this mode.
+  function refreshOnOpen() {
+    updateBuiltinOnBar()
+    rescan()
+    if (collectorsWanted) runCollectors("limits")
+  }
+}