@botbuddy/cli 1.34.0 → 1.34.2

package/src/usage/cursor.mjs

@@ -0,0 +1,151 @@
+// BOT-803 — per-file byte-offset cursors for usage sync.
+//
+// `~/.botbuddy/usage-cursors.json` (0600) maps each transcript's source HMAC
+// (never its path) to the byte offset just past the last COMPLETE line that was
+// successfully delivered, plus the adapter's derived per-file context. A live
+// writer's half-written last line is never consumed, so the next run resumes on
+// it. Writes are tmp-file + rename and merge with whatever is on disk at write
+// time — no lock, so a pre-push run can never wait on the daily sweep (BOT-1023
+// AC4). A lost race only means a later run re-reads a few lines; the server's
+// idempotency key makes that a no-op.
+import { open, readFile, rename, mkdir, writeFile, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export const CURSOR_FILE = "usage-cursors.json";
+export const MAX_RUNS_KEPT = 20;
+const CHUNK = 1 << 20;
+const NEWLINE = 0x0a;
+
+export function cursorPath(home = homedir()) {
+  return join(home, ".botbuddy", CURSOR_FILE);
+}
+
+const emptyState = () => ({ schema_version: 1, files: {}, runs: [] });
+
+/**
+ * Load the cursor state. A MISSING file is an empty state; a corrupt or
+ * unknown-schema file fails closed with `cursor_state_invalid` (Codex #982 R7):
+ * reading it as empty would drop the offsets that keep partly read files in
+ * scope and then overwrite them. The file is left untouched for the user —
+ * delete it to start over (every transcript in --since is re-read once and the
+ * server dedupes).
+ */
+export async function loadCursorState(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return emptyState();
+    throw Object.assign(new Error("usage cursor state is unreadable"), { code: "cursor_state_invalid" });
+  }
+  let parsed;
+  try { parsed = JSON.parse(text); } catch { parsed = null; }
+  if (!parsed || typeof parsed !== "object" || parsed.schema_version !== 1
+    || (parsed.files !== undefined && (typeof parsed.files !== "object" || parsed.files === null || Array.isArray(parsed.files)))) {
+    throw Object.assign(new Error("usage cursor state is corrupt or from another version"), { code: "cursor_state_invalid" });
+  }
+  return {
+    schema_version: 1,
+    files: parsed.files ?? {},
+    runs: Array.isArray(parsed.runs) ? parsed.runs : [],
+  };
+}
+
+/**
+ * Merge `updates` (source_hmac → entry) and `runs` into the on-disk state and
+ * write it atomically. For a file both sides know, the entry with the larger
+ * offset wins — two overlapping triggers can only move a cursor forward.
+ */
+export async function saveCursorState(path, { files = {}, runs = [] } = {}) {
+  const current = await loadCursorState(path);
+  for (const [key, entry] of Object.entries(files)) {
+    const existing = current.files[key];
+    if (!existing || !(existing.offset > entry.offset) || entry.reset === true) {
+      const { reset: _reset, ...clean } = entry;
+      current.files[key] = clean;
+    }
+  }
+  current.runs = [...current.runs, ...runs].slice(-MAX_RUNS_KEPT);
+  await mkdir(join(path, ".."), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  try {
+    await writeFile(tmp, `${JSON.stringify(current)}\n`, { mode: 0o600 });
+    await rename(tmp, path);
+  } catch (error) {
+    await unlink(tmp).catch(() => {});
+    throw error;
+  }
+  return current;
+}
+
+/** A transcript line longer than this is hostile or corrupt: skipped, never buffered. */
+export const MAX_LINE_BYTES = 16 * 1024 * 1024;
+const STOP_CHECK_EVERY = 256;
+
+/**
+ * Stream the complete lines of `path` starting at byte `fromOffset`.
+ * `onLine(text, lineStartOffset)` is called per newline-terminated line (a
+ * trailing CR is stripped). Returns the offset just past the last line handed
+ * out, whether an unterminated tail (a live writer mid-line) was left unread,
+ * whether the budget stopped the read, and how many oversized lines were
+ * skipped. `shouldStop()` is polled between chunks AND every 256 lines, so one
+ * 1 MiB chunk of tiny lines cannot outlive the budget; a line longer than
+ * `maxLineBytes` is dropped (counted) instead of growing the buffer unbounded.
+ */
+export async function readCompleteLines(path, fromOffset, onLine, { shouldStop = () => false, maxLineBytes = MAX_LINE_BYTES } = {}) {
+  const handle = await open(path, "r");
+  try {
+    let position = fromOffset;
+    let consumed = fromOffset;
+    let carry = Buffer.alloc(0);
+    const buffer = Buffer.alloc(CHUNK);
+    let stopped = false;
+    let skipping = false;
+    let oversized = 0;
+    let lines = 0;
+    outer: for (;;) {
+      if (shouldStop()) { stopped = true; break; }
+      const { bytesRead } = await handle.read(buffer, 0, CHUNK, position);
+      if (bytesRead === 0) break;
+      position += bytesRead;
+      let data = carry.length ? Buffer.concat([carry, buffer.subarray(0, bytesRead)]) : Buffer.from(buffer.subarray(0, bytesRead));
+      let start = 0;
+      if (skipping) {
+        const nl = data.indexOf(NEWLINE);
+        if (nl === -1) { consumed += data.length; carry = Buffer.alloc(0); continue; }
+        start = nl + 1;
+        skipping = false;
+      }
+      for (;;) {
+        const nl = data.indexOf(NEWLINE, start);
+        if (nl === -1) break;
+        let end = nl;
+        if (end > start && data[end - 1] === 0x0d) end -= 1;
+        if (nl - start > maxLineBytes) oversized += 1;
+        else onLine(data.toString("utf8", start, end), consumed + start);
+        start = nl + 1;
+        lines += 1;
+        if (lines % STOP_CHECK_EVERY === 0 && shouldStop()) {
+          stopped = true;
+          consumed += start;
+          carry = Buffer.alloc(0);
+          break outer;
+        }
+      }
+      consumed += start;
+      carry = data.subarray(start);
+      if (carry.length > maxLineBytes) {
+        oversized += 1;
+        consumed += carry.length;
+        carry = Buffer.alloc(0);
+        skipping = true;
+      }
+      data = null;
+    }
+    return { endOffset: consumed, partialTail: carry.length > 0, stopped, oversized };
+  } finally {
+    await handle.close();
+  }
+}

package/src/usage/envelope.mjs

@@ -0,0 +1,313 @@
+// BOT-803 — the usage envelope: an explicit allowlist of derived, non-content
+// fields for one assistant usage record. Nothing from a transcript is ever spread
+// or copied wholesale: every key below is named, and every value is re-derived
+// (ids, timestamps, token integers, booleans, HMACs). Prompt text, tool inputs,
+// slugs, summaries, attribution fields, and paths never reach an envelope.
+import { createHmac, randomBytes } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * The complete envelope schema, in wire order — identical to PR 1's server
+ * allowlist `USAGE_ENVELOPE_FIELDS` (supabase/functions/_shared/usageEnvelope.ts,
+ * BOT-1019). finalizeEnvelope emits exactly these keys.
+ */
+export const ENVELOPE_FIELDS = Object.freeze([
+  "provider",
+  "provider_schema_version",
+  "harness_session_id",
+  "request_id",
+  "message_id",
+  "record_uuid",
+  "occurred_at",
+  "model",
+  "input_tokens",
+  "output_tokens",
+  "cache_creation_input_tokens",
+  "cache_read_input_tokens",
+  "codex_input_tokens",
+  "codex_cached_input_tokens",
+  "codex_output_tokens",
+  "codex_reasoning_output_tokens",
+  "tool_call_count",
+  "is_sidechain",
+  "usage_final",
+  "usage_quality",
+  "git_branch",
+  "repo",
+  "commit_sha",
+  "pr_number",
+  "ticket_key_inferred",
+  "attribution_confidence",
+  "environment",
+  "cwd_hmac",
+  "source_hmac",
+  "source_offset",
+  "parser_version",
+]);
+
+const INTEGER_FIELDS = new Set([
+  "input_tokens",
+  "output_tokens",
+  "cache_creation_input_tokens",
+  "cache_read_input_tokens",
+  "codex_input_tokens",
+  "codex_cached_input_tokens",
+  "codex_output_tokens",
+  "codex_reasoning_output_tokens",
+  "tool_call_count",
+  "pr_number",
+  "source_offset",
+]);
+const BOOLEAN_FIELDS = new Set(["is_sidechain", "usage_final"]);
+
+/** Substrings that must never appear in any envelope string (paths, e-mail-ish identities). Mirrors the server's list. */
+export const FORBIDDEN_SUBSTRINGS = Object.freeze(["/Users/", "/home/", "/root/", "@", "\\"]);
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** A UUID string, or null (the server keys harness sessions and record ids on UUIDs). */
+export const uuid = (value) => (typeof value === "string" && UUID_RE.test(value) ? value : null);
+
+/**
+ * The server derives usage_quality the same way; sending it keeps the local
+ * receipt honest: 'measured' only for a final usage object carrying every
+ * native class of its provider.
+ */
+export function usageQuality({ usageFinal, classes }) {
+  return usageFinal && classes.every((c) => c !== null && c !== undefined) ? "measured" : "partial";
+}
+const TICKET_RE = /\b(BOT|ENT)-\d+\b/i;
+const MAX_STRING = 256;
+
+/** A non-empty string, or null. */
+export const str = (value) => (typeof value === "string" && value.length > 0 ? value : null);
+
+/** A non-negative integer token count, or null when absent/garbage. */
+// A non-negative SAFE INTEGER as-is (the server's rule); a fractional, negative,
+// huge or non-numeric value is invalid and becomes null — never truncated into a
+// lower count that would still read as "measured" (Codex #982 R7).
+export const tok = (value) => (Number.isSafeInteger(value) && value >= 0 ? value : null);
+
+/**
+ * A descriptive string (branch, repo, model, version) that is dropped — not sent —
+ * when it carries a forbidden substring. Identity fields are NOT sanitized here:
+ * the privacy self-check is their backstop and aborts the batch instead.
+ */
+export function safeLabel(value) {
+  const s = str(value);
+  if (!s || s.length > MAX_STRING) return null;
+  return FORBIDDEN_SUBSTRINGS.some((bad) => s.includes(bad)) ? null : s;
+}
+
+// Mirrors the server's model rule (usageEnvelope.ts MODEL_RE / VERTEX_MODEL_RE,
+// BOT-1019): a plain model id, or a Vertex `<model>@YYYYMMDD` snapshot whose base
+// passes the plain rule. That 8-digit suffix is the ONE '@' allowed anywhere.
+const MODEL_RE = /^[A-Za-z0-9._:\-[\]]{1,120}$/;
+const VERTEX_MODEL_RE = /^([A-Za-z0-9._:\-[\]]{1,110})@[0-9]{8}$/;
+const isVertexModel = (value) => typeof value === "string" && VERTEX_MODEL_RE.test(value);
+
+/** A model id the server accepts, or null. */
+export function modelLabel(value) {
+  const s = str(value);
+  if (!s) return null;
+  if (MODEL_RE.test(s)) return safeLabel(s);
+  const m = VERTEX_MODEL_RE.exec(s);
+  return m && MODEL_RE.test(m[1]) && safeLabel(m[1]) ? s : null;
+}
+
+export function inferTicketKey(gitBranch, cwd) {
+  const candidates = [str(gitBranch)];
+  const cwdStr = str(cwd);
+  if (cwdStr) {
+    const segments = cwdStr.split(/[\\/]+/).filter(Boolean);
+    candidates.push(segments.length ? segments[segments.length - 1] : null);
+  }
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    const match = candidate.match(TICKET_RE);
+    if (match) return match[0].toUpperCase();
+  }
+  return null;
+}
+
+/** GitHub `owner/name` from a remote URL; anything else (incl. credentials in the URL) → null. */
+export function normalizeRepo(remoteUrl) {
+  const raw = str(remoteUrl);
+  if (!raw) return null;
+  const match = raw.trim().replace(/\.git$/i, "").match(/github\.com[/:]([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/i);
+  return match ? `${match[1]}/${match[2]}` : null;
+}
+
+/** A 7–40 char lowercase hex commit sha, or null. */
+export function commitSha(value) {
+  const s = str(value);
+  return s && /^[0-9a-f]{7,40}$/i.test(s) ? s.toLowerCase() : null;
+}
+
+/**
+ * Build an envelope with EXACTLY the allowlisted keys. Unknown input keys are
+ * ignored; missing keys become null; integers/booleans are coerced defensively.
+ */
+// The server's field rules (supabase/functions/_shared/usageEnvelope.ts,
+// BOT-1019), mirrored so a value the allowlist would reject never leaves the
+// machine at all (Codex #982 R5): optional fields become null, and a row whose
+// identity fails is refused locally (envelopeRefusal).
+const PROVIDER_ID_RE = /^[A-Za-z0-9_.:-]{1,200}$/;
+const VERSION_RE = /^[A-Za-z0-9._+-]{1,40}$/;
+const BRANCH_RE = /^[A-Za-z0-9._/-]{1,200}$/;
+const REPO_RE = /^[A-Za-z0-9._-]{1,100}\/[A-Za-z0-9._-]{1,100}$/;
+const SHA_RE = /^[0-9a-f]{7,40}$/;
+const TICKET_KEY_RE = /^[A-Z][A-Z0-9]{1,9}-[0-9]{1,7}$/;
+const ENV_RE = /^[a-z0-9_-]{1,32}$/;
+const HMAC_RE = /^[0-9a-f]{64}$/;
+const ISO_TS_RE = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})?$/i;
+const ATTRIBUTION = ["deterministic", "inferred", "unattributed"];
+
+const matching = (re) => (v) => (typeof v === "string" && re.test(v.trim()) && !FORBIDDEN_SUBSTRINGS.some((bad) => v.includes(bad)) ? v.trim() : null);
+function daysInMonth(year, month) {
+  if (month === 2) return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28;
+  return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+/** A calendar-valid ISO timestamp normalised to UTC (the server's isoTimestamp), else null. */
+export function isoTimestamp(v) {
+  if (typeof v !== "string") return null;
+  const m = ISO_TS_RE.exec(v.trim());
+  if (!m) return null;
+  const [year, month, day, hour, minute, second] = [1, 2, 3, 4, 5, 6].map((i) => Number(m[i] ?? "0"));
+  if (year < 1 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) return null;
+  if (hour > 23 || minute > 59 || second > 59) return null;
+  const ms = Date.parse(v.trim());
+  if (!Number.isFinite(ms)) return null;
+  const iso = new Date(ms).toISOString();
+  return /^(?!0000)\d{4}-/.test(iso) ? iso : null;
+}
+const INT4_MAX = 2_147_483_647;
+const FIELD_RULES = {
+  provider: (v) => (v === "claude" || v === "codex" ? v : null),
+  usage_quality: (v) => (v === "measured" || v === "partial" ? v : null),
+  provider_schema_version: matching(VERSION_RE),
+  harness_session_id: (v) => uuid(v)?.toLowerCase() ?? null,
+  request_id: matching(PROVIDER_ID_RE),
+  message_id: matching(PROVIDER_ID_RE),
+  record_uuid: (v) => uuid(v)?.toLowerCase() ?? null,
+  occurred_at: isoTimestamp,
+  model: (v) => modelLabel(v),
+  git_branch: (v) => {
+    // Never path-shaped (Codex #982 R6): git itself forbids a leading '/', '//',
+    // '..' and a trailing '/', so such a value is a leaked path, not a branch.
+    const b = matching(BRANCH_RE)(v);
+    return b && !b.startsWith("/") && !b.endsWith("/") && !b.includes("//") && !b.includes("..") ? b : null;
+  },
+  repo: matching(REPO_RE),
+  commit_sha: (v) => (typeof v === "string" && SHA_RE.test(v.trim().toLowerCase()) ? v.trim().toLowerCase() : null),
+  ticket_key_inferred: (v) => (typeof v === "string" && TICKET_KEY_RE.test(v.trim().toUpperCase()) ? v.trim().toUpperCase() : null),
+  attribution_confidence: (v) => (ATTRIBUTION.includes(v) ? v : null),
+  environment: matching(ENV_RE),
+  cwd_hmac: matching(HMAC_RE),
+  source_hmac: matching(HMAC_RE),
+  parser_version: matching(VERSION_RE),
+};
+
+/**
+ * Build an envelope with EXACTLY the allowlisted keys, every string field
+ * passed through the server's rule. Unknown input keys are ignored; missing or
+ * rejected values become null; integers/booleans are coerced defensively.
+ */
+export function finalizeEnvelope(fields) {
+  const out = {};
+  for (const key of ENVELOPE_FIELDS) {
+    const value = fields[key];
+    if (INTEGER_FIELDS.has(key)) {
+      const n = tok(value);
+      out[key] = key === "tool_call_count" || key === "pr_number" ? (n !== null && n <= INT4_MAX ? n : null) : n;
+    }
+    else if (BOOLEAN_FIELDS.has(key)) out[key] = value === true;
+    else if (FIELD_RULES[key]) out[key] = FIELD_RULES[key](value);
+    else out[key] = typeof value === "string" && value.length > 0 ? value : null;
+  }
+  return out;
+}
+
+/** Why the server would refuse this envelope outright (so it is never sent), else null. */
+export function envelopeRefusal(envelope) {
+  if (!envelope.harness_session_id) return "harness_session_id_invalid";
+  if (!envelope.message_id) return "message_id_invalid";
+  if (!envelope.occurred_at) return "occurred_at_invalid";
+  if (!envelope.parser_version) return "parser_version_required";
+  return null;
+}
+
+/**
+ * Attach the routing tenant (the tenant bound to the envelope's checkout, or
+ * null when unbound) as a NON-enumerable property: it steers which run may post
+ * the envelope but is never serialized, so the wire allowlist is unchanged.
+ */
+export function withRoute(envelope, tenant) {
+  Object.defineProperty(envelope, "route_tenant", { value: tenant ?? null, enumerable: false });
+  return envelope;
+}
+
+/**
+ * Assert no string value contains a path prefix or '@'. Reports field names and
+ * counts, never values, so the receipt of a failed check cannot itself leak.
+ */
+export function privacySelfCheck(rows) {
+  const violations = new Map();
+  rows.forEach((row, index) => {
+    for (const [field, value] of Object.entries(row)) {
+      if (typeof value !== "string") continue;
+      // A Vertex snapshot's '@YYYYMMDD' is the one permitted '@' (model only).
+      const checked = field === "model" && isVertexModel(value) ? value.slice(0, value.lastIndexOf("@")) : value;
+      if (FORBIDDEN_SUBSTRINGS.some((bad) => checked.includes(bad))) {
+        const entry = violations.get(field) ?? { field, count: 0, first_index: index };
+        entry.count += 1;
+        violations.set(field, entry);
+      }
+    }
+  });
+  return { pass: violations.size === 0, rows_checked: rows.length, violations: [...violations.values()] };
+}
+
+// ── per-install HMAC key ─────────────────────────────────────────────────────
+
+export const HMAC_KEY_FILE = "usage-hmac-key";
+
+export function hmacKeyPath(home = homedir()) {
+  return join(home, ".botbuddy", HMAC_KEY_FILE);
+}
+
+/**
+ * The per-install secret that keys cwd/source HMACs. A plain sha256 of a
+ * guessable path (`/Users/<name>/Developer/<repo>`) is dictionary-reversible; an
+ * HMAC under a random local key is not. Created 0600 with O_EXCL, so two racing
+ * first runs converge on one key. `create: false` (dry runs) never writes: it
+ * returns an ephemeral key when none exists yet.
+ */
+export async function loadHmacKey({ home = homedir(), create = true } = {}) {
+  const path = hmacKeyPath(home);
+  const read = async () => {
+    const text = (await readFile(path, "utf8")).trim();
+    if (!/^[0-9a-f]{64}$/.test(text)) throw Object.assign(new Error("usage HMAC key is malformed"), { code: "hmac_key_invalid" });
+    return Buffer.from(text, "hex");
+  };
+  try {
+    return await read();
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const fresh = randomBytes(32);
+  if (!create) return fresh;
+  await mkdir(join(home, ".botbuddy"), { recursive: true, mode: 0o700 });
+  try {
+    await writeFile(path, `${fresh.toString("hex")}\n`, { mode: 0o600, flag: "wx" });
+    return fresh;
+  } catch (error) {
+    if (error?.code === "EEXIST") return read();
+    throw error;
+  }
+}
+
+export function hmac(key, value) {
+  return createHmac("sha256", key).update(String(value)).digest("hex");
+}

package/src/usage/launchd.mjs

@@ -0,0 +1,170 @@
+// BOT-1021 — the daily safety-net sweep as a macOS LaunchAgent.
+//
+// `bb setup` installs `ai.botbuddy.usage-sync` into the user's GUI launchd
+// domain: it runs `bb usage sync --since 3d --trigger daily` at 03:10 local time
+// and once at load (so a Mac that slept through 03:10 still sweeps on login).
+// The GUI domain (not `user/<uid>` Background, like the stack canary) is what
+// lets a stale worktree session self-heal from the login-Keychain client key.
+// Elsewhere this is a no-op with a notice; the pre-push and Stop-hook triggers
+// still run there.
+import { execFile } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export const USAGE_AGENT_LABEL = "ai.botbuddy.usage-sync";
+export const USAGE_AGENT_HOUR = 3;
+export const USAGE_AGENT_MINUTE = 10;
+// --all-tenants: ONE job sweeps every tenant the login reaches, so running
+// `bb setup` in another tenant's repo never narrows it (Codex #982 R6).
+export const USAGE_AGENT_ARGS = Object.freeze(["usage", "sync", "--since", "3d", "--trigger", "daily", "--all-tenants"]);
+
+export function usageAgentPlistPath(home = homedir()) {
+  return join(home, "Library", "LaunchAgents", `${USAGE_AGENT_LABEL}.plist`);
+}
+export function usageAgentLogPath(home = homedir()) {
+  return join(home, "Library", "Logs", "botbuddy-usage-sync.log");
+}
+
+/**
+ * The PATH baked into the plist. launchd gives a job almost nothing, and the
+ * installing shell's PATH is the wrong source: it carries per-shell dirs (fnm
+ * multishells, harness plugin dirs) that vanish when that shell exits. The sync
+ * needs node (absolute in ProgramArguments), git and security — so: node's own
+ * bin dir, then the standard system prefixes (the stack-canary rule, BOT-1751).
+ */
+export function usageAgentPath(nodeBin) {
+  return [dirname(nodeBin), "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(":");
+}
+
+function xml(value) {
+  return String(value).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+
+export function renderUsagePlist({ nodeBin, cliPath, workingDirectory, path, home, logPath }) {
+  const args = [nodeBin, cliPath, ...USAGE_AGENT_ARGS].map((a) => `    <string>${xml(a)}</string>`).join("\n");
+  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>${xml(USAGE_AGENT_LABEL)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xml(workingDirectory)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${xml(path)}</string>
+    <key>HOME</key>
+    <string>${xml(home)}</string>
+  </dict>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key>
+    <integer>${USAGE_AGENT_HOUR}</integer>
+    <key>Minute</key>
+    <integer>${USAGE_AGENT_MINUTE}</integer>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <false/>
+  <key>StandardOutPath</key>
+  <string>${xml(logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(logPath)}</string>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>Nice</key>
+  <integer>10</integer>
+</dict>
+</plist>
+`;
+}
+
+/** The main checkout of the repo `cwd` belongs to (stable across worktree deletion), else cwd. */
+export async function mainCheckoutRoot(cwd, { exec = execFileAsync } = {}) {
+  try {
+    const { stdout } = await exec("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], { cwd });
+    const common = stdout.trim();
+    return common.endsWith("/.git") ? dirname(common) : cwd;
+  } catch {
+    return cwd;
+  }
+}
+
+/**
+ * Install (or confirm) the daily LaunchAgent. Idempotent: an identical plist
+ * that launchd already has loaded is left alone; a changed one is replaced
+ * (bootout → bootstrap). Returns { status: installed|unchanged|unsupported|failed }.
+ */
+export async function installUsageAgent({
+  platform = process.platform, home = homedir(), cwd = process.cwd(), uid = process.getuid?.() ?? 0,
+  nodeBin = process.execPath, cliPath = fileURLToPath(new URL("../../bin/botbuddy.mjs", import.meta.url)),
+  path = usageAgentPath(nodeBin), exec = execFileAsync, read = readFile, write = writeFile, makeDir = mkdir,
+} = {}) {
+  if (platform !== "darwin") {
+    return { status: "unsupported", notice: "the daily usage sweep uses launchd (macOS only); pre-push and session hooks still sync here" };
+  }
+  const plistPath = usageAgentPlistPath(home);
+  const plist = renderUsagePlist({
+    nodeBin, cliPath, workingDirectory: await mainCheckoutRoot(cwd, { exec }), path, home, logPath: usageAgentLogPath(home),
+  });
+  const domain = `gui/${uid}`;
+  let existing = null;
+  try { existing = await read(plistPath, "utf8"); } catch { existing = null; }
+  if (existing === plist) {
+    try {
+      await exec("launchctl", ["print", `${domain}/${USAGE_AGENT_LABEL}`]);
+      return { status: "unchanged" };
+    } catch { /* on disk but not loaded: fall through and load it */ }
+  }
+  try {
+    await makeDir(dirname(plistPath), { recursive: true });
+    await makeDir(dirname(usageAgentLogPath(home)), { recursive: true });
+    await write(plistPath, plist, { mode: 0o644 });
+    // bootout first so a re-install replaces the loaded job; it fails harmlessly on a first install.
+    await exec("launchctl", ["bootout", `${domain}/${USAGE_AGENT_LABEL}`]).catch(() => {});
+    await exec("launchctl", ["bootstrap", domain, plistPath]);
+    return { status: "installed" };
+  } catch (error) {
+    return { status: "failed", error: error?.code ?? "launchctl_failed" };
+  }
+}
+
+/**
+ * Doctor's view. `installed` means launchd actually HAS the job: a plist on
+ * disk that launchd never loaded (a failed bootstrap, a later bootout) is
+ * reported as not installed, so a dead daily sweep is never shown as healthy.
+ */
+export async function usageAgentStatus({
+  platform = process.platform, home = homedir(), uid = process.getuid?.() ?? 0,
+  read = readFile, exec = execFileAsync,
+} = {}) {
+  if (platform !== "darwin") return { supported: false, installed: false };
+  let plist = false;
+  try {
+    const text = await read(usageAgentPlistPath(home), "utf8");
+    plist = text.includes(`<string>${USAGE_AGENT_LABEL}</string>`);
+  } catch {
+    plist = false;
+  }
+  if (!plist) return { supported: true, installed: false };
+  let loaded = false;
+  try {
+    await exec("launchctl", ["print", `gui/${uid}/${USAGE_AGENT_LABEL}`]);
+    loaded = true;
+  } catch {
+    loaded = false;
+  }
+  return loaded ? { supported: true, installed: true } : { supported: true, installed: false, plist: true, loaded: false };
+}