@bongos/core 1.17.0

package/scripts/gds/read-session-export.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+// read-session-export.js — READ a Claude Code `/export` zip, fast.
+//
+// Claude Code's built-in `/export` already produces the zip. This does NOT make
+// another one — it READS the existing one: it cracks the zip, finds the single
+// transcript file (the format is identical every time), and prints a compact,
+// skimmable conversation — your prompts, Claude's THINKING ("the thoughts"),
+// its replies, and one-line tool calls — straight to stdout for the session to
+// read. The ~30 `logs/*.log` debug files (tens of MB) are ignored.
+//
+// The point is reading effectively and swiftly, so the output is trimmed for
+// comprehension, not archived to a file. Thoughts and replies print in full;
+// tool results are clipped (use --full to loosen).
+//
+// Zero dependencies: a tiny ZIP reader on the Node `zlib` stdlib.
+//
+// Usage:
+//   node scripts/gds/read-session-export.js <export.zip>     # read it
+//   node scripts/gds/read-session-export.js --latest         # newest in ~/Downloads
+//   node scripts/gds/read-session-export.js <zip> --thoughts # just the thinking
+//   node scripts/gds/read-session-export.js <zip> --meta     # header summary only
+//   node scripts/gds/read-session-export.js <zip> --full     # don't clip tool results
+//
+// Exit codes: 0 ok · 1 runtime/IO error · 2 bad invocation
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const zlib = require('node:zlib');
+
+// ───────────────────────── minimal ZIP reader (stdlib only) ─────────────────
+// Random-access via fd: find the end-of-central-directory in the tail, read the
+// central directory for entry sizes/offsets (so we're safe against data-
+// descriptor entries), then inflate only the few entries we actually read —
+// never the giant logs/*.log.
+
+const SIG_EOCD = 0x06054b50;
+const SIG_CEN = 0x02014b50;
+const SIG_LOC = 0x04034b50;
+
+function readFull(fd, buf, position) {
+  let off = 0;
+  while (off < buf.length) {
+    const n = fs.readSync(fd, buf, off, buf.length - off, position + off);
+    if (n === 0) break;
+    off += n;
+  }
+  return off;
+}
+
+function openZip(filePath) {
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const tailLen = Math.min(size, 65557); // max EOCD comment (65535) + 22
+    const tail = Buffer.alloc(tailLen);
+    readFull(fd, tail, size - tailLen);
+    let eocd = -1;
+    for (let i = tail.length - 22; i >= 0; i--) {
+      if (tail.readUInt32LE(i) === SIG_EOCD) { eocd = i; break; }
+    }
+    if (eocd < 0) throw new Error('not a zip archive (no end-of-central-directory record)');
+    const cdEntries = tail.readUInt16LE(eocd + 10);
+    const cdSize = tail.readUInt32LE(eocd + 12);
+    const cdOffset = tail.readUInt32LE(eocd + 16);
+    if (cdOffset === 0xffffffff || cdSize === 0xffffffff || cdEntries === 0xffff) {
+      throw new Error('ZIP64 archives are not supported');
+    }
+    const cd = Buffer.alloc(cdSize);
+    readFull(fd, cd, cdOffset);
+    const entries = [];
+    let p = 0;
+    for (let n = 0; n < cdEntries && p + 46 <= cd.length; n++) {
+      if (cd.readUInt32LE(p) !== SIG_CEN) break;
+      const method = cd.readUInt16LE(p + 10);
+      const nameLen = cd.readUInt16LE(p + 28);
+      const extraLen = cd.readUInt16LE(p + 30);
+      const commentLen = cd.readUInt16LE(p + 32);
+      const localOffset = cd.readUInt32LE(p + 42);
+      const compSize = cd.readUInt32LE(p + 20);
+      const name = cd.toString('utf8', p + 46, p + 46 + nameLen);
+      entries.push({ name, method, compSize, localOffset });
+      p += 46 + nameLen + extraLen + commentLen;
+    }
+    return { fd, entries };
+  } catch (err) {
+    fs.closeSync(fd);
+    throw err;
+  }
+}
+
+function readEntry(fd, entry) {
+  const lh = Buffer.alloc(30);
+  readFull(fd, lh, entry.localOffset);
+  if (lh.readUInt32LE(0) !== SIG_LOC) throw new Error(`bad local header for ${entry.name}`);
+  const nameLen = lh.readUInt16LE(26);
+  const extraLen = lh.readUInt16LE(28);
+  const dataOffset = entry.localOffset + 30 + nameLen + extraLen;
+  const comp = Buffer.alloc(entry.compSize);
+  readFull(fd, comp, dataOffset);
+  if (entry.method === 0) return comp;
+  if (entry.method === 8) return zlib.inflateRawSync(comp);
+  throw new Error(`unsupported compression method ${entry.method}`);
+}
+
+// ───────────────────────── the constant export layout ──────────────────────
+// A `/export` zip is the same shape every time:
+//   metadata.json                       — model, effort, title, cwd, dates
+//   <cliSessionId>.jsonl                — THE transcript (one JSON record/line)
+//   <cliSessionId>/subagents/agent-*.jsonl(+.meta.json)  — subagent transcripts
+//   <cliSessionId>/tool-results/*.txt   — tool outputs too big to inline
+//   logs/*.log                          — app debug logs (ignored)
+
+function loadExport(zipPath) {
+  const { fd, entries } = openZip(zipPath);
+  try {
+    const byName = new Map(entries.map((e) => [e.name, e]));
+    const readText = (e) => readEntry(fd, e).toString('utf8');
+
+    let metadata = {};
+    if (byName.has('metadata.json')) {
+      try { metadata = JSON.parse(readText(byName.get('metadata.json'))); } catch { /* tolerate */ }
+    }
+
+    const topJsonl = entries.filter((e) => e.name.endsWith('.jsonl') && !e.name.includes('/'));
+    const mainEntry = (metadata.cliSessionId && byName.get(`${metadata.cliSessionId}.jsonl`)) || topJsonl[0];
+    if (!mainEntry) throw new Error('no transcript (.jsonl) found in this zip');
+    const records = parseJsonl(readText(mainEntry));
+
+    const subagents = [];
+    for (const e of entries) {
+      if (/\/subagents\/agent-[^/]+\.jsonl$/.test(e.name)) {
+        const metaName = e.name.replace(/\.jsonl$/, '.meta.json');
+        let meta = {};
+        if (byName.has(metaName)) { try { meta = JSON.parse(readText(byName.get(metaName))); } catch { /* tolerate */ } }
+        subagents.push({ meta, records: parseJsonl(readText(e)) });
+      }
+    }
+    const logCount = entries.filter((e) => e.name.startsWith('logs/')).length;
+    return { metadata, records, subagents, logCount };
+  } finally {
+    fs.closeSync(fd); // the reader holds nothing open — everything is in memory now
+  }
+}
+
+function parseJsonl(text) {
+  const out = [];
+  for (const line of text.split('\n')) {
+    const s = line.trim();
+    if (!s) continue;
+    try { out.push(JSON.parse(s)); } catch { /* skip a malformed line */ }
+  }
+  return out;
+}
+
+// ──────────────────────── transcript reduction ─────────────────────────────
+// Reduce raw records to readable turns: user prompts, and assistant turns whose
+// blocks are thinking / text / tool (with the tool's result attached by id).
+// Tool-result-carrier user records are folded into their tool call, not shown
+// as turns. system/queue/last-prompt records are dropped (noise).
+
+function reduce(records) {
+  const toolResults = new Map();
+  for (const r of records) {
+    const c = r.type === 'user' && r.message && r.message.content;
+    if (Array.isArray(c)) {
+      for (const b of c) {
+        if (b && b.type === 'tool_result') toolResults.set(b.tool_use_id, { text: flatten(b.content), isError: !!b.is_error });
+      }
+    }
+  }
+
+  const turns = [];
+  let visible = 0, redacted = 0, tools = 0, prompts = 0;
+  for (const r of records) {
+    if (r.type === 'user') {
+      const c = r.message && r.message.content;
+      if (Array.isArray(c) && c.some((b) => b && b.type === 'tool_result')) continue; // carrier
+      prompts++;
+      turns.push({ role: 'user', text: typeof c === 'string' ? c : flatten(c) });
+    } else if (r.type === 'attachment') {
+      const a = r.attachment || {};
+      turns.push({ role: 'attachment', label: a.fileName || a.name || a.path || a.type || 'attachment' });
+    } else if (r.type === 'assistant') {
+      const blocks = [];
+      for (const b of (r.message && r.message.content) || []) {
+        if (!b || typeof b !== 'object') continue;
+        if (b.type === 'thinking') {
+          if ((b.thinking || '').trim()) { visible++; blocks.push({ k: 'think', text: b.thinking.trim() }); }
+          else { redacted++; blocks.push({ k: 'think_redacted' }); }
+        } else if (b.type === 'redacted_thinking') {
+          redacted++; blocks.push({ k: 'think_redacted' });
+        } else if (b.type === 'text') {
+          if ((b.text || '').trim()) blocks.push({ k: 'text', text: b.text.trim() });
+        } else if (b.type === 'tool_use') {
+          tools++;
+          const res = toolResults.get(b.id);
+          blocks.push({ k: 'tool', name: b.name, input: b.input, result: res ? res.text : null, isError: res ? res.isError : false });
+        }
+      }
+      // Merge into the previous assistant turn — Claude Code streams each block
+      // (think / text / tool) as its own record, so one reply spans several.
+      const last = turns[turns.length - 1];
+      if (last && last.role === 'assistant') last.blocks.push(...blocks);
+      else turns.push({ role: 'assistant', blocks });
+    }
+  }
+  return { turns, stats: { prompts, visible, redacted, tools } };
+}
+
+function flatten(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map((b) => (typeof b === 'string' ? b : (b && b.text) || '')).join('\n');
+  return content == null ? '' : String(content);
+}
+
+// ──────────────────────────── compact rendering ────────────────────────────
+
+function clip(s, max) {
+  s = (s == null ? '' : String(s)).replace(/\s+$/, '');
+  if (s.length <= max) return s;
+  return `${s.slice(0, max).replace(/\s+\S*$/, '')} … (+${s.length - max} chars)`;
+}
+
+function oneLineInput(name, input) {
+  if (input == null) return '';
+  if (name === 'Bash' && input.command) return '`' + clip(input.command.replace(/\n/g, ' '), 140) + '`';
+  if (input.file_path) return input.file_path;
+  if (input.path) return input.path;
+  if (input.pattern) return `/${input.pattern}/`;
+  if (input.query) return clip(String(input.query), 100);
+  if (input.description) return input.description;
+  const keys = Object.keys(input);
+  return keys.length ? clip(keys.map((k) => `${k}=${JSON.stringify(input[k])}`).join(' '), 120) : '';
+}
+
+function isoOr(ms) {
+  if (!ms && ms !== 0) return '?';
+  try { return new Date(ms).toISOString().slice(0, 16).replace('T', ' '); } catch { return '?'; }
+}
+
+function renderTurns(turns, opts, out, prefix = '') {
+  const resultCap = opts.full ? 4000 : 200;
+  for (const turn of turns) {
+    if (opts.thoughtsOnly && turn.role !== 'assistant') continue;
+
+    if (turn.role === 'user') {
+      out.push(`\n${prefix}## 👤 You`);
+      out.push(`${prefix}${clip(turn.text, 4000) || '_(empty)_'}`);
+    } else if (turn.role === 'attachment') {
+      if (!opts.thoughtsOnly) out.push(`${prefix}📎 _attachment: ${turn.label}_`);
+    } else if (turn.role === 'assistant') {
+      // Redacted thinking adds no readable signal per-block — the header already
+      // reports the count + an all-redacted banner — so it's dropped from the
+      // body to keep the read clean. The reasoning you CAN see is the text + the
+      // tool sequence, which is exactly what we surface.
+      const blocks = (opts.thoughtsOnly
+        ? turn.blocks.filter((b) => b.k === 'think')
+        : turn.blocks).filter((b) => b.k !== 'think_redacted');
+      if (!blocks.length) continue;
+      out.push(`\n${prefix}## 🤖 Claude`);
+      for (const b of blocks) {
+        if (b.k === 'think') { out.push(`\n${prefix}💭 **Thinking**`); out.push(`${prefix}${b.text.replace(/\n/g, `\n${prefix}`)}`); }
+        else if (b.k === 'text') { out.push(`\n${prefix}${b.text.replace(/\n/g, `\n${prefix}`)}`); }
+        else if (b.k === 'tool') {
+          const inp = oneLineInput(b.name, b.input);
+          out.push(`${prefix}🔧 \`${b.name}\`${inp ? ` ${inp}` : ''}${b.isError ? '  ⚠️' : ''}`);
+          if (b.result != null && !opts.thoughtsOnly) {
+            const r = clip(b.result.replace(/^\s+/, ''), resultCap).replace(/\n/g, `\n${prefix}   `);
+            if (r) out.push(`${prefix}   ↳ ${r}`);
+          }
+        }
+      }
+    }
+  }
+}
+
+function render(data, opts) {
+  const m = data.metadata || {};
+  const { turns, stats } = reduce(data.records);
+  const out = [];
+
+  out.push(`# 📄 ${m.title || 'Session'}`);
+  out.push(`${m.model || '?'}${m.effort ? ` · ${m.effort}` : ''} · ${isoOr(m.createdAt)} → ${isoOr(m.lastActivityAt)}`);
+  if (m.cwd) out.push(`cwd: \`${m.cwd}\`${m.branch ? ` · branch \`${m.branch}\`` : ''}`);
+  out.push(`${stats.prompts} prompts · 💭 ${stats.visible} thoughts${stats.redacted ? ` (+${stats.redacted} redacted)` : ''} · 🔧 ${stats.tools} tool calls · ${data.subagents.length} subagents · ${data.logCount} app-logs ignored`);
+  if (stats.visible === 0 && stats.redacted > 0) {
+    out.push(`\n> ⚠️ All thinking in this session is **redacted** — this was an Opus session, and Opus exports carry only encrypted reasoning, not the plaintext thoughts. (Sonnet sessions export readable thinking.)`);
+  }
+
+  if (opts.meta) { process.stdout.write(out.join('\n') + '\n'); return; }
+
+  renderTurns(turns, opts, out);
+
+  for (const sa of data.subagents) {
+    out.push(`\n---\n\n# ⤷ Subagent: ${sa.meta.agentType || 'agent'}${sa.meta.description ? ` — ${sa.meta.description}` : ''}`);
+    const sub = reduce(sa.records);
+    renderTurns(sub.turns, opts, out, '> ');
+  }
+
+  process.stdout.write(out.join('\n') + '\n');
+}
+
+// ───────────────────────────────── CLI ─────────────────────────────────────
+
+function findLatest(dir) {
+  const d = dir || path.join(os.homedir(), 'Downloads');
+  let files;
+  try { files = fs.readdirSync(d); } catch { throw { code: 1, msg: `cannot read directory: ${d}` }; }
+  const cands = files.filter((f) => /^session-export-.*\.zip$/i.test(f))
+    .map((f) => ({ p: path.join(d, f), m: fs.statSync(path.join(d, f)).mtimeMs }))
+    .sort((a, b) => b.m - a.m);
+  if (!cands.length) throw { code: 1, msg: `no session-export-*.zip in ${d}` };
+  return cands[0].p;
+}
+
+const HELP = `read-session-export — read a Claude Code /export zip, fast (the format is the same every time)
+
+  node scripts/gds/read-session-export.js <export.zip>   read it (compact transcript → stdout)
+  node scripts/gds/read-session-export.js --latest       newest session-export-*.zip in ~/Downloads
+  --thoughts   only the thinking blocks (fast reasoning skim)
+  --meta       header summary only (model, dates, counts)
+  --full       don't clip tool results
+  --latest [dir]   pick the newest export in dir (default ~/Downloads)`;
+
+function main() {
+  const argv = process.argv.slice(2);
+  const opts = { zip: null, thoughtsOnly: false, meta: false, full: false, latest: false, latestDir: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') { console.log(HELP); return; }
+    else if (a === '--thoughts') opts.thoughtsOnly = true;
+    else if (a === '--meta') opts.meta = true;
+    else if (a === '--full') opts.full = true;
+    else if (a === '--latest') { opts.latest = true; if (argv[i + 1] && !argv[i + 1].startsWith('-')) opts.latestDir = argv[++i]; }
+    else if (a.startsWith('-')) { console.error(`✖ unknown option: ${a}\n\n${HELP}`); process.exit(2); }
+    else opts.zip = a;
+  }
+
+  let zipPath = opts.zip;
+  try { if (opts.latest) zipPath = findLatest(opts.latestDir); }
+  catch (e) { console.error(`✖ ${e.msg || e.message}`); process.exit(e.code || 1); }
+  if (!zipPath) { console.error(`✖ no zip given. Pass a path, or use --latest.\n\n${HELP}`); process.exit(2); }
+  zipPath = path.resolve(zipPath);
+  if (!fs.existsSync(zipPath)) { console.error(`✖ file not found: ${zipPath}`); process.exit(1); }
+
+  try {
+    render(loadExport(zipPath), opts);
+  } catch (e) {
+    console.error(`✖ ${e.message}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = { loadExport, reduce, render, openZip, readEntry };

package/scripts/gds/reauth.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// scripts/gds/reauth.js — #504.
+//
+// The fast, UI-first path to refresh an expired/invalid GDS CLI session.
+//
+// Why this exists: CLI bearer tokens carry a 24h idle TTL (refresh-on-use) for
+// auth-token hygiene (GDS-V3 criterion C9) — a leaked or abandoned token in the
+// plaintext session file dies on its own instead of living forever. That's a
+// keeper. The friction it caused (re-auth via the slow Device Flow, terminal
+// codes, Gemini-key prompts) is NOT a keeper. This script is the fix:
+//
+//   1. Detect — is the current session still valid? (GET /api/gds/me)
+//        valid   → print who you are + exit 0. Nothing to do.
+//        invalid → exit 10 ("re-auth needed") after opening the browser.
+//   2. Guide — open the builder's Settings page in the default browser (where
+//      the builder is already signed in via the httpOnly cookie) and print the
+//      exact click-path: Settings → CLI Access → Re-issue CLI token → Copy.
+//      The page hands back a one-liner: `node scripts/gds/paste-token.js
+//      <token>`. The builder pastes that one line back into Claude; the
+//      /builder-reauth skill runs it (paste-token.js verifies + writes safely).
+//
+// This script never touches the session file itself — paste-token.js owns the
+// write (and its verify-before-write safety contract). reauth.js is detect +
+// open + instruct only, so a failed re-auth can never corrupt a good session.
+//
+// Honors Lars's UI-first rule as far as guided-paste allows: browser clicks +
+// a single copy/paste, no Device-Flow code entry. (A true zero-paste loopback
+// flow is a deferred follow-up.)
+//
+// Usage:
+//   node scripts/gds/reauth.js            # detect; if invalid, open Settings + guide
+//   node scripts/gds/reauth.js --no-open  # detect + guide, but don't open browser
+//
+// Exit codes:
+//   0  — session is valid (no re-auth needed)
+//   10 — re-auth needed (browser opened, instructions printed)
+//   2  — could not reach the API to check (network); guidance still printed
+
+const { spawn } = require('node:child_process');
+const lib = require('./cli-lib');
+
+const HALL_URL = `${lib.API_BASE}/builders`;
+// The "Re-issue CLI token" button lives on the Settings page (under "CLI
+// Access"), not the hall profile — open the builder right where the button is.
+const SETTINGS_URL = `${lib.API_BASE}/builders/settings`;
+
+function openInBrowser(url) {
+  // Best-effort. We never fail the run if the browser can't be launched — the
+  // builder can always open the URL by hand (we print it either way).
+  let cmd, args;
+  switch (process.platform) {
+    case 'darwin':
+      cmd = 'open';
+      args = [url];
+      break;
+    case 'win32':
+      // rundll32's FileProtocolHandler opens a URL without going through a
+      // shell, so (unlike `cmd /c start`) shell metacharacters in the URL are
+      // never interpreted. Defense-in-depth: today the URL is a constant
+      // (GDS_API_BASE + '/builders'), but this keeps it safe if that ever
+      // becomes influenced by less-trusted input.
+      cmd = 'rundll32';
+      args = ['url.dll,FileProtocolHandler', url];
+      break;
+    default:
+      cmd = 'xdg-open';
+      args = [url];
+      break;
+  }
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {}); // swallow ENOENT etc.
+    child.unref();
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function printGuidance({ opened }) {
+  console.log('');
+  console.log('Refresh your GDS CLI session (UI-first — no Device Flow):');
+  console.log('');
+  // We can't reliably know if the browser actually launched — spawn() reports
+  // a missing-binary error asynchronously, after this prints. So we never claim
+  // success; we say we tried, and always show the URL so no one is stranded.
+  console.log(`  1. ${opened ? 'Opening (or open)' : 'Open'} your Settings page:`);
+  console.log(`       ${SETTINGS_URL}`);
+  console.log("       (if it didn't open, paste that URL into your browser —");
+  console.log("        you're already signed in there via your browser cookie)");
+  console.log('  2. Under the "CLI Access" section, click "Re-issue CLI token".');
+  console.log('  3. Click "Copy" — it copies a one-line command that looks like:');
+  console.log('       node scripts/gds/paste-token.js <token>');
+  console.log('  4. Paste that one line back to Claude. It will run it for you,');
+  console.log('     verify the token, and write your new session.');
+  console.log('');
+  console.log('  If the page says you are not signed in, sign in at the builders\'');
+  console.log(`  hall first (${HALL_URL}), then return to Settings and click Re-issue.`);
+  console.log('  Fallback (terminal Device Flow): node scripts/gds/setup.js --force');
+  console.log('');
+}
+
+async function main() {
+  const noOpen = process.argv.includes('--no-open');
+
+  const session = await lib.loadSession();
+  if (!session || !session.token) {
+    console.log('No GDS CLI session found on this machine.');
+    const opened = noOpen ? false : openInBrowser(SETTINGS_URL);
+    printGuidance({ opened });
+    process.exit(10);
+  }
+
+  // Detect: is the existing token still valid? /me is the canonical check
+  // (same endpoint paste-token.js and doctor.js use). allowUnauthenticated so
+  // a 401 returns here instead of triggering cli-lib's exit-with-guidance.
+  let res;
+  try {
+    const api = await lib.cliClient({ allowUnauthenticated: true });
+    res = await api.me.getMe();
+  } catch (err) {
+    console.error(`Could not reach ${lib.API_BASE} to check your session: ${err.message}`);
+    const opened = noOpen ? false : openInBrowser(SETTINGS_URL);
+    printGuidance({ opened });
+    process.exit(2);
+  }
+
+  if (res.ok) {
+    const b = (res.data && res.data.builder) || {};
+    console.log(`Your GDS CLI session is valid — no re-auth needed.`);
+    console.log(`  Signed in as ${b.github_login || '?'}${b.rank ? ` (rank: ${b.rank})` : ''}.`);
+    console.log('  (Sessions carry a 24h idle TTL and refresh on every use, so an');
+    console.log('   actively-used session stays alive.)');
+    process.exit(0);
+  }
+
+  // 401 / 403 / anything not-ok → treat as "needs re-auth".
+  console.log('Your GDS CLI session is no longer valid (expired or revoked).');
+  const opened = noOpen ? false : openInBrowser(SETTINGS_URL);
+  printGuidance({ opened });
+  process.exit(10);
+}
+
+main().catch((err) => {
+  console.error('reauth failed:', err && err.message ? err.message : err);
+  // Still print the manual path so the builder isn't stranded.
+  printGuidance({ opened: false });
+  process.exit(2);
+});

package/scripts/gds/recall.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// scripts/gds/recall.js — one-call project-knowledge search (task 955, V4.R17 /
+// ADR 0060). Wraps POST /api/gds/search: lexical (FTS + pg_trgm) fused with RRF,
+// rank/owner-scoped server-side (a sub-Metic caller never sees protected docs;
+// you only ever see your own private chunks). Authenticated — reads the builder
+// session like every other /builder-* CLI.
+//
+// Progressive disclosure (ADR 0095 C1 / task 1658): a plain `recall <query>`
+// returns the COMPACT summary layer — each hit shows a snippet plus its token
+// cost (what you see now vs. what a full expansion would cost), so you see the
+// price before paying it. `recall --expand <id>` then fetches one hit's full
+// content. Step 1 surfaces what's relevant + cheap; step 2 spends tokens only on
+// the hit you actually want.
+//
+// Usage:
+//   node scripts/gds/recall.js <query…>            # step 1: ranked summary + per-hit token cost
+//   node scripts/gds/recall.js "trust boundary" --limit 5
+//   node scripts/gds/recall.js grader bypass --kind doc
+//   node scripts/gds/recall.js --expand 1234       # step 2: full content of hit #1234
+//   node scripts/gds/recall.js <query…> --json     # raw JSON (for scripts)
+
+const { cliClient } = require('./cli-lib');
+
+function parseArgs(argv) {
+  const out = { terms: [], limit: undefined, kind: undefined, json: false, expand: undefined };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--limit') out.limit = Number(argv[++i]);
+    else if (a === '--kind') out.kind = argv[++i];
+    else if (a === '--expand') out.expand = Number(argv[++i]);
+    else if (a.startsWith('--limit=')) out.limit = Number(a.slice(8));
+    else if (a.startsWith('--kind=')) out.kind = a.slice(7);
+    else if (a.startsWith('--expand=')) out.expand = Number(a.slice(9));
+    else out.terms.push(a);
+  }
+  out.q = out.terms.join(' ').trim();
+  return out;
+}
+
+function truncate(s, n) {
+  const t = String(s || '').replace(/\s+/g, ' ').trim();
+  return t.length > n ? t.slice(0, n - 1) + '…' : t;
+}
+
+function reportError(r) {
+  if (r.status === 401) {
+    console.error('Not signed in. Run /builder-setup (or `node scripts/gds/setup.js`) first — recall searches as you, so it can scope results to your rank.');
+  } else if (r.status === 429) {
+    console.error(`Rate limited (${r.data && r.data.retry_after_seconds ? r.data.retry_after_seconds + 's' : 'slow down'}). Recall is capped per builder per minute.`);
+  } else {
+    console.error(`recall failed (${r.status}):`, r.data);
+  }
+}
+
+// Step 2 — fetch + print one hit's full content (the EXPAND half).
+async function runExpand(args) {
+  const api = await cliClient();
+  const r = await api.search.postSearch({ body: { expand: args.expand } });
+  if (!r.ok) {
+    if (r.status === 404) {
+      console.error(`No chunk #${args.expand} visible to you. Re-run the search to get a current id (ids are stable but a chunk may be above your rank).`);
+    } else {
+      reportError(r);
+    }
+    process.exit(1);
+  }
+  if (args.json) { console.log(JSON.stringify(r.data, null, 2)); return; }
+  const c = r.data.chunk;
+  console.log(`${c.title || c.source_ref}`);
+  console.log(`${c.heading_path || c.source_ref}`);
+  console.log(`${c.source_ref}  ·  ~${c.body_tokens} tokens\n`);
+  console.log(c.body);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  // Step 2: --expand <id> bypasses the search and pulls one hit's full content.
+  if (Number.isFinite(args.expand)) {
+    return runExpand(args);
+  }
+
+  if (!args.q) {
+    console.error('Usage: node scripts/gds/recall.js <query…> [--limit N] [--kind doc|db] [--json]');
+    console.error('       node scripts/gds/recall.js --expand <id>   # full content of one hit');
+    process.exit(1);
+  }
+  const body = { q: args.q };
+  if (Number.isFinite(args.limit)) body.limit = args.limit;
+  if (args.kind === 'doc' || args.kind === 'db') body.source_kind = args.kind;
+
+  const api = await cliClient();
+  const r = await api.search.postSearch({ body });
+  if (!r.ok) {
+    reportError(r);
+    process.exit(1);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(r.data, null, 2));
+    return;
+  }
+
+  const { count, results, total_full_tokens } = r.data;
+  if (!count) {
+    console.log(`No matches for "${args.q}". The index covers repo docs + (nightly) DB prose; try fewer / different terms, or it may not be indexed yet.`);
+    return;
+  }
+  const totalNote = Number.isFinite(total_full_tokens)
+    ? `  ·  ~${total_full_tokens} tokens to expand all`
+    : '';
+  console.log(`${count} result(s) for "${args.q}"${totalNote}:\n`);
+  for (const [i, res] of results.entries()) {
+    const where = res.heading_path || res.source_ref;
+    const legs = [res.fts_rank ? 'fts' : null, res.trgm_rank ? 'trgm' : null].filter(Boolean).join('+') || '—';
+    // Token-cost label: full_tokens is what a full read of this hit COSTS; the
+    // `+` flags that the snippet below is only a preview of a larger chunk.
+    const cost = res.full_tokens != null
+      ? `~${res.full_tokens} tok${res.truncated ? ' to expand' : ''}`
+      : '';
+    console.log(`#${res.id}. ${res.title || res.source_ref}`);
+    console.log(`   ${where}`);
+    console.log(`   ${res.source_ref}  ·  score ${Number(res.score).toFixed(4)}  ·  ${legs}${cost ? '  ·  ' + cost : ''}`);
+    console.log(`   ${truncate(res.snippet, 240)}`);
+    if (res.truncated) console.log(`   → recall --expand ${res.id}  for the full section`);
+    console.log('');
+  }
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error('recall: error', e && e.message ? e.message : e); process.exit(1); });
+}
+
+module.exports = { parseArgs, truncate };