ai-spend-agent 0.9.5 → 0.9.6

package/dist/index.js

@@ -9,7 +9,7 @@ import { askGuidedQuestion, classifyGuidedAnswer, createInteractivePromptSource,
 import { assessEmailDeliverability, buildWaitlistRef, normalizeWaitlistEmail, postWaitlistSignup, readSignupState, clearSignupState, sanitizeSignupRefTag, serializeWaitlistPayload, signupAskTimeoutMs, signupCopy, signupStateFilePath, writeSignupState } from "./signup.js";
 import { killTelemetryForThisProcess, readTelemetryState, telemetryDisclosureLine, telemetryStateFilePath, writeTelemetryState } from "./telemetry.js";
 import { parsePlanDraft, renderCleanExit, runIdentitySequence, runPlanSitting, runQualitySitting, runRecordSitting, runRollbackSitting, runStartSitting, shortSittingHint } from "./improveFlow.js";
-import { analyzeSpend, APPROVAL_EVENT_V0_KIND, buildContextHealth, buildActionVerificationProjectionV0, buildProjectEconomicsProjectionV0, buildTokenReductionBaselineV0, aibillCommandV0, aibillImproveCommandV0, decodeAgentDraftTokenV1, IMPROVE_USER_SAFETY_LINE_V1, looksLikeAgentDraftToken, screenAgentDraftSentence, attributeUsageRecords, buildUsageGlance, buildActivitySnapshot, buildResultCard, buildResultCardProjectLine, formatBilledUsdExact, formatCommittedPerMonth, resultCardSchema, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, invalidateConnectedSpendTrustReceipt, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, SAFE_QUALITATIVE_SCAN_POLICY, summarizeProviderFinancials, providerFinancialCompleteness, providerAccountKey, tagProviderAccountRecords, retainProviderRecordsForNewSync, providerAccountSlices, formatProviderAccountSlices, intersectProviderCoverageIntervals, duplicateProviderAccountSliceWarnings, providerSliceReplacementNotices, writeSafeStateText, verifyConnectedSpendTrustReceipt, verifyConnectedSourceRegistryTrustReceipt, writeConnectedSpendTrustReceipt, loadDeadContext, sampleDeadContext, sanitizeLocalActivityText, latestObservedWorkingDirectory, downgradeSampleUsageEvidence, isBundledSampleUsage, hasCompleteQualitativeCoverage, hasExactSelectedQualitativeEvidence, loadLocalAgentActionEvidence, extractSessionVitalsV0, loadLocalAgentFinancialUsage, localAgentFormatDescriptors, localAgentFormatLabel, localAgentFormatSupports, loadSampleUsageData, parseUsageRecord, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProjectIndexAdapters, createActionVerificationReference, createProjectEconomicsReference, createProjectEconomicsPlannedActionRefV0, PROJECT_ECONOMICS_V0_VERSION, createProviderConnectorStub, createProviderConnection, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, normalizeSourceRegistry, downgradeUntrustedSourceRegistryClaims, buildSourceStatuses, applyProviderContractGate, applyProviderContractGateToSourceRegistry, slugifySourceId, financialEvidenceForRecords, formatSourceStatuses, markTokenReductionAppliedV0, invalidateTokenReductionExperimentV0, markTokenReductionRolledBackV0, activitySnapshotCachePath, readActivitySnapshot, recordActivitySnapshotRefreshFailure, refreshTokenReductionExperimentV0, resolveWasteFindingTargetV0, selectBestWasteFindingV0, sourceStatusDefinitions, writeActivitySnapshot } from "@agent-finops/core";
+import { analyzeSpend, APPROVAL_EVENT_V0_KIND, buildContextHealth, buildActionVerificationProjectionV0, buildProjectEconomicsProjectionV0, buildTokenReductionBaselineV0, aibillCommandV0, aibillImproveCommandV0, decodeAgentDraftTokenV1, IMPROVE_USER_SAFETY_LINE_V1, looksLikeAgentDraftToken, screenAgentDraftSentence, attributeUsageRecords, buildUsageGlance, buildActivitySnapshot, buildResultCard, buildResultCardProjectLine, formatBilledUsdExact, formatCommittedPerMonth, resultCardSchema, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, invalidateConnectedSpendTrustReceipt, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, SAFE_QUALITATIVE_SCAN_POLICY, summarizeProviderFinancials, providerFinancialCompleteness, providerAccountKey, tagProviderAccountRecords, retainProviderRecordsForNewSync, providerAccountSlices, formatProviderAccountSlices, intersectProviderCoverageIntervals, duplicateProviderAccountSliceWarnings, providerSliceReplacementNotices, writeSafeStateText, verifyConnectedSpendTrustReceipt, verifyConnectedSourceRegistryTrustReceipt, writeConnectedSpendTrustReceipt, generateCutList, loadDeadContext, sampleDeadContext, sanitizeLocalActivityText, latestObservedWorkingDirectory, downgradeSampleUsageEvidence, isBundledSampleUsage, hasCompleteQualitativeCoverage, hasExactSelectedQualitativeEvidence, loadLocalAgentActionEvidence, extractSessionVitalsV0, loadLocalAgentFinancialUsage, localAgentFormatDescriptors, localAgentFormatLabel, localAgentFormatSupports, loadSampleUsageData, parseUsageRecord, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProjectIndexAdapters, createActionVerificationReference, createProjectEconomicsReference, createProjectEconomicsPlannedActionRefV0, PROJECT_ECONOMICS_V0_VERSION, createProviderConnectorStub, createProviderConnection, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, normalizeSourceRegistry, downgradeUntrustedSourceRegistryClaims, buildSourceStatuses, applyProviderContractGate, applyProviderContractGateToSourceRegistry, slugifySourceId, financialEvidenceForRecords, formatSourceStatuses, markTokenReductionAppliedV0, invalidateTokenReductionExperimentV0, markTokenReductionRolledBackV0, activitySnapshotCachePath, readActivitySnapshot, recordActivitySnapshotRefreshFailure, refreshTokenReductionExperimentV0, resolveWasteFindingTargetV0, selectBestWasteFindingV0, sourceStatusDefinitions, writeActivitySnapshot } from "@agent-finops/core";
 import { StatuslineInstallerError, installClaudeStatusline, refreshOwnedStatuslineRunner, uninstallClaudeStatusline } from "./statuslineInstaller.js";
 import { readStatuslineCache, renderStatusline } from "./statuslineRuntime.js";
 import { chooseLatestTokenReductionExperiment, loadTokenVerificationState, upsertTokenReductionExperiment } from "./tokenVerificationState.js";
@@ -17,8 +17,8 @@ import { buildGuidedExperience } from "./guidedExperience.js";
 import { buildImproveExperience } from "./improveExperience.js";
 import { appendAcceptedProjectOutcome, appendProjectApprovalEvent, createProjectAccountabilityOwnership, loadProjectAccountabilityState, projectAccountabilityStatePath, upsertConfirmedProjectOwnership } from "./projectAccountabilityState.js";
 import { fetchGitHubAcceptedOutcomeV0 } from "./githubAcceptedOutcome.js";
-import { decideReportAutoOpen, openReportInBrowser } from "./reportOpener.js";
-import { generateActionPlanMarkdown, generateApplyArtifactMarkdown, generateCommandSummary, generateDemoPackageMarkdown, generateHtmlReport, generateMarkdownReport, generatePlainEnglishSummary, generatePolicyConfigDraftMarkdown, generateReportCardCaption, generateReportCardSvg, generateVerificationPlanMarkdown, groupByDimensions } from "@agent-finops/report";
+import { decideReportAutoOpen, openReportInBrowser, platformOpenCommand } from "./reportOpener.js";
+import { generateActionPlanMarkdown, generateApplyArtifactMarkdown, generateCommandSummary, generateDemoPackageMarkdown, generateHtmlReport, generateMarkdownReport, generatePlainEnglishSummary, generatePolicyConfigDraftMarkdown, generateReceiptCompanionHtml, generateReportCardCaption, generateReportCardSvg, generateVerificationPlanMarkdown, groupByDimensions, shellPathPointer } from "@agent-finops/report";
 // One shared v2 sharded store instance for BOTH evidence kinds: the v1
 // monolithic qualitative adapter re-probed git privacy on every read (176
 // spawned git processes per warm run with $HOME itself a git repo) and
@@ -102,7 +102,7 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
         return reportCommand(args, runtime);
     }
     if (args.command === "report-card") {
-        return reportCardCommand(args);
+        return reportCardCommand(args, runtime);
     }
     if (args.command === "glance") {
         return glanceCommand(args);
@@ -166,52 +166,19 @@ async function quickstartCommand(args, runtime = {}) {
             stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
         };
     }
