costlayers 0.8.20 → 0.8.27

package/README.md

@@ -1,23 +1,23 @@
 # CostLayers CLI
 
-CostLayers is a cost-optimization layer for AI coding agents. It reduces repeated token waste from repo exploration, gives API users invoice-mode savings, and gives ChatGPT-login Codex users a usage-stretch meter that shows how much repeated context was avoided.
+CostLayers is an AI spend control layer for coding-agent teams. It starts with a free audit, finds repeated context waste, gives API users invoice-mode savings, and gives ChatGPT-login Codex users a usage-stretch meter that shows how much repeated context was avoided.
 
 ## Quick Start
 
-Daily Codex use:
+Run a free AI spend audit:
 
 ```bash
 cd your-repo
-npx -y https://costlayers.com/costlayers-0.8.20.tgz codex --email you@example.com --chatgpt
+npx -y https://costlayers.com/costlayers-0.8.27.tgz audit --monthly-spend 10000
 ```
 
-This default path preserves Codex's native ChatGPT-login/provider flow and shows a usage-stretch meter. CostLayers only routes billable API traffic when you explicitly pass `--api`.
+Use your real monthly AI spend if you have it. Omit `--monthly-spend` to get a repo-only audit. The audit writes `.agentspend/ai-spend-audit.md` and labels scan estimates separately from verified invoice savings. After the audit, `costlayers dashboard` shows the local result even before signup.
 
 Run a one-command API savings test:
 
 ```bash
 export OPENAI_API_KEY=sk-proj-...
-npx -y https://costlayers.com/costlayers-0.8.20.tgz test --email you@example.com
+npx -y https://costlayers.com/costlayers-0.8.27.tgz test --email you@example.com
 ```
 
 ## Usage
@@ -25,7 +25,13 @@ npx -y https://costlayers.com/costlayers-0.8.20.tgz test --email you@example.com
 Inside a repo:
 
 ```bash
-npx -y https://costlayers.com/costlayers-0.8.20.tgz codex --email you@example.com --chatgpt
+npx -y https://costlayers.com/costlayers-0.8.27.tgz audit --monthly-spend 10000
+```
+
+Then run Codex with CostLayers:
+
+```bash
+npx -y https://costlayers.com/costlayers-0.8.27.tgz codex --email you@example.com --chatgpt
 ```
 
 This gives Codex `.agentspend/repo-pack.md` and `.agentspend/runtime-plan.md`
@@ -45,7 +51,7 @@ API write permission:
 
 ```bash
 export OPENAI_API_KEY=sk-proj-...
-npx -y https://costlayers.com/costlayers-0.8.20.tgz codex --email you@example.com --api
+npx -y https://costlayers.com/costlayers-0.8.27.tgz codex --email you@example.com --api
 ```
 
 ChatGPT-login Codex can be metered, but it does not create per-request OpenAI
@@ -56,12 +62,13 @@ Platform invoice savings because it is not billed through your Platform API key.
 - ChatGPT-login Codex: use `costlayers codex --email you@example.com --chatgpt` to reduce repeated repo context and stretch usage limits.
 - OpenAI Platform API billing: set `OPENAI_API_KEY`, then use `costlayers codex --email you@example.com --api` for invoice-backed savings.
 - Savings proof: set `OPENAI_API_KEY`, then run `costlayers test --email you@example.com`.
+- Free audit: run `costlayers audit --monthly-spend <usd>` before changing a workflow.
 - Other OpenAI-compatible clients: point the client at the CostLayers gateway URL and check `costlayers gateway report`.
 
 To install only the Codex profile after signup:
 
 ```bash
-npx -y https://costlayers.com/costlayers-0.8.20.tgz codex-profile
+npx -y https://costlayers.com/costlayers-0.8.27.tgz codex-profile
 codex --profile costlayers
 ```
 
@@ -93,6 +100,8 @@ The hosted reducer defaults to quality-safe reduction:
 
 Output:
 
