@vimoxshah/tokenflow 1.1.0 → 1.1.2

package/scripts/build-menubar-app.sh

@@ -4,8 +4,24 @@
 #   scripts/build-menubar-app.sh [output-dir]
 #
 # Compiles menubar/TokenFlow/main.swift with swiftc (Xcode Command Line Tools)
-# into a minimal .app bundle, embedding the absolute paths of this clone's
-# node binary and CLI so the app can drive refresh/watch actions.
+# into a minimal .app bundle.
+#
+# The CLI is ALWAYS bundled into Contents/Resources/cli, packed with `npm pack`
+# so the copy inside the app is byte-for-byte the published package rather than
+# a hand-picked subset of the working tree. The app drives that copy, which is
+# the only one guaranteed to match the binary it ships beside: the app and the
+# CLI share a contract (the status file, the watcher lock format, /api/ping),
+# and an unrelated CLI version next door is a mismatch nobody can reason about.
+#
+# Two build flavours:
+#
+#   local (default)      also embeds this clone's absolute node + CLI paths, so
+#                        a developer's installed app drives the checkout they
+#                        are editing.
+#   TOKENFLOW_PORTABLE=1 embeds NO absolute paths. Anything built for
+#                        distribution must use this: a release built on CI
+#                        otherwise ships /Users/runner/... in its Info.plist,
+#                        which exists on no user's machine.
 set -euo pipefail
 
 REPO="$(cd "$(dirname "$0")/.." && pwd)"
@@ -25,14 +41,40 @@ command -v swiftc >/dev/null 2>&1 || {
 NODE_BIN="$(command -v node)"
 CLI_JS="$REPO/bin/tokenflow.js"
 [ -f "$CLI_JS" ] || { echo "error: $CLI_JS missing" >&2; exit 1; }
+PORTABLE="${TOKENFLOW_PORTABLE:-0}"
 
 TMP="$(mktemp -d)"
 trap 'rm -rf "$TMP"' EXIT
 
+rm -rf "$APP"
 mkdir -p "$APP/Contents/MacOS"
 mkdir -p "$APP/Contents/Resources"
 cp "$REPO/menubar/TokenFlow/AppIcon.icns" "$APP/Contents/Resources/AppIcon.icns"
 
+# ---- bundle the CLI ---------------------------------------------------------
+# `npm pack` rather than copying bin/ and src/: the tarball is what npm
+# publishes, filtered by package.json "files", so the app can never ship a file
+# the package does not.
+echo "packing the CLI into the bundle"
+( cd "$REPO" && npm pack --silent --pack-destination "$TMP" >/dev/null )
+TGZ="$(ls "$TMP"/*.tgz | head -1)"
+[ -f "$TGZ" ] || { echo "error: npm pack produced no tarball" >&2; exit 1; }
+mkdir -p "$APP/Contents/Resources/cli"
+tar -xzf "$TGZ" -C "$APP/Contents/Resources/cli"
+BUNDLED_CLI="$APP/Contents/Resources/cli/package/bin/tokenflow.js"
+[ -f "$BUNDLED_CLI" ] || { echo "error: bundled CLI missing at $BUNDLED_CLI" >&2; exit 1; }
+
+# Keep only what the CLI actually executes. docs/, skills/, examples/ and
+# scripts/ are never read at runtime — they appear in printed hints and nothing
+# opens them — and they are four fifths of the tarball. Whatever remains still
+# came from `npm pack`, so the bundle is a subset of the published package and
+# never a file npm does not ship.
+( cd "$APP/Contents/Resources/cli/package" \
+  && rm -rf docs skills examples scripts \
+     README.md CONTRIBUTING.md SECURITY.md CHANGELOG.md "Refresh & Open Dashboard.command" )
+[ -f "$BUNDLED_CLI" ] || { echo "error: pruning removed the CLI" >&2; exit 1; }
+[ -d "$APP/Contents/Resources/cli/package/src" ] || { echo "error: pruning removed src/" >&2; exit 1; }
+
 cat > "$APP/Contents/Info.plist" <<PLIST
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -50,12 +92,19 @@ cat > "$APP/Contents/Info.plist" <<PLIST
     <key>LSUIElement</key>                  <true/>
     <key>NSHighResolutionCapable</key>      <true/>
     <key>NSHumanReadableCopyright</key>     <string>MIT — local-first, nothing leaves your machine.</string>
-    <key>TokenFlowNodePath</key>            <string>$NODE_BIN</string>
-    <key>TokenFlowCLIPath</key>             <string>$CLI_JS</string>
 </dict>
 </plist>
 PLIST
 
+# A distributable build embeds no machine-specific path. A local one does, so
+# the developer's installed app drives the clone they are working in.
+if [ "$PORTABLE" != "1" ]; then
+  /usr/libexec/PlistBuddy \
+    -c "Add :TokenFlowNodePath string $NODE_BIN" \
+    -c "Add :TokenFlowCLIPath string $CLI_JS" \
+    "$APP/Contents/Info.plist" >/dev/null
+fi
+
 echo "compiling with $(swiftc --version | head -1)"
 swiftc -O -swift-version 5 \
   -o "$APP/Contents/MacOS/TokenFlow" \
@@ -63,5 +112,5 @@ swiftc -O -swift-version 5 \
 
 codesign --force --sign - "$APP" >/dev/null 2>&1 || true
 
-SIZE=$(du -h "$APP" | cut -f1 | tr -d ' ')
-echo "built: $APP ($SIZE)"
+SIZE=$(du -sh "$APP" | cut -f1 | tr -d ' ')
+echo "built: $APP ($SIZE)$([ "$PORTABLE" = "1" ] && echo ' · portable, no embedded paths')"

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 };