-    const { records, mode, warnings, providerCoverage, codexInvocationFiles, actionEvidence, localFinancialRecords, financialCoverageComplete } = await loadInstantReadData(args);
+    // ONE evidence bundle, shared with the machine-wide `report` (0.9.6) so the
+    // readout and the written artifact can never disagree.
+    const evidence = await loadBroadScanEvidence(args, sinceDays);
+    const { records, mode, warnings, providerCoverage, actionEvidence, financialCoverageComplete, summaryRecords, summary, detectedPlans, deadContext } = evidence;
     if (records.length === 0) {
         return noEvidenceResult("receipt", warnings, sinceDays, runtime.telemetryDisclosure);
     }
-    const summaryRecords = mode === "connected"
-        ? selectProviderFinancialHeadlineRecords(records)
-        : records;
-    const summary = analyzeSpend(summaryRecords);
-    // Connected receipts stay billed-primary but never ERASE the estimated
-    // axis: local transcript records ride along so subscription rows keep
-    // their ~ API-equivalent figures next to billed money (C-lane §1.4). The
-    // renderer classifies each record by basis and never blends the totals.
-    const receiptRecords = mode === "connected" && (localFinancialRecords?.length ?? 0) > 0
-        ? [...summaryRecords, ...localFinancialRecords]
-        : summaryRecords;
+    const receiptRecords = evidence.analysisRecords;
     // 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");
     const color = args.noColor ? false : undefined;
     const outputWidth = terminalOutputWidth();
-    // Persona: --plan override wins; otherwise read the plans the coding agents
-    // themselves persisted locally (read-only, whitelisted fields, no network).
-    let detectedPlans;
-    if (args.sample) {
-        // An explicit sample run must be deterministic and safe to record/share.
-        // Never mix the developer's real local plan into illustrative output.
-        detectedPlans = [];
-    }
-    else if (args.plan) {
-        const override = planOverrideFromFlag(args.plan);
-        if (!override) {
-            return {
-                exitCode: 1,
-                stdout: "",
-                stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
-            };
-        }
-        detectedPlans = [override];
-    }
-    else {
-        detectedPlans = await detectLocalPlans({
-            // Env overrides keep tests (and unusual installs) isolated from $HOME.
-            claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
-            codexAuthPath: process.env.AI_SPEND_CODEX_AUTH
-        }).catch(() => []);
-    }
     // Surface auto-detected credentials so the user knows their next 2-min step,
     // without ever printing a raw secret.
     // Sample output is designed for demos, docs, and screenshots. Keeping local
@@ -224,32 +191,6 @@ async function quickstartCommand(args, runtime = {}) {
             home: process.env.AI_SPEND_CLAUDE_HOME_DIR
         });
     const nextSteps = quickstartNextSteps(mode, detection.credentials);
