ai-spend-agent 0.9.3 → 0.9.5

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,7 +3,7 @@ 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";
@@ -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 } from "./reportOpener.js";
+import { generateActionPlanMarkdown, generateApplyArtifactMarkdown, generateCommandSummary, generateDemoPackageMarkdown, generateHtmlReport, generateMarkdownReport, generatePlainEnglishSummary, generatePolicyConfigDraftMarkdown, generateReportCardCaption, generateReportCardSvg, generateVerificationPlanMarkdown, groupByDimensions } 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
@@ -272,6 +273,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 <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,
@@ -618,9 +624,11 @@ function quickstartNextSteps(mode, detected) {
         steps.push(`npx aibill connect ${detected[0].provider}   set up the admin connector, then sync provider-reported cost`);
     }
     steps.push(mode === "demo"
-        // Every printed command must run as printed: the demo workspace does
-        // not exist yet, so the command creates it first (shipped-audit fix).
-        ? "mkdir -p ./demo-workspace && npx aibill report --sample --path ./demo-workspace     write a clearly labeled demo report in an explicitly narrow workspace"
+        // 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");
     steps.push("Need team reconciliation, allocation, budgets, and approvals? Workspace design partners: https://asktilden.com");
@@ -1154,7 +1162,9 @@ function noEvidenceResult(surface, warnings, sinceDays, telemetryDisclosure) {
         ? "Watch has no financial baseline yet; no zero total or sample activity was recorded."
         : surface === "report-card"
             ? "No receipt was written because there is no supported financial evidence to summarize."
-            : `No supported AI usage evidence was found in the last ${sinceDays} days.`;
+            : surface === "report"
+                ? "No report was written because there is no supported financial evidence to summarize."
+                : `No supported AI usage evidence was found in the last ${sinceDays} days.`;
     return {
         exitCode: surface === "receipt" ? 0 : 1,
         stdout: surface === "receipt"
@@ -3758,27 +3768,53 @@ async function confirmMappingCommand(args) {
     ].join("\n"));
 }
 async function reportCommand(args, runtime = {}) {
-    // NEW-B3 + adversary F2: guard UNCONDITIONALLY. Even --sample writes
-    // project state into the root (resolveSafeStateDirectory below), so a
-    // broad root must refuse with the friendly guidance — the sample gate
-    // alone still leaked the raw "Refusing to scan" from home. report-card
-    // --sample differs: it writes only the SVG artifact and keeps its
-    // deliberate home exemption.
-    const rootGuard = await guardExactProjectRoot("report", args.path);
-    if (rootGuard)
-        return rootGuard;
+    // 0.9.4: a broad root (home, /) runs MACHINE-WIDE — the same read-only
+    // transcript scanning as the bare receipt, no project state created, both
+    // report files written to the current directory. The report renders
+    // machine-wide content anyway (it lists every project), so the
+    // 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. 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) {
+        const broadGuard = guardUnwritableBroadRoot("report", args);
+        if (broadGuard)
+            return broadGuard;
+    }
+    else {
+        const rootGuard = await guardExactProjectRoot("report", args.path);
+        if (rootGuard)
+            return rootGuard;
+    }
     const rootPath = resolve(args.path);
     try {
         const sinceDays = args.sinceDays ?? 30;
         if (!validSinceDays(sinceDays))
             return invalidSinceDaysResult();
-        const stateDir = await resolveSafeStateDirectory(rootPath, { create: true });
+        // Machine-wide mode NEVER creates project state at the broad root — the
+        // only writes are the two report files below (plus ~/.aibill home state
+        // owned by other subsystems).
+        const stateDir = machineWide ? undefined : await resolveSafeStateDirectory(rootPath, { create: true });
         // Like Apply, an explicit sample report is a strict privacy boundary. It
         // must not inspect local transcripts, account metadata, or persisted state.
-        const reportInput = args.sample
-            ? await buildExplicitSampleReportInput(rootPath)
-            : await buildReportInput(stateDir, rootPath, sinceDays);
-        const persistedPreferredExperiment = args.sample
+        let reportInput;
+        if (args.sample) {
+            reportInput = await buildExplicitSampleReportInput(rootPath);
+        }
+        else if (machineWide) {
+            const machineWideInput = await buildMachineWideReportInput(args, sinceDays);
+            if (machineWideInput.kind === "no_evidence") {
+                return noEvidenceResult("report", machineWideInput.warnings, sinceDays, runtime.telemetryDisclosure);
+            }
+            reportInput = machineWideInput.input;
+        }
+        else {
+            reportInput = await buildReportInput(stateDir, rootPath, sinceDays);
+        }
+        const persistedPreferredExperiment = args.sample || machineWide
             ? undefined
             : chooseLatestTokenReductionExperiment((await loadTokenVerificationState(rootPath)).experiments);
         const preferredExperiment = persistedPreferredExperiment &&
@@ -3820,69 +3856,119 @@ async function reportCommand(args, runtime = {}) {
             : { ...reportInput, telemetryDisclosure };
         const qualitativeActionsSuppressed = reportInput.dataMode !== "sample" &&
             reportInput.qualitativeCoverage?.status !== "complete";
-        const outBase = args.out ? resolve(rootPath, args.out) : join(stateDir, "report");
+        // Machine-wide artifacts land in the CURRENT directory under the
+        // ai-spend-* family name; project mode keeps .ai-spend-agent/report.*.
+        const outBase = args.out
+            ? resolve(rootPath, args.out)
+            : machineWide
+                ? join(rootPath, "ai-spend-report")
+                : join(stateDir, "report");
         const markdownPath = `${outBase}.md`;
         const htmlPath = `${outBase}.html`;
-        await writeLocalReportFile(markdownPath, generateMarkdownReport(reportRenderInput), stateDir);
-        await writeLocalReportFile(htmlPath, generateHtmlReport(reportRenderInput), stateDir);
+        await writeLocalReportFile(markdownPath, generateMarkdownReport(reportRenderInput), stateDir ?? rootPath);
+        await writeLocalReportFile(htmlPath, generateHtmlReport(reportRenderInput), stateDir ?? rootPath);
         // A preferred canonical experiment owns this project's action/result
         // lineage even after completion or rollback. A report may refresh its
         // read-only projection, but never overwrite the frozen handoff with a
         // fresh or contradictory candidate. Coverage gaps receive only explicit
         // non-executable gap artifacts from the report package.
-        const artifactPaths = reportableExperiment
+        // Apply artifacts are project-scoped handoffs — machine-wide runs skip
+        // them (apply itself still requires one exact project folder).
+        const artifactPaths = reportableExperiment || machineWide
             ? undefined
             : await writeApplyArtifacts(stateDir, reportInput);
-        return ok([
-            "aibill report",
-            `path: ${rootPath}`,
-            `markdown: ${markdownPath}`,
-            `html: ${htmlPath}`,
-            ...(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}`
-                ]
-                : qualitativeActionsSuppressed
+        // 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
+                ? { 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: 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: `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 }
                     ]
-                    : artifactPaths
+                    : qualitativeActionsSuppressed
                         ? [
-                            `apply artifact: ${artifactPaths.codingPrompt}`,
-                            `action plan: ${artifactPaths.actionPlan}`,
-                            `policy/config draft: ${artifactPaths.policyConfigDraft}`,
-                            `verification plan: ${artifactPaths.verificationPlan}`,
-                            `demo package: ${artifactPaths.demoPackage}`
+                            { label: "Action artifacts", value: `suppressed · qualitative index ${reportInput.qualitativeCoverage?.status ?? "unknown"}` },
+                            { 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 }
                         ]
-                        : []),
-            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`,
-            reportableExperiment
-                ? `  ${improveRuntimeCommand}  review canonical token test ${reportableExperiment.id}`
-                : qualitativeActionsSuppressed
-                    ? `  ${actionRuntimeCommand(`context --json --since-days ${sinceDays}`)}  complete bounded qualitative evidence before any action`
-                    : 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"));
+                        : artifactPaths
+                            ? [
+                                { 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 }
+                            ]
+                            : []),
+            {
+                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.
+            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" },
+            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" }
+                : 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" }
+                        : 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" }
+        ];
+        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 {
@@ -3907,19 +3993,32 @@ async function resolveReceiptPath(rootPath, out) {
     return extname(resolved) ? resolved : `${resolved}.svg`;
 }
 async function reportCardCommand(args) {
-    if (!args.sample) {
-        // NEW-B3 + founder repro (`npx aibill report-card` from home): the raw
-        // scan refusal used to surface wrapped in "Couldn't write the report
-        // card:". The friendly guard renders clean, BEFORE the try/wrapper.
+    // 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. 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 (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;
     }
     try {
-        // Explicit sample mode reads no workspace data, so a broad-root scan guard
-        // would reject a harmless receipt written from the user's home directory.
-        // Output still goes through the safe-write/symlink checks below.
-        const rootPath = args.sample ? resolve(args.path) : await resolveSafeScanRoot(args.path);
+        // Sample mode reads no workspace data and machine-wide mode reads only
+        // the agent transcript dirs — neither scans the current directory, so
+        // both write the receipt from wherever the user stands. Output still
+        // goes through the safe-write/symlink checks below.
+        const rootPath = args.sample || machineWide
+            ? resolve(args.path)
+            : await resolveSafeScanRoot(args.path);
         const { records, mode, providerCoverage, warnings } = await loadInstantReadData(args);
         if (records.length === 0) {
             return noEvidenceResult("report-card", warnings, args.sinceDays ?? 30);
@@ -3936,28 +4035,36 @@ async function reportCardCommand(args) {
             mode,
             ...(providerCoverage ? { providerCoverage } : {})
         }));
-        const dataLine = mode === "demo"
+        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: "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 } : {})
+                        })]
+                }],
+            color: args.noColor ? false : undefined,
+            width: terminalOutputWidth()
+        }));
     }
     catch (error) {
         return {
@@ -3974,6 +4081,74 @@ async function reportCardCommand(args) {
  * exist (a location problem is not a breadth problem, but the fix is the
  * same). Returns undefined when the root is an acceptable exact project.
  */
+/**
+ * True when the requested root is a machine-wide location (home, filesystem
+ * root, a system directory, or anything containing home). report/report-card
+ * treat this as MACHINE-WIDE MODE — the same read-only, transcript-dir
+ * scanning the bare receipt performs — instead of refusing (0.9.4 founder
+ * fix: the receipt's own Next pointer led from home into a refusal that
+ * read as "the commands don't work"). Genuinely project-scoped commands
+ * (improve, apply, verify, watch, connect, reset, …) keep the guard.
+ */
+function isBroadScanRoot(requestedPath) {
+    return broadScanRootKind(requestedPath) !== undefined;
+}
+/** 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");
+    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);
     // An unset/empty $HOME (containers) must never make the current directory
@@ -5890,6 +6065,40 @@ 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.
+ */
+async function buildMachineWideReportInput(args, sinceDays) {
+    const { records, mode, providerCoverage, warnings } = await loadInstantReadData(args);
+    if (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 };
+    }
+    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;
+    return {
+        kind: "input",
+        input: {
+            generatedAt: new Date().toISOString(),
+            summary: analyzeSpend(headlineRecords),
+            allRecords: records,
+            dataMode: mode === "connected" ? "connected_provider" : "local_logs",
+            evidenceWindowDays: sinceDays,
+            detectedPlans,
+            ...(mode === "connected" ? { providerRecords: records } : {}),
+            ...(providerCoverage ? { providerCoverage } : {})
+        }
+    };
+}
 async function buildExplicitSampleReportInput(rootPath) {
     const records = await loadSampleUsageData();
     return {
@@ -6319,6 +6528,10 @@ function parseArgs(argv) {
             parsed.noColor = true;
             continue;
         }
+        if (arg === "--no-open") {
+            parsed.noOpen = true;
+            continue;
+        }
         if (arg === "--json") {
             parsed.json = true;
             continue;
@@ -6933,7 +7146,8 @@ 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",
         "  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",

package/dist/reportOpener.d.ts

@@ -0,0 +1,27 @@
+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";
+};
+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,132 @@
+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;
+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.3",
+  "version": "0.9.5",
   "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.3",
-    "@agent-finops/report": "0.9.3",
+    "@agent-finops/core": "0.9.5",
+    "@agent-finops/report": "0.9.5",
     "yocto-spinner": "^1.2.0"
   }
 }