claude-rpc 0.16.2 → 0.17.0

package/SECURITY.md

@@ -18,11 +18,12 @@ fetch-and-execute anywhere in `src/`.
 | --- | --- | --- | --- |
 | Startup persistence | `src/install.js` → `addStartupEntry` | `HKCU` Run key, current user, no admin | Yes — `claude-rpc uninstall` / `removeStartupEntry` |
 | Hook injection | `src/install.js` → `installHooks` | Only into Claude Code's own `settings.json`, only our own commands | Yes — `uninstallHooks` removes exactly what it added |
-| Outbound network | `src/community.js`, `src/gist.js`, `default-config.js` asset URLs | Anonymous counters + (opt-in) gist publish + GIF assets | Telemetry: `community off`. Gist: only on explicit `badge --gist`. |
-| Local subprocess | `reg.exe`, `git`, `gh` | Static args, no shell interpolation of untrusted input | n/a |
+| Outbound network | `src/community.js`, `src/gist.js`, `src/usage.js`, `src/notify.js`, `default-config.js` | Anonymous counters + (opt-in) profile/gist/webhook + own read-only OAuth-usage poll + GIF assets | Telemetry: `community off`. Profile: `profile off`. Gist/webhook: opt-in only. Usage: `usage.enabled:false`. |
+| Local subprocess | `reg.exe`, `wscript`, `git`, `gh`, `npm`, `claude`, `security`, notifiers | Static or escaped args, no shell interpolation of untrusted input | n/a |
 
-No credential access, no filesystem scanning outside `~/.claude-rpc` and Claude
-Code transcripts, no keylogging, no clipboard access, no AV/EDR evasion.
+No credential access beyond the read-only Claude Code OAuth-token read for usage
+polling (§3d), no filesystem scanning outside `~/.claude-rpc` and Claude Code
+transcripts, no keylogging, no clipboard access, no AV/EDR evasion.
 
 ## 1. Startup persistence (Windows Run key)
 
@@ -53,9 +54,9 @@ and skips it).
 
 **Source:** `src/install.js`, `installHooks` / `uninstallHooks`.
 
-`setup` adds command hooks to Claude Code's `settings.json` for eight lifecycle
+`setup` adds command hooks to Claude Code's `settings.json` for nine lifecycle
 events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
