agent-fuel 0.3.0 → 0.4.0

package/dist/adapters/agy.js

@@ -1,70 +1,53 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import { spawn } from 'node:child_process';
+import { TuiScraper } from '../tmux.js';
 const CACHE_PATH = path.join(os.homedir(), '.gemini/antigravity-cli/.agent-fuel-quota-cache.json');
 const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
-// ── ANSI / terminal helpers ────────────────────────────────────────────────
-function stripAnsi(str) {
-    // eslint-disable-next-line no-control-regex
-    return str.replace(/\x1B\[[0-9;]*[A-Za-z]|\x1B[^[]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
-}
 // ── Scraping ───────────────────────────────────────────────────────────────
+async function sleep(ms) {
+    return new Promise(res => setTimeout(res, ms));
+}
 /**
- * Spawns `agy` via `expect`, opens the `/usage` panel, waits for the
- * Model Quota list to render, then exits.
+ * Launches `agy` in a tmux session, opens the `/usage` panel, waits for
+ * the Model Quota list to render, then returns clean rendered screen text.
  */
-function runAgyUsage() {
-    return new Promise((resolve) => {
-        const expectScript = [
-            'set timeout 20',
-            'spawn agy',
-            'expect -re "for shortcuts"',
-            'send "/usage\\r"',
-            'expect -re "Model Quota"',
-            'after 800',
-            'send "\\x03"',
-            'expect eof',
-        ].join('\n');
-        // Cap output to avoid unbounded memory growth if agy misbehaves
-        const MAX_OUTPUT_BYTES = 64 * 1024; // 64 KB — far more than the quota panel needs
-        let output = '';
-        // Spread process.env so `expect` can locate `agy` via PATH and the
-        // keyring daemon can be reached via the existing session environment.
-        const child = spawn('expect', ['-c', expectScript], {
-            env: { ...process.env },
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        const append = (chunk) => {
-            if (output.length < MAX_OUTPUT_BYTES) {
-                output += chunk.toString();
-            }
-        };
-        child.stdout.on('data', append);
-        child.stderr.on('data', append);
-        const timer = setTimeout(() => { child.kill('SIGKILL'); resolve(output); }, 25_000);
-        child.on('close', () => { clearTimeout(timer); resolve(output); });
-    });
+async function runAgyUsage() {
+    const tui = new TuiScraper('agy');
+    try {
+        tui.start();
+        // Wait for AGY main menu ready
+        await tui.waitFor(/for shortcuts/, 20_000);
+        // Navigate to /usage panel
+        tui.send('/usage');
+        await tui.waitFor(/Model Quota/, 10_000);
+        // Brief pause for all model rows to finish rendering
+        await sleep(500);
+        return tui.capture();
+    }
+    finally {
+        tui.kill();
+    }
 }
 // ── Parsing ────────────────────────────────────────────────────────────────
 /**
  * Parse the Model Quota panel into an array of entries.
  *
- * Panel format (after ANSI strip):
+ * Panel format (tmux rendered — no ANSI codes):
  *
  *   └ Model Quota
  *
  *     Gemini 3.5 Flash (High)
  *     ░░░░░░░░░░░ ... 20%
- *     Refreshes in 3h 28m           ← or "80% remaining · Refreshes in …"
+ *     Refreshes in 3h 28m
  *
  *     Claude Sonnet 4.6 (Thinking)
  *     ███████████ ... 100%
  *     Quota available
  */
 function parseQuotaPanel(raw) {
-    const clean = stripAnsi(raw);
-    const lines = clean.split(/\r?\n/);
+    // tmux capture-pane returns clean rendered text — no ANSI stripping needed
+    const lines = raw.split(/\r?\n/);
     const results = [];
     const headerIdx = lines.findIndex(l => l.includes('Model Quota'));
     if (headerIdx === -1)
@@ -91,15 +74,12 @@ function parseQuotaPanel(raw) {
                     j++;
                     continue;
                 }
-                // Progress bar line: has block chars OR starts with a digit%
                 if (barLine === null && (candidate.includes('░') || candidate.includes('█') || /^\d+%/.test(candidate))) {
                     barLine = candidate;
                     j++;
                     continue;
                 }
-                // Refresh / availability line
                 if (barLine !== null && (candidate.includes('Refreshes') || candidate.includes('Quota available'))) {
-                    // Strip any leading "NN% remaining · " prefix
                     const m = candidate.match(/(Refreshes in [^\r\n]+|Quota available)/);
                     refreshLine = m ? m[1] : candidate;
                     j++;
@@ -107,7 +87,6 @@ function parseQuotaPanel(raw) {
                 break;
             }
             if (barLine !== null) {
-                // Percentage is always at the END of the bar line: "░░░ ... 20%" or "20% remaining · …"
                 const percentMatch = barLine.match(/(\d+)%/);
                 if (percentMatch) {
                     results.push({ model: line, percent: parseInt(percentMatch[1], 10), refreshLine });
@@ -137,11 +116,6 @@ async function writeCache(entries) {
     catch { /* non-fatal */ }
 }
 // ── Bucket aggregation ────────────────────────────────────────────────────
-/**
- * Given all quota entries, build the two UsageSnapshot rows:
- *   - agy-gemini: worst-case (min remaining) across all Gemini models
- *   - agy-other:  worst-case across all non-Gemini models (Claude, etc.)
- */
 function buildSnapshots(entries, fromCache) {
     const source = fromCache ? 'cache' : 'official-cli';
     const geminiEntries = entries.filter(e => /gemini/i.test(e.model));
@@ -150,7 +124,6 @@ function buildSnapshots(entries, fromCache) {
         if (bucket.length === 0) {
             return { tool, remainingPercent: null, usedPercent: null, resetAt: null, source: 'unknown' };
         }
-        // Show the lowest remaining % (most constrained model in the bucket)
         const worst = bucket.reduce((a, b) => a.percent <= b.percent ? a : b);
         return {
             tool,
@@ -174,7 +147,7 @@ export class AgyQuotaAdapter {
         if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
             return buildSnapshots(cached.entries, true);
         }
-        // Slow path: spawn agy, scrape the quota panel
+        // Slow path: spawn agy via tmux, scrape the quota panel
         try {
             const raw = await runAgyUsage();
             const entries = parseQuotaPanel(raw);
@@ -182,7 +155,6 @@ export class AgyQuotaAdapter {
                 await writeCache(entries);
                 return buildSnapshots(entries, false);
             }
-            // Panel not found — return unknown rows (do not cache failures)
             return [
                 { tool: 'agy-gemini', remainingPercent: null, usedPercent: null, resetAt: null, source: 'unknown' },
                 { tool: 'agy-other', remainingPercent: null, usedPercent: null, resetAt: null, source: 'unknown' },

package/dist/adapters/claude.d.ts

@@ -1,7 +1,5 @@
 import { QuotaAdapter, UsageSnapshot } from './index.js';
 export declare class ClaudeQuotaAdapter implements QuotaAdapter {
-    private readonly budgetLimit;
-    constructor();
     fetchSnapshots(): Promise<UsageSnapshot[]>;
     private _fetch;
 }

package/dist/adapters/claude.js

@@ -1,15 +1,55 @@
-import { exec } from 'node:child_process';
-import { promisify } from 'node:util';
-const execAsync = promisify(exec);
-// Budget limit for the rolling 5-hour billing window.
-// Override with AGENT_FUEL_CLAUDE_BUDGET env var (dollars).
-const DEFAULT_BUDGET_USD = 20.0;
-export class ClaudeQuotaAdapter {
-    budgetLimit;
-    constructor() {
-        const override = Number(process.env.AGENT_FUEL_CLAUDE_BUDGET);
-        this.budgetLimit = Number.isFinite(override) && override > 0 ? override : DEFAULT_BUDGET_USD;
+import { TuiScraper } from '../tmux.js';
+import { debug } from '../debug.js';
+// ── TUI scraper ────────────────────────────────────────────────────────────
+async function sleep(ms) {
+    return new Promise(res => setTimeout(res, ms));
+}
+/**
+ * Launches `claude` in a tmux session, opens /status, navigates to the
+ * Status tab (which shows real quota usage bars), and returns the captured
+ * screen text.
+ *
+ * The Status tab renders persistently (not transient), so regular
+ * capture-pane is sufficient — no pipe-pane needed.
+ */
+async function runClaudeScrape() {
+    const tui = new TuiScraper('claude');
+    try {
+        tui.start();
+        // Wait for TUI ready — welcome banner or prompt hint visible
+        await tui.waitFor(/Welcome back|Try "/i, 15_000, 0);
+        // Open the /status panel
+        tui.send('/status');
+        // Wait for the status panel tabs to appear
+        await tui.waitFor(/Settings\s+Status/i, 10_000, 0);
+        // Navigate to the Status tab (second tab after Settings)
+        tui.sendKey('Tab');
+        await sleep(300);
+        tui.sendKey('Tab');
+        // Wait for the usage bars — shows "XX% used"
+        return await tui.waitFor(/\d+%\s+used/i, 8_000, 0);
+    }
+    finally {
+        tui.kill();
     }
+}
+function parseScrapeOutput(screen) {
+    debug('claude:parse', `screen length: ${screen.length}`);
+    debug('claude:parse', 'screen', screen);
+    // Match "XX% used" occurrences in order:
+    // First = current session (5h block), second = current week
+    const usedMatches = [...screen.matchAll(/(\d+)%\s+used/gi)];
+    debug('claude:parse', `found ${usedMatches.length} "% used" matches`);
+    const sessionUsedPct = usedMatches[0] ? parseInt(usedMatches[0][1], 10) : null;
+    const weeklyUsedPct = usedMatches[1] ? parseInt(usedMatches[1][1], 10) : null;
+    // Reset time: "Resets H:MMam" or "Resets May 30 at 6am" — grab the first occurrence
+    const resetMatch = screen.match(/Resets\s+([^\n\r]+)/i);
+    const sessionResetAt = resetMatch ? resetMatch[1].trim() : null;
+    debug('claude:parse', 'result', { sessionUsedPct, sessionResetAt, weeklyUsedPct });
+    return { sessionUsedPct, sessionResetAt, weeklyUsedPct };
+}
+// ── Adapter ────────────────────────────────────────────────────────────────
+export class ClaudeQuotaAdapter {
     async fetchSnapshots() {
         return [await this._fetch()];
     }
@@ -21,51 +61,27 @@ export class ClaudeQuotaAdapter {
             resetAt: null,
             source: 'unknown',
         });
+        debug('claude:fetch', 'starting TUI scrape via tmux');
         try {
-            let stdout;
-            try {
-                ({ stdout } = await execAsync('npx --no-install ccusage blocks --json'));
-            }
-            catch {
-                throw new Error('ccusage not found. Run "npm install -g ccusage" to enable Claude Code tracking.');
-            }
-            const data = JSON.parse(stdout);
-            const blocks = Array.isArray(data?.blocks) ? data.blocks : data;
-            if (!Array.isArray(blocks)) {
-                throw new Error('Unexpected JSON shape from ccusage blocks.');
-            }
-            const activeBlock = blocks.find((b) => b.isActive === true);
-            if (!activeBlock)
-                return unknown();
-            const cost = typeof activeBlock.costUSD === 'number' ? activeBlock.costUSD : 0;
-            const usedPct = (cost / this.budgetLimit) * 100;
-            const remainingPercent = Math.max(0, Math.min(100, Math.round(100 - usedPct)));
-            let resetAt = null;
-            if (typeof activeBlock.endTime === 'string') {
-                try {
-                    resetAt = new Date(activeBlock.endTime).toLocaleTimeString([], {
-                        hour: '2-digit',
-                        minute: '2-digit',
-                    });
-                }
-                catch {
-                    resetAt = activeBlock.endTime;
-                }
+            const screen = await runClaudeScrape();
+            const result = parseScrapeOutput(screen);
+            if (result.sessionUsedPct !== null) {
+                const remainingPercent = Math.max(0, 100 - result.sessionUsedPct);
+                debug('claude:fetch', `parsed Usage tab → ${result.sessionUsedPct}% used (${remainingPercent}% remaining)`);
+                return {
+                    tool: 'claude-code',
+                    remainingPercent,
+                    usedPercent: result.sessionUsedPct,
+                    resetAt: result.sessionResetAt,
+                    source: 'official-cli',
+                };
             }
-            return {
-                tool: 'claude-code',
-                remainingPercent,
-                usedPercent: Math.round(usedPct),
-                resetAt,
-                source: 'ccusage',
-                raw: activeBlock,
-            };
+            debug('claude:fetch', 'parse failed → unknown');
+            return unknown();
         }
-        catch (error) {
-            return {
-                ...unknown(),
-                raw: error instanceof Error ? error.message : String(error),
-            };
+        catch (err) {
+            debug('claude:fetch', 'caught error', String(err));
+            return unknown();
         }
     }
 }

package/dist/adapters/codex.js

@@ -1,73 +1,109 @@
-import { exec, spawn } from 'node:child_process';
+import { exec, execFileSync } from 'node:child_process';
 import { promisify } from 'node:util';
+import { readFileSync, unlinkSync } from 'node:fs';
+import { TuiScraper } from '../tmux.js';
+import { debug } from '../debug.js';
 const execAsync = promisify(exec);
 // Used ONLY as a rough fallback estimate when the TUI scrape cannot determine
-// a percentage (i.e. quota has not yet been reached). This is a GUESS based on
-// local session cost data — not an official Codex quota signal.
-// Override with AGENT_FUEL_CODEX_BUDGET env var (dollars).
+// a percentage. This is a GUESS based on local session cost data — not an
+// official Codex quota signal. Override with AGENT_FUEL_CODEX_BUDGET env var.
 const DEFAULT_BUDGET_USD = 20.0;
 const ROLLING_WINDOW_MS = 5 * 60 * 60 * 1000;
-// ── TUI scraper (expect) ───────────────────────────────────────────────────
+// ── TUI scraper (tmux) ─────────────────────────────────────────────────────
+async function sleep(ms) {
+    return new Promise(res => setTimeout(res, ms));
+}
 /**
- * Spawns `codex` via `expect`, handles the trust prompt, waits for the TUI to
- * settle, then captures stdout/stderr to check for the quota-reached warning.
+ * Launches `codex` in a tmux session, pipes all terminal bytes to a temp
+ * file, sends /status twice, then reads the file and returns the raw bytes.
+ *
+ * Why pipe-pane instead of capture-pane:
+ * The /status overlay is full-screen and transient — it renders in-place for
+ * one frame and re-renders away without entering the tmux scrollback buffer.
+ * capture-pane (even with -S history) can never catch it. pipe-pane streams
+ * every raw byte to a file so even a 10ms overlay is permanently recorded.
  */
-function runCodexScrape() {
-    return new Promise((resolve) => {
-        const expectScript = [
-            'set timeout 15',
-            'spawn codex',
-            'expect {',
-            '  -re "Press enter to continue" { send "\\r"; exp_continue }',
-            '  -re "Individual quota reached" { after 300; send "\\x03" }',
-            '  -re "for shortcuts" { after 300; send "\\x03" }',
-            '  timeout { }',
-            '  eof { }',
-            '}',
-            'expect eof',
-        ].join('\n');
-        const MAX_OUTPUT_BYTES = 64 * 1024;
-        let output = '';
-        const child = spawn('expect', ['-c', expectScript], {
-            env: { ...process.env },
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        const append = (chunk) => {
-            if (output.length < MAX_OUTPUT_BYTES)
-                output += chunk.toString();
-        };
-        child.stdout.on('data', append);
-        child.stderr.on('data', append);
-        const timer = setTimeout(() => { child.kill('SIGKILL'); resolve(output); }, 20_000);
-        child.on('close', () => { clearTimeout(timer); resolve(output); });
-    });
+async function runCodexScrape() {
+    const tui = new TuiScraper('codex');
+    const pipePath = `/tmp/af-codex-${Date.now()}.log`;
+    try {
+        tui.start();
+        // Stream all pane output to a file from the start
+        execFileSync('tmux', ['pipe-pane', '-t', tui.sessionId, `cat >> '${pipePath}'`]);
+        debug('codex:scrape', `pipe-pane logging to ${pipePath}`);
+        // Wait for TUI ready: current screen (historyLines=0) shows Tip, meaning MCP boot done
+        await tui.waitFor(/Tip:/i, 20_000, 0);
+        // First /status: panel says "Limits: refresh requested; run /status again shortly"
+        tui.send('/status');
+        await sleep(2_000);
+        // Second /status: has actual 5h/weekly quota data
+        tui.send('/status');
+        await sleep(4_000);
+        const raw = readFileSync(pipePath, 'utf-8');
+        debug('codex:scrape', `pipe log size: ${raw.length} bytes`);
+        return raw;
+    }
+    finally {
+        tui.kill();
+        try {
+            unlinkSync(pipePath);
+        }
+        catch { /* ok */ }
+    }
 }
-// ── Output parser ──────────────────────────────────────────────────────────
 function stripAnsi(str) {
     // eslint-disable-next-line no-control-regex
-    return str.replace(/\x1B\[[0-9;]*[A-Za-z]|\x1B[^[]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+    return str
+        .replace(/\x1B\[[\x20-\x3f]*[\x40-\x7e]/g, '')
+        .replace(/\x1B[^[]/g, '')
+        .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
 }
 function parseScrapeOutput(raw) {
+    // pipe-pane output contains raw ANSI bytes — strip before pattern matching
     const clean = stripAnsi(raw);
+    debug('codex:parse', `raw length: ${raw.length}, cleaned length: ${clean.length}`);
+    debug('codex:parse', 'cleaned output', clean);
+    debug('codex:parse', 'checking patterns', {
+        hasIndividualQuota: /Individual quota reached/i.test(clean),
+        hasHeadsUp: /less than \d+%\s+of your 5h limit left/i.test(clean),
+        has5hLimit: /5h limit:/i.test(clean),
+        hasWeeklyLimit: /Weekly limit:/i.test(clean),
+        hasLimits: /Limits:/i.test(clean),
+    });
     // "Individual quota reached. Contact your administrator to enable overages. Resets in 4h33m29s."
-    const quotaMatch = clean.match(/Individual quota reached/i);
-    if (!quotaMatch)
-        return { quotaReached: false, resetIn: null };
-    // Parse "Resets in 4h33m29s" → "4h 33m"
-    const resetMatch = clean.match(/Resets in\s*((?:\d+h)?(?:\d+m)?(?:\d+s)?)/i);
-    let resetIn = null;
-    if (resetMatch) {
-        const parts = [];
-        const hm = resetMatch[1].match(/^(\d+h)?(\d+m)?/);
-        if (hm) {
-            if (hm[1])
-                parts.push(hm[1]);
-            if (hm[2])
-                parts.push(hm[2]);
+    if (/Individual quota reached/i.test(clean)) {
+        const resetMatch = clean.match(/Resets in\s*((?:\d+h)?(?:\d+m)?(?:\d+s)?)/i);
+        let resetIn = null;
+        if (resetMatch) {
+            const parts = [];
+            const hm = resetMatch[1].match(/^(\d+h)?(\d+m)?/);
+            if (hm) {
+                if (hm[1])
+                    parts.push(hm[1]);
+                if (hm[2])
+                    parts.push(hm[2]);
+            }
+            resetIn = parts.length > 0 ? parts.join(' ') : null;
         }
-        resetIn = parts.length > 0 ? parts.join(' ') : null;
+        debug('codex:parse', 'result', { quotaReached: true, resetIn });
+        return { quotaReached: true, resetIn, fiveHourRemainingPct: null, fiveHourResetAt: null };
     }
-    return { quotaReached: true, resetIn };
+    // "⚠ Heads up, you have less than X% of your 5h limit left."
+    const headsUpMatch = clean.match(/less than (\d+)%\s+of your 5h limit left/i);
+    if (headsUpMatch) {
+        const ceiling = parseInt(headsUpMatch[1], 10);
+        const fiveHourRemainingPct = Math.max(0, ceiling - 1);
+        debug('codex:parse', 'result', { source: 'headsUp', ceiling, fiveHourRemainingPct });
+        return { quotaReached: false, resetIn: null, fiveHourRemainingPct, fiveHourResetAt: null };
+    }
+    // Parse "/status" panel: "5h limit: [...] X% left (resets HH:MM)"
+    // Use the LAST match — /status is sent twice and the second response is fresh.
+    const allFiveHMatches = [...clean.matchAll(/5h limit:\s*\[.*?\]\s*(\d+)%\s*left\s*\(resets\s+([^)]+)\)/gi)];
+    const fiveHMatch = allFiveHMatches.at(-1) ?? null;
+    const fiveHourRemainingPct = fiveHMatch ? parseInt(fiveHMatch[1], 10) : null;
+    const fiveHourResetAt = fiveHMatch ? fiveHMatch[2].trim() : null;
+    debug('codex:parse', 'result', { quotaReached: false, fiveHourRemainingPct, fiveHourResetAt, fiveHMatchRaw: fiveHMatch?.[0] ?? null });
+    return { quotaReached: false, resetIn: null, fiveHourRemainingPct, fiveHourResetAt };
 }
 // ── ccusage fallback estimate ──────────────────────────────────────────────
 async function fetchCcusageEstimate(budgetLimit) {
@@ -86,6 +122,7 @@ async function fetchCcusageEstimate(budgetLimit) {
         catch {
             return unknown();
         }
+        debug('codex:ccusage', 'raw stdout', stdout);
         const data = JSON.parse(stdout);
         const sessions = Array.isArray(data?.sessions) ? data.sessions :
             Array.isArray(data?.session) ? data.session :
@@ -124,6 +161,14 @@ async function fetchCcusageEstimate(budgetLimit) {
             }
             catch { /* leave null */ }
         }
+        debug('codex:ccusage', 'computed', {
+            totalCost,
+            todaySessionsCount: todaySessions.length,
+            budgetLimit,
+            usedPct,
+            remainingPercent,
+            resetAt,
+        });
         return {
             tool: 'codex',
             remainingPercent,
@@ -148,13 +193,13 @@ export class CodexQuotaAdapter {
         return [await this._fetch()];
     }
     async _fetch() {
-        // Primary: scrape the Codex TUI via expect
+        debug('codex:fetch', 'starting TUI scrape via tmux');
         try {
             const raw = await runCodexScrape();
             const result = parseScrapeOutput(raw);
             if (result.quotaReached) {
-                // Ground truth: quota is exhausted
                 const resetAt = result.resetIn ? `Resets in ${result.resetIn}` : null;
+                debug('codex:fetch', 'quota reached → returning 0%');
                 return {
                     tool: 'codex',
                     remainingPercent: 0,
@@ -163,12 +208,21 @@ export class CodexQuotaAdapter {
                     source: 'official-cli',
                 };
             }
-            // TUI loaded cleanly with no quota warning → estimate remaining via ccusage
-            const estimate = await fetchCcusageEstimate(this.budgetLimit);
-            return estimate;
+            if (result.fiveHourRemainingPct !== null) {
+                debug('codex:fetch', `parsed /status → ${result.fiveHourRemainingPct}% remaining`);
+                return {
+                    tool: 'codex',
+                    remainingPercent: result.fiveHourRemainingPct,
+                    usedPercent: 100 - result.fiveHourRemainingPct,
+                    resetAt: result.fiveHourResetAt,
+                    source: 'official-cli',
+                };
+            }
+            debug('codex:fetch', '/status parse failed → falling back to ccusage estimate');
+            return fetchCcusageEstimate(this.budgetLimit);
         }
-        catch {
-            // expect not available or codex spawn failed → fall back to ccusage estimate
+        catch (err) {
+            debug('codex:fetch', 'caught error, falling back to ccusage', String(err));
             return fetchCcusageEstimate(this.budgetLimit);
         }
     }

package/dist/debug.d.ts

@@ -0,0 +1,4 @@
+declare const enabled: boolean;
+declare const logFile: string | null;
+export declare function debug(tag: string, message: string, data?: unknown): void;
+export { enabled as debugEnabled, logFile as debugLogFile };

package/dist/debug.js

@@ -0,0 +1,18 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+const enabled = process.argv.includes('--debug');
+const logFile = enabled
+    ? (() => {
+        const dir = join(process.cwd(), '.logs');
+        mkdirSync(dir, { recursive: true });
+        const ts = new Date().toISOString().replace(/[:.]/g, '-');
+        return join(dir, `debug-${ts}.log`);
+    })()
+    : null;
+export function debug(tag, message, data) {
+    if (!logFile)
+        return;
+    const line = `[${new Date().toISOString()}] [${tag}] ${message}${data !== undefined ? '\n' + JSON.stringify(data, null, 2) : ''}\n`;
+    appendFileSync(logFile, line);
+}
+export { enabled as debugEnabled, logFile as debugLogFile };

package/dist/index.js

@@ -1,38 +1,61 @@
 #!/usr/bin/env node
+import { debugEnabled, debugLogFile } from './debug.js';
 import { ClaudeQuotaAdapter } from './adapters/claude.js';
 import { CodexQuotaAdapter } from './adapters/codex.js';
 import { AgyQuotaAdapter } from './adapters/agy.js';
-import { printHeader, printFooter, formatRow, getDisplayName, LOADING_LINE } from './render.js';
+import { printHeader, printFooter, formatRow, getDisplayName } from './render.js';
 // Fixed display order — never changes regardless of which adapter resolves first
 const SLOT_ORDER = ['claude-code', 'codex', 'agy-gemini', 'agy-other'];
 const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
 const R = '\x1b[0m';
-const N = SLOT_ORDER.length;
-// Redraws all N slot lines from the current cursor position (cursor must be
-// just below the last slot line when called).
-function redraw(slots) {
-    process.stdout.write(`\x1b[${N}A`); // cursor up N lines
+const GRAY = '\x1b[90m';
+const isTTY = Boolean(process.stdout.isTTY);
+const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+let spinnerTick = 0;
+function spinnerLine(tool) {
+    const frame = SPINNER[spinnerTick % SPINNER.length];
+    return `${BOLD}${getDisplayName(tool).padEnd(13)}${R} ${DIM}${GRAY}${frame} loading...${R}\x1b[K`;
+}
+// In TTY mode: restore cursor to saved position and repaint all slots.
+// In pipe mode: emit each newly-resolved line exactly once (tracked via emitted set).
+function redraw(slots, emitted) {
+    if (!isTTY) {
+        for (const tool of SLOT_ORDER) {
+            const line = slots.get(tool);
+            if (line != null && !emitted.has(tool)) {
+                process.stdout.write(line + '\n');
+                emitted.add(tool);
+            }
+        }
+        return;
+    }
+    process.stdout.write('\x1b8'); // DEC restore-cursor — teleports back to saved position
     for (const tool of SLOT_ORDER) {
-        process.stdout.write('\x1b[2K\r'); // clear line
+        process.stdout.write('\x1b[2K\r');
         const line = slots.get(tool);
-        if (line != null) {
-            process.stdout.write(line + '\n');
-        }
-        else {
-            process.stdout.write(`${BOLD}${getDisplayName(tool).padEnd(13)}${R} ${LOADING_LINE}\n`);
-        }
+        process.stdout.write((line != null ? line + '\x1b[K' : spinnerLine(tool)) + '\n');
     }
 }
 async function main() {
     const claudeAdapter = new ClaudeQuotaAdapter();
     const codexAdapter = new CodexQuotaAdapter();
     const agyAdapter = new AgyQuotaAdapter();
+    if (debugEnabled)
+        process.stderr.write(`\x1b[2m[debug] logging to ${debugLogFile}\x1b[0m\n`);
     printHeader();
-    // Print placeholder rows in fixed order
+    // Save cursor before the placeholder rows so redraw() can teleport back and overwrite them
     const slots = new Map(SLOT_ORDER.map(t => [t, null]));
+    const emitted = new Set(); // pipe-mode: tracks which lines have been printed
+    if (isTTY)
+        process.stdout.write('\x1b7'); // DEC save-cursor
     for (const tool of SLOT_ORDER) {
-        process.stdout.write(`${BOLD}${getDisplayName(tool).padEnd(13)}${R} ${LOADING_LINE}\n`);
+        process.stdout.write(spinnerLine(tool) + '\n');
     }
+    // Animate spinner at 80ms while any slot is still loading
+    const spinnerTimer = isTTY
+        ? setInterval(() => { spinnerTick++; redraw(slots, emitted); }, 80)
+        : null;
     // Each adapter fills its slot(s) and triggers a redraw; order is always fixed
     function fill(snaps) {
         for (const snap of snaps) {
@@ -40,13 +63,16 @@ async function main() {
                 slots.set(snap.tool, formatRow(snap));
             }
         }
-        redraw(slots);
+        redraw(slots, emitted);
     }
     await Promise.allSettled([
         claudeAdapter.fetchSnapshots().then(fill),
         codexAdapter.fetchSnapshots().then(fill),
         agyAdapter.fetchSnapshots().then(fill),
     ]);
+    if (spinnerTimer)
+        clearInterval(spinnerTimer);
+    redraw(slots, emitted); // final clean repaint with all data
     printFooter();
 }
 main().catch((error) => {

package/dist/render.js

@@ -56,9 +56,7 @@ function formatResetAt(resetAt) {
     return `${DIM}${GRAY}(resets ${resetAt})${R}`;
 }
 function isEstimate(snap) {
-    return snap.source === 'ccusage' &&
-        typeof snap.raw === 'object' && snap.raw !== null &&
-        snap.raw.isEstimate === true;
+    return snap.source === 'ccusage';
 }
 // ── Core format (returns string, no newline) ───────────────────────────────
 export function formatRow(snap) {
@@ -87,7 +85,7 @@ export function formatRow(snap) {
             parts.push(`${DIM}${GRAY}[${label}]${R}`);
         }
     }
-    if (snap.tool === 'codex' && isEstimate(snap)) {
+    if (isEstimate(snap)) {
         parts.push(`${DIM}${GRAY}[~est]${R}`);
     }
     const detailStr = parts.length > 0 ? ` ${parts.join(' ')}` : '';

package/dist/tmux.d.ts

@@ -0,0 +1,13 @@
+export declare class TuiScraper {
+    private readonly command;
+    private readonly width;
+    private readonly height;
+    readonly sessionId: string;
+    constructor(command: string, width?: number, height?: number);
+    start(): void;
+    capture(historyLines?: number): string;
+    send(text: string): void;
+    sendKey(key: string): void;
+    waitFor(pattern: RegExp, timeoutMs: number, historyLines?: number): Promise<string>;
+    kill(): void;
+}

package/dist/tmux.js

@@ -0,0 +1,72 @@
+import { execFileSync } from 'node:child_process';
+import { debug } from './debug.js';
+export class TuiScraper {
+    command;
+    width;
+    height;
+    sessionId;
+    constructor(command, width = 220, height = 50) {
+        this.command = command;
+        this.width = width;
+        this.height = height;
+        this.sessionId = `af-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    }
+    start() {
+        try {
+            execFileSync('which', ['tmux'], { stdio: 'ignore' });
+        }
+        catch {
+            throw new Error('tmux not found — install with: brew install tmux');
+        }
+        debug('tmux', `starting session ${this.sessionId} for command: ${this.command}`);
+        execFileSync('tmux', [
+            'new-session', '-d', '-s', this.sessionId,
+            '-x', String(this.width), '-y', String(this.height),
+            this.command,
+        ]);
+    }
+    // historyLines > 0 → include that many lines of scrollback above the visible screen.
+    // This catches transient overlays that rendered and then re-rendered away.
+    capture(historyLines = 0) {
+        const args = historyLines > 0
+            ? ['capture-pane', '-t', this.sessionId, '-S', `-${historyLines}`, '-p']
+            : ['capture-pane', '-t', this.sessionId, '-p'];
+        const text = execFileSync('tmux', args).toString();
+        debug('tmux:capture', `[${this.sessionId}] captured ${text.length} chars (history=${historyLines})`);
+        return text;
+    }
+    send(text) {
+        debug('tmux:send', `[${this.sessionId}] sending: ${JSON.stringify(text)}`);
+        execFileSync('tmux', ['send-keys', '-t', this.sessionId, text, 'Enter']);
+    }
+    // Send a named key (Tab, Escape, Up, Down, etc.) without appending Enter.
+    sendKey(key) {
+        debug('tmux:send', `[${this.sessionId}] sendKey: ${key}`);
+        execFileSync('tmux', ['send-keys', '-t', this.sessionId, key]);
+    }
+    async waitFor(pattern, timeoutMs, historyLines = 500) {
+        const deadline = Date.now() + timeoutMs;
+        debug('tmux:waitFor', `[${this.sessionId}] waiting for ${pattern} (timeout ${timeoutMs}ms, history=${historyLines})`);
+        while (Date.now() < deadline) {
+            const text = this.capture(historyLines);
+            if (pattern.test(text)) {
+                debug('tmux:waitFor', `[${this.sessionId}] matched ${pattern}`);
+                return text;
+            }
+            await sleep(100);
+        }
+        const last = this.capture(historyLines);
+        debug('tmux:waitFor', `[${this.sessionId}] TIMEOUT for ${pattern}, last screen:\n${last}`);
+        throw new Error(`TuiScraper.waitFor timeout after ${timeoutMs}ms: ${pattern}`);
+    }
+    kill() {
+        debug('tmux', `killing session ${this.sessionId}`);
+        try {
+            execFileSync('tmux', ['kill-session', '-t', this.sessionId], { stdio: 'ignore' });
+        }
+        catch { /* already dead */ }
+    }
+}
+function sleep(ms) {
+    return new Promise(res => setTimeout(res, ms));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-fuel",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Sleek term-based dashboard for AI coding CLI quotas",
   "type": "module",
   "main": "dist/index.js",