@vimoxshah/tokenflow 1.1.0 → 1.1.1

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(),
+  };
+}

package/src/core/watch-lock.js

@@ -0,0 +1,160 @@
+/**
+ * The watcher's single-instance lock.
+ *
+ * A pidfile alone cannot answer "is my watcher running?". PID numbers restart
+ * at boot and the kernel reuses them, so a pidfile that outlives a reboot
+ * eventually names somebody else's process. That is not hypothetical: a lock
+ * left at pid 810 was inherited by `/usr/libexec/mobilerepaird` after a
+ * restart, `kill(810, 0)` kept succeeding, and every `tokenflow watch` — from
+ * the launch agent and from the menu bar's play button alike — refused to
+ * start with "a watcher is already running" for days. The data silently went
+ * stale behind a lock held by a phantom.
+ *
+ * So the lock records an IDENTITY, not just a number:
+ *
+ *   pid        the process to signal
+ *   boot       epoch ms of the boot the pid was issued by
+ *   startedAt  when the watcher took the lock (human-readable diagnostics)
+ *
+ * A lock is live only when the pid is alive AND its boot stamp matches this
+ * boot. A pidfile from an earlier boot is stale by construction, whoever holds
+ * that number now.
+ *
+ * Legacy bare-number pidfiles carry no boot stamp, so they fall back to asking
+ * the OS who owns the number: a command line without "tokenflow" in it is
+ * somebody else's process and the lock is stale.
+ *
+ * This module owns the lock so that both the watcher and the read-only status
+ * surfaces can consult it without importing each other.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { paths } from './config.js';
+
+export const LOCK_VERSION = 2;
+
+/**
+ * Boot stamps are derived from uptime, which the OS reports in whole seconds,
+ * so two readings inside one boot can differ by a second or two. Anything
+ * inside this window is the same boot; a reboot moves the stamp by at least
+ * the previous session's uptime.
+ */
+const BOOT_TOLERANCE_MS = 30000;
+
+/** Epoch ms of the last boot. Stable to ~1s for the life of the boot. */
+export function bootTimeMs() {
+  return Date.now() - os.uptime() * 1000;
+}
+
+/**
+ * @typedef {{pid:number, boot:number|null, startedAt:string|null, legacy:boolean}} WatchLock
+ */
+
+/** Read the lock file. Accepts both the JSON form and the legacy bare number. */
+export function readLock() {
+  let raw;
+  try {
+    raw = fs.readFileSync(paths().watchPid, 'utf8').trim();
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  if (raw.startsWith('{')) {
+    try {
+      const o = JSON.parse(raw);
+      const pid = Number(o.pid);
+      if (!Number.isFinite(pid) || pid <= 0) return null;
+      const boot = Number(o.boot);
+      return {
+        pid,
+        boot: Number.isFinite(boot) ? boot : null,
+        startedAt: typeof o.startedAt === 'string' ? o.startedAt : null,
+        legacy: false,
+      };
+    } catch {
+      return null;
+    }
+  }
+  const pid = Number(raw);
+  if (!Number.isFinite(pid) || pid <= 0) return null;
+  return { pid, boot: null, startedAt: null, legacy: true };
+}
+
+/** Just the pid, for callers that only want to signal it. */
+export function readLockPid() {
+  return readLock()?.pid ?? null;
+}
+
+/** Does SOME process hold this pid? (EPERM = alive, owned by someone else.) */
+export function processAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code !== 'ESRCH';
+  }
+}
+
+/**
+ * The command line behind a pid, or null when the OS will not say.
+ * Cheap enough for lock checks; never called in a loop.
+ */
+export function processCommand(pid) {
+  try {
+    if (process.platform === 'linux') {
+      const raw = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+      return raw.replace(/\0/g, ' ').trim() || null;
+    }
+    const out = execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
+      encoding: 'utf8',
+      timeout: 2000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Is this lock held by a live watcher of OURS?
+ *
+ * @param {WatchLock|null} lock
+ */
+export function lockIsLive(lock) {
+  if (!lock || !processAlive(lock.pid)) return false;
+  if (lock.boot !== null) {
+    return Math.abs(lock.boot - bootTimeMs()) <= BOOT_TOLERANCE_MS;
+  }
+  // No boot stamp to check: ask who owns the number instead. When the OS
+  // will not say, keep the lock — refusing to start is safer than two
+  // watchers racing on one store.
+  const cmd = processCommand(lock.pid);
+  if (cmd === null) return true;
+  return /tokenflow/i.test(cmd);
+}
+
+/** Write this process in as the lock holder. */
+export function writeLock() {
+  fs.writeFileSync(
+    paths().watchPid,
+    `${JSON.stringify({
+      v: LOCK_VERSION,
+      pid: process.pid,
+      boot: Math.round(bootTimeMs()),
+      startedAt: new Date().toISOString(),
+    })}\n`,
+  );
+}
+
+/** Remove the lock file. */
+export function clearLock() {
+  try {
+    fs.unlinkSync(paths().watchPid);
+    return true;
+  } catch {
+    return false; // already gone — that is fine
+  }
+}