@vimoxshah/tokenflow 1.1.1 → 1.2.0

package/src/core/policy.js

@@ -0,0 +1,103 @@
+/**
+ * Per-repository guard policy — `.tokenflow/policy.yaml` at a repository root.
+ *
+ * A cap declared with `tokenflow guard --set` lives in ~/.tokenflow/config.yaml:
+ * one machine, one person. A repository-level cap travels with the repo itself
+ * (checked in, reviewed in a PR, the same for everyone who clones it) and wins
+ * over the personal default — a data-heavy repo's sessions legitimately carry a
+ * bigger prompt than a docs repo's, and that is a fact about the repo, not
+ * about who happens to be sitting at the keyboard.
+ *
+ * Nothing here throws on a malformed file: a broken policy.yaml degrades to
+ * "reported, not applied" — the same posture the rest of TokenFlow takes
+ * toward bad input — rather than breaking the hook it is meant to configure.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from './yaml.js';
+import { repoRootOf } from './repo.js';
+import { loadConfig } from './config.js';
+
+/** The five thresholds `evaluateGuard` understands. Canonical list — guard.js re-exports this. */
+export const GUARD_KEYS = ['warnCostUsd', 'maxCostUsd', 'warnContextTokens', 'maxContextTokens', 'warnMarginalUsd'];
+
+const POLICY_RELATIVE_PATH = path.join('.tokenflow', 'policy.yaml');
+
+function isPositiveNumber(v) {
+  return typeof v === 'number' && Number.isFinite(v) && v > 0;
+}
+
+/**
+ * Read `<repo root>/.tokenflow/policy.yaml`, if this cwd sits inside a
+ * repository and that file exists. Invalid values are reported in `errors`
+ * and left out of `guard`, never thrown — a typo in a checked-in policy file
+ * must not take the hook down for everyone who clones the repo.
+ * @param {string|null|undefined} cwd
+ * @returns {{repoRoot:string|null, path:string|null, found:boolean, guard:object, note:string|null, errors:string[]}}
+ */
+export function loadRepoPolicy(cwd) {
+  const errors = [];
+  const repoRoot = cwd ? repoRootOf(cwd) : null;
+  if (!repoRoot) return { repoRoot: null, path: null, found: false, guard: {}, note: null, errors };
+
+  const file = path.join(repoRoot, POLICY_RELATIVE_PATH);
+  if (!fs.existsSync(file)) return { repoRoot, path: file, found: false, guard: {}, note: null, errors };
+
+  let doc;
+  try {
+    doc = parseYaml(fs.readFileSync(file, 'utf8')) || {};
+  } catch (err) {
+    errors.push(`${file}: ${err.message}`);
+    return { repoRoot, path: file, found: true, guard: {}, note: null, errors };
+  }
+
+  const rawGuard = doc.guard && typeof doc.guard === 'object' && !Array.isArray(doc.guard) ? doc.guard : {};
+  const guard = {};
+  for (const [k, v] of Object.entries(rawGuard)) {
+    if (k === 'note') continue; // accepted alongside the thresholds; handled below
+    if (!GUARD_KEYS.includes(k)) { errors.push(`${file}: unknown guard key "${k}"`); continue; }
+    if (v === null || v === undefined) continue; // not declared
+    if (!isPositiveNumber(v)) { errors.push(`${file}: guard.${k} must be a positive number, got ${JSON.stringify(v)}`); continue; }
+    guard[k] = v;
+  }
+
+  // `note:` can sit at the top level or beside the guard block — accept both
+  // rather than guess which one a hand-written file used.
+  const noteRaw = doc.note !== undefined ? doc.note : rawGuard.note;
+  let note = null;
+  if (noteRaw !== undefined && noteRaw !== null) {
+    if (typeof noteRaw === 'string') note = noteRaw;
+    else errors.push(`${file}: note must be a string`);
+  }
+
+  return { repoRoot, path: file, found: true, guard, note, errors };
+}
+
+/**
+ * Merge a repository's declared policy over `config.guard`: the repo wins
+ * key-by-key, the personal config is the fallback, and an undeclared key is
+ * `null` — informational only, the same contract `evaluateGuard` already has.
+ * @param {{cwd?:string|null, config?:object}} [opt]
+ * @returns {{policy:object, sources:Record<string,'repo'|'config'|'default'>, repoRoot:string|null, note:string|null, errors:string[]}}
+ */
+export function effectiveGuardPolicy({ cwd = null, config } = {}) {
+  const cfg = config || loadConfig();
+  const repo = loadRepoPolicy(cwd);
+  const cfgGuard = cfg.guard || {};
+  const policy = {};
+  /** @type {Record<string, 'repo'|'config'|'default'>} */
+  const sources = {};
+  for (const k of GUARD_KEYS) {
+    if (isPositiveNumber(repo.guard[k])) {
+      policy[k] = repo.guard[k];
+      sources[k] = 'repo';
+    } else if (isPositiveNumber(cfgGuard[k])) {
+      policy[k] = cfgGuard[k];
+      sources[k] = 'config';
+    } else {
+      policy[k] = null;
+      sources[k] = 'default';
+    }
+  }
+  return { policy, sources, repoRoot: repo.repoRoot, note: repo.note, errors: repo.errors };
+}

