ai-spend-agent 0.5.5 → 0.5.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Futura Studio LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,40 +1,19 @@
 # ai-spend-agent
 
-**Your AI spend in one view, in 90 seconds — local-first, no signup.**
+The full [aibill](https://github.com/futurastudio/ai-spend-agent) CLI.
 
 ```bash
 npx ai-spend-agent
+# short alias
+npx aibill
 ```
 
-If you use **Claude Code or Codex**, that one command reads the session logs
-already on your machine and shows your real usage: total dollars *estimated at
-API-equivalent rates*, where the money goes, a ranked "where to cut" list, a
-subscription-vs-API **plan check**, and the **dead context** you pay for but
-never use (tools/skills/MCP servers loaded on every turn and never invoked).
+It reads local Claude Code and Codex metadata, labels API-equivalent estimates,
+and can optionally add official OpenAI or Anthropic provider-reported cost
+through an environment-variable reference. No product telemetry is sent.
 
-No logs? You get an instant, clearly-labeled demo on sample data.
-
-## Connect real billing (optional, ~2 min)
-
-```bash
-ai-spend-agent connect openai      # org-owner Admin key
-ai-spend-agent connect anthropic   # Admin key
-```
-
-Billing-API numbers from OpenAI/Anthropic are tagged `verified`; local-log
-numbers are always `estimated`; the beta Cursor/Copilot connectors are
-`estimated` until reconciled against a real invoice. Every figure carries its
-confidence label — that's the product.
-
-## Privacy
-
-Local-first: nothing is uploaded, there is no telemetry, secrets are
-redacted from all output and persisted state, and provider keys are only ever
-referenced as `env:NAME` — never stored.
-
-## Docs
-
-Full README, MCP server, and connector guides:
-**https://github.com/futurastudio/ai-spend-agent#readme**
+See the repository
+[README](https://github.com/futurastudio/ai-spend-agent#readme) for commands,
+privacy boundaries, supported sources, and public-beta limitations.
 
 MIT licensed.

package/dist/index.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
-import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { dirname, extname, join, resolve } from "node:path";
+import { mkdir, readFile, rm, stat } from "node:fs/promises";
+import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { analyzeSpend, attributeUsageRecords, detectLocalCredentials, detectLocalPlans, redactSecrets, subscriptionPlans, unsafeScanRootReason, loadDeadContext, sampleDeadContext, loadLocalAgentUsage, loadSampleUsageData, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProviderConnectorStub, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, slugifySourceId } from "@agent-finops/core";
+import { analyzeSpend, attributeUsageRecords, buildUsageGlance, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, writeSafeStateText, loadDeadContext, sampleDeadContext, loadLocalAgentUsage, loadSampleUsageData, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProviderConnectorStub, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, slugifySourceId } from "@agent-finops/core";
 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)) {
+    if (argv.includes("--version") || argv.includes("-v")) {
+        return ok(await cliVersion());
+    }
     if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
         return ok(helpText());
     }
@@ -48,6 +51,12 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (args.command === "report-card") {
         return reportCardCommand(args);
     }
+    if (args.command === "glance") {
+        return glanceCommand(args);
+    }
+    if (args.command === "context" || args.command === "context-health") {
+        return contextHealthCommand(args);
+    }
     if (args.command === "apply-artifact" || args.command === "apply") {
         return applyArtifactCommand(args);
     }
