ai-spend-agent 0.6.0 → 0.7.0

package/dist/index.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
 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, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, invalidateConnectedSpendTrustReceipt, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, writeSafeStateText, verifyConnectedSpendTrustReceipt, verifyConnectedSourceRegistryTrustReceipt, writeConnectedSpendTrustReceipt, loadDeadContext, sampleDeadContext, latestObservedWorkingDirectory, downgradeSampleUsageEvidence, isBundledSampleUsage, loadLocalAgentUsage, loadSampleUsageData, parseUsageRecord, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProviderConnectorStub, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, normalizeSourceRegistry, downgradeUntrustedSourceRegistryClaims, buildSourceStatuses, slugifySourceId, financialEvidenceForRecords, formatSourceStatuses } from "@agent-finops/core";
+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, 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 { 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";
-export async function runCli(argv = process.argv.slice(2)) {
+export async function runCli(argv = process.argv.slice(2), runtime = {}) {
     if (argv.includes("--version") || argv.includes("-v")) {
         return ok(await cliVersion());
     }
@@ -34,7 +37,10 @@ export async function runCli(argv = process.argv.slice(2)) {
         return resetCommand(args);
     }
     if (args.command === "init") {
-        return initCommand(args);
+        return initCommand(args, runtime);
+    }
+    if (args.command === "statusline") {
+        return statuslineCommand(args, runtime);
     }
     if (args.command === "scan") {
         return scanCommand(args);
@@ -323,7 +329,7 @@ function quickstartNextSteps(mode, detected) {
     steps.push("Need team reconciliation, allocation, budgets, and approvals? Workspace design partners: https://ai-spend-agent.vercel.app");
     return steps;
 }
-async function readPersistedSpend(rootPath) {
+async function readPersistedSpend(rootPath, options = {}) {
     const stateDir = join(rootPath, ".ai-spend-agent");
     try {
         const exactSpendContents = await readSafeStateText(stateDir, "spend.json");
@@ -340,6 +346,9 @@ async function readPersistedSpend(rootPath) {
         const records = mode === "sample" || mode === undefined
             ? downgradeSampleUsageEvidence(parsedRecords)
             : parsedRecords;
+        if (spend.checkedAt !== undefined && !validIsoString(spend.checkedAt)) {
+            throw new Error("persisted spend checkedAt must be an ISO timestamp");
+        }
         const providerCoverage = persistedProviderCoverage(spend.accounting);
         const connectedTrust = mode === "connected_provider"
             ? await verifyConnectedSpendTrustReceipt(rootPath, exactSpendContents)
@@ -347,12 +356,16 @@ async function readPersistedSpend(rootPath) {
         return {
             mode,
             records,
+            ...(typeof spend.checkedAt === "string" ? { checkedAt: spend.checkedAt } : {}),
             ...(providerCoverage ? { providerCoverage } : {}),
             ...(isPlainObject(spend.accounting) ? { accounting: spend.accounting } : {}),
             ...(connectedTrust ? { connectedTrust } : {})
         };
     }
-    catch {
+    catch (error) {
+        if (options.strict && !isNodeError(error, "ENOENT")) {
+            throw new Error("Existing .ai-spend-agent/spend.json is invalid or unsafe; it was preserved and init stopped.");
+        }
         return undefined;
     }
 }
@@ -991,44 +1004,668 @@ async function resetCommand(args) {
         "next run will re-read your real local agent logs (or demo sample if none)."
     ].join("\n"));
 }
-async function initCommand(args) {
-    const rootPath = resolve(args.path);
-    const stateDir = join(rootPath, ".ai-spend-agent");
-    await mkdir(stateDir, { recursive: true });
-    const registry = createLocalFolderSourceRegistry(rootPath);
-    await writeJson(join(stateDir, "manifest.json"), {
+async function statuslineCommand(args, runtime) {
+    const action = args.statuslineAction;
+    if (action === undefined) {
+        const cache = await readStatuslineCache({
+            cacheDirectory: process.env.AIBILL_CACHE_DIR,
+            homeDirectory: runtime.homeDirectory
+        });
+        return ok(renderStatusline(cache, {
+            now: runtime.statuslineNow,
+            columns: runtime.statuslineColumns,
+            timeZone: runtime.statuslineTimeZone
+        }));
+    }
+    if (action === "install")
+        return installStatuslineCommand(args, runtime);
+    if (action === "uninstall")
+        return uninstallStatuslineCommand(runtime);
+    if (action === "refresh")
+        return refreshStatuslineCommand(args, runtime);
+    return {
+        exitCode: 1,
+        stdout: "",
+        stderr: `Unknown statusline action: ${sanitizeSecretishError(action)}\n` +
+            "Use: aibill statusline [refresh|install|uninstall]"
+    };
+}
+async function packagedStatuslineRunner(runtime) {
+    if (runtime.statuslineRunnerContents !== undefined) {
+        return runtime.statuslineRunnerContents;
+    }
+    return readFile(fileURLToPath(new URL("./statuslineRuntime.js", import.meta.url)));
+}
+async function installStatuslineCommand(args, runtime) {
+    try {
+        const result = await installClaudeStatusline({
+            homeDir: runtime.homeDirectory ?? homedir(),
+            cwd: resolve(args.path),
+            runnerContents: await packagedStatuslineRunner(runtime),
+            replace: args.replaceStatusline
+        });
+        return ok([
+            result.action === "unchanged"
+                ? "aibill statusline is already installed in Claude user settings."
+                : "aibill statusline installed in Claude user settings.",
+            "Claude Code: run /status to verify the active setting and every managed source.",
+            "The renderer reads only the private aibill cache; it never reads Claude's session stdin as financial evidence."
+        ].join("\n"));
+    }
+    catch (error) {
+        return statuslineInstallerFailure("install", error);
+    }
+}
+async function uninstallStatuslineCommand(runtime) {
+    try {
+        const result = await uninstallClaudeStatusline({
+            homeDir: runtime.homeDirectory ?? homedir(),
+            cwd: process.cwd()
+        });
+        return ok([
+            result.statusLineAction === "restored-prior"
+                ? "aibill statusline was removed and the prior Claude user statusLine was restored."
+                : "aibill statusline was removed from Claude user settings.",
+            {
+                removed: "The owned standalone runner was removed.",
+                restored: "The exact pre-installation runner was restored.",
+                "preserved-modified": "The modified runner was preserved because it was no longer owned.",
+                "already-missing": "The owned runner was already missing; no runner file was removed."
+            }[result.runnerAction],
+            ...result.warnings
+        ].join("\n"));
+    }
+    catch (error) {
+        return statuslineInstallerFailure("uninstall", error);
+    }
+}
+function statuslineInstallerFailure(action, error) {
+    const installerError = error instanceof StatuslineInstallerError
+        ? error
+        : new StatuslineInstallerError("unsafe-settings-file", `The local filesystem operation failed safely${safeFileSystemErrorCode(error)}; no successful settings change was claimed.`);
+    const replacement = installerError.code === "statusline-conflict"
+        ? "\nTo replace an existing status line explicitly: aibill statusline install --replace"
+        : "";
+    return {
+        exitCode: 1,
+        stdout: "",
+        stderr: [
+            `aibill statusline ${action} stopped safely: ${sanitizeSecretishError(installerError.message)}`,
+            "No successful settings change was claimed. Resolve the conflict, then verify active sources with /status in Claude Code.",
+            replacement.trim()
+        ].filter(Boolean).join("\n")
+    };
+}
+function safeFileSystemErrorCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return "";
+    const code = String(error.code ?? "");
+    return /^[A-Z][A-Z0-9_]{1,31}$/.test(code) ? ` (${code})` : "";
+}
+async function initCommand(args, runtime = {}) {
+    if (args.sample) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "aibill init only initializes from real local evidence; --sample was not used and no state or cache was changed. Run `npx aibill --sample` for the illustrative demo."
+        };
+    }
+    let detectedPlanOverride;
+    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(", ")}`
+            };
+        }
+        detectedPlanOverride = [override];
+    }
+    const rootPath = await resolveSafeScanRoot(args.path);
+    const cacheDirectory = process.env.AIBILL_CACHE_DIR;
+    await preflightInitCache(cacheDirectory);
+    let stateDir;
+    let stateDirectoryExists = true;
+    try {
+        stateDir = await resolveSafeStateDirectory(rootPath);
+    }
+    catch (error) {
+        if (!isNodeError(error, "ENOENT"))
+            throw error;
+        stateDirectoryExists = false;
+        stateDir = join(rootPath, ".ai-spend-agent");
+    }
+    const statePreparedAt = new Date();
+    // Preflight every existing project file before any mutation. Valid files are
+    // left byte-for-byte alone so a repeated init cannot erase connector
+    // configuration, audit history, provider trust, spend state, or unknown
+    // forward-compatible fields. The manifest remains the completion marker and
+    // is written last.
+    const existingManifest = stateDirectoryExists
+        ? await readInitJsonObject(stateDir, "manifest.json", { allowMissing: true })
+        : undefined;
+    const existingRegistry = stateDirectoryExists
+        ? await readInitJsonObject(stateDir, "sources.json", { allowMissing: true })
+        : undefined;
+    const existingAuditLog = stateDirectoryExists
+        ? await readInitJsonObject(stateDir, "audit-log.json", { allowMissing: true })
+        : undefined;
+    if (existingRegistry)
+        normalizeSourceRegistry(existingRegistry);
+    validateInitAuditLog(existingAuditLog);
+    const refresh = await collectAndPublishActivitySnapshot({
+        rootPath,
+        cacheDirectory,
+        detectedPlanOverride
+    });
+    const { asOf, activitySnapshot, logs, detectedPlans, trustedProviderRecords, persisted, scanError, cacheStatus } = refresh;
+    if (!stateDirectoryExists) {
+        stateDir = await resolveSafeStateDirectory(rootPath, { create: true });
+    }
+    await preserveOrCreateInitRegistry(stateDir, rootPath, statePreparedAt, existingRegistry);
+    await preserveOrCreateInitAuditLog(stateDir, rootPath, statePreparedAt, existingAuditLog);
+    const manifest = buildInitManifest(existingManifest, asOf);
+    await writeSafeStateText(stateDir, "manifest.json", `${JSON.stringify(manifest, null, 2)}\n`);
+    const receipt = formatInitReceipt({
+        rootPath,
+        asOf,
+        activitySnapshot,
+        logs,
+        detectedPlans,
+        trustedProviderRecords,
+        providerCoverage: persisted?.providerCoverage,
+        trustedProviderState: persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === true,
+        untrustedProviderState: persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted !== true,
+        scanError,
+        cacheStatus
+    });
+    if (!args.statusline) {
+        return ok(`${receipt}\noptional Claude Code status line: npx aibill statusline install`);
+    }
+    const installation = await installStatuslineCommand(args, runtime);
+    return installation.exitCode === 0
+        ? ok(`${receipt}\n${installation.stdout}`)
+        : {
+            exitCode: installation.exitCode,
+            stdout: receipt,
+            stderr: installation.stderr
+        };
+}
+async function collectAndPublishActivitySnapshot(input) {
+    // One attempt anchor binds every rolling window and cache ordering decision.
+    const asOf = new Date();
+    const planPromise = input.detectedPlanOverride
+        ? Promise.resolve(input.detectedPlanOverride)
+        : detectLocalPlans({
+            claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
+            codexAuthPath: process.env.AI_SPEND_CODEX_AUTH
+        }).catch(() => []);
+    // Attach the rejection handler immediately so a failed transcript scan can
+    // never leave an unhandled persisted-state rejection behind.
+    const persistedPromise = readPersistedSpend(input.rootPath, { strict: true }).then((persisted) => ({ persisted }), (error) => ({ error }));
+    let logs;
+    let scanError;
+    try {
+        logs = await loadLocalAgentFinancialUsage({
+            claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
+            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+            sinceIso: sinceIsoForDays(30, asOf)
+        });
+    }
+    catch (error) {
+        scanError = sanitizeSecretishError(error instanceof Error ? error.message : String(error));
+    }
+    const [detectedPlans, persistedResult] = await Promise.all([planPromise, persistedPromise]);
+    if ("error" in persistedResult)
+        throw persistedResult.error;
+    const persisted = persistedResult.persisted;
+    const trustedProviderRecords = persisted?.mode === "connected_provider" &&
+        persisted.connectedTrust?.trusted === true
+        ? selectProviderFinancialHeadlineRecords(persisted.records)
+        : [];
+    let activitySnapshot;
+    let cacheStatus;
+    const structuredSourceFailure = logs !== undefined &&
+        logs.sourceScans.some((scan) => scan.directoryStatus === "unreadable") &&
+        !logs.sourceScans.some((scan) => scan.directoryStatus === "readable");
+    if (logs && !structuredSourceFailure) {
+        let refreshErrorCode = "invalid_evidence";
+        try {
+            activitySnapshot = buildActivitySnapshot({
+                asOf: asOf.toISOString(),
+                generatedAt: new Date().toISOString(),
+                records: [...logs.records, ...trustedProviderRecords],
+                calls: logs.calls,
+                detectedPlans,
+                sourceScans: logs.sourceScans,
+                trustedProviderRecordIds: trustedProviderRecords.map((record) => record.id),
+                billedOverageRecordIds: [],
+                providerCoverage: initProviderCoverage(trustedProviderRecords, persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === true
+                    ? trustedAccountingMap(persisted.accounting, "coverageByProvider")
+                    : {}, persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === true
+                    ? trustedAccountingMap(persisted.accounting, "checkedAtByProvider")
+                    : {}, persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === true
+                    ? trustedAccountingMap(persisted.accounting, "coverageIntervalsByProvider")
+                    : {}, persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === true
+                    ? persisted.checkedAt ?? persisted.connectedTrust.trustedAt
+                    : undefined),
+                sampleData: false
+            });
+            refreshErrorCode = "cache_write_failed";
+            const written = await writeActivitySnapshot(activitySnapshot, {
+                cacheDirectory: input.cacheDirectory
+            });
+            cacheStatus = written.status === "written" ? "refreshed" : "kept newer snapshot";
+        }
+        catch {
+            scanError = refreshErrorCode === "invalid_evidence"
+                ? "the observed evidence could not produce a valid activity snapshot"
+                : "the private activity cache could not be updated";
+            const failed = await recordActivitySnapshotRefreshFailure(asOf.toISOString(), refreshErrorCode, { cacheDirectory: input.cacheDirectory });
+            activitySnapshot = failed.snapshot;
+            cacheStatus = "refresh failed";
+        }
+    }
+    else {
+        const failed = await recordActivitySnapshotRefreshFailure(asOf.toISOString(), structuredSourceFailure ? "source_unreadable" : "scan_failed", { cacheDirectory: input.cacheDirectory });
+        activitySnapshot = failed.snapshot;
+        cacheStatus = "refresh failed";
+    }
+    return {
+        asOf,
+        activitySnapshot,
+        logs,
+        detectedPlans,
+        trustedProviderRecords,
+        persisted,
+        scanError,
+        cacheStatus
+    };
+}
+async function refreshStatuslineCommand(args, runtime) {
+    if (args.sample) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "aibill statusline refresh only uses real local evidence; --sample was rejected and the cache was not changed."
+        };
+    }
+    let detectedPlanOverride;
+    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(", ")}`
+            };
+        }
+        detectedPlanOverride = [override];
+    }
+    const rootPath = await resolveSafeScanRoot(args.path);
+    const cacheDirectory = process.env.AIBILL_CACHE_DIR;
+    await preflightInitCache(cacheDirectory);
+    let refresh;
+    try {
+        refresh = await collectAndPublishActivitySnapshot({
+            rootPath,
+            cacheDirectory,
+            detectedPlanOverride
+        });
+    }
+    catch (error) {
+        const attemptedAt = new Date().toISOString();
+        await recordActivitySnapshotRefreshFailure(attemptedAt, "invalid_evidence", {
+            cacheDirectory
+        }).catch(() => undefined);
+        const cache = await readStatuslineCache({
+            cacheDirectory,
+            homeDirectory: runtime.homeDirectory
+        });
+        return {
+            exitCode: 1,
+            stdout: renderStatusline(cache, {
+                now: runtime.statuslineNow,
+                columns: runtime.statuslineColumns,
+                timeZone: runtime.statuslineTimeZone
+            }),
+            stderr: `aibill statusline refresh failed safely: ${sanitizeSecretishError(error instanceof Error ? error.message : String(error))}`
+        };
+    }
+    const cache = await readStatuslineCache({
+        cacheDirectory,
+        homeDirectory: runtime.homeDirectory
+    });
+    const line = renderStatusline(cache, {
+        now: runtime.statuslineNow,
+        columns: runtime.statuslineColumns,
+        timeZone: runtime.statuslineTimeZone
+    });
+    return refresh.cacheStatus === "refresh failed"
+        ? {
+            exitCode: 1,
+            stdout: line,
+            stderr: `aibill statusline refresh failed safely: ${refresh.scanError ?? "local evidence was unavailable"}`
+        }
+        : ok(line);
+}
+async function preflightInitCache(cacheDirectory) {
+    const existing = await readActivitySnapshot({ cacheDirectory });
+    if (existing.status !== "error")
+        return;
+    throw new Error(`Existing private activity cache is ${existing.code.replaceAll("_", " ")}; ` +
+        "it was preserved and init stopped. Remove the cache explicitly before rebuilding it.");
+}
+async function preserveOrCreateInitRegistry(stateDir, rootPath, asOf, existing) {
+    if (existing) {
+        // Leave the valid contract byte-for-byte alone. Rewriting would drop
+        // unknown future fields and could invalidate a connected-state receipt
+        // bound to the exact source-registry bytes.
+        return;
+    }
+    await writeSafeStateText(stateDir, "sources.json", `${JSON.stringify(createLocalFolderSourceRegistry(rootPath, asOf), null, 2)}\n`);
+}
+async function preserveOrCreateInitAuditLog(stateDir, rootPath, asOf, existing) {
+    if (existing)
+        return;
+    const timestamp = asOf.toISOString();
+    await writeSafeStateText(stateDir, "audit-log.json", `${JSON.stringify(createScanAuditLog([{
+            timestamp,
+            action: "source_registered",
+            sourceId: "local-root",
+            path: rootPath,
+            detail: "Explicit local folder source approved during init."
+        }]), null, 2)}\n`);
+}
+function validateInitAuditLog(existing) {
+    if (existing && (existing.version !== 1 || existing.localOnly !== true || !Array.isArray(existing.events))) {
+        throw new Error("Invalid local audit log: expected the canonical local-only audit shape.");
+    }
+}
+async function readInitJsonObject(stateDir, fileName, options) {
+    let contents;
+    try {
+        contents = await readSafeStateText(stateDir, fileName);
+    }
+    catch (error) {
+        if (options.allowMissing && isNodeError(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new Error(`Invalid local ${fileName}: expected JSON; the existing file was preserved.`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new Error(`Invalid local ${fileName}: expected a JSON object; the existing file was preserved.`);
+    }
+    return parsed;
+}
+function buildInitManifest(existing, asOf) {
+    const timestamp = asOf.toISOString();
+    return {
+        ...(existing ?? {}),
         product: "aibill",
-        mode: "local-first-demo",
+        mode: "local-first",
         cloudUpload: false,
         cronJobsEnabled: false,
         redactionPolicy: "secrets are never printed; detected values are written only as [REDACTED]",
         sourceRegistry: "sources.json",
         auditLog: "audit-log.json",
+        backfillWindowDays: 30,
+        statusSnapshot: {
+            schema: "aibill.activity_snapshot/v1",
+            storage: "private external cache",
+            networkUploaded: false
+        },
+        initializedAt: typeof existing?.initializedAt === "string" ? existing.initializedAt : timestamp,
+        lastInitializedAt: timestamp,
         nextCommands: [
-            "npx aibill doctor",
-            `npx aibill scan --sample --path ${rootPath}`,
-            `npx aibill report --sample --out ai-spend-report --path ${rootPath}`
+            "npx aibill",
+            "npx aibill doctor --sources",
+            "npx aibill report"
         ]
+    };
+}
+function initProviderCoverage(records, coverageByProvider, checkedAtByProvider, coverageIntervalsByProvider, fallbackCheckedAt) {
+    const providerGroups = new Map();
+    for (const record of records) {
+        const rawProvider = record.source.provider;
+        const provider = activitySnapshotProvider(rawProvider);
+        const group = providerGroups.get(provider) ?? {
+            rawProviders: new Set(),
+            records: []
+        };
+        group.rawProviders.add(rawProvider);
+        group.records.push(record);
+        providerGroups.set(provider, group);
+    }
+    for (const rawProvider of new Set([
+        ...Object.keys(coverageByProvider),
+        ...Object.keys(checkedAtByProvider),
+        ...Object.keys(coverageIntervalsByProvider)
+    ])) {
+        const provider = activitySnapshotProvider(rawProvider);
+        const group = providerGroups.get(provider) ?? {
+            rawProviders: new Set(),
+            records: []
+        };
+        group.rawProviders.add(rawProvider);
+        providerGroups.set(provider, group);
+    }
+    return [...providerGroups.entries()].map(([provider, group]) => {
+        const coverages = [...group.rawProviders]
+            .map((rawProvider) => coverageByProvider[rawProvider] ?? coverageByProvider[provider])
+            .filter((coverage) => coverage !== undefined);
+        const status = coverages.length === group.rawProviders.size && coverages.every((coverage) => coverage === "complete")
+            ? "complete"
+            : coverages.some((coverage) => coverage === "complete" || coverage === "partial")
+                ? "partial"
+                : "unavailable";
+        const checkedValues = [...group.rawProviders]
+            .map((rawProvider) => checkedAtByProvider[rawProvider] ?? checkedAtByProvider[provider])
+            .filter((value) => validIsoString(value));
+        const receiptBoundCheckedAt = checkedValues.length === group.rawProviders.size
+            ? checkedValues.sort()[0]
+            : providerGroups.size === 1 && validIsoString(fallbackCheckedAt)
+                ? fallbackCheckedAt
+                : undefined;
+        const latestEvidenceAt = group.records
+            .map((record) => record.timestamp)
+            .filter(validIsoString)
+            .sort()
+            .at(-1);
+        const intervals = [...group.rawProviders]
+            .map((rawProvider) => coverageIntervalsByProvider[rawProvider] ?? coverageIntervalsByProvider[provider])
+            .filter(validProviderCoverageInterval);
+        const coverageStart = intervals.length === group.rawProviders.size
+            ? intervals.map((interval) => interval.coverageStart).sort().at(-1)
+            : undefined;
+        const coverageEnd = intervals.length === group.rawProviders.size
+            ? intervals.map((interval) => interval.coverageEnd).sort()[0]
+            : undefined;
+        return {
+            provider,
+            status,
+            validationCoverage: sourceStatusDefinitions.find((definition) => definition.id === provider)?.validationCoverage
+                ?? "untested",
+            ...(receiptBoundCheckedAt ? { checkedAt: receiptBoundCheckedAt } : {}),
+            ...(receiptBoundCheckedAt && latestEvidenceAt ? { latestEvidenceAt } : {}),
+            ...(receiptBoundCheckedAt && coverageStart && coverageEnd && Date.parse(coverageStart) <= Date.parse(coverageEnd)
+                ? { coverageStart, coverageEnd }
+                : {})
+        };
+    }).sort((left, right) => left.provider.localeCompare(right.provider));
+}
+function validProviderCoverageInterval(value) {
+    return isPlainObject(value) &&
+        validIsoString(value.coverageStart) &&
+        validIsoString(value.coverageEnd) &&
+        Date.parse(value.coverageStart) <= Date.parse(value.coverageEnd);
+}
+function activitySnapshotProvider(provider) {
+    if (provider === "openai" || provider === "anthropic" || provider === "cursor" || provider === "github-copilot") {
+        return provider;
+    }
+    return "other";
+}
+function formatInitReceipt(input) {
+    const records = input.logs?.records ?? [];
+    const pricedRecords = records.filter((record) => typeof record.amountUsd === "number");
+    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
+        ? ["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 planLine = input.detectedPlans.length > 0
+        ? input.detectedPlans.map((plan) => {
+            const known = plan.planId ?? "unrecognized plan";
+            return `${plan.agent}: ${known} (${plan.billing})`;
+        }).join("; ")
+        : "none detected (billing mode remains unresolved)";
+    const sourceLines = (input.logs?.sourceScans ?? [
+        emptyInitSourceScan("claude-code"),
+        emptyInitSourceScan("codex")
+    ]).map((scan) => {
+        const agentRecords = records.filter((record) => record.agentId === scan.agent);
+        const priced = agentRecords.filter((record) => typeof record.amountUsd === "number").length;
+        const skipped = scan.filesSkippedBeforeWindow ?? 0;
+        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}`;
     });
-    await writeJson(join(stateDir, "sources.json"), registry);
-    await writeJson(join(stateDir, "audit-log.json"), createScanAuditLog([
-        {
-            timestamp: registry.updatedAt,
-            action: "source_registered",
-            sourceId: "local-root",
-            path: rootPath,
-            detail: "Explicit local folder source approved during init."
-        }
-    ]));
-    return ok([
+    const diagnosticLines = (input.logs?.diagnostics ?? [])
+        .filter((diagnostic) => diagnostic.code !== "directory_missing")
+        .map((diagnostic) => `  ! ${sanitizeSecretishError(diagnostic.message)} (${diagnostic.count})`);
+    const providerLines = formatInitProviderEvidence(input);
+    return [
         "aibill init",
-        `path: ${rootPath}`,
-        "demo mode: local-first sample workflow",
-        "cloud upload: disabled",
-        "cron jobs: disabled in V0 demo",
-        `state directory: ${stateDir}`,
-        `next: npx aibill scan --sample --path ${rootPath}`
-    ].join("\n"));
+        `state project: ${sanitizeSecretishError(basename(input.rootPath))}`,
+        "local usage scope: all Claude Code + Codex activity 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",
+        ...receiptLines,
+        `observed records: ${records.length}; priced: ${pricedRecords.length}; unpriced: ${records.length - pricedRecords.length}`,
+        ...providerLines,
+        `plans: ${planLine}`,
+        "",
+        "source diagnostics (same backfill scan; no second scan):",
+        ...sourceLines,
+        ...diagnosticLines,
+        input.scanError ? `  ! scan failed: ${input.scanError}` : "",
+        "",
+        `status cache: ${input.cacheStatus} · private local aggregate · nothing uploaded`,
+        "state: .ai-spend-agent",
+        "manifest: written last",
+        "next: npx aibill doctor --sources"
+    ].filter((line) => line !== "").join("\n");
+}
+function formatInitProviderEvidence(input) {
+    const windowStart = input.asOf.getTime() - 30 * 24 * 60 * 60 * 1_000;
+    const inWindow = input.trustedProviderRecords.filter((record) => {
+        const timestamp = Date.parse(record.timestamp);
+        return Number.isFinite(timestamp) && timestamp >= windowStart && timestamp <= input.asOf.getTime();
+    });
+    const priced = inWindow.filter((record) => typeof record.amountUsd === "number");
+    const verified = priced.filter((record) => record.costConfidence === "verified");
+    const estimatedApiEquivalent = priced.filter((record) => record.costConfidence === "estimated" &&
+        record.providerCostType === "anthropic_claude_code_usage");
+    const estimated = priced.filter((record) => record.costConfidence === "estimated" &&
+        record.providerCostType !== "anthropic_claude_code_usage");
+    const detected = priced.filter((record) => record.costConfidence === "detected_unverified");
+    const unpriced = inWindow.length - priced.length;
+    const lines = [];
+    if (verified.length > 0) {
+        const billedWindow = input.activitySnapshot?.metered?.providerBilled.thirtyDays;
+        lines.push(billedWindow?.amountUsd !== null && billedWindow?.amountUsd !== undefined
+            ? `provider-billed cost: ${formatOptionalUsd(billedWindow.amountUsd)} verified (kept separate)`
+            : "provider-billed cost: unavailable — billed bucket boundaries do not prove an exact 30-day amount");
+    }
+    if (estimated.length > 0) {
+        lines.push(`provider financial estimate: ${formatOptionalUsd(analyzeSpend(estimated).totalUsd)} estimated; not verified billed spend (kept separate)`);
+    }
+    if (estimatedApiEquivalent.length > 0) {
+        lines.push(`provider API-equivalent estimate: ${formatOptionalUsd(analyzeSpend(estimatedApiEquivalent).totalUsd)} estimated value; not verified billed spend (kept separate)`);
+    }
+    if (detected.length > 0) {
+        lines.push(`provider cost: ${formatOptionalUsd(analyzeSpend(detected).totalUsd)} detected_unverified; not billed spend (kept separate)`);
+    }
+    if (unpriced > 0) {
+        lines.push(`provider cost: unavailable — ${unpriced} trusted row(s) lacked a supported cost amount`);
+    }
+    const provedEmptyBilledWindow = input.activitySnapshot?.metered?.providerBilled.thirtyDays;
+    if (verified.length === 0 && provedEmptyBilledWindow?.amountUsd === 0 &&
+        provedEmptyBilledWindow.financialEvidence === "verified") {
+        lines.push("provider-billed cost: $0.00 verified for the receipt-bound 30-day interval");
+    }
+    if (lines.length === 0) {
+        lines.push(input.untrustedProviderState
+            ? "provider-billed cost: unavailable — untrusted repository state was ignored"
+            : input.trustedProviderRecords.length > 0
+                ? "provider cost: unavailable — connected evidence had no supported row in the last 30 days"
+                : input.trustedProviderState
+                    ? "provider-billed cost: unavailable — trusted connected provider evidence exists, but no receipt-bound 30-day amount was proven"
+                    : "provider-billed cost: not connected");
+    }
+    if (input.providerCoverage)
+        lines.push(`provider coverage: ${input.providerCoverage}`);
+    return lines;
+}
+function initApiEquivalentWindowLines(snapshot) {
+    if (snapshot.mode === "error") {
+        return ["API-equivalent usage value: unavailable — refresh failed"];
+    }
+    if (snapshot.mode === "empty") {
+        const completeZero = snapshot.coverage.recordsParsed === 0 &&
+            snapshot.coverage.agents.length > 0 &&
+            snapshot.coverage.agents.every((agent) => agent.directoryStatus === "readable" &&
+                agent.malformedLines === 0 &&
+                agent.unreadableFiles === 0 &&
+                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 — local source coverage is incomplete; no zero total was inferred"];
+    }
+    if (snapshot.mode === "unresolved" && snapshot.unresolved) {
+        return [formatInitApiWindows("billing unresolved", snapshot.unresolved.apiEquivalent)];
+    }
+    const lines = [];
+    for (const agent of snapshot.subscription?.agents ?? []) {
+        lines.push(formatInitApiWindows(`${agent.agent} subscription value`, agent.apiEquivalent));
+    }
+    if (snapshot.metered && snapshot.metered.apiEquivalent.thirtyDays.recordCount > 0) {
+        lines.push(formatInitApiWindows("metered API-equivalent value", snapshot.metered.apiEquivalent));
+    }
+    if (snapshot.unresolved && snapshot.unresolved.apiEquivalent.thirtyDays.recordCount > 0) {
+        lines.push(formatInitApiWindows("billing unresolved", snapshot.unresolved.apiEquivalent));
+    }
+    return lines.length > 0
+        ? lines
+        : ["API-equivalent usage value: unavailable — no priced local value was observed"];
+}
+function formatInitApiWindows(label, windows) {
+    const amount = (value) => value === null ? "unavailable" : `~${formatOptionalUsd(value)}`;
+    return `${label}: ${amount(windows.oneDay.amountUsd)} 1d · ${amount(windows.sevenDays.amountUsd)} 7d · ${amount(windows.thirtyDays.amountUsd)} 30d (API-equivalent; not billed spend)`;
+}
+function emptyInitSourceScan(agent) {
+    return {
+        agent,
+        directoryStatus: "unreadable",
+        filesDiscovered: 0,
+        filesParsed: 0,
+        malformedLines: 0,
+        unreadableFiles: 0,
+        unsupportedUsageSnapshots: 0
+    };
 }
 async function scanCommand(args) {
     const rootPath = resolve(args.path);
@@ -1507,6 +2144,16 @@ async function syncProviderCommand(args) {
             ...trustedAccountingMap(trustedPrior?.accounting, "financialsByProvider"),
             [result.provider]: result.financials
         };
+        const checkedAtByProvider = {
+            ...trustedAccountingMap(trustedPrior?.accounting, "checkedAtByProvider"),
+            [result.provider]: result.fetchedAt
+        };
+        const priorCoverageIntervals = trustedAccountingMap(trustedPrior?.accounting, "coverageIntervalsByProvider");
+        const coverageIntervalsByProvider = Object.fromEntries(Object.entries(priorCoverageIntervals).filter(([provider]) => provider !== result.provider));
+        const requestedCoverageInterval = result.coverageInterval;
+        if (requestedCoverageInterval) {
+            coverageIntervalsByProvider[result.provider] = requestedCoverageInterval;
+        }
         // Invalidate any earlier receipt before the first mutation. If a later
         // local write fails, the partially updated repository state stays
         // untrusted rather than inheriting the previous sync's authority.
@@ -1523,7 +2170,11 @@ async function syncProviderCommand(args) {
             records,
             qa: result.qa,
             qaByProvider,
+            checkedAtByProvider,
             coverageByProvider,
+            ...(Object.keys(coverageIntervalsByProvider).length > 0
+                ? { coverageIntervalsByProvider }
+                : {}),
             financialsByProvider
         });
         await recordProviderSourceAttempt(stateDir, result.provider, result.fetchedAt, result.coverage === "partial"
@@ -1533,9 +2184,11 @@ async function syncProviderCommand(args) {
             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,
+            checkedAtByProvider,
+            coverageIntervalsByProvider,
             qaByProvider,
             financialsByProvider
-        });
+        }, result.fetchedAt);
         await appendAuditEvent(stateDir, {
             timestamp: result.fetchedAt,
             action: "source_scanned",
@@ -2092,6 +2745,9 @@ function parseArgs(argv) {
         sample: false,
         path: process.cwd()
     };
+    if (command === "statusline" && rest[0] && !rest[0].startsWith("--")) {
+        parsed.statuslineAction = rest.shift();
+    }
     if (command === "connect" && rest[0] && !rest[0].startsWith("--")) {
         parsed.provider = rest[0];
         rest.shift();
@@ -2114,6 +2770,14 @@ function parseArgs(argv) {
             parsed.sources = true;
             continue;
         }
+        if (arg === "--statusline") {
+            parsed.statusline = true;
+            continue;
+        }
+        if (arg === "--replace") {
+            parsed.replaceStatusline = true;
+            continue;
+        }
         if (arg === "--ignore-state") {
             parsed.ignoreState = true;
             continue;
@@ -2373,12 +3037,13 @@ function stripTerminalControlSequences(message) {
 function isPersistedDataMode(value) {
     return value === "sample" || value === "local_logs" || value === "connected_provider";
 }
-async function writeLocalSpendState(stateDir, records, summary, mappings, mode, accounting) {
+async function writeLocalSpendState(stateDir, records, summary, mappings, mode, accounting, checkedAt) {
     if (mode !== "connected_provider") {
         await invalidateConnectedSpendTrustReceipt(dirname(stateDir));
     }
     await writeJson(join(stateDir, "spend.json"), {
         mode,
+        ...(checkedAt && validIsoString(checkedAt) ? { checkedAt } : {}),
         records,
         summary,
         ...(accounting ? { accounting } : {})
@@ -2486,7 +3151,13 @@ function helpText() {
         "",
         "Other commands:",
         "  --version, -v           Print the package version without reading local data",
-        "  init [--path <dir>]     Initialize local state",
+        "  init [--path <dir>]     Backfill 30 days machine-wide, print the first evidence-labeled receipt, and cache a private snapshot",
+        "    [--statusline]        Explicitly install the Claude Code status line after a successful init",
+        "  statusline              Render one plan-aware line from the private cache (no scan or network)",
+        "  statusline refresh      Foreground refresh from real local evidence, then render the cache",
+        "  statusline install      Reversibly add the standalone runner to Claude user settings",
+        "    [--replace]           Explicitly replace an existing statusLine while preserving it for uninstall",
+        "  statusline uninstall    Remove only the owned setting and restore its preserved predecessor",
         "  doctor [--sources]      Launch diagnostics; --sources shows validation, evidence, freshness, and errors",
         "  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",
@@ -2566,7 +3237,7 @@ export async function runMain() {
             stdout: "",
             stderr: [
                 `aibill hit an unexpected error: ${message}`,
-                "Nothing was uploaded; local state is unchanged.",
+                "Nothing was uploaded. The command stopped without completing; run diagnostics before retrying.",
                 "Try `npx aibill doctor` for diagnostics, or open an issue: https://github.com/futurastudio/ai-spend-agent/issues"
             ].join("\n")
         };