ai-spend-agent 0.9.4 → 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,
@@ -3769,9 +3775,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 +3877,98 @@ 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: `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 }
                         ]
                         : 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.
+            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"
-                    ? `  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 <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
-                    ? `  ${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: "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"));
+                            ? { 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 {
@@ -3953,9 +3997,16 @@ async function reportCardCommand(args) {
     // 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;
@@ -3984,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 {
@@ -4032,12 +4091,63 @@ async function reportCardCommand(args) {
  * (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");
-    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);
@@ -6418,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;
@@ -7032,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.4",
+  "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.4",
-    "@agent-finops/report": "0.9.4",
+    "@agent-finops/core": "0.9.5",
+    "@agent-finops/report": "0.9.5",
     "yocto-spinner": "^1.2.0"
   }
 }