package/src/core/receipt-note.js

@@ -0,0 +1,123 @@
+/**
+ * Receipts as git notes — a branch's TokenFlow receipt attached to the commit
+ * being pushed, under `refs/notes/tokenflow`, so it travels with the code
+ * with no server involved. `src/commands/hooks.js` is the only caller in this
+ * package (the pre-push hook body); everything here also works standalone.
+ *
+ * Every `git` invocation uses `execFileSync` with an argument array — never a
+ * shell string — so a branch name or path can never be interpreted as shell
+ * syntax.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { paths } from './config.js';
+import { readJson } from './store.js';
+import { buildPriceBook } from './pricing.js';
+import { repoRootOf, makeRepoResolver } from './repo.js';
+import { buildReceipts } from '../analytics/receipt.js';
+import { toReceiptV0 } from '../analytics/receipt-schema.js';
+import { loadPrimaryRecords } from '../commands/receipt.js';
+
+/** The git notes ref every receipt note in this package lives under. */
+export const NOTES_REF = 'tokenflow';
+
+/** This package's own version, read from its package.json (not the target repo's). */
+function toolVersion() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const pkgPath = path.resolve(here, '..', '..', 'package.json');
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0'; // package.json missing or unreadable: still return a usable receipt
+  }
+}
+
+function resolveSha(repoPath, branch) {
+  return execFileSync('git', ['rev-parse', `refs/heads/${branch}`], {
+    cwd: repoPath, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+/**
+ * Compute the receipt.v0 object for one branch of one repository checkout.
+ * Scans every primary record this machine has recorded, then narrows to the
+ * repository identified from `repoPath` (the same worktree-aware resolution
+ * `tokenflow receipt` uses) and to the named branch.
+ *
+ * No pull request is looked up here — attaching a note happens at push time,
+ * before any PR necessarily exists — so the returned receipt always carries
+ * `pr: null` and `changedLines: null`.
+ *
+ * @param {{repoPath:string, branch:string, store?:import('./store.js').Store,
+ *   config?:object, sha?:string}} opt
+ *   `config` is the pricing-overrides object (the shape of pricing.json /
+ *   buildPriceBook's argument); defaults to what's on disk. `sha` defaults to
+ *   `git rev-parse refs/heads/<branch>` in repoPath.
+ * @returns {object|null} a receipt.v0 object, or null when this branch has no local sessions
+ */
+export function buildBranchReceipt({ repoPath, branch, store, config, sha }) {
+  const pricingConfig = config || readJson(paths().pricing, {});
+  const book = buildPriceBook(pricingConfig);
+  const repoName = path.basename(repoRootOf(repoPath) || repoPath);
+
+  const records = loadPrimaryRecords({ store });
+  const result = buildReceipts(records, { book, repoOf: makeRepoResolver(), minTurns: 1 });
+  const R = result.repos.find((r) => r.repo === repoName);
+  const b = R ? R.branches.find((x) => x.key === branch) : null;
+  if (!b) return null;
+
+  const headSha = sha || resolveSha(repoPath, branch);
+  return toReceiptV0(b, { repo: repoName, headSha, toolVersion: toolVersion() });
+}
+
+/**
+ * Attach `receipt` to `sha` as a git note under refs/notes/tokenflow,
+ * overwriting any note already there (a re-push of the same sha updates it).
+ * @param {{repoPath:string, sha:string, receipt:object}} opt
+ */
+export function writeNote({ repoPath, sha, receipt }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'tokenflow-note-'));
+  const file = path.join(dir, 'receipt.json');
+  try {
+    fs.writeFileSync(file, `${JSON.stringify(receipt, null, 2)}\n`);
+    execFileSync('git', ['notes', `--ref=${NOTES_REF}`, 'add', '-f', '-F', file, sha], {
+      cwd: repoPath, stdio: ['ignore', 'ignore', 'pipe'],
+    });
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Read back the receipt attached to `sha`, or null when there isn't one.
+ * @param {{repoPath:string, sha:string}} opt
+ * @returns {object|null}
+ */
+export function readNote({ repoPath, sha }) {
+  try {
+    const out = execFileSync('git', ['notes', `--ref=${NOTES_REF}`, 'show', sha], {
+      cwd: repoPath, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return JSON.parse(out);
+  } catch {
+    return null; // no note on this sha (or a git/JSON error) — nothing to read back
+  }
+}
+
+/**
+ * Push refs/notes/tokenflow to `remote`. Runs with `TOKENFLOW_HOOK_NESTED=1`
+ * in the child's environment so a pre-push hook this triggers on the same
+ * repo can recognize this as the nested notes push and return immediately
+ * instead of recursing.
+ * @param {{repoPath:string, remote:string}} opt
+ */
+export function pushNotes({ repoPath, remote }) {
+  execFileSync('git', ['push', remote, `refs/notes/${NOTES_REF}`], {
+    cwd: repoPath,
+    stdio: ['ignore', 'ignore', 'pipe'],
+    env: { ...process.env, TOKENFLOW_HOOK_NESTED: '1' },
+  });
+}

package/src/core/repo.js

@@ -0,0 +1,64 @@
+/**
+ * Repository identity from a working directory, seeing through git worktrees.
+ *
+ * The adapters record `project` as the basename of the working directory, so a
+ * session in `<repo>/.worktrees/<x>` is filed under `x` and one repository's
+ * spend is split across every worktree it ever had. Walking up from the cwd
+ * to `.git` and following a worktree's `gitdir:` pointer back to the main
+ * checkout puts them back together. No subprocess, no network; results are
+ * cached per cwd because a store holds thousands of distinct ones.
+ *
+ * `src/core/ingest.js` applies `repoRootOf` at ingest time too, not only when
+ * a receipt is built later: `project`/`repository` are corrected to the
+ * resolved repo name as each record is normalized, and `metadata.repoResolved`
+ * records whether a root was found, so a record's stored fields already carry
+ * the correction rather than needing every reader to redo this walk.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * @param {string} cwd
+ * @param {Map<string,string|null>} [cache]
+ * @returns {string|null} the main checkout's root, or null when no `.git` is found above `cwd`
+ */
+export function repoRootOf(cwd, cache = new Map()) {
+  if (!cwd) return null;
+  if (cache.has(cwd)) return cache.get(cwd);
+  let d = cwd;
+  let out = null;
+  for (let i = 0; i < 12 && d && d !== path.dirname(d); i++) {
+    const g = path.join(d, '.git');
+    let st = null;
+    try { st = fs.statSync(g); } catch { /* not here; keep walking up */ }
+    if (st) {
+      if (st.isDirectory()) { out = d; break; }
+      // A worktree: `.git` is a file "gitdir: /main/checkout/.git/worktrees/<name>"
+      let txt = '';
+      try { txt = fs.readFileSync(g, 'utf8'); } catch { /* unreadable; fall back to this dir */ }
+      const m = /gitdir:\s*(.+)\s*$/m.exec(txt);
+      if (m) {
+        const gitdir = path.resolve(d, m[1].trim());
+        const wt = gitdir.indexOf(`${path.sep}.git${path.sep}worktrees${path.sep}`);
+        out = wt > -1 ? gitdir.slice(0, wt) : d;
+      } else {
+        out = d;
+      }
+      break;
+    }
+    d = path.dirname(d);
+  }
+  cache.set(cwd, out);
+  return out;
+}
+
+/** A resolver for the receipt builder: repository name from the recorded cwd, else what the adapter said. */
+export function makeRepoResolver() {
+  const cache = new Map();
+  return (rec) => {
+    const cwd = rec.metadata && rec.metadata.cwd;
+    const root = cwd ? repoRootOf(cwd, cache) : null;
+    if (root) return path.basename(root);
+    return rec.repository || rec.project || null;
+  };
+}

package/src/core/sync.js

@@ -1,5 +1,6 @@
 /**
- * Multi-machine aggregation — optional, OFF by default, file-based.
+ * Multi-machine aggregation — optional, OFF by default, file-based (or a
+ * server the user names).
  *
  * Philosophy: instead of a cloud SaaS endpoint, TokenFlow syncs through a
  * folder the user already trusts (iCloud Drive, Dropbox, Syncthing mount,
@@ -14,23 +15,48 @@
  *     machineName: MacBook Pro  # friendly label shown in aggregated views
  *     developerName: Vimox      # OPTIONAL — only when the team explicitly
  *                               # opts into per-developer visibility (P4-B)
+ *     receipts: true            # ← default; set false to skip the ledger file
+ *     to: https://…             # OPTIONAL — POST both files to a server
+ *                               # instead of writing them into `dir`
+ *     token: …                  # bearer token for `to` (or env
+ *                               # TOKENFLOW_SYNC_TOKEN)
  *
- * What is transmitted (per day, per provider/model):
+ * What is transmitted, in the daily rollup (per day, per provider/model):
  *   date, tokens in/out/cache, requests, estimated cost, machineId
  *   + developerName ONLY if you set it yourself (team mode, opt-in)
- * What is NEVER transmitted: prompts, code, file paths beyond the machine
- * label you chose, credentials.
  *
- * Conflict resolution: each machine writes ONLY its own file
- * (<machineId>.jsonl) — append-only, last-write-wins per line. Reads merge
- * all sibling files by summing per-date buckets. Offline is the natural
- * state: files just sync whenever the folder does.
+ * A SECOND file, `<machineId>.receipts.json`, carries the team's cost-per-
+ * branch-and-PR ledger (see src/analytics/receipt.js), whole-state and
+ * last-write-wins, written on every push unless `sync.receipts: false`. Per
+ * branch it transmits only:
+ *   repo (basename only — never a path or URL), branch, costUsd, turns,
+ *   sessions, subagentTurns, contextShare, first/last (ISO timestamps),
+ *   longLived (bool), and pr — null, or {number, mergedAt} for a PR this
+ *   branch shipped in. (`pr` comes from buildReceiptsForStore(), which has
+ *   no PR source wired in yet — it is null on every real push today; the
+ *   shape exists so a future cached PR list needs no format change.)
+ * It NEVER transmits: file paths, commit hashes, PR titles, diffs or line
+ * counts, prompts, or any model/code text — nothing beyond the aggregate
+ * numbers above.
+ *
+ * Conflict resolution: each machine writes ONLY its own files
+ * (<machineId>.jsonl append-only last-write-wins per line;
+ * <machineId>.receipts.json whole-state last-write-wins). Reads merge all
+ * sibling files. Offline is the natural state: files just sync whenever the
+ * folder does.
+ *
+ * `sync.to` (+ `sync.token` / env TOKENFLOW_SYNC_TOKEN) sends the exact same
+ * two files' contents to a server the user names instead of writing them
+ * into the shared folder — see push() below. Nothing else about the data
+ * changes; only the destination does.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
 import { loadConfig, paths } from './config.js';
+import { Store, readJson } from './store.js';
+import { buildReceiptsForStore } from './bundle.js';
 
 /** Stable, anonymous machine id: random UUID persisted locally on first use. */
 export function machineId(cfgHome = null) {
@@ -54,32 +80,25 @@ export function syncDir(cfg) {
 }
 
 /**
- * Export this machine's daily rollups to the shared folder.
- * @param {{config?: object}} opt
- * @returns {{file:string, days:number}}
+ * Read the local daily cube rollup written by the dashboard/watch pipeline
+ * and fold it into one JSONL line per date. Provider/model detail stays
+ * LOCAL; the synced line is deliberately coarse so the shared folder (or
+ * server) leaks minimum information.
+ * @param {object} cfg loaded config
+ * @param {string} id this machine's id
+ * @param {string} cubeFile path to data/cube.json, already known to exist
+ * @returns {string[]} one JSON-encoded line per date, oldest first
  */
-export function push(opt = {}) {
-  const cfg = opt.config || loadConfig();
-  if (!isEnabled(cfg)) throw new Error('sync is disabled (sync.enabled: false)');
-  const dir = ensureDir(cfg);
-
-  // Read the local daily cube rollup written by the dashboard/watch pipeline.
-  const cubeFile = `${paths().data}/cube.json`;
-  if (!fs.existsSync(cubeFile)) return { file: null, days: 0 };
-
+function computeDailyLines(cfg, id, cubeFile) {
   const cube = JSON.parse(fs.readFileSync(cubeFile, 'utf8'));
   const dims = cube.dims;
   const di = dims.indexOf('d');           // date
-  const pi = dims.indexOf('p');           // provider
   const off = dims.length;
   const mIn = off + cube.measures.indexOf('in');
   const mOut = off + cube.measures.indexOf('out');
   const mReq = off + cube.measures.indexOf('req');
   const mCost = off + cube.measures.indexOf('cost');
 
-  // Aggregate rows → one record per (date): totals across providers/models.
-  // Provider/model detail stays LOCAL; the synced file is deliberately coarse
-  // so the shared folder leaks minimum information.
   const byDay = new Map();
   for (const r of cube.rows) {
     const day = r[di];
@@ -91,12 +110,11 @@ export function push(opt = {}) {
     acc.estCost += r[mCost] || 0;
   }
 
-  const id = machineId();
   const name = sanitizeName(cfg.sync.machineName || os.hostname().split('.')[0]);
   // Developer identity is included ONLY when the user explicitly set
   // sync.developerName in their own config. Absent field = anonymous machine.
   const dev = cfg.sync.developerName ? sanitizeName(cfg.sync.developerName) : null;
-  const lines = [...byDay.values()]
+  return [...byDay.values()]
     .sort((a, b) => a.date.localeCompare(b.date))
     .map((d) => JSON.stringify({
       machineId: id, machineName: name,
@@ -106,12 +124,131 @@ export function push(opt = {}) {
       requests: d.requests, estCostUsd: Math.round(d.estCost * 10000) / 10000,
       exportedAt: new Date().toISOString(),
     }));
+}
+
+/** `sync.receipts: false` is the only way to skip the ledger file; absent = on. */
+function receiptsAllowed(cfg) {
+  return cfg?.sync?.receipts !== false;
+}
+
+/**
+ * The whole-state receipts ledger for this machine: cost per (repo, branch),
+ * joined to a PR when one is known. Sourced entirely from
+ * buildReceiptsForStore() — this module never re-derives cost or reads a
+ * session transcript itself.
+ * @param {object} cfg loaded config
+ * @param {string} id this machine's id
+ * @returns {object} the JSON-serializable payload, allowlisted fields only
+ */
+function buildReceiptsPayload(cfg, id) {
+  const pricing = readJson(paths().pricing, {});
+  const store = new Store();
+  const built = buildReceiptsForStore(store, pricing);
+  const receipts = [];
+  for (const R of built.repos) {
+    const repo = path.basename(R.repo || 'unknown');
+    for (const b of R.branches) {
+      receipts.push({
+        repo,
+        branch: b.key,
+        costUsd: b.cost,
+        turns: b.turns,
+        sessions: b.sessions,
+        subagentTurns: b.subagentTurns,
+        contextShare: b.contextShare,
+        first: b.first,
+        last: b.last,
+        longLived: b.longLived,
+        pr: b.pr ? { number: b.pr.number, mergedAt: b.pr.mergedAt ?? null } : null,
+      });
+    }
+  }
+  // Unlike the jsonl rollup (which always carries a hostname fallback), the
+  // machine label here is opt-in only — this file joins branch/PR identity,
+  // so it stays anonymous unless the user chose a label themselves.
+  const name = cfg?.sync?.machineName ? sanitizeName(cfg.sync.machineName) : null;
+  return {
+    schema: 1,
+    machineId: id,
+    ...(name ? { machineName: name } : {}),
+    generatedAt: new Date().toISOString(),
+    receipts,
+  };
+}
+
+/**
+ * Export this machine's daily rollups (and, unless disabled, its receipts
+ * ledger) to the shared folder, or POST both to a server when `to`/
+ * `sync.to` is set.
+ *
+ * Stays synchronous for the folder path (existing callers rely on getting
+ * `{file, days}` back immediately, not a Promise). The moment a destination
+ * server is configured, a network call is unavoidable, so that branch alone
+ * returns a Promise — `await push(...)` works either way.
+ * @param {{config?: object, to?: string|null, token?: string|null}} opt
+ * @returns {{file:string|null, days:number}|Promise<{file:null, days:number, pushedTo:string}>}
+ */
+export function push(opt = {}) {
+  const cfg = opt.config || loadConfig();
+  const id = machineId();
+  const to = opt.to || cfg?.sync?.to || null;
+  const token = opt.token || cfg?.sync?.token || process.env.TOKENFLOW_SYNC_TOKEN || null;
+
+  if (to) return pushToServer({ cfg, id, to, token });
+
+  if (!isEnabled(cfg)) throw new Error('sync is disabled (sync.enabled: false)');
+  const dir = ensureDir(cfg);
+
+  const cubeFile = `${paths().data}/cube.json`;
+  if (!fs.existsSync(cubeFile)) return { file: null, days: 0 };
 
+  const lines = computeDailyLines(cfg, id, cubeFile);
   const file = path.join(dir, `${id}.jsonl`);
   fs.writeFileSync(file, lines.join('\n') + (lines.length ? '\n' : ''));
+
+  if (receiptsAllowed(cfg)) {
+    const receiptsFile = path.join(dir, `${id}.receipts.json`);
+    fs.writeFileSync(receiptsFile, JSON.stringify(buildReceiptsPayload(cfg, id), null, 2));
+  }
+
   return { file, days: lines.length };
 }
 
+/**
+ * The remote-destination branch of push(): same two files' contents, POSTed
+ * instead of written to a folder.
+ * @param {{cfg:object, id:string, to:string, token:string|null}} args
+ * @returns {Promise<{file:null, days:number, pushedTo:string}>}
+ */
+async function pushToServer({ cfg, id, to, token }) {
+  if (cfg?.sync?.enabled !== true) throw new Error('sync is disabled (sync.enabled: false)');
+  if (!/^https?:\/\//i.test(to)) throw new Error(`sync.to must be an http(s) URL, got: ${to}`);
+
+  const cubeFile = `${paths().data}/cube.json`;
+  const lines = fs.existsSync(cubeFile) ? computeDailyLines(cfg, id, cubeFile) : [];
+  const files = { [`${id}.jsonl`]: lines.join('\n') + (lines.length ? '\n' : '') };
+  if (receiptsAllowed(cfg)) {
+    files[`${id}.receipts.json`] = JSON.stringify(buildReceiptsPayload(cfg, id), null, 2);
+  }
+
+  const url = `${to.replace(/\/+$/, '')}/api/rollup`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+    },
+    body: JSON.stringify({ machineId: id, files }),
+  });
+  if (!res.ok) {
+    // Drain the body so the connection can be reused, but never surface it —
+    // a server's error page is not ours to print.
+    try { await res.text(); } catch { /* ignore */ }
+    throw new Error(`sync push to ${to} failed: ${res.status} ${res.statusText}`);
+  }
+  return { file: null, days: lines.length, pushedTo: to };
+}
+
 /**
  * Merge every sibling machine's file into combined daily totals.
  * @returns {{machines: string[], days: Array}}

package/src/export/html-snapshot.js

@@ -24,9 +24,36 @@ function candidatePorts() {
   return [...new Set([configured, 7799, 7800, 8799].filter(Boolean))];
 }
 
+/**
+ * The base stylesheet followed by every registered view's stylesheet, in name
+ * order, concatenated in the same sequence the live page links them.
+ *
+ * The dev page gets these as one `<link>` per view, injected by app.js. A
+ * snapshot has no server to fetch them from, so they are inlined here instead —
+ * miss this and every registered tab loses its styles the moment the file is
+ * saved. Order matters: view rules must be able to override the base.
+ *
+ * @param {string} root repository root
+ * @returns {string}
+ */
+function collectCss(root) {
+  const uiDir = path.join(root, 'src', 'ui');
+  const parts = [fs.readFileSync(path.join(uiDir, 'styles.css'), 'utf8')];
+  const viewCssDir = path.join(uiDir, 'styles');
+  let files = [];
+  try {
+    files = fs.readdirSync(viewCssDir).filter((f) => f.endsWith('.css')).sort();
+  } catch { /* no per-view stylesheets yet: the base sheet is the whole answer */ }
+  for (const f of files) {
+    parts.push(`/* --- ${path.posix.join('src/ui/styles', f)} --- */`);
+    parts.push(fs.readFileSync(path.join(viewCssDir, f), 'utf8'));
+  }
+  return parts.join('\n');
+}
+
 export function buildSnapshot({ maxRecords = 20000, title = 'Tokenflow' } = {}) {
   const ROOT = rootDir();
-  const css = fs.readFileSync(path.join(ROOT, 'src', 'ui', 'styles.css'), 'utf8');
+  const css = collectCss(ROOT);
   const html = fs.readFileSync(path.join(ROOT, 'src', 'ui', 'index.html'), 'utf8');
   const js = bundle(path.join(ROOT, 'src', 'ui', 'app.js'), { root: ROOT });
   // A snapshot that does not parse is worse than a failed export, so check the

package/src/export/menubar.js

@@ -103,6 +103,27 @@ export function renderXbar(status, opt = {}) {
     }
   }
 
+  // ---- live sessions --------------------------------------------------------
+  // Older status.json files (written before this field existed) simply lack
+  // it, so this whole block is null-guarded rather than assumed present.
+  const live = status.liveSessions?.sessions || [];
+  if (live.length) {
+    lines.push('---');
+    lines.push(`Live now (${live.length}) | font-size=11`);
+    for (const s of live.slice(0, 3)) {
+      const glyph = GLYPH[s.guard?.level] || '';
+      const where = s.project || s.repository || s.branch || '';
+      lines.push(`${glyph}${s.model || 'session'}${where ? ` · ${where}` : ''}${s.costUsd != null ? ` · ${money(s.costUsd)}` : ''} | font-size=12`);
+    }
+  }
+
+  // ---- guard ------------------------------------------------------------
+  const guard = status.guard?.lastVerdict;
+  if (guard && guard.level !== 'ok') {
+    lines.push('---');
+    lines.push(`${GLYPH[guard.level] || ''}Guard: ${guard.reasons?.[0] || guard.level} | font-size=12`);
+  }
+
   // ---- freshness + actions ------------------------------------------------
   lines.push('---');
   const fr = status.freshness || {};