nearly-cli 0.1.0

package/scripts/hook.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// One Claude Code hook event, forwarded to the Nearly.
+//
+//   node scripts/hook.mjs <event> <repo-name>
+//
+// Claude Code writes the event as JSON on stdin and reads our answer from
+// stdout. We sit in between so the server does not have to be running before
+// you start work: if nothing is listening, this starts it, waits for it, and
+// forwards. Nobody has to remember a terminal.
+//
+// Two rules this file exists to honour:
+//
+//   1. Never break someone's session. If the server cannot be reached or
+//      started, print nothing and exit 0. Claude Code then falls back to its own
+//      permission prompts, which is worse than being recorded but better than
+//      being stuck.
+//   2. Never take longer than it has to. The health check is a few milliseconds
+//      on the common path, where the server is already up.
+
+import { spawn } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HOST = '127.0.0.1';
+const PORT = Number(process.env.NEARLY_PORT || 47653);
+const BASE = `http://${HOST}:${PORT}`;
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const [, , event, name = 'repo'] = process.argv;
+if (!event) process.exit(0);
+
+const body = await new Promise((r) => {
+  let s = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (d) => (s += d));
+  process.stdin.on('end', () => r(s));
+  process.stdin.on('error', () => r(''));
+});
+
+async function up(ms = 400) {
+  try {
+    const c = AbortSignal.timeout(ms);
+    const r = await fetch(`${BASE}/health`, { signal: c });
+    return r.ok;
+  } catch { return false; }
+}
+
+async function start() {
+  const child = spawn(process.execPath, [join(root, 'server', 'index.mjs')], {
+    cwd: root, detached: true, stdio: 'ignore',
+  });
+  child.unref();
+  // Two seconds is generous for a dependency-free server binding one port.
+  for (let i = 0; i < 20; i++) {
+    await new Promise((r) => setTimeout(r, 100));
+    if (await up(200)) return true;
+  }
+  return false;
+}
+
+if (!(await up()) && !(await start())) process.exit(0);   // fail open, silently
+
+// PreToolUse can hold for as long as the server is willing to wait for a human.
+// Everything else should be quick; keep it short so a wedged endpoint cannot
+// stall the agent.
+const budget = event === 'pre-tool' ? 600_000 : 15_000;
+
+try {
+  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: body || '{}',
+    signal: AbortSignal.timeout(budget),
+  });
+  const text = await res.text();
+  if (text && text !== '{}') process.stdout.write(text);
+} catch { /* fail open */ }
+
+process.exit(0);

package/scripts/install-push-hook.mjs

