ai-spend-agent 0.7.3 → 0.8.0

package/README.md

@@ -10,9 +10,12 @@ npx ai-spend-agent
 npx aibill
 ```
 
-Run `npx aibill init` from a project to detect machine-wide local Claude Code
-and Codex history, print the first evidence-labeled personal receipt, and seed a private
-aggregate cache under `~/.aibill/cache/`. Init never replaces missing personal
+Run `npx aibill init` from a project to detect machine-wide Claude Code, Codex,
+and experimental Gemini CLI financial evidence, print the first
+evidence-labeled personal receipt, and seed a private Claude/Codex aggregate
+cache under `~/.aibill/cache/`. Gemini financial rows come only from
+`~/.gemini/tmp/<opaque-project-id>/chats/**/*.{json,jsonl}`; `logs.json` is a
+presence signal and never a financial source. Init never replaces missing personal
 evidence with the bundled sample and never overwrites existing connected
 source or audit state.
 
@@ -23,8 +26,9 @@ hook. Subscription runway appears only when it was transcript-reported; `~`
 means API-equivalent value, and untilded `billed` money requires verified
 provider evidence. Remove it with `npx aibill statusline uninstall`.
 
-It reads local Claude Code and Codex metadata, labels API-equivalent estimates,
-and can optionally add official OpenAI or Anthropic provider-reported cost
+It reads supported local Claude Code, Codex, and Gemini CLI financial 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.
 aibill never sits in the inference path and never stores, prints, or proxies provider credentials.
 

package/dist/index.js

@@ -4,7 +4,7 @@ import { mkdir, readFile, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { analyzeSpend, attributeUsageRecords, buildUsageGlance, buildActivitySnapshot, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, invalidateConnectedSpendTrustReceipt, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, writeSafeStateText, verifyConnectedSpendTrustReceipt, verifyConnectedSourceRegistryTrustReceipt, writeConnectedSpendTrustReceipt, loadDeadContext, sampleDeadContext, latestObservedWorkingDirectory, downgradeSampleUsageEvidence, isBundledSampleUsage, loadLocalAgentUsage, loadLocalAgentFinancialUsage, localAgentFormatDescriptors, localAgentFormatLabel, loadSampleUsageData, parseUsageRecord, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProviderConnectorStub, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, normalizeSourceRegistry, downgradeUntrustedSourceRegistryClaims, buildSourceStatuses, slugifySourceId, financialEvidenceForRecords, formatSourceStatuses, readActivitySnapshot, recordActivitySnapshotRefreshFailure, sourceStatusDefinitions, writeActivitySnapshot } from "@agent-finops/core";
+import { analyzeSpend, attributeUsageRecords, buildUsageGlance, buildActivitySnapshot, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, invalidateConnectedSpendTrustReceipt, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, summarizeProviderFinancials, providerFinancialCompleteness, writeSafeStateText, verifyConnectedSpendTrustReceipt, verifyConnectedSourceRegistryTrustReceipt, writeConnectedSpendTrustReceipt, loadDeadContext, sampleDeadContext, latestObservedWorkingDirectory, downgradeSampleUsageEvidence, isBundledSampleUsage, loadLocalAgentUsage, loadLocalAgentFinancialUsage, localAgentFormatDescriptors, localAgentFormatLabel, localAgentFormatSupports, loadSampleUsageData, parseUsageRecord, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProviderConnectorStub, createProviderConnection, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, normalizeSourceRegistry, downgradeUntrustedSourceRegistryClaims, buildSourceStatuses, applyProviderContractGate, applyProviderContractGateToSourceRegistry, slugifySourceId, financialEvidenceForRecords, formatSourceStatuses, readActivitySnapshot, recordActivitySnapshotRefreshFailure, sourceStatusDefinitions, writeActivitySnapshot } from "@agent-finops/core";
 import { StatuslineInstallerError, installClaudeStatusline, uninstallClaudeStatusline } from "./statuslineInstaller.js";
 import { readStatuslineCache, renderStatusline } from "./statuslineRuntime.js";
 import { generateActionPlanMarkdown, generateApplyArtifactMarkdown, generateDemoPackageMarkdown, generateHtmlReport, generateMarkdownReport, generatePlainEnglishSummary, generatePolicyConfigDraftMarkdown, generateReportCardCaption, generateReportCardSvg, generateVerificationPlanMarkdown, groupByDimensions } from "@agent-finops/report";
@@ -177,7 +177,7 @@ async function quickstartCommand(args) {
         // table + window instead of repeating the whole readout.
         view: args.groupBy ? "breakdown" : "full"
     });
-    const header = [`  ${dataModeBanner(mode)}`, ...warnings.map((warning) => `  ! ${warning}`)].join("\n");
+    const header = [`  ${dataModeBanner(mode, summaryRecords)}`, ...warnings.map((warning) => `  ! ${warning}`)].join("\n");
     return ok(`${header}\n${summaryText}`);
 }
 async function glanceCommand(args) {
@@ -187,12 +187,14 @@ async function glanceCommand(args) {
     const logs = await loadLocalAgentUsage({
         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(sinceDays),
         collectCodexInvocationEvidence: true
     });
+    const glanceCalls = logs.calls.filter((call) => (localAgentFormatSupports(call.agent, "glance")));
     const calls = args.project
-        ? logs.calls.filter((call) => call.project === args.project)
-        : logs.calls;
+        ? glanceCalls.filter((call) => call.project === args.project)
+        : glanceCalls;
     const latestWorkingDirectory = latestObservedWorkingDirectory(calls);
     const contextProjectDir = args.pathExplicit
         ? resolve(args.path)
@@ -228,10 +230,12 @@ async function glanceCommand(args) {
         codexInvocationFiles: logs.codexInvocationFiles
     });
     const snapshot = buildUsageGlance(calls, {
-        filesParsed: logs.filesParsed,
-        detectedAgents: logs.agentsDetected,
+        filesParsed: logs.sourceScans
+            .filter((scan) => localAgentFormatSupports(scan.agent, "glance"))
+            .reduce((total, scan) => total + scan.filesParsed, 0),
+        detectedAgents: logs.agentsDetected.filter((agent) => (localAgentFormatSupports(agent, "glance"))),
         detectedPlans,
-        limitCalls: logs.calls,
+        limitCalls: glanceCalls,
         contextHealth
     });
     return ok(JSON.stringify(snapshot));
@@ -244,12 +248,14 @@ async function contextHealthCommand(args) {
     const logs = await loadLocalAgentUsage({
         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,
         collectCodexInvocationEvidence: true
     });
+    const contextCalls = logs.calls.filter((call) => (localAgentFormatSupports(call.agent, "contextHealth")));
     const calls = args.project
-        ? logs.calls.filter((call) => call.project === args.project)
-        : logs.calls;
+        ? contextCalls.filter((call) => call.project === args.project)
+        : contextCalls;
     const health = await loadContextHealth(calls, {
         claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
         codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
@@ -326,7 +332,7 @@ function quickstartNextSteps(mode, detected) {
         ? "npx aibill report --sample     write a clearly labeled demo Markdown + HTML report"
         : "npx aibill report              write a shareable Markdown + HTML report");
     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");
+    steps.push("Need team reconciliation, allocation, budgets, and approvals? Workspace design partners: https://asktilden.com");
     return steps;
 }
 async function readPersistedSpend(rootPath, options = {}) {
@@ -343,9 +349,12 @@ async function readPersistedSpend(rootPath, options = {}) {
         // tag. A copied/tampered sample must never become connected billing merely
         // because `mode` was changed in JSON.
         const mode = isBundledSampleUsage(parsedRecords) ? "sample" : storedMode;
-        const records = mode === "sample" || mode === undefined
+        const parsedModeRecords = mode === "sample" || mode === undefined
             ? downgradeSampleUsageEvidence(parsedRecords)
             : parsedRecords;
+        const records = mode === "connected_provider"
+            ? applyProviderContractGate(parsedModeRecords)
+            : parsedModeRecords;
         if (spend.checkedAt !== undefined && !validIsoString(spend.checkedAt)) {
             throw new Error("persisted spend checkedAt must be an ISO timestamp");
         }
@@ -410,7 +419,7 @@ async function loadInstantReadData(args) {
         looksConnected &&
         persisted.connectedTrust?.trusted === true) {
         return {
-            records: persisted.records,
+            records: applyProviderContractGate(persisted.records),
             mode: "connected",
             warnings,
             ...(persisted.providerCoverage ? { providerCoverage: persisted.providerCoverage } : {})
@@ -424,6 +433,7 @@ async function loadInstantReadData(args) {
         // 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);
@@ -441,6 +451,16 @@ async function loadInstantReadData(args) {
             codexInvocationFiles: logs.codexInvocationFiles
         };
     }
+    const geminiPresence = logs?.sourceScans.find((scan) => scan.agent === "gemini-cli");
+    if (geminiPresence && ((geminiPresence.detectionSignals ?? 0) > 0 || geminiPresence.filesDiscovered > 0)) {
+        warnings.push("Gemini CLI was 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");
+        return {
+            records: [],
+            mode: "local-logs",
+            warnings,
+            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.
     if (persisted && persisted.records.length > 0 && persisted.mode !== "connected_provider" && persisted.mode !== "local_logs") {
@@ -457,9 +477,12 @@ async function loadInstantReadData(args) {
     return { records: await loadSampleUsageData(), mode: "demo", warnings };
 }
 /** A one-line, unmissable banner telling the user which data they're seeing. */
-function dataModeBanner(mode) {
-    if (mode === "local-logs")
-        return "DATA MODE: your local agent logs (estimated at API-equivalent rates)";
+function dataModeBanner(mode, records) {
+    if (mode === "local-logs") {
+        return records.some((record) => typeof record.amountUsd === "number")
+            ? "DATA MODE: your local agent logs (estimated at API-equivalent rates)"
+            : "DATA MODE: local agent evidence (financial value unavailable; no demo sample substituted)";
+    }
     if (mode === "connected")
         return "DATA MODE: connected provider billing";
     return "DATA MODE: demo sample (illustrative — not your real spend)";
@@ -479,12 +502,18 @@ async function doctorCommand(args) {
         : "no state";
     const logs = await loadLocalAgentUsage({
         claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
-        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR
+        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+        geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR
     }).catch(() => undefined);
     const detected = logs?.agentsDetected ?? [];
     const claudeFound = detected.includes("claude-code");
     const codexFound = detected.includes("codex");
-    const hasLogs = claudeFound || codexFound;
+    const geminiScan = logs?.sourceScans.find((scan) => scan.agent === "gemini-cli");
+    const geminiFinancialFound = detected.includes("gemini-cli");
+    const geminiPresenceFound = Boolean(geminiScan && ((geminiScan.detectionSignals ?? 0) > 0 || geminiScan.filesDiscovered > 0));
+    const geminiFound = geminiFinancialFound || geminiPresenceFound;
+    const hasFinancialLogs = claudeFound || codexFound || geminiFinancialFound;
+    const hasLocalSource = hasFinancialLogs || geminiPresenceFound;
     const detection = await detectLocalCredentials({
         cwd: rootPath,
         home: process.env.AI_SPEND_CLAUDE_HOME_DIR
@@ -505,15 +534,20 @@ async function doctorCommand(args) {
     if (persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === false) {
         warnings.push(`${persisted.connectedTrust.message} Run \`npx aibill connect <provider>\` or repeat the prior \`npx aibill sync-provider ...\` command.`);
     }
