@henryz2004/agency 1.0.0

package/lib/opencode.js

@@ -0,0 +1,447 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { DATA_DIR } from './paths.js';
+
+const HOME = os.homedir();
+const DB_PATH = path.join(HOME, '.local', 'share', 'opencode', 'opencode.db');
+
+function dbExists() {
+  try {
+    fs.accessSync(DB_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function escId(s) {
+  return String(s).replace(/'/g, "''");
+}
+
+function query(sql) {
+  if (!dbExists()) return [];
+  try {
+    const out = execFileSync('sqlite3', [DB_PATH, '-cmd', '.timeout 3000', '-json', sql], {
+      timeout: 4000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (!out.trim()) return [];
+    return JSON.parse(out);
+  } catch {
+    return [];
+  }
+}
+
+const AGENTS_DIR = path.join(HOME, '.local', 'share', 'opencode', 'agents');
+
+function isAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+function getLiveFromHeartbeats(now) {
+  let files;
+  try {
+    files = fs.readdirSync(AGENTS_DIR);
+  } catch {
+    return null;
+  }
+
+  const jsonFiles = files.filter((f) => f.endsWith('.json'));
+  if (!jsonFiles.length) return null; // no plugin installed yet — fall back to DB
+
+  // First pass: read every live heartbeat. The opencode plugin writes ONE file
+  // per session, INCLUDING subagents a session spawns (each carries a non-null
+  // `parentId` pointing at the session that launched it). A subagent shares its
+  // parent's pid + cwd, so emitting both as top-level floor agents shows the
+  // SAME opencode session as two desks — the duplicate this dedup removes.
+  const heartbeats = [];
+  const liveIds = new Set();
+  for (const f of jsonFiles) {
+    let hb;
+    try {
+      hb = JSON.parse(fs.readFileSync(path.join(AGENTS_DIR, f), 'utf8'));
+    } catch {
+      continue;
+    }
+
+    if (!isAlive(hb.pid)) {
+      try { fs.unlinkSync(path.join(AGENTS_DIR, f)); } catch {}
+      continue;
+    }
+
+    heartbeats.push(hb);
+    if (hb.sessionId) liveIds.add(hb.sessionId);
+  }
+
+  // Collect each parent's running subagents, keyed by parentId. We only fold a
+  // child into a parent that is ALSO live here — an orphaned subagent (parent
+  // heartbeat already reaped) stays a standalone agent rather than vanishing.
+  const childrenByParent = new Map();
+  for (const hb of heartbeats) {
+    const parent = hb.parentId || null;
+    if (parent && liveIds.has(parent)) {
+      const list = childrenByParent.get(parent) || [];
+      list.push({ type: hb.agent || 'agent' }); // matches Claude's subagent shape
+      childrenByParent.set(parent, list);
+    }
+  }
+
+  const agents = [];
+  for (const hb of heartbeats) {
+    // Skip subagents whose parent is live — they fold into the parent below.
+    if (hb.parentId && liveIds.has(hb.parentId)) continue;
+
+    const cwd = hb.cwd || null;
+    const activity = hb.status === 'idle' ? 'idle' : 'working';
+    const startedAt = hb.startedAt || null;
+
+    const metrics = hb.sessionId ? metricsFor(hb.sessionId) : { toolCalls30m: 0, tokensOut30m: 0, windowMin: 30 };
+    agents.push({
+      pid: hb.pid,
+      sessionId: hb.sessionId || null,
+      source: 'opencode',
+      cwd,
+      project: cwd ? path.basename(cwd) : 'unknown',
+      kind: hb.agent || 'interactive',
+      activity,
+      status: activity === 'working' ? 'busy' : 'idle',
+      state: null,
+      needsYou: false,
+      task: hb.title || null,
+      chatName: hb.title || null,
+      lastPrompt: null,
+      subagents: hb.sessionId ? (childrenByParent.get(hb.sessionId) || []) : [],
+      startedAt,
+      uptimeMs: startedAt ? Math.max(0, now - startedAt) : null,
+      model: hb.model || null,
+      provider: hb.provider || null,
+      metrics,
+    });
+  }
+
+  return agents.length ? agents : [];
+}
+
+function activityFor(sessionId) {
+  const rows = query(
+    `SELECT json_extract(data, '$.type') as ptype, json_extract(data, '$.state.status') as status ` +
+    `FROM part WHERE session_id = '${escId(sessionId)}' ` +
+    `ORDER BY time_created DESC LIMIT 20`
+  );
+  for (const r of rows) {
+    if (r.ptype === 'tool' && r.status === 'running') return 'shell';
+    if (r.ptype === 'step-start') return 'working';
+    if (r.ptype === 'step-finish') return 'idle';
+  }
+  return 'idle';
+}
+
+function metricsFor(sessionId) {
+  const now = Date.now();
+  const cutoff = now - 30 * 60 * 1000;
+  const sid = escId(sessionId);
+  const toolRows = query(
+    `SELECT COUNT(*) as cnt FROM part WHERE session_id = '${sid}' ` +
+    `AND json_extract(data, '$.type') = 'tool' AND time_created >= ${cutoff}`
+  );
+  const tokRows = query(
+    `SELECT COALESCE(SUM(json_extract(data, '$.tokens.output')), 0) as tok_out ` +
+    `FROM part WHERE session_id = '${sid}' ` +
+    `AND json_extract(data, '$.type') = 'step-finish' AND time_created >= ${cutoff}`
+  );
+  return {
+    toolCalls30m: (toolRows[0] && toolRows[0].cnt) || 0,
+    tokensOut30m: (tokRows[0] && tokRows[0].tok_out) || 0,
+    windowMin: 30,
+  };
+}
+
+export function getOpenCodeLive() {
+  const now = Date.now();
+
+  const heartbeatAgents = getLiveFromHeartbeats(now);
+  if (heartbeatAgents) {
+    return { agents: heartbeatAgents, now };
+  }
+
+  const staleCutoff = now - 30 * 60 * 1000;
+  const sessions = query(
+    `SELECT id, title, model, directory, agent, tokens_input, tokens_output, ` +
+    `tokens_cache_read, tokens_cache_write, tokens_reasoning, cost, ` +
+    `time_created, time_updated ` +
+    `FROM session WHERE time_archived IS NULL AND time_updated > ${staleCutoff} ORDER BY time_updated DESC`
+  );
+  if (!sessions.length) return { agents: [], now };
+
+  const agents = sessions.map((s) => {
+    let modelObj = {};
+    try { modelObj = JSON.parse(s.model || '{}'); } catch { /* ignore */ }
+    const modelId = modelObj.id || 'unknown';
+    const provider = modelObj.providerID || '';
+    const startedAt = s.time_created;
+    const uptimeMs = startedAt ? Math.max(0, now - startedAt) : null;
+    const activity = activityFor(s.id);
+    const cwd = s.directory || null;
+
+    const titleRows = query(
+      `SELECT substr(json_extract(data, '$.text'), 1, 80) as txt ` +
+      `FROM part WHERE session_id = '${escId(s.id)}' AND json_extract(data, '$.type') = 'text' ` +
+      `ORDER BY time_created DESC LIMIT 1`
+    );
+    const lastPrompt = titleRows.length ? titleRows[0].txt : null;
+
+    const metrics = metricsFor(s.id);
+    return {
+      pid: null,
+      sessionId: s.id,
+      source: 'opencode',
+      cwd,
+      project: cwd ? path.basename(cwd) : 'unknown',
+      kind: s.agent || 'interactive',
+      activity,
+      status: activity === 'working' ? 'busy' : 'idle',
+      state: null,
+      needsYou: false,
+      task: s.title || null,
+      chatName: s.title || null,
+      lastPrompt,
+      subagents: [],
+      startedAt,
+      uptimeMs,
+      model: modelId,
+      provider,
+      metrics,
+    };
+  });
+
+  return { agents, now };
+}
+
+// ---- usage -----------------------------------------------------------------
+
+const CACHE_PATH = path.join(DATA_DIR, 'opencode-usage-cache.json');
+
+let cache = { version: 2, lastDbMtime: 0, sessions: {} };
+let loaded = false;
+
+function loadCache() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(CACHE_PATH, 'utf8'));
+    if (raw && raw.version === cache.version) cache = raw;
+  } catch { /* no cache yet */ }
+}
+
+function saveCache() {
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    fs.writeFileSync(CACHE_PATH, JSON.stringify(cache));
+  } catch { /* best effort */ }
+}
+
+function localDay(ts) {
+  const d = new Date(ts);
+  if (Number.isNaN(d.getTime())) return null;
+  return d.toLocaleDateString('en-CA');
+}
+
+function emptyDay() {
+  return { out: 0, in: 0, cr: 0, cc: 0, tools: 0, msgs: 0, agents: 0 };
+}
+
+function parseSession(s) {
+  let modelObj = {};
+  try { modelObj = JSON.parse(s.model || '{}'); } catch { /* ignore */ }
+  const modelId = modelObj.id || 'unknown';
+
+  const parts = query(
+    `SELECT json_extract(data, '$.type') as ptype, ` +
+    `json_extract(data, '$.tokens.input') as tok_in, ` +
+    `json_extract(data, '$.tokens.output') as tok_out, ` +
+    `json_extract(data, '$.tokens.cache.read') as tok_cr, ` +
+    `json_extract(data, '$.tokens.cache.write') as tok_cc, ` +
+    `json_extract(data, '$.tokens.reasoning') as tok_reason, ` +
+    `json_extract(data, '$.tool') as tool_name, ` +
+    `json_extract(data, '$.text') as txt, ` +
+    `time_created ` +
+    `FROM part WHERE session_id = '${escId(s.id)}' ` +
+    `AND json_extract(data, '$.type') IN ('step-finish', 'tool') ` +
+    `ORDER BY time_created ASC`
+  );
+
+  const agg = {
+    days: {},
+    models: {},
+    project: s.directory ? path.basename(s.directory) : 'unknown',
+    cwd: s.directory || null,
+    sessionId: s.id,
+    firstTs: s.time_created,
+    lastTs: s.time_updated,
+    out: 0,
+    in: 0,
+    cr: 0,
+    cc: 0,
+    tools: 0,
+    msgs: 0,
+    agents: 0,
+  };
+
+  for (const p of parts) {
+    const ts = p.time_created;
+    if (!ts) continue;
+
+    if (p.ptype === 'step-finish') {
+      const out = p.tok_out || 0;
+      const inp = p.tok_in || 0;
+      const cr = p.tok_cr || 0;
+      const cc = p.tok_cc || 0;
+
+      agg.out += out;
+      agg.in += inp;
+      agg.cr += cr;
+      agg.cc += cc;
+      agg.msgs += 1;
+
+      const day = localDay(ts);
+      if (day) {
+        const d = (agg.days[day] ||= emptyDay());
+        d.out += out;
+        d.in += inp;
+        d.cr += cr;
+        d.cc += cc;
+        d.msgs += 1;
+      }
+
+      if (!agg.models[modelId]) agg.models[modelId] = { out: 0, in: 0, msgs: 0 };
+      agg.models[modelId].out += out;
+      agg.models[modelId].in += inp;
+      agg.models[modelId].msgs += 1;
+    }
+
+    if (p.ptype === 'tool') {
+      agg.tools += 1;
+      const toolName = p.tool_name || '';
+      if (toolName === 'task' || toolName === 'agent') agg.agents += 1;
+      const day = localDay(ts);
+      if (day) {
+        const d = (agg.days[day] ||= emptyDay());
+        d.tools += 1;
+        if (toolName === 'task' || toolName === 'agent') d.agents += 1;
+      }
+    }
+  }
+
+  return agg;
+}
+
+export function getOpenCodeUsage() {
+  if (!dbExists()) return null;
+
+  if (!loaded) {
+    loadCache();
+    loaded = true;
+  }
+
+  let dbMtime = 0;
+  try {
+    dbMtime = fs.statSync(DB_PATH).mtimeMs;
+  } catch { /* ignore */ }
+
+  if (dbMtime !== cache.lastDbMtime) {
+    const sessions = query(
+      `SELECT id, title, model, directory, tokens_input, tokens_output, ` +
+      `tokens_cache_read, tokens_cache_write, tokens_reasoning, cost, ` +
+      `time_created, time_updated ` +
+      `FROM session ORDER BY time_updated ASC`
+    );
+
+    const seen = new Set();
+    for (const s of sessions) {
+      seen.add(s.id);
+      const prev = cache.sessions[s.id];
+      if (prev && prev.updatedAt === s.time_updated) continue;
+      cache.sessions[s.id] = {
+        updatedAt: s.time_updated,
+        agg: parseSession(s),
+      };
+    }
+    for (const id of Object.keys(cache.sessions)) {
+      if (!seen.has(id)) delete cache.sessions[id];
+    }
+    cache.lastDbMtime = dbMtime;
+    saveCache();
+  }
+
+  return combine();
+}
+
+function combine() {
+  const lifetime = { out: 0, in: 0, cr: 0, cc: 0, tools: 0, msgs: 0, agents: 0, sessions: 0 };
+  const dayMap = {};
+  const byModel = {};
+  const byProject = {};
+
+  for (const { agg } of Object.values(cache.sessions)) {
+    if (!agg) continue;
+    lifetime.out += agg.out;
+    lifetime.in += agg.in;
+    lifetime.cr += agg.cr;
+    lifetime.cc += agg.cc;
+    lifetime.tools += agg.tools;
+    lifetime.msgs += agg.msgs;
+    lifetime.agents += agg.agents;
+    lifetime.sessions += 1;
+
+    for (const [day, d] of Object.entries(agg.days)) {
+      const t = (dayMap[day] ||= emptyDay());
+      t.out += d.out;
+      t.in += d.in;
+      t.cr += d.cr;
+      t.cc += d.cc;
+      t.tools += d.tools;
+      t.agents += d.agents;
+      t.msgs += d.msgs;
+    }
+
+    for (const [m, v] of Object.entries(agg.models)) {
+      const t = (byModel[m] ||= { out: 0, in: 0, msgs: 0 });
+      t.out += v.out;
+      t.in += v.in;
+      t.msgs += v.msgs;
+    }
+
+    const proj = agg.project || 'unknown';
+    const p = (byProject[proj] ||= { out: 0, msgs: 0, tools: 0, agents: 0, sessions: 0, lastTs: null });
+    p.out += agg.out;
+    p.msgs += agg.msgs;
+    p.tools += agg.tools;
+    p.agents += agg.agents;
+    p.sessions += 1;
+    if (agg.lastTs && (!p.lastTs || agg.lastTs > p.lastTs)) p.lastTs = agg.lastTs;
+  }
+
+  const daily = Object.entries(dayMap)
+    .map(([date, v]) => ({ date, ...v }))
+    .sort((a, b) => (a.date < b.date ? -1 : 1));
+
+  const today = new Date().toLocaleDateString('en-CA');
+  const todayStats = dayMap[today] ? { date: today, ...dayMap[today] } : { date: today, ...emptyDay() };
+
+  return {
+    lifetime,
+    today: todayStats,
+    daily,
+    byModel,
+    byProject,
+    firstDay: daily.length ? daily[0].date : null,
+    activeDays: daily.length,
+  };
+}

package/lib/paths.js

@@ -0,0 +1,12 @@
+// paths.js — where Agency persists its regenerable caches + roster.
+// A published / `npx` install runs from a read-only or ephemeral package dir,
+// so state lives in the user's home (~/.agency) by default. Override with
+// AGENCY_DATA_DIR (e.g. `AGENCY_DATA_DIR=./data` to keep it repo-local in dev).
+// ponytail: one rule, no dev/prod heuristic — set the env var if you want local.
+
+import path from 'node:path';
+import os from 'node:os';
+
+export const DATA_DIR = process.env.AGENCY_DATA_DIR
+  ? path.resolve(process.env.AGENCY_DATA_DIR)
+  : path.join(os.homedir(), '.agency');

package/lib/roster.js

@@ -0,0 +1,204 @@
+// roster.js — assign each session a stable identity: a name, a job title keyed
+// to its model tier, an avatar palette, and a hire date. Identities are derived
+// deterministically from the sessionId (so they're stable even before the file
+// is written) and persisted to data/roster.json to record tenure.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DATA_DIR } from './paths.js';
+
+const ROSTER_PATH = path.join(DATA_DIR, 'roster.json');
+
+const FIRST = [
+  'Ada', 'Ravi', 'Mona', 'Kenji', 'Lena', 'Otis', 'Priya', 'Theo', 'Yara', 'Cole',
+  'Nina', 'Dax', 'Ines', 'Bram', 'Suki', 'Ezra', 'Vera', 'Knox', 'Tara', 'Joon',
+  'Remy', 'Fynn', 'Wren', 'Iris', 'Beau', 'Sol', 'Hana', 'Milo', 'Faye', 'Ace',
+];
+const LAST = [
+  'Vance', 'Okoro', 'Sato', 'Reyes', 'Novak', 'Kapoor', 'Mertz', 'Holt', 'Ferro',
+  'Lund', 'Cruz', 'Bose', 'Pike', 'Calder', 'Ono', 'Frost', 'Wells', 'Drake',
+  'Marsh', 'Vega', 'Sloan', 'Quill', 'Rhodes', 'Tran', 'Voss', 'Hale', 'Ng', 'Booth',
+];
+
+// Job titles by model tier — the office hierarchy.
+const TITLES = {
+  opus: ['Principal Engineer', 'Staff Architect', 'Lead Engineer', 'Distinguished Eng'],
+  sonnet: ['Senior Engineer', 'Software Engineer II', 'Product Engineer', 'Full-Stack Dev'],
+  haiku: ['Junior Engineer', 'Associate Dev', 'Intern', 'Apprentice'],
+  unknown: ['Contractor', 'Specialist', 'Generalist'],
+};
+
+// Avatar shirt/hair palettes — picked deterministically per agent.
+const SHIRTS = [
+  '#e05d5d', '#5d9ce0', '#5dc98a', '#e0b05d', '#a87de0', '#e07db0',
+  '#5dc9c9', '#9bd45d', '#e0855d', '#7d8fe0',
+];
+const HAIRS = ['#2b2233', '#5a3a26', '#3a2e22', '#1f2a33', '#4a2233', '#332b1f', '#26333a'];
+const SKINS = ['#f0c8a0', '#e8b890', '#d8a070', '#c08858', '#a87048', '#8a5a3a'];
+
+function hash(str) {
+  let h = 2166136261 >>> 0;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h >>> 0;
+}
+
+function tierFor(model) {
+  if (!model) return 'unknown';
+  const m = model.toLowerCase();
+  if (m.includes('opus')) return 'opus';
+  if (m.includes('sonnet')) return 'sonnet';
+  if (m.includes('haiku')) return 'haiku';
+  if (m.includes('fable')) return 'opus';
+  return 'unknown';
+}
+
+let roster = null;
+
+// Deterministically pick a "First Last" name from the hash, probing the name
+// space until we find one no other chat already owns — so each chat is a
+// distinct, persistent person even when two sessionIds hash near each other.
+function uniqueName(h, id) {
+  const taken = new Set(
+    Object.entries(roster || {})
+      .filter(([k]) => k !== id)
+      .map(([, v]) => v.name)
+  );
+  const total = FIRST.length * LAST.length;
+  let fi = h % FIRST.length;
+  let li = (h >>> 8) % LAST.length;
+  for (let n = 0; n < total; n++) {
+    const name = `${FIRST[fi]} ${LAST[li]}`;
+    if (!taken.has(name)) return name;
+    li = (li + 1) % LAST.length;
+    if (li === (h >>> 8) % LAST.length) fi = (fi + 1) % FIRST.length;
+  }
+  // name space exhausted (>784 chats) — disambiguate with a short suffix
+  return `${FIRST[h % FIRST.length]} ${LAST[(h >>> 8) % LAST.length]} ${id.slice(0, 4)}`;
+}
+
+function load() {
+  if (roster) return;
+  try {
+    roster = JSON.parse(fs.readFileSync(ROSTER_PATH, 'utf8'));
+  } catch {
+    roster = {};
+  }
+}
+
+function save() {
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    fs.writeFileSync(ROSTER_PATH, JSON.stringify(roster, null, 2));
+  } catch {
+    /* best effort */
+  }
+}
+
+// Tier ranking so a momentarily-null model never demotes an agent's title.
+const TIER_RANK = { unknown: 0, haiku: 1, sonnet: 2, opus: 3 };
+
+// Get (or mint) the identity for a session. `model` refines the job title and
+// is allowed to change the tier over the session's life.
+export function identityFor(sessionId, model, firstSeenAt) {
+  load();
+  const id = sessionId || 'anon';
+  const h = hash(id);
+  const tier = tierFor(model);
+
+  let rec = roster[id];
+  let dirty = false;
+  if (!rec) {
+    rec = {
+      name: uniqueName(h, id),
+      skin: SKINS[(h >>> 3) % SKINS.length],
+      hair: HAIRS[(h >>> 11) % HAIRS.length],
+      shirt: SHIRTS[(h >>> 5) % SHIRTS.length],
+      hiredAt: firstSeenAt || Date.now(),
+      tier: 'unknown',
+    };
+    roster[id] = rec;
+    dirty = true;
+  }
+
+  // Keep the best tier ever seen so a transient null model doesn't demote them.
+  if ((TIER_RANK[tier] || 0) > (TIER_RANK[rec.tier] || 0)) {
+    rec.tier = tier;
+    dirty = true;
+  }
+  if (dirty) save();
+
+  const effTier = rec.tier || 'unknown';
+  const titles = TITLES[effTier] || TITLES.unknown;
+  const title = titles[(h >>> 13) % titles.length];
+
+  return {
+    name: rec.customName || rec.name,
+    title,
+    tier: effTier,
+    skin: rec.skin,
+    hair: rec.hair,
+    shirt: rec.shirt,
+    hiredAt: rec.hiredAt,
+  };
+}
+
+// Sanitize a user-supplied custom name: strip control chars, trim, cap length.
+// Returns a non-empty string, or null when the input clears the override.
+// CTRL_RE is built from a plain-ASCII pattern string (no raw control bytes in
+// source) and matches C0 controls (U+0000..U+001F), DEL (U+007F), and C1
+// controls (U+0080..U+009F) so a pasted name cannot smuggle in newlines.
+const NAME_CAP = 60;
+const CTRL_RE = new RegExp('[\\u0000-\\u001F\\u007F-\\u009F]', 'g');
+function cleanName(name) {
+  if (name == null) return null;
+  const s = String(name).replace(CTRL_RE, '').trim().slice(0, NAME_CAP);
+  return s ? s : null;
+}
+
+// Ensure a roster record exists for `sessionId`, minting one via identityFor if
+// missing. Returns the live record (so callers can mutate + save).
+function ensureRec(sessionId) {
+  load();
+  const id = sessionId || 'anon';
+  if (!roster[id]) identityFor(id, null); // mints + persists the base record
+  return roster[id];
+}
+
+// Apply a user override to a session. `patch` may carry `name` and/or `hidden`;
+// only the keys present are touched (so a hide toggle won't wipe a rename and
+// vice-versa). `name`: a non-empty trimmed string sets the custom name; '' or
+// null clears it. `hidden`: a boolean. Returns the effective { name, hidden }.
+// Fail-soft — never throws.
+export function setOverride(sessionId, patch = {}) {
+  try {
+    const rec = ensureRec(sessionId);
+    if (!rec) return { name: null, hidden: false };
+    if (Object.prototype.hasOwnProperty.call(patch, 'name')) {
+      const n = cleanName(patch.name);
+      if (n) rec.customName = n;
+      else delete rec.customName;
+    }
+    if (Object.prototype.hasOwnProperty.call(patch, 'hidden')) {
+      rec.hidden = !!patch.hidden;
+    }
+    save();
+    return { name: rec.customName || null, hidden: !!rec.hidden };
+  } catch {
+    return { name: null, hidden: false };
+  }
+}
+
+// Cheap read of a session's override, defaulting when unset. Fail-soft.
+export function overrideFor(sessionId) {
+  try {
+    load();
+    const rec = roster[sessionId || 'anon'];
+    if (!rec) return { name: null, hidden: false };
+    return { name: rec.customName || null, hidden: !!rec.hidden };
+  } catch {
+    return { name: null, hidden: false };
+  }
+}