@@ -0,0 +1,87 @@
+// Install a git pre-push hook that builds the branch's session record and
+// offers to post it to the pull request.
+//
+//   node scripts/install-push-hook.mjs <repo-path> [--remove]
+//
+// Pushing is the moment your work stops being yours and becomes someone else's
+// to review, so it is the right moment to hand over the record. The hook:
+//
+//   1. builds one record for the branch being pushed, merging every session
+//   2. prints what it found, including anything that was refused
+//   3. asks whether to post it, reading your answer from the terminal
+//   4. gets out of the way
+//
+// It never blocks a push. If the record cannot be built, or you say no, or
+// anything at all goes wrong, the push proceeds and the hook exits 0. Posting
+// is always your explicit "y" — a record of what you refused is more revealing
+// than a diff, and software should not publish that on your behalf.
+
+import { writeFileSync, readFileSync, mkdirSync, existsSync, rmSync, chmodSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
+const argv = process.argv.slice(2);
+const repo = resolve(argv.find((a) => !a.startsWith('--')) || '.');
+const remove = argv.includes('--remove');
+
+if (!existsSync(join(repo, '.git'))) {
+  console.error(`${repo} is not a git repository`);
+  process.exit(1);
+}
+// Stable across renames on purpose: this string is how a hook is identified as
+// ours years from now, so it must never carry the product name.
+const MARKER = 'x-session-record-hook';
+const hooksDir = join(repo, '.git', 'hooks');
+const hookPath = join(hooksDir, 'pre-push');
+
+if (remove) {
+  if (existsSync(hookPath)) { rmSync(hookPath); console.log(`Removed ${hookPath}`); }
+  else console.log('No pre-push hook to remove.');
+  process.exit(0);
+}
+
+if (existsSync(hookPath)) {
+  const existing = readFileSync(hookPath, 'utf8');
+  // Recognise it by a marker that does not change when the product is renamed,
+  // and still recognise hooks written before this file existed.
+  const mine = existing.includes(MARKER) || /control-room|nearly/.test(existing);
+  if (!mine) {
+    console.error(`${hookPath} already exists and was not written by the Nearly.`);
+    console.error('Refusing to overwrite it. Move it aside, or add this line to it yourself:');
+    console.error(`  node ${join(root, 'scripts', 'push-record.mjs')} "${repo}" || true`);
+    process.exit(1);
+  }
+}
+
+mkdirSync(hooksDir, { recursive: true });
+writeFileSync(hookPath, `#!/bin/sh
+# ${MARKER}
+# nearly: hand the session record over at push time.
+# Never blocks the push; "exit 0" at the end is the whole safety story.
+#
+# git gives a hook no terminal of its own, so borrow the user's when there is
+# one. Scripted and CI pushes have no controlling terminal: run anyway, print
+# nothing to ask, and post nothing.
+#
+# The test has to be an actual open. /dev/tty always exists and is always
+# readable and writable by its permission bits; opening it is what fails, with
+# ENXIO, when no terminal is attached. The open has to happen inside a subshell
+# too: a failed redirection is reported by the shell itself, so redirecting the
+# command's stderr does not silence it, but redirecting the subshell's does.
+CR="${join(root, 'scripts', 'push-record.mjs')}"
+if (: >/dev/tty) 2>/dev/null; then
+  node "$CR" "${repo}" </dev/tty >/dev/tty 2>&1 || true
+else
+  NEARLY_NO_TTY=1 node "$CR" "${repo}" || true
+fi
+exit 0
+`);
+chmodSync(hookPath, 0o755);
+
+console.log(`Installed ${hookPath}`);
+console.log('');
+console.log('Next push on this repo will build the branch record and ask before posting.');
+console.log('Set NEARLY_URL_BASE so the comment can link to the hosted page, e.g.');
+console.log('  export NEARLY_URL_BASE=https://<user>.github.io/<repo>/recaps');
+console.log('Remove it again with: node scripts/install-push-hook.mjs "' + repo + '" --remove');

package/scripts/post-recap.mjs

@@ -0,0 +1,124 @@
+// Post a session's recap to the pull request for its branch, as a comment.
+//
+//   node scripts/post-recap.mjs <session-id | latest> [--url-base https://you.github.io/nearly/recaps] [--dry-run]
+//
+// Uses the GitHub CLI (`gh pr comment`) in the repo the session ran in, so it
+// works with whatever account gh is logged in as. Nothing is uploaded: the
+// comment carries the computed summary and every narration line as text, plus
+// a link to the record page when --url-base (or NEARLY_URL_BASE) says where the
+// ui/records folder is hosted. Without a base URL the comment says where the
+// file lives locally. --dry-run prints the comment and posts nothing.
+
+import { readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const argv = process.argv.slice(2);
+const dry = argv.includes('--dry-run');
+const ubIdx = argv.indexOf('--url-base');
+const urlBase = (ubIdx !== -1 ? argv[ubIdx + 1] : process.env.NEARLY_URL_BASE || '').replace(/\/$/, '');
+const target = argv.find((a, i) => !a.startsWith('--') && argv[i - 1] !== '--url-base') || 'latest';
+
+const dir = join(root, 'records');
+const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+if (!files.length) { console.error('no storyboards in records/. Run build-recap first.'); process.exit(1); }
+let file;
+if (target === 'latest') {
+  file = files.map((f) => ({ f, m: statSync(join(dir, f)).mtimeMs })).sort((a, b) => b.m - a.m)[0].f;
+} else {
+  file = files.find((f) => f === `${target}.json`)                                  // exact slug, e.g. repo--branch
+      || files.find((f) => JSON.parse(readFileSync(join(dir, f), 'utf8')).id.startsWith(target))  // session id
+      || files.find((f) => f.includes(target));                                     // loose match, last resort
+}
+if (!file) { console.error(`no storyboard for ${target}`); process.exit(1); }
+
+const sb = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+const slug = file.replace(/\.json$/, '');
+const cover = sb.scenes.find((s) => s.kind === 'cover');
+const outcome = sb.scenes.find((s) => s.kind === 'outcome');
+const mmss = (s) => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, '0')}`;
+
+const lines = [];
+lines.push(sb.runs > 1
+  ? `### Session record for \`${sb.branch}\`: ${cover.title}`
+  : `### Session record: ${cover.title}`);
+lines.push('');
+lines.push(urlBase
+  ? `**[Watch the record (${mmss(sb.totalS)})](${urlBase}/${slug}.html)** · ${sb.runs > 1 ? `${sb.runs} agent sessions` : `agent \`${sb.name}\``} · ${sb.model} · ${sb.date}`
+  : `Record: \`ui/records/${slug}.html\` in the Nearly checkout (${mmss(sb.totalS)}, not hosted yet) · ${sb.runs > 1 ? `${sb.runs} agent sessions` : `agent \`${sb.name}\``} · ${sb.model} · ${sb.date}`);
+lines.push('');
+if (outcome?.notDone?.length) {
+  lines.push(`> **${outcome.notDone.length} thing${outcome.notDone.length > 1 ? 's' : ''} the agent wanted to do did not happen.** The diff cannot show you this.`);
+  lines.push('>');
+  for (const n of outcome.notDone) lines.push(`> - \`${n.tool}\` · \`${n.what}\` — ${n.by === 'policy' ? 'blocked by policy' : 'refused by the supervisor'}`);
+  lines.push('');
+}
+lines.push('| ' + cover.stats.map(([k]) => k).join(' | ') + ' |');
+lines.push('|' + cover.stats.map(() => '---').join('|') + '|');
+lines.push('| ' + cover.stats.map(([, v]) => v).join(' | ') + ' |');
+lines.push('');
+lines.push('<details><summary>Scene by scene</summary>');
+lines.push('');
+sb.scenes.forEach((s, i) => { lines.push(`${i + 1}. **${s.kind}** — ${s.narration}`); });
+lines.push('');
+lines.push('</details>');
+lines.push('');
+lines.push(`<sub>Every number above was computed from the session recording. ${sb.polished ? 'Sentences were rewritten by a model; facts were not.' : 'No model wrote any of it.'}</sub>`);
+// A hidden marker so we can find our own comment again on the next push and
+// edit it, instead of stacking a new one on every push until nobody reads any.
+// Deliberately carries no product name. This string is how a comment is
+// recognised as ours on every future push, so renaming the project must not
+// orphan every comment already posted. LEGACY covers ones posted before this.
+const MARKER = '<!-- x-session-record -->';
+const LEGACY = ['<!-- nearly:session-record -->', '<!-- control-room:session-record -->'];
+const body = `${MARKER}\n${lines.join('\n')}`;
+
+if (dry) { console.log(body); process.exit(0); }
+
+const cwd = sb.cwd;
+if (!cwd) { console.error('storyboard has no repo path; cannot find the pull request'); process.exit(1); }
+
+const gh = (args, opts = {}) => spawnSync('gh', args, { cwd, encoding: 'utf8', ...opts });
+
+// Which pull request, and in which repository.
+//
+// Ask for the record's own branch rather than whatever happens to be checked
+// out. You should be able to hand over a branch's record from anywhere in the
+// repo, and days after you moved on from it.
+const view = gh(['pr', 'view', ...(sb.branch ? [sb.branch] : []), '--json', 'number,url']);
+if (view.status !== 0) {
+  console.error(`no open pull request for ${sb.branch ? `"${sb.branch}"` : 'this branch'} in ${cwd}`);
+  console.error((view.stderr || view.stdout || '').trim().split('\n')[0]);
+  process.exit(1);
+}
+const { number, url: prUrl } = JSON.parse(view.stdout);
+const repoView = gh(['repo', 'view', '--json', 'nameWithOwner']);
+const nwo = JSON.parse(repoView.stdout || '{}').nameWithOwner;
+if (!nwo) { console.error('could not identify the repository'); process.exit(1); }
+
+const tmp = join(tmpdir(), `recap-comment-${slug}.md`);
+writeFileSync(tmp, body);
+
+// Already posted one? Edit it. A branch gets pushed many times, and the reviewer
+// should see the current state, not a stack of stale records.
+const anyMarker = [MARKER, ...LEGACY].map((m) => `(.body | contains("${m}"))`).join(' or ');
+const mine = gh(['api', `repos/${nwo}/issues/${number}/comments`, '--paginate',
+                 '--jq', `[.[] | select(${anyMarker}) | .id] | first`]);
+const existing = (mine.stdout || '').trim();
+
+let r;
+if (existing && existing !== 'null') {
+  r = gh(['api', '-X', 'PATCH', `repos/${nwo}/issues/comments/${existing}`,
+          '-F', `body=@${tmp}`, '--jq', '.html_url']);
+  if (r.status === 0) console.log(`updated ${(r.stdout || '').trim() || prUrl}`);
+} else {
+  r = gh(['pr', 'comment', String(number), '--body-file', tmp]);
+  if (r.status === 0) console.log(`posted ${(r.stdout || '').trim() || prUrl}`);
+}
+if (r.status !== 0) {
+  console.error(`could not ${existing && existing !== 'null' ? 'update' : 'post'} the comment: ${(r.stderr || r.stdout).trim()}`);
+  process.exit(1);
+}