package/src/core/store.js

@@ -442,6 +442,57 @@ export function compactShards(store) {
   return { kept, dropped, shards };
 }
 
+/**
+ * Physically remove one source's records from every shard.
+ *
+ * The stale-generation mechanism cannot do this job: it supersedes records
+ * per source FILE, and cursor-based sources (SQLite adapters) have no file to
+ * supersede. Re-ingesting such a source after fixing its adapter therefore
+ * needs its old records dropped outright, which is what `reset --source` does.
+ *
+ * @returns {{kept:number, dropped:number, shards:number}}
+ */
+export function dropSourceRecords(store, sourceId) {
+  let kept = 0;
+  let dropped = 0;
+  let shards = 0;
+  for (const shard of store.listShards()) {
+    const src = path.join(store.p.records, shard);
+    const tmp = src + '.drop';
+    let buf = '';
+    let shardDropped = 0;
+    const out = fs.openSync(tmp, 'w');
+    try {
+      readLines(src, (line) => {
+        let o;
+        try { o = JSON.parse(line); } catch { return; }
+        if (o.so === sourceId) { dropped++; shardDropped++; return; }
+        kept++;
+        buf += line + '\n';
+        if (buf.length > 1 << 20) { fs.writeSync(out, buf); buf = ''; }
+      });
+      if (buf) fs.writeSync(out, buf);
+    } finally {
+      fs.closeSync(out);
+    }
+    if (!shardDropped) {
+      // Nothing to change here — leave the shard untouched rather than
+      // rewriting it byte-for-byte and disturbing its mtime.
+      try { fs.rmSync(tmp, { force: true }); } catch { /* leave the temp file */ }
+      continue;
+    }
+    try {
+      fs.renameSync(tmp, src);
+    } catch (err) {
+      if (!['EPERM', 'EXDEV', 'EACCES', 'ENOTSUP'].includes(err.code)) throw err;
+      fs.writeFileSync(src, fs.readFileSync(tmp));
+      try { fs.rmSync(tmp, { force: true }); } catch { /* leave the temp file */ }
+    }
+    shards++;
+  }
+  return { kept, dropped, shards };
+}
+
 export function fileId(sourceId, key) {
   return hashId(sourceId, key);
 }

package/src/core/sync.js

@@ -12,9 +12,12 @@
  *     enabled: false            # ← default; nothing leaves the machine
  *     dir: ~/Sync/TokenFlow     # shared folder both machines can see
  *     machineName: MacBook Pro  # friendly label shown in aggregated views
