quotacap 0.0.22 → 0.0.24

package/README.md

@@ -19,10 +19,11 @@ QuotaCap helps you get more from the AI coding subscriptions you already pay for
 | Provider | Mechanism | Source |
 |---|---|---|
 | Claude Code | `exec` — `claude -p /usage --output-format json` | Live |
-| Antigravity | `exec` — `agy -p /usage --output-format json` (two rows: `agy` Gemini, `agy:3p` 3p) | Live |
+| Antigravity | `exec` — `agy -p /usage --output-format json` (two rows: Antigravity for Gemini, Antigravity 3P for third-party models) | Live |
 | Codex | `pty` — `codex --no-alt-screen` then `/status`, parse `Weekly/5h limit: X% left` | Live |
 | Kimi Code | `pty` — `kimi` then `/usage`, parse `Weekly/5h limit: Y% used` | Live |
 | Grok | `pty` — `grok` then `/usage`, parse `Weekly limit (plan)` + `Credits: $X` | Live |
+| Muse Code | `pty` — `muse --trust-workspace` then `/usage`, parse `Subscription · Muse Code <plan>` + `Weekly/Current N% used` | Live |
 
 Exec adapters run via `execFile` with an argv list. PTY adapters run via `node-pty` (`src/adapters/pty.ts`). They are TUI-fragile: a vendor text change breaks the parser and the row degrades fail-closed until the regex is fixed. Poll latency is 2–10 s per PTY provider (settle plus completion). It dominates `POST /api/refresh` and the first poll, not the steady-state 15 m timer.
 
@@ -39,21 +40,22 @@ npm install -g quotacap
 ```
 
 The binary is a self-contained executable from GitHub Releases (shipped as `quotacap-<os>-<arch>.tar.gz` with a `pty` sidecar for Kimi/Codex/Grok); `install.sh` handles the tarball and sidecar transparently.
+One command takes you from zero to a running tracker: the installer verifies checksums, provisions config, registers the background login service, and opens the dashboard. Re-running it upgrades in place with no flags. Pass `--no-service` (foreground only) or `--no-open` (SSH sessions) to skip steps.
 The npm package runs the same CLI on Node. To run without a global install, replace `quotacap` with `npx quotacap` in any command, for example `npx quotacap web`.
 
 ## Quick start
 
 ```bash
-# Terminal 1: leave this running
-quotacap init                 # writes ~/.quotacap/config.json
-quotacap web                  # dashboard at http://localhost:8787
-
-# Terminal 2: after the dashboard table fills
-quotacap status
+quotacap            # opens the dashboard, starting the service if needed
+quotacap status     # summary table (pass --verbose for adapter failure guidance)
 quotacap advise
+quotacap update     # upgrade to the latest release
+quotacap providers list                    # view built-in and effective provider names
+quotacap providers rename claude "Work"    # customize provider display name
+quotacap providers reset claude            # restore built-in name (--all resets all)
 ```
 
-`web` stays in the foreground and starts the daemon.
+No setup ceremony: config is provisioned on first use, and bare `quotacap` is the dashboard launcher. `quotacap status --verbose` displays actionable remediation guidance and sanitized failure details for failing adapters. `status` remains strictly read-only and never triggers background polling. `quotacap providers` manages custom display names (persisted to `~/.quotacap/config.json` under `providerNames`). `quotacap web --foreground` and `quotacap daemon` keep the old hold-the-terminal mode for SSH, containers, and supervisors.
 
 ## MCP
 
@@ -80,6 +82,7 @@ The local web server listens on `127.0.0.1:8787` (configured via `QUOTACAP_URL`
 | `GET` | `/api/recommendation` | None | Current advisory on which provider to use next |
 | `GET` | `/api/token` | Same-origin | Shared secret token for the dashboard |
 | `POST` | `/api/refresh` | `X-QuotaCap-Token` | Trigger an immediate adapter poll (debounced to 60s) |
+| `PATCH` | `/api/providers/:id` | `X-QuotaCap-Token` | Set or clear custom provider display name override |
 
 ### Curl examples
 
@@ -96,11 +99,27 @@ curl -X POST http://localhost:8787/api/refresh \
   -H "X-QuotaCap-Token: $(cat ~/.quotacap/token)"
 ```
 
