@vimoxshah/tokenflow 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to TokenFlow are recorded here. Versions follow
+[semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## 1.1.1 — 2026-09-03
+
+A reliability release. Five defects had combined to leave the app paused, the
+dashboard unreachable, the stop button inert, one day's token total inflated by
+37 billion — and the alert that would have caught it ranked out of sight.
+
+### Fixed
+
+- **The watcher refused to start after a reboot.** The lock file held a bare
+  PID, and PID numbers restart and get reused at every boot, so a lock that
+  outlived a restart kept naming a live process — just not ours. One left at
+  pid 810 was inherited by `mobilerepaird`; `kill(810, 0)` went on succeeding
+  and every `tokenflow watch` refused to start, from the launch agent and the
+  menu bar's play button alike. The data went stale behind a phantom. The lock
+  now records the boot its PID was issued by, so a pidfile from an earlier boot
+  is stale by construction. A watcher that fails to start now reports why
+  instead of failing silently.
+- **The Dashboard button opened a closed port.** It opened
+  `http://127.0.0.1:<port>` whether or not anything was serving. It now starts
+  the server when none is running, shows progress while the data bundle builds,
+  and reports a failure. `tokenflow dashboard` also binds the port from
+  `config.yaml` rather than a hardcoded default, and a second invocation opens
+  the window instead of failing on a busy port.
+- **The stop button never stopped anything.** A `KeepAlive: true` launch agent
+  restarts the job after *any* exit, including the clean one a deliberate stop
+  produces — measured at about two seconds. The supported agent uses
+  `KeepAlive: { SuccessfulExit: false }`: a crash comes back, a stop stays
+  stopped.
+- **The Hermes adapter invented usage that never happened.**
+  `session_model_usage` is keyed on six columns and the adapter's bookkeeping
+  key used four, omitting `billing_base_url` and `billing_mode`. Two real rows
+  differing only in billing mode shared one entry, each computed its delta
+  against the other's totals, and every refresh cycle re-emitted the difference
+  under a fresh id. Five colliding sessions turned one day into 39.9B tokens —
+  a figure that grew with the number of refresh cycles rather than with usage.
+  The key is now the table's whole primary key, and the tail is a high-water
+  mark, so a total that comes back lower can never manufacture usage.
+- **The alert that caught it was buried.** That corruption was detected the day
+  it began: 240× the 60-day median, a modified z-score of 170.9, severity high.
+  Severity saturates at "high" around z=6 and the list then sorted by date, so
+  the outlier ranked third behind two request spikes of z=6.5 and z=11.2 from
+  later in the week — and the menu bar shows the top two. Anomalies of a
+  different order now outrank recency; ordinary alerts still read newest-first.
+
+### Added
+
+- `tokenflow watch --install-agent` — keeps the watcher running across reboots,
+  supervised by launchd. `--uninstall-agent` removes it. Installing replaces any
+  other agent that runs a watcher, because two of them fight over the same lock
+  for ever. `tokenflow watch --status` now reports the agent's state and warns
+  about conflicts.
+- `tokenflow reset --source <id> --yes` — forget one source and re-read it from
+  scratch on the next refresh, leaving every other source untouched. This is the
+  repair path for a store holding data from an adapter that has since been
+  fixed.
+
+### Changed
+
+- `tokenflow setup` now installs the watcher agent on macOS, so live data works
+  without hand-rolling a LaunchAgent. `--no-agent` opts out, and the install is
+  announced rather than silent. On other platforms it prints the systemd/cron
+  equivalent instead.
+- A dead watcher no longer leaves its identity in the status file, so a paused
+  TokenFlow cannot report itself as live.
+
+### Repairing an affected store
+
+A store that ingested the inflated Hermes records keeps them until it is told
+to re-read the source:
+
+```sh
+tokenflow reset --source hermes --yes
+tokenflow refresh
+```
+
+The Hermes database still holds the truth, so nothing is lost. On the corpus
+this was found on, the re-read reconciled exactly — 1,568 source rows to 1,568
+records, every token field matching — and the affected day fell from 39.9B to
+2.35B, with usage returning to the days it actually happened on.

package/README.md

@@ -25,6 +25,16 @@
 <p align="center"><em>The native macOS menu bar popover — live cost, tokens, per-provider,
 per-source and per-model usage, capacity meters and forecast, in light and dark.</em></p>
 
+<p align="center">
+  🌐 <a href="https://vimoxshah.github.io/tokenflow/"><strong>Landing page</strong></a>
+  &nbsp;·&nbsp;
+  🖥️ <a href="https://vimoxshah.github.io/tokenflow/demo/"><strong>Live demo</strong></a> <em>(synthetic data)</em>
+  &nbsp;·&nbsp;
+  📦 <a href="https://www.npmjs.com/package/@vimoxshah/tokenflow"><code>@vimoxshah/tokenflow</code> on npm</a>
+  &nbsp;·&nbsp;
+  🍺 <code>brew install --cask tokenflow</code> (via <a href="https://github.com/vimoxshah/tokenflow">this tap</a>)
+</p>
+
 **How deep it goes**
 
 | Layer | What's inside |
@@ -38,9 +48,44 @@ per-source and per-model usage, capacity meters and forecast, in light and dark.
 
 Zero runtime dependencies. Nothing leaves your machine. No API keys, no accounts, no telemetry.
 
+## Uninstall
+
+```bash
+# macOS app
+brew uninstall --cask tokenflow        # if installed via the tap
+# otherwise: quit TokenFlow, drag /Applications/TokenFlow.app to Trash
+
+# CLI / npm
+npm uninstall -g @vimoxshah/tokenflow  # if installed globally
+
+# data (everything local: config, records, digests, state)
+rm -rf ~/.tokenflow
+
+# optional extras you may have installed
+launchctl unload ~/Library/LaunchAgents/app.tokenflow.digest.plist 2>/dev/null
+rm -f ~/Library/LaunchAgents/app.tokenflow.digest.plist
+launchctl unload ~/Library/LaunchAgents/app.tokenflow.bar.plist 2>/dev/null
+rm -f ~/Library/LaunchAgents/app.tokenflow.bar.plist
+```
+
+Nothing is stored anywhere else. Deleting `~/.tokenflow` and the app removes every trace.
+
 ### Install
 
-**macOS app** — download `TokenFlow-*.dmg` from the
+**Homebrew (macOS)** — the one-liner:
+
+```bash
+brew tap vimoxshah/tap https://github.com/vimoxshah/tokenflow
+brew install --cask tokenflow
+```
+
+**npm (macOS, Linux, Windows)** — CLI + dashboard, no app bundle:
+
+```bash
+npx @vimoxshah/tokenflow@latest setup
+```
+
+**macOS app (manual)** — download `TokenFlow-*.dmg` from the
 [**latest release**](https://github.com/vimoxshah/tokenflow/releases/latest) (each release also
 carries `tokenflow-dashboard-demo.html`, an offline demo dashboard that opens in any browser).
 Open the DMG, drag **TokenFlow.app** to Applications, launch from Launchpad.
@@ -156,6 +201,7 @@ node bin/tokenflow.js models-compare # cost/usage efficiency per model — your
 node bin/tokenflow.js budget --set 200   # monthly cap + forecast alerts (fires once per state/month)
 node bin/tokenflow.js schedule --install --at "Monday 09:00"  # weekly digest via launchd
 node bin/tokenflow.js diagnostics    # local observability — nothing transmitted
+node bin/tokenflow.js team           # per-developer team view (needs sync + opt-in names)
 node bin/tokenflow.js up             # refresh → rebuild offline HTML → serve + open
 
 npm link                             # optional: global `tokenflow` command
@@ -237,6 +283,9 @@ discard the rest. No telemetry. Two features can touch the network, both strictl
 - **Multi-machine sync** (`sync:` in config) — exchanges daily totals (date, tokens, requests,
   est. cost) with a folder you own (iCloud/Dropbox/Syncthing). Never prompts, code, credentials.
   Default is OFF; nothing leaves this machine until you set `sync.enabled: true`.
+- **Team view** (`tokenflow team`) — per-developer usage from that same shared folder. A name
+  appears next to a machine only if its owner set `sync.developerName` themselves; machines
+  without it stay anonymous and are excluded from per-person rows.
 - **Prompt analytics** (`promptAnalytics:` in config) — OFF by default; even when enabled, only
   one-way prompt hashes and keyword categories are stored. Raw text requires a separate opt-in.
 - **Map location** (`map.showMyLocation: true`) — one cached IP geolocation of this machine to

package/bin/tokenflow.js

@@ -29,7 +29,7 @@ import {
   buildLiveStatus, currentStatus, readLiveStatus, withComputedFreshness, barLine,
 } from '../src/core/live-status.js';
 import {
-  startWatch, runCycle, stopWatch, watchIsRunning, releaseWatchLock,
+  startWatch, runCycle, stopWatch, watchIsRunning, releaseWatchLock, readLock,
 } from '../src/core/watch.js';
 import { renderXbar, installSwiftBarPlugin } from '../src/export/menubar.js';
 
@@ -85,6 +85,7 @@ async function main() {
     case 'sync': return cmdSync();
     case 'models-compare': return cmdModelsCompare();
     case 'diagnostics': return cmdDiagnostics();
+    case 'team': return cmdTeam();
     default:
       console.error(`${C.red}Unknown command "${cmd}".${C.r}\n`);
       return help(1);
@@ -125,10 +126,38 @@ async function cmdSetup() {
 
   console.log(`\n${C.g}✓${C.r} wrote ${file}`);
   console.log(`  enabled providers: ${detected.length ? detected.join(', ') : '(none)'}`);
-  console.log(`  timezone: ${cfg.timezone}\n`);
+  console.log(`  timezone: ${cfg.timezone}`);
+  await setupWatchAgent();
   console.log(`Next:  ${C.c}tokenflow refresh${C.r}   then   ${C.c}tokenflow dashboard${C.r}\n`);
 }
 
+/**
+ * Set up the watcher to run by default, because "live" is the point.
+ *
+ * Installing a login agent is a real side effect, so it is announced and
+ * `--no-agent` opts out. On anything other than macOS it prints the hint and
+ * does nothing.
+ */
+async function setupWatchAgent() {
+  if (flags.agent === false || flags['no-agent'] === true) {
+    console.log(`  ${C.dim}watcher agent: skipped (--no-agent). Install later: tokenflow watch --install-agent${C.r}\n`);
+    return;
+  }
+  const agent = await import('../src/core/watch-agent.js');
+  if (!agent.supported()) {
+    console.log(`  ${C.dim}watcher: run 'tokenflow watch' from a systemd --user unit, or 'watch --once' from cron${C.r}\n`);
+    return;
+  }
+  try {
+    const r = agent.install();
+    for (const f of r.removed) console.log(`  ${C.y}!${C.r} removed a conflicting watcher agent: ${f.label}`);
+    console.log(`${C.g}✓${C.r} the watcher now starts at login ${C.dim}(tokenflow watch --uninstall-agent removes it)${C.r}\n`);
+  } catch (err) {
+    console.log(`  ${C.y}! could not install the watcher agent: ${err.message}${C.r}`);
+    console.log(`  ${C.dim}run it by hand with 'tokenflow watch', or retry with 'tokenflow watch --install-agent'${C.r}\n`);
+  }
+}
+
 // ================================================================ providers ==
 
 async function cmdProviders() {
@@ -281,16 +310,43 @@ async function cmdStatus() {
 // ================================================================ dashboard ==
 
 async function cmdDashboard() {
-  const port = Number(flags.port) || 7799;
+  const cfg = loadConfig();
+  // The configured port is the one every other surface opens — the menu bar
+  // reads it straight out of config.yaml — so the server must bind THAT port
+  // rather than a hardcoded default the rest of the app has never heard of.
+  const port = Number(flags.port) || Number(cfg.ui?.port) || 7799;
   const host = flags.host || '127.0.0.1';
+  const wantOpen = flags.open !== false && flags['no-open'] !== true;
+
+  // Already serving? Then this invocation is a second Dashboard click, not a
+  // failure. Open the window and leave the running server alone.
+  const { pingServer } = await import('../src/server/server.js');
+  const alive = await pingServer({ host, port });
+  if (alive) {
+    const url = `http://${host}:${port}`;
+    console.log(`\n  ${C.b}Tokenflow${C.r} ${C.dim}already serving${C.r}`);
+    console.log(`  ${C.c}${url}${C.r}`);
+    console.log(`  ${C.dim}${int(alive.records)} records · started elsewhere · loopback only${C.r}\n`);
+    if (wantOpen) tryOpen(url);
+    return;
+  }
+
   const b = buildBundle();
-  const s = await startServer({ port, host, token: flags.token === false ? false : undefined });
+  let s;
+  try {
+    s = await startServer({ port, host, token: flags.token === false ? false : undefined });
+  } catch (err) {
+    if (err.code !== 'EADDRINUSE') throw err;
+    throw Object.assign(new Error(`port ${port} is busy, and whatever holds it is not TokenFlow`), {
+      hint: `Free it, or pick another port:  tokenflow dashboard --port ${port + 1}`,
+    });
+  }
   console.log(`\n  ${C.b}Tokenflow${C.r}`);
   console.log(`  ${C.c}${s.url}${C.r}`);
   console.log(`  ${C.dim}${int(b.health.records)} records · ${b.health.coverage.from ? `${shortDate(b.health.coverage.from)} → ${shortDate(b.health.coverage.to)}` : 'no data'} · loopback only, nothing leaves this machine${C.r}`);
   if (!b.health.records) console.log(`  ${C.y}No data yet — click ↻ Refresh in the dashboard, or run 'tokenflow refresh'.${C.r}`);
   console.log(`  ${C.dim}Ctrl+C to stop${C.r}\n`);
-  if (flags.open !== false && flags['no-open'] !== true) tryOpen(s.url);
+  if (wantOpen) tryOpen(s.url);
   await new Promise(() => {});
 }
 
@@ -611,6 +667,17 @@ function safeReaddir(d) {
 // ===================================================================== demo ==
 
 async function cmdDemo() {
+  // Synthetic data must never mix into a real store: `demo` used to overwrite
+  // ~/.tokenflow/config.yaml with providers:['mock'] and ingest demo records
+  // into whatever home was active. An explicit $TOKENFLOW_HOME wins (scripted
+  // setups that want exactly that); otherwise a throwaway home under tmpdir()
+  // is created for this run, leaving the default store untouched.
+  if (!process.env.TOKENFLOW_HOME) {
+    const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'tokenflow-demo-'));
+    process.env.TOKENFLOW_HOME = sandbox;
+    console.log(`\n  ${C.dim}sandboxed demo store: ${sandbox}`);
+    console.log(`  reopen later with:   TOKENFLOW_HOME=${sandbox} tokenflow dashboard${C.r}`);
+  }
   process.env.TOKENFLOW_DEMO = '1';
   const cfg = loadConfig();
   cfg.providers = ['mock'];
@@ -757,8 +824,10 @@ async function cmdRestore() {
 }
 
 async function cmdReset() {
+  const only = typeof flags.source === 'string' ? flags.source : null;
+  if (only) return resetOneSource(only);
   if (!flags.yes) {
-    throw Object.assign(new Error('this deletes all ingested data'), { hint: `re-run with --yes to confirm. Config and pricing are kept. Data home: ${paths().root}` });
+    throw Object.assign(new Error('this deletes all ingested data'), { hint: `re-run with --yes to confirm. Config and pricing are kept. Data home: ${paths().root}\n  To re-ingest a single source instead:  tokenflow reset --source <id> --yes` });
   }
   const p = paths();
   fs.rmSync(p.data, { recursive: true, force: true });
@@ -766,6 +835,48 @@ async function cmdReset() {
   console.log(`${C.g}✓${C.r} cleared ${p.data} (config and pricing kept)`);
 }
 
+/**
+ * Forget one source and let the next refresh re-read it from scratch.
+ *
+ * This is the repair path for an adapter bug: the source's own logs or
+ * database still hold the truth, so dropping what was ingested from it and
+ * clearing its cursor re-derives that source correctly while every other
+ * source's records stay exactly as they are.
+ */
+async function resetOneSource(id) {
+  const store = new Store();
+  const known = Object.keys(store.state.sources || {});
+  const held = store.state.sources?.[id]?.records ?? null;
+  if (!known.includes(id)) {
+    throw Object.assign(new Error(`no ingested source called '${id}'`), {
+      hint: known.length ? `the store holds: ${known.sort().join(', ')}` : 'the store is empty — nothing to reset',
+    });
+  }
+  if (!flags.yes) {
+    throw Object.assign(new Error(`this drops every record ingested from '${id}'${held ? ` (${int(held)} at last count)` : ''}`), {
+      hint: `The next refresh re-reads ${id} from its own source, so nothing is lost that the source still knows. Re-run with --yes to confirm.`,
+    });
+  }
+  const { dropSourceRecords } = await import('../src/core/store.js');
+  const { rebuildAggregates } = await import('../src/core/ingest.js');
+
+  const res = dropSourceRecords(store, id);
+  delete store.state.sources[id];
+  const rb = rebuildAggregates(store);
+  store.state.counters.records = rb.records;
+  for (const sid of Object.keys(store.state.sources)) store.state.sources[sid].records = rb.bySource[sid] || 0;
+  store.saveCube();
+  store.saveSessions();
+  store.saveActivity();
+  store.saveState();
+
+  console.log(`  ${C.g}✓${C.r} dropped ${int(res.dropped)} record(s) from '${id}' across ${res.shards} shard(s)`);
+  console.log(`  ${C.g}✓${C.r} cleared its cursor — the next refresh re-reads it from the beginning`);
+  console.log(`  ${C.g}✓${C.r} rebuilt aggregates from the remaining ${int(rb.records)} record(s)`);
+  for (const [sid, n] of Object.entries(rb.bySource).sort((a, b) => b[1] - a[1])) console.log(`      ${sid.padEnd(12)} ${int(n).padStart(9)}`);
+  console.log(`\n  ${C.dim}next:  tokenflow refresh${C.r}\n`);
+}
+
 // ==================================================================== live ==
 
 /** Fast path for live commands: watch snapshot when fresh, else compute now. */
@@ -783,7 +894,36 @@ async function liveStatus() {
  *   --status        is a watcher running? how fresh is it?
  *   --stop          stop a running watcher
  */
+/**
+ * `tokenflow watch --install-agent` / `--uninstall-agent`.
+ *
+ * Live data needs a resident watcher. Without an agent one only lasts as long
+ * as the session that started it, so a reboot leaves stale numbers behind a
+ * paused menu bar.
+ */
+async function watchAgentCommand() {
+  const agent = await import('../src/core/watch-agent.js');
+  if (flags['uninstall-agent']) {
+    const r = agent.uninstall();
+    console.log(r.removed
+      ? `  ${C.g}✓${C.r} removed the watcher agent ${C.dim}(${r.plist})${C.r}\n  ${C.dim}the watcher no longer starts at login; 'tokenflow watch' still runs by hand.${C.r}\n`
+      : `  ${C.dim}○ no watcher agent was installed${C.r}\n`);
+    return;
+  }
+  const r = agent.install();
+  for (const f of r.removed) {
+    console.log(`  ${C.y}!${C.r} removed a conflicting agent: ${C.b}${f.label}${C.r}`);
+    console.log(`      ${C.dim}${f.file} — two agents running a watcher fight over the same lock${C.r}`);
+  }
+  console.log(`  ${C.g}✓${C.r} installed the watcher agent ${C.dim}(${r.plist})${C.r}`);
+  console.log(`  ${C.dim}starts at login · restarts on a crash · a deliberate stop stays stopped${C.r}`);
+  console.log(`  ${C.dim}log: ${paths().root}/watch.log${C.r}`);
+  if (!r.started) console.log(`  ${C.y}!${C.r} launchctl would not start it — check Console.app, or run 'tokenflow watch' by hand`);
+  console.log(`\n  ${C.dim}remove it:  tokenflow watch --uninstall-agent${C.r}\n`);
+}
+
 async function cmdWatch() {
+  if (flags['install-agent'] || flags['uninstall-agent']) return watchAgentCommand();
   if (flags.stop) {
     const r = stopWatch();
     console.log(r.stopped ? `${C.g}✓${C.r} stopped watcher ${C.dim}(pid ${r.pid})${C.r}` : `${C.dim}○ ${r.reason}${C.r}`);
@@ -794,9 +934,17 @@ async function cmdWatch() {
     const st = readLiveStatus();
     console.log(`  watcher   ${running ? `${C.g}running${C.r}` : `${C.dim}not running${C.r}`}`);
     // Identity lines only describe a live process — a dead watcher's leftovers
-    // are history, not status.
-    if (running && st?.watcher?.pid != null) {
-      console.log(`  pid       ${st.watcher.pid} · every ${st.watcher.intervalSeconds ?? '?'}s · ${int(st.watcher.cycles)} cycle(s)`);
+    // are history, not status. The PID comes from the LOCK, which is the only
+    // thing that knows who holds it; the cycle count comes from the status
+    // file, and only when that file was written by this same watcher. After a
+    // restart the two disagree for one cycle, and reporting the dead PID then
+    // would be exactly the kind of small lie that hid a stale watcher before.
+    const lock = running ? readLock() : null;
+    if (lock) {
+      const own = st?.watcher?.pid === lock.pid ? st.watcher : null;
+      const every = own?.intervalSeconds ?? st?.watcher?.intervalSeconds ?? '?';
+      const cycles = own ? `${int(own.cycles)} cycle(s)` : 'first cycle pending';
+      console.log(`  pid       ${lock.pid} · every ${every}s · ${cycles}`);
     }
     const lastErr = st?.lastError;
     if (lastErr) console.log(`  ${C.y}last error${C.r} ${relativeTime(lastErr.at)}: ${lastErr.message}`);
@@ -805,6 +953,22 @@ async function cmdWatch() {
       console.log(`  data      ${fresh.stale ? `${C.y}stale${C.r}` : `${C.g}fresh${C.r}`} ${st.freshness.lastRefresh ? `· updated ${relativeTime(st.freshness.lastRefresh)}` : '(never refreshed)'}`);
       console.log(`  status    ${paths().status}`);
     }
+    const agent = await import('../src/core/watch-agent.js');
+    if (agent.supported()) {
+      const a = agent.status();
+      const state = !a.installed ? `${C.dim}not installed${C.r}`
+        : a.loaded ? `${C.g}installed${C.r} ${C.dim}· starts at login, restarts on crash${C.r}`
+          : `${C.y}installed but not loaded${C.r}`;
+      console.log(`  agent     ${state}`);
+      if (!a.installed) console.log(`            ${C.dim}install it:  tokenflow watch --install-agent${C.r}`);
+      // Two agents running a watcher means the loser exits and respawns for
+      // ever; say so rather than letting it churn quietly in the log.
+      for (const f of a.foreign) {
+        console.log(`  ${C.y}!${C.r} another agent also runs a watcher: ${f.label}`);
+        console.log(`            ${C.dim}${f.file}${C.r}`);
+        console.log(`            ${C.dim}'tokenflow watch --install-agent' replaces it with the supported one.${C.r}`);
+      }
+    }
     if (!running && !flags.json) {
       console.log(`\n  ${C.dim}start one:  tokenflow watch${C.r}`);
     }
@@ -1146,6 +1310,33 @@ async function cmdDiagnostics() {
   }
 }
 
+/** `tokenflow team` — per-developer usage from the shared sync folder (P4-B). */
+async function cmdTeam() {
+  const cfg = loadConfig();
+  if (!cfg.sync?.enabled || !cfg.sync?.dir) {
+    console.error(`${C.red}Team view reads the shared sync folder.${C.r}
+Enable multi-machine sync first — every team member points at the SAME folder:
+
+  sync:
+    enabled: true
+    dir: /path/to/shared/TokenFlow      # same folder for everyone
+    machineName: MacBook Pro            # this machine's label
+    developerName: Your Name            # ← opt-in per person; omit to stay anonymous
+
+Then run \`tokenflow sync\` on each machine and \`tokenflow team\` here.`);
+    return;
+  }
+  const { aggregate, renderText } = await import('../src/core/team.js');
+  const dir = cfg.sync.dir.replace(/^~(?=$|\/)/, os.homedir());
+  const t = aggregate(dir, {
+    from: typeof flags.from === 'string' ? flags.from : null,
+    to: typeof flags.to === 'string' ? flags.to : null,
+    includeAnonymous: !!flags['include-anonymous'],
+  });
+  if (flags.json) { console.log(JSON.stringify(t, null, 2)); return; }
+  console.log(renderText(t));
+}
+
 async function cmdMenubar() {
   const mode = String(flags.mode || loadConfig().ui?.menubarMode || 'auto');
 
@@ -1244,6 +1435,9 @@ function help(code = 0) {
     tokenflow watch --once          one cycle and exit (cron-friendly)
     tokenflow watch --status        is a watcher running? how fresh is the data?
     tokenflow watch --stop          stop a running watcher
+    tokenflow watch --install-agent keep the watcher running across reboots
+                                   (installed by default at setup on macOS;
+                                    --uninstall-agent removes it)
     tokenflow usage                 today / week / month tokens & cost (--json)
     tokenflow cost                  estimated vs measured spend, projections
     tokenflow capacity              configured limits: %, burn, reset countdowns
@@ -1263,6 +1457,21 @@ function help(code = 0) {
     tokenflow export --csv --all    every normalized record
     tokenflow export --html         one self-contained offline dashboard file
 
+  ${C.b}Intelligence${C.r}
+    tokenflow models-compare        cost/request, tokens/request, cache-hit% per model
+                                   (--from/--to <date> to pick the window)
+    tokenflow budget --set 200      monthly cap → projected-overrun alerts (dedup'd)
+    tokenflow budget                current state: safe / approaching / over
+    tokenflow digest --deliver      build "Your AI Week" and send via configured channels
+    tokenflow schedule --install --at "Monday 09:00"   weekly digest via launchd
+    tokenflow schedule --status     is the digest schedule installed?
+    tokenflow team                  per-developer usage from the shared sync folder
+    tokenflow diagnostics           version, providers, store freshness, feature states
+
+  ${C.b}Sync (optional, off by default)${C.r}
+    tokenflow sync                  push this machine's daily rollups + show merged view
+    tokenflow sync --off            disable sync entirely
+
   ${C.b}Configure${C.r}
     tokenflow pricing               show which models have a price, and from where
     tokenflow pricing --sources     provenance of every built-in rate + tier multipliers
@@ -1276,6 +1485,10 @@ function help(code = 0) {
     tokenflow validate              re-validate every stored record
     tokenflow compact               drop superseded records after a rewrite
     tokenflow reset --yes           delete ingested data (keeps config)
+    tokenflow reset --source <id> --yes
+                                   forget ONE source and re-read it from
+                                   scratch on the next refresh (repairs a
+                                   source whose adapter was fixed)
 
   ${C.b}Flags${C.r}  --json  --quiet  --provider <id>  --from/--to <date>  --port <n>  --no-open  --debug
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vimoxshah/tokenflow",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Local-first, provider-agnostic analytics for the AI tokens you actually spend. Zero dependencies, nothing leaves your machine.",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
     "examples",
     "scripts",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "SECURITY.md",
     "CONTRIBUTING.md",

package/src/analytics/anomalies.js

@@ -16,6 +16,18 @@
 const MAD_SCALE = 1.4826;
 const SPIKE_Z = 3.5;      // Iglewicz–Hoaglin threshold for a modified z-score
 const HIGH_Z = 6;         // well past that: call it high severity
+/**
+ * Far past "high": magnitude at this scale outranks recency in the list.
+ *
+ * Severity saturates at `high` around z=6, and the ordering below then falls
+ * back to date, newest first. That buried a real one: an adapter bug inflated
+ * one day to 240× its 60-day median, scoring z=171, and it ranked THIRD behind
+ * two request spikes of z=6.5 and z=11.2 from later in the week. The menu bar
+ * shows the top two alerts, so for a week the loudest signal the product had
+ * was the one thing it did not show. A z of 171 and a z of 6 are not the same
+ * news, whichever happened more recently.
+ */
+const EXTREME_Z = 25;
 const BASELINE_WINDOW = 60;
 const MIN_BASELINE = 10;
 
@@ -167,9 +179,14 @@ export function detectAnomalies(daily, opt = {}) {
   }
 
   const cap = opt.limit ?? 12;
+  // severity, then extremes by magnitude, then recency. Ordinary alerts keep
+  // reading as a feed; an outlier of a different order never gets buried in it.
+  const extreme = (a) => ((a.z ?? 0) >= EXTREME_Z ? 0 : 1);
   return out
     .sort((a, b) =>
       SEV_ORDER[a.severity] - SEV_ORDER[b.severity]
+      || extreme(a) - extreme(b)
+      || (extreme(a) === 0 ? (b.z ?? 0) - (a.z ?? 0) : 0)
       || (a.date < b.date ? 1 : a.date > b.date ? -1 : 0)
       || (b.z ?? 0) - (a.z ?? 0))
     .slice(0, cap);

package/src/commands/diagnostics.js

@@ -10,6 +10,19 @@ import os from 'node:os';
 import path from 'node:path';
 import { loadConfig, paths } from '../core/config.js';
 
+/**
+ * The shipped package.json is the only honest source for the version. A
+ * hardcoded fallback goes stale the moment anyone forgets it at release time,
+ * and then every diagnostics report quietly names the wrong release.
+ */
+function packageVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
 /**
  * @param {{includePaths?: boolean}} opt
  * @returns {object} diagnostics snapshot (plain JSON-able)
@@ -26,7 +39,7 @@ export function collect(opt = {}) {
   };
 
   return {
-    version: process.env.npm_package_version || '1.1.0',
+    version: process.env.npm_package_version || packageVersion(),
     node: process.version,
     platform: `${os.platform()} ${os.arch()} ${os.release()}`,
     timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,

package/src/core/live-status.js

@@ -22,6 +22,7 @@ import { loadConfig, paths, ensureDirs } from './config.js';
 import { readJson } from './store.js';
 import { compact, usd, countdown } from './units.js';
 import { detectMilestones } from '../analytics/milestones.js';
+import { lockIsLive, readLock } from './watch-lock.js';
 
 // Formatting adapters over the shared units.js formatters (which the browser
 // bundle also uses): null means "nothing to show", never "—", never 0.
@@ -324,8 +325,10 @@ export function withComputedFreshness(status, nowMs = Date.now()) {
  * The cache window derives from the watcher's own cadence (interval + slack),
  * because a snapshot written 90 seconds into a 120-second cycle is exactly as
  * current as the product promised — not stale. When a fallback compute does
- * happen, daemon identity (pid, cycles, last error) is carried over from the
- * cached file: a slow poll must never make the UI claim no watcher is running.
+ * happen, daemon identity (pid, cycles) is carried over from the cached file
+ * so a slow poll never makes the UI claim no watcher is running — but only
+ * while the watcher lock is actually live, so a dead daemon's identity does
+ * not linger either.
  */
 export function currentStatus(opt = {}) {
   const cached = readLiveStatus();
@@ -337,7 +340,15 @@ export function currentStatus(opt = {}) {
     if (age <= maxAgeMs) return { status: withComputedFreshness(cached), fromWatch: true };
   }
   const fresh = buildLiveStatus({ config: cfg });
-  if (cached?.watcher) fresh.watcher = cached.watcher;
+  // Carry daemon identity over ONLY while THAT daemon is really there. A
+  // watcher block outlives the process that wrote it, and repeating it after
+  // the watcher died is how a paused TokenFlow came to look live. Matching the
+  // pid against the lock holder also stops a restarted watcher from being
+  // described with its predecessor's pid and cycle count.
+  const lock = readLock();
+  if (cached?.watcher && lockIsLive(lock) && cached.watcher.pid === lock.pid) {
+    fresh.watcher = cached.watcher;
+  }
   if (!fresh.lastCycle && cached?.lastCycle) fresh.lastCycle = cached.lastCycle;
   if (!fresh.lastError && cached?.lastError) fresh.lastError = cached.lastError;
   return { status: fresh, fromWatch: false };