ai-spend-agent 0.8.0 → 0.8.1

package/dist/index.js

@@ -9,13 +9,33 @@ import { StatuslineInstallerError, installClaudeStatusline, uninstallClaudeStatu
 import { readStatuslineCache, renderStatusline } from "./statuslineRuntime.js";
 import { generateActionPlanMarkdown, generateApplyArtifactMarkdown, generateDemoPackageMarkdown, generateHtmlReport, generateMarkdownReport, generatePlainEnglishSummary, generatePolicyConfigDraftMarkdown, generateReportCardCaption, generateReportCardSvg, generateVerificationPlanMarkdown, groupByDimensions } from "@agent-finops/report";
 export async function runCli(argv = process.argv.slice(2), runtime = {}) {
-    if (argv.includes("--version") || argv.includes("-v")) {
+    if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v")) {
         return ok(await cliVersion());
     }
     if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
         return ok(helpText());
     }
     const args = parseArgs(argv);
+    if (args.parseErrors.length > 0) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                ...args.parseErrors.map((error) => `Invalid arguments: ${sanitizeSecretishError(error)}`),
+                "Run `npx aibill --help` to see supported commands and flags."
+            ].join("\n")
+        };
+    }
+    if (args.json && args.command !== "context" && args.command !== "context-health" && args.command !== "glance") {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                "--json is not available for the main receipt yet; no text receipt was substituted.",
+                "Use `npx aibill context --json` for the canonical Context Health object or `npx aibill glance` for the canonical Glance snapshot."
+            ].join("\n")
+        };
+    }
     if (args.groupByInvalid) {
         return {
             exitCode: 1,
@@ -23,10 +43,8 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
             stderr: `--group-by needs a dimension: ${groupByDimensions.join("|")}\nexample: npx aibill --group-by project`
         };
     }
-    // Zero-key instant demo is the DEFAULT first run. Running `ai-spend-agent`
-    // with no subcommand (or `npx ai-spend-agent`), or with only flags such as
-    // `--group-by agent`, lands the wow immediately on sample / auto-detected
-    // local data — no credential required.
+    // Running with no subcommand reads only evidence available on this machine.
+    // Illustrative records are reachable only through an explicit --sample.
     if (!args.command || args.command.startsWith("--") || args.command === "quickstart" || args.command === "demo") {
         return quickstartCommand(args);
     }
@@ -84,14 +102,24 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
     return {
         exitCode: 1,
         stdout: "",
-        stderr: `Unknown command: ${args.command}\n${helpText()}`
+        stderr: `Unknown command: ${sanitizeSecretishError(args.command)}\n${helpText()}`
     };
 }
 async function quickstartCommand(args) {
     const sinceDays = args.sinceDays ?? 30;
     if (!validSinceDays(sinceDays))
         return invalidSinceDaysResult();
+    if (args.plan && !planOverrideFromFlag(args.plan)) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+        };
+    }
     const { records, mode, warnings, providerCoverage, codexInvocationFiles } = await loadInstantReadData(args);
+    if (records.length === 0) {
+        return noEvidenceResult("receipt", warnings, sinceDays);
+    }
     const summaryRecords = mode === "connected"
         ? selectProviderFinancialHeadlineRecords(records)
         : records;
