claude-rpc 0.12.1 → 0.13.1

package/README.md

@@ -35,14 +35,35 @@ A small Node daemon that takes the lifecycle events Claude Code already fires an
 
 ## install
 
-**Windows (no Node required)** — [grab the portable exe from the latest release](https://github.com/rar-file/claude-rpc/releases/latest):
+**macOS / Linux / any Node 18+** — one command:
+
+```sh
+npx claude-rpc setup
+```
+
+That installs `claude-rpc` globally, wires the hooks into Claude Code, and starts the daemon — no separate `start` step. Open Claude Code in any project and the card appears within a second. Something looks wrong? `claude-rpc doctor` (or `claude-rpc doctor --fix` to auto-repair).
+
+**Prefer a one-liner that figures it out for you?**
+
+```sh
+curl -fsSL https://claude-rpc.vercel.app/install | sh
+```
+
+Detects Node (installs the npm package) or falls back to the prebuilt Apple-Silicon binary, then runs `setup` for you.
+
+**Homebrew** (macOS / Linux):
+
+```sh
+brew install rar-file/claude-rpc/claude-rpc && claude-rpc setup
+```
+
+**Windows (no Node required)** — [grab the portable exe from the latest release](https://github.com/rar-file/claude-rpc/releases/latest), then:
 
 ```sh
 claude-rpc setup
-claude-rpc start
 ```
 
-That's the whole pitch. Open Claude Code in any project — the daemon picks it up within a second. Something looks wrong? `claude-rpc doctor`.
+That's the whole pitch.
 
 > `setup` registers a Windows startup entry and wires hooks into Claude Code's `settings.json`, and the daemon reports anonymous totals by default. All of it is reversible (`claude-rpc uninstall`, `community off`) and fully documented in [`SECURITY.md`](SECURITY.md) — read it first if you want to know exactly what runs.
 
@@ -55,11 +76,10 @@ The Discord *desktop* app must be running. The browser client doesn't expose the
 git clone https://github.com/rar-file/claude-rpc.git
 cd claude-rpc
 npm install
-node ./src/cli.js setup
-node ./src/cli.js start
+node ./src/cli.js setup     # wires hooks + starts the daemon
 ```
 
-Or `npm install -g claude-rpc` for the global bin. Both modes survive `npm update` without losing your `clientId` — user config lives under the per-OS config dir, not inside `node_modules`.
+Or `npm install -g claude-rpc && claude-rpc setup` for the global bin. `setup` starts the daemon for you; manage it afterward with `claude-rpc start | stop | status`. Every mode survives `npm update` without losing your `clientId` — user config lives under the per-OS config dir, not inside `node_modules`.
 </details>
 
 <details>
@@ -282,14 +302,15 @@ Exit codes: `0` ok · `1` user error · `2` system error · `3` wrong state. `--
 ## development
 
 ```sh
-npm test                  # 200+ tests, ~1.7s
+npm test                  # 270+ tests, ~2s
+npm run lint              # eslint over src + test
 npm run start             # run daemon in foreground
 npm run serve             # web dashboard against your real data
 npm run dashboard         # Electron settings GUI (dev mode)
 npm run build:exe         # SEA single-file binary for the current OS
 ```
 
-Tests are `node --test` with zero deps. The CI pipeline ([release.yml](.github/workflows/release.yml)) gates the matrix build and the npm publish behind the test job. Every public export of `src/*.js` is exercised at least once.
+Tests are `node --test` with zero deps. The CI pipeline ([release.yml](.github/workflows/release.yml)) runs the suite (plus the Cloudflare Worker's own tests) across Node 18/20/22 and gates the matrix build and the npm publish behind it. Every pure/logic module in `src/*.js` is unit-tested, including the MCP transport and the SVG renderers; the long-running daemon, the TUI, and the CLI dispatcher are covered by integration and manual smoke testing rather than unit tests.
 
 ## license
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "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",
@@ -31,14 +31,23 @@
     "prep:dashboard": "node ./scripts/prep-dashboard.js",
     "dist:mac": "npm run build:exe && npm run prep:dashboard && npm --prefix dashboard run dist:mac",
     "dist:win": "npm run build:exe && npm run prep:dashboard && npm --prefix dashboard run dist:win",
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "lint": "eslint src test",
+    "format": "prettier --write \"src/**/*.js\" \"test/**/*.js\"",
+    "format:check": "prettier --check \"src/**/*.js\" \"test/**/*.js\"",
+    "typecheck": "tsc -p jsconfig.json"
   },
   "dependencies": {
     "@xhayper/discord-rpc": "^1.2.1"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "esbuild": "^0.24.0",
-    "postject": "^1.0.0-alpha.6"
+    "eslint": "^10.4.1",
+    "globals": "^17.6.0",
+    "postject": "^1.0.0-alpha.6",
+    "prettier": "^3.8.3",
+    "typescript": "^6.0.3"
   },
   "engines": {
     "node": ">=18"

package/src/calendar.js

@@ -86,7 +86,7 @@ export function renderCalendar(aggregate, { weeks = 53, generatedAt = new Date()
   <text x="${W - 170}" y="${H - 10}" font-family="JetBrains Mono, ui-monospace, monospace" font-size="9" fill="${PALETTE.inkFaint}">less</text>
   ${legend}
   <text x="${W - 28}" y="${H - 10}" font-family="JetBrains Mono, ui-monospace, monospace" font-size="9" fill="${PALETTE.inkFaint}">more</text>
-  <text x="${padX}" y="${H - 8}" font-family="JetBrains Mono, ui-monospace, monospace" font-size="9" fill="${PALETTE.inkFaint}">claude-rpc v${VERSION}</text>
+  <text x="${padX}" y="${H - 8}" font-family="JetBrains Mono, ui-monospace, monospace" font-size="9" fill="${PALETTE.inkFaint}">claude-rpc.vercel.app · v${VERSION}</text>
 </svg>`;
 }
 

package/src/card.js

@@ -334,7 +334,7 @@ export function renderCard(aggregate, { range = 'year', generatedAt = new Date()
   <!-- ── credits ── -->
   <g transform="translate(${W - 60} ${H - 24})" text-anchor="end">
     <text font-family="JetBrains Mono, ui-monospace, monospace" font-size="10"
-          fill="${PALETTE.inkFaint}">${escapeXml(allTimeHours)}h all-time · github.com/rar-file/claude-rpc</text>
+          fill="${PALETTE.inkFaint}">${escapeXml(allTimeHours)}h all-time · claude-rpc.vercel.app</text>
   </g>
 </svg>`;
 }

package/src/cli.js

@@ -10,7 +10,7 @@ import process from 'node:process';
 if (process.platform === 'win32' && process.stdout.isTTY) {
   try { spawnSync('chcp.com', ['65001'], { stdio: 'ignore', windowsHide: true }); } catch { /* chcp absent (Wine, custom shell) — accept whatever code page is set */ }
 }
-import { DAEMON_SCRIPT, PID_PATH, STATE_PATH, LOG_PATH, AGGREGATE_PATH, CONFIG_PATH, IS_PACKAGED, EXE_PATH, CANONICAL_EXE } from './paths.js';
+import { DAEMON_SCRIPT, PID_PATH, STATE_PATH, LOG_PATH, AGGREGATE_PATH, CONFIG_PATH, IS_PACKAGED, IS_NPX, EXE_PATH, CANONICAL_EXE } from './paths.js';
 import { readState } from './state.js';
 import { buildVars, fillTemplate, humanProject, humanTool, applyIdle, framePasses } from './format.js';
 import { scan, readAggregate, findLiveSessions, dayKey, weekKey } from './scanner.js';
@@ -18,12 +18,14 @@ import { runHookCli } from './hook.js';
 import { install as runInstall, uninstall as runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, mcpServerCommand } from './install.js';
 import { startTui } from './tui.js';
 import { generateInsights } from './insights.js';
+import { maybeNudge } from './nudge.js';
 import { badgeSvg } from './badge.js';
 import { fmtCost } from './pricing.js';
 import { addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility } from './privacy.js';
 import { loadConfig, hasUserConfig } from './config.js';
+import * as lb from './leaderboard.js';
 import { VERSION } from './version.js';
-import { fail, EX_USER_ERROR, EX_BAD_STATE } from './ui.js';
+import { fail, EX_USER_ERROR, EX_BAD_STATE, EX_SYS_ERROR } from './ui.js';
 import { randomUUID } from 'node:crypto';
 import { createInterface } from 'node:readline';
 import { basename } from 'node:path';
@@ -458,6 +460,13 @@ function showToday() {
     box('when you code · hour of day', renderHourHistogram(aggregate.byHour, { peakHour: vars.peakHourNum }), 40);
     console.log('');
   }
+
+  // Share nudge — only on a TTY (keeps piped/scripted output clean) and only
+  // when a new milestone was crossed. maybeNudge marks it shown internally.
+  if (process.stdout.isTTY) {
+    const nudge = maybeNudge(aggregate, config);
+    if (nudge) console.log(`  ${c.dim}↗ share${c.reset}  ${nudge}\n`);
+  }
 }
 
 function showWeek() {
@@ -1038,6 +1047,158 @@ async function communityReport() {
   console.log('');
 }
 
+// ── leaderboard profile (local) ───────────────────────────────────────
+// `profile` manages the local, opt-in identity used by the public leaderboard.
+// Everything is stored locally in config.json; nothing is published until the
+// 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];
+  const eq = argv.find((a) => a.startsWith(`--${name}=`));
+  return eq ? eq.slice(name.length + 3) : undefined;
+}
+
+function profileStatus() {
+  const p = (loadConfig().profile) || {};
+  console.log('');
+  console.log(`  ${c.bold}claude-rpc profile${c.reset}  ${c.dim}— public leaderboard identity${c.reset}`);
+  console.log('');
+  console.log(`  state:    ${p.enabled ? `${c.green}on${c.reset}` : `${c.dim}off${c.reset}`}`);
+  console.log(`  handle:   ${p.handle ? c.cyan + p.handle + c.reset : c.dim + '(unset)' + c.reset}`);
+  console.log(`  name:     ${p.displayName ? p.displayName : c.dim + '(unset)' + c.reset}`);
+  console.log(`  github:   ${p.githubUser ? `${p.githubUser} ${c.dim}(verify to earn ✓)${c.reset}` : c.dim + '(unset — unverified)' + c.reset}`);
+  console.log('');
+  if (!p.handle) console.log(`  ${c.dim}set one with:${c.reset} claude-rpc profile set --handle <name> [--name "..."] [--github <user>]`);
+  else if (!p.enabled) console.log(`  ${c.dim}publish to the board with:${c.reset} claude-rpc profile on`);
+  console.log('');
+}
+
+function profileSet(argv) {
+  const { normalizeHandle, cleanDisplayName, normalizeGithubUser } = lb;
+  const userCfg = readJson(CONFIG_PATH, {});
+  const next = { ...(userCfg.profile || {}) };
+
+  const rawHandle = readFlag(argv, 'handle');
+  if (rawHandle !== undefined) {
+    const h = normalizeHandle(rawHandle);
+    if (!h) return fail('invalid handle — use 2–32 chars of letters, numbers, and dashes', { code: EX_USER_ERROR });
+    next.handle = h;
+  }
+  const rawName = readFlag(argv, 'name');
+  if (rawName !== undefined) next.displayName = cleanDisplayName(rawName);
+  const rawGh = readFlag(argv, 'github');
+  if (rawGh !== undefined) {
+    if (rawGh === '') next.githubUser = null;
+    else {
+      const u = normalizeGithubUser(rawGh);
+      if (!u) return fail(`invalid GitHub username: ${rawGh}`, { code: EX_USER_ERROR });
+      next.githubUser = u;
+    }
+  }
+
+  userCfg.profile = next;
+  writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
+  console.log(`${c.green}✓${c.reset} profile saved`);
+  profileStatus();
+}
+
+function profileEnable(on) {
+  const userCfg = readJson(CONFIG_PATH, {});
+  const next = { ...(userCfg.profile || {}) };
+  if (on && !lb.isValidHandle(next.handle)) {
+    return fail('set a handle before going on', {
+      hint: 'claude-rpc profile set --handle <name>',
+      code: EX_BAD_STATE,
+    });
+  }
+  next.enabled = on;
+  // Publishing reuses the anonymous community instanceId as the profile's row
+  // key. Mint one if the user never opted into community totals, so a
+  // profile-only user can still publish.
+  if (on) {
+    const community = { ...(userCfg.community || {}) };
+    if (!community.instanceId) {
+      community.instanceId = randomUUID();
+      userCfg.community = community;
+    }
+  }
+  userCfg.profile = next;
+  writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2));
+  console.log(`${c.green}✓${c.reset} leaderboard publishing ${on ? 'enabled' : 'disabled'}`);
+  if (on) console.log(`  ${c.dim}your stats publish on the next daemon flush. run ${c.reset}${c.cyan}claude-rpc profile verify${c.reset}${c.dim} to earn the ✓.${c.reset}`);
+}
+
+// GitHub verification: ask the worker for a one-time token, publish it in a
+// public gist (reusing the gist helper), then have the worker confirm it.
+async function profileVerify() {
+  const cfg = loadConfig();
+  const profile = cfg.profile || {};
+  const community = cfg.community || {};
+  if (!profile.githubUser) {
+    return fail('set a GitHub username first', {
+      hint: 'claude-rpc profile set --github <user>', code: EX_BAD_STATE,
+    });
+  }
+  if (!community.instanceId) {
+    return fail('enable the profile first', { hint: 'claude-rpc profile on', code: EX_BAD_STATE });
+  }
+  const endpoint = (community.endpoint || '').replace(/\/+$/, '');
+  if (!endpoint) return fail('no community endpoint configured', { code: EX_BAD_STATE });
+
+  const post = async (path, body) => {
+    const res = await fetch(endpoint + path, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    return { status: res.status, json: await res.json().catch(() => ({})) };
+  };
+
+  try {
+    console.log(`${c.dim}requesting a verification token…${c.reset}`);
+    const start = await post('/verify/start', { instanceId: community.instanceId, githubUser: profile.githubUser });
+    if (!start.json?.token) return fail(`verify/start failed: ${start.json?.error || start.status}`, { code: EX_SYS_ERROR });
+    const token = start.json.token;
+
+    const { publishGistFile } = await import('./gist.js');
+    console.log(`${c.dim}publishing a proof gist as @${profile.githubUser}…${c.reset}`);
+    await publishGistFile({
+      svg: `claude-rpc leaderboard verification for @${profile.githubUser}\n${token}\n`,
+      filename: 'claude-rpc-verify.txt',
+      description: 'claude-rpc profile verification',
+      isPublic: true,
+    });
+
+    console.log(`${c.dim}asking the server to confirm…${c.reset}`);
+    // Small delay so the gist is visible to GitHub's API before we check.
+    await new Promise((r) => setTimeout(r, 2500));
+    const check = await post('/verify/check', { instanceId: community.instanceId });
+    if (check.json?.verified) {
+      console.log(`${c.green}✓${c.reset} verified as @${profile.githubUser} — you'll show the ✓ on the board.`);
+    } else {
+      console.log(`${c.yellow}!${c.reset} not confirmed yet: ${check.json?.error || check.status}`);
+      console.log(`  ${c.dim}the gist may take a moment to propagate — re-run ${c.reset}${c.cyan}claude-rpc profile verify${c.reset}${c.dim} shortly.${c.reset}`);
+    }
+  } catch (e) {
+    return fail(`verification failed: ${e.message}`, {
+      hint: 'needs `gh` logged in or GH_TOKEN with gist scope', code: EX_SYS_ERROR,
+    });
+  }
+}
+
+async function doProfile(argv) {
+  const sub = (argv[0] || 'status').toLowerCase();
+  if (sub === 'status' || sub === '') return profileStatus();
+  if (sub === 'set') return profileSet(argv.slice(1));
+  if (sub === 'on') return profileEnable(true);
+  if (sub === 'off') return profileEnable(false);
+  if (sub === 'verify') return profileVerify();
+  fail(`unknown profile subcommand: ${sub}`, {
+    hint: 'try: profile [status|set|on|off|verify]',
+    code: EX_USER_ERROR,
+  });
+}
+
 async function doCommunity(argv) {
   const sub = (argv[0] || 'status').toLowerCase();
   if (sub === 'on') return communityOn();
@@ -1175,6 +1336,7 @@ function help() {
     ['public',    'Un-mark the current directory'],
     ['privacy',   'Show resolved visibility for the current directory'],
     ['community', 'Opt in/out of anonymous community totals (on|off|status|report)'],
+    ['profile',   'Public leaderboard identity — set handle/name/github (status|set|on|off)'],
     ['doctor',    'Run a diagnostic checklist — common-failure triage (--fix to auto-repair)'],
     ['tail',      'Tail the daemon log file'],
     ['daemon',    'Run daemon in foreground (debug)'],
@@ -1219,7 +1381,30 @@ const packagedDefault = IS_PACKAGED && !cmd;
     // startup, install = with) but in practice users expect one command
     // to do everything. Non-Windows: addStartupEntry is a no-op + warning.
     case 'setup':
-    case 'install':   await runInstall({ exePath: EXE_PATH || process.execPath }); break;
+    case 'install':
+      await runInstall({ exePath: EXE_PATH || process.execPath });
+      // Slimmer first run: bring the daemon up now so the card appears
+      // immediately, instead of making the user run a separate `start`.
+      // Best-effort — a start hiccup must never make `setup` look failed.
+      try {
+        if (IS_NPX) {
+          // Our own tree is npm's throwaway _npx cache; launch from the global
+          // install setup just promoted to, via the PATH-resolved bin.
+          if (!daemonPid()) {
+            spawn('claude-rpc', ['daemon'], {
+              detached: true, stdio: 'ignore', windowsHide: true,
+              shell: process.platform === 'win32',
+            }).unref();
+            console.log(`${c.green}✓${c.reset} Daemon launched  ${c.dim}logs: ${LOG_PATH}${c.reset}`);
+          }
+        } else {
+          startDaemon();
+        }
+      } catch (e) {
+        console.log(`${c.yellow}!${c.reset} Couldn't auto-start the daemon: ${e.message}`);
+        console.log(`  ${c.dim}↳ run \`claude-rpc start\` when you're ready${c.reset}`);
+      }
+      break;
     case 'uninstall': await runUninstall(); break;
     case 'upgrade-config': migrateConfig(); break;
     case 'start':     startDaemon(); break;
@@ -1259,23 +1444,46 @@ const packagedDefault = IS_PACKAGED && !cmd;
     case 'public':    doPublic(); break;
     case 'privacy':   doPrivacy(); break;
     case 'community': await doCommunity(process.argv.slice(3)); break;
+    case 'profile':   await doProfile(process.argv.slice(3)); break;
     case 'doctor': {
-      const { runDoctor } = await import('./doctor.js');
+      const { runDoctor, fixPlan } = await import('./doctor.js');
       const fix = process.argv.includes('--fix');
       const code = runDoctor();
       if (!fix) process.exit(code);
-      // --fix: re-run setup (re-seeds/migrates config, re-wires hooks — all
-      // idempotent) and restart the daemon to pick it up. Covers the common
-      // breakages doctor flags: missing/stale hooks, bricked config, dead daemon.
-      console.log(`\n  ${c.cyan}◆ --fix${c.reset} ${c.dim}— re-running setup and restarting the daemon${c.reset}`);
-      try {
-        await runInstall({ exePath: EXE_PATH || process.execPath });
-        console.log(`  ${c.green}✓${c.reset} config + hooks repaired`);
-      } catch (e) {
-        console.log(`  ${c.red}✗${c.reset} setup step failed: ${e.message}`);
+
+      // --fix: apply ONLY the repairs the checklist flagged, in dependency
+      // order, reporting each — instead of blindly re-running everything.
+      const plan = fixPlan();
+      if (plan.length === 0) {
+        console.log(`\n  ${c.green}◆ --fix${c.reset} ${c.dim}— nothing to repair; everything that can be auto-fixed already passes.${c.reset}`);
+        process.exit(code);
+      }
+      console.log(`\n  ${c.cyan}◆ --fix${c.reset} ${c.dim}— applying ${plan.length} targeted repair${plan.length === 1 ? '' : 's'}: ${plan.join(', ')}${c.reset}`);
+
+      let restarted = false;
+      for (const kind of plan) {
+        try {
+          if (kind === 'setup') {
+            await runInstall({ exePath: EXE_PATH || process.execPath });
+            console.log(`  ${c.green}✓${c.reset} config + hooks repaired`);
+          } else if (kind === 'rescan') {
+            doScan(true);
+            console.log(`  ${c.green}✓${c.reset} aggregate rebuilt from transcripts`);
+          } else if (kind === 'daemon') {
+            restartDaemon();
+            restarted = true;
+            console.log(`  ${c.green}✓${c.reset} daemon (re)starting`);
+          } else if (kind === 'discord') {
+            console.log(`  ${c.yellow}!${c.reset} discord IPC is down — open the Discord ${c.bold}desktop${c.reset} app (RPC isn't exposed by the browser client). Not auto-fixable.`);
+          }
+        } catch (e) {
+          console.log(`  ${c.red}✗${c.reset} ${kind} step failed: ${e.message}`);
+        }
       }
-      restartDaemon();
-      console.log(`  ${c.green}✓${c.reset} daemon restarting — run ${c.cyan}claude-rpc doctor${c.reset} again in a few seconds to confirm.`);
+      // A 'setup' rewire only takes effect once the daemon reloads, so ensure a
+      // restart even if the daemon wasn't itself flagged.
+      if (plan.includes('setup') && !restarted) restartDaemon();
+      console.log(`  ${c.dim}run ${c.cyan}claude-rpc doctor${c.reset}${c.dim} again in a few seconds to confirm.${c.reset}`);
       break; // let the restart timer fire before the process drains
     }
     case 'tail':

package/src/community.js

@@ -23,8 +23,10 @@ import { join, dirname } from 'node:path';
 import { platform } from 'node:os';
 import { AGGREGATE_PATH, STATE_DIR } from './paths.js';
 import { VERSION } from './version.js';
+import { profileIsPublishable } from './leaderboard.js';
 
 const CURSOR_PATH = join(STATE_DIR, 'community-cursor.json');
+const PROFILE_CURSOR_PATH = join(STATE_DIR, 'profile-cursor.json');
 
 export function readCursor(path = CURSOR_PATH) {
   if (!existsSync(path)) return { sessions: 0, tokens: 0, ts: 0 };
@@ -71,6 +73,93 @@ 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.
+
+function totalTokens(aggregate) {
+  return (aggregate?.inputTokens || 0)
+    + (aggregate?.outputTokens || 0)
+    + (aggregate?.cacheReadTokens || 0)
+    + (aggregate?.cacheWriteTokens || 0);
+}
+
+export function readProfileCursor(path = PROFILE_CURSOR_PATH) {
+  const base = { sessions: 0, tokens: 0, activeMs: 0, ts: 0 };
+  if (!existsSync(path)) return base;
+  try { return { ...base, ...JSON.parse(readFileSync(path, 'utf8')) }; }
+  catch { return base; }
+}
+
+export function buildProfilePayload(aggregate, profileCfg, cursor, { instanceId, now = Date.now() }) {
+  const sessions = aggregate?.sessions || 0;
+  const tokens = totalTokens(aggregate);
+  const activeMs = aggregate?.activeMs || 0;
+  return {
+    instanceId,
+    handle: profileCfg.handle,
+    displayName: profileCfg.displayName || null,
+    githubUser: profileCfg.githubUser || null,
+    sessionsDelta: Math.max(0, sessions - (cursor.sessions || 0)),
+    tokensDelta:   Math.max(0, tokens   - (cursor.tokens   || 0)),
+    activeMsDelta: Math.max(0, activeMs  - (cursor.activeMs || 0)),
+    streak: aggregate?.streak || 0,
+    version: VERSION,
+    osFamily: osFamily(),
+    ts: now,
+  };
+}
+
+export async function flushProfile(cfg, {
+  aggregatePath = AGGREGATE_PATH,
+  cursorPath = PROFILE_CURSOR_PATH,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const profile = cfg?.profile || {};
+  const community = cfg?.community || {};
+  if (!profileIsPublishable(profile)) return { ok: false, reason: 'disabled' };
+  const instanceId = community.instanceId;
+  if (!instanceId) return { ok: false, reason: 'no-instance-id' };
+  if (!community.endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!existsSync(aggregatePath)) return { ok: false, reason: 'no-aggregate' };
+
+  let aggregate;
+  try { aggregate = JSON.parse(readFileSync(aggregatePath, 'utf8')); }
+  catch { return { ok: false, reason: 'unreadable-aggregate' }; }
+
+  const cursor = readProfileCursor(cursorPath);
+  const payload = buildProfilePayload(aggregate, profile, cursor, { instanceId });
+
+  const url = community.endpoint.replace(/\/+$/, '') + '/profile';
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+  } catch (e) {
+    return { ok: false, reason: 'network', error: e.message };
+  }
+  if (!res.ok) {
+    if (res.status === 429) return { ok: false, reason: 'rate-limited' };
+    return { ok: false, reason: `http-${res.status}` };
+  }
+
+  // Advance the cursor only on acceptance (same reasoning as flushCommunity).
+  writeCursor({
+    sessions: (cursor.sessions || 0) + payload.sessionsDelta,
+    tokens:   (cursor.tokens   || 0) + payload.tokensDelta,
+    activeMs: (cursor.activeMs || 0) + payload.activeMsDelta,
+    ts: payload.ts,
+  }, cursorPath);
+
+  return { ok: true, delta: { sessions: payload.sessionsDelta, tokens: payload.tokensDelta, activeMs: payload.activeMsDelta } };
+}
+
 // Single best-effort flush. Returns { ok, reason, delta? } — never throws.
 // Caller passes in the merged config so we can be tested without touching
 // disk for config too.