claude-rpc 0.3.11 → 0.5.0

package/src/daemon.js

@@ -5,6 +5,7 @@ import { readState } from './state.js';
 import { buildVars, fillTemplate, framePasses, applyIdle } from './format.js';
 import { scan, readAggregate, findLiveSessions, readSessionTokens } from './scanner.js';
 import { detectGithubUrl } from './git.js';
+import { applyPrivacy } from './privacy.js';
 import { CONFIG_PATH, STATE_PATH, PID_PATH, LOG_PATH, STATE_DIR, AGGREGATE_PATH } from './paths.js';
 
 if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true });
@@ -99,6 +100,12 @@ function buildActivity(opts = {}) {
     }
   }
 
+  // Apply privacy AFTER token resolution but BEFORE buildVars — so the
+  // template inputs ({project}, {currentFile}, etc.) already reflect the
+  // visibility decision. Sets state._privacy so we can short-circuit to
+  // clearActivity when visibility=hidden.
+  state = applyPrivacy(state, config);
+
   const vars = buildVars(state, config, opts.aggregate || aggregate);
   const p = config.presence || {};
 
@@ -172,9 +179,12 @@ function buildActivity(opts = {}) {
   if (typeof config.activityType === 'number') activity.type = config.activityType;
 
   // Buttons: static configured set, optionally augmented with a per-project
-  // GitHub button when the current cwd has a github origin.
+  // GitHub button when the current cwd has a github origin. Privacy mode
+  // suppresses the GitHub button entirely (else clicking it leaks the
+  // project name we're trying to hide).
+  const isPrivacyConstrained = state._privacy && state._privacy.visibility !== 'public';
   const buttons = Array.isArray(p.buttons) ? p.buttons.slice() : [];
-  const gh = state.status !== 'stale' ? detectGithubUrl(state.cwd) : null;
+  const gh = (!isPrivacyConstrained && state.status !== 'stale') ? detectGithubUrl(state.cwd) : null;
   if (gh && !buttons.some((b) => /github\.com/i.test(b.url || ''))) {
     buttons.unshift({ label: 'View on GitHub →', url: gh });
   }
@@ -196,9 +206,14 @@ async function pushPresence() {
     let resolved = readState();
     resolved.liveSessions = liveSessions;
     resolved = applyIdle(resolved, config);
+    // Privacy can convert any state into a "hidden" verdict — give it the
+    // same treatment as hideWhenStale: a single clearActivity, deduped via
+    // lastPayloadHash so we don't spam the IPC.
+    resolved = applyPrivacy(resolved, config);
 
     const hideWhenStale = config.hideWhenStale !== false;
-    if (resolved.status === 'stale' && hideWhenStale) {
+    const privacyHidden = resolved._privacy?.visibility === 'hidden';
+    if ((resolved.status === 'stale' && hideWhenStale) || privacyHidden) {
       const stamp = 'cleared';
       if (lastPayloadHash === stamp) return;
       lastPayloadHash = stamp;
@@ -206,7 +221,8 @@ async function pushPresence() {
       // elapsed timer rather than counting from a previous session.
       effectiveSessionStart = null;
       await client.user.clearActivity();
-      log('Presence cleared (stale — Claude Code not running)');
+      const reason = privacyHidden ? 'privacy=hidden in this project' : 'stale — Claude Code not running';
+      log(`Presence cleared (${reason})`);
       return;
     }
 

package/src/doctor.js

@@ -0,0 +1,396 @@
+// `claude-rpc doctor` — one-shot diagnostic.
+//
+// Checks every common failure path users have hit in support and prints a
+// colored pass/fail/warn checklist with one-line fix hints. Self-contained:
+// no Discord IPC connection (just a brief probe), no side effects, safe to
+// run repeatedly. Exit code 0 when everything passes, 1 when any check fails.
+
+import { existsSync, readFileSync, statSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import {
+  IS_PACKAGED, IS_NPM_INSTALL, IS_INSTALLED,
+  CONFIG_PATH, CANONICAL_EXE, USER_CONFIG_DIR,
+  STATE_PATH, PID_PATH, LOG_PATH,
+  AGGREGATE_PATH, SCAN_CACHE_PATH,
+  CLAUDE_HOME, CLAUDE_PROJECTS, CLAUDE_SETTINGS,
+} from './paths.js';
+import { findLiveSessions } from './scanner.js';
+import { resolveVisibility, listPrivateCwds } from './privacy.js';
+
+const TTY = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = {
+  reset:  TTY ? '\x1b[0m'   : '',
+  dim:    TTY ? '\x1b[2m'   : '',
+  bold:   TTY ? '\x1b[1m'   : '',
+  red:    TTY ? '\x1b[31m'  : '',
+  green:  TTY ? '\x1b[32m'  : '',
+  yellow: TTY ? '\x1b[33m'  : '',
+  cyan:   TTY ? '\x1b[36m'  : '',
+  gray:   TTY ? '\x1b[90m'  : '',
+};
+
+const SYM_OK   = TTY ? `${c.green}✓${c.reset}` : '[ok]  ';
+const SYM_FAIL = TTY ? `${c.red}✗${c.reset}`   : '[fail]';
+const SYM_WARN = TTY ? `${c.yellow}!${c.reset}` : '[warn]';
+const SYM_INFO = TTY ? `${c.cyan}·${c.reset}`  : '[info]';
+
+const counters = { pass: 0, fail: 0, warn: 0 };
+
+function check(label, status, detail = '', hint = '') {
+  let sym;
+  if (status === 'pass')      { sym = SYM_OK;   counters.pass++; }
+  else if (status === 'fail') { sym = SYM_FAIL; counters.fail++; }
+  else if (status === 'warn') { sym = SYM_WARN; counters.warn++; }
+  else                          { sym = SYM_INFO; }
+  const tail = detail ? `  ${c.dim}${detail}${c.reset}` : '';
+  console.log(`  ${sym}  ${label}${tail}`);
+  if (hint && status !== 'pass') {
+    console.log(`        ${c.gray}↳ ${hint}${c.reset}`);
+  }
+}
+
+function section(title) {
+  console.log(`\n${c.bold}${title}${c.reset}`);
+}
+
+// ── individual checks ────────────────────────────────────────────────────
+
+function checkNodeVersion() {
+  const major = Number((process.versions.node || '').split('.')[0] || 0);
+  if (major >= 18) {
+    check('Node.js version', 'pass', `${process.versions.node}`);
+  } else {
+    check('Node.js version', 'fail', `${process.versions.node} (need ≥18)`,
+      'install a newer Node from https://nodejs.org');
+  }
+}
+
+function checkMode() {
+  let mode, detail;
+  if (IS_PACKAGED) {
+    mode = 'pass';
+    detail = `packaged exe at ${process.execPath}`;
+  } else if (IS_NPM_INSTALL) {
+    mode = 'pass';
+    detail = 'npm install (global or local node_modules)';
+  } else {
+    mode = 'pass';
+    detail = 'dev source (cloned repo, no node_modules wrapper)';
+  }
+  check('execution mode', mode, detail);
+}
+
+function checkConfig() {
+  if (!existsSync(CONFIG_PATH)) {
+    check('config.json present', 'fail', CONFIG_PATH,
+      'run `claude-rpc setup` to seed a default config');
+    return null;
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch (e) {
+    check('config.json present', 'fail', `parse error: ${e.message}`,
+      `open ${CONFIG_PATH} and fix the JSON syntax (or delete it and re-run setup)`);
+    return null;
+  }
+  check('config.json present', 'pass', CONFIG_PATH);
+
+  if (!cfg.clientId || cfg.clientId === '1234567890123456789') {
+    check('discord clientId set', 'fail', cfg.clientId || '(empty)',
+      `paste your discord application ID into ${CONFIG_PATH}`);
+  } else if (!/^\d{17,21}$/.test(String(cfg.clientId))) {
+    check('discord clientId set', 'warn', `${cfg.clientId} doesn't look like a snowflake`,
+      'discord application IDs are 17–21 digits');
+  } else {
+    check('discord clientId set', 'pass', String(cfg.clientId));
+  }
+
+  const hasByStatus = !!cfg.presence?.byStatus;
+  const hasRotation = Array.isArray(cfg.presence?.rotation) && cfg.presence.rotation.length > 0;
+  if (hasByStatus) {
+    check('presence schema', 'pass', 'byStatus block present (v0.3.6+ shape)');
+  } else if (hasRotation) {
+    check('presence schema', 'warn', 'legacy rotation only — no byStatus block',
+      'run `claude-rpc setup` again to migrate config into the byStatus shape');
+  } else {
+    check('presence schema', 'warn', 'no presence templates configured',
+      'either rotation or byStatus is needed for the card to render');
+  }
+  return cfg;
+}
+
+function checkClaudeHome() {
+  if (!existsSync(CLAUDE_HOME)) {
+    check('~/.claude exists', 'fail', CLAUDE_HOME,
+      'install claude code first — https://claude.com/claude-code');
+    return false;
+  }
+  check('~/.claude exists', 'pass', CLAUDE_HOME);
+  return true;
+}
+
+function checkClaudeProjects() {
+  if (!existsSync(CLAUDE_PROJECTS)) {
+    check('~/.claude/projects exists', 'warn', 'no transcripts on disk yet',
+      'open claude code and prompt once — the directory is created lazily');
+    return 0;
+  }
+  let count = 0;
+  try {
+    for (const proj of readdirSync(CLAUDE_PROJECTS)) {
+      for (const f of readdirSync(join(CLAUDE_PROJECTS, proj))) {
+        if (f.endsWith('.jsonl')) count++;
+      }
+    }
+  } catch {}
+  check('claude transcripts visible', count > 0 ? 'pass' : 'warn',
+    `${count} .jsonl ${count === 1 ? 'file' : 'files'}`,
+    count === 0 ? 'open claude code and send a prompt — transcripts appear immediately' : '');
+  return count;
+}
+
+const HOOK_EVENTS = [
+  'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse',
+  'Stop', 'SubagentStop', 'Notification', 'SessionEnd',
+];
+
+function isOurHookCommand(cmd) {
+  if (!cmd) return false;
+  return /claude-rpc/i.test(cmd) || /hook\.js/i.test(cmd);
+}
+
+function checkHooks() {
+  if (!existsSync(CLAUDE_SETTINGS)) {
+    check('hooks registered', 'fail', `${CLAUDE_SETTINGS} missing`,
+      'run `claude-rpc setup` to register hooks');
+    return;
+  }
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(CLAUDE_SETTINGS, 'utf8'));
+  } catch (e) {
+    check('hooks registered', 'fail', `parse error: ${e.message}`,
+      `open ${CLAUDE_SETTINGS} and fix the JSON syntax`);
+    return;
+  }
+  const missing = [];
+  const stale = [];
+  for (const event of HOOK_EVENTS) {
+    const bucket = settings.hooks?.[event];
+    if (!Array.isArray(bucket) || bucket.length === 0) { missing.push(event); continue; }
+    const ours = bucket.flatMap((e) => e.hooks || []).find((h) => isOurHookCommand(h.command));
+    if (!ours) { missing.push(event); continue; }
+    if (IS_PACKAGED && !ours.command.includes(CANONICAL_EXE)) stale.push({ event, cmd: ours.command });
+    if (IS_NPM_INSTALL && !/\bclaude-rpc\b\s+hook\b/.test(ours.command)) stale.push({ event, cmd: ours.command });
+  }
+  if (missing.length === 0 && stale.length === 0) {
+    check(`hooks registered (${HOOK_EVENTS.length}/${HOOK_EVENTS.length})`, 'pass',
+      'all events wired against the current binary');
+  } else if (missing.length === HOOK_EVENTS.length) {
+    check('hooks registered', 'fail', 'no claude-rpc hooks found',
+      'run `claude-rpc setup` to register hooks');
+  } else if (missing.length > 0) {
+    check('hooks registered', 'warn', `missing: ${missing.join(', ')}`,
+      'run `claude-rpc setup` to add the missing events');
+  } else if (stale.length > 0) {
+    check('hooks registered', 'warn',
+      `${stale.length} pointing at an old binary path`,
+      'run `claude-rpc setup` to refresh hook commands against the current binary');
+  }
+}
+
+function checkCanonicalExe() {
+  if (!IS_PACKAGED) {
+    check('canonical exe', 'pass', `not applicable (${IS_NPM_INSTALL ? 'npm' : 'dev'} mode)`);
+    return;
+  }
+  if (existsSync(CANONICAL_EXE)) {
+    let size = '';
+    try { size = `${(statSync(CANONICAL_EXE).size / 1024 / 1024).toFixed(1)} MB`; } catch {}
+    check('canonical exe installed', 'pass', `${CANONICAL_EXE} (${size})`);
+  } else {
+    check('canonical exe installed', 'fail', `missing: ${CANONICAL_EXE}`,
+      'run `claude-rpc setup` to copy this binary to the canonical location');
+  }
+}
+
+function isAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function checkDaemon() {
+  if (!existsSync(PID_PATH)) {
+    check('daemon running', 'warn', 'no pid file',
+      'run `claude-rpc start` to launch the daemon');
+    return false;
+  }
+  const pid = Number(readFileSync(PID_PATH, 'utf8'));
+  if (!pid || !isAlive(pid)) {
+    check('daemon running', 'fail', `stale pid file (${pid})`,
+      'run `claude-rpc start` — old daemon died without cleaning up');
+    return false;
+  }
+  check('daemon running', 'pass', `pid ${pid}`);
+  return true;
+}
+
+function checkDaemonLog() {
+  if (!existsSync(LOG_PATH)) {
+    check('daemon log', 'warn', 'no log file yet',
+      'daemon will create this on first start');
+    return;
+  }
+  let st;
+  try { st = statSync(LOG_PATH); } catch {
+    check('daemon log', 'warn', 'unreadable');
+    return;
+  }
+  const ageMin = (Date.now() - st.mtimeMs) / 60_000;
+  const sizeKB = (st.size / 1024).toFixed(1);
+  // Look for "Discord RPC connected" in the tail to confirm Discord IPC.
+  let connected = false;
+  try {
+    const tail = readFileSync(LOG_PATH, 'utf8').split('\n').slice(-50).join('\n');
+    connected = /Discord RPC connected/i.test(tail);
+  } catch {}
+  if (connected) {
+    check('discord IPC connection', 'pass',
+      `${sizeKB} KB log · last write ${ageMin.toFixed(1)} min ago`);
+  } else {
+    check('discord IPC connection', 'warn',
+      `log shows no recent "connected" line`,
+      'is the discord desktop client running? rpc only works via desktop, not browser');
+  }
+}
+
+function checkState() {
+  if (!existsSync(STATE_PATH)) {
+    check('state.json', 'warn', 'not present', 'created by the first hook event');
+    return;
+  }
+  let state;
+  try { state = JSON.parse(readFileSync(STATE_PATH, 'utf8')); }
+  catch (e) {
+    check('state.json', 'fail', `parse error: ${e.message}`,
+      `delete ${STATE_PATH} and let the next hook event recreate it`);
+    return;
+  }
+  const ageMin = state.lastActivity
+    ? (Date.now() - state.lastActivity) / 60_000
+    : Infinity;
+  const ageLabel = ageMin === Infinity ? 'never' : `${ageMin.toFixed(1)} min ago`;
+  check('state.json fresh', 'pass', `status=${state.status} · last activity ${ageLabel}`);
+}
+
+function checkAggregate() {
+  if (!existsSync(AGGREGATE_PATH)) {
+    check('aggregate built', 'warn', 'never scanned',
+      'run `claude-rpc scan` to build lifetime stats from your transcripts');
+    return;
+  }
+  try {
+    const agg = JSON.parse(readFileSync(AGGREGATE_PATH, 'utf8'));
+    const hours = ((agg.activeMs || 0) / 3_600_000).toFixed(1);
+    const ageMin = (Date.now() - statSync(AGGREGATE_PATH).mtimeMs) / 60_000;
+    check('aggregate built', 'pass',
+      `${agg.sessions || 0} sessions · ${hours}h · refreshed ${ageMin.toFixed(0)} min ago`);
+  } catch (e) {
+    check('aggregate built', 'fail', `parse error: ${e.message}`,
+      'run `claude-rpc rescan` to rebuild the aggregate from scratch');
+  }
+}
+
+function checkPrivacy(cfg) {
+  try {
+    const cwd = process.cwd();
+    const { visibility, projectName, reason } = resolveVisibility(cwd, cfg || {});
+    const listed = listPrivateCwds();
+    const detail = projectName
+      ? `${visibility}  ·  alias=${projectName}  ·  ${reason}`
+      : `${visibility}  ·  ${reason}`;
+    const status = visibility === 'hidden' ? 'warn'
+                 : visibility === 'name-only' ? 'warn'
+                 : 'pass';
+    check('current directory visibility', status, detail);
+    if (listed.length) {
+      check('private-list entries', 'pass', `${listed.length} ${listed.length === 1 ? 'path' : 'paths'} marked private`);
+    } else {
+      check('private-list entries', 'pass', 'none');
+    }
+  } catch (e) {
+    check('privacy check', 'warn', `lookup failed: ${e.message}`);
+  }
+}
+
+function checkLiveSessions() {
+  try {
+    const live = findLiveSessions({ thresholdMs: 90_000 });
+    if (live.length === 0) {
+      check('live sessions', 'pass',
+        'none — claude code isn\'t actively writing a transcript right now');
+    } else {
+      const names = live.slice(0, 3).map((s) => `${s.project}(${s.ageSec}s)`).join(', ');
+      check('live sessions', 'pass', `${live.length} active: ${names}`);
+    }
+  } catch (e) {
+    check('live sessions', 'warn', `lookup failed: ${e.message}`);
+  }
+}
+
+function checkDataDir() {
+  if (!existsSync(USER_CONFIG_DIR)) {
+    check('user config dir', 'warn', `${USER_CONFIG_DIR} missing`,
+      'run `claude-rpc setup` — this is created automatically');
+    return;
+  }
+  check('user config dir', 'pass', USER_CONFIG_DIR);
+}
+
+// ── public entry point ──────────────────────────────────────────────────
+
+export function runDoctor() {
+  console.log(`${c.bold}${c.cyan}claude-rpc doctor${c.reset}  ${c.dim}— diagnostic checklist${c.reset}`);
+
+  section('Runtime');
+  checkNodeVersion();
+  checkMode();
+  checkCanonicalExe();
+
+  section('Config');
+  checkDataDir();
+  const cfg = checkConfig();
+
+  section('Claude Code');
+  if (checkClaudeHome()) {
+    checkClaudeProjects();
+    checkHooks();
+  }
+
+  section('Daemon');
+  checkDaemon();
+  checkDaemonLog();
+  checkState();
+
+  section('Data');
+  checkAggregate();
+  checkLiveSessions();
+
+  section('Privacy');
+  checkPrivacy(cfg);
+
+  // Summary
+  const { pass, fail, warn } = counters;
+  console.log('');
+  console.log(`  ${c.bold}Summary:${c.reset}  ${c.green}${pass} pass${c.reset}` +
+    (warn ? `  ${c.yellow}${warn} warn${c.reset}` : '') +
+    (fail ? `  ${c.red}${fail} fail${c.reset}` : ''));
+  if (fail === 0 && warn === 0) {
+    console.log(`  ${c.dim}everything looks good. if presence still isn't showing, restart discord.${c.reset}`);
+  } else if (fail === 0) {
+    console.log(`  ${c.dim}no failures — warnings are usually fixed by running \`claude-rpc setup\`.${c.reset}`);
+  }
+  console.log('');
+
+  return fail === 0 ? 0 : 1;
+}

package/src/privacy.js

@@ -0,0 +1,231 @@
+// Privacy mode — controls what the Discord card shows about a given cwd.
+// Three layers, highest-priority first:
+//
+//   1. Per-project ./.claude-rpc.json file in the project root.
+//      { "visibility": "hidden|name-only|public", "projectName": "alias" }
+//      Shortcut: { "private": true } == { "visibility": "hidden" }
+//   2. Runtime list at ~/.claude-rpc/private-list.json, toggled by
+//      `claude-rpc private` / `claude-rpc public`.
+//   3. Auto-detection of GitHub private repos via the `gh` CLI when
+//      installed. Best-effort, silently skips when gh isn't available
+//      or auth isn't set up. Cached per-cwd with 5min TTL.
+//
+// "Visibility" levels:
+//   public      everything as-is (default)
+//   name-only   project name kept, but currentFile / currentTool / files
+//               arrays cleared so the card doesn't leak paths
+//   hidden      cwd cleared entirely; daemon then short-circuits to
+//               clearActivity (same effect as hideWhenStale)
+//
+// Aggregates (scanner) and the local TUI/web dashboards are NEVER affected
+// by these flags. Privacy is a one-way valve from local state → Discord.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, basename, dirname, resolve as resolvePath } from 'node:path';
+import { DATA_DIR } from './paths.js';
+
+const PRIVATE_LIST_PATH = join(DATA_DIR, 'private-list.json');
+const TTL_MS = 5 * 60 * 1000;
+
+const projectFileCache = new Map();   // cwd → { ts, value | null }
+const ghPrivateCache  = new Map();    // cwd → { ts, value: bool | null }
+
+// ── Per-project .claude-rpc.json ────────────────────────────────────────
+
+// Walk up from `cwd` looking for a .claude-rpc.json. Stops at the first
+// match or at a .git directory (the project root). Lets a subdirectory
+// inherit the parent's privacy config.
+function findProjectFile(cwd) {
+  if (!cwd) return null;
+  let dir = cwd;
+  while (true) {
+    const candidate = join(dir, '.claude-rpc.json');
+    if (existsSync(candidate)) return candidate;
+    if (existsSync(join(dir, '.git'))) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function readProjectConfig(cwd) {
+  if (!cwd) return null;
+  const cached = projectFileCache.get(cwd);
+  if (cached && Date.now() - cached.ts < TTL_MS) return cached.value;
+  let value = null;
+  const path = findProjectFile(cwd);
+  if (path) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf8'));
+      if (parsed && typeof parsed === 'object') value = parsed;
+    } catch { /* broken JSON ≡ no override */ }
+  }
+  projectFileCache.set(cwd, { ts: Date.now(), value });
+  return value;
+}
+
+function normalizeProjectConfig(cfg) {
+  if (!cfg) return null;
+  let visibility = cfg.visibility;
+  if (cfg.private === true && !visibility) visibility = 'hidden';
+  if (!['public', 'name-only', 'hidden'].includes(visibility)) visibility = null;
+  return {
+    visibility,
+    projectName: typeof cfg.projectName === 'string' ? cfg.projectName : null,
+  };
+}
+
+// ── Runtime private-list ────────────────────────────────────────────────
+
+function readPrivateList() {
+  if (!existsSync(PRIVATE_LIST_PATH)) return { paths: [] };
+  try {
+    const v = JSON.parse(readFileSync(PRIVATE_LIST_PATH, 'utf8'));
+    if (Array.isArray(v?.paths)) return v;
+  } catch {}
+  return { paths: [] };
+}
+
+function writePrivateList(list) {
+  if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
+  writeFileSync(PRIVATE_LIST_PATH, JSON.stringify(list, null, 2));
+}
+
+export function addPrivateCwd(cwd) {
+  const list = readPrivateList();
+  const abs = resolvePath(cwd);
+  if (!list.paths.includes(abs)) {
+    list.paths.push(abs);
+    writePrivateList(list);
+  }
+  return list.paths;
+}
+
+export function removePrivateCwd(cwd) {
+  const list = readPrivateList();
+  const abs = resolvePath(cwd);
+  list.paths = list.paths.filter((p) => p !== abs);
+  writePrivateList(list);
+  return list.paths;
+}
+
+export function listPrivateCwds() {
+  return readPrivateList().paths;
+}
+
+function isInPrivateList(cwd) {
+  if (!cwd) return false;
+  const abs = resolvePath(cwd);
+  return readPrivateList().paths.some(
+    (p) => abs === p || abs.startsWith(p + '/') || abs.startsWith(p + '\\')
+  );
+}
+
+// ── GitHub-private detection (best-effort, gh CLI) ──────────────────────
+
+function detectGithubPrivate(cwd) {
+  if (!cwd) return null;
+  const cached = ghPrivateCache.get(cwd);
+  if (cached && Date.now() - cached.ts < TTL_MS) return cached.value;
+  let value = null;
+  try {
+    const out = execFileSync(
+      'gh',
+      ['repo', 'view', '--json', 'isPrivate', '-q', '.isPrivate'],
+      { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500 }
+    ).toString().trim();
+    if (out === 'true') value = true;
+    else if (out === 'false') value = false;
+  } catch { /* gh missing, not auth'd, not a repo, timeout — unknown */ }
+  ghPrivateCache.set(cwd, { ts: Date.now(), value });
+  return value;
+}
+
+// ── Resolution + application ────────────────────────────────────────────
+
+// Resolve effective visibility for a cwd.
+// Returns: { visibility, projectName, reason }
+export function resolveVisibility(cwd, config = {}) {
+  const proj = normalizeProjectConfig(readProjectConfig(cwd));
+  if (proj?.visibility) {
+    return { visibility: proj.visibility, projectName: proj.projectName, reason: '.claude-rpc.json' };
+  }
+  if (isInPrivateList(cwd)) {
+    return { visibility: 'hidden', projectName: proj?.projectName ?? null, reason: 'private-list' };
+  }
+  const patterns = config?.privacy?.patterns || [];
+  if (patterns.length && cwd) {
+    const leaf = basename(cwd);
+    for (const p of patterns) {
+      if (matchesPattern(leaf, p)) {
+        const mode = config?.privacy?.mode || 'hidden';
+        return { visibility: mode, projectName: proj?.projectName ?? null, reason: `config pattern '${p}'` };
+      }
+    }
+  }
+  if (config?.privacy?.autoDetectGithubPrivate !== false) {
+    const isPrivate = detectGithubPrivate(cwd);
+    if (isPrivate === true) {
+      const mode = config?.privacy?.githubPrivateMode || 'hidden';
+      return { visibility: mode, projectName: proj?.projectName ?? null, reason: 'github private repo' };
+    }
+  }
+  return { visibility: 'public', projectName: proj?.projectName ?? null, reason: 'default' };
+}
+
+// Glob-lite. '*' matches any run; otherwise plain text. Case-insensitive.
+function matchesPattern(name, pattern) {
+  if (pattern === name) return true;
+  if (!pattern.includes('*')) return false;
+  const re = new RegExp('^' + pattern.split('*').map(escapeRe).join('.*') + '$', 'i');
+  return re.test(name);
+}
+function escapeRe(s) { return s.replace(/[.+?^${}()|[\]\\]/g, '\\$&'); }
+
+// Apply privacy to a post-applyIdle state. Pure function — no IO.
+export function applyPrivacy(state, config = {}) {
+  if (!state || state.status === 'stale') return state;
+  const { visibility, projectName } = resolveVisibility(state.cwd || '', config);
+
+  if (visibility === 'public') {
+    if (projectName) {
+      return { ...state, cwd: joinCwdAlias(state.cwd, projectName), _privacy: { visibility, alias: true } };
+    }
+    return state;
+  }
+
+  if (visibility === 'name-only') {
+    return {
+      ...state,
+      cwd: projectName ? joinCwdAlias(state.cwd, projectName) : state.cwd,
+      currentTool: null,
+      currentFile: null,
+      filesEdited: [],
+      filesRead: [],
+      filesOpened: [],
+      _privacy: { visibility, alias: !!projectName },
+    };
+  }
+
+  // hidden
+  return {
+    ...state,
+    cwd: '',
+    currentTool: null,
+    currentFile: null,
+    filesEdited: [],
+    filesRead: [],
+    filesOpened: [],
+    _privacy: { visibility, alias: false },
+  };
+}
+
+function joinCwdAlias(cwd, alias) {
+  if (!cwd) return alias;
+  const sep = cwd.includes('\\') ? '\\' : '/';
+  const parts = cwd.split(/[\\/]/).filter(Boolean);
+  if (!parts.length) return alias;
+  parts[parts.length - 1] = alias;
+  return (cwd.startsWith('/') ? '/' : '') + parts.join(sep);
+}