-    // Dead-context cost, globalized across the user's whole Claude Code setup
-    // (all projects' MCP + user-scope skills/agents/commands, vs. every
-    // transcript) so it's populated from ANY directory on the first run.
-    // Never throws into the readout.
-    let deadContext = args.sample
-        ? undefined
-        : 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: sinceIsoForDays(sinceDays),
-            windowDays: sinceDays,
-            codexInvocationFiles
-        }).catch(() => undefined);
-    // Sample dead-context is shown ONLY on the demo readout. A real readout
-    // (local logs / connected billing) never gets fabricated waste injected —
-    // a genuinely clean setup earns its congratulation line instead.
-    if (mode === "demo" && (!deadContext || !deadContext.hasData)) {
-        deadContext = sampleDeadContext();
-    }
     const guidedExperience = !args.sample && actionEvidence
         ? await buildQuickstartGuidedExperience({
             args,
@@ -262,6 +203,11 @@ async function quickstartCommand(args, runtime = {}) {
         : undefined;
     const summaryText = generatePlainEnglishSummary(summary, {
         records: receiptRecords,
+        // The same array the machine-wide report renders into its ACT section.
+        cutList: evidence.actionCandidates,
+        // …and the same coverage facts the artifact discloses in its banner, so
+        // the two surfaces state the same thing about what was actually read.
+        ...(actionEvidence ? { qualitativeCoverage: summarizeCliQualitativeCoverage(actionEvidence) } : {}),
         groupBy,
         color,
         mode,
@@ -275,7 +221,7 @@ async function quickstartCommand(args, runtime = {}) {
         detectedPlans,
         // 0.9.5: from a broad root the --full view's project-scoped pointers
         // (apply, apply-artifact, watch, connect) carry the machine-wide
-        // report's `cd <project> && …` prefix instead of advertising commands
+        // report's `cd /path/to/project && …` prefix instead of advertising commands
         // that friendly-refuse right where they were printed.
         commandScope: isBroadScanRoot(args.path) ? "machine-wide" : "project",
         // C-lane §1.4: the result card header states the evidence window.
@@ -617,20 +563,31 @@ 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
     // the report/waitlist pointers.
+    // Command steps are STRUCTURED, never hand-padded: every option handed to
+    // the readout passes through a sanitizer that collapses whitespace runs, so
+    // "npx aibill report              write a shareable report" reached the user
+    // as "npx aibill report write a shareable report" — no visible boundary
+    // between the command and its description (0.9.6).
     const steps = [];
     if (detected.length > 0) {
         const names = detected.map((credential) => `${credential.provider} (${credential.hint})`).join(", ");
         steps.push(`Found local key${detected.length === 1 ? "" : "s"}: ${names}`);
-        steps.push(`npx aibill connect ${detected[0].provider}   set up the admin connector, then sync provider-reported cost`);
+        steps.push({
+            command: `npx aibill connect ${detected[0].provider}`,
+            description: "set up the admin connector, then sync provider-reported cost"
+        });
     }
     steps.push(mode === "demo"
         // 0.9.4: report --sample runs as printed from ANY directory — broad
         // roots write ./ai-spend-report.{md,html} machine-wide-style, project
         // folders keep .ai-spend-agent/report.* (the old mkdir demo-workspace
         // preamble is no longer needed for the command to run as printed).
-        ? "npx aibill report --sample     write a clearly labeled demo report right here"
-        : "npx aibill report              write a shareable Markdown + HTML report");
-    steps.push("npx aibill --group-by project  see which project has the most observed activity");
+        ? { command: "npx aibill report --sample", description: "write a clearly labeled demo report right here" }
+        : { command: "npx aibill report", description: "write a shareable Markdown + HTML report" });
+    steps.push({
+        command: "npx aibill --group-by project",
+        description: "see which project has the most observed activity"
+    });
     steps.push("Need team reconciliation, allocation, budgets, and approvals? Workspace design partners: https://asktilden.com");
     if (mode === "demo") {
         // Static pointer only — sample output is built for recordings and
@@ -829,6 +786,86 @@ async function loadInstantReadData(args) {
             : false
     };
 }
+/**
+ * Build the one {@link BroadScanEvidence} bundle. Called by the receipt /
+ * `--full` readout AND by the machine-wide `report`; nothing else may
+ * re-derive these facts.
+ *
+ * Everything here was previously inline in the receipt path. The machine-wide
+ * report used to call {@link loadInstantReadData} directly and keep only
+ * `records`, which is exactly how its ACT and VERIFY sections lost the
+ * transcript index and degraded to internal-jargon "unknown" copy while the
+ * readout from the same directory showed real, ranked candidates.
+ */
+async function loadBroadScanEvidence(args, sinceDays) {
+    const instant = await loadInstantReadData(args);
+    const { records, mode, warnings, providerCoverage } = instant;
+    const summaryRecords = mode === "connected"
+        ? selectProviderFinancialHeadlineRecords(records)
+        : records;
+    // Connected receipts stay billed-primary but never ERASE the estimated
+    // axis: local transcript records ride along so subscription rows keep
+    // their ~ API-equivalent figures next to billed money (C-lane §1.4).
+    const analysisRecords = mode === "connected" && (instant.localFinancialRecords?.length ?? 0) > 0
+        ? [...summaryRecords, ...instant.localFinancialRecords]
+        : summaryRecords;
+    // Persona: --plan override wins; otherwise read the plans the coding agents
+    // themselves persisted locally (read-only, whitelisted fields, no network).
+    // An explicit sample run must be deterministic and safe to record/share:
+    // never mix the developer's real local plan into illustrative output.
+    const planOverride = args.plan ? planOverrideFromFlag(args.plan) : undefined;
+    const detectedPlans = args.sample
+        ? []
+        : planOverride
+            ? [planOverride]
+            : await detectLocalPlans({
+                // Env overrides keep tests (and unusual installs) isolated from $HOME.
+                claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
+                codexAuthPath: process.env.AI_SPEND_CODEX_AUTH
+            }).catch(() => []);
+    // Dead-context cost, globalized across the user's whole Claude Code setup
+    // (all projects' MCP + user-scope skills/agents/commands, vs. every
+    // transcript) so it's populated from ANY directory on the first run.
+    // Never throws into the readout.
+    let deadContext = args.sample
+        ? undefined
+        : 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: resolve(args.path),
+            includeAllProjectMcp: true,
+            sinceIso: sinceIsoForDays(sinceDays),
+            windowDays: sinceDays,
+            codexInvocationFiles: instant.codexInvocationFiles
+        }).catch(() => undefined);
+    // Sample dead-context is shown ONLY on the demo readout. A real readout
+    // (local logs / connected billing) never gets fabricated waste injected —
+    // a genuinely clean setup earns its congratulation line instead.
+    if (mode === "demo" && (!deadContext || !deadContext.hasData)) {
+        deadContext = sampleDeadContext();
+    }
+    return {
+        records,
+        mode,
+        warnings,
+        ...(providerCoverage ? { providerCoverage } : {}),
+        summaryRecords,
+        analysisRecords,
+        summary: analyzeSpend(summaryRecords),
+        // THE parity anchor: derived once, handed to every surface.
+        actionCandidates: generateCutList(analysisRecords),
+        detectedPlans,
+        ...(deadContext ? { deadContext } : {}),
+        ...(instant.actionEvidence ? { actionEvidence: instant.actionEvidence } : {}),
+        ...(instant.codexInvocationFiles ? { codexInvocationFiles: instant.codexInvocationFiles } : {}),
+        ...(instant.localFinancialRecords ? { localFinancialRecords: instant.localFinancialRecords } : {}),
+        financialCoverageComplete: instant.financialCoverageComplete === true
+    };
+}
 function localFinancialEvidenceComplete(result) {
     const scanCoverageComplete = result.sourceScans.every((scan) => (scan.directoryStatus !== "unreadable" &&
         scan.unreadableFiles === 0 &&
@@ -856,9 +893,23 @@ async function loadBoundedLocalActionEvidence(sinceIso) {
  * qualitative index converges, printing honest per-pass progress.
  */
 async function indexEvidenceCommand(args, runtime) {
-    const rootGuard = await guardExactProjectRoot("index", args.path);
-    if (rootGuard)
-        return rootGuard;
+    // 0.9.6, same fix and same reason as `report` (0.9.4): the report prints
+    // `npx aibill index` as its prescribed next step 13 times, and from a broad
+    // root — the home folder the machine-wide report is normally written in —
+    // the exact-project guard made that pointer exit 1. The report's own next
+    // step refused from the directory that wrote the report.
+    //
+    // The guard was never load-bearing here. `index` reads the env-scoped GLOBAL
+    // transcript directories (AI_SPEND_CLAUDE_LOGS_DIR / AI_SPEND_CODEX_LOGS_DIR,
+    // defaulting to the agents' own home-level locations) and writes the
+    // home-level private cache under ~/.aibill. `args.path` scopes nothing it
+    // reads and nothing it writes, so a broad root scans no more than a project
+    // root does. Only a bogus --path still gets the friendly guard.
+    if (!isBroadScanRoot(args.path)) {
+        const rootGuard = await guardExactProjectRoot("index", args.path);
+        if (rootGuard)
+            return rootGuard;
+    }
     const sinceDays = args.sinceDays ?? 30;
     if (!validSinceDays(sinceDays))
         return invalidSinceDaysResult();
@@ -903,7 +954,7 @@ async function indexEvidenceCommand(args, runtime) {
                     `${coverage.readCompletely}/${coverage.selectedFiles} selected files read completely · ` +
                         `${formatBytes(totalBytes)} streamed across ${passes} pass(es)`
                 ],
-                next: { reason: "your evidence is fully indexed — run the token test", command: improveRuntimeCommand }
+                next: { reason: "your evidence is fully indexed — run the token test", command: projectScopedPointer(improveRuntimeCommand, args.path) }
             }));
         }
         if (passBytes === 0 && stillConverging === 0) {
@@ -915,7 +966,7 @@ async function indexEvidenceCommand(args, runtime) {
                     `${coverage.readCompletely}/${coverage.selectedFiles} selected files read completely · ` +
                         `${coverage.skippedForBudget} file(s) remain outside the read budget`
                 ],
-                next: { reason: "run the token test on the evidence that is indexed", command: improveRuntimeCommand }
+                next: { reason: "run the token test on the evidence that is indexed", command: projectScopedPointer(improveRuntimeCommand, args.path) }
             }));
         }
     }