+- `.agentspend/ai-spend-audit.md`
+- `.agentspend/ai-spend-audit.json`
 - `.agentspend/repo-pack.md`
 - `.agentspend/savings-report.md`
 - `.agentspend/savings-report.json`

package/bin/agentspend.js

@@ -11,14 +11,14 @@ const { spawnSync } = require("child_process");
 
 function packageVersion() {
   try {
-    return require(path.join(__dirname, "..", "package.json")).version || "0.8.20";
+    return require(path.join(__dirname, "..", "package.json")).version || "0.8.27";
   } catch (_err) {
-    return "0.8.20";
+    return "0.8.27";
   }
 }
 
 const VERSION = packageVersion();
-const INSTALL_SPEC = "https://costlayers.com/costlayers-0.8.20.tgz";
+const INSTALL_SPEC = process.env.COSTLAYERS_INSTALL_SPEC || `https://costlayers.com/costlayers-${VERSION}.tgz`;
 const DEFAULT_RUNS_PER_WEEK = 20;
 const WEEKS_PER_MONTH = 4.33;
 const DEFAULT_EXCLUDES = new Set([
@@ -60,6 +60,7 @@ function usage(exitCode = 0) {
 CostLayers ${VERSION}
 
 Usage:
+  costlayers audit [--email <email>] [--monthly-spend <usd>] [--usage-file <path>]
   costlayers codex [--email <email>] [--chatgpt|--api] [-- <codex args>]
   costlayers test [--email <email>] [--prompt <text>]
   costlayers init [--repo <path>]
@@ -76,6 +77,7 @@ Usage:
   costlayers doctor
 
 Commands:
+  audit   Run a free AI spend audit: repo context waste plus optional monthly spend/imported usage.
   codex   Start Codex with CostLayers. Defaults to ChatGPT-login mode unless --api is passed.
   test    Run a safe read-only API invoice-mode Codex task and print the CostLayers savings report.
   init    Create .agentspend config and agent instructions.
@@ -195,7 +197,7 @@ function repoConnectionPath(repo) {
   return path.join(repo, ".agentspend", "connection.json");
 }
 
-function ensureAgentSpendGitignore(outDir) {
+function ensureCostLayersGitignore(outDir) {
   ensureDir(outDir);
   const file = path.join(outDir, ".gitignore");
   const required = ["connection.json", "*.secret.json", "gateway-key.txt", "local-cache.json"];
@@ -239,7 +241,7 @@ function writePrivateJson(file, payload) {
 function saveConnection(repo, connection) {
   const outDir = path.join(repo, ".agentspend");
   ensureDir(outDir);
-  ensureAgentSpendGitignore(outDir);
+  ensureCostLayersGitignore(outDir);
   const connectionId = connectionIdFor(repo, connection);
   const full = {
     ...connection,
@@ -677,7 +679,7 @@ function writeLocalCache(outDir, payload) {
 function scanToFiles(repo, args) {
   const outDir = path.join(repo, ".agentspend");
   ensureDir(outDir);
-  ensureAgentSpendGitignore(outDir);
+  ensureCostLayersGitignore(outDir);
   const tasks = Number(args.tasks || 100);
   const runsPerWeek = Number(args["runs-per-week"] || DEFAULT_RUNS_PER_WEEK);
   const pricePer1m = Number(args["price-per-1m"] || 2.0);
@@ -786,7 +788,7 @@ This public scanner estimates repeated context waste. Real savings should be val
 function init(repo, options = {}) {
   const outDir = path.join(repo, ".agentspend");
   ensureDir(outDir);
-  ensureAgentSpendGitignore(outDir);
+  ensureCostLayersGitignore(outDir);
   writeIfMissing(path.join(outDir, "config.json"), JSON.stringify({
     version: VERSION,
     created_utc: new Date().toISOString(),
@@ -862,6 +864,58 @@ function loadConnection(repo, args) {
   };
 }
 
+function localAudit(repo) {
+  const auditPath = path.join(repo, ".agentspend", "ai-spend-audit.json");
+  const savingsPath = path.join(repo, ".agentspend", "savings-report.json");
+  const auditReportPath = path.join(repo, ".agentspend", "ai-spend-audit.md");
+  const savingsReportPath = path.join(repo, ".agentspend", "savings-report.md");
+  const audit = readJsonIfExists(auditPath);
+  const savings = readJsonIfExists(savingsPath);
+  if (!audit && !savings) return null;
+  return { audit, savings, auditReportPath, savingsReportPath };
+}
+
+function printLocalDashboard(repo) {
+  const local = localAudit(repo);
+  if (!local) {
+    process.stderr.write([
+      "No CostLayers dashboard is available for this repo yet.",
+      "",
+      "Run a free local audit first:",
+      `  npx -y ${INSTALL_SPEC} audit --monthly-spend 10000`,
+      "",
+      "Or create a hosted dashboard:",
+      `  npx -y ${INSTALL_SPEC} signup --email you@example.com`,
+      ""
+    ].join("\n"));
+    return false;
+  }
+  const audit = local.audit || {};
+  const savings = local.savings || {};
+  const contextTokens = audit.tokens_avoided_per_run ?? savings.tokens_avoided_per_repeated_task ?? 0;
+  const contextReduction = audit.context_reduction_percent ?? savings.estimated_reduction_percent ?? 0;
+  const contextPackTokens = audit.context_pack_tokens ?? savings.context_pack_tokens ?? 0;
+  const sourceTokens = audit.source_tokens_indexed ?? savings.source_tokens_indexed ?? 0;
+  process.stdout.write(`CostLayers Local Dashboard\n`);
+  process.stdout.write(`status: local audit only; no hosted account connected\n`);
+  process.stdout.write(`repo: ${path.basename(repo)}\n`);
+  if (audit.spend_analyzed_display) process.stdout.write(`ai_spend_analyzed: ${audit.spend_analyzed_display}\n`);
+  if (audit.waste_found_display) process.stdout.write(`candidate_waste_found: ${audit.waste_found_display}\n`);
+  if (audit.safe_savings_display) process.stdout.write(`quality_safe_savings_now: ${audit.safe_savings_display}\n`);
+  process.stdout.write(`context_tokens_avoided_per_agent_run: ${formatInt(contextTokens)}\n`);
+  process.stdout.write(`context_reduction: ${Number(contextReduction || 0).toFixed(2)}%\n`);
+  process.stdout.write(`before_after_context: ${formatInt(sourceTokens)} -> ${formatInt(contextPackTokens)} tokens\n`);
+  process.stdout.write(`local_report: ${local.audit ? local.auditReportPath : local.savingsReportPath}\n`);
+  process.stdout.write(`\nNext:\n`);
+  process.stdout.write(`  Open the local report above, or create the hosted savings meter:\n`);
+  process.stdout.write(`  npx -y ${INSTALL_SPEC} signup --email you@example.com\n`);
+  process.stdout.write(`\nEvidence labels:\n`);
+  process.stdout.write(`  Context estimate: local scan, visible immediately.\n`);
+  process.stdout.write(`  Usage stretch: appears after Codex profile token events.\n`);
+  process.stdout.write(`  API invoice savings: appears only after API-billed traffic is routed through CostLayers.\n`);
+  return true;
+}
+
 function defaultPublicGatewayUrl(engineUrl, apiKey) {
   try {
     const url = new URL(engineUrl);
@@ -920,10 +974,20 @@ function dashboardUrlFromConnection(connection) {
   return (connection.gateway_url || defaultPublicGatewayUrl(connection.engine_url, connection.api_key)).replace("/gateway/", "/engine/dashboard/");
 }
 
-function printSavingsSummary(report) {
+function printSavingsSummary(report, options = {}) {
   const verdict = savingsVerdict(report);
   const projection = verdict.projection;
   const avoided = verdict.avoided;
+  if (options.compact) {
+    if (!verdict.meaningful) {
+      process.stdout.write(`CostLayers: repo scanned; no meaningful savings claim for this small/simple repo.\n`);
+    } else {
+      process.stdout.write(`CostLayers found context waste: ${formatInt(report.tokens_avoided_per_repeated_task)} tokens/run avoided (${report.estimated_reduction_percent}% less).\n`);
+      process.stdout.write(`Usage-stretch estimate: ${formatUsd(projection.monthlyUsd)}/month at ${formatInt(projection.runsPerWeek)} agent runs/week.\n`);
+    }
+    process.stdout.write(`Invoice savings require API mode; ChatGPT-login mode keeps native Codex auth.\n`);
+    return;
+  }
   if (!verdict.meaningful) {
     process.stdout.write(`\nCostLayers installed. This repo is too small for a meaningful savings claim.\n`);
   } else {
@@ -951,6 +1015,177 @@ function printSavingsSummary(report) {
   }
 }
 
+function moneyNumber(value) {
+  const text = String(value || "").replace(/[$,_\s]/g, "");
+  const number = Number(text);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+}
+
+function usageSpendFromObject(value) {
+  if (!value) return 0;
+  if (Array.isArray(value)) return value.reduce((sum, item) => sum + usageSpendFromObject(item), 0);
+  if (typeof value !== "object") return 0;
+  const directKeys = [
+    "cost_usd",
+    "total_cost_usd",
+    "billed_usd",
+    "spend_usd",
+    "amount_usd",
+    "total_usd",
+    "cost",
+    "total_cost",
+    "amount",
+    "usd"
+  ];
+  for (const key of directKeys) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      const amount = moneyNumber(value[key]);
+      if (amount > 0) return amount;
+    }
+  }
+  const nestedKeys = ["data", "rows", "items", "usage", "results", "records"];
+  let total = 0;
+  for (const key of nestedKeys) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) total += usageSpendFromObject(value[key]);
+  }
+  return total;
+}
+
+function parseCsvSpend(text) {
+  const lines = String(text || "").split(/\r?\n/).filter(Boolean);
+  if (lines.length < 2) return 0;
+  const headers = lines[0].split(",").map((item) => item.trim().replace(/^"|"$/g, "").toLowerCase());
+  const spendColumns = headers
+    .map((name, index) => ({ name, index }))
+    .filter(({ name }) => /^(cost_usd|total_cost_usd|billed_usd|spend_usd|amount_usd|total_usd|cost|amount|usd)$/.test(name));
+  if (!spendColumns.length) return 0;
+  let total = 0;
+  for (const line of lines.slice(1)) {
+    const cells = line.split(",");
+    const column = spendColumns.find(({ index }) => moneyNumber(cells[index]) > 0);
+    if (column) total += moneyNumber(cells[column.index]);
+  }
+  return total;
+}
+
+function loadSpendInput(args) {
+  const supplied = moneyNumber(args["monthly-spend"] || args.spend);
+  if (supplied > 0) return { monthlySpendUsd: supplied, source: "user-supplied monthly spend" };
+  const usageFile = args["usage-file"] ? path.resolve(String(args["usage-file"])) : "";
+  if (!usageFile) return { monthlySpendUsd: 0, source: "not supplied" };
+  if (!fs.existsSync(usageFile)) {
+    process.stderr.write(`Usage file not found: ${usageFile}\n`);
+    process.exit(2);
+  }
+  const text = fs.readFileSync(usageFile, "utf8");
+  let total = 0;
+  if (usageFile.toLowerCase().endsWith(".json")) {
+    try {
+      total = usageSpendFromObject(JSON.parse(text));
+    } catch (err) {
+      process.stderr.write(`Could not parse usage JSON: ${err.message}\n`);
+      process.exit(2);
+    }
+  } else {
+    total = parseCsvSpend(text);
+  }
+  return { monthlySpendUsd: total, source: `usage import: ${usageFile}` };
+}
+
+function buildAuditMarkdown(audit) {
+  return `# CostLayers AI Spend Audit
+
+Generated: ${audit.created_utc}
+Repo: ${audit.repo}
+
+## Executive Summary
+
+- AI spend analyzed: ${audit.spend_analyzed_display}
+- Candidate waste found: ${audit.waste_found_display}
+- Quality-safe savings available now: ${audit.safe_savings_display}
+- First-scan context reduction: ${audit.context_reduction_percent}%
+- Repeated-context tokens avoided/run: ${audit.tokens_avoided_per_run.toLocaleString()}
+
+## Evidence Labels
+
+- Safe estimate: local repo scan found repeated context that agents can avoid before broad exploration.
+- Verified invoice savings: requires API-mode traffic through CostLayers and provider cost rows.
+- Risky savings: not counted here. CostLayers should forward unchanged when a reduction boundary is unsafe.
+
+## Recommended Next Step
+
+${audit.next_step}
+
+## Largest Repeated Context Sources
+
+${audit.largest_files.map((row) => `- ${row.path}: ${row.tokens.toLocaleString()} tokens`).join("\n")}
+`;
+}
+
+function buildAuditReport(repo, report, args) {
+  const projection = savingsProjection(report);
+  const spendInput = loadSpendInput(args);
+  const spendAnalyzed = spendInput.monthlySpendUsd;
+  const contextSafeSavings = projection.monthlyUsd;
+  const contextRatio = Math.max(0, Math.min(1, Number(report.estimated_reduction_percent || 0) / 100));
+  const budgetWasteEstimate = spendAnalyzed > 0 ? spendAnalyzed * Math.min(0.25, contextRatio * 0.2) : 0;
+  const wasteFound = Math.max(contextSafeSavings, budgetWasteEstimate);
+  const safeSavings = contextSafeSavings;
+  return {
+    created_utc: new Date().toISOString(),
+    repo: path.basename(repo),
+    spend_source: spendInput.source,
+    monthly_spend_analyzed_usd: Number(spendAnalyzed.toFixed(6)),
+    waste_found_usd_per_month: Number(wasteFound.toFixed(6)),
+    quality_safe_savings_usd_per_month: Number(safeSavings.toFixed(6)),
+    context_reduction_percent: Number(report.estimated_reduction_percent || 0),
+    tokens_avoided_per_run: Number(report.tokens_avoided_per_repeated_task || 0),
+    source_tokens_indexed: Number(report.source_tokens_indexed || 0),
+    context_pack_tokens: Number(report.context_pack_tokens || 0),
+    largest_files: report.largest_files || [],
+    spend_analyzed_display: spendAnalyzed > 0 ? `${formatUsd(spendAnalyzed)}/month (${spendInput.source})` : "not supplied; using repo-scan savings only",
+    waste_found_display: `${formatUsd(wasteFound)}/month candidate estimate`,
+    safe_savings_display: `${formatUsd(safeSavings)}/month from local context scan`,
+    next_step: spendAnalyzed > 0
+      ? "Enable API invoice mode on one controlled coding-agent workflow so CostLayers can turn the audit estimate into verified provider-dollar savings."
+      : "Rerun with --monthly-spend <usd> or --usage-file <path>, then enable API invoice mode on one controlled workflow."
+  };
+}
+
+function writeAuditReport(outDir, repo, report, args) {
+  const auditReport = buildAuditReport(repo, report, args);
+  fs.writeFileSync(path.join(outDir, "ai-spend-audit.json"), JSON.stringify(auditReport, null, 2) + "\n", "utf8");
+  fs.writeFileSync(path.join(outDir, "ai-spend-audit.md"), buildAuditMarkdown(auditReport), "utf8");
+  return auditReport;
+}
+
+async function audit(repo, args) {
+  process.stdout.write(`Running CostLayers AI spend audit for: ${repo}\n`);
+  const precomputed = scanToFiles(repo, args);
+  const { outDir, report } = precomputed;
+  const auditReport = writeAuditReport(outDir, repo, report, args);
+  process.stdout.write(`\nCostLayers AI Spend Audit\n`);
+  process.stdout.write(`\nYou found repeated context waste\n`);
+  process.stdout.write(`  AI spend analyzed: ${auditReport.spend_analyzed_display}\n`);
+  process.stdout.write(`  Candidate waste found: ${auditReport.waste_found_display}\n`);
+  process.stdout.write(`  Quality-safe savings available now: ${auditReport.safe_savings_display}\n`);
+  process.stdout.write(`  Context reduction: ${auditReport.context_reduction_percent}%\n`);
+  process.stdout.write(`  Tokens avoided per agent run: ${formatInt(auditReport.tokens_avoided_per_run)}\n`);
+  process.stdout.write(`  Audit report: ${path.join(outDir, "ai-spend-audit.md")}\n`);
+  process.stdout.write(`\nView this result any time:\n`);
+  process.stdout.write(`  npx -y ${INSTALL_SPEC} dashboard\n`);
+  process.stdout.write(`\nNext best step:\n`);
+  process.stdout.write(`  ${auditReport.next_step}\n`);
+  process.stdout.write(`\nHosted dashboard, optional:\n`);
+  process.stdout.write(`  npx -y ${INSTALL_SPEC} signup --email you@example.com\n`);
+  await trackEvent(repo, args, "ai_spend_audit", {
+    monthly_spend_analyzed_usd: auditReport.monthly_spend_analyzed_usd,
+    waste_found_usd_per_month: auditReport.waste_found_usd_per_month,
+    quality_safe_savings_usd_per_month: auditReport.quality_safe_savings_usd_per_month,
+    context_tokens_avoided_per_task: auditReport.tokens_avoided_per_run
+  });
+}
+
 function codexHomeDir() {
   return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
 }
@@ -1154,7 +1389,10 @@ async function signup(repo, args) {
   process.stdout.write(`Dashboard: ${dashboardUrlFromConnection(connection)}\n`);
   process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
   process.stdout.write(`Plan: free beta\n`);
-  process.stdout.write(`Next: costlayers gateway start --mode reduce --provider-url https://api.openai.com\n`);
+  process.stdout.write(`\nNext:\n`);
+  process.stdout.write(`  View dashboard: npx -y ${INSTALL_SPEC} dashboard\n`);
+  process.stdout.write(`  Run Codex with usage-stretch metering: npx -y ${INSTALL_SPEC} codex --email ${connection.email || "you@example.com"} --chatgpt\n`);
+  process.stdout.write(`  Prove API invoice savings: export OPENAI_API_KEY=sk-proj-... && npx -y ${INSTALL_SPEC} test --email ${connection.email || "you@example.com"}\n`);
 }
 
 async function codexProfile(repo, args) {
@@ -1327,24 +1565,28 @@ async function runAgent(repo, args, argv, options = {}) {
   if (connection && connection.engine_url) {
     try {
       plan = await fetchEnginePlan(connection, repo, pack, report);
-      process.stdout.write(`Fetched CostLayers engine plan\n`);
+      if (!options.compactOutput) process.stdout.write(`Fetched CostLayers engine plan\n`);
     } catch (err) {
       process.stderr.write(`Engine unavailable; falling back to local plan: ${err.message}\n`);
     }
   }
   writeRuntimePrompt(outDir, plan);
-  process.stdout.write(`Runtime plan: ${path.join(outDir, "runtime-plan.md")}\n`);
+  if (!options.compactOutput) process.stdout.write(`Runtime plan: ${path.join(outDir, "runtime-plan.md")}\n`);
   let commandToRun = command;
   if (connection && connection.engine_url && isCodexCommand(command)) {
     assertCodexProxyApiKey(args);
     const profilePath = writeCodexProfile(connection, args);
     commandToRun = withCostLayersCodexProfile(command);
     await trackEvent(repo, args, "codex_run", { profile_mode: codexProxyEnabled(args) ? "api" : "chatgpt" }, connection);
-    process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
-    process.stdout.write(`Codex metering enabled: ${commandToRun.join(" ")}\n`);
-    process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
-    process.stdout.write(`Savings dashboard: ${dashboardUrlFromConnection(connection)}\n`);
-    process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
+    if (options.compactOutput) {
+      process.stdout.write(`Launching Codex with CostLayers profile: ${commandToRun.join(" ")}\n`);
+    } else {
+      process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
+      process.stdout.write(`Codex metering enabled: ${commandToRun.join(" ")}\n`);
+      process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
+      process.stdout.write(`Savings dashboard: ${dashboardUrlFromConnection(connection)}\n`);
+      process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
+    }
   }
   const env = {
     ...process.env,
@@ -1417,8 +1659,19 @@ async function gateway(repo, args) {
 }
 
 async function dashboard(repo, args) {
-  const connection = loadConnection(repo, args);
-  const status = await postJson(`${connection.engine_url}/v1/me`, {}, connection.api_key);
+  const connection = loadStoredConnection(repo);
+  if (!connection || !connection.engine_url || !connection.api_key) {
+    if (printLocalDashboard(repo)) return;
+    process.exit(2);
+  }
+  let status;
+  try {
+    status = await postJson(`${connection.engine_url}/v1/me`, {}, connection.api_key);
+  } catch (err) {
+    process.stderr.write(`Hosted dashboard unavailable: ${err.message}\n\n`);
+    if (printLocalDashboard(repo)) return;
+    process.exit(1);
+  }
   await trackEvent(repo, args, "dashboard_open", {}, connection);
   const dashboardUrl = (connection.gateway_url || defaultPublicGatewayUrl(connection.engine_url, connection.api_key)).replace("/gateway/", "/engine/dashboard/");
   process.stdout.write(`CostLayers Dashboard\n`);
@@ -1440,11 +1693,11 @@ async function codexShortcut(repo, args, argv) {
   const codexTail = codexArgsAfterDash(argv);
   const command = codexTail.length > 0 ? codexTail : ["codex"];
   const commandToRun = isCodexCommand(command) ? command : ["codex", ...command];
-  const nextArgs = withAutoCodexMode(args);
+  const nextArgs = withAutoCodexMode({ ...args, "ux-compact": true });
   if (codexProxyEnabled(nextArgs)) {
     process.stdout.write(`CostLayers Codex: API invoice mode explicitly enabled from ${codexProxyApiKeyEnv(nextArgs)}.\n`);
   } else {
-    process.stdout.write(`CostLayers Codex: ChatGPT usage-stretch mode. Pass --api to route API-billed provider calls for invoice savings.\n`);
+    process.stdout.write(`CostLayers Codex: ChatGPT usage-stretch mode. Native Codex auth stays unchanged.\n`);
   }
   return start(repo, nextArgs, ["start", "--", ...commandToRun]);
 }
@@ -1485,16 +1738,18 @@ async function savingsTest(repo, args) {
 async function start(repo, args, argv, options = {}) {
   const dash = argv.indexOf("--");
   const command = dash >= 0 ? argv.slice(dash + 1) : [];
+  const compactOutput = Boolean(args["ux-compact"]);
   const codexTelemetryRun = command.length > 0 && isCodexCommand(command) && !codexProxyEnabled(args);
   if (command.length > 0 && isCodexCommand(command)) assertCodexProxyApiKey(args);
   init(repo, { suppressNext: true });
   process.stdout.write(`Scanning repo: ${repo}\n`);
   const precomputed = scanToFiles(repo, args);
   const { outDir, pack, report } = precomputed;
+  writeAuditReport(outDir, repo, report, args);
   process.stdout.write(`CostLayers scan complete\n`);
   if (precomputed.localCacheHit) process.stdout.write(`Local exact cache hit: source hashes unchanged, reused CostLayers artifacts\n`);
-  process.stdout.write(`Report: ${path.join(outDir, "savings-report.md")}\n`);
-  printSavingsSummary(report);
+  if (!compactOutput) process.stdout.write(`Report: ${path.join(outDir, "savings-report.md")}\n`);
+  printSavingsSummary(report, { compact: compactOutput });
   const connection = await ensureConnection(repo, args);
   await trackEvent(repo, args, "cli_start", {
     files_indexed: report.files_indexed,
@@ -1507,11 +1762,15 @@ async function start(repo, args, argv, options = {}) {
   } catch (err) {
     process.stderr.write(`Dashboard sync delayed; local report is still available: ${err.message}\n`);
   }
-  process.stdout.write(`CostLayers connection ready\n`);
+  if (!compactOutput) process.stdout.write(`CostLayers connection ready\n`);
   let gatewayBaseUrl = connection.gateway_url || defaultPublicGatewayUrl(connection.engine_url, connection.api_key);
   if (codexTelemetryRun) {
-    process.stdout.write(`ChatGPT-login Codex mode: native Codex provider preserved; model calls are not routed through CostLayers.\n`);
-    process.stdout.write(`What users get: repo context discipline and a usage-stretch meter. This does not reduce a flat ChatGPT subscription invoice.\n`);
+    if (compactOutput) {
+      process.stdout.write(`Mode: ChatGPT-login Codex. Model calls are not routed; CostLayers adds repo context discipline and usage-stretch metering.\n`);
+    } else {
+      process.stdout.write(`ChatGPT-login Codex mode: native Codex provider preserved; model calls are not routed through CostLayers.\n`);
+      process.stdout.write(`What users get: repo context discipline and a usage-stretch meter. This does not reduce a flat ChatGPT subscription invoice.\n`);
+    }
   } else {
     const providerUrl = typeof args["provider-url"] === "string" ? args["provider-url"] : "https://api.openai.com";
     const payload = {
@@ -1537,13 +1796,15 @@ async function start(repo, args, argv, options = {}) {
     }
   }
   process.stdout.write(`Dashboard: ${dashboardUrlFromConnection(connection)}\n`);
-  process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
+  if (!compactOutput) process.stdout.write(`Keep this dashboard URL private; it contains your keyed CostLayers path.\n`);
   process.stdout.write(`Plan: free beta\n`);
   const profilePath = writeCodexProfile(connection, args);
-  process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
-  process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
+  if (!compactOutput) {
+    process.stdout.write(`CostLayers Codex profile: ${profilePath}\n`);
+    process.stdout.write(`Codex profile mode: ${codexProxyEnabled(args) ? "API invoice mode" : "ChatGPT usage-stretch mode; native Codex model path preserved"}\n`);
+  }
   if (command.length > 0) {
-    return runAgent(repo, args, argv, { skipSetup: true, precomputed, returnStatus: options.returnStatus });
+    return runAgent(repo, args, argv, { skipSetup: true, precomputed, returnStatus: options.returnStatus, compactOutput });
   }
   process.stdout.write(`\nReady.\n`);
   process.stdout.write(`  Run Codex: codex --profile costlayers\n`);
@@ -1581,8 +1842,9 @@ function main() {
   const cmd = args._[0];
   if (!cmd || args.help || args.h) usage(0);
   const repo = path.resolve(String(args.repo || process.cwd()));
-  if (["init", "scan", "start", "run", "codex-profile", "codex", "test"].includes(cmd)) guardRepoRoot(repo, args);
+  if (["init", "scan", "audit", "start", "run", "codex-profile", "codex", "test"].includes(cmd)) guardRepoRoot(repo, args);
   if (cmd === "doctor") return doctor();
+  if (cmd === "audit") return audit(repo, args);
   if (cmd === "codex") return codexShortcut(repo, args, rawArgv);
   if (cmd === "test") return savingsTest(repo, args);
   if (cmd === "init") return init(repo);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "costlayers",
-  "version": "0.8.20",
+  "version": "0.8.27",
   "description": "CostLayers cost control for AI coding agents. Build compact repo context packs, gateway reports, and savings dashboards.",
   "bin": {
     "agentspend": "bin/agentspend.js",