-`Stop`, `SubagentStop`, `Notification`, `SessionEnd`. Each entry looks like:
+`Stop`, `SubagentStop`, `Notification`, `SessionEnd`, `PreCompact`. Each entry looks like:
 
 ```jsonc
 { "matcher": "", "hooks": [{ "type": "command", "command": "\"<exe>\" hook PostToolUse" }] }
@@ -78,9 +79,11 @@ events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
 
 ## 3. Outbound network
 
-There are five distinct network behaviors: community totals (3a), gist
-publishing (3b), squads/web login (3c), subscription-usage polling (3d), and
-the cosmetic GIF assets (3e). Each is independently optional.
+There are six distinct network behaviors: community totals (3a), gist
+publishing (3b), squads/web login (3c), subscription-usage polling (3d),
+the cosmetic GIF assets (3e), and the opt-in status webhook (3f). Each is
+independently optional. The separate desktop dashboard app, if installed,
+additionally auto-updates itself (3g).
 
 ### 3a. Community totals (telemetry) — ON by default for fresh installs
 
@@ -144,6 +147,31 @@ Worker-side storage adds: `gh:<login>` → profile link, `squad:*` membership
 records, and weekly baseline snapshots (auto-expiring). Leaving your last
 squad deletes its record.
 
+When the opt-in public profile is enabled (`profile on` + a handle), the daemon
+also POSTs to `<endpoint>/profile` on the same 30-minute timer. Unlike the
+anonymous 3a report, this one carries your chosen public identity. The
+**complete** payload (`buildProfilePayload`, enforced by the worker's
+`validateProfile`) is:
+
+```json
+{
+  "instanceId": "<your local UUID>",
+  "handle": "ada",
+  "displayName": "Ada L.",
+  "githubUser": "ada",
+  "tokens": 142000000,
+  "sessions": 1200,
+  "activeMs": 360000000,
+  "streak": 23,
+  "version": "0.16.2",
+  "osFamily": "linux",
+  "ts": 1716500000000
+}
+```
+
+It sends absolute totals (not deltas) and is idempotent worker-side (a SET, not
+an add). `profile off` stops it.
+
 ### 3d. Subscription usage — your own token, to its issuer, ON by default
 
 **Source:** `src/usage.js`; consumed by the daemon poll, `claude-rpc usage`,
@@ -180,20 +208,62 @@ are handed to Discord as image keys; **Discord's** client fetches them to render
 the card. The daemon itself doesn't download them. Swap them for your own URLs
 in `config.json` if you prefer.
 
+### 3f. Status webhook — opt-in, OFF by default
+
+**Source:** `src/notify.js` (`postWebhook`), fired from the daemon's
+`fireStatusSideEffects` (`src/daemon.js`). Dormant unless you set `webhook.url`
+and list statuses in `webhook.on`. On a matching status transition the daemon
+POSTs to your configured URL (a Slack/Discord channel or your own endpoint):
+
+```json
+{ "status": "notification", "project": "my-app", "model": "claude-opus-4-8", "justShipped": null, "ts": 1716500000000 }
+```
+
+`project` is the cwd-derived name — redacted to `"Claude Code"` when the
+directory is privacy=hidden, and run through `sanitizeLabel` (strips shell /
+PowerShell metacharacters) first; `model` is always sent. The webhook is
+suppressed entirely while the card is paused or privacy=hidden. Turn it off by
+removing `webhook.url`.
+
+### 3g. Desktop dashboard auto-update — the optional Electron app only
+
+**Source:** `dashboard/main.js` (`initAutoUpdater`, electron-updater). The npm
+CLI package never auto-updates. The *separate* desktop dashboard app, if you
+install it, polls GitHub Releases hourly and downloads + installs updates on
+quit (`autoDownload` / `autoInstallOnAppQuit`) over HTTPS. The release binaries
+are currently **unsigned**, so update integrity rests on GitHub Releases + TLS
+rather than a code signature — a known gap tracked for provenance + published
+checksums. Avoid it by not installing the dashboard.
+
 ## 4. Local subprocesses
 
-All `child_process` use is static-argument and visible:
+Every binary the package can spawn, with its trigger and argument shape. All
+arguments are static constants or values we control — none interpolate
+untrusted or remote input into a shell:
 
-- `reg.exe add/delete` — the Run key above (`src/install.js`).
+- `reg.exe add/delete` — the Windows Run key (`src/install.js`).
+- `wscript.exe` — runs the generated windowless startup shim (`src/install.js`).
+- `chcp.com 65001` — set the console to UTF-8 on Windows TTYs (`src/cli.js`).
 - `git` — read last commit subject / branch for the "just shipped" card
   (`src/git.js`).
 - `gh repo view --json isPrivate` — auto-hide GitHub-private repos from the card
   (`src/privacy.js`); 1.5s timeout, silent skip if `gh` is absent.
-- `gh gist` — only under 3b above.
-
-No subprocess interpolates untrusted/remote input into a shell. The one
-`shell: true` call (`verifyHookPipe`) uses only static, trusted args and is
-documented inline as such.
+- `gh gist` / `gh --version` — gist badge publishing, only under 3b
+  (`src/gist.js`).
+- `npm root -g` / `npm install -g` — resolve / promote the global install during
+  `setup` (`src/install.js`, `src/cli.js`).
+- `claude mcp add/remove` — register / unregister the MCP server on
+  `mcp install` / `mcp uninstall` (`src/install.js`).
+- `security find-generic-password` — read Claude Code's OAuth token from the
+  macOS login keychain for usage polling (`src/usage.js`, §3d). Read-only; may
+  prompt for keychain access.
+- `osascript` / `powershell` / `notify-send` — the opt-in desktop notification
+  (`src/notify.js`); off unless `notify.enabled`. The project label is
+  interpolated but sanitized first (`sanitizeLabel`).
+
+No subprocess passes untrusted or remote input to a shell — arguments are
+static or escaped. The historical `shell: true` paths (`verifyHookPipe`, and the
+gist `gh` wrapper on Windows) use only trusted args.
 
 ## 5. What it stores locally
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.16.2",
+  "version": "0.17.0",
   "description": "Discord Rich Presence for Claude Code — live model, project, tokens, and lifetime stats driven by Claude Code's hook system.",
   "type": "module",
   "license": "MIT",

package/src/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from 'node:child_process';
-import { readFileSync, writeFileSync, existsSync, watchFile, unlinkSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, watchFile, unlinkSync, mkdirSync } from 'node:fs';
 import process from 'node:process';
 
 // Force the console code page to UTF-8 (65001) on Windows so Unicode box
@@ -15,7 +15,7 @@ import { readState } from './state.js';
 import { buildVars, fillTemplate, humanProject, humanTool, applyIdle, framePasses, fmtNum } from './format.js';
 import { scan, readAggregate, findLiveSessions, dayKey, weekKey } from './scanner.js';
 import { runHookCli } from './hook.js';
-import { install as runInstall, uninstall as runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, mcpServerCommand, setupOutro } from './install.js';
+import { install as runInstall, uninstall as runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, setupOutro } from './install.js';
 import { startTui } from './tui.js';
 import { generateInsights } from './insights.js';
 import { maybeNudge, pickTodayMilestone } from './nudge.js';
@@ -30,7 +30,7 @@ import { VERSION } from './version.js';
 import { fail, tailLines, heat, sparkline, fmtDelta, topPercentile, EX_USER_ERROR, EX_BAD_STATE, EX_SYS_ERROR } from './ui.js';
 import { randomUUID } from 'node:crypto';
 import { createInterface } from 'node:readline';
-import { basename, join } from 'node:path';
+import { basename, join, dirname } from 'node:path';
 
 const cmd = process.argv[2];
 
@@ -56,6 +56,29 @@ function readJson(path, fallback) {
   try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
 }
 
+// Persist a mutated config.json. The config dir doesn't exist until `setup`
+// runs (npm/npx install no install script), so a bare writeFileSync threw an
+// uncaught ENOENT for any config-mutating command run before setup
+// (`profile set`, `community on`, `link`, …). mkdirSync first.
+function writeUserConfig(userCfg) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeUserConfig(userCfg);
+}
+
+// Validate a flag's value taken with `argv[++i]`. A value that's missing or
+// itself looks like a flag (`--out --gist` → out='--gist') is almost always a
+// forgotten argument, so fail loudly instead of silently doing the wrong thing.
+// The `--flag=value` form stays the escape hatch for legit `-`-leading values.
+function takeValue(v, flag) {
+  if (v === undefined || (typeof v === 'string' && v.startsWith('-'))) {
+    fail(`${flag} needs a value`, {
+      hint: v === undefined ? 'nothing followed it' : `got \`${v}\` — use ${flag}=<value> if the value really starts with "-"`,
+      code: EX_USER_ERROR,
+    });
+  }
+  return v;
+}
+
 function isAlive(pid) {
   try { process.kill(pid, 0); return true; } catch { return false; }
 }
