@clastres/groundcontrol 0.1.7 → 0.1.8

package/daemon.mjs

@@ -22,7 +22,7 @@ import { createRequire } from 'node:module';
 
 const execFileP = promisify(execFile);
 
-const VERSION = '0.1.7';
+const VERSION = '0.1.8';
 const PACKAGE = '@clastres/groundcontrol';
 
 // ---------- config / pairing ----------
@@ -638,23 +638,40 @@ widenPath();
 const which = (cmd) => { try { return execSync(`command -v ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim() || null; } catch { return null; } };
 const executable = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return p; } catch { return null; } };
 
-const claudeBin = which('claude');
-console.log(`[daemon] claude binary: ${claudeBin || 'NOT FOUND (phone prompts to idle sessions without a visible terminal will fail)'}`);
+// Every agent binary is resolved on use rather than at startup. launchd starts
+// this at login and it then runs for weeks, while CLIs get installed
+// underneath it. Session discovery already rescans the disk every few seconds,
+// so a `const` resolved at boot produces the worst possible split: the new
+// session appears on the phone, its transcript streams, and sending fails with
+// "binary not found" until someone restarts the daemon. Cached for a minute so
+// a prompt does not pay for a PATH scan.
+const binMemo = new Map(); // label -> { at, path }
+function resolveBin(label, find) {
+  const c = binMemo.get(label);
+  if (c && Date.now() - c.at < 60_000) return c.path;
+  let p = null;
+  try { p = find() || null; } catch {}
+  binMemo.set(label, { at: Date.now(), path: p });
+  return p;
+}
+
+const claudeBin = () => resolveBin('claude', () => which('claude'));
+console.log(`[daemon] claude binary: ${claudeBin() || 'NOT FOUND (phone prompts to idle sessions without a visible terminal will fail)'}`);
 
 // Codex ships a full CLI inside the ChatGPT desktop app, so Codex Desktop
 // users can receive phone prompts even without a standalone install.
-const codexBin = which('codex') || executable('/Applications/ChatGPT.app/Contents/Resources/codex');
+const codexBin = () => resolveBin('codex', () => which('codex') || executable('/Applications/ChatGPT.app/Contents/Resources/codex'));
 
 // Kimi Code renames a legacy Python `kimi` shim to `kimi-legacy` on install,
 // so when the Kimi Code store (~/.kimi-code) exists, `kimi` on PATH belongs
 // to Kimi Code and `kimi-legacy` is the old CLI. Without the store, `kimi` is
 // the legacy one. The two binaries cannot resume each other's sessions, so
 // neither ever doubles for the other.
-const kimiCodeInstalled = fs.existsSync(path.join(os.homedir(), '.kimi-code'));
-const kimiCodeBin = kimiCodeInstalled
+const kimiCodeInstalled = () => fs.existsSync(path.join(os.homedir(), '.kimi-code'));
+const kimiCodeBin = () => resolveBin('kimicode', () => (kimiCodeInstalled()
   ? which('kimi') || executable(path.join(os.homedir(), '.kimi-code', 'bin', 'kimi'))
-  : null;
-const kimiLegacyBin = which('kimi-legacy') || (kimiCodeInstalled ? null : which('kimi'));
+  : null));
+const kimiLegacyBin = () => resolveBin('kimi', () => which('kimi-legacy') || (kimiCodeInstalled() ? null : which('kimi')));
 
 // ---------- Claude Code session discovery ----------
 
@@ -850,6 +867,7 @@ function readMessages(sessionId, maxBytes = 512 * 1024, limit = 80) {
   // path.sep keeps the prefixes unambiguous: without it ~/.kimi would also
   // match every ~/.kimi-code path and routing would depend on check order.
   if (file.startsWith(CODEX_SESS_DIR + path.sep)) return readCodexMessages(file, maxBytes, limit);
+  if (file.startsWith(GROKBOT_DIR + path.sep)) return readGrokBotMessages(file, maxBytes, limit);
   if (file.startsWith(KIMICODE_DIR + path.sep)) return readKimiCodeMessages(file, maxBytes, limit);
   if (file.startsWith(KIMI_DIR + path.sep)) return readKimiLegacyMessages(file, maxBytes, limit);
   let raw;
@@ -1312,6 +1330,157 @@ function readKimiSessions() {
   return kimiCache.sessions;
 }
 
+// ---------- Grok Bot session discovery ----------
+// Grok Bot's agents run on a cloud VM, so unlike every other provider there is
+// nothing local to attach to: no process, no tty, no working directory, and no
+// way to send. What the desktop app does keep is a replica of what it has
+// synced, under ~/Library/Application Support/Grok Bot/sand-client-persistence,
+// one JSON blob per store key with the key base32 encoded into the filename.
+// Two keys matter:
+//   <account>.roster.last-roster        one row per Bot
+//   <account>.transcript.replicas.<id>  that Bot's conversation
+//
+// Read only, deliberately. The replica is the app's cache and not the source of
+// truth (that lives on the VM at /home/box/sand-data/agents/<id>/store.db), so
+// a message written in here is a message the app overwrites rather than sends.
+//
+// It also only advances while the desktop app is running. Bots keep working
+// with the app closed and the island cannot see it, so a Bot left mid turn is
+// the app having quit, not the Bot being stuck: busy expires on staleness the
+// same way the other journal-freshness providers do.
+
+const GROKBOT_DIR = path.join(os.homedir(), 'Library', 'Application Support', 'Grok Bot', 'sand-client-persistence');
+const GROKBOT_BUSY_STALE_MS = 5 * 60 * 1000;
+
+// RFC 4648 base32, lowercase and unpadded, which is how the app names blobs.
+// A name that is not one of ours decodes to junk and simply matches nothing,
+// so guessing wrong costs a string compare.
+const B32_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567';
+function b32decode(name) {
+  let bits = 0;
+  let value = 0;
+  const out = [];
+  for (const ch of name.toLowerCase()) {
+    if (ch === '=') break;
+    const i = B32_ALPHABET.indexOf(ch);
+    if (i < 0) return '';
+    value = (value << 5) | i;
+    bits += 5;
+    if (bits >= 8) { out.push((value >>> (bits - 8)) & 0xff); bits -= 8; }
+  }
+  return Buffer.from(out).toString('utf8');
+}
+
+// The names are long and never change, so decode each one once.
+const grokbotKeys = new Map(); // filename -> decoded store key
+const grokbotKeyOf = (name) => {
+  if (!grokbotKeys.has(name)) grokbotKeys.set(name, b32decode(name.replace(/\.blob$/, '')));
+  return grokbotKeys.get(name);
+};
+
+const grokbotEntriesOf = (file) => {
+  const entries = readJson(file)?.value?.entries;
+  return Array.isArray(entries) ? entries : [];
+};
+
+// Two entry kinds carry a turn: a typed one is {kind:'message', role, content}
+// and a Bot one is {kind:'send-message', message:{type,content}}. Everything
+// else in the stream (tool calls, approvals, status) has no place in a phone
+// transcript.
+function grokbotMessages(entries, limit = 80) {
+  const out = [];
+  for (const e of entries) {
+    let role = null;
+    let text = '';
+    if (e?.kind === 'message' && (e.role === 'user' || e.role === 'assistant')) {
+      role = e.role;
+      text = typeof e.content === 'string' ? e.content : '';
+    } else if (e?.kind === 'send-message' && e.message?.type === 'text') {
+      role = 'assistant';
+      text = typeof e.message.content === 'string' ? e.message.content : '';
+    }
+    text = text.trim();
+    if (!role || !text) continue;
+    out.push({ role, text: text.slice(0, 4000), ts: isoOf(e.timestampMs) });
+  }
+  return out.slice(-limit);
+}
+
+// One JSON object rather than a journal, so the tail slice every other provider
+// reads with would just be a syntax error. Whole file, with a ceiling that only
+// exists so a pathological blob cannot stall the daemon.
+function readGrokBotMessages(file, maxBytes = 512 * 1024, limit = 80) {
+  try { if (fs.statSync(file).size > 8 * 1024 * 1024) return []; } catch { return []; }
+  return grokbotMessages(grokbotEntriesOf(file), limit);
+}
+
+function scanGrokBotSessions() {
+  const sessions = [];
+  let files = [];
+  try { files = fs.readdirSync(GROKBOT_DIR); } catch { return sessions; }
+
+  let rosterFile = null;
+  const transcripts = new Map(); // botId -> blob path
+  for (const name of files) {
+    if (!name.endsWith('.blob')) continue;
+    const key = grokbotKeyOf(name);
+    if (key.endsWith('.roster.last-roster')) rosterFile = path.join(GROKBOT_DIR, name);
+    else {
+      const m = key.match(/\.transcript\.replicas\.([0-9a-f-]{36})$/);
+      if (m) transcripts.set(m[1], path.join(GROKBOT_DIR, name));
+    }
+  }
+  const rows = rosterFile ? readJson(rosterFile)?.value?.rows : null;
+  if (!Array.isArray(rows)) return sessions;
+
+  for (const row of rows) {
+    // A Bot is a standing teammate rather than a session that ends, so the
+    // roster is mirrored as it stands: what the Grok Bot sidebar lists, the
+    // island shows.
+    if (!row?.id || row.isHiddenFromSidebar) continue;
+    const file = transcripts.get(row.id) || null;
+    const scan = file
+      ? memoScan(`grokbot:${file}`, file, () => {
+        const entries = grokbotEntriesOf(file);
+        return { messages: grokbotMessages(entries, 1), streaming: entries.some((e) => e?.isStreaming === true) };
+      })
+      : { messages: [], streaming: false };
+    let updatedAt = row.lastActivityAt || row.updatedAt || 0;
+    if (file) { try { updatedAt = Math.max(updatedAt, fs.statSync(file).mtimeMs); } catch {} }
+    const busy = scan.streaming && Date.now() - updatedAt < GROKBOT_BUSY_STALE_MS;
+    if (file) transcriptCache.set(row.id, file);
+    sessions.push({
+      id: row.id,
+      provider: 'grokbot',
+      name: row.name || 'Bot',
+      // Its working directory is on a machine that is not this one, and
+      // claiming otherwise would put a path on the island you cannot open.
+      cwd: '',
+      project: 'Grok Bot',
+      // awaitingUserResponse is how the app marks a Bot stopped on you, which
+      // is the same pink invader as a held permission request.
+      status: row.awaitingUserResponse ? 'waiting' : (busy ? 'busy' : 'idle'),
+      updatedAt,
+      startedAt: row.createdAt || 0,
+      lastMessage: scan.messages.length ? scan.messages[scan.messages.length - 1] : null,
+      tty: '',
+      live: false,
+      // Nothing reads this yet. It is what a build that greys out the compose
+      // box will key on, instead of re-deriving read-only from the provider.
+      readOnly: true,
+    });
+  }
+  return sessions;
+}
+
+let grokbotCache = { at: 0, sessions: [] };
+function readGrokBotSessions() {
+  if (Date.now() - grokbotCache.at < 10_000) return grokbotCache.sessions;
+  grokbotCache.at = Date.now();
+  grokbotCache.sessions = scanGrokBotSessions();
+  return grokbotCache.sessions;
+}
+
 /// The phone-facing shape of a held request.
 const askPayload = (ask, queued) => ({
   id: ask.id,
@@ -1323,7 +1492,7 @@ const askPayload = (ask, queued) => ({
 });
 
 function readSessions() {
-  const sessions = [...readClaudeSessions(), ...readCodexSessions(), ...readKimiSessions()];
+  const sessions = [...readClaudeSessions(), ...readCodexSessions(), ...readKimiSessions(), ...readGrokBotSessions()];
   const known = new Set(sessions.map((s) => s.id));
   for (const s of sessions) {
     const queue = askQueue.get(s.id);
@@ -1758,7 +1927,14 @@ function watchTranscript(sessionId) {
   if (!file) return;
   let debounce;
   try {
-    const w = fs.watch(file, () => {
+    // Journals are appended to, so watching the file is enough. Grok Bot
+    // rewrites its replica blob wholesale, and a rename leaves a file watch
+    // bound to an inode nothing writes to again: watch the directory instead
+    // and filter, which survives the swap.
+    const inGrokBot = file.startsWith(GROKBOT_DIR + path.sep);
+    const target = inGrokBot ? GROKBOT_DIR : file;
+    const w = fs.watch(target, (_ev, changed) => {
+      if (inGrokBot && changed && changed !== path.basename(file)) return;
       clearTimeout(debounce);
       debounce = setTimeout(() => {
         ws?.send(seal({ type: 'transcript', sessionId, messages: readMessages(sessionId) }));
@@ -1828,6 +2004,15 @@ async function handleCommand(cmd) {
     const session = readSessions().find((s) => s.id === cmd.sessionId);
     if (!session) return ws?.send(seal({ type: 'promptResult', sessionId: cmd.sessionId, ok: false, error: 'session not found' }));
 
+    // A Bot lives on a cloud VM this daemon has no channel to. Saying so beats
+    // a send that looks accepted and arrives nowhere.
+    if (session.provider === 'grokbot') {
+      return ws?.send(seal({
+        type: 'promptResult', sessionId: cmd.sessionId, ok: false,
+        error: 'Grok Bot runs in the cloud, so Ground Control can only watch it. Open the Grok Bot app to reply.',
+      }));
+    }
+
     if (session.provider && session.provider !== 'claude') return promptHeadless(session, cmd.text);
 
     // Preferred path: type into the real terminal so the desktop updates live.
@@ -1849,7 +2034,8 @@ async function handleCommand(cmd) {
       }
     }
     if (session.status === 'busy') return ws?.send(seal({ type: 'promptResult', sessionId: cmd.sessionId, ok: false, error: 'session is busy, wait for it to go idle' }));
-    if (!claudeBin) {
+    const bin = claudeBin();
+    if (!bin) {
       console.log('[daemon] prompt failed: claude binary not found on PATH');
       return ws?.send(seal({
         type: 'promptResult', sessionId: cmd.sessionId, ok: false,
@@ -1859,7 +2045,7 @@ async function handleCommand(cmd) {
     console.log(`[daemon] prompt -> ${session.name}: ${cmd.text.slice(0, 60)}`);
     headlessActive.add(cmd.sessionId);
     sendSnapshot(true);
-    const child = spawn(claudeBin, ['--resume', cmd.sessionId, '-p', cmd.text], {
+    const child = spawn(bin, ['--resume', cmd.sessionId, '-p', cmd.text], {
       cwd: fs.existsSync(session.cwd || '') ? session.cwd : os.homedir(),
       env: process.env,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -1898,14 +2084,15 @@ async function handleCommand(cmd) {
 // dash there (the models do not care about leading whitespace).
 const defuse = (text) => (/^\s*-/.test(text) ? ` ${text}` : text);
 const headlessPromptSpec = {
-  codex: () => codexBin && { bin: codexBin, args: (id, text) => ['exec', 'resume', id, '--skip-git-repo-check', '--', text] },
-  kimicode: () => kimiCodeBin && { bin: kimiCodeBin, args: (id, text) => ['--session', id, '-p', defuse(text)] },
-  kimi: () => kimiLegacyBin && { bin: kimiLegacyBin, args: (id, text) => ['--print', '--session', id, '-p', defuse(text)] },
+  codex: () => { const bin = codexBin(); return bin && { bin, args: (id, text) => ['exec', 'resume', id, '--skip-git-repo-check', '--', text] }; },
+  kimicode: () => { const bin = kimiCodeBin(); return bin && { bin, args: (id, text) => ['--session', id, '-p', defuse(text)] }; },
+  kimi: () => { const bin = kimiLegacyBin(); return bin && { bin, args: (id, text) => ['--print', '--session', id, '-p', defuse(text)] }; },
 };
 
 function bustProviderCaches() {
   codexCache.at = 0;
   kimiCache.at = 0;
+  grokbotCache.at = 0;
 }
 
 function promptHeadless(session, text) {
@@ -1918,7 +2105,7 @@ function promptHeadless(session, text) {
     console.log(`[daemon] ${session.provider} prompt failed: binary not found`);
     return ws?.send(seal({
       type: 'promptResult', sessionId: session.id, ok: false,
-      error: `The daemon could not find the ${session.provider === 'codex' ? 'codex' : 'kimi'} command on this Mac, so it cannot reach this session.`,
+      error: `The daemon could not find the ${session.provider === 'codex' ? 'codex' : 'kimi'} command on this Mac, so it cannot reach this session. If you just installed it, try again in a minute.`,
     }));
   }
   console.log(`[daemon] prompt -> ${session.provider} ${session.name}: ${text.slice(0, 60)}`);
@@ -2060,6 +2247,7 @@ function watchProviderDir(dir, cache, label) {
     console.log(`[daemon] ${label}: watching ${dir}`);
   } catch {}
 }
-watchProviderDir(CODEX_SESS_DIR, codexCache, `codex sessions (codex binary: ${codexBin || 'not found, sessions will be read only'})`);
+watchProviderDir(CODEX_SESS_DIR, codexCache, `codex sessions (codex binary: ${codexBin() || 'not found yet, rechecked on each prompt'})`);
 watchProviderDir(path.join(KIMI_DIR, 'sessions'), kimiCache, 'kimi sessions');
 watchProviderDir(path.join(KIMICODE_DIR, 'sessions'), kimiCache, 'kimi code sessions');
+watchProviderDir(GROKBOT_DIR, grokbotCache, 'grok bot roster (read only, replies happen in the Grok Bot app)');

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@clastres/groundcontrol",
-  "version": "0.1.7",
-  "description": "See and command your Claude Code sessions from your iPhone. Pairs the Ground Control app with the agents running on this Mac, end to end encrypted.",
+  "version": "0.1.8",
+  "description": "See and command your coding agents from your iPhone. Pairs the Ground Control app with Claude Code, Codex, Kimi and Grok Bot sessions running on this Mac, end to end encrypted.",
   "bin": {
     "groundcontrol": "bin/groundcontrol.mjs"
   },
+  "scripts": {
+    "test": "node test/run.mjs"
+  },
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -16,6 +19,9 @@
   "keywords": [
     "claude",
     "claude-code",
+    "codex",
+    "kimi",
+    "grok",
     "ai",
     "agents",
     "cli",

package/test/binaries.mjs

@@ -0,0 +1,68 @@
+// Agent binaries are looked up on use, not at daemon startup.
+//
+// This is a regression test for a real failure: the daemon had been running
+// since Aug 4, Kimi Code was installed on Aug 12, and because the binary
+// consts were resolved once at boot the session showed up on the phone,
+// streamed its transcript, and refused every prompt with "binary not found"
+// for eight days. Session discovery rescans the disk constantly; binary
+// lookup did not.
+//
+// The resolver block is extracted from daemon.mjs rather than copied, with an
+// injected clock so the one minute memo can be stepped over instantly.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAEMON = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'daemon.mjs');
+const src = fs.readFileSync(DAEMON, 'utf8');
+const start = src.indexOf('// Every agent binary is resolved on use');
+const end = src.indexOf('// ---------- Claude Code session discovery ----------');
+if (start < 0 || end < 0 || end < start) throw new Error('could not locate the binary resolver block in daemon.mjs');
+const block = src.slice(start, end);
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gc-bin-'));
+const home = path.join(tmp, 'home');
+fs.mkdirSync(path.join(home, '.kimi-code', 'bin'), { recursive: true });
+const kimiPath = path.join(home, '.kimi-code', 'bin', 'kimi');
+
+let now = 1_000_000;
+const clock = { now: () => now };
+const fakeOs = { ...os, homedir: () => home };
+const executable = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return p; } catch { return null; } };
+const which = () => null;           // nothing on PATH, which is the real case here
+const quiet = { log: () => {} };    // swallow the startup banner
+
+const load = () => new Function('fs', 'os', 'path', 'Date', 'which', 'executable', 'console',
+  `${block}\n return { kimiCodeBin, claudeBin, codexBin, resolveBin };`)(
+  fs, fakeOs, path, clock, which, executable, quiet);
+
+const { kimiCodeBin } = load();
+
+let failures = 0;
+const check = (label, cond) => { console.log(`${cond ? 'ok  ' : 'FAIL'} ${label}`); if (!cond) failures++; };
+
+// Boot: ~/.kimi-code exists but the binary is not installed yet.
+check('not installed yet reads as missing', kimiCodeBin() === null);
+
+// Kimi Code installs while the daemon keeps running. This is the exact case
+// that left a session readable but unanswerable.
+fs.writeFileSync(kimiPath, '#!/bin/sh\n');
+fs.chmodSync(kimiPath, 0o755);
+
+check('still cached inside the memo window', kimiCodeBin() === null);
+now += 61_000;
+check('picked up a minute after install', kimiCodeBin() === kimiPath);
+
+// And the reverse: an uninstall is noticed rather than cached forever.
+fs.rmSync(kimiPath);
+now += 61_000;
+check('uninstall clears back to missing', kimiCodeBin() === null);
+
+// A lookup that throws must not take a prompt down with it.
+const { resolveBin } = load();
+check('a throwing lookup returns null', resolveBin('boom', () => { throw new Error('nope'); }) === null);
+
+fs.rmSync(tmp, { recursive: true, force: true });
+console.log(failures ? `\n${failures} FAILURE(S)` : '\nall checks passed');
+process.exit(failures ? 1 : 0);

package/test/grokbot.mjs

@@ -0,0 +1,86 @@
+// Runs the real Grok Bot reader out of daemon.mjs against whatever replica this
+// Mac has. The block is extracted from source rather than copied, so the test
+// cannot drift from what the daemon ships.
+//
+// The daemon is one long script that connects to the relay on import, so there
+// is nothing to import: pulling the section out by its comment markers and
+// evaluating it with its handful of helpers injected is what keeps this honest.
+//
+// On a Mac without Grok Bot installed the roster assertions are skipped and the
+// machine independent ones still run.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAEMON = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'daemon.mjs');
+const src = fs.readFileSync(DAEMON, 'utf8');
+const start = src.indexOf('// ---------- Grok Bot session discovery ----------');
+const end = src.indexOf('/// The phone-facing shape of a held request.');
+if (start < 0 || end < 0 || end < start) throw new Error('could not locate the Grok Bot block in daemon.mjs');
+const block = src.slice(start, end);
+
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
+const isoOf = (t) => { try { return t ? new Date(t).toISOString() : null; } catch { return null; } };
+const memoScan = (_key, _file, fn) => fn();
+const transcriptCache = new Map();
+
+const load = (source, cache) => new Function('fs', 'os', 'path', 'readJson', 'isoOf', 'memoScan', 'transcriptCache',
+  `${source}\n return { readGrokBotSessions, readGrokBotMessages, b32decode, GROKBOT_DIR };`)(
+  fs, os, path, readJson, isoOf, memoScan, cache);
+
+const { readGrokBotSessions, readGrokBotMessages, b32decode, GROKBOT_DIR } = load(block, transcriptCache);
+
+let failures = 0;
+const check = (label, cond, detail = '') => {
+  console.log(`${cond ? 'ok  ' : 'FAIL'} ${label}${detail ? `  ${detail}` : ''}`);
+  if (!cond) failures++;
+};
+
+// A store key the app really writes, so a change to the encoding is caught here
+// rather than by an empty island.
+const known = 'onqw4zbomnwgszlooqxhg3djmnss4y3mnfsw45bnnvsxiyjomfrwg33vnz2c243mn52a';
+check('b32decode reads a real store key', b32decode(known) === 'sand.client.slice.client-meta.account-slot', b32decode(known));
+check('b32decode rejects junk', b32decode('!!!!') === '');
+
+// A Mac without Grok Bot must return an empty list rather than throw.
+check('missing install returns empty, does not throw',
+  load(block.replace(/const GROKBOT_DIR = .*/, "const GROKBOT_DIR = '/nope/not/here';"), new Map())
+    .readGrokBotSessions().length === 0);
+
+const sessions = fs.existsSync(GROKBOT_DIR) ? readGrokBotSessions() : [];
+if (!sessions.length) {
+  console.log(`\nskipped the roster checks: no Bots found in ${GROKBOT_DIR}`);
+  console.log(failures ? `\n${failures} FAILURE(S)` : '\nall checks passed');
+  process.exit(failures ? 1 : 0);
+}
+
+console.log(`\n${sessions.length} bot(s) found\n`);
+for (const s of sessions) {
+  check(`${s.name}: id is a uuid`, /^[0-9a-f-]{36}$/.test(s.id));
+  check(`${s.name}: status is one the app understands`, ['idle', 'busy', 'waiting'].includes(s.status));
+  check(`${s.name}: has a name`, !!s.name);
+  check(`${s.name}: startedAt set`, s.startedAt > 0);
+  check(`${s.name}: updatedAt set`, s.updatedAt > 0);
+  check(`${s.name}: read only flagged`, s.readOnly === true);
+  // Every field the Swift Session struct decodes as non-optional must be here,
+  // or the phone drops the whole snapshot, not just this row.
+  for (const k of ['id', 'name', 'cwd', 'project', 'status', 'updatedAt', 'startedAt']) {
+    check(`${s.name}: ${k} present for Swift decode`, s[k] !== undefined && s[k] !== null);
+  }
+
+  const file = transcriptCache.get(s.id);
+  check(`${s.name}: transcript located`, !!file);
+  if (!file) continue;
+  const msgs = readGrokBotMessages(file);
+  check(`${s.name}: transcript has messages`, msgs.length > 0);
+  check(`${s.name}: roles are user/assistant only`, msgs.every((m) => m.role === 'user' || m.role === 'assistant'));
+  check(`${s.name}: every message has a timestamp`, msgs.every((m) => !!m.ts));
+  check(`${s.name}: lastMessage matches transcript tail`, s.lastMessage?.text === msgs[msgs.length - 1]?.text);
+  // The app stores a ProseMirror doc beside every typed turn. Leaking it into
+  // the transcript would put raw JSON on the phone.
+  check(`${s.name}: no raw richText leaked into text`, msgs.every((m) => !m.text.includes('"type":"doc"')));
+}
+
+console.log(failures ? `\n${failures} FAILURE(S)` : '\nall checks passed');
+process.exit(failures ? 1 : 0);

package/test/run.mjs

@@ -0,0 +1,23 @@
+// Every test in this directory, in one run. Plain node, no framework, matching
+// the rest of the CLI: the daemon ships with two runtime dependencies and a
+// test runner is not going to be the third.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const dir = path.dirname(fileURLToPath(import.meta.url));
+const files = fs.readdirSync(dir).filter((f) => f.endsWith('.mjs') && f !== 'run.mjs').sort();
+
+let failed = 0;
+for (const f of files) {
+  console.log(`\n=== ${f} ===`);
+  try {
+    execFileSync(process.execPath, [path.join(dir, f)], { stdio: 'inherit' });
+  } catch {
+    failed++;
+  }
+}
+
+console.log(failed ? `\n${failed} of ${files.length} test file(s) failed` : `\n${files.length} test file(s) passed`);
+process.exit(failed ? 1 : 0);