-    if (!hasLogs)
-        warnings.push("no real Claude Code / Codex logs found — a first run here will show DEMO sample data");
+    if (geminiPresenceFound && !geminiFinancialFound) {
+        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");
     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)");
     const predictedMode = connectedStateTrusted
         ? "connected provider billing"
-        : hasLogs
+        : hasFinancialLogs
             ? "your local agent logs (estimated at API-equivalent rates)"
-            : "demo sample (illustrative)";
+            : geminiPresenceFound
+                ? "local Gemini CLI presence only (financial evidence unavailable; no sample substituted)"
+                : "demo sample (illustrative)";
     const lines = [
         "aibill doctor",
         `node version: ${process.version}`,
@@ -524,6 +558,11 @@ async function doctorCommand(args) {
         `state mode: ${stateMode}`,
         `Claude Code logs: ${claudeFound ? "found" : "not found"}`,
         `Codex logs: ${codexFound ? "found" : "not found"}`,
+        `Gemini CLI sessions: ${geminiFinancialFound
+            ? "found"
+            : geminiPresenceFound
+                ? "detected, but no supported chats financial rows found"
+                : "not found"}`,
         `provider env references: ${providerRefs.length > 0 ? providerRefs.join(", ") : "none detected"}`,
         `subscription plans: ${planLine}`,
         "redaction policy: secrets are never printed or persisted",
@@ -549,7 +588,8 @@ async function doctorSourcesCommand(args) {
     try {
         localLogs = await loadLocalAgentUsage({
             claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
-            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR
+            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+            geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR
         });
     }
     catch (error) {
@@ -659,14 +699,18 @@ function localFinancialEvidenceNote(records, evidence, scan) {
         if (scan.directoryStatus === "unreadable") {
             return "The local transcript path could not be read; absence of usage cannot be confirmed.";
         }
+        if (scan.agent === "gemini-cli" && (scan.detectionSignals ?? 0) > 0 &&
+            scan.filesDiscovered === 0) {
+            return "Gemini CLI detected, but no supported chats JSON/JSONL financial evidence was found. logs.json is presence-only evidence; zero financial rows were created. Need this coverage? +1 or contribute a synthetic fixture: https://github.com/futurastudio/ai-spend-agent/issues/new?template=provider_or_agent.yml";
+        }
         if (scan.filesDiscovered === 0) {
-            return "The local transcript directory was readable, but no JSONL files were found.";
+            return "The local transcript directory was readable, but no supported session files were found.";
         }
         if (scan.unreadableFiles > 0) {
             return `${scan.filesDiscovered} transcript file(s) were found, but ${scan.unreadableFiles} could not be read; absence of usage cannot be confirmed.`;
         }
         if (scan.malformedLines > 0) {
-            return `${scan.filesDiscovered} transcript file(s) were found, but no valid usage rows were parsed; ${scan.malformedLines} malformed JSONL line(s) were skipped.`;
+            return `${scan.filesDiscovered} transcript file(s) were found, but no valid usage rows were parsed; ${scan.malformedLines} malformed session record(s) were skipped.`;
         }
         return `${scan.filesDiscovered} transcript file(s) were found, but no supported usage rows were observed.`;
     }
@@ -697,9 +741,13 @@ function localFinancialEvidenceNote(records, evidence, scan) {
 function localAgentDiagnosticSummary(diagnostics) {
     const relevant = diagnostics.filter((diagnostic) => diagnostic.code !== "directory_missing");
     const unsupported = relevant.filter((diagnostic) => diagnostic.code === "unsupported_token_shape");
-    const malformed = relevant.filter((diagnostic) => diagnostic.code === "malformed_jsonl");
+    const malformed = relevant.filter((diagnostic) => (diagnostic.code === "malformed_jsonl" || diagnostic.code === "malformed_session_file"));
     const messages = [...new Set(relevant
-            .filter((diagnostic) => !["unsupported_token_shape", "malformed_jsonl"].includes(diagnostic.code))
+            .filter((diagnostic) => ![
+            "unsupported_token_shape",
+            "malformed_jsonl",
+            "malformed_session_file"
+        ].includes(diagnostic.code))
             .map((diagnostic) => diagnostic.message))];
     const unsupportedCount = unsupported
         .reduce((total, diagnostic) => total + diagnostic.count, 0);
@@ -709,7 +757,7 @@ function localAgentDiagnosticSummary(diagnostics) {
     const malformedCount = malformed
         .reduce((total, diagnostic) => total + diagnostic.count, 0);
     if (malformedCount > 0) {
-        messages.push(`${malformedCount} malformed JSONL line(s) were skipped in ${localAgentFormatLabel(malformed[0].agent)} transcripts.`);
+        messages.push(`${malformedCount} malformed session record(s) were skipped in ${localAgentFormatLabel(malformed[0].agent)} transcripts.`);
     }
     return messages.length > 0 ? messages.join(" ") : undefined;
 }
@@ -1210,6 +1258,7 @@ async function collectAndPublishActivitySnapshot(input) {
         logs = await loadLocalAgentFinancialUsage({
             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(30, asOf)
         });
     }
@@ -1222,13 +1271,14 @@ async function collectAndPublishActivitySnapshot(input) {
     const persisted = persistedResult.persisted;
     const trustedProviderRecords = persisted?.mode === "connected_provider" &&
         persisted.connectedTrust?.trusted === true
-        ? selectProviderFinancialHeadlineRecords(persisted.records)
+        ? selectProviderFinancialHeadlineRecords(applyProviderContractGate(persisted.records))
         : [];
     let activitySnapshot;
     let cacheStatus;
+    const statuslineSourceScans = logs?.sourceScans.filter((scan) => (localAgentFormatSupports(scan.agent, "statuslineSnapshot"))) ?? [];
     const structuredSourceFailure = logs !== undefined &&
-        logs.sourceScans.some((scan) => scan.directoryStatus === "unreadable") &&
-        !logs.sourceScans.some((scan) => scan.directoryStatus === "readable");
+        statuslineSourceScans.some((scan) => scan.directoryStatus === "unreadable") &&
+        !statuslineSourceScans.some((scan) => scan.directoryStatus === "readable");
     if (logs && !structuredSourceFailure) {
         let refreshErrorCode = "invalid_evidence";
         try {
@@ -1516,13 +1566,18 @@ function activitySnapshotProvider(provider) {
 function formatInitReceipt(input) {
     const records = input.logs?.records ?? [];
     const pricedRecords = records.filter((record) => typeof record.amountUsd === "number");
+    const registryOnlyLines = initRegistryOnlyFinancialLines(records);
     const sourceFailures = (input.logs?.sourceScans ?? []).some((scan) => scan.directoryStatus === "unreadable") ||
         (input.logs?.diagnostics ?? []).some((diagnostic) => diagnostic.severity === "error");
-    const receiptLines = input.scanError || sourceFailures && records.length === 0
+    const snapshotLines = input.scanError || sourceFailures && records.length === 0
         ? ["API-equivalent usage value: unavailable — the local scan could not prove an empty result"]
         : input.activitySnapshot
             ? initApiEquivalentWindowLines(input.activitySnapshot)
             : ["API-equivalent usage value: unavailable — no snapshot was produced"];
+    const receiptLines = registryOnlyLines.length > 0 &&
+        input.activitySnapshot?.mode === "empty" && !input.scanError
+        ? registryOnlyLines
+        : [...snapshotLines, ...registryOnlyLines];
     const planLine = input.detectedPlans.length > 0
         ? input.detectedPlans.map((plan) => {
             const known = plan.planId ?? "unrecognized plan";
@@ -1536,7 +1591,10 @@ function formatInitReceipt(input) {
         const validation = scan.jsonlValidationCoverage === "financial_events_only"
             ? "; financial-event JSONL validation only"
             : "";
-        return `  ${scan.agent}: ${scan.directoryStatus}; ${scan.filesParsed}/${scan.filesDiscovered} files parsed; ${priced}/${agentRecords.length} rows priced${skipped > 0 ? `; ${skipped} old files skipped` : ""}${validation}`;
+        const detection = (scan.detectionSignals ?? 0) > 0
+            ? `; ${scan.detectionSignals} presence-only signal(s)`
+            : "";
+        return `  ${scan.agent}: ${scan.directoryStatus}; ${scan.filesParsed}/${scan.filesDiscovered} files parsed; ${priced}/${agentRecords.length} rows priced${detection}${skipped > 0 ? `; ${skipped} old files skipped` : ""}${validation}`;
     });
     const diagnosticLines = (input.logs?.diagnostics ?? [])
         .filter((diagnostic) => diagnostic.code !== "directory_missing")
@@ -1545,7 +1603,7 @@ function formatInitReceipt(input) {
     return [
         "aibill init",
         `state project: ${sanitizeSecretishError(basename(input.rootPath))}`,
-        "local usage scope: all Claude Code + Codex activity on this machine (last 30 days)",
+        "local usage scope: supported Claude Code, Codex, and Gemini CLI financial evidence on this machine (last 30 days)",
         "provider scope: trusted connected billing from this state project only (shown separately)",
         "",
         "FIRST RECEIPT · API-equivalent usage value · last 30 days",
@@ -1565,6 +1623,25 @@ function formatInitReceipt(input) {
         "next: npx aibill doctor --sources"
     ].filter((line) => line !== "").join("\n");
 }
+function initRegistryOnlyFinancialLines(records) {
+    const lines = [];
+    for (const descriptor of localAgentFormatDescriptors) {
+        if (descriptor.capabilities.statuslineSnapshot)
+            continue;
+        const sourceRecords = records.filter((record) => record.agentId === descriptor.id);
+        if (sourceRecords.length === 0)
+            continue;
+        const priced = sourceRecords.filter((record) => typeof record.amountUsd === "number");
+        if (priced.length === 0) {
+            lines.push(`${descriptor.id} API-equivalent value: unavailable — ${sourceRecords.length} observed row(s) lacked complete token components or a supported model price`);
+            continue;
+        }
+        const amount = analyzeSpend(priced).totalUsd;
+        const unpriced = sourceRecords.length - priced.length;
+        lines.push(`${descriptor.id} experimental value: ~${formatOptionalUsd(amount)} 30d (API-equivalent; fixture-verified; not billed spend${unpriced > 0 ? `; ${unpriced} row(s) unpriced` : ""})`);
+    }
+    return lines;
+}
 function formatInitProviderEvidence(input) {
     const windowStart = input.asOf.getTime() - 30 * 24 * 60 * 60 * 1_000;
     const inWindow = input.trustedProviderRecords.filter((record) => {
@@ -1836,7 +1913,7 @@ async function runWatchCycle(stateDir, args) {
             // Watch may observe an already trusted provider snapshot, but it may not
             // mint trust from repository-authored provider-records.json or rewrite
             // connected state. Only an explicit provider sync can do that.
-            records = persisted.records;
+            records = applyProviderContractGate(persisted.records);
             mode = "connected_provider";
         }
         else {
@@ -1844,7 +1921,8 @@ async function runWatchCycle(stateDir, args) {
             // never serve a stale snapshot.
             const logs = await loadLocalAgentUsage({
                 claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
-                codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR
+                codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+                geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR
             }).catch(() => undefined);
             if (logs && logs.records.length > 0) {
                 records = logs.records;
@@ -1857,18 +1935,21 @@ async function runWatchCycle(stateDir, args) {
         }
     }
     const headlineRecords = mode === "connected_provider"
-        ? selectProviderFinancialHeadlineRecords(records)
+        ? selectProviderFinancialHeadlineRecords(applyProviderContractGate(records))
         : records;
     const summary = analyzeSpend(headlineRecords);
+    const financialAmountAvailable = headlineRecords.some((record) => typeof record.amountUsd === "number");
     const mappings = attributeUsageRecords(records);
     if (mode !== "connected_provider") {
         await writeLocalSpendState(stateDir, records, summary, mappings, mode);
     }
     const snapshot = {
         capturedAt: new Date().toISOString(),
-        totalUsd: summary.totalUsd,
+        totalUsd: financialAmountAvailable ? summary.totalUsd : null,
         recordCount: summary.recordCount,
-        byModel: summary.byModel.map((entry) => ({ key: entry.key, amountUsd: entry.amountUsd }))
+        byModel: financialAmountAvailable
+            ? summary.byModel.map((entry) => ({ key: entry.key, amountUsd: entry.amountUsd }))
+            : []
     };
     // Append to the rolling history and persist the latest snapshot for the next run.
     const history = await readOptionalJson(join(stateDir, "watch-history.json"), []);
@@ -1878,14 +1959,25 @@ async function runWatchCycle(stateDir, args) {
         timestamp: snapshot.capturedAt,
         action: "scan_completed",
         sourceId: "watch",
-        detail: `Watch cycle captured ${snapshot.recordCount} records totaling $${snapshot.totalUsd.toFixed(2)}.`
+        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)}.`
     });
     return { summary, snapshot, records: headlineRecords, mode };
 }
 function buildDeltaHeadline(previous, current) {
     if (!previous) {
+        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.`;
     }
+    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.`;
+    }
     const deltaUsd = roundMoneyCli(current.totalUsd - previous.totalUsd);
     const lines = [];
     if (Math.abs(deltaUsd) < 0.01) {
@@ -2120,12 +2212,24 @@ async function syncProviderCommand(args) {
             enterprise: args.enterprise,
             accountId: args.accountId
         });
-        const records = [
+        const syncedRecords = applyProviderContractGate(result.records);
+        const syncedFinancials = summarizeProviderFinancials(syncedRecords);
+        const syncedCompleteness = providerFinancialCompleteness(syncedRecords, result.coverage);
+        const syncedSource = createProviderConnection({
+            provider: result.provider,
+            sourceId: result.source.id,
+            authReference: args.authReference,
+            verifiedRecordCount: syncedRecords.length,
+            totalUsd: syncedFinancials.headlineUsd,
+            completeness: syncedCompleteness,
+            fetchedAt: new Date(result.fetchedAt)
+        });
+        const records = applyProviderContractGate([
             ...(trustedPrior?.records ?? []).filter((record) => record.source.provider !== result.provider),
-            ...result.records
-        ].sort((left, right) => left.timestamp.localeCompare(right.timestamp));
+            ...syncedRecords
+        ]).sort((left, right) => left.timestamp.localeCompare(right.timestamp));
         const registry = await readSourceRegistry(stateDir, rootPath);
-        const nextRegistry = addApprovedSource(registry, result.source);
+        const nextRegistry = addApprovedSource(registry, syncedSource);
         const headlineRecords = selectProviderFinancialHeadlineRecords(records);
         const summary = analyzeSpend(headlineRecords);
         const mappings = attributeUsageRecords(records);
@@ -2139,7 +2243,7 @@ async function syncProviderCommand(args) {
         };
         const financialsByProvider = {
             ...trustedAccountingMap(trustedPrior?.accounting, "financialsByProvider"),
-            [result.provider]: result.financials
+            [result.provider]: syncedFinancials
         };
         const checkedAtByProvider = {
             ...trustedAccountingMap(trustedPrior?.accounting, "checkedAtByProvider"),
@@ -2160,10 +2264,10 @@ async function syncProviderCommand(args) {
         await writeJson(join(stateDir, "provider-records.json"), {
             provider: result.provider,
             fetchedAt: result.fetchedAt,
-            completeness: result.completeness,
+            completeness: syncedCompleteness,
             coverage: result.coverage,
-            financials: result.financials,
-            sourceId: result.source.id,
+            financials: syncedFinancials,
+            sourceId: syncedSource.id,
             records,
             qa: result.qa,
             qaByProvider,
@@ -2189,24 +2293,24 @@ async function syncProviderCommand(args) {
         await appendAuditEvent(stateDir, {
             timestamp: result.fetchedAt,
             action: "source_scanned",
-            sourceId: result.source.id,
+            sourceId: syncedSource.id,
             detail: `${args.provider} provider connector synced ${result.records.length} evidence records with ${result.coverage} coverage. Auth reference only; no raw secrets stored.`
         });
         await writeConnectedSpendTrustReceipt(rootPath, await readSafeStateText(stateDir, "spend.json"), { sourceRegistryContents: await readSafeStateText(stateDir, "sources.json") });
         return ok([
             "aibill sync-provider",
             `provider: ${result.provider}`,
-            `source: ${result.source.id}`,
-            `boundary approval: ${result.source.boundaryApproval}`,
-            `validation coverage: ${result.source.validationCoverage}`,
-            `financial evidence: ${result.source.financialEvidence}`,
+            `source: ${syncedSource.id}`,
+            `boundary approval: ${syncedSource.boundaryApproval}`,
+            `validation coverage: ${syncedSource.validationCoverage}`,
+            `financial evidence: ${syncedSource.financialEvidence}`,
             `coverage: ${result.coverage}`,
             `records fetched: ${result.records.length}`,
-            `headline basis: ${result.financials.headlineBasis}`,
-            `synced provider headline: ${formatOptionalUsd(result.financials.headlineUsd)}`,
+            `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"}`,
-            ...(result.financials.apiEquivalentEstimatedUsd !== null
-                ? [`API-equivalent estimate (kept separate): $${result.financials.apiEquivalentEstimatedUsd.toFixed(2)}`]
+            ...(syncedFinancials.apiEquivalentEstimatedUsd !== null
+                ? [`API-equivalent estimate (kept separate): $${syncedFinancials.apiEquivalentEstimatedUsd.toFixed(2)}`]
                 : []),
             "auth: reference-only; raw secrets were not persisted or printed"
         ].join("\n"));
@@ -2324,7 +2428,10 @@ async function reportCommand(args) {
             `demo package: ${artifactPaths.demoPackage}`,
             reportInput.dataMode === "sample"
                 ? `DEMO SAMPLE · illustrative cost/value evidence total: $${reportInput.summary.totalUsd.toFixed(2)} · not user data`
-                : `cost/value evidence total: $${reportInput.summary.totalUsd.toFixed(2)}`,
+                : 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)}`,
             "privacy: report rendered locally with no aibill telemetry; only explicit sync-provider contacts the selected provider",
             "",
             "next:",
@@ -2510,9 +2617,12 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30) {
         // A bundled sample remains sample even if a conflicting mode was written.
         // This guards report and Apply separately from the quickstart read path.
         const mode = isBundledSampleUsage(parsedRecords) ? "sample" : storedMode;
-        const records = mode === "sample" || mode === undefined
+        const parsedModeRecords = mode === "sample" || mode === undefined
             ? downgradeSampleUsageEvidence(parsedRecords)
             : parsedRecords;
+        const records = mode === "connected_provider"
+            ? applyProviderContractGate(parsedModeRecords)
+            : parsedModeRecords;
         unavailablePersistedLocalLogs = mode === "local_logs";
         const headlineRecords = mode === "connected_provider"
             ? selectProviderFinancialHeadlineRecords(records)
@@ -2560,6 +2670,7 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30) {
         const logs = await loadLocalAgentUsage({
             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,
             collectCodexInvocationEvidence: true
         }).catch(() => undefined);
@@ -2588,10 +2699,10 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30) {
             throw new Error(`${untrustedConnectedStateMessage} No connected totals or Apply actions were generated.`);
         }
         if (unavailablePersistedLocalLogs) {
-            throw new Error("Persisted local-log state is an untrusted cache and its source Claude Code/Codex records are unavailable. " +
+            throw new Error("Persisted local-log state is an untrusted cache and its source local-agent records are unavailable. " +
                 "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 local Claude Code/Codex logs found. " +
+        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).");
     }
     const [discovery, sourceRegistry, missingSourcePrompts, confirmedMappings, persistedProviderRecordsState] = await Promise.all([
@@ -2651,7 +2762,7 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30) {
     // If live transcript calls are unavailable, omit it instead of fabricating a
     // session-level recommendation from day-aggregate spend records.
     const contextHealth = spendState.mode === "local_logs" && freshLocalCalls
-        ? await loadContextHealth(freshLocalCalls, {
+        ? await loadContextHealth(freshLocalCalls.filter((call) => (localAgentFormatSupports(call.agent, "contextHealth"))), {
             claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
             codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
             claudeHomeDir: process.env.AI_SPEND_CLAUDE_HOME_DIR,
@@ -3057,7 +3168,7 @@ async function readSourceRegistry(stateDir, rootPath) {
             if (parsedSpend.mode === "connected_provider") {
                 const trust = await verifyConnectedSourceRegistryTrustReceipt(rootPath, exactSpendContents, exactSourceRegistryContents);
                 if (trust.trusted)
-                    return registry;
+                    return applyProviderContractGateToSourceRegistry(registry);
             }
         }
         catch {
@@ -3065,7 +3176,7 @@ async function readSourceRegistry(stateDir, rootPath) {
             // controlled validation/evidence claims are never promoted without the
             // matching external provider-sync receipt.
         }
-        return downgradeUntrustedSourceRegistryClaims(registry);
+        return applyProviderContractGateToSourceRegistry(downgradeUntrustedSourceRegistryClaims(registry));
     }
     catch {
         return createLocalFolderSourceRegistry(rootPath);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-spend-agent",
-  "version": "0.7.3",
-  "description": "Local-first financial accountability CLI for Claude Code and Codex work, cost evidence, attribution, runway, provenance, and Context Health.",
+  "version": "0.8.0",
+  "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",
   "types": "./dist/index.d.ts",
@@ -54,8 +54,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@agent-finops/core": "0.7.3",
-    "@agent-finops/report": "0.7.3",
+    "@agent-finops/core": "0.8.0",
+    "@agent-finops/report": "0.8.0",
     "yocto-spinner": "^1.2.0"
   }
 }