+Set or clear a provider display name override:
+
+```bash
+# Set custom display name
+curl -X PATCH http://localhost:8787/api/providers/claude \
+  -H "X-QuotaCap-Token: $(cat ~/.quotacap/token)" \
+  -H "Content-Type: application/json" \
+  -d '{"displayName": "Work Claude"}'
+
+# Reset to built-in name
+curl -X PATCH http://localhost:8787/api/providers/claude \
+  -H "X-QuotaCap-Token: $(cat ~/.quotacap/token)" \
+  -H "Content-Type: application/json" \
+  -d '{"displayName": null}'
+```
+
 ## Security
 
 QuotaCap is a local daemon. It binds to `127.0.0.1` only (`src/cli/index.ts:56`). It does not listen on `0.0.0.0`. There is no LAN surface.
 
-It owns no tokens. It never reads `~/.codex/auth.json`, `~/.kimi-code/credentials/kimi-code.json`, `~/.kimi/credentials/kimi-code.json`, `~/.grok/auth.json`, or `~/.gemini/oauth_creds.json`. It never uses `refresh_token` or `grant_type=refresh_token`. It has no hardcoded client ids. Those OAuth paths and the `.qc-bak` and `.qc-lock` helpers were removed in #14. This is asserted by `tests/adapters/credential-free.test.ts`. Each CLI owns its own session. QuotaCap only spawns the CLI and reads its stdout via `exec` (`claude`, `agy`) or PTY (`codex`, `kimi`, `grok`).
+It owns no tokens. It never reads `~/.codex/auth.json`, `~/.kimi-code/credentials/kimi-code.json`, `~/.kimi/credentials/kimi-code.json`, `~/.grok/auth.json`, or `~/.gemini/oauth_creds.json`. It never uses `refresh_token` or `grant_type=refresh_token`. It has no hardcoded client ids. Those OAuth paths and the `.qc-bak` and `.qc-lock` helpers were removed in #14. This is asserted by `tests/adapters/credential-free.test.ts`. Each CLI owns its own session. It never reads `~/.config/muse/auth.json`, `~/.local/share/muse/sessions/`, or `~/.config/muse/tui-history.jsonl`. Each CLI owns its own session. QuotaCap only spawns the CLI and reads its stdout via `exec` (`claude`, `agy`) or PTY (`codex`, `kimi`, `grok`, `muse`).
 
 It stores no `raw` provider payload. The `raw` column was dropped and migrated in `src/store/db.ts:37-48`. `GET /api/quotas` and MCP `get_quotas` never return `raw` (`tests/http/api.test.ts`). History and the token live under `~/.quotacap/` with `0700` on the directory and `0600` on files.
 
@@ -136,6 +155,8 @@ The same code is an npm package and a compiled binary.
 
 The Kimi adapter spawns `kimi` in your home directory so the quota modal does not depend on the project path. If Kimi shows `Trust this folder?`, QuotaCap fails closed with `untrusted workspace — run \`kimi\` there and select Trust this folder` and does not auto-trust; trust remains an explicit interactive decision.
 
+The Muse adapter never trusts a directory of yours. It runs `muse --trust-workspace` with its working directory set to an empty folder QuotaCap owns (`~/.quotacap/muse-probe/`), so the flag has no project-local skills, rules, hooks or plugin config to load, and Muse's own flag does not persist trust. If a future Muse ignores the flag and shows the prompt anyway, the adapter aborts fail-closed rather than answering it.
+
 The compiled binaries are built with `bun build --compile`.
 Each `dist-bin/quotacap-<os>-<arch>.tar.gz` bundles a `pty` sidecar.
 The sidecar is `pty/node-pty` with the matching prebuild.

package/dist/adapters/grok.js