@@ -74,7 +83,10 @@ export async function runCli(argv = process.argv.slice(2)) {
 }
 async function quickstartCommand(args) {
     const { records, mode, warnings } = await loadInstantReadData(args);
-    const summary = analyzeSpend(records);
+    const summaryRecords = mode === "connected"
+        ? selectProviderFinancialHeadlineRecords(records)
+        : records;
+    const summary = analyzeSpend(summaryRecords);
     // For real local-log users the by-project view is the flagship table
     // ("which project burns my plan"); demo/connected keep by-model.
     const groupBy = args.groupBy ?? (mode === "local-logs" ? "project" : "model");
@@ -113,8 +125,11 @@ async function quickstartCommand(args) {
         : await loadDeadContext({
             // 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,
             claudeHomeDir: process.env.AI_SPEND_CLAUDE_HOME_DIR,
+            codexHomeDir: process.env.AI_SPEND_CODEX_HOME_DIR,
             claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
+            claudeSettingsPath: process.env.AI_SPEND_CLAUDE_SETTINGS,
             projectDir: resolve(args.path),
             includeAllProjectMcp: true,
             sinceIso: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
@@ -127,7 +142,7 @@ async function quickstartCommand(args) {
         deadContext = sampleDeadContext();
     }
     const summaryText = generatePlainEnglishSummary(summary, {
-        records,
+        records: summaryRecords,
         groupBy,
         color,
         mode,
@@ -141,6 +156,137 @@ async function quickstartCommand(args) {
     const header = [`  ${dataModeBanner(mode)}`, ...warnings.map((warning) => `  ! ${warning}`)].join("\n");
     return ok(`${header}\n${summaryText}`);
 }
+async function glanceCommand(args) {
+    const sinceDays = args.sinceDays ?? 30;
+    if (!Number.isInteger(sinceDays) || sinceDays < 1 || sinceDays > 365) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "--since-days must be a whole number between 1 and 365"
+        };
+    }
+    const logs = await loadLocalAgentUsage({
+        claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
+        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+        sinceIso: new Date(Date.now() - sinceDays * 24 * 60 * 60 * 1_000).toISOString()
+    });
+    const calls = args.project
+        ? logs.calls.filter((call) => call.project === args.project)
+        : logs.calls;
+    let detectedPlans;
+    if (args.plan) {
+        const override = planOverrideFromFlag(args.plan);
+        if (!override) {
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: `Unknown --plan "${args.plan}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
+            };
+        }
+        detectedPlans = [override];
+    }
+    else {
+        detectedPlans = await detectLocalPlans({
+            claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
+            codexAuthPath: process.env.AI_SPEND_CODEX_AUTH
+        }).catch(() => []);
+    }
+    const contextHealth = await loadContextHealth(calls, {
+        claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
+        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+        claudeHomeDir: process.env.AI_SPEND_CLAUDE_HOME_DIR,
+        codexHomeDir: process.env.AI_SPEND_CODEX_HOME_DIR,
+        claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
+        claudeSettingsPath: process.env.AI_SPEND_CLAUDE_SETTINGS,
+        projectDir: resolve(args.path),
+        sinceIso: new Date(Date.now() - sinceDays * 24 * 60 * 60 * 1_000).toISOString(),
+        windowDays: sinceDays
+    });
+    const snapshot = buildUsageGlance(calls, {
+        filesParsed: logs.filesParsed,
+        detectedAgents: logs.agentsDetected,
+        detectedPlans,
+        limitCalls: logs.calls,
+        contextHealth
+    });
+    return ok(JSON.stringify(snapshot));
+}
+async function contextHealthCommand(args) {
+    const sinceDays = args.sinceDays ?? 30;
+    if (!Number.isInteger(sinceDays) || sinceDays < 1 || sinceDays > 365) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "--since-days must be a whole number between 1 and 365"
+        };
+    }
+    const sinceIso = new Date(Date.now() - sinceDays * 24 * 60 * 60 * 1_000).toISOString();
+    const logs = await loadLocalAgentUsage({
+        claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
+        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+        sinceIso
+    });
+    const calls = args.project
+        ? logs.calls.filter((call) => call.project === args.project)
+        : logs.calls;
+    const health = await loadContextHealth(calls, {
+        claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
+        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+        claudeHomeDir: process.env.AI_SPEND_CLAUDE_HOME_DIR,
+        codexHomeDir: process.env.AI_SPEND_CODEX_HOME_DIR,
+        claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
+        claudeSettingsPath: process.env.AI_SPEND_CLAUDE_SETTINGS,
+        projectDir: resolve(args.path),
+        sinceIso,
+        windowDays: sinceDays
+    });
+    return ok(args.json ? JSON.stringify(health) : renderContextHealth(health));
+}
+function renderContextHealth(health) {
+    const status = health.status.replace("_", " ").toUpperCase();
+    const activation = health.activation;
+    const dead = health.deadContext;
+    const lines = [
+        `CONTEXT HEALTH  ${status}`,
+        health.headline,
+        "",
+        `Action: ${health.action}`,
+        `Confidence: ${health.confidence}`,
+        "",
+        "Activation",
+        `  Discoverable: ${activation.discoverableItems}  Invoked: ${activation.explicitlyInvokedItems}  MCP schema-loaded: ${activation.mcpSchemaLoadedItems}`,
+        `  Hook-injected: ${activation.hookInjectedItems}  Other lifecycle hooks: ${activation.lifecycleHooks}  Unmeasured weight: ${activation.unmeasuredItems}`,
+        `  Invocation-unobservable: ${activation.invocationUnobservableItems}`,
+        "",
+        `Never invoked among observable inventory (${dead.windowDays}d): ${dead.neverInvokedItems}/${dead.loadedItems} ` +
+            `(${dead.measuredNeverInvokedItems} measured, ${dead.unmeasuredNeverInvokedItems} unmeasured)`
+    ];
+    if (health.currentSession) {
+        const session = health.currentSession;
+        lines.push(`Session: ${session.agent}${session.project ? ` · ${session.project}` : ""} · ` +
+            `${session.totalTokens.toLocaleString("en-US")} tokens · ` +
+            (session.ratioToMedian === null
+                ? "no same-agent baseline"
+                : `${session.ratioToMedian}× median (${session.comparisonSessions} prior)`));
+    }
+    const churn = health.contextChurn;
+    if (churn.currentSessionEvidence === "matched") {
+        lines.push(`Context churn: ${churn.compactionEvents ?? 0} compaction event${churn.compactionEvents === 1 ? "" : "s"} · ` +
+            `${churn.repeatedReadEvents ?? 0} repeat explicit read${churn.repeatedReadEvents === 1 ? "" : "s"} · ` +
+            `${churn.currentSessionScope ?? "unknown"} session`);
+    }
+    else {
+        lines.push(`Context churn: current transcript ${churn.currentSessionEvidence === "not_matched" ? "not matched" : "unavailable"}`);
+    }
+    if (health.evidence.length > 0) {
+        lines.push("", "Evidence");
+        for (const evidence of health.evidence) {
+            lines.push(`  - ${evidence.summary} [${evidence.confidence}; ${evidence.source}]`);
+        }
+    }
+    lines.push("", "Data: local agent configuration + local Claude Code/Codex transcripts; hook commands were not run.", "Privacy: this CLI run uploads nothing.");
+    return lines.join("\n");
+}
 function quickstartNextSteps(mode, detected) {
     // Connect/verify guidance now lives in the readout's APPLY/VERIFY sections;
     // this footer only carries what those can't know (detected local keys) and
@@ -149,11 +295,11 @@ 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 ai-spend-agent connect ${detected[0].provider}   use it — note: COST data needs an ADMIN/owner key`);
+        steps.push(`npx aibill connect ${detected[0].provider}   add official provider-reported cost (ADMIN/owner key)`);
     }
     steps.push("npx aibill report              write a shareable Markdown + HTML report");
-    steps.push("npx aibill --group-by project  see which project burns the most");
-    steps.push("Want this watched while your laptop is off? Hosted beta waitlist: https://ai-spend-agent.vercel.app");
+    steps.push("npx aibill --group-by project  see which project has the most observed activity");
+    steps.push("Need team reconciliation, allocation, budgets, and approvals? Workspace design partners: https://ai-spend-agent.vercel.app");
     return steps;
 }
 async function readPersistedSpend(rootPath) {
@@ -246,7 +392,7 @@ async function doctorCommand(args) {
     if (!hasLogs)
         warnings.push("no real Claude Code / Codex logs found — a first run here will show DEMO sample data");
     if (providerRefs.length === 0)
-        warnings.push("no provider admin keys detected — connect OpenAI/Anthropic for VERIFIED billing (local logs stay ESTIMATED)");
+        warnings.push("no provider admin keys detected — connect OpenAI/Anthropic to add official provider-reported cost (local logs stay API-equivalent estimates)");
     const predictedMode = stateMode === "connected_provider"
         ? "connected provider billing"
         : hasLogs
@@ -282,8 +428,21 @@ async function cliVersion() {
     }
 }
 async function resetCommand(args) {
-    const rootPath = resolve(args.path);
-    const stateDir = join(rootPath, ".ai-spend-agent");
+    const rootPath = await resolveSafeScanRoot(args.path);
+    let stateDir;
+    try {
+        stateDir = await resolveSafeStateDirectory(rootPath);
+    }
+    catch (error) {
+        if (!isNodeError(error, "ENOENT"))
+            throw error;
+        return ok([
+            "AI Spend Analyst 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)."
+        ].join("\n"));
+    }
     // Clear derived spend state so a prior `scan --sample` (or stale provider
     // sync) can never mask the next real local-log read. Leaves sources/audit.
     const targets = ["spend.json", "mappings.json", "provider-records.json", "watch-latest.json", "watch-history.json"];
@@ -530,7 +689,10 @@ async function runWatchCycle(stateDir, args) {
             }
         }
     }
-    const summary = analyzeSpend(records);
+    const headlineRecords = mode === "connected_provider"
+        ? selectProviderFinancialHeadlineRecords(records)
+        : records;
+    const summary = analyzeSpend(headlineRecords);
     const mappings = attributeUsageRecords(records);
     await writeLocalSpendState(stateDir, records, summary, mappings, mode);
     const snapshot = {
@@ -549,7 +711,7 @@ async function runWatchCycle(stateDir, args) {
         sourceId: "watch",
         detail: `Watch cycle captured ${snapshot.recordCount} records totaling $${snapshot.totalUsd.toFixed(2)}.`
     });
-    return { summary, snapshot, records, mode };
+    return { summary, snapshot, records: headlineRecords, mode };
 }
 function buildDeltaHeadline(previous, current) {
     if (!previous) {
@@ -771,34 +933,68 @@ async function syncProviderCommand(args) {
             enterprise: args.enterprise,
             accountId: args.accountId
         });
+        const priorProviderState = await readOptionalJson(join(stateDir, "provider-records.json"), { records: [] });
+        const records = [
+            ...priorProviderState.records.filter((record) => record.source.provider !== result.provider),
+            ...result.records
+        ].sort((left, right) => left.timestamp.localeCompare(right.timestamp));
         const registry = await readSourceRegistry(stateDir, rootPath);
         const nextRegistry = addApprovedSource(registry, result.source);
-        const summary = analyzeSpend(result.records);
-        const mappings = attributeUsageRecords(result.records);
+        const headlineRecords = selectProviderFinancialHeadlineRecords(records);
+        const summary = analyzeSpend(headlineRecords);
+        const mappings = attributeUsageRecords(records);
+        const qaByProvider = {
+            ...(priorProviderState.qaByProvider ?? {}),
+            [result.provider]: result.qa
+        };
+        const coverageByProvider = {
+            ...(priorProviderState.coverageByProvider ?? {}),
+            [result.provider]: result.coverage
+        };
+        const financialsByProvider = {
+            ...(priorProviderState.financialsByProvider ?? {}),
+            [result.provider]: result.financials
+        };
         await mkdir(stateDir, { recursive: true });
         await writeJson(join(stateDir, "sources.json"), nextRegistry);
         await writeJson(join(stateDir, "provider-records.json"), {
             provider: result.provider,
             fetchedAt: result.fetchedAt,
             completeness: result.completeness,
+            coverage: result.coverage,
+            financials: result.financials,
             sourceId: result.source.id,
-            records: result.records,
-            qa: result.qa
+            records,
+            qa: result.qa,
+            qaByProvider,
+            coverageByProvider,
+            financialsByProvider
+        });
+        await writeLocalSpendState(stateDir, records, summary, mappings, "connected_provider", {
+            policy: "provider_reported_billed_cost_preferred",
+            note: "Official provider-reported billed costs are the spend headline. API-equivalent estimates remain separate evidence and are not added to that total.",
+            coverageByProvider,
+            financialsByProvider
         });
-        await writeLocalSpendState(stateDir, result.records, summary, mappings, "connected_provider");
         await appendAuditEvent(stateDir, {
             timestamp: result.fetchedAt,
             action: "source_scanned",
             sourceId: result.source.id,
-            detail: `${args.provider} provider connector synced ${result.records.length} verified records. Auth reference only; no raw secrets stored.`
+            detail: `${args.provider} provider connector synced ${result.records.length} evidence records with ${result.coverage} coverage. Auth reference only; no raw secrets stored.`
         });
         return ok([
             "AI Spend Analyst Agent sync-provider",
             `provider: ${result.provider}`,
             `source: ${result.source.id}`,
             `verification: ${result.source.verification}`,
-            `verified records: ${result.records.length}`,
-            `total spend: $${summary.totalUsd.toFixed(2)}`,
+            `coverage: ${result.coverage}`,
+            `records fetched: ${result.records.length}`,
+            `headline basis: ${result.financials.headlineBasis}`,
+            `synced provider headline: $${(result.financials.headlineUsd ?? 0).toFixed(2)}`,
+            `combined headline spend: $${summary.totalUsd.toFixed(2)}`,
+            ...(result.financials.apiEquivalentEstimatedUsd !== null
+                ? [`API-equivalent estimate (kept separate): $${result.financials.apiEquivalentEstimatedUsd.toFixed(2)}`]
+                : []),
             "auth: reference-only; raw secrets were not persisted or printed"
         ].join("\n"));
     }
@@ -854,8 +1050,8 @@ async function reportCommand(args) {
         const outBase = args.out ? resolve(rootPath, args.out) : join(stateDir, "report");
         const markdownPath = `${outBase}.md`;
         const htmlPath = `${outBase}.html`;
-        await writeFile(markdownPath, generateMarkdownReport(reportInput), "utf8");
-        await writeFile(htmlPath, generateHtmlReport(reportInput), "utf8");
+        await writeLocalReportFile(markdownPath, generateMarkdownReport(reportInput), stateDir);
+        await writeLocalReportFile(htmlPath, generateHtmlReport(reportInput), stateDir);
         const artifactPaths = await writeApplyArtifacts(stateDir, reportInput);
         return ok([
             "AI Spend Analyst Agent report",
@@ -899,27 +1095,39 @@ async function resolveReceiptPath(rootPath, out) {
     return extname(resolved) ? resolved : `${resolved}.svg`;
 }
 async function reportCardCommand(args) {
-    const rootPath = resolve(args.path);
-    const { records, mode } = await loadInstantReadData(args);
-    const summary = analyzeSpend(records);
-    const outPath = await resolveReceiptPath(rootPath, args.out);
-    await mkdir(dirname(outPath), { recursive: true });
-    await writeFile(outPath, generateReportCardSvg({ summary, records }), "utf8");
-    const dataLine = mode === "demo"
-        ? "data: DEMO sample data — run without --sample on a machine with Claude Code/Codex logs for your own numbers."
-        : mode === "local-logs"
-            ? "data: local Claude Code/Codex logs priced at API-equivalent rates."
-            : "data: connected local spend state.";
-    return ok([
-        "Your AI Receipt — a shareable, redacted spend card (no client/project/user names).",
-        `receipt: ${outPath}`,
-        dataLine,
-        "",
-        "Caption to share:",
-        generateReportCardCaption({ summary, records }),
-        "",
-        "privacy: rendered locally; only totals, savings, and model-level cuts are included."
-    ].join("\n"));
+    try {
+        const rootPath = await resolveSafeScanRoot(args.path);
+        const { records, mode } = await loadInstantReadData(args);
+        const headlineRecords = mode === "connected"
+            ? selectProviderFinancialHeadlineRecords(records)
+            : records;
+        const summary = analyzeSpend(headlineRecords);
+        const outPath = await resolveReceiptPath(rootPath, args.out);
+        await mkdir(dirname(outPath), { recursive: true });
+        await writeSafeStateText(dirname(outPath), basename(outPath), generateReportCardSvg({ summary, records: headlineRecords, mode }));
+        const dataLine = mode === "demo"
+            ? "data: DEMO sample data — run without --sample on a machine with Claude Code/Codex logs for your own numbers."
+            : mode === "local-logs"
+                ? "data: local Claude Code/Codex logs priced at API-equivalent rates."
+                : "data: connected local spend state with provider-reported cost kept separate from API-equivalent estimates.";
+        return ok([
+            "Your AI Receipt — a shareable, redacted spend card (no client/project/user names).",
+            `receipt: ${outPath}`,
+            dataLine,
+            "",
+            "Caption to share:",
+            generateReportCardCaption({ summary, records: headlineRecords, mode }),
+            "",
+            "privacy: rendered locally; only totals, modeled opportunities, and model-level investigations are included."
+        ].join("\n"));
+    }
+    catch (error) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `Couldn't write the report card: ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
 }
 async function applyArtifactCommand(args) {
     const rootPath = resolve(args.path);
@@ -1003,8 +1211,11 @@ async function buildReportInput(stateDir, rootPath) {
     const deadContext = spendState.mode === "local_logs"
         ? await loadDeadContext({
             claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
+            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
             claudeHomeDir: process.env.AI_SPEND_CLAUDE_HOME_DIR,
+            codexHomeDir: process.env.AI_SPEND_CODEX_HOME_DIR,
             claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
+            claudeSettingsPath: process.env.AI_SPEND_CLAUDE_SETTINGS,
             projectDir: rootPath,
             includeAllProjectMcp: true,
             sinceIso: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
@@ -1023,7 +1234,9 @@ async function buildReportInput(stateDir, rootPath) {
         detectedPlans,
         // Evidence ledger is built from the SAME records as the confidence
         // breakdown so the two sections can never contradict each other.
-        allRecords: spendState.records ?? [],
+        allRecords: spendState.mode === "connected_provider"
+            ? selectProviderFinancialHeadlineRecords(spendState.records ?? [])
+            : spendState.records ?? [],
         dataMode: spendState.mode,
         discovery,
         mappings: mappings ?? [],
@@ -1039,6 +1252,7 @@ function emptyDiscovery(rootPath) {
         rootPath,
         scannedFiles: 0,
         skippedDirectories: [],
+        skippedSymlinks: [],
         unreadablePaths: [],
         signals: [],
         secretsDetected: [],
@@ -1053,11 +1267,11 @@ async function writeApplyArtifacts(stateDir, reportInput) {
         verificationPlan: join(stateDir, "ai-spend-verify-plan.md"),
         demoPackage: join(stateDir, "demo-package.md")
     };
-    await writeFile(paths.codingPrompt, generateApplyArtifactMarkdown(reportInput), "utf8");
-    await writeFile(paths.actionPlan, generateActionPlanMarkdown(reportInput), "utf8");
-    await writeFile(paths.policyConfigDraft, generatePolicyConfigDraftMarkdown(reportInput), "utf8");
-    await writeFile(paths.verificationPlan, generateVerificationPlanMarkdown(reportInput), "utf8");
-    await writeFile(paths.demoPackage, generateDemoPackageMarkdown(reportInput), "utf8");
+    await writeSafeStateText(stateDir, basename(paths.codingPrompt), generateApplyArtifactMarkdown(reportInput));
+    await writeSafeStateText(stateDir, basename(paths.actionPlan), generateActionPlanMarkdown(reportInput));
+    await writeSafeStateText(stateDir, basename(paths.policyConfigDraft), generatePolicyConfigDraftMarkdown(reportInput));
+    await writeSafeStateText(stateDir, basename(paths.verificationPlan), generateVerificationPlanMarkdown(reportInput));
+    await writeSafeStateText(stateDir, basename(paths.demoPackage), generateDemoPackageMarkdown(reportInput));
     return paths;
 }
 function parseArgs(argv) {
@@ -1086,6 +1300,10 @@ function parseArgs(argv) {
             parsed.noColor = true;
             continue;
         }
+        if (arg === "--json") {
+            parsed.json = true;
+            continue;
+        }
         if (arg === "--ignore-state") {
             parsed.ignoreState = true;
             continue;
@@ -1098,6 +1316,14 @@ function parseArgs(argv) {
             }
             continue;
         }
+        if (arg === "--since-days") {
+            const next = rest[index + 1];
+            if (next) {
+                parsed.sinceDays = Number(next);
+                index += 1;
+            }
+            continue;
+        }
         if (arg === "--group-by") {
             const next = rest[index + 1];
             if (isGroupByDimension(next)) {
@@ -1318,8 +1544,13 @@ function sanitizeSecretishError(message, authReference) {
     }
     return sanitized;
 }
-async function writeLocalSpendState(stateDir, records, summary, mappings, mode) {
-    await writeJson(join(stateDir, "spend.json"), { mode, records, summary });
+async function writeLocalSpendState(stateDir, records, summary, mappings, mode, accounting) {
+    await writeJson(join(stateDir, "spend.json"), {
+        mode,
+        records,
+        summary,
+        ...(accounting ? { accounting } : {})
+    });
     await writeJson(join(stateDir, "mappings.json"), mappings);
 }
 async function readSourceRegistry(stateDir, rootPath) {
@@ -1363,7 +1594,7 @@ async function appendAuditEvent(stateDir, event) {
     await writeJson(join(stateDir, "audit-log.json"), createScanAuditLog([...auditLog.events, event].slice(-500)));
 }
 async function readJson(path) {
-    return JSON.parse(await readFile(path, "utf8"));
+    return JSON.parse(await readSafeStateText(dirname(path), basename(path)));
 }
 async function readOptionalJson(path, fallback) {
     try {
@@ -1374,42 +1605,52 @@ async function readOptionalJson(path, fallback) {
     }
 }
 async function writeJson(path, value) {
-    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    await writeSafeStateText(dirname(path), basename(path), `${JSON.stringify(value, null, 2)}\n`);
+}
+async function writeLocalReportFile(path, contents, _stateDir) {
+    await writeSafeStateText(dirname(path), basename(path), contents);
+}
+function isNodeError(error, code) {
+    return error instanceof Error && error.code === code;
 }
 function ok(stdout) {
     return { exitCode: 0, stdout, stderr: "" };
 }
 function helpText() {
     return [
-        "AI Spend Analyst — your AI spend in one view in 90 seconds",
+        "aibill — your AI cost and usage evidence in one private view",
         "",
         "Run with no command for an instant, zero-key demo:",
-        "  ai-spend-agent                       Show where your AI money goes (sample/auto-detected data)",
+        "  ai-spend-agent                       Show available AI cost/value evidence (sample or local data)",
         "  ai-spend-agent --group-by agent      Drill down by source|model|client|project|agent|user|workspace|apiKey",
         "  ai-spend-agent --plan <id>           Declare your plan when auto-detection can't (claude-max-5x|claude-max-20x|claude-pro|chatgpt-plus|chatgpt-pro)",
         "",
-        "Connect your real spend (cost data is ADMIN/owner-gated):",
-        "  ai-spend-agent connect openai        Self-serve in ~2 min with an org-owner Admin key",
-        "  ai-spend-agent connect anthropic     Self-serve in ~2 min with an Admin key",
+        "Add official provider-reported cost (ADMIN/owner-gated):",
+        "  ai-spend-agent connect openai        Requires an org-owner Admin key",
+        "  ai-spend-agent connect anthropic     Requires an Admin key",
         "  ai-spend-agent connect cursor        Upgrade: requires a Cursor team-admin key (Business plan)",
         "  ai-spend-agent connect github-copilot Upgrade: requires a GitHub billing-admin token",
-        "  ai-spend-agent sync-provider ...     Pull verified cost via a local env: reference (never a raw key)",
+        "  ai-spend-agent sync-provider ...     Pull provider cost/usage evidence via a local env: reference (never a raw key)",
         "",
         "Watch continuously (deltas + anomalies):",
         "  watch [--interval N]    Re-run analysis on an interval and report deltas/anomalies",
         "    [--cycles N] [--group-by ...]  --cycles 0 runs forever; default 1 (cron-friendly)",
         "",
         "Other commands:",
+        "  --version, -v           Print the package version without reading local data",
         "  init [--path <dir>]     Initialize local state",
         "  doctor                  Launch-grade diagnostics: data mode, logs found, provider keys, warnings",
         "  reset [--path <dir>]    Clear persisted spend state (so sample state can't mask real logs)",
         "  --ignore-state          On the default/quickstart run, ignore persisted spend.json for this run",
         "  scan [--path <dir>]     Scan a local workspace for AI usage signals",
         "  scan --sample           Include deterministic sample spend analysis",
-        "  quickstart [--sample]   Plain-English 90-second readout (alias of the default run)",
+        "  quickstart [--sample]   Plain-English local readout (alias of the default run)",
         "    [--group-by source|model|client|project|agent|user|workspace|apiKey]  Default: model",
         "  report [--out <name>]   Generate local Markdown and HTML reports",
         "  report-card [--out f.svg] Write your AI Receipt — a redacted, shareable SVG + caption",
+        "  glance [--project <name>] [--plan <id>] 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",
         "  apply                   Print the paste-ready coding-agent prompt + write action/policy/verification plans",
         "  apply-artifact          Same as `apply` (long form)",
         "",

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "ai-spend-agent",
-  "version": "0.5.5",
-  "description": "Your AI spend in one view, in 90 seconds — local-first CLI for OpenAI, Anthropic, Cursor, Copilot + Claude Code/Codex session logs, with a ranked savings cut list, and flags the tools your agent loads but never uses (dead context).",
+  "version": "0.5.7",
+  "description": "Local-first financial intelligence CLI for Claude Code and Codex activity, provider-reported cost, attribution, runway, provenance, and Context Health.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "ai-spend-agent": "./dist/index.js"
+    "ai-spend-agent": "dist/index.js"
   },
   "files": [
     "dist",
@@ -21,6 +21,9 @@
     "directory": "packages/cli"
   },
   "homepage": "https://github.com/futurastudio/ai-spend-agent#readme",
+  "bugs": {
+    "url": "https://github.com/futurastudio/ai-spend-agent/issues"
+  },
   "keywords": [
     "ai",
     "spend",
@@ -51,8 +54,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@agent-finops/core": "0.5.5",
-    "@agent-finops/report": "0.5.5",
+    "@agent-finops/core": "0.5.7",
+    "@agent-finops/report": "0.5.7",
     "yocto-spinner": "^1.2.0"
   }
 }