ai-spend-agent 0.5.7 → 0.5.9

package/dist/index.js

@@ -3,7 +3,7 @@ import { realpathSync } from "node:fs";
 import { mkdir, readFile, rm, stat } from "node:fs/promises";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { analyzeSpend, attributeUsageRecords, buildUsageGlance, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, writeSafeStateText, loadDeadContext, sampleDeadContext, loadLocalAgentUsage, loadSampleUsageData, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProviderConnectorStub, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, slugifySourceId } from "@agent-finops/core";
+import { analyzeSpend, attributeUsageRecords, buildUsageGlance, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, writeSafeStateText, loadDeadContext, sampleDeadContext, latestObservedWorkingDirectory, isBundledSampleUsage, loadLocalAgentUsage, loadSampleUsageData, parseUsageRecord, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProviderConnectorStub, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, slugifySourceId } from "@agent-finops/core";
 import { generateActionPlanMarkdown, generateApplyArtifactMarkdown, generateDemoPackageMarkdown, generateHtmlReport, generateMarkdownReport, generatePlainEnglishSummary, generatePolicyConfigDraftMarkdown, generateReportCardCaption, generateReportCardSvg, generateVerificationPlanMarkdown, groupByDimensions } from "@agent-finops/report";
 export async function runCli(argv = process.argv.slice(2)) {
     if (argv.includes("--version") || argv.includes("-v")) {
@@ -82,7 +82,10 @@ export async function runCli(argv = process.argv.slice(2)) {
     };
 }
 async function quickstartCommand(args) {
-    const { records, mode, warnings } = await loadInstantReadData(args);
+    const sinceDays = args.sinceDays ?? 30;
+    if (!validSinceDays(sinceDays))
+        return invalidSinceDaysResult();
+    const { records, mode, warnings, codexInvocationFiles } = await loadInstantReadData(args);
     const summaryRecords = mode === "connected"
         ? selectProviderFinancialHeadlineRecords(records)
         : records;
@@ -94,7 +97,12 @@ async function quickstartCommand(args) {
     // Persona: --plan override wins; otherwise read the plans the coding agents
     // themselves persisted locally (read-only, whitelisted fields, no network).
     let detectedPlans;
-    if (args.plan) {
+    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 {
@@ -114,7 +122,15 @@ async function quickstartCommand(args) {
     }
     // Surface auto-detected credentials so the user knows their next 2-min step,
     // without ever printing a raw secret.
-    const detection = await detectLocalCredentials({ cwd: resolve(args.path) });
+    // Sample output is designed for demos, docs, and screenshots. Keeping local
+    // credential discovery out of that path prevents even redacted machine-
+    // specific hints from leaking into a recording.
+    const detection = args.sample
+        ? { credentials: [], scannedFiles: [] }
+        : await detectLocalCredentials({
+            cwd: resolve(args.path),
+            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
@@ -132,8 +148,9 @@ async function quickstartCommand(args) {
             claudeSettingsPath: process.env.AI_SPEND_CLAUDE_SETTINGS,
             projectDir: resolve(args.path),
             includeAllProjectMcp: true,
-            sinceIso: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
-            windowDays: 30
+            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 —
@@ -158,21 +175,21 @@ async function quickstartCommand(args) {
 }
 async function glanceCommand(args) {
     const sinceDays = args.sinceDays ?? 30;
-    if (!Number.isInteger(sinceDays) || sinceDays < 1 || sinceDays > 365) {
-        return {
-            exitCode: 1,
-            stdout: "",
-            stderr: "--since-days must be a whole number between 1 and 365"
-        };
-    }
+    if (!validSinceDays(sinceDays))
+        return invalidSinceDaysResult();
     const logs = await loadLocalAgentUsage({
         claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
         codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
-        sinceIso: new Date(Date.now() - sinceDays * 24 * 60 * 60 * 1_000).toISOString()
+        sinceIso: sinceIsoForDays(sinceDays),
+        collectCodexInvocationEvidence: true
     });
     const calls = args.project
         ? logs.calls.filter((call) => call.project === args.project)
         : logs.calls;
+    const latestWorkingDirectory = latestObservedWorkingDirectory(calls);
+    const contextProjectDir = args.pathExplicit
+        ? resolve(args.path)
+        : latestWorkingDirectory ?? resolve(args.path);
     let detectedPlans;
     if (args.plan) {
         const override = planOverrideFromFlag(args.plan);
@@ -198,9 +215,10 @@ async function glanceCommand(args) {
         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),
-        sinceIso: new Date(Date.now() - sinceDays * 24 * 60 * 60 * 1_000).toISOString(),
-        windowDays: sinceDays
+        projectDir: contextProjectDir,
+        sinceIso: sinceIsoForDays(sinceDays),
+        windowDays: sinceDays,
+        codexInvocationFiles: logs.codexInvocationFiles
     });
     const snapshot = buildUsageGlance(calls, {
         filesParsed: logs.filesParsed,
@@ -213,18 +231,14 @@ async function glanceCommand(args) {
 }
 async function contextHealthCommand(args) {
     const sinceDays = args.sinceDays ?? 30;
-    if (!Number.isInteger(sinceDays) || sinceDays < 1 || sinceDays > 365) {
-        return {
-            exitCode: 1,
-            stdout: "",
-            stderr: "--since-days must be a whole number between 1 and 365"
-        };
-    }
-    const sinceIso = new Date(Date.now() - sinceDays * 24 * 60 * 60 * 1_000).toISOString();
+    if (!validSinceDays(sinceDays))
+        return invalidSinceDaysResult();
+    const sinceIso = sinceIsoForDays(sinceDays);
     const logs = await loadLocalAgentUsage({
         claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
         codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
-        sinceIso
+        sinceIso,
+        collectCodexInvocationEvidence: true
     });
     const calls = args.project
         ? logs.calls.filter((call) => call.project === args.project)
@@ -238,7 +252,8 @@ async function contextHealthCommand(args) {
         claudeSettingsPath: process.env.AI_SPEND_CLAUDE_SETTINGS,
         projectDir: resolve(args.path),
         sinceIso,
-        windowDays: sinceDays
+        windowDays: sinceDays,
+        codexInvocationFiles: logs.codexInvocationFiles
     });
     return ok(args.json ? JSON.stringify(health) : renderContextHealth(health));
 }
@@ -254,20 +269,23 @@ function renderContextHealth(health) {
         `Confidence: ${health.confidence}`,
         "",
         "Activation",
-        `  Discoverable: ${activation.discoverableItems}  Invoked: ${activation.explicitlyInvokedItems}  MCP schema-loaded: ${activation.mcpSchemaLoadedItems}`,
+        `  Discoverable: ${activation.discoverableItems}  Invoked: ${activation.explicitlyInvokedItems}  MCP configured: ${activation.mcpConfiguredItems}`,
+        `  MCP always-load requested: ${activation.mcpAlwaysLoadedItems}  Legacy schema-loaded label: ${activation.mcpSchemaLoadedItems}`,
         `  Hook-injected: ${activation.hookInjectedItems}  Other lifecycle hooks: ${activation.lifecycleHooks}  Unmeasured weight: ${activation.unmeasuredItems}`,
         `  Invocation-unobservable: ${activation.invocationUnobservableItems}`,
         "",
-        `Never invoked among observable inventory (${dead.windowDays}d): ${dead.neverInvokedItems}/${dead.loadedItems} ` +
+        `No matching invocation among observable inventory (${dead.windowDays}d): ${dead.neverInvokedItems}/${dead.loadedItems} ` +
             `(${dead.measuredNeverInvokedItems} measured, ${dead.unmeasuredNeverInvokedItems} unmeasured)`
     ];
     if (health.currentSession) {
         const session = health.currentSession;
-        lines.push(`Session: ${session.agent}${session.project ? ` · ${session.project}` : ""} · ` +
-            `${session.totalTokens.toLocaleString("en-US")} tokens · ` +
-            (session.ratioToMedian === null
-                ? "no same-agent baseline"
-                : `${session.ratioToMedian}× median (${session.comparisonSessions} prior)`));
+        lines.push(`Latest turn: ${session.agent}${session.project ? ` · ${session.project}` : ""} · ` +
+            (session.usageSource === "not_available"
+                ? "input context unavailable; cumulative lifetime usage excluded"
+                : `${session.contextTokens.toLocaleString("en-US")} input context tokens · ` +
+                    (session.ratioToMedian === null
+                        ? `${session.comparisonSessions} comparable prior session${session.comparisonSessions === 1 ? "" : "s"}; baseline not yet sufficient`
+                        : `${session.ratioCapped ? "at least " : ""}${session.ratioToMedian}× comparable median (${session.comparisonSessions} prior)`)));
     }
     const churn = health.contextChurn;
     if (churn.currentSessionEvidence === "matched") {
@@ -331,7 +349,9 @@ async function loadInstantReadData(args) {
     const logs = await loadLocalAgentUsage({
         // 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
+        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+        sinceIso: sinceIsoForDays(args.sinceDays ?? 30),
+        collectCodexInvocationEvidence: true
     }).catch(() => undefined);
     if (logs && logs.records.length > 0) {
         // Persisted local_logs state (written by report/apply-artifact) is the
@@ -340,7 +360,12 @@ async function loadInstantReadData(args) {
         if (persisted && persisted.records.length > 0 && persisted.mode !== "connected_provider" && persisted.mode !== "local_logs") {
             warnings.push("Ignored persisted sample/legacy state in .ai-spend-agent/spend.json — showing your real local agent logs. Run `ai-spend-agent reset` to clear it, or pass --ignore-state.");
         }
-        return { records: logs.records, mode: "local-logs", warnings };
+        return {
+            records: logs.records,
+            mode: "local-logs",
+            warnings,
+            codexInvocationFiles: logs.codexInvocationFiles
+        };
     }
     // No real logs. Persisted sample/legacy state may still be shown, but only as
     // DEMO (never as connected), with a warning when its origin is unknown.
@@ -375,7 +400,10 @@ async function doctorCommand(args) {
     const claudeFound = detected.includes("claude-code");
     const codexFound = detected.includes("codex");
     const hasLogs = claudeFound || codexFound;
-    const detection = await detectLocalCredentials({ cwd: rootPath }).catch(() => ({ credentials: [] }));
+    const detection = await detectLocalCredentials({
+        cwd: rootPath,
+        home: process.env.AI_SPEND_CLAUDE_HOME_DIR
+    }).catch(() => ({ credentials: [] }));
     const providerRefs = detection.credentials.map((credential) => `${credential.provider} (${credential.hint})`);
     const plans = await detectLocalPlans({
         claudeConfigPath: process.env.AI_SPEND_CLAUDE_CONFIG,
@@ -399,7 +427,7 @@ async function doctorCommand(args) {
             ? "your local agent logs (estimated at API-equivalent rates)"
             : "demo sample (illustrative)";
     const lines = [
-        "AI Spend Analyst doctor",
+        "aibill doctor",
         `node version: ${process.version}`,
         `cli version: ${await cliVersion()}`,
         "local-first mode: enabled (no cloud upload, no telemetry)",
@@ -437,7 +465,7 @@ async function resetCommand(args) {
         if (!isNodeError(error, "ENOENT"))
             throw error;
         return ok([
-            "AI Spend Analyst reset",
+            "aibill reset",
             `path: ${rootPath}`,
             "nothing to clear (no persisted spend state found)",
             "next run will re-read your real local agent logs (or demo sample if none)."
@@ -457,7 +485,7 @@ async function resetCommand(args) {
         }
     }
     return ok([
-        "AI Spend Analyst reset",
+        "aibill reset",
         `path: ${rootPath}`,
         removed.length > 0 ? `cleared: ${removed.join(", ")}` : "nothing to clear (no persisted spend state found)",
         "next run will re-read your real local agent logs (or demo sample if none)."
@@ -469,7 +497,7 @@ async function initCommand(args) {
     await mkdir(stateDir, { recursive: true });
     const registry = createLocalFolderSourceRegistry(rootPath);
     await writeJson(join(stateDir, "manifest.json"), {
-        product: "AI Spend Analyst Agent",
+        product: "aibill",
         mode: "local-first-demo",
         cloudUpload: false,
         cronJobsEnabled: false,
@@ -493,7 +521,7 @@ async function initCommand(args) {
         }
     ]));
     return ok([
-        "AI Spend Analyst Agent init",
+        "aibill init",
         `path: ${rootPath}`,
         "demo mode: local-first sample workflow",
         "cloud upload: disabled",
@@ -570,7 +598,7 @@ async function scanCommand(args) {
     await writeJson(join(stateDir, "discovery.json"), discovery);
     await writeJson(join(stateDir, "missing-sources.json"), missingSourcePrompts);
     const lines = [
-        "AI Spend Analyst Agent scan",
+        "aibill scan",
         `path: ${rootPath}`,
         "source registry: .ai-spend-agent/sources.json",
         "audit log: .ai-spend-agent/audit-log.json",
@@ -779,7 +807,7 @@ async function addSourceCommand(args) {
         detail: `${args.sourceType} approved via CLI add-source.`
     });
     return ok([
-        "AI Spend Analyst Agent add-source",
+        "aibill add-source",
         `source added: ${id}`,
         `type: ${args.sourceType}`,
         `path: ${sourcePath}`,
@@ -792,7 +820,7 @@ async function listSourcesCommand(args) {
     const stateDir = join(rootPath, ".ai-spend-agent");
     const registry = await readSourceRegistry(stateDir, rootPath);
     const lines = [
-        "AI Spend Analyst Agent sources",
+        "aibill sources",
         `approved sources: ${registry.approvedSources.length}`
     ];
     for (const source of registry.approvedSources) {
@@ -847,10 +875,13 @@ async function connectCommand(args) {
         detail: `${provider} ${type} connector stub registered. No raw secrets stored.`
     });
     // Auto-detect a local key for this provider (never prints the raw value).
-    const detection = await detectLocalCredentials({ cwd: rootPath });
+    const detection = await detectLocalCredentials({
+        cwd: rootPath,
+        home: process.env.AI_SPEND_CLAUDE_HOME_DIR
+    });
     const detected = detection.credentials.find((credential) => credential.provider === provider);
     const lines = [
-        "AI Spend Analyst Agent connect",
+        "aibill connect",
         `connector stub: ${source.id}`,
         `provider: ${provider}`,
         `type: ${type}`,
@@ -983,7 +1014,7 @@ async function syncProviderCommand(args) {
             detail: `${args.provider} provider connector synced ${result.records.length} evidence records with ${result.coverage} coverage. Auth reference only; no raw secrets stored.`
         });
         return ok([
-            "AI Spend Analyst Agent sync-provider",
+            "aibill sync-provider",
             `provider: ${result.provider}`,
             `source: ${result.source.id}`,
             `verification: ${result.source.verification}`,
@@ -1035,7 +1066,7 @@ async function confirmMappingCommand(args) {
         detail: `${args.provider} mapped to ${[args.team, args.project, args.workflow].filter(Boolean).join(" / ")}`
     });
     return ok([
-        "AI Spend Analyst Agent confirm-mapping",
+        "aibill confirm-mapping",
         `mapping confirmed: ${mapping.id}`,
         `provider: ${mapping.provider}`,
         `target: ${[mapping.team, mapping.project, mapping.workflow].filter(Boolean).join(" / ")}`,
@@ -1046,7 +1077,10 @@ async function reportCommand(args) {
     const rootPath = resolve(args.path);
     const stateDir = join(rootPath, ".ai-spend-agent");
     try {
-        const reportInput = await buildReportInput(stateDir, rootPath);
+        const sinceDays = args.sinceDays ?? 30;
+        if (!validSinceDays(sinceDays))
+            return invalidSinceDaysResult();
+        const reportInput = await buildReportInput(stateDir, rootPath, sinceDays);
         const outBase = args.out ? resolve(rootPath, args.out) : join(stateDir, "report");
         const markdownPath = `${outBase}.md`;
         const htmlPath = `${outBase}.html`;
@@ -1054,7 +1088,7 @@ async function reportCommand(args) {
         await writeLocalReportFile(htmlPath, generateHtmlReport(reportInput), stateDir);
         const artifactPaths = await writeApplyArtifacts(stateDir, reportInput);
         return ok([
-            "AI Spend Analyst Agent report",
+            "aibill report",
             `path: ${rootPath}`,
             `markdown: ${markdownPath}`,
             `html: ${htmlPath}`,
@@ -1063,8 +1097,8 @@ async function reportCommand(args) {
             `policy/config draft: ${artifactPaths.policyConfigDraft}`,
             `verification plan: ${artifactPaths.verificationPlan}`,
             `demo package: ${artifactPaths.demoPackage}`,
-            `total spend: $${reportInput.summary.totalUsd.toFixed(2)}`,
-            "privacy: local files only; no cloud upload performed",
+            `cost/value evidence total: $${reportInput.summary.totalUsd.toFixed(2)}`,
+            "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`,
@@ -1118,7 +1152,7 @@ async function reportCardCommand(args) {
             "Caption to share:",
             generateReportCardCaption({ summary, records: headlineRecords, mode }),
             "",
-            "privacy: rendered locally; only totals, modeled opportunities, and model-level investigations are included."
+            "privacy: rendered locally; only totals, generic candidate categories, and evidence labels are included."
         ].join("\n"));
     }
     catch (error) {
@@ -1133,13 +1167,34 @@ async function applyArtifactCommand(args) {
     const rootPath = resolve(args.path);
     const stateDir = join(rootPath, ".ai-spend-agent");
     try {
-        const reportInput = await buildReportInput(stateDir, rootPath);
+        const sinceDays = args.sinceDays ?? 30;
+        if (!validSinceDays(sinceDays))
+            return invalidSinceDaysResult();
+        // `--sample` is a privacy boundary, not presentation sugar. It must never
+        // fall through to live transcript, plan, credential, or persisted-state
+        // discovery — regardless of where the flag appears after the command.
+        const reportInput = args.sample
+            ? await buildExplicitSampleReportInput(rootPath)
+            : await buildReportInput(stateDir, rootPath, sinceDays);
+        await mkdir(stateDir, { recursive: true });
         const artifactPaths = await writeApplyArtifacts(stateDir, reportInput);
         // The prompt IS the product of this command — print it so a terminal
         // user can copy it right here instead of hunting for a file path.
         const codingPrompt = await readFile(artifactPaths.codingPrompt, "utf8");
+        if (args.sample) {
+            return ok([
+                "aibill apply-artifact",
+                "data: DEMO sample data (illustrative — not your logs, account, bill, project, or workflow)",
+                "artifacts: .ai-spend-agent/ (non-executable demo files)",
+                "safety: no live transcripts, account metadata, credentials, or persisted spend state were read",
+                "",
+                "──── non-executable demo prompt (also saved under .ai-spend-agent/) ────",
+                "",
+                codingPrompt.trimEnd()
+            ].join("\n"));
+        }
         return ok([
-            "AI Spend Analyst Agent apply-artifact",
+            "aibill apply-artifact",
             `path: ${rootPath}`,
             `action plan: ${artifactPaths.actionPlan}`,
             `policy/config draft: ${artifactPaths.policyConfigDraft}`,
@@ -1160,9 +1215,51 @@ async function applyArtifactCommand(args) {
         };
     }
 }
-async function buildReportInput(stateDir, rootPath) {
+async function buildExplicitSampleReportInput(rootPath) {
+    const records = await loadSampleUsageData();
+    return {
+        // Fixed alongside the bundled fixture so repeated demo runs stay stable
+        // and cannot absorb this machine's clock or account state into an asset.
+        generatedAt: "2026-05-20T00:00:00.000Z",
+        summary: analyzeSpend(records),
+        allRecords: records,
+        dataMode: "sample",
+        discovery: emptyDiscovery(rootPath),
+        mappings: attributeUsageRecords(records),
+        missingSourcePrompts: [],
+        confirmedMappings: [],
+        providerRecords: [],
+        providerQa: [],
+        deadContext: sampleDeadContext(),
+        detectedPlans: []
+    };
+}
+async function buildReportInput(stateDir, rootPath, sinceDays = 30) {
+    // One anchor for logs, Context Health, the paste-ready prompt, and every
+    // supporting Apply artifact. This prevents millisecond window drift between
+    // files generated by the same command.
+    const generatedAt = new Date();
+    const sinceIso = sinceIsoForDays(sinceDays, generatedAt);
+    let freshLocalCalls;
+    let freshCodexInvocationFiles;
     let spendState = await readOptionalJson(join(stateDir, "spend.json"), undefined);
     let mappings = await readOptionalJson(join(stateDir, "mappings.json"), undefined);
+    // Never trust a persisted summary or an absent mode. Re-parse the records,
+    // recover the narrowly identifiable bundled sample written by older
+    // releases, and recompute decision output under the current evidence rules.
+    // Any other unlabeled state remains unlabeled and therefore non-executable.
+    if (spendState?.records && spendState.records.length > 0) {
+        const records = spendState.records.map((record) => parseUsageRecord(record));
+        const mode = spendState.mode ?? (isBundledSampleUsage(records) ? "sample" : undefined);
+        const headlineRecords = mode === "connected_provider"
+            ? selectProviderFinancialHeadlineRecords(records)
+            : records;
+        spendState = {
+            records,
+            mode,
+            summary: analyzeSpend(headlineRecords)
+        };
+    }
     // Local-log state is a CACHE, not a source of truth: the quickstart always
     // re-reads the logs fresh, so report/apply must too — otherwise yesterday's
     // persisted snapshot makes the artifact's numbers disagree with the screen.
@@ -1182,9 +1279,13 @@ async function buildReportInput(stateDir, rootPath) {
     if (needsFreshLogs) {
         const logs = await loadLocalAgentUsage({
             claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
-            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR
+            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+            sinceIso,
+            collectCodexInvocationEvidence: true
         }).catch(() => undefined);
         if (logs && logs.records.length > 0) {
+            freshLocalCalls = logs.calls;
+            freshCodexInvocationFiles = logs.codexInvocationFiles;
             const records = logs.records;
             const summary = analyzeSpend(records);
             const liveMappings = attributeUsageRecords(records);
@@ -1218,8 +1319,9 @@ async function buildReportInput(stateDir, rootPath) {
             claudeSettingsPath: process.env.AI_SPEND_CLAUDE_SETTINGS,
             projectDir: rootPath,
             includeAllProjectMcp: true,
-            sinceIso: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
-            windowDays: 30
+            sinceIso,
+            windowDays: sinceDays,
+            codexInvocationFiles: freshCodexInvocationFiles
         }).catch(() => undefined)
         : undefined;
     const detectedPlans = spendState.mode === "local_logs"
@@ -1228,10 +1330,30 @@ async function buildReportInput(stateDir, rootPath) {
             codexAuthPath: process.env.AI_SPEND_CODEX_AUTH
         }).catch(() => [])
         : [];
+    // Report/apply and Glance consume the same canonical Context Health result.
+    // If live transcript calls are unavailable, omit it instead of fabricating a
+    // session-level recommendation from day-aggregate spend records.
+    const contextHealth = spendState.mode === "local_logs" && freshLocalCalls
+        ? await loadContextHealth(freshLocalCalls, {
+            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: rootPath,
+            includeAllProjectMcp: true,
+            sinceIso,
+            windowDays: sinceDays,
+            codexInvocationFiles: freshCodexInvocationFiles
+        }).catch(() => undefined)
+        : undefined;
     return {
+        generatedAt: generatedAt.toISOString(),
         summary: spendState.summary,
         deadContext,
         detectedPlans,
+        contextHealth,
         // Evidence ledger is built from the SAME records as the confidence
         // breakdown so the two sections can never contradict each other.
         allRecords: spendState.mode === "connected_provider"
@@ -1247,6 +1369,19 @@ async function buildReportInput(stateDir, rootPath) {
         providerQa: providerRecordsState.qa ? [providerRecordsState.qa] : []
     };
 }
+function validSinceDays(value) {
+    return Number.isInteger(value) && value >= 1 && value <= 365;
+}
+function sinceIsoForDays(value, now = new Date()) {
+    return new Date(now.getTime() - value * 24 * 60 * 60 * 1_000).toISOString();
+}
+function invalidSinceDaysResult() {
+    return {
+        exitCode: 1,
+        stdout: "",
+        stderr: "--since-days must be a whole number between 1 and 365"
+    };
+}
 function emptyDiscovery(rootPath) {
     return {
         rootPath,
@@ -1348,6 +1483,7 @@ function parseArgs(argv) {
             const next = rest[index + 1];
             if (next) {
                 parsed.path = next;
+                parsed.pathExplicit = true;
                 index += 1;
             }
             continue;
@@ -1644,20 +1780,20 @@ function helpText() {
         "  --ignore-state          On the default/quickstart run, ignore persisted spend.json for this run",
         "  scan [--path <dir>]     Scan a local workspace for AI usage signals",
         "  scan --sample           Include deterministic sample spend analysis",
-        "  quickstart [--sample]   Plain-English local readout (alias of the default run)",
-        "    [--group-by source|model|client|project|agent|user|workspace|apiKey]  Default: model",
-        "  report [--out <name>]   Generate local Markdown and HTML reports",
+        "  quickstart [--sample] [--since-days N] Plain-English local readout (default 30 days)",
+        "    [--group-by source|model|client|project|agent|user|workspace|apiKey]  Default: project for local logs; model otherwise",
+        "  report [--out <name>] [--since-days N] Generate local Markdown and HTML reports from the same window",
         "  report-card [--out f.svg] Write your AI Receipt — a redacted, shareable SVG + caption",
-        "  glance [--project <name>] [--plan <id>] Emit the local, machine-readable Glance snapshot JSON",
+        "  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",
-        "  apply                   Print the paste-ready coding-agent prompt + write action/policy/verification plans",
+        "  apply [--sample] [--since-days N]  Print an evidence-constrained inspection/approval prompt + verification plans",
         "  apply-artifact          Same as `apply` (long form)",
         "",
         "Cron (production watch): add a crontab entry such as:",
         "  0 * * * * cd /path/to/workspace && ai-spend-agent watch --interval 3600 --cycles 1 >> ai-spend-watch.log 2>&1",
         "",
-        "Privacy: local-first. No files, credentials, or spend data are uploaded. Secrets are never printed."
+        "Privacy: local analysis and reports upload nothing. Only explicit sync-provider contacts the selected provider through an env: reference; secrets are never printed or persisted."
     ].join("\n");
 }
 // Main-module check that survives npm's bin SYMLINKS: argv[1] is

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-spend-agent",
-  "version": "0.5.7",
-  "description": "Local-first financial intelligence CLI for Claude Code and Codex activity, provider-reported cost, attribution, runway, provenance, and Context Health.",
+  "version": "0.5.9",
+  "description": "Local-first financial accountability CLI for Claude Code and Codex work, cost evidence, attribution, runway, provenance, and Context Health.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -54,8 +54,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@agent-finops/core": "0.5.7",
-    "@agent-finops/report": "0.5.7",
+    "@agent-finops/core": "0.5.9",
+    "@agent-finops/report": "0.5.9",
     "yocto-spinner": "^1.2.0"
   }
 }