@@ -98,12 +121,23 @@ function stopDaemon({ quiet = false } = {}) {
 }
 
 function restartDaemon() {
-  if (stopDaemon({ quiet: true })) {
-    // wait briefly for the OS to release the pid file, then spawn fresh
-    setTimeout(() => startDaemon(), 600);
-  } else {
-    startDaemon();
-  }
+  if (!stopDaemon({ quiet: true })) { startDaemon(); return; }
+  // Poll for the old daemon to release the PID file rather than guessing with a
+  // fixed sleep — under load 600ms wasn't always enough, and startDaemon would
+  // then see it "still up" and no-op, leaving NO daemon running once the old
+  // one exited. Give up after ~3s, force-kill the wedged pid, and start anyway.
+  const deadline = Date.now() + 3000;
+  const tick = () => {
+    if (!daemonPid()) { startDaemon(); return; }
+    if (Date.now() >= deadline) {
+      const pid = daemonPid();
+      if (pid) { try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ } }
+      startDaemon();
+      return;
+    }
+    setTimeout(tick, 50);
+  };
+  setTimeout(tick, 50);
 }
 
 // ── Box drawing — auto-widens to fit longest line ────────────────────────────
@@ -795,10 +829,10 @@ function parseBadgeArgs(argv) {
   const out = { metric: 'hours', range: '7d', out: '', gist: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--metric' || a === '-m') out.metric = argv[++i];
-    else if (a === '--range' || a === '-r') out.range = argv[++i];
-    else if (a === '--out' || a === '-o') out.out = argv[++i];
-    else if (a === '--label' || a === '-l') out.label = argv[++i];
+    if (a === '--metric' || a === '-m') out.metric = takeValue(argv[++i], '--metric');
+    else if (a === '--range' || a === '-r') out.range = takeValue(argv[++i], '--range');
+    else if (a === '--out' || a === '-o') out.out = takeValue(argv[++i], '--out');
+    else if (a === '--label' || a === '-l') out.label = takeValue(argv[++i], '--label');
     else if (a === '--gist') out.gist = true;
   }
   return out;
@@ -851,7 +885,7 @@ async function publishBadgeToGist(svg, opts) {
       filename,
     };
     if (stored.public !== undefined) userCfg.gist.public = stored.public;
-    writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
+    writeUserConfig(userCfg);
     const wasUpdate = !!stored.id;
     console.log('');
     console.log(`  ${c.green}✓${c.reset}  ${wasUpdate ? 'updated' : 'created'} gist ${c.cyan}${result.id}${c.reset}`);
@@ -876,8 +910,8 @@ function parseCardArgs(argv) {
   const out = { range: 'year', out: '' };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--range' || a === '-r') out.range = argv[++i];
-    else if (a === '--out' || a === '-o') out.out = argv[++i];
+    if (a === '--range' || a === '-r') out.range = takeValue(argv[++i], '--range');
+    else if (a === '--out' || a === '-o') out.out = takeValue(argv[++i], '--out');
   }
   return out;
 }
