ai-spend-agent 0.9.4 → 0.9.6

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { type GuidedPromptSource } from "./guidedPrompt.js";
 import { type SignupDnsResolver } from "./signup.js";
+import { decideReportAutoOpen, openReportInBrowser } from "./reportOpener.js";
 export type CliResult = {
     exitCode: number;
     stdout: string;
@@ -44,6 +45,15 @@ export type CliRuntimeOptions = {
      * Embedded/MCP callers never set it (and never emit telemetry).
      */
     telemetryDisclosure?: boolean;
+    /**
+     * Test seams for `report`'s HTML auto-open (0.9.5): decide computes the
+     * truthful open/suppress verdict (platform, TTY, CI/SSH, --no-open,
+     * AI_SPEND_NO_OPEN); open fires the detached platform opener. Production
+     * uses the real implementations; tests inject stubs to pin the opener
+     * argv per platform, every suppression path, and summary-line truth.
+     */
+    reportOpenDecide?: typeof decideReportAutoOpen;
+    reportOpenLaunch?: typeof openReportInBrowser;
 };
 export declare function runCli(argv?: string[], runtime?: CliRuntimeOptions): Promise<CliResult>;
 /**

package/dist/index.js

@@ -3,13 +3,13 @@ import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { lstat, mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, extname, join, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { askGuidedQuestion, classifyGuidedAnswer, createInteractivePromptSource, renderForYourAgent } from "./guidedPrompt.js";
 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,7 +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 { generateActionPlanMarkdown, generateApplyArtifactMarkdown, 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
@@ -101,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);
@@ -165,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
@@ -223,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,
@@ -261,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,
@@ -272,6 +219,11 @@ async function quickstartCommand(args, runtime = {}) {
         nextSteps,
         deadContext,
         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 /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.
         windowDays: sinceDays,
         width: outputWidth,
@@ -611,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
@@ -823,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 &&
@@ -850,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();
@@ -897,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) {
@@ -909,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) }
             }));
         }
     }
@@ -950,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
@@ -1171,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")
             : "",
@@ -1834,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: "",
@@ -2126,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);
@@ -2193,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
@@ -2203,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();
@@ -2213,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);
@@ -3769,9 +3869,16 @@ async function reportCommand(args, runtime = {}) {
     // exact-project requirement was incoherent here: the receipt's own Next
     // pointer led from home straight into a refusal. Only a bogus --path
     // still gets the friendly guard; project folders behave exactly as
-    // before.
+    // before. 0.9.5: broad roots that cannot HOLD the artifacts (/, /etc,
+    // /Users, …) get the friendly guard voice up front instead of dying at
+    // write time with a wrapped raw error.
     const machineWide = isBroadScanRoot(args.path);
-    if (!machineWide) {
+    if (machineWide) {
+        const broadGuard = guardUnwritableBroadRoot("report", args);
+        if (broadGuard)
+            return broadGuard;
+    }
+    else {
         const rootGuard = await guardExactProjectRoot("report", args.path);
         if (rootGuard)
             return rootGuard;
@@ -3864,67 +3971,111 @@ async function reportCommand(args, runtime = {}) {
         const artifactPaths = reportableExperiment || machineWide
             ? undefined
             : await writeApplyArtifacts(stateDir, reportInput);
-        return ok([
-            "aibill report",
+        // 0.9.5 "agent feel": the HTML report opens itself in the browser via
+        // the platform opener — decided truthfully BEFORE the summary renders,
+        // suppressed for non-TTY/CI/SSH/--no-open/AI_SPEND_NO_OPEN, and fired
+        // detached so a missing or slow opener can never crash, hang, or delay
+        // exit (the telemetry detached-child pattern).
+        const openDecision = (runtime.reportOpenDecide ?? decideReportAutoOpen)({
+            htmlPath,
+            noOpenFlag: args.noOpen === true
+        });
+        const openedInBrowser = (runtime.reportOpenLaunch ?? openReportInBrowser)(openDecision);
+        // 0.9.5 founder polish ("really hard to read… I wonder if we can have
+        // the text aligned"): the same facts, rendered in the receipt's visual
+        // language — header, one shared label column, dot separators, and a Next
+        // block whose commands pad to one description column. Display-only.
+        const rows = [
             machineWide
-                ? `scope: machine-wide · all supported local agent evidence on this machine (last ${sinceDays} days) · artifacts in ${rootPath}`
-                : `path: ${rootPath}`,
-            `markdown: ${markdownPath}`,
-            `html: ${htmlPath}`,
+                ? { label: "Scope", value: `machine-wide · all supported local agent evidence on this machine (last ${sinceDays} days) · artifacts in ${rootPath}` }
+                : { label: "Path", value: rootPath },
+            { label: "Markdown", value: markdownPath },
+            { label: "HTML", value: htmlPath },
             ...(machineWide
                 ? []
                 : reportableExperiment
                     ? [
-                        `action artifacts: preserved · canonical token test ${reportableExperiment.id} (${reportableExperiment.lifecycle})`,
-                        `token result: status=${reportableExperiment.evaluation.status}; reductionPercent=${reportExperimentProjection.reductionPercent ?? "unavailable"}; metricEvidence=${reportExperimentProjection.evidenceLabel}; quality=${reportExperimentProjection.qualityLabel}; qualityEvidence=${reportExperimentProjection.qualityEvidence}; matchingEvidence=${reportableExperiment.evaluation.matchingEvidence}`,
-                        `token test: ${improveRuntimeCommand}`
+                        { label: "Action artifacts", value: `preserved · canonical token test ${reportableExperiment.id} (${reportableExperiment.lifecycle})` },
+                        { label: "Token result", value: `status=${reportableExperiment.evaluation.status}; reductionPercent=${reportExperimentProjection.reductionPercent ?? "unavailable"}; metricEvidence=${reportExperimentProjection.evidenceLabel}; quality=${reportExperimentProjection.qualityLabel}; qualityEvidence=${reportExperimentProjection.qualityEvidence}; matchingEvidence=${reportableExperiment.evaluation.matchingEvidence}` },
+                        { label: "Token test", value: improveRuntimeCommand }
                     ]
                     : qualitativeActionsSuppressed
                         ? [
-                            `action artifacts: suppressed · qualitative index ${reportInput.qualitativeCoverage?.status ?? "unknown"}`,
-                            `coverage artifact: ${artifactPaths.codingPrompt}`,
-                            `coverage action plan: ${artifactPaths.actionPlan}`,
-                            `coverage policy/config: ${artifactPaths.policyConfigDraft}`,
-                            `coverage verification: ${artifactPaths.verificationPlan}`,
-                            `coverage package: ${artifactPaths.demoPackage}`
+                            { 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 },
+                            { label: "Coverage verification", value: artifactPaths.verificationPlan },
+                            { label: "Coverage package", value: artifactPaths.demoPackage }
                         ]
                         : artifactPaths
                             ? [
-                                `apply artifact: ${artifactPaths.codingPrompt}`,
-                                `action plan: ${artifactPaths.actionPlan}`,
-                                `policy/config draft: ${artifactPaths.policyConfigDraft}`,
-                                `verification plan: ${artifactPaths.verificationPlan}`,
-                                `demo package: ${artifactPaths.demoPackage}`
+                                { label: "Apply artifact", value: artifactPaths.codingPrompt },
+                                { label: "Action plan", value: artifactPaths.actionPlan },
+                                { label: "Policy/config draft", value: artifactPaths.policyConfigDraft },
+                                { label: "Verification plan", value: artifactPaths.verificationPlan },
+                                { label: "Demo package", value: artifactPaths.demoPackage }
                             ]
                             : []),
-            reportInput.dataMode === "sample"
-                ? `DEMO SAMPLE · illustrative cost/value evidence total: ${formatOptionalUsd(reportInput.summary.totalUsd)} · not user data`
-                : reportInput.dataMode === "connected_provider" &&
-                    !(reportInput.allRecords ?? reportInput.providerRecords ?? []).some((record) => typeof record.amountUsd === "number")
-                    ? "cost/value evidence total: Unavailable · no priced financial evidence; missing/null is not zero"
-                    : `cost/value evidence total: ${formatOptionalUsd(reportInput.summary.totalUsd)}`,
-            runtime.telemetryDisclosure === true
-                ? `privacy: report rendered locally · ${telemetryDisclosureLine}; only explicit sync-provider contacts the selected provider`
-                : "privacy: report rendered locally with no aibill telemetry; only explicit sync-provider contacts the selected provider",
-            "",
-            "next:",
-            `  open ${htmlPath}       view the full report in your browser`,
-            `  less ${markdownPath}       read it in the terminal`,
+            {
+                label: "Total",
+                value: reportInput.dataMode === "sample"
+                    ? `${formatOptionalUsd(reportInput.summary.totalUsd)} · DEMO SAMPLE · illustrative cost/value evidence · not user data`
+                    : reportInput.dataMode === "connected_provider" &&
+                        !(reportInput.allRecords ?? reportInput.providerRecords ?? []).some((record) => typeof record.amountUsd === "number")
+                        ? "Unavailable · cost/value evidence · no priced financial evidence; missing/null is not zero"
+                        : `${formatOptionalUsd(reportInput.summary.totalUsd)} · cost/value evidence`
+            },
+            {
+                label: "Privacy",
+                value: runtime.telemetryDisclosure === true
+                    ? `report rendered locally · ${telemetryDisclosureLine}; only explicit sync-provider contacts the selected provider`
+                    : "report rendered locally with no aibill telemetry; only explicit sync-provider contacts the selected provider"
+            }
+        ];
+        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: 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"
-                    ? `  cd <project> && ${actionRuntimeCommand("apply --sample")}  print the non-executable demo boundary from one exact project folder`
-                    : `  cd <project> && ${actionRuntimeCommand(`apply --since-days ${sinceDays}`)}  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
-                    ? `  ${improveRuntimeCommand}  review canonical token test ${reportableExperiment.id}`
+                    ? { command: improveRuntimeCommand, description: `review canonical token test ${reportableExperiment.id}` }
                     : qualitativeActionsSuppressed
-                        ? `  ${actionRuntimeCommand(`context --json --since-days ${sinceDays}`)}  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"
-                            ? `  ${actionRuntimeCommand("apply --sample")}  print the non-executable demo boundary`
-                            : `  ${actionRuntimeCommand(`apply --since-days ${sinceDays}`)}  print the paste-ready coding-agent prompt from this exact evidence window`
-        ].join("\n"));
+                            ? { 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" }
+        ];
+        return ok(generateCommandSummary({
+            title: "aibill report",
+            note: "a shareable Markdown + HTML report, written locally",
+            rows,
+            nextSteps,
+            color: args.noColor ? false : undefined,
+            width: terminalOutputWidth()
+        }));
     }
     catch (error) {
         return {
@@ -3948,14 +4099,21 @@ 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
     // an exact-project requirement was incoherent here; only a bogus --path
-    // still gets the friendly guard.
+    // still gets the friendly guard. 0.9.5: broad roots that cannot HOLD the
+    // receipt (/, /etc, /Users, …) get the friendly guard voice up front
+    // instead of dying at write time with a wrapped raw error.
     const machineWide = isBroadScanRoot(args.path);
-    if (!args.sample && !machineWide) {
+    if (machineWide) {
+        const broadGuard = guardUnwritableBroadRoot("report-card", args);
+        if (broadGuard)
+            return broadGuard;
+    }
+    else if (!args.sample) {
         const rootGuard = await guardExactProjectRoot("report-card", args.path);
         if (rootGuard)
             return rootGuard;
@@ -3978,34 +4136,80 @@ 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 } : {})
-        }));
-        const dataLine = mode === "demo"
+        });
+        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
-                ? "data: DEMO sample data — explicit illustrative mode; no local transcripts or persisted spend state were read."
-                : "data: DEMO sample data — no supported local Claude Code/Codex evidence was found; use --sample to reproduce this demo explicitly."
+                ? "DEMO sample data — explicit illustrative mode; no local transcripts or persisted spend state were read"
+                : "DEMO sample data — no supported local Claude Code/Codex evidence was found; use --sample to reproduce this demo explicitly"
             : mode === "local-logs"
-                ? "data: local Claude Code/Codex logs priced at API-equivalent rates."
-                : "data: connected local spend state with provider-reported cost kept separate from API-equivalent estimates.";
-        return ok([
-            "Your AI Receipt — a shareable, redacted spend card (no client/project/user names).",
-            `receipt: ${outPath}`,
-            dataLine,
-            "",
-            "Caption to share:",
-            generateReportCardCaption({
-                summary,
-                records: headlineRecords,
-                mode,
-                ...(providerCoverage ? { providerCoverage } : {})
-            }),
-            "",
-            "privacy: rendered locally; only totals, generic candidate categories, and evidence labels are included."
-        ].join("\n"));
+                ? "local Claude Code/Codex logs priced at API-equivalent rates"
+                : "connected local spend state with provider-reported cost kept separate from API-equivalent estimates";
+        // 0.9.5 founder polish: same facts, receipt-language layout — header,
+        // one label column, and the caption set off as its own block.
+        return ok(generateCommandSummary({
+            title: "aibill report-card",
+            badge: "Your AI Receipt",
+            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: [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()
+        }));
     }
     catch (error) {
         return {
@@ -4032,12 +4236,76 @@ async function reportCardCommand(args) {
  * (improve, apply, verify, watch, connect, reset, …) keep the guard.
  */
 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);
     const home = homedir();
     const guardHome = home && home.trim().length > 0
         ? home
         : join(rootPath, "aibill-impossible-home-sentinel");