@@ -956,10 +1007,28 @@ function summarizeCliQualitativeCoverageByAgent(logs) {
         ];
     }));
 }
+/**
+ * The report summary's coverage row, in the user-facing voice (0.9.6). It read
+ * "suppressed · qualitative index partial" — a status nobody outside this
+ * codebase can act on, and a word ("suppressed") that was not even accurate
+ * for the ranked candidates, which are financial-derived and never withheld.
+ *
+ * Names the ACTUAL gap: unread transcripts and budget-skipped files are
+ * different problems with different fixes, and a bare "4 of 4 read" hid the
+ * second one entirely.
+ */
+function reportQualitativeRowValue(coverage) {
+    const read = coverage?.readCompletely ?? 0;
+    const selected = coverage?.selectedFiles ?? 0;
+    const skipped = coverage?.skippedForBudget ?? 0;
+    return `not drafted · ${read} of ${selected} session transcripts read` +
+        (skipped > 0 ? ` · ${skipped} ${skipped === 1 ? "file" : "files"} skipped by budget` : "");
+}
 function renderCliQualitativeCoverage(coverage) {
-    return `QUALITATIVE INDEX  ${coverage.status.toUpperCase()} · ` +
-        `${coverage.readCompletely}/${coverage.selectedFiles} selected files read completely · ` +
-        `${coverage.skippedForBudget} eligible files skipped by budget`;
+    return `SESSION TRANSCRIPTS  ${coverage.readCompletely} of ${coverage.selectedFiles} read completely` +
+        (coverage.skippedForBudget > 0
+            ? ` · ${coverage.skippedForBudget} ${coverage.skippedForBudget === 1 ? "file was" : "files were"} skipped by budget`
+            : "");
 }
 /**
  * `aibill signup <email> [--ref <token>]` — the explicit, deliberate path to
@@ -1177,7 +1246,19 @@ function noEvidenceResult(surface, warnings, sinceDays, telemetryDisclosure) {
                 ...warnings.map((warning) => `! ${warning}`),
                 "",
                 "Next",
-                "  npx aibill doctor --sources       see the exact evidence gap and setup paths",
+                // 0.9.6: this screen used to offer exactly two next steps — a
+                // diagnostic and an email signup — to a visitor who had just been
+                // told there is nothing to show. The only occurrence of the word
+                // "sample" on it was "No sample data was substituted." `--sample`
+                // works, needs no evidence and no email, and is the one thing that
+                // shows a first-time visitor what the tool actually produces, so it
+                // goes FIRST.
+                "  npx aibill --sample               see a full worked example on bundled demo data",
+                // Honest label (0.9.6): this prints a per-source coverage matrix —
+                // which locations were checked and what each returned. It does not
+                // print install or setup instructions, and promising "setup paths"
+                // sent people looking for something that is not there.
+                "  npx aibill doctor --sources       see which source locations were checked, and what each returned",
                 `  ${signupCopy.receiptPointer}`
             ].join("\n")
             : "",
@@ -1840,7 +1921,7 @@ async function statuslineCommand(args, runtime) {
     if (action === "refresh")
         return refreshStatuslineCommand(args, runtime);
     if (action === "expand")
-        return expandStatuslineCommand(runtime);
+        return expandStatuslineCommand(args, runtime);
     return {
         exitCode: 1,
         stdout: "",
@@ -2132,6 +2213,19 @@ async function refreshStatuslineCommand(args, runtime) {
         }
         detectedPlanOverride = [override];
     }
+    // `statusline refresh` scans an approved workspace root, so a broad root is
+    // a genuine refusal — but it must SOUND like one (0.9.6). It used to let
+    // resolveSafeScanRoot throw, which the crash wrapper rendered as "aibill hit
+    // an unexpected error: Refusing to scan …" plus "run diagnostics before
+    // retrying" — the tool reporting its own deliberate safety check as a bug.
+    // `statusline refresh` scans an approved workspace root, so a broad root is
+    // a genuine refusal — but it must SOUND like one (0.9.6). It used to let
+    // resolveSafeScanRoot throw, which the crash wrapper rendered as "aibill hit
+    // an unexpected error: Refusing to scan …" plus "run diagnostics before
+    // retrying" — the tool reporting its own deliberate safety check as a bug.
+    const refreshGuard = await guardExactProjectRoot("statusline refresh", args.path);
+    if (refreshGuard)
+        return refreshGuard;
     const rootPath = await resolveSafeScanRoot(args.path);
     const cacheDirectory = process.env.AIBILL_CACHE_DIR;
     await preflightInitCache(cacheDirectory);
@@ -2199,7 +2293,7 @@ async function refreshStatuslineCommand(args, runtime) {
  * snapshot; `runways[]` carries both limits), never bypassing the contract.
  * Printed command output, not a hook line.
  */