package/scripts/publish-pages.mjs

@@ -0,0 +1,141 @@
+// Build the docs/ folder that GitHub Pages serves, so recap links in pull
+// request comments actually resolve.
+//
+//   node scripts/publish-pages.mjs [--base https://<user>.github.io/<repo>]
+//
+// Copies every built recap into docs/records/ and writes docs/index.html, an
+// index of the sessions on record. Then, once:
+//
+//   Settings → Pages → Source: "Deploy from a branch", branch main, folder /docs
+//
+// After that, `node scripts/post-recap.mjs latest --url-base <base>/recaps`
+// posts a comment whose link works for anyone who can see the repository.
+//
+// Zero cost, no server, no account beyond the GitHub one you already have.
+
+import { readFileSync, writeFileSync, readdirSync, mkdirSync, copyFileSync, existsSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const storyDir = join(root, 'records');
+const builtDir = join(root, 'ui', 'records');
+const docsDir = join(root, 'docs');
+const outRecaps = join(docsDir, 'records');
+
+const argv = process.argv.slice(2);
+const bIdx = argv.indexOf('--base');
+const BASE = (bIdx !== -1 ? argv[bIdx + 1] : process.env.NEARLY_URL_BASE || '').replace(/\/$/, '');
+
+if (!existsSync(storyDir)) { console.error('no records/ yet — run build-recap first'); process.exit(1); }
+
+mkdirSync(outRecaps, { recursive: true });
+
+const esc = (s) => String(s ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+const mmss = (s) => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, '0')}`;
+
+// Every session auto-builds its own record when it ends, but a branch record
+// merges them and is what the reviewer gets. Where both exist for a branch, the
+// branch record wins; otherwise the index fills with pages nobody links to.
+const all = readdirSync(storyDir).filter((f) => f.endsWith('.json'));
+const coveredBranches = new Set();
+for (const f of all) {
+  try {
+    const sb = JSON.parse(readFileSync(join(storyDir, f), 'utf8'));
+    if (sb.kind === 'branch' && sb.branch) coveredBranches.add(`${sb.cwd || ''}::${sb.branch}`);
+  } catch { /* unreadable storyboard; the loop below reports it */ }
+}
+
+const sessions = [];
+const superseded = [];
+for (const f of all) {
+  const slug = f.replace(/\.json$/, '');
+  const html = join(builtDir, `${slug}.html`);
+  if (!existsSync(html)) { console.warn(`skipping ${slug}: no built page`); continue; }
+  
+  const sb = JSON.parse(readFileSync(join(storyDir, f), 'utf8'));
+  if (sb.kind !== 'branch' && coveredBranches.has(`${sb.cwd || ''}::${sb.branch}`)) { superseded.push(slug); continue; }
+  const cover = sb.scenes.find((s) => s.kind === 'cover');
+  const outcome = sb.scenes.find((s) => s.kind === 'outcome');
+  sessions.push({
+    slug, name: sb.name, branch: sb.branch, date: sb.date, startedAt: sb.startedAt,
+    title: cover?.title ?? slug, total: sb.totalS, supervisor: sb.supervisor,
+    refused: (outcome?.notDone ?? []).length, kb: Math.round(statSync(html).size / 1024),
+  });
+  copyFileSync(html, join(outRecaps, `${slug}.html`));
+}
+sessions.sort((a, b) => b.startedAt - a.startedAt);
+
+const rows = sessions.map((s) => `
+      <a class="row" href="recaps/${esc(s.slug)}.html">
+        <span class="t">${esc(s.title)}</span>
+        <span class="m">${esc(s.name)}${s.branch ? ` · ${esc(s.branch)}` : ''} · supervised by ${esc(s.supervisor)}</span>
+        <span class="r">${s.refused ? `<b>${s.refused} refused</b>` : 'nothing refused'}</span>
+        <span class="d">${esc(s.date)} · ${mmss(s.total)}</span>
+      </a>`).join('');
+
+const page = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Session records · Nearly</title>
+<meta name="description" content="What agents did in this repository, including what a human refused.">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap">
+<style>
+  :root {
+    --bg:#0B0D11; --panel:#13161C; --panel-2:#191D25; --rule:#242932; --rule-soft:#1B1F27;
+    --ink:#E9ECF1; --ink-2:#98A1AF; --ink-3:#667080; --deny:#FF7A7A; --accent:#7C8CFF;
+    --mono:"JetBrains Mono",ui-monospace,SFMono-Regular,Menlo,monospace;
+    color-scheme: dark;
+  }
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--ink);font-family:"Plus Jakarta Sans",ui-sans-serif,system-ui,-apple-system,sans-serif;font-size:14px;line-height:1.55;letter-spacing:-.006em;-webkit-font-smoothing:antialiased}
+  .shell{max-width:840px;margin:0 auto;padding-inline:22px;padding-block:52px 80px;display:flex;flex-direction:column;gap:28px}
+  .lbl{font-family:var(--mono);font-size:10px;letter-spacing:.14em;text-transform:uppercase;color:var(--ink-3);font-weight:500}
+  h1{margin:6px 0 0;font-size:27px;font-weight:700;letter-spacing:-.03em}
+  .lede{margin:0;color:var(--ink-2);font-size:15.5px;max-width:60ch;line-height:1.6}
+  .lede b{color:var(--ink);font-weight:600}
+  .list{display:flex;flex-direction:column;gap:10px}
+  a.row{display:grid;grid-template-columns:1fr auto;gap:5px 16px;padding:16px 18px;text-decoration:none;color:inherit;background:var(--panel);border:1px solid var(--rule);border-radius:12px;transition:border-color .12s,background .12s}
+  a.row:hover{background:var(--panel-2);border-color:var(--ink-3)}
+  a.row:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+  .t{font-size:16px;font-weight:700;letter-spacing:-.02em;grid-column:1}
+  .m{font-family:var(--mono);font-size:11px;color:var(--ink-3);grid-column:1}
+  .r{grid-column:2;grid-row:1;text-align:right;font-family:var(--mono);font-size:11px;color:var(--ink-3);white-space:nowrap}
+  .r b{color:var(--deny);font-weight:500}
+  .d{grid-column:2;grid-row:2;text-align:right;font-family:var(--mono);font-size:11px;color:var(--ink-3);white-space:nowrap}
+  .empty{padding:26px 18px;color:var(--ink-3);border:1px dashed var(--rule);border-radius:12px}
+  .foot{color:var(--ink-3);font-size:12.5px;max-width:74ch;border-top:1px solid var(--rule-soft);padding-top:18px}
+  @media (max-width:560px){a.row{grid-template-columns:1fr}.r,.d{grid-column:1;text-align:left}}
+</style>
+</head>
+<body>
+<div class="shell">
+  <div>
+    <span class="lbl">Nearly</span>
+    <h1>Session records</h1>
+  </div>
+  <p class="lede">Each entry is the record of one coding-agent session: the task it was given, every action a human held or refused, the changes it made, and anything that was rolled back. <b>A diff tells you what changed. These tell you what nearly happened.</b></p>
+  <div class="list">${rows || '<div class="empty">No sessions recorded yet.</div>'}</div>
+  <p class="foot">Generated ${new Date().toLocaleString('en-GB')} by the Nearly. Every figure on these pages is computed from the session recordings, not written by a model.</p>
+</div>
+</body>
+</html>
+`;
+
+writeFileSync(join(docsDir, 'index.html'), page);
+writeFileSync(join(docsDir, '.nojekyll'), '');
+
+console.log(`docs/ built — ${sessions.length} record(s)`);
+if (superseded.length) console.log(`  (${superseded.length} per-session record(s) superseded by a branch record)`);
+for (const s of sessions) console.log(`  ${s.slug.padEnd(22)} ${s.refused} refused  ${s.kb} KB`);
+console.log('');
+if (BASE) {
+  console.log(`Index will be at   ${BASE}/`);
+  console.log(`Post a recap with  node scripts/post-recap.mjs latest --url-base ${BASE}/recaps`);
+} else {
+  console.log('Next: commit docs/, then Settings → Pages → branch main, folder /docs.');
+  console.log('Then re-run with --base https://<user>.github.io/<repo> for the exact commands.');
+}