+ *     developerName: Vimox      # OPTIONAL — only when the team explicitly
+ *                               # opts into per-developer visibility (P4-B)
  *
  * What is transmitted (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.
  *
@@ -90,10 +93,15 @@ export function push(opt = {}) {
 
   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()]
     .sort((a, b) => a.date.localeCompare(b.date))
     .map((d) => JSON.stringify({
-      machineId: id, machineName: name, date: d.date,
+      machineId: id, machineName: name,
+      ...(dev ? { developer: dev } : {}),
+      date: d.date,
       inputTokens: d.input, outputTokens: d.output,
       requests: d.requests, estCostUsd: Math.round(d.estCost * 10000) / 10000,
       exportedAt: new Date().toISOString(),

package/src/core/team.js

@@ -0,0 +1,162 @@
+/**
+ * P4 Team dashboard — Option B (per-developer rows), built on file sync.
+ *
+ * PRIVACY CONTRACT (explicit opt-in, per person):
+ *   A record carries a `developer` name ONLY if that person set
+ *   sync.developerName in their own config. Machines without it stay
+ *   anonymous ("machine-a1b2") and are EXCLUDED from per-developer rows —
+ *   they only contribute to team totals if includeAnonymous is set.
+ *   Nobody can be de-anonymized by another member; the name is chosen
+ *   (or withheld) by each developer locally.
+ *
+ * Aggregation reads the SAME shared sync folder as multi-machine mode:
+ * one JSONL per machine of {date, tokens, requests, estCostUsd,
+ * machineId, machineName, developer?}. No server, no new backend.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * @param {string} dir resolved sync directory
+ * @param {{from?: string|null, to?: string|null, includeAnonymous?: boolean}} opt
+ * @returns {object|null} team rollup or null when nothing readable
+ */
+export function aggregate(dir, opt = {}) {
+  if (!fs.existsSync(dir)) return null;
+
+  const from = opt.from || null;
+  const to = opt.to || null;
+  const includeAnonymous = !!opt.includeAnonymous;
+
+  // Per-developer and per-machine accumulators.
+  const devs = new Map();      // developer → totals + daily map
+  const machines = new Map();  // machineName/id → totals (for the roster)
+  const anon = { tokens: 0, requests: 0, cost: 0 };  // records w/o developer
+  let days = new Map();        // date → {tokens, requests, cost} for trend
+
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.endsWith('.jsonl')) continue;
+    for (const line of fs.readFileSync(path.join(dir, f), 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      let r;
+      try { r = JSON.parse(line); } catch { continue; }   // tolerate partial syncs
+      if (from && r.date < from) continue;
+      if (to && r.date > to) continue;
+
+      const tokens = (r.inputTokens || 0) + (r.outputTokens || 0);
+      const req = r.requests || 0;
+      const cost = r.estCostUsd || 0;
+      const mKey = r.machineName || r.machineId || f.replace(/\.jsonl$/, '');
+      const dev = typeof r.developer === 'string' && r.developer.trim()
+        ? r.developer.trim() : null;
+
+      let m = machines.get(mKey);
+      if (!m) { m = { machine: mKey, developer: dev, tokens: 0, requests: 0, cost: 0, days: new Set() }; machines.set(mKey, m); }
+      m.tokens += tokens; m.requests += req; m.cost += cost; m.days.add(r.date);
+
+      if (dev) {
+        let d = devs.get(dev);
+        if (!d) { d = { developer: dev, tokens: 0, requests: 0, cost: 0, days: new Map(), machines: new Set() }; devs.set(dev, d); }
+        d.tokens += tokens; d.requests += req; d.cost += cost;
+        d.machines.add(mKey);
+        const dayTot = d.days.get(r.date) || { tokens: 0 };
+        dayTot.tokens += tokens; d.days.set(r.date, dayTot);
+      } else {
+        anon.tokens += tokens; anon.requests += req; anon.cost += cost;
+      }
+
+      const t = days.get(r.date) || { tokens: 0, requests: 0, cost: 0 };
+      t.tokens += tokens; t.requests += req; t.cost += cost;
+      days.set(r.date, t);
+    }
+  }
+
+  if (!machines.size) return null;
+
+  const developers = [...devs.values()]
+    .map((d) => ({
+      developer: d.developer,
+      requests: d.requests,
+      tokens: d.tokens,
+      estCostUsd: Math.round(d.cost * 100) / 100,
+      activeDays: d.days.size,
+      avgTokensPerDay: d.days.size ? Math.round(d.tokens / d.days.size) : null,
+      machines: [...d.machines],
+    }))
+    .sort((a, b) => b.estCostUsd - a.estCostUsd || b.tokens - a.tokens);
+
+  const maxCost = developers[0]?.estCostUsd || 0;
+  const totalTokens = [...days.values()].reduce((s, d) => s + d.tokens, 0);
+  const totalRequests = [...days.values()].reduce((s, d) => s + d.requests, 0);
+  const totalCost = [...days.values()].reduce((s, d) => s + d.cost, 0);
+
+  return {
+    window: { from, to },
+    totals: {
+      requests: totalRequests,
+      tokens: totalTokens,
+      estCostUsd: Math.round(totalCost * 100) / 100,
+      activeMachines: machines.size,
+      namedDevelopers: developers.length,
+      anonymousTokens: anon.tokens,
+    },
+    // Per-developer share bars are rendered from these percentages.
+    shares: developers.map((d) => ({
+      ...d,
+      pctOfCost: totalCost > 0 ? Math.round((d.estCostUsd / totalCost) * 1000) / 10 : null,
+      bar: maxCost > 0 ? Math.max(1, Math.round((d.estCostUsd / maxCost) * 24)) : 1,
+    })),
+    roster: [...machines.values()]
+      .sort((a, b) => b.cost - a.cost)
+      .map((m) => ({ ...m, estCostUsd: Math.round(m.cost * 100) / 100 })),
+    anonymous: includeAnonymous || !developers.length ? { ...anon } : undefined,
+    trendDays: [...days.entries()]
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .slice(-28)
+      .map(([date, v]) => ({ date, ...v })),
+  };
+}
+
+/** Plain-text rendering for the CLI. */
+export function renderText(t) {
+  if (!t) return 'No team data found in the sync folder.';
+  const L = [];
+  const win = t.window.from || t.window.to
+    ? `${t.window.from || '…'} → ${t.window.to || '…'}`
+    : 'all time';
+  L.push(`Team AI usage — ${win}`);
+  L.push('');
+  L.push(`  Total requests     ${t.totals.requests.toLocaleString('en-US')}`);
+  L.push(`  Total tokens       ${fmt(t.totals.tokens)}`);
+  L.push(`  Estimated cost     $${t.totals.estCostUsd.toFixed(2)}   (estimated from local price table)`);
+  L.push(`  Active machines    ${t.totals.activeMachines}   named developers: ${t.totals.namedDevelopers}`);
+  L.push('');
+  L.push('Per developer');
+  if (!t.shares.length) {
+    L.push('  (no records carry a developer name — nobody has set sync.developerName)');
+  }
+  for (const d of t.shares) {
+    const bar = '█'.repeat(d.bar);
+    const pct = d.pctOfCost != null ? ` ${d.pctOfCost}%` : '';
+    L.push(`  ${d.developer.padEnd(14).slice(0, 14)} ${bar.padEnd(25)} ${fmt(d.tokens).padStart(8)} tok  $${d.estCostUsd.toFixed(2).padStart(9)}${pct}`);
+  }
+  if (t.anonymous && (t.anonymous.tokens > 0)) {
+    L.push(`  ${'(anonymous)'.padEnd(14)} ${fmt(t.anonymous.tokens).padStart(8)} tok  excluded from per-dev rows`);
+  }
+  if (!t.shares.length && !(t.anonymous && t.anonymous.tokens > 0)) L.push('  (empty window)');
+  L.push('');
+  L.push('Roster (per machine)');
+  for (const m of t.roster) {
+    L.push(`  ${String(m.machine).padEnd(16).slice(0, 16)} ${String(m.developer || '—').padEnd(12).slice(0, 12)} ${fmt(m.tokens).padStart(8)} tok  $${m.estCostUsd.toFixed(2).padStart(9)}  ${m.days.size}d`);
+  }
+  L.push('');
+  L.push('Names appear here only for developers who chose to publish theirs (sync.developerName).');
+  return L.join('\n');
+}
+
+function fmt(n) {
+  if (n >= 1e9) return (n / 1e9).toFixed(1) + 'B';
+  if (n >= 1e6) return (n / 1e6).toFixed(1) + 'M';
+  if (n >= 1e3) return (n / 1e3).toFixed(1) + 'K';
+  return String(n);
+}

package/src/core/watch-agent.js

@@ -0,0 +1,226 @@
+/**
+ * The watcher's login agent — launchd-supervised `tokenflow watch`.
+ *
+ * "Live" needs a resident process, and until now nothing installed one. The
+ * play button could start a watcher for the length of the session, and that
+ * was all: nothing survived a reboot, so a machine woke up with stale data and
+ * a paused menu bar. Every user who wanted live data had to hand-roll a
+ * LaunchAgent, and a hand-rolled one is where two real defects came from.
+ *
+ * ## KeepAlive is not a boolean here
+ *
+ * `KeepAlive: true` restarts the job whatever happens — including after a
+ * clean exit. On a supervised watcher that silently defeats the stop button:
+ * `tokenflow watch --stop` sends SIGTERM, the watcher releases its lock and
+ * exits 0, and launchd starts it again about two seconds later. Measured, not
+ * assumed. So the rule is `KeepAlive: { SuccessfulExit: false }` — a crash
+ * comes back, a deliberate stop stays stopped until the next login.
+ *
+ * ## ThrottleInterval is a safety belt, not a tuning knob
+ *
+ * A watcher that cannot take the lock exits 1, which under the rule above is a
+ * restart. If something ever holds the lock persistently, that is an infinite
+ * respawn loop writing to the log every time — exactly what filled one user's
+ * watch.log with 2.2 MB of the same refusal. 60 seconds keeps a stuck state
+ * quiet enough to diagnose.
+ *
+ * ## One watcher, one agent
+ *
+ * Two agents both running `tokenflow watch` is the same trap: the loser exits
+ * 1 forever. Installing therefore hunts down any OTHER agent that runs a
+ * tokenflow watcher and removes it — by reading what each plist actually runs,
+ * not by trusting a label, because a hand-rolled one can be called anything.
+ * Leaving the file on disk is not enough either: launchd reloads it at the next
+ * login and the race comes back.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+export const LABEL = 'app.tokenflow.watch';
+
+/** launchd restarts a crash after this many seconds, never faster. */
+const THROTTLE_SECONDS = 60;
+
+export function agentsDir() {
+  return path.join(os.homedir(), 'Library', 'LaunchAgents');
+}
+
+export function plistPath() {
+  return path.join(agentsDir(), `${LABEL}.plist`);
+}
+
+export function supported() {
+  return process.platform === 'darwin';
+}
+
+function homeDir() {
+  return process.env.TOKENFLOW_HOME || path.join(os.homedir(), '.tokenflow');
+}
+
+/** The CLI this module was loaded from: src/core/watch-agent.js → ../../bin */
+export function cliPath() {
+  const here = path.dirname(new URL(import.meta.url).pathname);
+  return path.resolve(here, '..', '..', 'bin', 'tokenflow.js');
+}
+
+function xml(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+export function renderPlist({ nodeBin, cli, home, workingDir }) {
+  // A launchd plist always carries POSIX paths, so build them with path.posix
+  // rather than the host's separator. Rendering is then identical everywhere,
+  // which is what makes it testable on a machine that could never run it.
+  const bin = path.posix.dirname(nodeBin);
+  const PATH = [bin, '/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin', '/opt/homebrew/bin'].join(':');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key><string>${LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${xml(nodeBin)}</string>
+        <string>${xml(cli)}</string>
+        <string>watch</string>
+    </array>
+    <key>RunAtLoad</key><true/>
+    <!-- A crash restarts; a clean stop stays stopped. See watch-agent.js. -->
+    <key>KeepAlive</key>
+    <dict><key>SuccessfulExit</key><false/></dict>
+    <key>ThrottleInterval</key><integer>${THROTTLE_SECONDS}</integer>
+    <key>WorkingDirectory</key><string>${xml(workingDir)}</string>
+    <key>StandardOutPath</key><string>${xml(path.posix.join(home, 'watch.log'))}</string>
+    <key>StandardErrorPath</key><string>${xml(path.posix.join(home, 'watch.log'))}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>TOKENFLOW_HOME</key><string>${xml(home)}</string>
+        <key>PATH</key><string>${xml(PATH)}</string>
+    </dict>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * Every OTHER launch agent that runs a tokenflow watcher.
+ *
+ * Reads what each plist RUNS rather than matching a label: a hand-rolled agent
+ * can be named anything, and one that keeps respawning against our lock is
+ * indistinguishable from a broken install.
+ *
+ * @param {string} [dir]
+ * @returns {{label:string, file:string}[]}
+ */
+export function findForeignAgents(dir = agentsDir()) {
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((f) => f.endsWith('.plist'));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    if (name === `${LABEL}.plist`) continue;
+    const file = path.join(dir, name);
+    let text;
+    try { text = fs.readFileSync(file, 'utf8'); } catch { continue; }
+    // Runs a tokenflow CLI, and runs it with the `watch` subcommand.
+    const runsCli = /<string>[^<]*\/(?:tokenflow\.js|tokenflow)<\/string>/.test(text);
+    const runsWatch = /<string>\s*watch\s*<\/string>/.test(text);
+    if (!runsCli || !runsWatch) continue;
+    const label = /<key>Label<\/key>\s*<string>([^<]+)<\/string>/.exec(text)?.[1] || name.replace(/\.plist$/, '');
+    out.push({ label, file });
+  }
+  return out;
+}
+
+function launchctl(args, { quiet = true } = {}) {
+  try {
+    execFileSync('launchctl', args, { stdio: quiet ? 'ignore' : 'inherit' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function domain() {
+  return `gui/${process.getuid?.() ?? ''}`;
+}
+
+/** Load a plist, preferring the modern API and falling back to the legacy one. */
+function bootstrap(file) {
+  if (launchctl(['bootstrap', domain(), file])) return true;
+  return launchctl(['load', file]);
+}
+
+function bootout(label, file) {
+  const byLabel = launchctl(['bootout', `${domain()}/${label}`]);
+  const byFile = launchctl(['unload', file]);
+  return byLabel || byFile;
+}
+
+/**
+ * Install (or reinstall) the agent and start it.
+ * @returns {{plist:string, removed:{label:string,file:string}[], started:boolean}}
+ */
+export function install() {
+  if (!supported()) {
+    throw Object.assign(new Error('a launch agent needs macOS'), {
+      hint: 'On Linux, run `tokenflow watch` from a systemd --user unit, or `tokenflow watch --once` from cron.',
+    });
+  }
+  const home = homeDir();
+  const cli = cliPath();
+  if (!fs.existsSync(cli)) throw new Error(`cannot find the CLI at ${cli}`);
+  fs.mkdirSync(agentsDir(), { recursive: true });
+  fs.mkdirSync(home, { recursive: true });
+
+  // Any other watcher agent would fight this one for the lock forever. Unload
+  // it AND delete its plist — an unloaded file returns at the next login.
+  const removed = findForeignAgents();
+  for (const a of removed) {
+    bootout(a.label, a.file);
+    try { fs.unlinkSync(a.file); } catch { /* already gone */ }
+  }
+
+  const file = plistPath();
+  fs.writeFileSync(file, renderPlist({
+    nodeBin: process.execPath,
+    cli,
+    home,
+    workingDir: path.resolve(path.dirname(cli), '..'),
+  }));
+  bootout(LABEL, file); // a reinstall must replace, not duplicate
+  const started = bootstrap(file);
+  return { plist: file, removed, started };
+}
+
+export function uninstall() {
+  const file = plistPath();
+  const had = fs.existsSync(file);
+  bootout(LABEL, file);
+  if (had) {
+    try { fs.unlinkSync(file); } catch { /* already gone */ }
+  }
+  return { removed: had, plist: file };
+}
+
+/** @returns {{supported:boolean, installed:boolean, loaded:boolean, plist:string, foreign:{label:string,file:string}[]}} */
+export function status() {
+  const file = plistPath();
+  let loaded = false;
+  try {
+    const out = execFileSync('launchctl', ['list'], { encoding: 'utf8' });
+    loaded = out.split('\n').some((l) => l.trim().endsWith(LABEL));
+  } catch { /* launchctl unavailable */ }
+  return {
+    supported: supported(),
+    installed: fs.existsSync(file),
+    loaded,
+    plist: file,
+    foreign: findForeignAgents(),
+  };
+}