@@ -100,6 +128,7 @@ async function quickstartCommand(args) {
     // ("which project burns my plan"); demo/connected keep by-model.
     const groupBy = args.groupBy ?? (mode === "local-logs" ? "project" : "model");
     const color = args.noColor ? false : undefined;
+    const outputWidth = terminalOutputWidth();
     // Persona: --plan override wins; otherwise read the plans the coding agents
     // themselves persisted locally (read-only, whitelisted fields, no network).
     let detectedPlans;
@@ -114,7 +143,7 @@ async function quickstartCommand(args) {
             return {
                 exitCode: 1,
                 stdout: "",
-                stderr: `Unknown --plan "${args.plan}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+                stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
             };
         }
         detectedPlans = [override];
@@ -173,12 +202,17 @@ async function quickstartCommand(args) {
         nextSteps,
         deadContext,
         detectedPlans,
+        width: outputWidth,
         // An explicit --group-by is a drill-down question: answer with just the
         // table + window instead of repeating the whole readout.
-        view: args.groupBy ? "breakdown" : "full"
+        view: args.groupBy ? "breakdown" : args.full ? "full" : "compact"
     });
-    const header = [`  ${dataModeBanner(mode, summaryRecords)}`, ...warnings.map((warning) => `  ! ${warning}`)].join("\n");
-    return ok(`${header}\n${summaryText}`);
+    const detailedView = Boolean(args.groupBy || args.full);
+    const header = [
+        ...(detailedView ? wrapCliHeader(dataModeBanner(mode, summaryRecords), "  ", outputWidth) : []),
+        ...warnings.flatMap((warning) => wrapCliHeader(warning, "  ! ", outputWidth))
+    ].join("\n");
+    return ok(header ? `${header}\n${summaryText}` : summaryText);
 }
 async function glanceCommand(args) {
     const sinceDays = args.sinceDays ?? 30;
@@ -206,7 +240,7 @@ async function glanceCommand(args) {
             return {
                 exitCode: 1,
                 stdout: "",
-                stderr: `Unknown --plan "${args.plan}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+                stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
             };
         }
         detectedPlans = [override];
@@ -326,7 +360,7 @@ function quickstartNextSteps(mode, detected) {
     if (detected.length > 0) {
         const names = detected.map((credential) => `${credential.provider} (${credential.hint})`).join(", ");
         steps.push(`Found local key${detected.length === 1 ? "" : "s"}: ${names}`);
-        steps.push(`npx aibill connect ${detected[0].provider}   add official provider-reported cost (ADMIN/owner key)`);
+        steps.push(`npx aibill connect ${detected[0].provider}   set up the admin connector, then sync provider-reported cost`);
     }
     steps.push(mode === "demo"
         ? "npx aibill report --sample     write a clearly labeled demo Markdown + HTML report"
@@ -429,14 +463,22 @@ async function loadInstantReadData(args) {
         warnings.push(`${persisted.connectedTrust.message} CLI: run \`npx aibill connect <provider>\` or repeat the prior \`npx aibill sync-provider ...\` command. The repository-provided connected totals were ignored.`);
     }
     // Real local agent logs (Claude Code / Codex) beat any sample/legacy state.
-    const logs = await loadLocalAgentUsage({
-        // Env overrides keep tests (and unusual installs) isolated from $HOME.
-        claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
-        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
-        geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR,
-        sinceIso: sinceIsoForDays(args.sinceDays ?? 30),
-        collectCodexInvocationEvidence: true
-    }).catch(() => undefined);
+    let logs;
+    try {
+        logs = await loadLocalAgentUsage({
+            // Env overrides keep tests (and unusual installs) isolated from $HOME.
+            claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
+            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+            geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR,
+            sinceIso: sinceIsoForDays(args.sinceDays ?? 30),
+            collectCodexInvocationEvidence: true
+        });
+    }
+    catch {
+        // A failed read is not the same as an honest empty scan. Keep the compact
+        // result useful without leaking a local path or raw parser exception.
+        warnings.push("Some local agent evidence could not be read; coverage is incomplete.");
+    }
     if (logs && logs.records.length > 0) {
         // Persisted local_logs state (written by report/apply-artifact) is the
         // same data source we just re-read — superseding it silently is correct,
@@ -461,20 +503,81 @@ async function loadInstantReadData(args) {
             codexInvocationFiles: logs?.codexInvocationFiles
         };
     }
-    // No real logs. Persisted sample/legacy state may still be shown, but only as
-    // DEMO (never as connected), with a warning when its origin is unknown.
+    // No real logs. Sample and legacy persisted state must never appear unless
+    // this invocation explicitly opted into --sample.
     if (persisted && persisted.records.length > 0 && persisted.mode !== "connected_provider" && persisted.mode !== "local_logs") {
-        if (persisted.mode === undefined) {
-            warnings.push("Persisted state in .ai-spend-agent/spend.json is from an older format with no data-mode tag — treating it as demo. Run `npx aibill reset`, then re-scan to refresh.");
-        }
-        return { records: persisted.records, mode: "demo", warnings };
+        warnings.push(persisted.mode === "sample"
+            ? "Sample state exists but was not displayed because this run did not include --sample."
+            : "Legacy state with no trustworthy data-mode label was ignored. Run `npx aibill reset`, then collect fresh evidence.");
     }
     if (persisted?.mode === "local_logs") {
         warnings.push("Ignored persisted local-log cache because no current Claude Code/Codex source records were found. Re-run the local agent activity first; repository state alone cannot authorize an Apply action.");
     }
-    // loadSampleUsageData resolves the bundled CSVs relative to the installed
-    // package, so this works from ANY directory (true zero-config).
-    return { records: await loadSampleUsageData(), mode: "demo", warnings };
+    return { records: [], mode: "local-logs", warnings };
+}
+function noEvidenceResult(surface, warnings, sinceDays) {
+    const surfaceLine = surface === "watch"
+        ? "Watch has no financial baseline yet; no zero total or sample activity was recorded."
+        : surface === "report-card"
+            ? "No receipt was written because there is no supported financial evidence to summarize."
+            : `No supported AI usage evidence was found in the last ${sinceDays} days.`;
+    return {
+        exitCode: surface === "receipt" ? 0 : 1,
+        stdout: surface === "receipt"
+            ? [
+                "aibill · local only",
+                "",
+                surfaceLine,
+                "Looked for: Claude Code, Codex, and Gemini CLI local history.",
+                "Nothing was uploaded. No sample data was substituted.",
+                ...warnings.map((warning) => `! ${warning}`),
+                "",
+                "Next",
+                "  npx aibill doctor --sources       see the exact evidence gap and setup paths"
+            ].join("\n")
+            : "",
+        stderr: surface === "receipt"
+            ? ""
+            : [
+                surfaceLine,
+                "Run `npx aibill doctor --sources` to see the exact evidence gap.",
+                "Local evidence: use Claude Code, Codex, or Gemini CLI normally, then retry.",
+                "Provider billing: connect openai, anthropic, cursor, or github-copilot with an admin credential reference.",
+                "For illustrative output only, rerun this command with --sample."
+            ].join("\n")
+    };
+}
+function terminalOutputWidth() {
+    const envColumns = Number(process.env.COLUMNS);
+    const ttyColumns = process.stdout.columns;
+    const requested = Number.isFinite(envColumns) && envColumns > 0
+        ? envColumns
+        : Number.isFinite(ttyColumns) && (ttyColumns ?? 0) > 0
+            ? ttyColumns
+            : 72;
+    return Math.max(40, Math.min(120, Math.floor(requested)));
+}
+function wrapCliHeader(text, prefix, width) {
+    const available = Math.max(12, width - prefix.length);
+    const words = text.trim().split(/\s+/u);
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        if (!current) {
+            current = word;
+            continue;
+        }
+        if (`${current} ${word}`.length <= available) {
+            current += ` ${word}`;
+            continue;
+        }
+        lines.push(current);
+        current = word;
+    }
+    if (current)
+        lines.push(current);
+    const continuationPrefix = " ".repeat(prefix.length);
+    return lines.map((line, index) => `${index === 0 ? prefix : continuationPrefix}${line}`);
 }
 /** A one-line, unmissable banner telling the user which data they're seeing. */
 function dataModeBanner(mode, records) {
@@ -538,16 +641,16 @@ async function doctorCommand(args) {
         warnings.push("Gemini CLI detected, but no supported chats JSON/JSONL financial evidence was found. No financial rows were created; logs.json is presence-only evidence. Need this coverage? +1 or contribute a synthetic fixture: https://github.com/futurastudio/ai-spend-agent/issues/new?template=provider_or_agent.yml");
     }
     if (!hasLocalSource)
-        warnings.push("no supported Claude Code, Codex, or Gemini CLI session evidence found — a first run here will show DEMO sample data");
+        warnings.push("no supported Claude Code, Codex, or Gemini CLI session evidence found — the default receipt will remain empty; use --sample only for the labeled demo");
     if (providerRefs.length === 0)
-        warnings.push("no provider admin keys detected — connect OpenAI/Anthropic to add official provider-reported cost (local logs stay API-equivalent estimates)");
+        warnings.push("no provider admin keys detected — set up and sync an OpenAI/Anthropic admin connector for provider-reported cost (local logs stay API-equivalent estimates)");
     const predictedMode = connectedStateTrusted
         ? "connected provider billing"
         : hasFinancialLogs
             ? "your local agent logs (estimated at API-equivalent rates)"
             : geminiPresenceFound
                 ? "local Gemini CLI presence only (financial evidence unavailable; no sample substituted)"
-                : "demo sample (illustrative)";
+                : "no supported evidence yet (no sample substituted)";
     const lines = [
         "aibill doctor",
         `node version: ${process.version}`,
@@ -1029,7 +1132,7 @@ async function resetCommand(args) {
             "aibill reset",
             `path: ${rootPath}`,
             "nothing to clear (no persisted spend state found)",
-            "next run will re-read your real local agent logs (or demo sample if none)."
+            "next run will re-read your real local agent logs; no sample is substituted without --sample."
         ].join("\n"));
     }
     // Clear derived spend state so a prior `scan --sample` (or stale provider
@@ -1049,7 +1152,7 @@ async function resetCommand(args) {
         "aibill reset",
         `path: ${rootPath}`,
         removed.length > 0 ? `cleared: ${removed.join(", ")}` : "nothing to clear (no persisted spend state found)",
-        "next run will re-read your real local agent logs (or demo sample if none)."
+        "next run will re-read your real local agent logs; no sample is substituted without --sample."
     ].join("\n"));
 }
 async function statuslineCommand(args, runtime) {
@@ -1165,7 +1268,7 @@ async function initCommand(args, runtime = {}) {
             return {
                 exitCode: 1,
                 stdout: "",
-                stderr: `Unknown --plan "${args.plan}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+                stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
             };
         }
         detectedPlanOverride = [override];
@@ -1348,7 +1451,7 @@ async function refreshStatuslineCommand(args, runtime) {
             return {
                 exitCode: 1,
                 stdout: "",
-                stderr: `Unknown --plan "${args.plan}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+                stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
             };
         }
         detectedPlanOverride = [override];
@@ -1706,7 +1809,7 @@ function initApiEquivalentWindowLines(snapshot) {
                 agent.unsupportedUsageSnapshots === 0 &&
                 agent.jsonlValidationCoverage === "complete");
         return [completeZero
-                ? "API-equivalent value: ~$0.00 1d · ~$0.00 7d · ~$0.00 30d (estimated value; not billed spend)"
+                ? "API-equivalent usage value: unavailable — no priced evidence was observed in readable local sources"
                 : "API-equivalent usage value: unavailable — local source coverage is incomplete; no zero total was inferred"];
     }
     if (snapshot.mode === "unresolved" && snapshot.unresolved) {
@@ -1826,7 +1929,7 @@ async function scanCommand(args) {
         const mappings = attributeUsageRecords(records);
         await writeLocalSpendState(stateDir, records, summary, mappings, "sample");
         lines.push(`sample records: ${records.length}`);
-        lines.push(`total spend: $${summary.totalUsd.toFixed(2)}`);
+        lines.push(`total spend: ${formatOptionalUsd(summary.totalUsd)}`);
         lines.push(`attribution mappings: ${mappings.length}`);
     }
     if (discovery.signals.length > 0) {
@@ -1858,6 +1961,9 @@ async function watchCommand(args) {
     while (unbounded || iteration < cycles) {
         const previous = await readOptionalJson(join(stateDir, "watch-latest.json"), null);
         const { summary, snapshot, records, mode } = await runWatchCycle(stateDir, args);
+        if (records.length === 0) {
+            return noEvidenceResult("watch", [], args.sinceDays ?? 30);
+        }
         const deltaHeadline = buildDeltaHeadline(previous, snapshot);
         // Watch's job is DELTAS: render the compact breakdown view per cycle, not
         // the whole diagnose→verify readout again (the quickstart owns that).
@@ -1866,6 +1972,7 @@ async function watchCommand(args) {
             groupBy: args.groupBy ?? "model",
             color: args.noColor ? false : undefined,
             mode: mode === "sample" ? "demo" : mode === "connected_provider" ? "connected" : "local-logs",
+            width: terminalOutputWidth(),
             view: "breakdown"
         });
         const stamped = [
@@ -1929,8 +2036,8 @@ async function runWatchCycle(stateDir, args) {
                 mode = "local_logs";
             }
             else {
-                records = await loadSampleUsageData();
-                mode = "sample";
+                records = [];
+                mode = "local_logs";
             }
         }
     }
@@ -1961,7 +2068,7 @@ async function runWatchCycle(stateDir, args) {
         sourceId: "watch",
         detail: snapshot.totalUsd === null
             ? `Watch cycle captured ${snapshot.recordCount} records with no priced financial evidence; total unavailable.`
-            : `Watch cycle captured ${snapshot.recordCount} records totaling $${snapshot.totalUsd.toFixed(2)}.`
+            : `Watch cycle captured ${snapshot.recordCount} records totaling ${formatOptionalUsd(snapshot.totalUsd)}.`
     });
     return { summary, snapshot, records: headlineRecords, mode };
 }