package/scripts/push-record.mjs

@@ -0,0 +1,126 @@
+// What the pre-push hook runs. Builds the branch's session record, shows what
+// it found, and asks whether to hand it to the reviewer.
+//
+//   node scripts/push-record.mjs <repo-path>
+//
+// Exits 0 no matter what. A recap is never worth failing someone's push over.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
+const repo = resolve(process.argv[2] || '.');
+function configured() {
+  try {
+    const f = join(root, '.nearly.json');
+    if (existsSync(f)) return JSON.parse(readFileSync(f, 'utf8')).urlBase || '';
+  } catch { /* fall through to the env var */ }
+  return '';
+}
+const URL_BASE = (process.env.NEARLY_URL_BASE || configured() || '').replace(/\/$/, '');
+// Narration takes about a second a scene, which is too long to make someone
+// wait at a push. Opt in with NEARLY_AUDIO=1 when you are making the good one.
+const WANT_AUDIO = process.env.NEARLY_AUDIO === '1';
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+
+function bail(msg) { if (msg) console.error(dim(`nearly: ${msg}`)); process.exit(0); }
+
+let branch;
+try {
+  branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repo, encoding: 'utf8' }).trim();
+} catch { bail('could not read the branch'); }
+if (!branch || branch === 'HEAD') bail('detached HEAD, nothing to record');
+
+const args = ['--branch', branch, '--repo', repo];
+if (!WANT_AUDIO) args.push('--no-audio');
+const build = spawnSync(process.execPath, [join(root, 'scripts', 'build-recap.mjs'), ...args],
+  { cwd: root, encoding: 'utf8', timeout: 180_000 });
+
+if (build.status !== 0) {
+  // A branch with no agent sessions is the normal case for hand-written work,
+  // not an error worth shouting about. Node prints a stack plus its own version
+  // footer, so pick the message line rather than the last line.
+  const err = build.stderr || '';
+  if (/no recordings on branch/.test(err)) bail(`no agent sessions recorded on ${branch}`);
+  const line = err.split('\n').map((l) => l.trim())
+    .find((l) => /^(Error|TypeError|ReferenceError|SyntaxError)[:\s]/.test(l));
+  bail(line || `could not build the record (exit ${build.status})`);
+}
+
+const safe = (x) => String(x).replace(/[^a-z0-9._-]+/gi, '-').replace(/^-|-$/g, '').toLowerCase();
+const slug = `${safe(basename(repo))}--${safe(branch)}`;
+const storyPath = join(root, 'records', `${slug}.json`);
+if (!existsSync(storyPath)) bail('record built but not found on disk');
+
+const sb = JSON.parse(readFileSync(storyPath, 'utf8'));
+const cover = sb.scenes.find((s) => s.kind === 'cover');
+const outcome = sb.scenes.find((s) => s.kind === 'outcome');
+const notDone = outcome?.notDone ?? [];
+const mmss = (s) => `${Math.floor(s / 60)}:${String(Math.round(s % 60)).padStart(2, '0')}`;
+
+console.log('');
+console.log(bold(`  Session record for ${branch}`));
+console.log(dim(`  ${sb.runs} session${sb.runs === 1 ? '' : 's'} · ${cover.title} · ${mmss(sb.totalS)} to watch`));
+if (notDone.length) {
+  console.log('');
+  console.log(`  ${red('These never happened, and the diff will not show them:')}`);
+  for (const n of notDone) {
+    const by = n.by === 'policy' ? 'blocked by policy' : 'you refused it';
+    console.log(`    · ${n.tool}  ${n.what}  ${dim(`(${by})`)}`);
+  }
+}
+console.log('');
+console.log(dim(`  ${URL_BASE ? `${URL_BASE}/${slug}.html` : `ui/records/${slug}.html (set NEARLY_URL_BASE to publish it)`}`));
+console.log('');
+
+// A push is the right moment to update: it happens often for anyone actually
+// using this, the person is present and waiting, and it is nowhere near the path
+// an agent's tool call travels. Turning it on for a repo happens once, and the
+// hooks are excluded on purpose, so without this an active user would never
+// hear about a fix.
+try {
+  const { checkForUpdate, applyUpdate } = await import('./update-check.mjs');
+  applyUpdate(await checkForUpdate());
+} catch { /* never worth failing a push over */ }
+
+// gh is only useful if there is a pull request to comment on
+const hasGh = spawnSync('gh', ['--version'], { encoding: 'utf8' }).status === 0;
+const pr = hasGh ? spawnSync('gh', ['pr', 'view', '--json', 'number,url'], { cwd: repo, encoding: 'utf8' }) : null;
+if (!pr || pr.status !== 0) {
+  console.log(dim('  No open pull request for this branch yet. Raise one, then push again to attach the record.'));
+  console.log('');
+  process.exit(0);
+}
+const prUrl = (() => { try { return JSON.parse(pr.stdout).url; } catch { return null; } })();
+
+if (process.env.NEARLY_NO_TTY === '1' || !process.stdin.isTTY) {
+  console.log(dim('  No terminal to ask on, so nothing was posted.'));
+  console.log(dim(`  Post it yourself: node scripts/post-recap.mjs ${slug}${URL_BASE ? ` --url-base ${URL_BASE}` : ''}`));
+  console.log('');
+  process.exit(0);
+}
+
+const rl = createInterface({ input: process.stdin, output: process.stdout });
+const answer = await new Promise((r) => rl.question(`  Post this record to ${prUrl || 'the pull request'}? [y/N] `, r))
+  .finally(() => rl.close());
+
+if (!/^y(es)?$/i.test(String(answer).trim())) {
+  console.log(dim('  Not posted. Push continues.'));
+  console.log('');
+  process.exit(0);
+}
+
+const postArgs = [join(root, 'scripts', 'post-recap.mjs'), slug];
+if (URL_BASE) postArgs.push('--url-base', URL_BASE);
+const post = spawnSync(process.execPath, postArgs, { cwd: root, encoding: 'utf8', timeout: 60_000 });
+console.log(post.status === 0
+  ? `  Posted. ${(post.stdout || '').trim()}`
+  : red(`  Could not post: ${(post.stderr || post.stdout || '').trim().split('\n').pop()}`));
+console.log('');
+process.exit(0);