@@ -906,8 +940,8 @@ function parseGithubStatArgs(argv) {
   const out = { out: '', gist: false, handle: '' };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--out' || a === '-o') out.out = argv[++i];
-    else if (a === '--handle' || a === '-u') out.handle = argv[++i];
+    if (a === '--out' || a === '-o') out.out = takeValue(argv[++i], '--out');
+    else if (a === '--handle' || a === '-u') out.handle = takeValue(argv[++i], '--handle');
     else if (a === '--gist') out.gist = true;
   }
   return out;
@@ -950,7 +984,7 @@ function liveVars() {
 function doStatusline(argv) {
   let tpl = '{statusVerbose} · {project} · {modelPretty}{tokensLabelPad}';
   for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === '--template' || argv[i] === '-t') tpl = argv[++i] || tpl;
+    if (argv[i] === '--template' || argv[i] === '-t') tpl = takeValue(argv[++i], '--template');
   }
   const { vars } = liveVars();
   vars.tokensLabelPad = vars.tokensLabel ? ` · ${vars.tokensLabel}` : '';
@@ -961,7 +995,7 @@ function doStatusline(argv) {
 async function doCalendar(argv) {
   const opts = { out: '', gist: false };
   for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === '--out' || argv[i] === '-o') opts.out = argv[++i];
+    if (argv[i] === '--out' || argv[i] === '-o') opts.out = takeValue(argv[++i], '--out');
     else if (argv[i] === '--gist') opts.gist = true;
   }
   const aggregate = readAggregate();
@@ -979,7 +1013,7 @@ async function doCalendar(argv) {
 async function doSessionCard(argv) {
   const opts = { out: '' };
   for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === '--out' || argv[i] === '-o') opts.out = argv[++i];
+    if (argv[i] === '--out' || argv[i] === '-o') opts.out = takeValue(argv[++i], '--out');
   }
   const { vars } = liveVars();
   const { renderSessionCard } = await import('./session-card.js');
@@ -1170,16 +1204,27 @@ function squadAuth() {
       code: EX_BAD_STATE,
     });
   }