-async function expandStatuslineCommand(runtime) {
+async function expandStatuslineCommand(args, runtime) {
     const cache = await readStatuslineCache({
         cacheDirectory: process.env.AIBILL_CACHE_DIR,
         homeDirectory: runtime.homeDirectory
@@ -2209,8 +2303,8 @@ async function expandStatuslineCommand(runtime) {
             exitCode: 1,
             stdout: "",
             stderr: cache.status === "missing"
-                ? "aibill statusline expand needs a refreshed private cache: run `npx aibill statusline refresh` first."
-                : "aibill statusline expand could not read the private cache safely; run `npx aibill statusline refresh`."
+                ? `aibill statusline expand needs a refreshed private cache: run \`${projectScopedPointer(actionRuntimeCommand("statusline refresh"), args.path)}\` first.`
+                : `aibill statusline expand could not read the private cache safely; run \`${projectScopedPointer(actionRuntimeCommand("statusline refresh"), args.path)}\`.`
         };
     }
     const now = runtime.statuslineNow ?? new Date();
@@ -2219,7 +2313,7 @@ async function expandStatuslineCommand(runtime) {
         return ok([
             "aibill subscriptions · 30d window",
             "  no detected subscription evidence in the private cache",
-            "  run `npx aibill statusline refresh` after using Claude Code or Codex"
+            `  run \`${projectScopedPointer(actionRuntimeCommand("statusline refresh"), args.path)}\` after using Claude Code or Codex`
         ].join("\n"));
     }
     const card = statuslineSnapshotToResultCard(snapshot, now);
@@ -3907,7 +4001,7 @@ async function reportCommand(args, runtime = {}) {
                     ]
                     : qualitativeActionsSuppressed
                         ? [
-                            { label: "Action artifacts", value: `suppressed · qualitative index ${reportInput.qualitativeCoverage?.status ?? "unknown"}` },
+                            { label: "Action artifacts", value: reportQualitativeRowValue(reportInput.qualitativeCoverage) },
                             { label: "Coverage artifact", value: artifactPaths.codingPrompt },
                             { label: "Coverage action plan", value: artifactPaths.actionPlan },
                             { label: "Coverage policy/config", value: artifactPaths.policyConfigDraft },
@@ -3942,21 +4036,34 @@ async function reportCommand(args, runtime = {}) {
         const nextSteps = [
             // Summary-line truth: only a fired opener may claim it opened; every
             // suppression path keeps the plain copy-pasteable pointer.
+            // 0.9.6: the pointer must survive a NAIVE PARTIAL READ. The founder saw
+            // `› open <the full absolute path>` with its description on the
+            // next line, read "open" as a label rather than the command, typed bare
+            // `open`, and got macOS's usage dump — "i don't know what im looking
+            // at." shellPathPointer names an artifact in the current directory
+            // relatively (one short unit) and quotes anything absolute so the
+            // command and its argument read — and paste — as one thing.
             openedInBrowser
                 ? { command: `opened ${basename(htmlPath)} in your browser · next time: --no-open to skip` }
-                : { command: `open ${htmlPath}`, description: "view the full report in your browser" },
-            { command: `less ${markdownPath}`, description: "read it in the terminal" },
+                : {
+                    command: shellPathPointer(platformOpenCommand(), htmlPath, process.cwd()),
+                    description: `view in your browser — or double-click ${basename(htmlPath)} in your file manager`
+                },
+            {
+                command: shellPathPointer("less", markdownPath, process.cwd()),
+                description: "read it in the terminal"
+            },
             machineWide
                 // apply/improve need one exact project folder — a machine-wide
                 // report must never point at a command that then refuses (the exact
                 // trap this mode removes).
                 ? reportInput.dataMode === "sample"
-                    ? { command: `cd <project> && ${actionRuntimeCommand("apply --sample")}`, description: "print the non-executable demo boundary from one exact project folder" }
-                    : { command: `cd <project> && ${actionRuntimeCommand(`apply --since-days ${sinceDays}`)}`, description: "per-project action plan from one exact project folder" }
+                    ? { command: `cd /path/to/project && ${actionRuntimeCommand("apply --sample")}`, description: "print the non-executable demo boundary from one exact project folder" }
+                    : { command: `cd /path/to/project && ${actionRuntimeCommand(`apply --since-days ${sinceDays}`)}`, description: "per-project action plan from one exact project folder" }
                 : reportableExperiment
                     ? { command: improveRuntimeCommand, description: `review canonical token test ${reportableExperiment.id}` }
                     : qualitativeActionsSuppressed
-                        ? { command: actionRuntimeCommand(`context --json --since-days ${sinceDays}`), description: "complete bounded qualitative evidence before any action" }
+                        ? { command: actionRuntimeCommand(`context --json --since-days ${sinceDays}`), description: "inspect the transcript evidence read so far" }
                         : reportInput.dataMode === "sample"
                             ? { command: actionRuntimeCommand("apply --sample"), description: "print the non-executable demo boundary" }
                             : { command: actionRuntimeCommand(`apply --since-days ${sinceDays}`), description: "print the paste-ready coding-agent prompt from this exact evidence window" }
@@ -3992,7 +4099,7 @@ async function resolveReceiptPath(rootPath, out) {
         return join(resolved, "ai-spend-receipt.svg");
     return extname(resolved) ? resolved : `${resolved}.svg`;
 }
-async function reportCardCommand(args) {
+async function reportCardCommand(args, runtime = {}) {
     // 0.9.4: a broad root (home, /) runs MACHINE-WIDE — identical read-only
     // scanning to the bare receipt (loadInstantReadData below), SVG written to
     // the current directory. The card renders machine-wide content anyway, so
@@ -4029,12 +4136,39 @@ async function reportCardCommand(args) {
         const summary = analyzeSpend(headlineRecords);
         const outPath = await resolveReceiptPath(rootPath, args.out);
         await mkdir(dirname(outPath), { recursive: true });
-        await writeSafeStateText(dirname(outPath), basename(outPath), generateReportCardSvg({
+        const svg = generateReportCardSvg({
             summary,
             records: headlineRecords,
             mode,
             ...(providerCoverage ? { providerCoverage } : {})
-        }));
+        });
+        await writeSafeStateText(dirname(outPath), basename(outPath), svg);
+        const caption = generateReportCardCaption({
+            summary,
+            records: headlineRecords,
+            mode,
+            ...(providerCoverage ? { providerCoverage } : {})
+        });
+        // 0.9.6: the receipt now SHOWS itself. 0.9.5 wrote the SVG and stopped,
+        // leaving the user to go find and open it by hand ("not automatically
+        // showing on a html or opening the file: making it inefficient").
+        //
+        // We auto-open a companion .html rather than the .svg itself: platform
+        // openers hand a .svg to whatever claims that extension, which on a
+        // developer machine is frequently an editor, so "show me my receipt"
+        // could open a wall of XML. An .html is claimed by a browser everywhere.
+        // The .svg remains the canonical shareable artifact; the companion just
+        // renders it next to the caption, embedding both verbatim so it inherits
+        // the card's redaction guarantees exactly.
+        const companionPath = `${outPath.replace(/\.svg$/iu, "")}.html`;
+        await writeSafeStateText(dirname(companionPath), basename(companionPath), generateReceiptCompanionHtml({ svg, caption }));
+        // Same decision function, same suppression matrix, same metacharacter
+        // refusal, same detached launch as `report` — one opener, two commands.
+        const openDecision = (runtime.reportOpenDecide ?? decideReportAutoOpen)({
+            htmlPath: companionPath,
+            noOpenFlag: args.noOpen === true
+        });
+        const openedInBrowser = (runtime.reportOpenLaunch ?? openReportInBrowser)(openDecision);
         const dataRow = mode === "demo"
             ? args.sample
                 ? "DEMO sample data — explicit illustrative mode; no local transcripts or persisted spend state were read"
@@ -4050,18 +4184,29 @@ async function reportCardCommand(args) {
             note: "a shareable, redacted spend card (no client/project/user names)",
             rows: [
                 { label: "Receipt", value: outPath },
+                { label: "Preview", value: companionPath },
                 { label: "Data", value: dataRow },
                 { label: "Privacy", value: "rendered locally; only totals, generic candidate categories, and evidence labels are included" }
             ],
             sections: [{
                     heading: "Caption to share",
-                    body: [generateReportCardCaption({
-                            summary,
-                            records: headlineRecords,
-                            mode,
-                            ...(providerCoverage ? { providerCoverage } : {})
-                        })]
+                    body: [caption]
                 }],
+            nextSteps: [
+                // Summary-line truth: only a fired opener may claim it opened; every
+                // suppression path keeps the plain copy-pasteable pointer.
+                openedInBrowser
+                    ? { command: `opened ${basename(companionPath)} in your browser · next time: --no-open to skip` }
+                    : {
+                        command: shellPathPointer(platformOpenCommand(), companionPath, process.cwd()),
+                        description: `view the receipt — or double-click ${basename(companionPath)} in your file manager`
+                    },
+                // NOT a command, so it must not LOOK like one: `post ai-receipt.svg`
+                // sitting under "Next" beside two real commands is exactly the trap
+                // that made the founder type a bare `open`. Description-less lines
+                // render verbatim, so this one states a fact instead.
+                { command: `${basename(outPath)} is the file to share — post that one` }
+            ],
             color: args.noColor ? false : undefined,
             width: terminalOutputWidth()
         }));
@@ -4093,6 +4238,19 @@ async function reportCardCommand(args) {
 function isBroadScanRoot(requestedPath) {
     return broadScanRootKind(requestedPath) !== undefined;
 }
+/**
+ * A project-scoped command, printed so it WORKS from where it was printed.
+ *
+ * The founder's most-repeated complaint class (0.9.4 report, 0.9.6 index, and
+ * these): a surface running machine-wide prints a bare project-scoped command,
+ * the user copies it, and it friendly-refuses in the very directory that
+ * printed it. Commands that genuinely need one project carry their own `cd`
+ * from a broad root — a PATH placeholder, never `<project>`, which the shell
+ * would read as redirection.
+ */
+function projectScopedPointer(command, requestedPath) {
+    return isBroadScanRoot(requestedPath) ? `cd /path/to/project && ${command}` : command;
+}
 /** Classifies WHICH broad-root category a machine-wide path falls in. */
 function broadScanRootKind(requestedPath) {
     const rootPath = resolve(requestedPath);
@@ -5912,7 +6070,7 @@ async function tokenVerificationCommand(args) {
         }
         const observation = await loadTokenVerificationObservation(rootPath, experiment);
         if (!observation.qualitativeCoverageComplete) {
-            return tokenVerificationUsageError("the bounded qualitative index is incomplete for this experiment's agent; no post-change sessions or reduction percentage were accepted");
+            return tokenVerificationUsageError("this experiment's agent still has unread session transcripts; no post-change sessions or reduction percentage were accepted. Run `npx aibill index` to finish reading them, then verify again");
         }
         const unlabelled = refreshTokenReductionExperimentV0(experiment, {
             sessionVitals: observation.sessionVitals,
@@ -6066,36 +6224,50 @@ function applyEvidenceAcquisitionLines(input) {
     return lines;
 }
 /**
- * Machine-wide report input (0.9.4): the bare receipt's own data path —
- * loadInstantReadData over the agent transcript dirs (read-only) — rendered
- * through the report package. No project state is read or created; plan
- * detection is home-scoped metadata, exactly as the receipt reads it.
+ * Machine-wide report input — built from {@link loadBroadScanEvidence}, the
+ * SAME call the `--full` readout makes from the same directory (0.9.6).
+ *
+ * 0.9.4 shipped this as a parallel thin builder over `loadInstantReadData`,
+ * keeping only the financial records. Everything that gates an action claim —
+ * the bounded transcript index above all — was dropped, so the report package
+ * fell back to `qualitativeCoverage: "unknown"` and every ACT/VERIFY branch
+ * degraded, while `--full` from the same home showed real ranked candidates.
+ * The evidence is not project-scoped and never was; only the builder was
+ * withholding it.
+ *
+ * No project state is read or created. Everything below comes from the shared
+ * bundle; nothing is re-derived here.
  */
 async function buildMachineWideReportInput(args, sinceDays) {
-    const { records, mode, providerCoverage, warnings } = await loadInstantReadData(args);
-    if (records.length === 0) {
+    const evidence = await loadBroadScanEvidence(args, sinceDays);
+    if (evidence.records.length === 0) {
         // Same honest empty-state voice the receipt/report-card use — an empty
         // report file would just look broken.
-        return { kind: "no_evidence", warnings };
+        return { kind: "no_evidence", warnings: evidence.warnings };
     }
-    const detectedPlans = await detectLocalPlans({
-        claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
-        codexAuthPath: process.env.AI_SPEND_CODEX_AUTH
-    }).catch(() => []);
-    const headlineRecords = mode === "connected"
-        ? selectProviderFinancialHeadlineRecords(records)
-        : records;
+    const { records, mode, actionEvidence } = evidence;
     return {
         kind: "input",
         input: {
             generatedAt: new Date().toISOString(),
-            summary: analyzeSpend(headlineRecords),
+            summary: evidence.summary,
             allRecords: records,
             dataMode: mode === "connected" ? "connected_provider" : "local_logs",
             evidenceWindowDays: sinceDays,
-            detectedPlans,
+            detectedPlans: evidence.detectedPlans,
+            // The ranked set the readout prints, verbatim — not a second derivation.
+            actionCandidates: evidence.actionCandidates,
+            analysisScope: "machine-wide",
+            // The bounded transcript index the 0.9.4 builder dropped. This is what
+            // un-degrades ACT, VERIFY, plan context, and the configuration section.
+            qualitativeCoverage: summarizeCliQualitativeCoverage(actionEvidence),
+            qualitativeCoverageByAgent: summarizeCliQualitativeCoverageByAgent(actionEvidence),
+            ...(evidence.deadContext ? { deadContext: evidence.deadContext } : {}),
             ...(mode === "connected" ? { providerRecords: records } : {}),
-            ...(providerCoverage ? { providerCoverage } : {})
+            ...(mode === "connected" && (evidence.localFinancialRecords?.length ?? 0) > 0
+                ? { localFinancialRecords: evidence.localFinancialRecords }
+                : {}),
+            ...(evidence.providerCoverage ? { providerCoverage: evidence.providerCoverage } : {})
         }
     };
 }
@@ -7149,6 +7321,10 @@ function helpText(telemetryDisclosure) {
         "  report [--sample] [--out <name>] [--since-days N] Generate local Markdown and HTML reports and open the HTML in your browser",
         "    [--no-open]           Skip the automatic browser open (also AI_SPEND_NO_OPEN=1; auto-open is TTY-only and never fires in CI or SSH sessions)",
         "  report-card [--out f.svg] Write your AI Receipt — a redacted, shareable SVG + caption",
+        // C3: report-card writes TWO files. `--out index.svg` silently replaced an
+        // existing index.html next to it; the second artifact is now disclosed
+        // where the user chooses the name.
+        "    [--out f.svg]         Also writes the companion viewer f.html alongside it, overwriting any existing file of that name",
         "  glance [--project <name>] [--plan <id>] [--since-days N] Emit the local, machine-readable Glance snapshot JSON",
         "  context [--project <name>] [--since-days N] Show hook-aware Context Health in the terminal",
         "    [--json]              Emit the same canonical Context Health object used by MCP and Glance",

package/dist/reportOpener.d.ts

@@ -7,6 +7,20 @@ export type ReportOpenDecision = {
     open: false;
     reason: "no-open-flag" | "env-switch" | "not-a-tty" | "ci" | "ssh" | "unsafe-path" | "no-opener";
 };
+/**
+ * The command a USER would type to open a file on this platform (0.9.6).
+ *
+ * The printed "open this report" pointers hardcoded macOS `open`, so every
+ * Linux and Windows user was told to run a command they do not have — while
+ * {@link decideReportAutoOpen} right below already branched per platform to
+ * decide what to spawn. One platform decision, used by both.
+ *
+ * This is the TYPED form, which is not always the spawned form: auto-open uses
+ * `rundll32 url.dll,FileProtocolHandler` on Windows precisely to keep cmd.exe
+ * out of the chain, but nobody types that — `start` is the builtin a Windows
+ * user actually uses, and by then they are typing into a shell anyway.
+ */
+export declare function platformOpenCommand(platform?: NodeJS.Platform): string;
 export declare function decideReportAutoOpen(input: {
     htmlPath: string;
     noOpenFlag: boolean;

package/dist/reportOpener.js

@@ -50,6 +50,30 @@ import { delimiter, join } from "node:path";
  * to a platform opener; auto-open falls back to the plain pointer instead.
  */
 const UNSAFE_PATH_METACHARACTERS = /[&^%()<>|"]/u;
+/**
+ * The command a USER would type to open a file on this platform (0.9.6).
+ *
+ * The printed "open this report" pointers hardcoded macOS `open`, so every
+ * Linux and Windows user was told to run a command they do not have — while
+ * {@link decideReportAutoOpen} right below already branched per platform to
+ * decide what to spawn. One platform decision, used by both.
+ *
+ * This is the TYPED form, which is not always the spawned form: auto-open uses
+ * `rundll32 url.dll,FileProtocolHandler` on Windows precisely to keep cmd.exe
+ * out of the chain, but nobody types that — `start` is the builtin a Windows
+ * user actually uses, and by then they are typing into a shell anyway.
+ */
+export function platformOpenCommand(platform = process.platform) {
+    if (platform === "darwin")
+        return "open";
+    // `start ""`, not bare `start`. cmd's `start` reads a QUOTED first argument
+    // as the new window's title, so `start "C:\...\ai-receipt.html"` opens an
+    // empty console window titled with the path and never opens the file. The
+    // empty title is the canonical fix, and every path we print is quoted.
+    if (platform === "win32")
+        return 'start ""';
+    return "xdg-open";
+}
 export function decideReportAutoOpen(input) {
     const env = input.env ?? process.env;
     const platform = input.platform ?? process.platform;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spend-agent",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "funding": "https://asktilden.com",
   "description": "Local-first financial accountability CLI: Claude Code/Codex attribution, provenance, and next actions, plus experimental Gemini CLI cost evidence.",
   "type": "module",
@@ -55,8 +55,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@agent-finops/core": "0.9.5",
-    "@agent-finops/report": "0.9.5",
+    "@agent-finops/core": "0.9.6",
+    "@agent-finops/report": "0.9.6",
     "yocto-spinner": "^1.2.0"
   }
 }