@@ -1970,24 +2077,24 @@ function buildDeltaHeadline(previous, current) {
         if (current.totalUsd === null) {
             return `First watch snapshot. Financial baseline is unavailable across ${current.recordCount} records; missing/null is not zero. Future priced cycles will establish a numeric baseline.`;
         }
-        return `First watch snapshot. Baseline AI spend is $${current.totalUsd.toFixed(2)} across ${current.recordCount} charges. Future cycles will report what changed.`;
+        return `First watch snapshot. Baseline AI spend is ${formatOptionalUsd(current.totalUsd)} across ${current.recordCount} charges. Future cycles will report what changed.`;
     }
     if (current.totalUsd === null) {
         return `Financial evidence is unavailable across ${current.recordCount} records; missing/null is not zero and no numeric delta was calculated.`;
     }
     if (previous.totalUsd === null) {
-        return `A priced financial baseline is now available at $${current.totalUsd.toFixed(2)} across ${current.recordCount} records. The prior snapshot was unavailable, so no numeric delta was calculated.`;
+        return `A priced financial baseline is now available at ${formatOptionalUsd(current.totalUsd)} across ${current.recordCount} records. The prior snapshot was unavailable, so no numeric delta was calculated.`;
     }
     const deltaUsd = roundMoneyCli(current.totalUsd - previous.totalUsd);
     const lines = [];