-    return unsafeScanRootReason(rootPath, guardHome) !== undefined;
+    const reason = unsafeScanRootReason(rootPath, guardHome);
+    if (reason === undefined)
+        return undefined;
+    if (reason.includes("filesystem root"))
+        return "filesystem-root";
+    if (reason.includes("home directory is too broad"))
+        return "home";
+    if (reason.includes("contains your home directory"))
+        return "contains-home";
+    return "system-directory";
+}
+/**
+ * 0.9.5: machine-wide report/report-card write their artifacts INTO the
+ * requested root. That works from the home directory, but /, /etc, or a
+ * folder that contains home cannot hold them — the run used to die at write
+ * time with a wrapped raw error ("Couldn't build a report: EROFS…",
+ * "Refusing to use /etc…"). Those roots get the friendly guard voice BEFORE
+ * anything is scanned or written. Returns undefined when the root is home
+ * itself (machine-wide proceeds) or when an explicit absolute --out points
+ * the artifacts somewhere else entirely.
+ */
+function guardUnwritableBroadRoot(commandName, args) {
+    const kind = broadScanRootKind(args.path);
+    if (kind === undefined || kind === "home")
+        return undefined;
+    // An absolute --out lands outside the broad root; only rootPath-relative
+    // artifacts make this location a write problem.
+    if (args.out !== undefined && isAbsolute(args.out))
+        return undefined;
+    const artifactNoun = commandName === "report" ? "its report files" : "the receipt";
+    const explanation = kind === "filesystem-root"
+        ? `You pointed it at the filesystem root, which can't hold ${artifactNoun}.`
+        : kind === "contains-home"
+            ? `You pointed it at a folder that contains your home directory, which can't hold ${artifactNoun}.`
+            : `You pointed it at a system directory, which can't hold ${artifactNoun}.`;
+    return {
+        exitCode: 1,
+        stdout: "",
+        stderr: [
+            `aibill ${commandName} writes ${artifactNoun} into the folder it points at.`,
+            explanation,
+            "",
+            "Run it from your home directory for a machine-wide view, or from one exact project folder",
+            `  e.g. cd ~ && ${actionRuntimeCommand(commandName)}`,
+            "",
+            "Nothing was read, created, or changed."
+        ].join("\n")
+    };
 }
 async function guardExactProjectRoot(commandName, requestedPath) {
     const rootPath = resolve(requestedPath);
@@ -5802,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,
@@ -5956,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 } : {})
         }
     };
 }