+  const netFail = (e) => fail(`couldn't reach the squads service: ${e.message}`, {
+    hint: 'check your connection and retry — this never blocks Claude Code',
+    code: EX_SYS_ERROR,
+  });
   const post = async (path, body) => {
-    const res = await fetch(endpoint + path, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ instanceId, ...body }),
-    });
+    let res;
+    try {
+      res = await fetch(endpoint + path, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ instanceId, ...body }),
+        signal: AbortSignal.timeout(10_000),
+      });
+    } catch (e) { return netFail(e); }
     return { status: res.status, json: await res.json().catch(() => ({})) };
   };
   const get = async (path) => {
-    const res = await fetch(endpoint + path);
+    let res;
+    try {
+      res = await fetch(endpoint + path, { signal: AbortSignal.timeout(10_000) });
+    } catch (e) { return netFail(e); }
     return { status: res.status, json: await res.json().catch(() => ({})) };
   };
   return { cfg, endpoint, instanceId, post, get };
@@ -1334,7 +1379,7 @@ async function doLink(argv) {
   // Mirror the verified identity locally so `profile status` agrees.
   const userCfg = readJson(CONFIG_PATH, {});
   userCfg.profile = { ...(userCfg.profile || {}), githubUser: r.json.githubUser, verified: true };
-  writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
+  writeUserConfig(userCfg);
   console.log(`  ${c.green}✓${c.reset}  linked as ${c.cyan}@${r.json.githubUser}${c.reset} — profile verified, squads unlocked in the browser`);
   if (r.json.merged) {
     // This machine joined an existing identity: its stats now roll up under the
@@ -1422,7 +1467,7 @@ async function communityOn() {
     instanceId: userCfg.community?.instanceId || community.instanceId || randomUUID(),
   };
   userCfg.community = next;
-  writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
+  writeUserConfig(userCfg);
   console.log('');
   console.log(`  ${c.green}✓${c.reset} community totals enabled`);
   console.log(`    ${c.dim}id: …${next.instanceId.slice(-8)}${c.reset}`);
@@ -1437,7 +1482,7 @@ function communityOff() {
     return;
   }
   userCfg.community = { ...userCfg.community, enabled: false };
-  writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
+  writeUserConfig(userCfg);
   console.log(`  ${c.green}✓${c.reset}  community totals disabled ${c.dim}(instanceId retained for re-enable continuity)${c.reset}`);
 }
 
@@ -1465,7 +1510,10 @@ async function communityReport() {
 // daemon flush runs with profile.enabled + a valid handle (Phase 2).
 function readFlag(argv, name) {
   const i = argv.indexOf(`--${name}`);
-  if (i !== -1 && i + 1 < argv.length) return argv[i + 1];
+  // Don't consume the next token as the value when it's itself a flag
+  // (`profile set --handle --name x` must not save handle '--name'); fall
+  // through to the --name=value form, which stays the escape hatch.
+  if (i !== -1 && i + 1 < argv.length && !argv[i + 1].startsWith('-')) return argv[i + 1];
   const eq = argv.find((a) => a.startsWith(`--${name}=`));
   return eq ? eq.slice(name.length + 3) : undefined;
 }
@@ -1572,7 +1620,7 @@ function profileSet(argv) {
   }
 
   userCfg.profile = next;
-  writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
+  writeUserConfig(userCfg);
   // One-line confirmation + a pointer at the next step. The full dashboard
   // stays behind `claude-rpc profile` — mutations shouldn't re-render it.
   const saved = [];
@@ -1604,7 +1652,7 @@ function profileEnable(on) {
     }
   }
   userCfg.profile = next;
-  writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
+  writeUserConfig(userCfg);
   if (on) {
     console.log(`  ${c.green}✓${c.reset}  publishing enabled  ${c.dim}— board syncs on the next flush, or now: ${c.reset}${c.cyan}claude-rpc profile publish${c.reset}`);
     profileNextStep();
@@ -1699,7 +1747,7 @@ async function profileVerify() {
       // profile checklist and future publishes match what got verified.
       const userCfg = readJson(CONFIG_PATH, {});
       userCfg.profile = { ...(userCfg.profile || {}), ...(who ? { githubUser: who } : {}), verified: true };
-      writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
+      writeUserConfig(userCfg);
       console.log(`  ${c.green}✓${c.reset}  verified as ${c.cyan}@${who}${c.reset} — you'll show the ✓ on the board`);
       if (who && profile.githubUser && who.toLowerCase() !== profile.githubUser.toLowerCase()) {
         console.log(`     ${c.dim}(your gist is owned by @${who}, so the profile now uses that account)${c.reset}`);
@@ -1845,7 +1893,7 @@ function help() {
     ['start',     'Start the Discord RPC daemon (detached)'],
     ['stop',      'Stop the daemon'],
     ['restart',   'Stop then start the daemon'],
-    ['status',    'Print current session + all-time stats'],
+    ['status',    'Interactive stats TUI; --dump (or piped) prints static text'],
     ['today',     'Focus view: today\'s stats + 24h activity histogram'],
     ['week',      'Focus view: this week, daily breakdown'],
     ['usage',     'Subscription limits — session + weekly % (what /usage shows)'],
@@ -1862,6 +1910,7 @@ function help() {
     ['calendar',  'Year activity heatmap SVG (--out --gist)'],
     ['session-card', 'Recap card for the current session (--out)'],
     ['mcp install', 'Wire the stats MCP server into Claude Code (one command)'],
+    ['mcp uninstall', 'Remove the stats MCP server from Claude Code'],
     ['mcp',       'Run the MCP server (stdio) — exposes your stats to Claude'],
     ['wrapped',   'Open your animated year-in-review (Claude Wrapped)'],
     ['pause',     'Snooze the Discord card globally (pause [30m|2h], default 1h)'],
@@ -1903,6 +1952,14 @@ function help() {
 // Dev mode keeps the original `help` fallback so behavior is unchanged.
 const packagedDefault = IS_PACKAGED && !cmd;
 
+// Floor for any rejection that escapes a command handler (a bare `await fetch`
+// going offline, etc.): the rejected IIFE promise lands here instead of
+// printing a raw stack + an unhandled-rejection warning, keeping the documented
+// 0/1/2/3 exit-code contract intact.
+process.on('unhandledRejection', (e) => {
+  fail(`unexpected error: ${e?.message || e}`, { code: EX_SYS_ERROR });
+});
+
 // Wrapped in an async IIFE so the same source compiles cleanly under both
 // ESM (dev) and CommonJS (esbuild → SEA bundle) — CJS doesn't allow
 // top-level await.

package/src/community.js

@@ -82,11 +82,11 @@ export function buildPayload(aggregate, cursor, { instanceId, now = Date.now() }
 }
 
 // ── leaderboard profile flush ──────────────────────────────────────────
-// Publishes the opt-in public profile (identity + server-validated usage
-// deltas) to the worker's /profile endpoint. Reuses the anonymous community
-// instanceId as the profile's row key, and its own cursor (which also tracks
-// activeMs). Same three guarantees as flushCommunity: never throws, sends only
-// the documented fields, never advances the cursor on a failed flush.
+// Publishes the opt-in public profile (identity + lifetime totals) to the
+// worker's /profile endpoint. Reuses the anonymous community instanceId as the
+// profile's row key. Unlike flushCommunity this is cursor-free and idempotent —
+// it POSTs absolute totals, so the worker SETs (never accumulates) and a resend
+// is a no-op. Same safety guarantees: never throws, sends only documented fields.
 
 function totalTokens(aggregate) {
   return (aggregate?.inputTokens || 0)
@@ -140,6 +140,7 @@ export async function flushProfile(cfg, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(10_000), // bare fetch never times out; a hung peer would wedge the 30-min flush loop
     });
   } catch (e) {
     return { ok: false, reason: 'network', error: e.message };
@@ -182,6 +183,7 @@ export async function flushCommunity(cfg, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(10_000), // bare fetch never times out; a hung peer would wedge the 30-min flush loop
     });
   } catch (e) {
     return { ok: false, reason: 'network', error: e.message };