@@ -10,7 +10,7 @@ const ABBR_MONTHS = {
     jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11,
 };
 function parseGrokReset(raw, now) {
-    const m = raw.trim().match(/^([A-Za-z]+)\s+(\d{1,2}),\s+(\d{1,2}):(\d{2})$/);
+    const m = raw.trim().match(/^([A-Za-z]+)\s+(\d{1,2}),\s*(\d{1,2}):(\d{2})$/);
     if (!m)
         return null;
     const monStr = m[1].toLowerCase();
@@ -73,7 +73,7 @@ export function parseGrokTui(text, now = new Date()) {
         if (Number.isFinite(v) && v >= 0)
             creditsUsd = v;
     }
-    const mReset = cleaned.match(/Resets:\s*([A-Za-z]+\s+\d+,\s+\d+:\d+)/i);
+    const mReset = cleaned.match(/Resets:\s*([A-Za-z]+\s+\d+,\s*\d+:\d+)/i);
     let resetsAt = null;
     let estimated = false;
     if (mReset) {

package/dist/adapters/index.js

@@ -4,6 +4,7 @@ import { codexAdapter } from "./codex.js";
 import { kimiAdapter } from "./kimi.js";
 import { grokAdapter } from "./grok.js";
 import { agyAdapter } from "./agy.js";
+import { museAdapter } from "./muse.js";
 import { installAdapterSignal, clearAdapterSignal } from "../runtime/spawn.js";
 export const adapters = {
     claude: claudeAdapter,
@@ -12,6 +13,7 @@ export const adapters = {
     kimi: kimiAdapter,
     grok: grokAdapter,
     agy: agyAdapter,
+    muse: museAdapter,
 };
 const ADAPTER_TIMEOUTS = {
     claude: 8000,
@@ -19,6 +21,7 @@ const ADAPTER_TIMEOUTS = {
     kimi: 8000,
     grok: 14000,
     agy: 20000,
+    muse: 14000,
 };
 export async function pollAll(enabled, opts) {
     const rawJobs = enabled.map(id => {

package/dist/adapters/muse.d.ts

@@ -0,0 +1,8 @@
+import type { ParsedQuota } from "./types.js";
+export declare function museProbeDir(): string;
+export declare function parseMuseTui(text: string, now?: Date): ParsedQuota;
+export declare const museAdapter: {
+    id: string;
+    requiresAuth: string;
+    poll(): Promise<ParsedQuota>;
+};

package/dist/adapters/muse.js

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseResetText } from "./parse.js";
+import { runPty, stripAnsi } from "./pty.js";
+import { adapterSignal } from "../runtime/spawn.js";
+// QuotaCap-owned empty probe dir, beside the config and database. Muse loads
+// project-local skills, rules, hooks and plugin config from cwd, so the probe
+// never runs in $HOME or a user project — an empty dir grants nothing.
+export function museProbeDir() {
+    return path.join(process.env.QUOTACAP_HOME ?? os.homedir(), ".quotacap", "muse-probe");
+}
+export function parseMuseTui(text, now = new Date()) {
+    // After ANSI stripping the panel is ONE line (cursor-addressed, no
+    // newlines), so no pattern here may anchor on ^, $ or \n.
+    const cleaned = stripAnsi(text);
+    const weekly = cleaned.match(/Weekly\s+(\d+)%\s+used/i);
+    if (!weekly)
+        throw new Error("muse: weekly usage not found in TUI output");
+    const current = cleaned.match(/Current\s+(\d+)%\s+used/i);
+    if (!current)
+        throw new Error("muse: current-window usage not found in TUI output");
+    const usedPct = parseInt(weekly[1], 10);
+    const sessionPct = parseInt(current[1], 10);
+    if (!Number.isFinite(usedPct) || usedPct < 0 || usedPct > 100)
+        throw new Error("muse: bad weekly pct");
+    if (!Number.isFinite(sessionPct) || sessionPct < 0 || sessionPct > 100)
+        throw new Error("muse: bad current pct");
+    // First match wins; overdrawn transcripts carry two identical copies.
+    // Vendor casing preserved (grok precedent: SuperGrok); the Muse Code
+    // product prefix is stripped because the product is already the row label.
+    let plan = "unknown";
+    const planMatch = cleaned.match(/Subscription\s*·\s*Muse Code\s+(.+?)\s{2,}/i);
+    if (planMatch)
+        plan = planMatch[1].trim();
+    // The Current-window reset ("Resets at 3:51 PM") is a bare clock time with
+    // no date, and Quota has no session-reset field — discarded, as claude and
+    // kimi already do. A missing or unparseable Weekly reset throws rather than
+    // estimating: an invented reset would feed the advisory a false deadline.
+    const resetMatch = cleaned.match(/Weekly[^\n]*?Resets\s+([A-Za-z]{3}\s+\d{1,2}\s+at\s+\d{1,2}:\d{2}\s*[AP]M)/i);
+    if (!resetMatch)
+        throw new Error("muse: bad weekly reset");
+    const resetRaw = resetMatch[1].trim();
+    const resetsAt = parseResetText(`resets ${resetRaw}`, now);
+    if (!resetsAt)
+        throw new Error(`muse: bad weekly reset "${resetRaw}"`);
+    const periodStart = new Date(new Date(resetsAt).getTime() - 7 * 86400000).toISOString();
+    return {
+        provider: "muse",
+        plan,
+        usedPct,
+        sessionPct,
+        resetsAt,
+        periodStart,
+        source: "tui",
+        fetchedAt: now.toISOString(),
+        raw: cleaned.slice(0, 4096),
+    };
+}
+export const museAdapter = {
+    id: "muse",
+    requiresAuth: "muse login (CLI owns credentials)",
+    async poll() {
+        const cwd = museProbeDir();
+        fs.mkdirSync(cwd, { recursive: true });
+        const transcript = await runPty({
+            file: "muse",
+            args: ["--trust-workspace"],
+            cwd,
+            // Without this, a missing binary triggers a foreground 248 MB download
+            // on every poll; with it the launcher dies fast with a clear message.
+            env: { MUSE_NO_AUTO_UPDATE: "1" },
+            cols: 140,
+            rows: 50,
+            readyRegex: /muse-spark|Muse Code \d/,
+            readyTimeoutMs: 8000,
+            settleDelayMs: 1000,
+            // Two-phase submit: "/usage" first, CR 1500ms later. A single combined
+            // write is swallowed by the slash-command autocomplete and never runs.
+            input: "/usage",
+            submitInput: "\r",
+            submitAfterMs: 1500,
+            completionRegex: /Subscription/i,
+            // Trust prompt (in case a future Muse ignores the flag), an accidental
+            // model turn from a mistimed Enter, and the unavailable-subscription
+            // fast-fail — every one aborts to a degraded row, never a 14s timeout.
+            abortOn: /Do you trust this workspace|Working \(\d+s|Subscriptions aren't currently available|subscription_unavailable/,
+            timeoutMs: 14000,
+            respondToQueries: true,
+            maxBytes: 256 * 1024,
+            signal: adapterSignal("muse"),
+            label: "muse",
+        });
+        return parseMuseTui(transcript);
+    },
+};

package/dist/adapters/pty.d.ts

@@ -8,8 +8,26 @@ export interface PtyRunOptions {
     rows?: number;
     readyRegex?: RegExp;
     readyTimeoutMs?: number;
+    /**
+     * Settle delay after spawn (no readyRegex) or after readiness (with
+     * readyRegex). The post-ready default stays 200ms; pass an explicit value
+     * (e.g. muse's 1000ms) only when the TUI needs longer after signalling.
+     */
     settleDelayMs?: number;
     input: string;
+    /**
+     * Second-phase input, written `submitAfterMs` after `input`. Both must be
+     * set for the second write to happen; absent by default, which keeps the
+     * historical single-write behaviour for existing adapters.
+     */
+    submitInput?: string;
+    submitAfterMs?: number;
+    /**
+     * Opt-in terminal-query responder: answers DSR, DA1 and OSC 4/10/11
+     * capability queries the child emits. Off by default; TUIs that never
+     * query (codex, kimi, grok) are unaffected either way.
+     */
+    respondToQueries?: boolean;
     completionRegex?: RegExp;
     /** If matched, abort immediately with a clear error (e.g. trust prompts). */
     abortOn?: RegExp;
@@ -20,4 +38,39 @@ export interface PtyRunOptions {
     /** Diagnostic label for the tracked child (adapter id). */
     label?: string;
 }
+export interface TerminalQueryRule {
+    /** Non-global pattern; must match the complete query including terminator. */
+    match: RegExp;
+    reply: (m: RegExpMatchArray) => string;
+}
+/**
+ * Canned answers to terminal capability queries, table-driven so a future
+ * query type is a one-line row. Replies are static: colour answers never
+ * affect parsing because styling is stripped before matching.
+ */
+export declare const TERMINAL_QUERY_RESPONSES: TerminalQueryRule[];
+/**
+ * Stateful feeder for `TERMINAL_QUERY_RESPONSES`. Consumes each matched query
+ * from an internal buffer, so a query split across chunks is answered once it
+ * completes and never answered twice. Plain output passes through silently.
+ */
+export declare function createTerminalQueryResponder(write: (s: string) => void): (chunk: string) => void;
+export interface SpawnHelperRepair {
+    helper: string;
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Lazy replacement for the removed postinstall: best-effort `chmod 0o755`
+ * over every prebuilds entry `spawn-helper` under the given node-pty roots.
+ * Missing roots, missing prebuild dirs, and missing helpers are skipped
+ * silently; only attempted repairs are recorded.
+ */
+export declare function repairSpawnHelpers(roots: string[], chmod?: (p: string, mode: number) => void): SpawnHelperRepair[];
+/**
+ * Human diagnostic for failed repairs, or null when nothing failed.
+ * Load-bearing for root-owned trees (e.g. `sudo` global installs) where the
+ * invoking user cannot repair: without it the failure would go opaque again.
+ */
+export declare function describeSpawnHelperRepairs(outcomes: SpawnHelperRepair[]): string | null;
 export declare function runPty(opts: PtyRunOptions): Promise<string>;