@@ -6418,6 +6700,10 @@ function parseArgs(argv) {
             parsed.noColor = true;
             continue;
         }
+        if (arg === "--no-open") {
+            parsed.noOpen = true;
+            continue;
+        }
         if (arg === "--json") {
             parsed.json = true;
             continue;
@@ -7032,8 +7318,13 @@ function helpText(telemetryDisclosure) {
         "  quickstart [--sample] [--since-days N] Plain-English local readout (default 30 days)",
         "    [--full]            Render the complete audit; default is the compact receipt",
         "    [--group-by source|model|client|project|agent|user|workspace|apiKey]  Default: project for local logs; model otherwise",
-        "  report [--sample] [--out <name>] [--since-days N] Generate local Markdown and HTML reports from the same window",
+        "  report [--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

@@ -0,0 +1,41 @@
+import { spawn } from "node:child_process";
+export type ReportOpenDecision = {
+    open: true;
+    command: string;
+    args: string[];
+} | {
+    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;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    stdoutIsTty?: boolean;
+    /** Test seam for the linux xdg-open PATH probe. */
+    hasCommandImpl?: (command: string, env: NodeJS.ProcessEnv) => boolean;
+}): ReportOpenDecision;
+/**
+ * Fire-and-forget launch of an affirmative decision. Returns true when the
+ * opener was handed to the OS (the summary may then say "opened …");
+ * returns false — never throws — on any spawn failure.
+ */
+export declare function openReportInBrowser(decision: ReportOpenDecision, options?: {
+    spawnImpl?: typeof spawn;
+}): boolean;
+//# sourceMappingURL=reportOpener.d.ts.map

package/dist/reportOpener.js

@@ -0,0 +1,156 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+/**
+ * 0.9.5 "agent feel": after `report` writes its artifacts, the HTML report
+ * opens in the user's browser automatically — through the platform opener,
+ * never a hardcoded browser:
+ *
+ *   darwin  →  open <html>
+ *   linux   →  xdg-open <html>   (only when xdg-open is actually on PATH)
+ *   win32   →  rundll32 url.dll,FileProtocolHandler <html>
+ *
+ * The decision to open is computed SYNCHRONOUSLY and truthfully before the
+ * summary renders, so the summary's Next block can say what actually
+ * happened. Auto-open is suppressed — silently, keeping the plain
+ * `open <path>` pointer — whenever any of these hold:
+ *
+ *   - stdout is not a TTY (pipes, redirection, scripts)
+ *   - CI is set (any non-empty value)
+ *   - an SSH session (SSH_CONNECTION or SSH_TTY set): the browser would
+ *     open on the wrong machine
+ *   - the user asked not to: `--no-open` flag or AI_SPEND_NO_OPEN env
+ *     (any non-empty value, same convention as AI_SPEND_NO_TELEMETRY)
+ *   - the resolved path contains a shell metacharacter (see below)
+ *   - the platform has no known opener (or linux without xdg-open)
+ *
+ * The spawn itself follows the telemetry detached-child pattern: detached,
+ * stdio ignored, unref'd, every failure (including async ENOENT) swallowed —
+ * the CLI must never crash, hang, or delay exit because an opener is
+ * missing or slow.
+ *
+ * SECURITY (win32 command-injection, fixed 0.9.5): the earlier
+ * `cmd /c start "" <path>` opener passed the path through cmd.exe, which
+ * re-parses `& ^ % ( ) < > |` even when spawned with shell:false — a
+ * space-free path like `C:\code\proj&calc` (all legal filename chars)
+ * would make cmd execute `calc`, and `%VAR%` would expand (info leak). The
+ * cwd-derived machine-wide path AND an absolute `--out` both reach here.
+ * Two independent defenses now stand:
+ *   1. UNSAFE_PATH_METACHARACTERS refuses auto-open (falling back to the
+ *      plain pointer) for ANY path carrying those characters or a quote,
+ *      on every platform — a metacharacter path is a reasonable thing to
+ *      decline to shell-open anywhere.
+ *   2. The win32 opener no longer touches a shell: rundll32 hands the path
+ *      straight to url.dll's FileProtocolHandler with a discrete argv, so
+ *      even a metacharacter path that slipped past (1) cannot reach cmd.
+ */
+/**
+ * cmd.exe re-parsing set plus the double-quote (which can break out of
+ * libuv's own arg quoting). A path containing any of these is never handed
+ * 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;
+    const stdoutIsTty = input.stdoutIsTty ?? Boolean(process.stdout.isTTY);
+    const hasCommand = input.hasCommandImpl ?? commandOnPath;
+    if (input.noOpenFlag)
+        return { open: false, reason: "no-open-flag" };
+    if (env.AI_SPEND_NO_OPEN)
+        return { open: false, reason: "env-switch" };
+    if (!stdoutIsTty)
+        return { open: false, reason: "not-a-tty" };
+    if (env.CI)
+        return { open: false, reason: "ci" };
+    if (env.SSH_CONNECTION || env.SSH_TTY)
+        return { open: false, reason: "ssh" };
+    // Defense (1): never shell-open a path carrying a cmd metacharacter or a
+    // quote — on any platform. This alone neutralizes the win32 vector.
+    if (UNSAFE_PATH_METACHARACTERS.test(input.htmlPath)) {
+        return { open: false, reason: "unsafe-path" };
+    }
+    if (platform === "darwin") {
+        return { open: true, command: "open", args: [input.htmlPath] };
+    }
+    if (platform === "win32") {
+        // Defense (2): rundll32 → url.dll,FileProtocolHandler opens the path
+        // with NO shell in the chain — cmd.exe never sees it, so its
+        // `& ^ % ( ) < > |` re-parsing (which shell:false does not prevent for
+        // `cmd /c start`) cannot fire even if defense (1) ever missed a char.
+        return {
+            open: true,
+            command: "rundll32",
+            args: ["url.dll,FileProtocolHandler", input.htmlPath]
+        };
+    }
+    if (platform === "linux" && hasCommand("xdg-open", env)) {
+        return { open: true, command: "xdg-open", args: [input.htmlPath] };
+    }
+    return { open: false, reason: "no-opener" };
+}
+/**
+ * Fire-and-forget launch of an affirmative decision. Returns true when the
+ * opener was handed to the OS (the summary may then say "opened …");
+ * returns false — never throws — on any spawn failure.
+ */
+export function openReportInBrowser(decision, options = {}) {
+    if (!decision.open)
+        return false;
+    try {
+        const spawnImpl = options.spawnImpl ?? spawn;
+        const child = spawnImpl(decision.command, decision.args, {
+            detached: true,
+            stdio: "ignore"
+        });
+        // Async spawn errors (a vanished opener) surface on the child, not the
+        // call — swallow them so they can never crash the exiting CLI.
+        child.on?.("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Synchronous PATH probe (linux xdg-open) — cheap, no child process. */
+function commandOnPath(command, env) {
+    const pathValue = env.PATH ?? "";
+    for (const dir of pathValue.split(delimiter)) {
+        if (!dir)
+            continue;
+        try {
+            accessSync(join(dir, command), constants.X_OK);
+            return true;
+        }
+        catch {
+            // keep looking
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=reportOpener.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spend-agent",
-  "version": "0.9.4",
+  "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.4",
-    "@agent-finops/report": "0.9.4",
+    "@agent-finops/core": "0.9.6",
+    "@agent-finops/report": "0.9.6",
     "yocto-spinner": "^1.2.0"
   }
 }