-    if (Math.abs(deltaUsd) < 0.01) {
-        lines.push(`No change since the last check: AI spend is holding at $${current.totalUsd.toFixed(2)}.`);
+    if (deltaUsd === 0) {
+        lines.push(`No change since the last check: AI spend is holding at ${formatOptionalUsd(current.totalUsd)}.`);
     }
     else {
         const direction = deltaUsd > 0 ? "UP" : "DOWN";
         const percent = previous.totalUsd > 0 ? Math.round((deltaUsd / previous.totalUsd) * 100) : 100;
-        lines.push(`Spend is ${direction} $${Math.abs(deltaUsd).toFixed(2)} (${Math.abs(percent)}%) since the last check — ` +
-            `from $${previous.totalUsd.toFixed(2)} to $${current.totalUsd.toFixed(2)}.`);
+        lines.push(`Spend is ${direction} ${formatOptionalUsd(Math.abs(deltaUsd))} (${Math.abs(percent)}%) since the last check — ` +
+            `from ${formatOptionalUsd(previous.totalUsd)} to ${formatOptionalUsd(current.totalUsd)}.`);
     }
     // New-model and per-model spike detection versus the previous snapshot.
     const previousModels = new Map(previous.byModel.map((entry) => [entry.key, entry.amountUsd]));
@@ -1996,12 +2103,12 @@ function buildDeltaHeadline(previous, current) {
         const before = previousModels.get(entry.key);
         if (before === undefined) {
             if (entry.amountUsd >= 1) {
-                anomalies.push(`New model "${entry.key}" appeared, already at $${entry.amountUsd.toFixed(2)}.`);
+                anomalies.push(`New model "${entry.key}" appeared, already at ${formatOptionalUsd(entry.amountUsd)}.`);
             }
             continue;
         }
         if (before > 0 && entry.amountUsd - before >= 5 && entry.amountUsd / before >= 1.5) {
-            anomalies.push(`"${entry.key}" jumped from $${before.toFixed(2)} to $${entry.amountUsd.toFixed(2)}.`);
+            anomalies.push(`"${entry.key}" jumped from ${formatOptionalUsd(before)} to ${formatOptionalUsd(entry.amountUsd)}.`);
         }
     }
     if (anomalies.length > 0) {
@@ -2013,7 +2120,7 @@ function sleep(milliseconds) {
     return new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds));
 }
 function roundMoneyCli(value) {
-    return Math.round(value * 100) / 100;
+    return Math.round(value * 10_000) / 10_000;
 }
 async function addSourceCommand(args) {
     const rootPath = resolve(args.path);
@@ -2074,6 +2181,10 @@ const adminUpgradeProviders = {
     "github-copilot": "requires a GitHub BILLING-ADMIN token (org/enterprise)",
     copilot: "requires a GitHub BILLING-ADMIN token (org/enterprise)"
 };
+const supportedAdminProviders = new Set(["openai", "anthropic", "cursor", "github-copilot"]);
+const providerAliases = {
+    copilot: "github-copilot"
+};
 const providerAdminEnvHint = {
     openai: "env:OPENAI_ADMIN_KEY",
     anthropic: "env:ANTHROPIC_ADMIN_KEY",
@@ -2081,10 +2192,20 @@ const providerAdminEnvHint = {
     "github-copilot": "env:GITHUB_TOKEN",
     copilot: "env:GITHUB_TOKEN"
 };
+function providerSyncSetupCommand(provider, adminRef) {
+    if (provider === "cursor") {
+        return `npx aibill sync-provider --provider cursor --auth-reference ${adminRef} --account-id <team-label>`;
+    }
+    if (provider === "github-copilot") {
+        return `npx aibill sync-provider --provider github-copilot --auth-reference ${adminRef} --org <organization>`;
+    }
+    return `npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time <unix>`;
+}
 async function connectCommand(args) {
     const rootPath = resolve(args.path);
     const stateDir = join(rootPath, ".ai-spend-agent");
-    const provider = args.provider ?? "unknown";
+    const requestedProvider = (args.provider ?? "unknown").trim().toLowerCase();
+    const provider = providerAliases[requestedProvider] ?? requestedProvider;
     if (!provider || provider === "unknown") {
         return {
             exitCode: 1,
@@ -2100,6 +2221,20 @@ async function connectCommand(args) {
         };
     }
     const type = args.sourceType ?? "provider_api";
+    if (!supportedAdminProviders.has(provider) || type !== "provider_api") {
+        const reason = !supportedAdminProviders.has(provider)
+            ? `connect does not implement provider "${sanitizeSecretishError(requestedProvider)}".`
+            : `connect supports provider_api only; received "${sanitizeSecretishError(type)}".`;
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                reason,
+                "Supported admin connectors: openai, anthropic, cursor, github-copilot.",
+                "For an approved file/export boundary, use `npx aibill add-source` instead."
+            ].join("\n")
+        };
+    }
     const registry = await readSourceRegistry(stateDir, rootPath);
     const source = createProviderConnectorStub(provider, type);
     const nextRegistry = addApprovedSource(registry, source);
@@ -2126,7 +2261,7 @@ async function connectCommand(args) {
         `boundary approval: ${source.boundaryApproval}`,
         `validation coverage: ${source.validationCoverage}`,
         `financial evidence: ${source.financialEvidence}`,
-        "secrets: no raw secrets stored; we only reference a local env var such as env:OPENAI_ADMIN_KEY"
+        `secrets: no raw secrets stored; we only reference a local env var such as ${providerAdminEnvHint[provider] ?? "env:YOUR_ADMIN_KEY"}`
     ];
     if (selfServeProviders.has(provider)) {
         lines.push("tier: self-serve — an org owner can enable this in ~2 minutes");
@@ -2140,19 +2275,19 @@ async function connectCommand(args) {
         lines.push(`auto-detected: a ${provider} key in ${detected.reference} (${detected.hint}) from ${describeOrigin(detected)}`);
         if (detected.isLikelyAdminKey) {
             const adminRef = providerAdminEnvHint[provider] ?? detected.reference;
-            lines.push(`next: npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time <unix>`);
+            lines.push(`next: ${providerSyncSetupCommand(provider, adminRef)}`);
         }
         else {
             const adminRef = providerAdminEnvHint[provider] ?? "env:YOUR_ADMIN_KEY";
             lines.push(`this looks like a regular key — for COST data set an admin key in ${adminRef}, then:`);
-            lines.push(`  npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time <unix>`);
+            lines.push(`  ${providerSyncSetupCommand(provider, adminRef)}`);
         }
     }
     else {
         const adminRef = providerAdminEnvHint[provider] ?? "env:YOUR_ADMIN_KEY";
         lines.push("");
         lines.push(`next: export an admin key reference, e.g. ${adminRef}, then run:`);
-        lines.push(`  npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time <unix>`);
+        lines.push(`  ${providerSyncSetupCommand(provider, adminRef)}`);
     }
     lines.push(`missing: ${source.fieldsMissing.join(", ")}`);
     return ok(lines.join("\n"));
@@ -2181,17 +2316,62 @@ function describeOrigin(credential) {
 async function syncProviderCommand(args) {
     const rootPath = resolve(args.path);
     const stateDir = join(rootPath, ".ai-spend-agent");
-    if (!args.provider || !args.authReference || !args.startTime) {
+    const requestedProvider = (args.provider ?? "").trim().toLowerCase();
+    const provider = providerAliases[requestedProvider] ?? requestedProvider;
+    if (!provider) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                "sync-provider requires --provider.",
+                "Supported admin connectors: openai, anthropic, cursor, github-copilot."
+            ].join("\n")
+        };
+    }
+    if (!supportedAdminProviders.has(provider)) {
         return {
             exitCode: 1,
             stdout: "",
             stderr: [
-                "sync-provider requires --provider, --auth-reference env:NAME, and --start-time <unix seconds>.",
-                "example:",
-                "  npx aibill sync-provider --provider anthropic --auth-reference env:ANTHROPIC_ADMIN_KEY --start-time 1750000000"
+                `sync-provider does not implement provider "${sanitizeSecretishError(requestedProvider)}".`,
+                "Supported admin connectors: openai, anthropic, cursor, github-copilot."
             ].join("\n")
         };
     }
+    if (!args.authReference) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `sync-provider ${provider} requires --auth-reference env:NAME; raw secrets are not accepted.`
+        };
+    }
+    const usesRequestedTimeBounds = provider === "openai" || provider === "anthropic";
+    if (usesRequestedTimeBounds && args.startTime === undefined) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                `sync-provider ${provider} requires --start-time <unix seconds>; --end-time is optional.`,
+                `example: npx aibill sync-provider --provider ${provider} --auth-reference ${providerAdminEnvHint[provider]} --start-time 1750000000`
+            ].join("\n")
+        };
+    }
+    if (!usesRequestedTimeBounds && (args.startTime !== undefined || args.endTime !== undefined)) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: provider === "cursor"
+                ? "Cursor Admin spend is returned for the provider's current team subscription cycle; --start-time/--end-time are not accepted because the connector cannot enforce them."
+                : "GitHub Copilot returns its latest metrics-report window plus current seat data; --start-time/--end-time are not accepted because the connector cannot enforce them."
+        };
+    }
+    if (provider === "github-copilot" && Boolean(args.org) === Boolean(args.enterprise)) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "GitHub Copilot sync requires exactly one of --org <organization> or --enterprise <enterprise>."
+        };
+    }
     try {
         // A provider sync may merge only a prior connected snapshot whose exact
         // repository bytes have a matching external machine receipt. A cloned
@@ -2203,10 +2383,13 @@ async function syncProviderCommand(args) {
             ? priorSpend
             : undefined;
         const result = await fetchProviderUsageRecords({
-            provider: args.provider,
-            sourceId: `${args.provider}-provider-api`,
+            provider,
+            sourceId: `${provider}-provider-api`,
             authReference: args.authReference,
-            startTime: args.startTime,
+            // Core keeps a single connector input contract. Non-time-bounded
+            // adapters ignore this sentinel and the CLI rejects user-supplied bounds
+            // above so no requested interval can be silently discarded.
+            startTime: usesRequestedTimeBounds ? args.startTime : 0,
             endTime: args.endTime,
             org: args.org,
             enterprise: args.enterprise,
@@ -2306,18 +2489,23 @@ async function syncProviderCommand(args) {
             `financial evidence: ${syncedSource.financialEvidence}`,
             `coverage: ${result.coverage}`,
             `records fetched: ${result.records.length}`,
+            provider === "cursor"
+                ? "source window: current team subscription cycle returned by Cursor"
+                : provider === "github-copilot"
+                    ? "source window: latest Copilot metrics-report window plus current seat data"
+                    : `source window: requested from ${new Date(args.startTime * 1_000).toISOString()}${args.endTime === undefined ? " through provider current time" : ` through ${new Date(args.endTime * 1_000).toISOString()}`}`,
             `headline basis: ${syncedFinancials.headlineBasis}`,
             `synced provider headline: ${formatOptionalUsd(syncedFinancials.headlineUsd)}`,
             `combined headline spend: ${selectProviderFinancialHeadlineRecords(records).some((record) => typeof record.amountUsd === "number") ? formatOptionalUsd(summary.totalUsd) : "unavailable"}`,
             ...(syncedFinancials.apiEquivalentEstimatedUsd !== null
-                ? [`API-equivalent estimate (kept separate): $${syncedFinancials.apiEquivalentEstimatedUsd.toFixed(2)}`]
+                ? [`API-equivalent estimate (kept separate): ${formatOptionalUsd(syncedFinancials.apiEquivalentEstimatedUsd)}`]
                 : []),
             "auth: reference-only; raw secrets were not persisted or printed"
         ].join("\n"));
     }
     catch (error) {
         const sanitizedError = sanitizeSecretishError(error instanceof Error ? error.message : String(error), args.authReference);
-        await recordProviderSourceAttempt(stateDir, args.provider, new Date().toISOString(), sanitizedError).catch(() => {
+        await recordProviderSourceAttempt(stateDir, provider, new Date().toISOString(), sanitizedError).catch(() => {
             // Source-status state is diagnostic only. Do not hide the provider's
             // real error if derived-state persistence is unavailable.
         });
@@ -2427,11 +2615,11 @@ async function reportCommand(args) {
             `verification plan: ${artifactPaths.verificationPlan}`,
             `demo package: ${artifactPaths.demoPackage}`,
             reportInput.dataMode === "sample"
-                ? `DEMO SAMPLE · illustrative cost/value evidence total: $${reportInput.summary.totalUsd.toFixed(2)} · not user data`
+                ? `DEMO SAMPLE · illustrative cost/value evidence total: ${formatOptionalUsd(reportInput.summary.totalUsd)} · not user data`
                 : reportInput.dataMode === "connected_provider" &&
                     !(reportInput.allRecords ?? reportInput.providerRecords ?? []).some((record) => typeof record.amountUsd === "number")
                     ? "cost/value evidence total: Unavailable · no priced financial evidence; missing/null is not zero"
-                    : `cost/value evidence total: $${reportInput.summary.totalUsd.toFixed(2)}`,
+                    : `cost/value evidence total: ${formatOptionalUsd(reportInput.summary.totalUsd)}`,
             "privacy: report rendered locally with no aibill telemetry; only explicit sync-provider contacts the selected provider",
             "",
             "next:",
@@ -2446,7 +2634,7 @@ async function reportCommand(args) {
         return {
             exitCode: 1,
             stdout: "",
-            stderr: `Couldn't build a report: ${error instanceof Error ? error.message : String(error)}`
+            stderr: `Couldn't build a report: ${sanitizeSecretishError(error instanceof Error ? error.message : String(error))}`
         };
     }
 }
@@ -2470,7 +2658,10 @@ async function reportCardCommand(args) {
         // would reject a harmless receipt written from the user's home directory.
         // Output still goes through the safe-write/symlink checks below.
         const rootPath = args.sample ? resolve(args.path) : await resolveSafeScanRoot(args.path);
-        const { records, mode, providerCoverage } = await loadInstantReadData(args);
+        const { records, mode, providerCoverage, warnings } = await loadInstantReadData(args);
+        if (records.length === 0) {
+            return noEvidenceResult("report-card", warnings, args.sinceDays ?? 30);
+        }
         const headlineRecords = mode === "connected"
             ? selectProviderFinancialHeadlineRecords(records)
             : records;
@@ -2510,7 +2701,7 @@ async function reportCardCommand(args) {
         return {
             exitCode: 1,
             stdout: "",
-            stderr: `Couldn't write the report card: ${error instanceof Error ? error.message : String(error)}`
+            stderr: `Couldn't write the report card: ${sanitizeSecretishError(error instanceof Error ? error.message : String(error))}`
         };
     }
 }
@@ -2544,6 +2735,13 @@ async function applyArtifactCommand(args) {
                 codingPrompt.trimEnd()
             ].join("\n"));
         }
+        const noCandidateGuidance = codingPrompt.includes("NO SCOPED CHANGE CANDIDATE")
+            ? [
+                "",
+                "No scoped change is supported yet. Collect the missing source evidence instead of guessing:",
+                ...applyEvidenceAcquisitionLines(reportInput)
+            ]
+            : [];
         return ok([
             "aibill apply-artifact",
             `path: ${rootPath}`,
@@ -2552,6 +2750,7 @@ async function applyArtifactCommand(args) {
             `verification plan: ${artifactPaths.verificationPlan}`,
             `demo package: ${artifactPaths.demoPackage}`,
             "safety: generated artifacts only; no external systems changed",
+            ...noCandidateGuidance,
             "",
             `──── copy everything below into Claude Code / Codex (also saved at ${artifactPaths.codingPrompt}) ────`,
             "",
@@ -2562,10 +2761,35 @@ async function applyArtifactCommand(args) {
         return {
             exitCode: 1,
             stdout: "",
-            stderr: `Couldn't build apply artifacts: ${error instanceof Error ? error.message : String(error)}`
+            stderr: [
+                `Couldn't build apply artifacts: ${sanitizeSecretishError(error instanceof Error ? error.message : String(error))}`,
+                "Collect evidence, then retry Apply:",
+                "- Claude Code / Codex / Gemini CLI: use the agent normally so supported local history exists.",
+                "- OpenAI / Anthropic / Cursor / GitHub Copilot: run `npx aibill connect <provider>` with an admin credential reference.",
+                "- Diagnose the exact gap: `npx aibill doctor --sources`.",
+                "- Demo only: `npx aibill apply --sample` (non-executable)."
+            ].join("\n")
         };
     }
 }
+function applyEvidenceAcquisitionLines(input) {
+    const records = input.allRecords ?? input.providerRecords ?? [];
+    const providers = new Set(records.map((record) => record.source.provider));
+    const lines = [];
+    if (providers.has("anthropic") || providers.has("openai") || input.dataMode === "local_logs") {
+        lines.push("- Local coding agents: run `npx aibill context --json` after comparable Claude Code/Codex sessions to inspect action-capable context evidence.");
+    }
+    if (providers.has("gemini") || providers.has("gemini-cli")) {
+        lines.push("- Gemini CLI: current chat evidence is financial-only; unsupported context/action evidence remains missing.");
+    }
+    if (input.dataMode === "connected_provider") {
+        lines.push("- Provider billing: sync explicit call/invocation-level workload evidence; aggregate owner or spend rows do not authorize a change.");
+    }
+    if (lines.length === 0) {
+        lines.push("- Run `npx aibill doctor --sources` to see which local or provider evidence is missing.");
+    }
+    return lines;
+}
 async function buildExplicitSampleReportInput(rootPath) {
     const records = await loadSampleUsageData();
     return {
@@ -2703,7 +2927,8 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30) {
                 "Re-run `npx aibill` while the local transcripts are available; no report or Apply action was generated from repository state alone.");
         }
         throw new Error("no persisted spend state and no supported local-agent financial evidence found. " +
-            "Run `npx aibill` first (or `npx aibill scan --sample --path <dir>` for a demo-data report).");
+            "Use Claude Code, Codex, or Gemini CLI normally; connect an admin provider for billed cost; " +
+            "or run `npx aibill doctor --sources` to inspect the exact gap.");
     }
     const [discovery, sourceRegistry, missingSourcePrompts, confirmedMappings, persistedProviderRecordsState] = await Promise.all([
         readOptionalJson(join(stateDir, "discovery.json"), emptyDiscovery(rootPath)),
@@ -2851,7 +3076,8 @@ function parseArgs(argv) {
     const parsed = {
         command,
         sample: false,
-        path: process.cwd()
+        path: process.cwd(),
+        parseErrors: []
     };
     if (command === "statusline" && rest[0] && !rest[0].startsWith("--")) {
         parsed.statuslineAction = rest.shift();
@@ -2860,8 +3086,26 @@ function parseArgs(argv) {
         parsed.provider = rest[0];
         rest.shift();
     }
+    const valueFlags = new Set([
+        "--plan", "--since-days", "--path", "--out",
+        "--source-path", "--type", "--provider", "--source-id", "--team",
+        "--person", "--client", "--project", "--agent", "--workflow",
+        "--evidence", "--confidence", "--label", "--auth-reference",
+        "--start-time", "--end-time", "--org", "--enterprise", "--account-id",
+        "--interval", "--cycles"
+    ]);
+    const numericValueFlags = new Set([
+        "--since-days", "--confidence", "--start-time", "--end-time", "--interval", "--cycles"
+    ]);
     for (let index = 0; index < rest.length; index += 1) {
         const arg = rest[index];
+        const nextValue = rest[index + 1];
+        const nextLooksLikeFlag = nextValue?.startsWith("--") ||
+            (!numericValueFlags.has(arg) && nextValue?.startsWith("-"));
+        if (valueFlags.has(arg) && (nextValue === undefined || nextLooksLikeFlag)) {
+            parsed.parseErrors.push(`${arg} requires a value`);
+            continue;
+        }
         if (arg === "--sample") {
             parsed.sample = true;
             continue;
@@ -2874,6 +3118,10 @@ function parseArgs(argv) {
             parsed.json = true;
             continue;
         }
+        if (arg === "--full") {
+            parsed.full = true;
+            continue;
+        }
         if (arg === "--sources") {
             parsed.sources = true;
             continue;
@@ -2957,6 +3205,10 @@ function parseArgs(argv) {
                 parsed.sourceType = next;
                 index += 1;
             }
+            else if (next) {
+                parsed.parseErrors.push(`--type received unsupported source type "${next}"`);
+                index += 1;
+            }
             continue;
         }
         if (arg === "--provider") {
@@ -3039,6 +3291,9 @@ function parseArgs(argv) {
                 if (Number.isFinite(value) && value >= 0 && value <= 1) {
                     parsed.confidence = value;
                 }
+                else {
+                    parsed.parseErrors.push("--confidence must be a number between 0 and 1");
+                }
                 index += 1;
             }
             continue;
@@ -3062,7 +3317,11 @@ function parseArgs(argv) {
         if (arg === "--start-time") {
             const next = rest[index + 1];
             if (next) {
-                parsed.startTime = Number(next);
+                const value = Number(next);
+                if (Number.isFinite(value))
+                    parsed.startTime = value;
+                else
+                    parsed.parseErrors.push("--start-time must be a finite Unix timestamp");
                 index += 1;
             }
             continue;
@@ -3070,7 +3329,11 @@ function parseArgs(argv) {
         if (arg === "--end-time") {
             const next = rest[index + 1];
             if (next) {
-                parsed.endTime = Number(next);
+                const value = Number(next);
+                if (Number.isFinite(value))
+                    parsed.endTime = value;
+                else
+                    parsed.parseErrors.push("--end-time must be a finite Unix timestamp");
                 index += 1;
             }
             continue;
@@ -3102,7 +3365,11 @@ function parseArgs(argv) {
         if (arg === "--interval") {
             const next = rest[index + 1];
             if (next) {
-                parsed.interval = Number(next);
+                const value = Number(next);
+                if (Number.isFinite(value) && value > 0)
+                    parsed.interval = value;
+                else
+                    parsed.parseErrors.push("--interval must be a positive number of seconds");
                 index += 1;
             }
             continue;
@@ -3110,11 +3377,18 @@ function parseArgs(argv) {
         if (arg === "--cycles") {
             const next = rest[index + 1];
             if (next) {
-                parsed.cycles = Number(next);
+                const value = Number(next);
+                if (Number.isInteger(value) && value >= 0)
+                    parsed.cycles = value;
+                else
+                    parsed.parseErrors.push("--cycles must be a whole number of 0 or greater");
                 index += 1;
             }
             continue;
         }
+        parsed.parseErrors.push(arg.startsWith("-")
+            ? `unknown flag "${arg}"`
+            : `unexpected argument "${arg}"`);
     }
     return parsed;
 }
@@ -3242,7 +3516,9 @@ function helpText() {
         "aibill — your AI cost and usage evidence in one private view",
         "",
         "Run with no command for an instant, zero-key local readout:",
-        "  npx aibill                           Show available AI cost/value evidence (sample or local data)",
+        "  npx aibill                           Show a compact receipt from available local/connected evidence",
+        "  npx aibill --full                    Show the complete diagnose → recommend → apply → verify audit",
+        "  npx aibill --sample                  Show the clearly labeled illustrative demo (never implicit)",
         "  npx aibill --group-by agent          Drill down by source|model|client|project|agent|user|workspace|apiKey",
         "  npx aibill --plan <id>               Declare your plan when auto-detection can't (claude-max-5x|claude-max-20x|claude-pro|chatgpt-plus|chatgpt-pro)",
         "",
@@ -3272,12 +3548,14 @@ function helpText() {
         "  scan [--path <dir>]     Scan a local workspace for AI usage signals",
         "  scan --sample           Include deterministic sample spend analysis",
         "  quickstart [--sample] [--since-days N] Plain-English local readout (default 30 days)",
+        "    [--full]            Render the complete audit; default is the compact receipt",
         "    [--group-by source|model|client|project|agent|user|workspace|apiKey]  Default: project for local logs; model otherwise",
         "  report [--sample] [--out <name>] [--since-days N] Generate local Markdown and HTML reports from the same window",
         "  report-card [--out f.svg] Write your AI Receipt — a redacted, shareable SVG + caption",
         "  glance [--project <name>] [--plan <id>] [--since-days N] Emit the local, machine-readable Glance snapshot JSON",
         "  context [--project <name>] [--since-days N] Show hook-aware Context Health in the terminal",
         "    [--json]              Emit the same canonical Context Health object used by MCP and Glance",
+        "  Main receipt JSON is not published yet; unsupported --json requests fail instead of returning text.",
         "  apply [--sample] [--since-days N]  Print an evidence-constrained inspection/approval prompt + verification plans",
         "  apply-artifact          Same as `apply` (long form)",
         "",
@@ -3326,7 +3604,7 @@ export async function runMain() {
     if (isInstantDemo && process.stdout.isTTY && !process.env.NO_COLOR) {
         try {
             const { default: yoctoSpinner } = await import("yocto-spinner");
-            spinner = yoctoSpinner({ text: "Analyzing your AI spend…" }).start();
+            spinner = yoctoSpinner({ text: "Reading local AI evidence…" }).start();
         }
         catch {
             // Spinner is optional; never block the wow on it.

package/dist/statuslineRuntime.js

@@ -17,6 +17,11 @@ const CACHE_MAX_BYTES = 64 * 1_024;
 const DEFAULT_COLUMNS = 100;
 const MAX_COLUMNS = 240;
 const STALE_AFTER_MS = 5 * 60 * 1_000;
+// A freshly regenerated cache does not make an old transcript percentage current.
+// Five-hour evidence expires with that window; weekly evidence must have been
+// observed within the last day before it can be presented as live runway.
+const FIVE_HOUR_LIMIT_FRESHNESS_MS = 5 * 60 * 60 * 1_000;
+const WEEKLY_LIMIT_FRESHNESS_MS = 24 * 60 * 60 * 1_000;
 const STDIN_MAX_BYTES = 64 * 1_024;
 const STDIN_DRAIN_TIMEOUT_MS = 25;
 const guardedOutputs = new WeakSet();
@@ -276,8 +281,9 @@ function renderSubscription(snapshot, tier, now, timeZone) {
         ? [...limits].sort((left, right) => limitKindOrder(left.kind) - limitKindOrder(right.kind))
         : [...limits].sort(compareUrgency).slice(0, 1);
     const segments = ordered.map((limit) => formatLimit(limit, now, timeZone));
-    if (limits.length === 0)
-        segments.push("subscription detected", "runway not reported");
+    if (limits.length === 0) {
+        segments.push("subscription detected", missingRunwaySegment(snapshot, now));
+    }
     const value = agent.apiEquivalent.sevenDays;
     if (value.amountUsd !== null && value.financialEvidence === "estimated") {
         segments.push(`~${formatUsd(value.amountUsd)} 7d value`);
@@ -299,8 +305,9 @@ function renderMixed(snapshot, tier, now, timeZone) {
         ? [...limits].sort((left, right) => limitKindOrder(left.kind) - limitKindOrder(right.kind))
         : [...limits].sort(compareUrgency).slice(0, 1);
     const segments = selectedLimits.map((limit) => formatLimit(limit, now, timeZone));
-    if (limits.length === 0 && tier !== "minimal")
-        segments.push("runway not reported");
+    if (limits.length === 0 && tier !== "minimal") {
+        segments.push(missingRunwaySegment(snapshot, now));
+    }
     appendMeteredSevenDaySegment(snapshot, segments);
     const value = agent?.apiEquivalent.sevenDays;
     if (value?.amountUsd !== null && value?.amountUsd !== undefined &&
@@ -318,8 +325,12 @@ function renderMultiSubscriptionSegments(snapshot, tier, now, timeZone) {
     const segments = selected.map(({ agent, limit }) => tier === "full"
         ? formatAttributedLimit(agent, limit, now, timeZone)
         : formatAttributedLimitCompact(agent, limit));
-    if (entries.length === 0 && tier !== "minimal") {
-        segments.push("subscription detected", "runway not reported");
+    const staleRunway = staleRunwaySegments(snapshot, now);
+    if (staleRunway.length > 0 && tier !== "minimal") {
+        segments.push(...staleRunway);
+    }
+    else if (entries.length === 0 && tier !== "minimal") {
+        segments.push("subscription detected", missingRunwaySegment(snapshot, now));
     }
     const agents = orderedSubscriptionAgents(snapshot, now);
     const valueAgents = tier === "full" ? agents : agents.slice(0, 1);
@@ -422,7 +433,30 @@ function latestLimitObservation(agent, now) {
     return Math.max(0, ...activeLimits(agent, now).map((limit) => Date.parse(limit.observedAt)));
 }
 function activeLimits(agent, now) {
-    return agent.limits.filter((limit) => Date.parse(limit.resetsAt) > now.getTime());
+    return agent.limits.filter((limit) => (Date.parse(limit.resetsAt) > now.getTime() && isFreshLimitEvidence(limit, now)));
+}
+function staleActiveLimits(agent, now) {
+    return agent.limits.filter((limit) => (Date.parse(limit.resetsAt) > now.getTime() && !isFreshLimitEvidence(limit, now)));
+}
+function isFreshLimitEvidence(limit, now) {
+    const observedMs = Date.parse(limit.observedAt);
+    const ageMs = now.getTime() - observedMs;
+    const maximumAgeMs = limit.kind === "five-hour"
+        ? FIVE_HOUR_LIMIT_FRESHNESS_MS
+        : WEEKLY_LIMIT_FRESHNESS_MS;
+    return Number.isFinite(observedMs) && ageMs >= 0 && ageMs <= maximumAgeMs;
+}
+function hasStaleLimitEvidence(snapshot, now) {
+    return (snapshot.subscription?.agents ?? [])
+        .some((agent) => staleActiveLimits(agent, now).length > 0);
+}
+function missingRunwaySegment(snapshot, now) {
+    return hasStaleLimitEvidence(snapshot, now) ? "runway stale" : "runway not reported";
+}
+function staleRunwaySegments(snapshot, now) {
+    return orderedSubscriptionAgents(snapshot, now)
+        .filter((agent) => activeLimits(agent, now).length === 0 && staleActiveLimits(agent, now).length > 0)
+        .map((agent) => `${subscriptionAgentLabel(agent)} runway stale`);
 }
 function compareUrgency(left, right) {
     const remainingDifference = left.remainingPercent - right.remainingPercent;
@@ -516,6 +550,8 @@ function formatAge(rawAgeMs) {
     return `${Math.floor(hours / 24)}d`;
 }
 function formatUsd(amount) {
+    if (amount > 0 && amount < 0.01)
+        return "<$0.01";
     if (amount >= 1_000_000_000)
         return `$${compactNumber(amount / 1_000_000_000)}b`;
     if (amount >= 1_000_000)
@@ -574,7 +610,9 @@ function assembleMultiSubscriptionOverageLine(snapshot, fullSegments, overage, f
 function assembleMixedLine(snapshot, fullSegments, freshness, tier, columns, now, timeZone) {
     const agent = selectSubscriptionAgent(snapshot, now);
     const urgent = agent ? [...activeLimits(agent, now)].sort(compareUrgency)[0] : undefined;
-    const runway = urgent ? formatLimitCompact(urgent) : "runway n/r";
+    const runway = urgent
+        ? formatLimitCompact(urgent)
+        : hasStaleLimitEvidence(snapshot, now) ? "runway stale" : "runway n/r";
     const runwayWithReset = urgent
         ? `${runway} ↻${formatReset(urgent, now, timeZone)}`
         : runway;
@@ -625,7 +663,10 @@ function assembleMultiSubscriptionLine(snapshot, freshness, tier, columns, now,
     const pressure = agents
         .filter((agent) => agent.pressure === "extra_usage_credits_exhausted")
         .map((agent) => `${subscriptionAgentLabel(agent)} plan pressure`);
-    const noRunway = entries.length === 0 ? ["subscription detected", "runway not reported"] : [];
+    const staleRunway = staleRunwaySegments(snapshot, now);
+    const noRunway = entries.length === 0 && staleRunway.length === 0
+        ? ["subscription detected", "runway not reported"]
+        : staleRunway;
     const urgent = compactPrimary[0];
     const urgentValue = agents[0] ? formatAttributedValue(agents[0], true) : undefined;
     const candidates = [];
@@ -641,7 +682,8 @@ function assembleMultiSubscriptionLine(snapshot, freshness, tier, columns, now,
         candidates.push(["aibill", urgent, freshness], ["aibill", urgent], [urgent]);
     }
     else {
-        candidates.push(["aibill", "runway n/r", freshness], ["runway n/r", freshness], ["aibill", ...noRunway, ...compactValues, freshness], ["aibill", ...compactValues, freshness], ["aibill", "subscription detected", freshness], ["subscription detected"]);
+        const compactRunway = hasStaleLimitEvidence(snapshot, now) ? "runway stale" : "runway n/r";
+        candidates.push(["aibill", compactRunway, freshness], [compactRunway, freshness], ["aibill", ...noRunway, ...compactValues, freshness], ["aibill", ...compactValues, freshness], ["aibill", "subscription detected", freshness], ["subscription detected"]);
     }
     return firstFittingLine(candidates, columns);
 }
@@ -652,7 +694,10 @@ function assembleMultiSubscriptionMixedLine(snapshot, fullSegments, freshness, t
     const compactLimits = entries.map(({ agent, limit }) => formatAttributedLimitCompact(agent, limit));
     const compactPrimary = primary.map(({ agent, limit }) => formatAttributedLimitCompact(agent, limit));
     const compactValues = agents.flatMap((agent) => formatAttributedValue(agent, true) ?? []);
-    const noRunway = entries.length === 0 ? ["subscription detected", "runway not reported"] : [];
+    const staleRunway = staleRunwaySegments(snapshot, now);
+    const noRunway = entries.length === 0 && staleRunway.length === 0
+        ? ["subscription detected", "runway not reported"]
+        : staleRunway;
     const urgent = compactPrimary[0];
     const urgentValue = agents[0] ? formatAttributedValue(agents[0], true) : undefined;
     const meteredBilled = snapshot.metered?.providerBilled.sevenDays;
@@ -665,6 +710,7 @@ function assembleMultiSubscriptionMixedLine(snapshot, fullSegments, freshness, t
             ? `metered ~${formatUsd(meteredEstimated.amountUsd)}/7d`
             : "metered n/r";
     const shortFreshness = compactFreshness(freshness);
+    const compactRunway = hasStaleLimitEvidence(snapshot, now) ? "runway stale" : "runway n/r";
     const candidates = [];
     if (tier === "full")
         candidates.push(["aibill", ...fullSegments, freshness]);
@@ -677,7 +723,7 @@ function assembleMultiSubscriptionMixedLine(snapshot, fullSegments, freshness, t
         candidates.push(["aibill", "mix", urgent, metered, shortFreshness], ["mix", urgent, metered], ["aibill", urgent, shortFreshness], ["aibill", urgent], [urgent]);
     }
     else {
-        candidates.push(["aibill", "mix", ...noRunway, metered, freshness], ["aibill", ...noRunway, freshness], ["aibill", "mix", "runway n/r", metered, shortFreshness], ["mix", "runway n/r", metered, shortFreshness], ["mix", "runway n/r", shortFreshness]);
+        candidates.push(["aibill", "mix", ...noRunway, metered, freshness], ["aibill", ...noRunway, freshness], ["aibill", "mix", compactRunway, metered, shortFreshness], ["mix", compactRunway, metered, shortFreshness], ["mix", compactRunway, shortFreshness]);
     }
     candidates.push(["mix", metered, shortFreshness], ["mix", metered], ["mix"]);
     return firstFittingLine(candidates, columns);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spend-agent",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Local-first financial accountability CLI: Claude Code/Codex attribution, provenance, and next actions, plus experimental Gemini CLI cost evidence.",
   "type": "module",
   "main": "./dist/index.js",
@@ -54,8 +54,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@agent-finops/core": "0.8.0",
-    "@agent-finops/report": "0.8.0",
+    "@agent-finops/core": "0.8.1",
+    "@agent-finops/report": "0.8.1",
     "yocto-spinner": "^1.2.0"
   }
 }