@hasna/economy 0.2.41 → 0.2.43

package/dist/cli/index.js

@@ -528,6 +528,7 @@ __export(exports_database, {
   setIngestState: () => setIngestState,
   seedModelPricing: () => seedModelPricing,
   rollupSession: () => rollupSession,
+  queryZeroCostTokenizedModels: () => queryZeroCostTokenizedModels,
   queryUsageSnapshots: () => queryUsageSnapshots,
   queryTopSessions: () => queryTopSessions,
   querySummary: () => querySummary,
@@ -623,6 +624,32 @@ function getDbPath() {
     return process.env["ECONOMY_DB"];
   return join(getDataDir(), "economy.db");
 }
+function isSqliteBusyError(error) {
+  const candidate = error;
+  const code = typeof candidate.code === "string" ? candidate.code : "";
+  const message = typeof candidate.message === "string" ? candidate.message : String(error);
+  return code === "SQLITE_BUSY" || code === "SQLITE_BUSY_RECOVERY" || /database is locked|SQLITE_BUSY/i.test(message);
+}
+function retryDelayMs(attempt) {
+  return Math.min(1000, 50 * 2 ** attempt);
+}
+function withSqliteBusyRetry(operation, context) {
+  const maxAttempts = 8;
+  let lastError;
+  for (let attempt = 0;attempt < maxAttempts; attempt++) {
+    try {
+      return operation();
+    } catch (error) {
+      if (!isSqliteBusyError(error))
+        throw error;
+      lastError = error;
+      if (attempt === maxAttempts - 1)
+        break;
+      Bun.sleepSync(retryDelayMs(attempt));
+    }
+  }
+  throw new Error(`SQLite database is locked after ${maxAttempts} attempts while ${context}. Another economy sync/merge may be recovering the database; retry shortly.`, { cause: lastError });
+}
 function openDatabase(dbPath, skipSeed = false) {
   const path = dbPath ?? getDbPath();
   if (path !== ":memory:") {
@@ -630,11 +657,21 @@ function openDatabase(dbPath, skipSeed = false) {
     if (dir && !existsSync(dir))
       mkdirSync(dir, { recursive: true });
   }
-  const db = new Database(path);
-  db.exec("PRAGMA journal_mode = WAL");
-  db.exec("PRAGMA busy_timeout = 5000");
-  db.exec("PRAGMA foreign_keys = ON");
-  initSchema(db);
+  const db = withSqliteBusyRetry(() => {
+    const opened = new Database(path);
+    try {
+      opened.exec("PRAGMA busy_timeout = 10000");
+      opened.exec("PRAGMA journal_mode = WAL");
+      opened.exec("PRAGMA foreign_keys = ON");
+      initSchema(opened);
+      return opened;
+    } catch (error) {
+      try {
+        opened.close();
+      } catch {}
+      throw error;
+    }
+  }, `opening ${path}`);
   if (!skipSeed) {
     Promise.resolve().then(() => (init_pricing(), exports_pricing)).then(({ ensurePricingSeeded: ensurePricingSeeded2 }) => ensurePricingSeeded2(db)).catch(() => {});
   }
@@ -996,36 +1033,50 @@ function querySessions(db, filter = {}) {
     SELECT * FROM sessions ${where} ORDER BY started_at DESC LIMIT ? OFFSET ?
   `).all(...params, limit, offset);
 }
-function queryTopSessions(db, n = 10, agent) {
+function queryTopSessions(db, n = 10, agent, since) {
+  const conditions = [];
+  const params = [];
   if (agent) {
-    return db.prepare(`SELECT * FROM sessions WHERE agent = ? ORDER BY total_cost_usd DESC LIMIT ?`).all(agent, n);
+    conditions.push("agent = ?");
+    params.push(agent);
+  }
+  if (since) {
+    conditions.push("started_at >= ?");
+    params.push(since);
   }
-  return db.prepare(`SELECT * FROM sessions ORDER BY total_cost_usd DESC LIMIT ?`).all(n);
+  const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+  return db.prepare(`SELECT * FROM sessions ${where} ORDER BY total_cost_usd DESC LIMIT ?`).all(...params, n);
 }
-function querySummary(db, period, machine, allMachines = false) {
+function querySummary(db, period, machine, allMachines = false, agent) {
   const rWhere = periodWhere(period);
   const sWhere = sessionPeriodWhere(period);
-  const machineClause = !allMachines && machine ? ` AND machine_id = '${machine.replace(/'/g, "''")}'` : "";
+  const machineClause = !allMachines && machine ? " AND machine_id = ?" : "";
+  const agentClause = agent ? " AND agent = ?" : "";
+  const params = [];
+  if (!allMachines && machine)
+    params.push(machine);
+  if (agent)
+    params.push(agent);
   const r = db.prepare(`
     SELECT COALESCE(SUM(cost_usd), 0) as total_usd,
            COUNT(*) as requests,
            COALESCE(SUM(input_tokens + output_tokens + cache_read_tokens + cache_create_tokens), 0) as tokens
-    FROM requests WHERE ${rWhere}${machineClause}
-  `).get();
+    FROM requests WHERE ${rWhere}${machineClause}${agentClause}
+  `).get(...params);
   const codexTotals = db.prepare(`
     SELECT COALESCE(SUM(total_cost_usd), 0) as cost_usd,
            COALESCE(SUM(total_tokens), 0) as tokens,
            COALESCE(SUM(request_count), 0) as requests,
            COUNT(*) as sessions
     FROM sessions
-    WHERE ${sWhere}${machineClause}
+    WHERE ${sWhere}${machineClause}${agentClause}
     AND id NOT IN (SELECT DISTINCT session_id FROM requests)
-  `).get();
+  `).get(...params);
   const requestSessionCount = db.prepare(`
     SELECT COUNT(DISTINCT session_id) as sessions
     FROM requests
-    WHERE ${rWhere}${machineClause}
-  `).get();
+    WHERE ${rWhere}${machineClause}${agentClause}
+  `).get(...params);
   return {
     total_usd: r.total_usd + codexTotals.cost_usd,
     requests: r.requests + codexTotals.requests,
@@ -1034,6 +1085,21 @@ function querySummary(db, period, machine, allMachines = false) {
     period
   };
 }
+function queryZeroCostTokenizedModels(db, limit = 10) {
+  return db.prepare(`
+    SELECT agent,
+           model,
+           COUNT(*) as requests,
+           COALESCE(SUM(input_tokens + output_tokens + cache_read_tokens + cache_create_tokens), 0) as total_tokens,
+           MAX(timestamp) as last_seen
+    FROM requests
+    WHERE cost_usd = 0
+      AND (input_tokens > 0 OR output_tokens > 0 OR cache_read_tokens > 0 OR cache_create_tokens > 0)
+    GROUP BY agent, model
+    ORDER BY requests DESC, total_tokens DESC
+    LIMIT ?
+  `).all(limit);
+}
 function queryModelBreakdown(db) {
   return db.prepare(`
     SELECT model, agent,
@@ -4270,15 +4336,15 @@ __export(exports_config, {
   loadConfig: () => loadConfig2,
   getConfigValue: () => getConfigValue
 });
-import { existsSync as existsSync13, readFileSync as readFileSync11, writeFileSync as writeFileSync2, mkdirSync as mkdirSync3 } from "fs";
-import { dirname as dirname2, join as join12 } from "path";
+import { existsSync as existsSync14, readFileSync as readFileSync11, writeFileSync as writeFileSync3, mkdirSync as mkdirSync4 } from "fs";
+import { dirname as dirname2, join as join13 } from "path";
 function getConfigPath() {
-  return process.env["HASNA_ECONOMY_CONFIG_PATH"] ?? join12(getDataDir(), "config.json");
+  return process.env["HASNA_ECONOMY_CONFIG_PATH"] ?? join13(getDataDir(), "config.json");
 }
 function loadConfig2() {
   try {
     const configPath = getConfigPath();
-    if (existsSync13(configPath)) {
+    if (existsSync14(configPath)) {
       const raw = readFileSync11(configPath, "utf-8");
       return { ...DEFAULTS, ...JSON.parse(raw) };
     }
@@ -4288,9 +4354,9 @@ function loadConfig2() {
 function saveConfig2(config) {
   const configPath = getConfigPath();
   const dir = dirname2(configPath);
-  if (!existsSync13(dir))
-    mkdirSync3(dir, { recursive: true });
-  writeFileSync2(configPath, JSON.stringify(config, null, 2) + `
+  if (!existsSync14(dir))
+    mkdirSync4(dir, { recursive: true });
+  writeFileSync3(configPath, JSON.stringify(config, null, 2) + `
 `);
 }
 function getConfigValue(key) {
@@ -4432,7 +4498,7 @@ var init_webhooks = __esm(() => {
 });
 
 // src/lib/watch-paths.ts
-import { existsSync as existsSync14 } from "fs";
+import { existsSync as existsSync15 } from "fs";
 function getWatchPaths() {
   const p = agentPaths();
   const candidates = [
@@ -4445,7 +4511,7 @@ function getWatchPaths() {
     p.piSessions,
     p.hermesDir
   ];
-  return candidates.filter((path) => existsSync14(path));
+  return candidates.filter((path) => existsSync15(path));
 }
 var init_watch_paths = __esm(() => {
   init_paths();
@@ -4607,16 +4673,275 @@ var init_watch = __esm(() => {
   init_notification();
 });
 
+// src/db/sync-pg.ts
+import { Worker, MessageChannel, receiveMessageOnPort } from "worker_threads";
+import { fileURLToPath } from "url";
+import { dirname as dirname3, join as join14 } from "path";
+import { existsSync as existsSync16 } from "fs";
+import { translateSql, translateParams } from "@hasna/cloud";
+function translateSqliteDates(sql) {
+  let s = sql;
+  const isoDate = (expr) => `to_char(${expr}, 'YYYY-MM-DD')`;
+  s = s.replace(/DATE\('now',\s*'weekday 0',\s*'-7 days'\)/gi, isoDate("(date_trunc('week', now() + interval '1 day') - interval '1 day')"));
+  s = s.replace(/DATE\('now',\s*'start of month'\)/gi, isoDate("date_trunc('month', now())"));
+  s = s.replace(/DATE\('now',\s*'start of year'\)/gi, isoDate("date_trunc('year', now())"));
+  s = s.replace(/DATE\('now',\s*'(-?\d+)\s*days?'\)/gi, (_m, n) => isoDate(`now() + interval '${n} days'`));
+  s = s.replace(/DATE\('now',\s*(\$\d+)\s*\|\|\s*' days'\)/gi, (_m, p) => isoDate(`now() + ((${p}) || ' days')::interval`));
+  s = s.replace(/DATETIME\('now',\s*(\$\d+)\)/gi, (_m, p) => `(now() + (${p})::interval)`);
+  s = s.replace(/DATETIME\('now',\s*'([^']+)'\)/gi, (_m, lit) => `(now() + interval '${lit}')`);
+  const strftimeMap = { "%H": "HH24", "%Y": "YYYY", "%m": "MM", "%d": "DD", "%M": "MI", "%S": "SS" };
+  s = s.replace(/STRFTIME\('([^']+)',\s*([A-Za-z_][A-Za-z0-9_]*)\)/gi, (_m, fmt4, col) => {
+    const pgFmt = Object.entries(strftimeMap).reduce((acc, [k, v]) => acc.split(k).join(v), fmt4);
+    return `to_char(CAST("${col}" AS timestamptz), '${pgFmt}')`;
+  });
+  s = s.replace(/\bDATE\('now'\)/gi, isoDate("now()"));
+  s = s.replace(/\bDATETIME\('now'\)/gi, "now()");
+  s = s.replace(/\bDATETIME\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)/gi, (_m, col) => `CAST("${col}" AS timestamptz)`);
+  s = s.replace(/\bDATE\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)/gi, (_m, col) => `substr("${col}", 1, 10)`);
+  return s;
+}
+function resolveWorkerPath() {
+  const here = dirname3(fileURLToPath(import.meta.url));
+  const candidates = [
+    join14(here, "pg-sync-worker.ts"),
+    join14(here, "pg-sync-worker.js"),
+    join14(here, "..", "db", "pg-sync-worker.js")
+  ];
+  for (const candidate of candidates)
+    if (existsSync16(candidate))
+      return candidate;
+  return candidates[0];
+}
+
+class SyncPgAdapter {
+  worker;
+  port;
+  counter = 0;
+  constructor(dsn) {
+    const workerPath = resolveWorkerPath();
+    this.worker = new Worker(workerPath, { workerData: { dsn } });
+    this.worker.on("error", (err) => console.error(JSON.stringify({ evt: "pg_worker_error", message: err.message })));
+    const channel = new MessageChannel;
+    this.port = channel.port1;
+    this.worker.postMessage({ type: "init", port: channel.port2 }, [channel.port2]);
+  }
+  query(sql, params) {
+    const pgSql = translateSqliteDates(translateSql(sql, "pg"));
+    const pgParams = translateParams(params);
+    const id = ++this.counter;
+    const signal = new SharedArrayBuffer(4);
+    const sig = new Int32Array(signal);
+    Atomics.store(sig, 0, 0);
+    this.worker.postMessage({ id, sql: pgSql, params: pgParams, signal });
+    Atomics.wait(sig, 0, 0);
+    let received = receiveMessageOnPort(this.port);
+    for (let attempt = 0;!received && attempt < 1e6; attempt++)
+      received = receiveMessageOnPort(this.port);
+    if (!received)
+      throw new Error("SyncPgAdapter: no reply from worker");
+    const reply = received.message;
+    if (!reply.ok)
+      throw new Error(reply.error);
+    return { rows: reply.rows, rowCount: reply.rowCount };
+  }
+  run(sql, ...params) {
+    const result = this.query(sql, params);
+    return { changes: result.rowCount, lastInsertRowid: result.rows?.[0]?.["id"] ?? 0 };
+  }
+  get(sql, ...params) {
+    return this.query(sql, params).rows[0] ?? null;
+  }
+  all(sql, ...params) {
+    return this.query(sql, params).rows;
+  }
+  exec(sql) {
+    this.query(sql, []);
+  }
+  prepare(sql) {
+    const self = this;
+    return {
+      run: (...params) => self.run(sql, ...params),
+      get: (...params) => self.get(sql, ...params),
+      all: (...params) => self.all(sql, ...params),
+      finalize: () => {}
+    };
+  }
+  transaction(fn) {
+    return fn();
+  }
+  close() {
+    this.worker.terminate();
+  }
+}
+var init_sync_pg = () => {};
+
+// src/db/cloud.ts
+import pg from "pg";
+function getCloudDatabaseUrl2() {
+  return process.env["HASNA_ECONOMY_DATABASE_URL"]?.trim() || process.env["ECONOMY_DATABASE_URL"]?.trim() || process.env["DATABASE_URL"]?.trim() || undefined;
+}
+function isCloudMode() {
+  const mode = process.env["HASNA_ECONOMY_STORAGE_MODE"]?.trim().toLowerCase();
+  if (mode === "cloud")
+    return true;
+  if (mode === "local")
+    return false;
+  return Boolean(getCloudDatabaseUrl2());
+}
+function resolveSigningSecret() {
+  return process.env["HASNA_ECONOMY_API_SIGNING_KEY"]?.trim() || process.env["HASNA_API_SIGNING_KEY"]?.trim() || process.env["API_KEY_SIGNING_SECRET"]?.trim() || undefined;
+}
+function openCloudDatabase(dsn = getCloudDatabaseUrl2()) {
+  if (!dsn) {
+    throw new Error("economy cloud mode requires a Postgres DSN: set HASNA_ECONOMY_DATABASE_URL (or ECONOMY_DATABASE_URL / DATABASE_URL)");
+  }
+  return new SyncPgAdapter(dsn);
+}
+function createCloudPool(dsn = getCloudDatabaseUrl2()) {
+  if (!dsn)
+    throw new Error("economy cloud mode requires a Postgres DSN (HASNA_ECONOMY_DATABASE_URL)");
+  const ssl = dsn.includes("sslmode=require") || dsn.includes("ssl=true") ? { rejectUnauthorized: false } : undefined;
+  const pool = new pg.Pool({ connectionString: dsn, ssl, max: Number(process.env["ECONOMY_PG_POOL_MAX"] ?? "5"), connectionTimeoutMillis: 1e4 });
+  pool.on("error", (err) => {
+    console.error(JSON.stringify({ evt: "pg_pool_error", message: err.message }));
+  });
+  return pool;
+}
+function authClientFromPool(pool) {
+  return {
+    async many(sql, params = []) {
+      const res = await pool.query(sql, params);
+      return res.rows;
+    },
+    async get(sql, params = []) {
+      const res = await pool.query(sql, params);
+      return res.rows[0] ?? null;
+    },
+    async execute(sql, params = []) {
+      await pool.query(sql, params);
+    }
+  };
+}
+var init_cloud = __esm(() => {
+  init_sync_pg();
+  init_pg_migrations();
+});
+
+// src/openapi.ts
+var openApiSpec;
+var init_openapi = __esm(() => {
+  openApiSpec = {
+    openapi: "3.0.3",
+    info: {
+      title: "@hasna/economy self-hosted API",
+      version: "0.0.0",
+      description: "AI coding cost tracker \u2014 self-hosted control plane. Cloud mode is PURE REMOTE per Amendment A1: the serve process reads/writes the shared RDS Postgres directly with API-key auth via @hasna/contracts. All /v1 routes require a valid `economy:*` scoped API key (x-api-key or Authorization: Bearer). The foundation probes /health, /ready, /version are open."
+    },
+    servers: [{ url: "https://economy.hasna.xyz", description: "prod" }, { url: "http://localhost:3456", description: "local" }],
+    security: [{ apiKey: [] }, { bearer: [] }],
+    components: {
+      securitySchemes: {
+        apiKey: { type: "apiKey", in: "header", name: "x-api-key" },
+        bearer: { type: "http", scheme: "bearer" }
+      },
+      schemas: {
+        Envelope: { type: "object", properties: { data: {}, meta: { type: "object", additionalProperties: true } }, required: ["data"] },
+        Foundation: { type: "object", properties: { status: { type: "string" }, version: { type: "string" }, mode: { type: "string" }, service: { type: "string" } }, required: ["status", "version", "mode"] },
+        Error: { type: "object", properties: { error: { type: "string" }, message: { type: "string" } }, required: ["error"] },
+        MutationOk: { type: "object", properties: { ok: { type: "boolean" } } },
+        CostSummary: { type: "object", properties: { total_cost_usd: { type: "number" }, total_tokens: { type: "number" }, request_count: { type: "number" }, session_count: { type: "number" }, period: { type: "string" } }, additionalProperties: true },
+        Session: { type: "object", properties: { id: { type: "string" }, agent: { type: "string" }, project_path: { type: "string" }, project_name: { type: "string" }, started_at: { type: "string" }, ended_at: { type: "string", nullable: true }, total_cost_usd: { type: "number" }, total_tokens: { type: "number" }, request_count: { type: "number" } }, additionalProperties: true },
+        ModelBreakdown: { type: "object", additionalProperties: true },
+        ProjectBreakdown: { type: "object", additionalProperties: true },
+        AgentBreakdown: { type: "object", additionalProperties: true },
+        AccountBreakdown: { type: "object", additionalProperties: true },
+        DailyPoint: { type: "object", additionalProperties: true },
+        BudgetStatus: { type: "object", properties: { id: { type: "string" }, limit_usd: { type: "number" }, period: { type: "string" }, spent_usd: { type: "number" } }, additionalProperties: true },
+        CreateBudgetInput: { type: "object", properties: { limit_usd: { type: "number" }, alert_at_percent: { type: "number" }, period: { type: "string", enum: ["daily", "weekly", "monthly", "day", "week", "month"] }, project_path: { type: "string", nullable: true }, agent: { type: "string", nullable: true } }, required: ["limit_usd"] },
+        GoalStatus: { type: "object", additionalProperties: true },
+        CreateGoalInput: { type: "object", properties: { period: { type: "string", enum: ["day", "week", "month", "year"] }, limit_usd: { type: "number" }, project_path: { type: "string", nullable: true }, agent: { type: "string", nullable: true } }, required: ["limit_usd"] },
+        ModelPricing: { type: "object", additionalProperties: true },
+        CreatePricingInput: { type: "object", properties: { model: { type: "string" }, input_per_1m: { type: "number" }, output_per_1m: { type: "number" } }, required: ["model", "input_per_1m", "output_per_1m"] },
+        Subscription: { type: "object", additionalProperties: true },
+        CreateSubscriptionInput: { type: "object", properties: { provider: { type: "string" }, plan: { type: "string" }, monthly_fee_usd: { type: "number" }, included_usage_usd: { type: "number" }, agent: { type: "string", nullable: true } }, required: ["provider", "plan"] },
+        Project: { type: "object", additionalProperties: true },
+        CreateProjectInput: { type: "object", properties: { path: { type: "string" }, name: { type: "string" }, description: { type: "string" }, tags: { type: "array", items: { type: "string" } } }, required: ["path"] },
+        MachineInfo: { type: "object", additionalProperties: true },
+        BillingSummary: { type: "object", additionalProperties: true }
+      }
+    },
+    paths: {
+      "/health": { get: { operationId: "health", summary: "Liveness probe", security: [], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Foundation" } } } } } } },
+      "/ready": { get: { operationId: "ready", summary: "Readiness probe (storage reachable + migrated)", security: [], responses: { "200": { description: "ready", content: { "application/json": { schema: { $ref: "#/components/schemas/Foundation" } } } }, "503": { description: "not ready", content: { "application/json": { schema: { $ref: "#/components/schemas/Foundation" } } } } } } },
+      "/version": { get: { operationId: "version", summary: "Version probe", security: [], responses: { "200": { description: "version", content: { "application/json": { schema: { $ref: "#/components/schemas/Foundation" } } } } } } },
+      "/v1/summary": { get: { operationId: "getSummary", summary: "Cost summary for a period", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/CostSummary" } } } } } } } } },
+      "/v1/sessions": { get: { operationId: "listSessions", summary: "List sessions", parameters: [{ name: "agent", in: "query", schema: { type: "string" } }, { name: "project", in: "query", schema: { type: "string" } }, { name: "search", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }, { name: "account", in: "query", schema: { type: "string" } }, { name: "limit", in: "query", schema: { type: "integer" } }, { name: "offset", in: "query", schema: { type: "integer" } }, { name: "since", in: "query", schema: { type: "string" } }, { name: "fields", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/Session" } } } } } } } } } },
+      "/v1/sessions/{id}/requests": { get: { operationId: "getSessionRequests", summary: "Requests for a session", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } }, "404": { description: "not found", content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } } } },
+      "/v1/top": { get: { operationId: "topSessions", summary: "Top sessions by cost", parameters: [{ name: "n", in: "query", schema: { type: "integer" } }, { name: "agent", in: "query", schema: { type: "string" } }, { name: "since", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/Session" } } } } } } } } } },
+      "/v1/models": { get: { operationId: "modelBreakdown", summary: "Cost by model", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/ModelBreakdown" } } } } } } } } } },
+      "/v1/projects": { get: { operationId: "projectBreakdown", summary: "Cost by project", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/ProjectBreakdown" } } } } } } } } } },
+      "/v1/accounts": { get: { operationId: "accountBreakdown", summary: "Cost by account", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/AccountBreakdown" } } } } } } } } } },
+      "/v1/breakdown": { get: { operationId: "breakdown", summary: "Cost breakdown by dimension", parameters: [{ name: "by", in: "query", schema: { type: "string", enum: ["model", "project", "agent", "account"] } }, { name: "period", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+      "/v1/daily": { get: { operationId: "daily", summary: "Daily cost points", parameters: [{ name: "days", in: "query", schema: { type: "integer" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/DailyPoint" } } } } } } } } } },
+      "/v1/hourly": { get: { operationId: "hourly", summary: "Hourly cost points", parameters: [{ name: "hours", in: "query", schema: { type: "integer" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+      "/v1/machines": { get: { operationId: "listMachines", summary: "Known machines", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/MachineInfo" } } } } } } } } } },
+      "/v1/fleet": { get: { operationId: "fleet", summary: "Fleet summary", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "machine", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+      "/v1/billing": { get: { operationId: "billing", summary: "Provider billing summary", parameters: [{ name: "period", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/BillingSummary" } } } } } } } } },
+      "/v1/billing/diff": { get: { operationId: "billingDiff", summary: "Billing vs tracked diff", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "threshold", in: "query", schema: { type: "number" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+      "/v1/usage": { get: { operationId: "usage", summary: "Usage snapshots + summary", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "agent", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+      "/v1/savings": { get: { operationId: "savings", summary: "Savings summary", parameters: [{ name: "period", in: "query", schema: { type: "string" } }, { name: "agent", in: "query", schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } },
+      "/v1/budgets": {
+        get: { operationId: "listBudgets", summary: "List budgets", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/BudgetStatus" } } } } } } } } },
+        post: { operationId: "createBudget", summary: "Create a budget", requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreateBudgetInput" } } } }, responses: { "200": { description: "created", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/BudgetStatus" } } } } } } } }
+      },
+      "/v1/budgets/{id}": { delete: { operationId: "deleteBudget", summary: "Delete a budget", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } } },
+      "/v1/goals": {
+        get: { operationId: "listGoals", summary: "List goals", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/GoalStatus" } } } } } } } } },
+        post: { operationId: "createGoal", summary: "Create a goal", requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreateGoalInput" } } } }, responses: { "200": { description: "created", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/GoalStatus" } } } } } } } }
+      },
+      "/v1/goals/{id}": { delete: { operationId: "deleteGoal", summary: "Delete a goal", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } } },
+      "/v1/pricing": {
+        get: { operationId: "listPricing", summary: "List model pricing", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/ModelPricing" } } } } } } } } },
+        post: { operationId: "upsertPricing", summary: "Upsert model pricing", requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreatePricingInput" } } } }, responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/ModelPricing" } } } } } } } }
+      },
+      "/v1/pricing/{model}": { delete: { operationId: "deletePricing", summary: "Delete model pricing", parameters: [{ name: "model", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } } },
+      "/v1/subscriptions": {
+        get: { operationId: "listSubscriptions", summary: "List subscriptions", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/Subscription" } } } } } } } } },
+        post: { operationId: "upsertSubscription", summary: "Upsert a subscription", requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreateSubscriptionInput" } } } }, responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { $ref: "#/components/schemas/Subscription" } } } } } } } }
+      },
+      "/v1/subscriptions/{id}": { delete: { operationId: "deleteSubscription", summary: "Delete a subscription", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } } },
+      "/v1/project-registry": {
+        get: { operationId: "listProjectRegistry", summary: "List registered projects", responses: { "200": { description: "ok", content: { "application/json": { schema: { type: "object", properties: { data: { type: "array", items: { $ref: "#/components/schemas/Project" } } } } } } } } },
+        post: { operationId: "upsertProject", summary: "Register a project", requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/CreateProjectInput" } } } }, responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } }
+      },
+      "/v1/project-registry/{id}": { delete: { operationId: "deleteProject", summary: "Delete a registered project", parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }], responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/MutationOk" } } } } } } },
+      "/v1/sync": { post: { operationId: "sync", summary: "Trigger an ingest sync", requestBody: { required: false, content: { "application/json": { schema: { type: "object", properties: { sources: { type: "string" } } } } } }, responses: { "200": { description: "ok", content: { "application/json": { schema: { $ref: "#/components/schemas/Envelope" } } } } } } }
+    }
+  };
+});
+
 // src/server/serve.ts
 var exports_serve = {};
 __export(exports_serve, {
   startServer: () => startServer,
+  openApiDocument: () => openApiDocument,
   createServerFetch: () => createServerFetch,
   createHandler: () => createHandler
 });
 import { randomUUID as randomUUID2 } from "crypto";
-import { existsSync as existsSync15 } from "fs";
-import { resolve, sep } from "path";
+import { existsSync as existsSync17 } from "fs";
+import { resolve as resolve2, sep } from "path";
+import { verifyApiKey, ApiKeyStore } from "@hasna/contracts/auth";
+function openApiDocument() {
+  const spec = openApiSpec;
+  return { ...spec, info: { ...spec["info"], version: packageMetadata.version } };
+}
+function serveMode() {
+  return isCloudMode() ? "self_hosted" : "local";
+}
+function foundationEnvelope(status, extra = {}) {
+  return { status, version: packageMetadata.version, mode: serveMode(), service: "economy", ...extra };
+}
 function json(data, status = 200) {
   return new Response(JSON.stringify(data), {
     status,
@@ -4670,23 +4995,23 @@ function dashboardPath(root, pathname) {
     return null;
   }
   const relativePath = decoded === "/" ? "index.html" : decoded.replace(/^\/+/, "");
-  const rootPath = resolve(root);
-  const filePath = resolve(rootPath, relativePath);
+  const rootPath = resolve2(root);
+  const filePath = resolve2(rootPath, relativePath);
   return filePath === rootPath || filePath.startsWith(rootPath + sep) ? filePath : null;
 }
 function createServerFetch(apiHandler, dashboardDir = DEFAULT_DASHBOARD_DIR) {
   return async function fetch2(req) {
     const url = new URL(req.url);
-    if (url.pathname.startsWith("/api") || url.pathname === "/health") {
+    if (url.pathname.startsWith("/api") || url.pathname.startsWith("/v1") || FOUNDATION_PATHS.has(url.pathname)) {
       return apiHandler(req);
     }
-    if (existsSync15(dashboardDir)) {
+    if (existsSync17(dashboardDir)) {
       const filePath = dashboardPath(dashboardDir, url.pathname);
-      if (filePath && existsSync15(filePath)) {
+      if (filePath && existsSync17(filePath)) {
         return new Response(Bun.file(filePath));
       }
       const indexPath = dashboardPath(dashboardDir, "/");
-      if (indexPath && existsSync15(indexPath)) {
+      if (indexPath && existsSync17(indexPath)) {
         return new Response(Bun.file(indexPath));
       }
     }
@@ -4698,15 +5023,34 @@ function applyFields(obj, fields) {
     return obj;
   return Object.fromEntries(fields.map((f) => [f, obj[f] ?? null]));
 }
-function createHandler(db) {
+function createHandler(db, options = {}) {
   return async function handler(req) {
     const url = new URL(req.url);
-    const path = url.pathname;
+    const rawPath = url.pathname;
+    const path = rawPath.startsWith("/v1/") ? "/api" + rawPath.slice(3) : rawPath === "/v1" ? "/api" : rawPath;
     const method = req.method;
     if (method === "OPTIONS")
       return new Response(null, { status: 204, headers: CORS });
-    if (!isAuthorizedRequest(req, path))
+    if (method === "GET" && (rawPath === "/health" || rawPath === "/healthz")) {
+      return json(foundationEnvelope("ok"));
+    }
+    if (method === "GET" && (rawPath === "/version" || rawPath === "/v1/version")) {
+      return json(foundationEnvelope("ok"));
+    }
+    if (method === "GET" && (rawPath === "/ready" || rawPath === "/readyz")) {
+      const result = options.readyCheck ? await options.readyCheck() : { ready: true };
+      return json(foundationEnvelope(result.ready ? "ready" : "not_ready", result.detail ? { detail: result.detail } : {}), result.ready ? 200 : 503);
+    }
+    if (method === "GET" && rawPath === "/openapi.json") {
+      return json(openApiDocument());
+    }
+    if (options.authenticator) {
+      const decision = await options.authenticator.authenticate(req.headers, { method, path: rawPath });
+      if (!decision.ok)
+        return json({ error: decision.reason ?? "unauthorized", message: decision.message }, decision.status || 401);
+    } else if (!isAuthorizedRequest(req, path)) {
       return err("Unauthorized", 401);
+    }
     if (path === "/health")
       return ok({ status: "ok", ts: new Date().toISOString() });
     if (path === "/api/summary" && method === "GET") {
@@ -4771,7 +5115,8 @@ function createHandler(db) {
     if (path === "/api/top" && method === "GET") {
       const n = Number(url.searchParams.get("n") ?? 10);
       const agent = url.searchParams.get("agent") ?? undefined;
-      return ok(queryTopSessions(db, n, agent));
+      const since = url.searchParams.get("since") ?? undefined;
+      return ok(queryTopSessions(db, n, agent, since));
     }
     if (path === "/api/models" && method === "GET") {
       return ok(queryModelBreakdown(db));
@@ -5058,22 +5403,56 @@ function createHandler(db) {
     return err("Not found", 404);
   };
 }
+function isLocalHost(host) {
+  return ["127.0.0.1", "localhost", "::1"].includes(host);
+}
 function startServer(port = 3456, options = {}) {
-  const db = options.db ?? openDatabase();
-  ensurePricingSeeded(db);
-  const apiHandler = createHandler(db);
-  const hostname2 = options.hostname ?? getServeBindHost();
+  const cloud = options.db ? false : isCloudMode();
+  const hostname2 = options.hostname ?? (cloud ? process.env["ECONOMY_HOST"] ?? "0.0.0.0" : getServeBindHost());
+  const log = options.log ?? console.log;
+  const handlerOptions = {};
+  let db;
+  if (cloud) {
+    db = openCloudDatabase();
+    const pool = createCloudPool();
+    const signingSecret = resolveSigningSecret();
+    if (signingSecret) {
+      const keys = new ApiKeyStore(authClientFromPool(pool));
+      keys.ensureSchema().catch((e) => log(`api_keys ensureSchema: ${e instanceof Error ? e.message : String(e)}`));
+      handlerOptions.authenticator = verifyApiKey({
+        app: APP,
+        signingSecret,
+        isRevoked: keys.statusChecker(),
+        audit: (event) => log(JSON.stringify({ evt: "api_auth", outcome: event.outcome, kid: event.kid, reason: event.reason, path: event.path, status: event.status }))
+      });
+    } else if (!isLocalHost(hostname2)) {
+      throw new Error("economy-serve on a non-local host requires an API signing secret (HASNA_ECONOMY_API_SIGNING_KEY / API_KEY_SIGNING_SECRET)");
+    }
+    handlerOptions.readyCheck = async () => {
+      try {
+        const res = await pool.query("SELECT to_regclass($1) AS reg", ["public.requests"]);
+        if (!res.rows[0]?.reg)
+          return { ready: false, detail: "pending_migrations:requests" };
+        return { ready: true };
+      } catch (error) {
+        return { ready: false, detail: error instanceof Error ? error.message : "storage_unreachable" };
+      }
+    };
+  } else {
+    db = options.db ?? openDatabase();
+    ensurePricingSeeded(db);
+  }
+  const apiHandler = createHandler(db, handlerOptions);
   const server = Bun.serve({
     port,
     hostname: hostname2,
     fetch: createServerFetch(apiHandler, options.dashboardDir)
   });
   const address = `http://${hostname2 === "0.0.0.0" ? "localhost" : hostname2}:${server.port}`;
-  const log = options.log ?? console.log;
   log(`economy-serve listening on ${address}`);
   return server;
 }
-var CORS, AGENT_ERROR, SYNC_SOURCES, DEFAULT_DASHBOARD_DIR;
+var CORS, AGENT_ERROR, SYNC_SOURCES, DEFAULT_DASHBOARD_DIR, FOUNDATION_PATHS, APP = "economy";
 var init_serve = __esm(() => {
   init_database();
   init_pricing();
@@ -5081,6 +5460,9 @@ var init_serve = __esm(() => {
   init_sync_all();
   init_billing_diff();
   init_database();
+  init_package_metadata();
+  init_cloud();
+  init_openapi();
   CORS = {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET,POST,PUT,DELETE,OPTIONS",
@@ -5089,6 +5471,7 @@ var init_serve = __esm(() => {
   AGENT_ERROR = `agent must be one of: ${AGENTS.join(", ")}`;
   SYNC_SOURCES = ["all", ...AGENTS];
   DEFAULT_DASHBOARD_DIR = new URL("../../dashboard/dist", import.meta.url).pathname;
+  FOUNDATION_PATHS = new Set(["/health", "/healthz", "/ready", "/readyz", "/version", "/openapi.json"]);
 });
 
 // src/cli/commands/menubar.ts
@@ -5101,14 +5484,14 @@ __export(exports_menubar, {
 });
 import chalk6 from "chalk";
 import { execFileSync as execFileSync3 } from "child_process";
-import { cpSync, existsSync as existsSync16, mkdirSync as mkdirSync4, rmSync, writeFileSync as writeFileSync3 } from "fs";
+import { cpSync, existsSync as existsSync18, mkdirSync as mkdirSync5, rmSync as rmSync2, writeFileSync as writeFileSync4 } from "fs";
 import { tmpdir, arch } from "os";
-import { join as join13 } from "path";
+import { join as join15 } from "path";
 function getArch() {
   return arch() === "arm64" ? "arm64" : "x86_64";
 }
 function isInstalled() {
-  return existsSync16(APP_PATH);
+  return existsSync18(APP_PATH);
 }
 function isRunning() {
   try {
@@ -5145,15 +5528,15 @@ async function menubarInstall(opts) {
     console.error(chalk6.red(`\u2717 Failed to fetch release info: ${e instanceof Error ? e.message : String(e)}`));
     process.exit(1);
   }
-  const zipPath = join13(tmpdir(), `economy-bar-${cpuArch}.zip`);
-  const extractDir = join13(tmpdir(), "economy-bar-extracted");
+  const zipPath = join15(tmpdir(), `economy-bar-${cpuArch}.zip`);
+  const extractDir = join15(tmpdir(), "economy-bar-extracted");
   console.log(chalk6.cyan(`\u2192 Downloading ${assetUrl}...`));
   try {
     const res = await fetch(assetUrl, { signal: AbortSignal.timeout(60000) });
     if (!res.ok)
       throw new Error(`Download failed: ${res.status}`);
     const buffer = await res.arrayBuffer();
-    writeFileSync3(zipPath, Buffer.from(buffer));
+    writeFileSync4(zipPath, Buffer.from(buffer));
     console.log(chalk6.green(`\u2713 Downloaded (${(buffer.byteLength / 1024 / 1024).toFixed(1)} MB)`));
   } catch (e) {
     console.error(chalk6.red(`\u2717 Download failed: ${e instanceof Error ? e.message : String(e)}`));
@@ -5161,17 +5544,17 @@ async function menubarInstall(opts) {
   }
   console.log(chalk6.cyan("\u2192 Installing to /Applications..."));
   try {
-    rmSync(extractDir, { recursive: true, force: true });
-    mkdirSync4(extractDir, { recursive: true });
+    rmSync2(extractDir, { recursive: true, force: true });
+    mkdirSync5(extractDir, { recursive: true });
     execFileSync3("unzip", ["-q", zipPath, "-d", extractDir], { stdio: "ignore" });
     if (isInstalled())
-      rmSync(APP_PATH, { recursive: true, force: true });
-    cpSync(join13(extractDir, "Economy Bar.app"), APP_PATH, { recursive: true });
+      rmSync2(APP_PATH, { recursive: true, force: true });
+    cpSync(join15(extractDir, "Economy Bar.app"), APP_PATH, { recursive: true });
     try {
       execFileSync3("xattr", ["-rd", "com.apple.quarantine", APP_PATH], { stdio: "ignore" });
     } catch {}
-    rmSync(zipPath, { force: true });
-    rmSync(extractDir, { recursive: true, force: true });
+    rmSync2(zipPath, { force: true });
+    rmSync2(extractDir, { recursive: true, force: true });
     console.log(chalk6.green(`\u2713 Installed to ${APP_PATH}`));
   } catch (e) {
     console.error(chalk6.red(`\u2717 Install failed: ${e instanceof Error ? e.message : String(e)}`));
@@ -5198,7 +5581,7 @@ function menubarUninstall() {
       execFileSync3("sleep", ["1"], { stdio: "ignore" });
     } catch {}
   }
-  rmSync(APP_PATH, { recursive: true, force: true });
+  rmSync2(APP_PATH, { recursive: true, force: true });
   console.log(chalk6.green("\u2713 Economy Bar uninstalled"));
 }
 function menubarStart() {
@@ -6564,6 +6947,15 @@ init_paths();
 function fmt2(usd) {
   return "$" + usd.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
 }
+function fmtTokens(n) {
+  if (n >= 1e9)
+    return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6)
+    return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1000)
+    return `${(n / 1000).toFixed(1)}k`;
+  return n.toLocaleString("en-US");
+}
 function parsePeriod(value, fallback = "month") {
   const p = value ?? fallback;
   if (!["today", "yesterday", "week", "month", "year", "all"].includes(p)) {
@@ -6578,7 +6970,7 @@ function registerExtendedCommands(program) {
     const period = parsePeriod(periodArg, "month");
     const agent = parseAgent(opts.agent, "--agent");
     const snaps = queryUsageSnapshots(db, { agent, ...usageSnapshotFilterForPeriod(period) });
-    const summary = querySummary(db, period, undefined, true);
+    const summary = querySummary(db, period, undefined, true, agent);
     if (opts.json) {
       console.log(JSON.stringify({ period, agent: agent ?? "all", snapshots: snaps, summary }, null, 2));
       return;
@@ -6593,8 +6985,9 @@ function registerExtendedCommands(program) {
         console.log(`  ${chalk4.white(s.agent.padEnd(10))} ${s.metric.padEnd(28)} ${s.value}${s.unit ? ` ${s.unit}` : ""}  ${chalk4.dim(s.date)}`);
       }
     }
+    const spendLabel = agent ? `${agent} API-equivalent spend:` : "Fleet API-equivalent spend:";
     console.log(`
-  ${chalk4.dim("Fleet API-equivalent spend:")} ${fmt2(summary.total_usd)}`);
+  ${chalk4.dim(spendLabel)} ${fmt2(summary.total_usd)}`);
     console.log();
   });
   program.command("savings [period]").description("Subscription vs API-equivalent savings breakdown").option("--agent <agent>", "Filter by agent").option("--json", "Output JSON").action((periodArg, opts) => {
@@ -6676,8 +7069,19 @@ function registerExtendedCommands(program) {
     }
     checks.push({ ok: Boolean(process.env["CURSOR_SESSION_TOKEN"]), msg: `cursor token: ${process.env["CURSOR_SESSION_TOKEN"] ? "set" : "missing CURSOR_SESSION_TOKEN"}` });
     checks.push({ ok: Boolean(getCloudDatabaseUrl()), msg: `cloud: ${getCloudDatabaseUrl() ? "ECONOMY_CLOUD_DATABASE_URL set" : "not configured"}` });
-    const zeroCost = db.prepare(`SELECT COUNT(*) as c FROM requests WHERE cost_usd = 0 AND (input_tokens > 0 OR output_tokens > 0)`).get();
-    checks.push({ ok: zeroCost.c === 0, msg: `zero-cost requests with tokens: ${zeroCost.c}` });
+    const zeroCostBuckets = queryZeroCostTokenizedModels(db, 5);
+    const zeroCost = db.prepare(`
+        SELECT COUNT(*) as c
+        FROM requests
+        WHERE cost_usd = 0
+          AND (input_tokens > 0 OR output_tokens > 0 OR cache_read_tokens > 0 OR cache_create_tokens > 0)
+      `).get();
+    const zeroCostSuffix = zeroCostBuckets.length > 0 ? `; top buckets: ${zeroCostBuckets.map((row) => {
+      const pricing = getPricingFromDb(db, row.model);
+      const status = pricing ? "pricing configured" : "missing pricing";
+      return `${row.agent}/${row.model} ${row.requests} req ${fmtTokens(row.total_tokens)} tok (${status})`;
+    }).join("; ")}` : "";
+    checks.push({ ok: zeroCost.c === 0, msg: `zero-cost requests with tokens: ${zeroCost.c}${zeroCostSuffix}` });
     const estimated = querySummary(db, "month", undefined, true);
     const actual = queryBillingSummary(db, "month");
     const drift = actual.total_usd > 0 ? Math.abs(estimated.total_usd - actual.total_usd) / actual.total_usd : 0;
@@ -7824,6 +8228,187 @@ function mergePeerDatabase(target, sourcePath, opts = {}) {
   };
 }
 
+// src/lib/fleet-sync.ts
+init_database();
+import { spawnSync } from "child_process";
+import { existsSync as existsSync13, mkdirSync as mkdirSync3, renameSync, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join12, resolve } from "path";
+import { homedir as homedir9 } from "os";
+import { Database as Database2 } from "bun:sqlite";
+var DEFAULT_TIMEOUT_MS = 120000;
+var DEFAULT_MACHINES = ["spark02", "apple03"];
+function runEconomyFleetSync(options = {}) {
+  const generatedAt = (options.now ?? new Date).toISOString();
+  const timeoutMs = normalizePositiveInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS);
+  const runner = options.runner ?? spawnCommand;
+  const dryRun = Boolean(options.dryRun);
+  const machines = ((options.machines?.length) ? options.machines : DEFAULT_MACHINES).filter(Boolean);
+  const cacheDir = resolve(options.cacheDir ?? join12(homedir9(), ".hasna", "economy", "fleet-sync-cache"));
+  const remoteSnapshotDir = options.remoteSnapshotDir ?? "$HOME/.hasna/economy/fleet-sync-snapshots";
+  const localSync = options.localSync !== false;
+  const remoteSync = options.remoteSync !== false;
+  const local = {
+    status: dryRun ? "dry_run" : localSync ? "skipped" : "skipped",
+    db_path: getDbPath()
+  };
+  if (localSync) {
+    if (dryRun) {
+      local.status = "dry_run";
+    } else {
+      local.sync = runner("economy", ["sync"], { timeoutMs });
+      local.status = local.sync.code === 0 ? "synced" : "failed";
+    }
+  }
+  const remote = machines.map((machine) => syncMachine(machine, {
+    generatedAt,
+    timeoutMs,
+    runner,
+    dryRun,
+    remoteSync,
+    cacheDir,
+    remoteSnapshotDir
+  }));
+  return {
+    schema: "open-economy.fleet-sync.v1",
+    generated_at: generatedAt,
+    dry_run: dryRun,
+    local,
+    remote,
+    summary: {
+      machines: remote.length,
+      merged: remote.filter((row) => row.status === "merged").length,
+      failed: remote.filter((row) => row.status === "failed").length,
+      dry_run: remote.filter((row) => row.status === "dry_run").length + (dryRun ? 1 : 0)
+    }
+  };
+}
+function syncMachine(machine, context) {
+  const safeMachine = machine.replace(/[^A-Za-z0-9_.-]/g, "_");
+  const stamp = context.generatedAt.replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+  const snapshotName = `${safeMachine}-${stamp}.economy.db`;
+  const remoteSnapshotPath = `${context.remoteSnapshotDir.replace(/\/$/, "")}/${snapshotName}`;
+  const tmpLocal = join12(context.cacheDir, `${snapshotName}.tmp`);
+  const verifiedLocal = join12(context.cacheDir, snapshotName);
+  if (context.dryRun) {
+    return { machine, status: "dry_run", remote_snapshot_path: remoteSnapshotPath };
+  }
+  mkdirSync3(context.cacheDir, { recursive: true });
+  rmSync(tmpLocal, { force: true });
+  const result = {
+    machine,
+    status: "failed",
+    remote_snapshot_path: remoteSnapshotPath
+  };
+  if (context.remoteSync) {
+    result.remote_sync = context.runner("ssh", [machine, "economy sync"], { timeoutMs: context.timeoutMs });
+    if (result.remote_sync.code !== 0) {
+      result.error = "remote economy sync failed";
+      return result;
+    }
+  }
+  result.remote_snapshot = context.runner("ssh", [machine, remoteSnapshotCommand(context.remoteSnapshotDir, snapshotName)], { timeoutMs: context.timeoutMs });
+  if (result.remote_snapshot.code !== 0) {
+    result.error = "remote snapshot failed";
+    return result;
+  }
+  const emittedPath = result.remote_snapshot.stdout.trim().split(/\r?\n/).at(-1)?.trim() || remoteSnapshotPath;
+  if (!isSafeRemoteSnapshotPath(emittedPath, context.remoteSnapshotDir)) {
+    result.error = `remote snapshot path refused: ${emittedPath}`;
+    return result;
+  }
+  result.remote_snapshot_path = emittedPath;
+  result.pull = context.runner("scp", [`${machine}:${emittedPath}`, tmpLocal], { timeoutMs: context.timeoutMs });
+  context.runner("ssh", [machine, `rm -f ${shellQuote(emittedPath)}`], { timeoutMs: context.timeoutMs });
+  if (result.pull.code !== 0) {
+    result.error = "snapshot pull failed; no cached DB merged";
+    rmSync(tmpLocal, { force: true });
+    return result;
+  }
+  const integrity = verifySqliteIntegrity(tmpLocal);
+  result.local_integrity = integrity;
+  if (!integrity.ok) {
+    result.error = "pulled snapshot failed local integrity check";
+    rmSync(tmpLocal, { force: true });
+    return result;
+  }
+  renameSync(tmpLocal, verifiedLocal);
+  const db = openDatabase();
+  result.merge = mergePeerDatabase(db, verifiedLocal, { sourceMachine: machine });
+  result.status = "merged";
+  return result;
+}
+function remoteSnapshotCommand(remoteDir, filename) {
+  const dirExpr = remoteDir.startsWith("$HOME/") ? `"${remoteDir.replace(/"/g, "\\\"")}"` : shellQuote(remoteDir);
+  const safeFilename = filename.replace(/[^A-Za-z0-9_.-]/g, "_");
+  return [
+    "set -euo pipefail",
+    'db="${HASNA_ECONOMY_DB_PATH:-${ECONOMY_DB:-$HOME/.hasna/economy/economy.db}}"',
+    `snapshot_dir=${dirExpr}`,
+    `out="$snapshot_dir/${safeFilename}"`,
+    'test -f "$db"',
+    'mkdir -p "$snapshot_dir"',
+    'rm -f "$out"',
+    `sqlite3 "$db" "VACUUM INTO '$out'"`,
+    'test "$(sqlite3 "$out" "PRAGMA integrity_check;")" = "ok"',
+    'printf "%s\\n" "$out"'
+  ].join("; ");
+}
+function isSafeRemoteSnapshotPath(path, remoteSnapshotDir = "$HOME/.hasna/economy/fleet-sync-snapshots") {
+  if (!path || path.includes("\x00") || path.includes(`
+`) || path.includes("\r"))
+    return false;
+  if (!path.endsWith(".db"))
+    return false;
+  if (path.includes(".."))
+    return false;
+  const prefix = remoteSnapshotDir.replace(/\/$/, "");
+  return path.startsWith(`${prefix}/`) || path.startsWith("$HOME/.hasna/economy/fleet-sync-snapshots/") || path.includes("/.hasna/economy/fleet-sync-snapshots/");
+}
+function verifySqliteIntegrity(path) {
+  if (!existsSync13(path))
+    return { ok: false, detail: "file does not exist" };
+  let db;
+  try {
+    db = new Database2(path, { readonly: true });
+    const row = db.query("PRAGMA integrity_check").get();
+    const detail = Object.values(row ?? {})[0] ?? "";
+    return { ok: detail.toLowerCase() === "ok", detail: detail || "no integrity result" };
+  } catch (error) {
+    return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+  } finally {
+    db?.close();
+  }
+}
+function writeFleetSyncReport(reportDir, result) {
+  mkdirSync3(reportDir, { recursive: true });
+  const path = join12(resolve(reportDir), `${result.generated_at.replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z")}.json`);
+  writeFileSync2(path, `${JSON.stringify(result, null, 2)}
+`);
+  return path;
+}
+function spawnCommand(command, args, options) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    timeout: options.timeoutMs,
+    maxBuffer: 1024 * 1024,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  return {
+    code: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    ...result.error ? { error: result.error.message } : {}
+  };
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function normalizePositiveInteger(value, fallback) {
+  if (value == null || !Number.isFinite(value) || value < 1)
+    return fallback;
+  return Math.floor(value);
+}
+
 // src/cli/index.ts
 init_database();
 init_database();
@@ -7863,7 +8448,7 @@ function fmt4(usd) {
   }
   return chalk7.green(formatted);
 }
-function fmtTokens(n) {
+function fmtTokens2(n) {
   if (n >= 1e9)
     return `${(n / 1e9).toFixed(1)}B`;
   if (n >= 1e6)
@@ -7971,7 +8556,7 @@ function printAccountBreakdown(rows) {
     chalk7.dim(r.account_source || "unknown"),
     String(r.sessions),
     String(r.requests),
-    chalk7.cyan(fmtTokens(r.total_tokens)),
+    chalk7.cyan(fmtTokens2(r.total_tokens)),
     fmt4(r.api_equivalent_usd),
     fmt4(r.billable_usd),
     fmt4(r.subscription_included_usd)
@@ -7998,7 +8583,7 @@ function printSummary(label, period) {
     ["Total cost", fmt4(s.total_usd)],
     ["Sessions", chalk7.yellow(fmtCount(s.sessions))],
     ["Requests", chalk7.yellow(fmtCount(s.requests))],
-    ["Tokens", chalk7.yellow(fmtTokens(s.tokens))]
+    ["Tokens", chalk7.yellow(fmtTokens2(s.tokens))]
   ]);
   console.log();
 }
@@ -8018,9 +8603,9 @@ program.action(async () => {
   console.log(chalk7.bold.cyan("  Economy"));
   console.log();
   printTable(["Period", "Cost", "Sessions", "Requests", "Tokens"], [
-    ["Today", fmt4(t.total_usd), fmtCount(t.sessions), fmtCount(t.requests), fmtTokens(t.tokens)],
-    ["This Week", fmt4(w.total_usd), fmtCount(w.sessions), fmtCount(w.requests), fmtTokens(w.tokens)],
-    ["This Month", fmt4(m.total_usd), fmtCount(m.sessions), fmtCount(m.requests), fmtTokens(m.tokens)]
+    ["Today", fmt4(t.total_usd), fmtCount(t.sessions), fmtCount(t.requests), fmtTokens2(t.tokens)],
+    ["This Week", fmt4(w.total_usd), fmtCount(w.sessions), fmtCount(w.requests), fmtTokens2(w.tokens)],
+    ["This Month", fmt4(m.total_usd), fmtCount(m.sessions), fmtCount(m.requests), fmtTokens2(m.tokens)]
   ]);
   if (dailyValues.length > 0) {
     console.log(`
@@ -8076,7 +8661,7 @@ program.command("sync").description("Ingest cost data from all coding agents").o
     console.log(chalk7.cyan(`\u2192 Backfilled machine_id='${machine}': ${reqCount.changes} requests, ${sessCount.changes} sessions`));
   }
   if (opts.recalculate) {
-    const { computeCostFromDb: computeCostFromDb2 } = await Promise.resolve().then(() => (init_pricing(), exports_pricing));
+    const { computeCostFromDb: computeCostFromDb2, getPricingFromDb: getPricingFromDb2 } = await Promise.resolve().then(() => (init_pricing(), exports_pricing));
     const zeroRows = db.prepare(`SELECT id, model, input_tokens, output_tokens, cache_read_tokens, cache_create_tokens, cache_create_5m_tokens, cache_create_1h_tokens FROM requests WHERE cost_usd = 0 AND (input_tokens > 0 OR output_tokens > 0 OR cache_read_tokens > 0 OR cache_create_tokens > 0)`).all();
     let fixed = 0;
     for (const r of zeroRows) {
@@ -8098,6 +8683,16 @@ program.command("sync").description("Ingest cost data from all coding agents").o
       }
     }
     console.log(chalk7.cyan(`\u2192 Recalculated: ${fixed}/${zeroRows.length} zero-cost requests now have pricing`));
+    const zeroCostBuckets = queryZeroCostTokenizedModels(db, 8);
+    if (zeroCostBuckets.length > 0) {
+      console.log(chalk7.yellow("\u2192 Zero-cost token buckets remain:"));
+      for (const row of zeroCostBuckets) {
+        const pricing = getPricingFromDb2(db, row.model);
+        const status = pricing ? pricing.inputPer1M === 0 && pricing.outputPer1M === 0 && pricing.cacheReadPer1M === 0 && pricing.cacheWritePer1M === 0 ? "explicit zero/free pricing" : "pricing configured; inspect/recalculate" : "missing pricing";
+        console.log(chalk7.yellow(`  ${row.agent}/${row.model}: ${row.requests} requests, ${fmtTokens2(row.total_tokens)} tokens (${status})`));
+      }
+      console.log(chalk7.dim("  Add pricing with `economy pricing set <model> --input ... --output ...`, then rerun `economy sync --recalculate`."));
+    }
   }
   try {
     const { checkAndFireWebhooks: checkAndFireWebhooks2 } = await Promise.resolve().then(() => (init_webhooks(), exports_webhooks));
@@ -8140,7 +8735,7 @@ program.command("sessions").description("List coding sessions with costs").optio
   const f = opts.format ?? "table";
   if (f === "compact") {
     for (const s of sessions)
-      process.stdout.write(`${s.id.slice(0, 8)} ${s.agent} ${fmt4(s.total_cost_usd)} ${fmtTokens(s.total_tokens)} ${s.project_name || "\u2014"}
+      process.stdout.write(`${s.id.slice(0, 8)} ${s.agent} ${fmt4(s.total_cost_usd)} ${fmtTokens2(s.total_tokens)} ${s.project_name || "\u2014"}
 `);
     return;
   }
@@ -8160,7 +8755,7 @@ program.command("sessions").description("List coding sessions with costs").optio
     fmtAgent(s.agent),
     chalk7.white(s.project_name || chalk7.dim("unknown")),
     fmt4(s.total_cost_usd),
-    chalk7.cyan(fmtTokens(s.total_tokens)),
+    chalk7.cyan(fmtTokens2(s.total_tokens)),
     fmtCount(s.request_count),
     chalk7.dim(s.started_at.substring(0, 16))
   ]));
@@ -8171,9 +8766,7 @@ program.command("top").description("Most expensive sessions").option("-n <n>", "
   const agent = parseOptionalCliAgent(opts.agent);
   const db = openDatabase();
   const sinceDate = opts.since ? parseSinceDate2(opts.since) : undefined;
-  let sessions = queryTopSessions(db, count, agent);
-  if (sinceDate)
-    sessions = sessions.filter((s) => s.started_at >= sinceDate);
+  const sessions = queryTopSessions(db, count, agent, sinceDate);
   if (sessions.length === 0) {
     console.log(chalk7.yellow("No sessions found. Run `economy sync` first."));
     return;
@@ -8184,7 +8777,7 @@ program.command("top").description("Most expensive sessions").option("-n <n>", "
     chalk7.white(s.project_name || chalk7.dim("unknown")),
     fmtAgent(s.agent),
     fmt4(s.total_cost_usd),
-    chalk7.cyan(fmtTokens(s.total_tokens)),
+    chalk7.cyan(fmtTokens2(s.total_tokens)),
     chalk7.dim(s.started_at.substring(0, 16))
   ]));
   console.log();
@@ -8208,7 +8801,7 @@ program.command("breakdown").description("Cost breakdown by model, agent, projec
       chalk7.white(r.project_name || chalk7.dim("unknown")),
       String(r.sessions),
       String(r.requests),
-      chalk7.cyan(fmtTokens(r.total_tokens)),
+      chalk7.cyan(fmtTokens2(r.total_tokens)),
       fmt4(r.cost_usd)
     ]));
   } else if (opts.by === "agent") {
@@ -8230,7 +8823,7 @@ program.command("breakdown").description("Cost breakdown by model, agent, projec
       fmtAgent(r.agent),
       String(r.sessions),
       String(r.requests),
-      chalk7.cyan(fmtTokens(r.total_tokens)),
+      chalk7.cyan(fmtTokens2(r.total_tokens)),
       fmt4(r.api_equivalent_usd),
       fmt4(r.billable_usd),
       fmt4(r.subscription_included_usd)
@@ -8352,7 +8945,7 @@ program.command("breakdown").description("Cost breakdown by model, agent, projec
       chalk7.white(r.model),
       fmtAgent(r.agent),
       String(r.requests),
-      chalk7.cyan(fmtTokens(r.total_tokens)),
+      chalk7.cyan(fmtTokens2(r.total_tokens)),
       fmt4(r.cost_usd)
     ]));
   }
@@ -8514,7 +9107,7 @@ projectCmd.command("show <nameOrPath>").description("Detailed project breakdown
   printTable(["Metric", "Value"], [
     ["Total cost", fmt4(totalCost)],
     ["Sessions", fmtCount(sessions.length)],
-    ["Total tokens", fmtTokens(totalTokens)]
+    ["Total tokens", fmtTokens2(totalTokens)]
   ]);
   if (dailyValues.length > 0) {
     console.log(`
@@ -8647,8 +9240,8 @@ program.command("dashboard").description("Open the web dashboard (auto-starts se
   if (!serverRunning) {
     console.log(chalk7.cyan(`\u2192 Starting economy server on port ${port}...`));
     const { spawn } = await import("child_process");
-    const { resolve: resolve2, dirname: dirname3 } = await import("path");
-    const serveScript = resolve2(dirname3(process.argv[1]), "..", "server", "index.js");
+    const { resolve: resolve3, dirname: dirname4 } = await import("path");
+    const serveScript = resolve3(dirname4(process.argv[1]), "..", "server", "index.js");
     const child = spawn(process.execPath, [serveScript], {
       detached: true,
       stdio: "ignore",
@@ -8719,7 +9312,7 @@ program.command("session <id>").description("Show detailed breakdown of a single
     ["Started", String(session["started_at"]).substring(0, 19)],
     ["Ended", session["ended_at"] ? String(session["ended_at"]).substring(0, 19) : "\u2014"],
     ["Total cost", fmt4(session["total_cost_usd"])],
-    ["Total tokens", fmtTokens(session["total_tokens"])],
+    ["Total tokens", fmtTokens2(session["total_tokens"])],
     ["Requests", fmtCount(session["request_count"])]
   ]);
   if (requests.length > 0) {
@@ -8729,10 +9322,10 @@ program.command("session <id>").description("Show detailed breakdown of a single
     printTable(["Time", "Model", "Input", "Output", "Cache R", "Cache W", "Cost"], requests.slice(0, 50).map((r) => [
       chalk7.dim(String(r["timestamp"]).substring(11, 19)),
       chalk7.white(String(r["model"]).substring(0, 22)),
-      fmtTokens(r["input_tokens"]),
-      fmtTokens(r["output_tokens"]),
-      fmtTokens(r["cache_read_tokens"]),
-      fmtTokens(r["cache_create_tokens"]),
+      fmtTokens2(r["input_tokens"]),
+      fmtTokens2(r["output_tokens"]),
+      fmtTokens2(r["cache_read_tokens"]),
+      fmtTokens2(r["cache_create_tokens"]),
       fmt4(r["cost_usd"])
     ]));
     if (requests.length > 50)
@@ -8763,6 +9356,31 @@ program.command("machines").description("List all machines that have synced data
   ${chalk7.dim("Current machine:")} ${chalk7.bold(current)}`);
   console.log();
 });
+program.command("fleet-sync").description("Loop-safe cross-machine sync using remote SQLite snapshots").option("--machine <ids>", "Comma-separated remote machines", "spark02,apple03").option("--no-local-sync", "Skip local economy sync before remote merge").option("--no-remote-sync", "Skip remote economy sync before snapshot").option("--cache-dir <path>", "Directory for verified pulled DB snapshots").option("--report-dir <path>", "Directory for JSON evidence reports").option("--remote-snapshot-dir <path>", "Remote snapshot directory", "$HOME/.hasna/economy/fleet-sync-snapshots").option("--timeout-ms <n>", "Per remote command timeout", "120000").option("--dry-run", "Plan without syncing, pulling, or merging").option("--json", "Output JSON").action((opts) => {
+  const result = runEconomyFleetSync({
+    machines: opts.machine?.split(",").map((entry) => entry.trim()).filter(Boolean),
+    localSync: opts.localSync !== false,
+    remoteSync: opts.remoteSync !== false,
+    cacheDir: opts.cacheDir,
+    remoteSnapshotDir: opts.remoteSnapshotDir,
+    timeoutMs: parsePositiveCliInteger(opts.timeoutMs, "--timeout-ms"),
+    dryRun: opts.dryRun
+  });
+  const reportPath = opts.reportDir ? writeFleetSyncReport(opts.reportDir, result) : undefined;
+  if (opts.json) {
+    console.log(JSON.stringify({ ...result, ...reportPath ? { report_path: reportPath } : {} }, null, 2));
+    return;
+  }
+  const status = result.summary.failed === 0 ? chalk7.green("ok") : chalk7.red("failed");
+  console.log(`${status} machines=${result.summary.machines} merged=${result.summary.merged} failed=${result.summary.failed} dry_run=${result.summary.dry_run}`);
+  if (reportPath)
+    console.log(chalk7.dim(`report=${reportPath}`));
+  for (const row of result.remote.filter((entry) => entry.status !== "merged").slice(0, 20)) {
+    console.log(`${row.status === "failed" ? chalk7.red("failed") : chalk7.yellow(row.status)} ${row.machine} ${chalk7.dim(row.error ?? "")}`);
+  }
+  if (result.local.status === "failed" || result.summary.failed > 0)
+    process.exitCode = 1;
+});
 program.command("merge-db <source-db>").description("Merge another Economy SQLite database into this machine").option("--source-machine <id>", "Machine id to use for source rows that do not have one").option("--json", "Output JSON").action((sourceDb, opts) => {
   const db = openDatabase();
   const result = mergePeerDatabase(db, sourceDb, { sourceMachine: opts.sourceMachine });
@@ -8802,8 +9420,8 @@ program.command("export").description("Export data as CSV").option("--type <type
     }
   }
   if (opts.output) {
-    const { writeFileSync: writeFileSync4 } = await import("fs");
-    writeFileSync4(opts.output, csv);
+    const { writeFileSync: writeFileSync5 } = await import("fs");
+    writeFileSync5(opts.output, csv);
     console.log(chalk7.green(`\u2713 Exported to ${opts.output}`));
   } else {
     process.stdout.write(csv);
@@ -8875,7 +9493,7 @@ program.command("compare <period1> <period2>").description("Compare two periods
     ["Cost", fmt4(a.cost), fmt4(b.cost), delta(a.cost, b.cost)],
     ["Sessions", fmtCount(a.sessions), fmtCount(b.sessions), delta(a.sessions, b.sessions)],
     ["Requests", fmtCount(a.requests), fmtCount(b.requests), delta(a.requests, b.requests)],
-    ["Tokens", fmtTokens(a.tokens), fmtTokens(b.tokens), delta(a.tokens, b.tokens)]
+    ["Tokens", fmtTokens2(a.tokens), fmtTokens2(b.tokens), delta(a.tokens, b.tokens)]
   ]);
   console.log();
 });