nearly-cli 0.1.7 → 0.1.10

package/README.md

@@ -22,7 +22,11 @@ Watch the first thirty seconds. The cover says what the diff cannot: an action t
 
 ## What it needs
 
-Node 18 or newer, git, and one of the seven coding agents below signed in. No dependencies and no API key of its own: agents run on whatever subscription you already have.
+Node 18 or newer, git, and one of the seven coding agents below signed in.
+Posting the record to a pull request also needs the [GitHub CLI](https://cli.github.com)
+signed in (`gh auth login`); everything else works without it. If nothing is
+showing up, `nearly doctor` walks the whole chain — gate, recording, record,
+pull request, link — and names what is in the way. No dependencies and no API key of its own: agents run on whatever subscription you already have.
 
 ### Platforms
 
@@ -61,11 +65,16 @@ the hook. Seven are supported:
 | Claude Code | `.claude/settings.local.json` | yes | full |
 | Cursor | `.cursor/hooks.json` | yes | full |
 | Antigravity | `.agents/hooks.json` | yes | full |
-| GitHub Copilot CLI | `.github/hooks/nearly.json` | yes | full |
+| GitHub Copilot (CLI **and VS Code agent mode**) | `.github/hooks/nearly.json` | yes | full |
 | Gemini CLI | `.gemini/settings.json` | yes | full |
 | Codex CLI | `.codex/hooks.json` | yes | no prompts, one turn |
 | Windsurf | `.windsurf/hooks.json` | until Cascade gives up | shell and file tools only |
 
+VS Code agent mode loads every `.json` in `.github/hooks/` with no further
+setup, so `nearly --agent=copilot` is the whole of it there — and it is the only
+route for someone on Windows who does not have Claude Code, since Cline's hooks
+are macOS and Linux only and Windsurf's cannot be given a deadline.
+
 `nearly` turns on whichever of these the repo shows signs of, and Claude Code
 either way. `nearly --agent=cursor` forces one, `--agent=all` forces all of them,
 and `nearly agents` prints what is actually wired here.
@@ -113,6 +122,11 @@ Zed's built-in agent, Aider, Kilo Code, Warp and the hosted builders (Replit,
 Lovable, Bolt, v0) expose no blocking pre-tool hook. There is nothing to attach
 to, and no adapter can change that.
 
+**Cline** has one, and it is macOS and Linux only — so on Windows there is
+nothing to attach to there either. Cline does keep its own consent trail in
+`ui_messages.json` under its task history, which Nearly could read after the
+fact; that would be a reader rather than a gate, and it does not exist yet.
+
 ## Use it on your own repo
 
 One command, in the repo you want recorded.
@@ -317,6 +331,36 @@ node scripts/publish-pages.mjs --base https://<user>.github.io/<repo>
 
 That copies every built recap into `docs/records/` and writes `docs/index.html`, an index of the sessions on record. Commit `docs/`, then set **Settings → Pages → branch `main`, folder `/docs`**. Preview it locally first at http://127.0.0.1:47653/docs/ while the server is running.
 
+## The server, and why you never start it
+
+The first hook that needs the server starts it, and it stays up for the rest of
+the day rather than paying the startup cost on every tool call. Two consequences
+had to be designed for, because both were found the hard way on other people's
+machines.
+
+A server outlives the run that started it, so one `npx nearly-cli` — or any
+upgrade — can leave the previous build holding the port. It keeps answering,
+from a directory npm has since replaced, which is why its record pages 404 and
+why upgrading appears to do nothing at all. Every server now says which build it
+is and where it lives, and a hook from a different install takes the port back
+before doing anything else — without being asked, because nobody reads a hook's
+output, and a fix only the people who happen to re-read a message ever get is
+not a fix.
+
+Builds from 0.1.8 stand down when asked. Older ones have no way to be asked, so
+an idle one is ended outright. Two rules make that defensible. It must prove it
+is ours twice, on `/health` and on `/state` — the second carries the consent
+gradient itself, which nothing else on your machine is going to return by
+chance, so a plain web server that happens to sit on 47653 is never touched. And
+it is never ended while anybody is using it: dropping a held request would hand
+it back to the agent's own prompt, which is the one outcome this project exists
+to prevent. If a server cannot be ended, `nearly` says so and gives you the
+command for your platform rather than leaving you to work it out.
+
+And a server with no sessions that nobody has asked anything of for thirty
+minutes exits on its own. There is nothing to remember to shut down, and nothing
+squats on a port for days.
+
 ## Why the hook fails open
 
 Claude Code treats a hook that times out, errors, or returns anything other than `200` with JSON as a non-blocking error and lets the tool call proceed. So this server always answers with JSON, holds "ask" calls for at most `ASK_TIMEOUT_MS`, and denies when nobody decides. The hook's own timeout is set longer than that.

package/bin/nearly.mjs

@@ -8,6 +8,7 @@
 //   nearly record       build the record for the current branch
 //   nearly post         put that record on the pull request
 //   nearly agents       which agents this repo is gated for
+//   nearly doctor       why nothing is showing up
 //   nearly voices       list the narration voices you have
 //   nearly server       run the server in the foreground (it self-starts otherwise)
 //   nearly hook <ev>    internal: what the Claude Code hooks call
@@ -78,6 +79,9 @@ switch (cmd) {
   case 'agents':
     return run(s('agents.mjs'), rest);
 
+  case 'doctor': case 'why':
+    return run(s('doctor.mjs'), rest);
+
   case 'voices':
     return run(s('build-recap.mjs'), ['--voices']);
 
@@ -106,6 +110,7 @@ switch (cmd) {
   nearly record       build the record for the current branch
   nearly post         put that record on the pull request
   nearly agents       which agents this repo is gated for
+  nearly doctor       why nothing is showing up
   nearly voices       list the narration voices you have
   nearly server       run the server in the foreground
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.7",
+  "version": "0.1.10",
   "description": "A pull request tells you what changed. Nearly tells you what nearly happened: the commands a human refused, the pushes policy blocked, the turns rolled back.",
   "type": "module",
   "bin": {
@@ -34,6 +34,6 @@
   },
   "homepage": "https://anujpatel06.github.io/nearly/",
   "scripts": {
-    "test": "node --test --test-concurrency=1 test/policy.test.mjs test/server.test.mjs test/record.test.mjs test/resilience.test.mjs test/detect.test.mjs test/adapters.test.mjs test/spawn.test.mjs"
+    "test": "node --test --test-concurrency=1 test/policy.test.mjs test/server.test.mjs test/record.test.mjs test/resilience.test.mjs test/detect.test.mjs test/adapters.test.mjs test/spawn.test.mjs test/stale-server.test.mjs"
   }
 }

package/scripts/attach.mjs

@@ -28,7 +28,7 @@ import { ADAPTERS } from '../server/adapters.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const HOOK = join(root, 'scripts', 'hook.mjs');
-const PORT = 47653;
+const PORT = Number(process.env.NEARLY_PORT || 47653);
 
 // What the hooks should invoke, in order of preference. This choice decides
 // whether upgrading the tool ever reaches the repos it was turned on for.
@@ -177,6 +177,27 @@ try {
   notes.push(`could not remember this repo for the dashboard: ${e.message}`);
 }
 
+// ---------------------------------------------------------------------------
+// A server from somewhere else, already holding the port
+// ---------------------------------------------------------------------------
+// The server outlives the run that starts it. So a single `npx nearly-cli`, or
+// any upgrade, can leave the previous build squatting — answering from a
+// directory npm has since replaced, 404ing its own record pages, and making
+// every fix since invisible. A hook cannot say any of this out loud; this
+// command can, because you are here reading it.
+//
+// Builds from 0.1.8 stand down when asked. Older ones have no way to be asked,
+// so the honest thing is to name the problem and the exact command.
+async function checkPort() {
+  let mine = root;
+  try { mine = realpathSync(root); } catch { /* compare the literal path */ }
+  try {
+    const { reclaim } = await import('../server/reclaim.mjs');
+    return await reclaim({ port: PORT, base: `http://127.0.0.1:${PORT}`, root: mine });
+  } catch { return null; }
+}
+const port = off ? null : await checkPort();
+
 // ---------------------------------------------------------------------------
 // git pre-push hook
 // ---------------------------------------------------------------------------
@@ -260,6 +281,25 @@ if (base) {
 }
 for (const n of notes) console.log(`  ${dim('·')} ${dim(n)}`);
 
+if (port?.outcome === 'stood-down' || port?.outcome === 'ended') {
+  const from = port.who?.root || 'an older build';
+  console.log(`  ${ok('·')} ${dim(`closed an older Nearly server that was holding port ${PORT}`)}`);
+  console.log(`    ${dim(from)}`);
+} else if (port?.outcome === 'busy') {
+  console.log('');
+  console.log(`  ${bold('Another Nearly server is on this port and is in use.')}`);
+  console.log(dim('  Left it alone. Run this again once it is idle and this build will take over.'));
+} else if (port?.outcome === 'stuck') {
+  console.log('');
+  console.log(`  ${bold(`An older Nearly server is holding port ${PORT} and would not close.`)}`);
+  console.log(dim('  Until it goes it answers instead of this one, which is why its record pages'));
+  console.log(dim('  404 and why upgrading appears to do nothing.'));
+  console.log('');
+  console.log(`  ${dim('End it with:')}  ${process.platform === 'win32'
+    ? `netstat -ano | findstr :${PORT}   then   taskkill /PID <pid> /F`
+    : `lsof -ti:${PORT} -sTCP:LISTEN | xargs kill`}`);
+}
+
 // An agent you have on this machine but have not used here is worth a word, and
 // nothing more: having it installed is no reason to write files into this repo.
 const elsewhere = agentsOnMachine().filter((i) => !wired.some((w) => w.id === i.id));

package/scripts/doctor.mjs

@@ -0,0 +1,165 @@
+// Why is nothing showing up?
+//
+//   nearly doctor
+//
+// Everything this project does is a chain: gate the session, record it, build
+// the record, find the pull request, post the link. A break anywhere means
+// nothing appears, and every step is quiet by design — hooks must never
+// interrupt an agent, and a push must never fail over a recap. Quiet is right
+// and it is also how somebody ends up staring at an empty pull request with no
+// idea which link came apart.
+//
+// So this walks the chain in order and stops being polite about it.
+
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { join, resolve, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { paths, dataRoot } from '../server/paths.mjs';
+import { ADAPTERS } from '../server/adapters.mjs';
+
+const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
+const repo = resolve(process.argv.slice(2).find((a) => !a.startsWith('--')) || process.cwd());
+const PORT = Number(process.env.NEARLY_PORT || 47653);
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+
+const blockers = [];
+function say(ok, label, detail, fix) {
+  const mark = ok === true ? green('✓') : ok === false ? red('✗') : yellow('!');
+  console.log(`  ${mark} ${label}${detail ? dim(`  ${detail}`) : ''}`);
+  if (ok === false && fix) blockers.push(fix);
+}
+
+const git = (args) => {
+  try { return execFileSync('git', args, { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  catch { return null; }
+};
+
+console.log('');
+console.log(`  ${bold('Nearly')} ${dim(repo)}`);
+console.log('');
+
+// 1 — a repo at all
+const branch = git(['rev-parse', '--abbrev-ref', 'HEAD']);
+if (!existsSync(join(repo, '.git'))) {
+  say(false, 'a git repository', 'this is not one', `cd into the repo you work in, then run nearly`);
+} else {
+  say(true, 'a git repository', `on ${branch}`);
+}
+
+// 2 — which agents are gated here. An agent Nearly cannot see records nothing,
+// and that is the single most common reason for an empty pull request.
+const gated = ADAPTERS.filter((a) => {
+  const f = join(repo, a.config);
+  try { return existsSync(f) && /nearly/i.test(readFileSync(f, 'utf8')); } catch { return false; }
+});
+if (gated.length) say(true, 'agents gated here', gated.map((a) => a.name).join(', '));
+else say(false, 'agents gated here', 'none', 'run `nearly` in this repo to turn it on');
+
+// 3 — the server, and whether it is this build
+let health = null;
+try {
+  const r = await fetch(`http://127.0.0.1:${PORT}/health`, { signal: AbortSignal.timeout(900) });
+  if (r.ok) health = await r.json();
+} catch { /* not running is normal: hooks start it */ }
+if (!health) {
+  say(null, 'server', 'not running — a hook starts it when one fires');
+} else {
+  let mine = root;
+  try { mine = realpathSync(root); } catch { /* compare literally */ }
+  const same = health.root === mine;
+  say(same ? true : false, 'server', same ? `v${health.version}` : `a different install is answering: ${health.root || 'an older build'}`,
+    'run `nearly` here — it closes an older server that is holding the port');
+}
+
+// 4 — recordings for this branch, matched the way the record builder matches
+// them, so this cannot disagree with it.
+const recDir = paths.recordings();
+let runs = 0, otherBranches = new Set();
+const real = (p) => { try { return realpathSync(resolve(p)); } catch { return resolve(p); } };
+try {
+  for (const f of readdirSync(recDir).filter((f) => f.endsWith('.jsonl'))) {
+    let created = null;
+    for (const line of readFileSync(join(recDir, f), 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      try {
+        const e = JSON.parse(line);
+        if (e.type === 'session' && e.subtype === 'created') { created = e; break; }
+      } catch { /* a torn line */ }
+    }
+    if (!created) continue;
+    if (created.worktree && real(created.worktree) !== real(repo)) continue;
+    if (created.branch === branch) runs += 1;
+    else if (created.branch) otherBranches.add(created.branch);
+  }
+} catch { /* no recordings directory yet */ }
+
+if (runs) {
+  say(true, `sessions recorded on ${branch}`, `${runs}`);
+} else {
+  say(false, `sessions recorded on ${branch}`, 'none',
+    otherBranches.size
+      ? `this branch has no recorded sessions. Others do: ${[...otherBranches].join(', ')}. A record only exists for work an agent Nearly gates actually did.`
+      : `nothing here has been recorded yet. Nearly only sees the agents it gates — run \`nearly agents\` to see which those are.`);
+}
+
+// 5 — the hook that offers the record at push time
+const pushHook = join(repo, '.git', 'hooks', 'pre-push');
+const hasPush = existsSync(pushHook) && /x-session-record-hook|nearly/i.test((() => {
+  try { return readFileSync(pushHook, 'utf8'); } catch { return ''; }
+})());
+say(hasPush, 'pre-push hook', hasPush ? 'installed' : 'missing', 'run `nearly` here to install it');
+
+// 6 — gh, which is how a pull request is found and commented on. Its absence
+// used to be reported as "no pull request yet", which sent people off to raise
+// one they already had.
+const ghOk = spawnSync('gh', ['--version'], { encoding: 'utf8' }).status === 0;
+if (!ghOk) {
+  say(false, 'GitHub CLI (gh)', 'not on PATH',
+    'install it from cli.github.com and run `gh auth login` — without it the record cannot be posted to a pull request');
+} else {
+  const auth = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8' }).status === 0;
+  say(auth, 'GitHub CLI (gh)', auth ? 'installed and signed in' : 'installed but not signed in', 'run `gh auth login`');
+  if (auth) {
+    const pr = spawnSync('gh', ['pr', 'view', '--json', 'number,url'], { cwd: repo, encoding: 'utf8' });
+    if (pr.status === 0) {
+      let url = '';
+      try { url = JSON.parse(pr.stdout).url; } catch { /* keep it blank */ }
+      say(true, 'open pull request', url);
+    } else {
+      say(null, 'open pull request', `none for ${branch} — raise one, then push again`);
+    }
+  }
+}
+
+// 7 — where a posted record would point
+const urlBase = (() => {
+  if (process.env.NEARLY_URL_BASE) return process.env.NEARLY_URL_BASE;
+  for (const f of [paths.config(), join(root, '.nearly.json')]) {
+    try { if (existsSync(f)) { const u = JSON.parse(readFileSync(f, 'utf8')).urlBase; if (u) return u; } }
+    catch { /* try the next */ }
+  }
+  return null;
+})();
+say(urlBase ? true : null, 'somewhere to publish records',
+  urlBase || `kept in ${dataRoot.replace(process.env.HOME || '~', '~')}, so a comment would have no link to give`);
+
+// 8 — whether a record for this branch exists right now
+const slug = `${String(basename(repo)).replace(/[^a-z0-9._-]+/gi, '-').toLowerCase()}--${String(branch).replace(/[^a-z0-9._-]+/gi, '-').toLowerCase()}`;
+const built = join(paths.records(), `${slug}.json`);
+say(existsSync(built) ? true : null, 'record built for this branch',
+  existsSync(built) ? built : 'not yet — it is built at push time, or by `nearly record`');
+
+console.log('');
+if (!blockers.length) {
+  console.log(`  ${green('Nothing is in the way.')} ${dim('Work, push, and the record is offered.')}`);
+} else {
+  console.log(`  ${bold(blockers.length === 1 ? 'One thing is in the way:' : `${blockers.length} things are in the way:`)}`);
+  for (const b of blockers) console.log(`    · ${b}`);
+}
+console.log('');

package/scripts/hook.mjs

@@ -25,6 +25,7 @@
 import { spawn } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
 import { byId } from '../server/adapters.mjs';
 
 const HOST = '127.0.0.1';
@@ -49,11 +50,21 @@ const body = await new Promise((r) => {
   process.stdin.on('error', () => r(''));
 });
 
+const realRoot = (() => { try { return realpathSync(root); } catch { return root; } })();
+
+// Is the thing on this port *us*?
+//
+// A hook starts the server and the server outlives the run. So after an upgrade
+// — or after a one-off `npx nearly-cli` — the old build keeps the port and keeps
+// answering, from a directory that may not exist any more. Its record pages 404
+// and every fix since is invisible, with nothing anywhere saying why.
 async function up(ms = 400) {
   try {
-    const c = AbortSignal.timeout(ms);
-    const r = await fetch(`${BASE}/health`, { signal: c });
-    return r.ok;
+    const r = await fetch(`${BASE}/health`, { signal: AbortSignal.timeout(ms) });
+    if (!r.ok) return false;
+    const h = await r.json().catch(() => ({}));
+    if (h.root !== realRoot) return 'stale';   // no root at all means older than this check
+    return true;
   } catch { return false; }
 }
 
@@ -70,7 +81,19 @@ async function start() {
   return false;
 }
 
-if (!(await up()) && !(await start())) process.exit(0);   // fail open, silently
+let health = await up();
+if (health === 'stale') {
+  // Take the port back rather than run whatever is already there. Nobody reads
+  // a hook's output, so this has to happen without being asked — otherwise the
+  // only people who ever get the fix are the ones who happen to re-run `nearly`
+  // and read the message.
+  const { reclaim } = await import('../server/reclaim.mjs');
+  const { outcome } = await reclaim({ port: PORT, base: BASE, root: realRoot });
+  // 'busy' and 'stuck' both mean it is still there. Talking to an old server
+  // still gates the call, which is better than not gating it.
+  health = (outcome === 'stood-down' || outcome === 'ended' || outcome === 'free') ? false : true;
+}
+if (!health && !(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

package/scripts/push-record.mjs

@@ -94,11 +94,24 @@ try {
   applyUpdate(await checkForUpdate());
 } catch { /* never worth failing a push over */ }
 
-// gh is only useful if there is a pull request to comment on
+// Finding the pull request needs gh. Not having it and not having a pull
+// request are different problems with the same silence, and they were reported
+// as the same sentence — which sent people off to raise a pull request they
+// were already looking at.
 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.'));
+if (!hasGh) {
+  console.log(dim('  The record is built, but posting it to a pull request needs the GitHub CLI,'));
+  console.log(dim('  and `gh` is not on PATH. Install it from cli.github.com, then `gh auth login`.'));
+  console.log(dim('  `nearly doctor` checks the whole chain.'));
+  console.log('');
+  process.exit(0);
+}
+const pr = spawnSync('gh', ['pr', 'view', '--json', 'number,url'], { cwd: repo, encoding: 'utf8' });
+if (pr.status !== 0) {
+  const why = /not logged|authentication|gh auth/i.test(pr.stderr || '')
+    ? 'gh is installed but not signed in. Run `gh auth login`, then push again.'
+    : 'No open pull request for this branch yet. Raise one, then push again to attach the record.';
+  console.log(dim(`  ${why}`));
   console.log('');
   process.exit(0);
 }

package/server/adapters.mjs

@@ -342,12 +342,17 @@ export const ADAPTERS = [
   // -------------------------------------------------------------------------
   {
     id: 'copilot',
-    name: 'GitHub Copilot CLI',
+    name: 'GitHub Copilot',
     verified: null,
     config: '.github/hooks/nearly.json',
-    // Copilot accepts PascalCase event names as a Claude Code compatibility
-    // mode, and in that mode it sends snake_case fields and Claude's own tool
-    // names. So this adapter is mostly a different file path.
+    // Both the CLI and VS Code's agent mode, which loads every .json in
+    // .github/hooks/ with no further setup. Copilot accepts PascalCase event
+    // names as a Claude Code compatibility mode, and in that mode it sends
+    // snake_case fields and Claude's own tool names, so this adapter is mostly
+    // a different file path.
+    //
+    // It also fails closed where Claude Code fails open: a crash or a non-zero
+    // exit in a preToolUse hook denies the call rather than waving it through.
     events: {
       SessionStart: 'session-start', UserPromptSubmit: 'prompt', PreToolUse: 'pre-tool',
       PostToolUse: 'post-tool', Stop: 'stop', SessionEnd: 'session-end',
@@ -356,7 +361,12 @@ export const ADAPTERS = [
       const file = join(repo, '.github', 'hooks', 'nearly.json');
       const cfg = { version: 1, hooks: {} };
       for (const [their, ours] of Object.entries(this.events)) {
-        cfg.hooks[their] = [{ type: 'command', command: cmdFor(ours), timeoutSec: holdFor(ours) }];
+        const run = cmdFor(ours);
+        // `command` is the cross-platform fallback; `bash` and `powershell` are
+        // what the runtime picks per OS. Writing all three means a Windows
+        // machine finds one whichever property it prefers — and Windows is
+        // exactly where somebody with no other option is running this.
+        cfg.hooks[their] = [{ type: 'command', command: run, bash: run, powershell: run, timeoutSec: holdFor(ours) }];
       }
       writeJson(file, cfg);        // our own file; nobody else's entries to keep
       return { file };

package/server/index.mjs

@@ -20,6 +20,19 @@ const WORKTREES = path.join(paths.workspace(), '.worktrees');
 const RECORDINGS = paths.recordings();
 const UI = path.join(ROOT, 'ui', 'index.html');
 const MAX_SESSIONS = 3;                 // 8 GB machine
+// Which build is actually answering on this port. A server started by a hook
+// outlives the run that started it, so after an upgrade the old one keeps the
+// port and keeps serving its own code — and every fix stays invisible. Say who
+// we are so the launcher can tell.
+const VERSION = (() => {
+  try { return JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version; }
+  catch { return '0.0.0'; }
+})();
+// Idle since the last request. A server nobody is using should not hold a port
+// for the rest of the week, least of all one running from a cache directory
+// that npm may already have deleted.
+const IDLE_EXIT_MS = Number(process.env.NEARLY_IDLE_EXIT_MS || 30 * 60_000);
+let lastSeen = Date.now();
 const ASK_TIMEOUT_MS = Number(process.env.NEARLY_ASK_TIMEOUT_MS || 120_000);         // UI must answer before this; then we fail CLOSED (deny)
 const HOOK_TIMEOUT_S = 180;             // Claude Code's own hook timeout; must be > ASK_TIMEOUT
 const MODEL = 'sonnet';
@@ -358,7 +371,10 @@ function readBody(req) {
   return new Promise((resolve) => { let b = ''; req.on('data', (c) => (b += c)); req.on('end', () => resolve(b)); });
 }
 
+const realRoot = (() => { try { return fs.realpathSync(ROOT); } catch { return ROOT; } })();
+
 const server = http.createServer(async (req, res) => {
+  lastSeen = Date.now();
   const url = new URL(req.url, `http://${HOST}:${PORT}`);
   const sidParam = url.searchParams.get('s');
 
@@ -470,18 +486,40 @@ const server = http.createServer(async (req, res) => {
 
   // ---- UI API ----
   // Cheap liveness check: the hook launcher calls this before every tool call.
-  if (req.method === 'GET' && url.pathname === '/health') return json(res, 200, { ok: true, sessions: sessions.size });
+  if (req.method === 'GET' && url.pathname === '/health') {
+    return json(res, 200, { ok: true, sessions: sessions.size, version: VERSION, root: realRoot });
+  }
+  // Stand down so a newer build can take the port. Refused while anybody is
+  // waiting on a decision: dropping a held request would hand it back to the
+  // agent's own prompt, which is the one outcome this whole project exists to
+  // avoid.
+  if (req.method === 'POST' && url.pathname === '/exit') {
+    const waiting = [...sessions.values()].reduce((n, s) => n + s.pending.size, 0);
+    if (waiting) return json(res, 409, { ok: false, waiting });
+    json(res, 200, { ok: true, version: VERSION });
+    setTimeout(() => process.exit(0), 50);
+    return;
+  }
   if (req.method === 'GET' && url.pathname === '/') {
     res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
     return res.end(fs.readFileSync(UI));
   }
-  // Static: built recaps and the replay out of ui/, plus a local preview of the
-  // docs/ folder that GitHub Pages will serve, so you can check it before pushing.
+  // Static: built records, the replay page, and a local preview of the docs/
+  // folder GitHub Pages serves, so you can check it before pushing.
+  //
+  // Each of these has to be asked for by name rather than resolved against the
+  // package. Records used to live in ui/records/ and moved to the user's own
+  // directory when it turned out an upgrade was deleting them — but this route
+  // kept serving out of the package, so from an npm install every record 404'd
+  // while sitting perfectly well on disk. It only ever worked from a checkout,
+  // which is the one place nobody would notice.
   if (req.method === 'GET' && (url.pathname.startsWith('/records/') || url.pathname === '/replay.html' || url.pathname === '/docs' || url.pathname.startsWith('/docs/'))) {
-    const docs = url.pathname === '/docs' || url.pathname.startsWith('/docs/');
-    const base = path.join(ROOT, docs ? 'docs' : 'ui');
-    let rel = url.pathname.slice(1).split('/').filter((p) => p && p !== '..').join('/');
-    if (docs) rel = rel.replace(/^docs\/?/, '') || 'index.html';
+    const isDocs = url.pathname === '/docs' || url.pathname.startsWith('/docs/');
+    const isRecord = url.pathname.startsWith('/records/');
+    const base = isRecord ? paths.pages() : isDocs ? paths.docs() : path.join(ROOT, 'ui');
+    const strip = isRecord ? '/records/' : isDocs ? '/docs' : '/';
+    let rel = url.pathname.slice(strip.length).split('/').filter((p) => p && p !== '..').join('/');
+    if (isDocs) rel = rel || 'index.html';
     const file = path.join(base, rel);
     if (!file.startsWith(base) || !fs.existsSync(file) || !fs.statSync(file).isFile()) return json(res, 404, { error: 'not found' });
     res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
@@ -582,6 +620,15 @@ server.on('error', (e) => {
   process.exit(1);
 });
 
+// Nothing to remember to shut down. A server with no sessions that nobody has
+// asked anything of for half an hour has no reason to still be holding a port.
+if (IDLE_EXIT_MS > 0) {
+  const idle = setInterval(() => {
+    if (sessions.size === 0 && Date.now() - lastSeen > IDLE_EXIT_MS) process.exit(0);
+  }, 60_000);
+  idle.unref();
+}
+
 server.listen(PORT, HOST, () => {
   console.log(`nearly  http://${HOST}:${PORT}`);
   console.log(`worktrees     ${WORKTREES}`);

package/server/reclaim.mjs

@@ -0,0 +1,104 @@
+// Take the port back from a Nearly server that is not this one.
+//
+// The server outlives the run that starts it. So a single `npx nearly-cli`, or
+// any upgrade, leaves the previous build holding 47653 — still answering, from a
+// directory npm has since replaced. Its record pages 404, and worse, every fix
+// shipped after it never runs. Nothing anywhere says why.
+//
+// Builds from 0.1.8 stand down when asked. Everything already installed does
+// not, and that is most people. Telling them to run taskkill is not a fix; it
+// is a fix for whoever reads the message. So when an older build is idle, we
+// end it ourselves.
+//
+// The rule that makes that defensible: never kill anything until it has proved,
+// twice, that it is one of ours, and never kill one that anybody is using.
+
+import { execFileSync } from 'node:child_process';
+
+const isWin = process.platform === 'win32';
+
+async function get(base, path, ms = 700) {
+  try {
+    const r = await fetch(base + path, { signal: AbortSignal.timeout(ms) });
+    if (!r.ok) return null;
+    return await r.json();
+  } catch { return null; }
+}
+
+// Two independent shapes only this server produces. /health alone is a couple of
+// generic fields that anything could return by chance; /state carries the
+// consent gradient itself — the tier table, the learned rules, the deadline. A
+// process answering both is ours, whatever version wrote it.
+export async function identify(base) {
+  const health = await get(base, '/health');
+  if (!health || health.ok !== true || typeof health.sessions !== 'number') return null;
+  const state = await get(base, '/state');
+  if (!state || !state.defaults || !Array.isArray(state.sessions)) return null;
+  if (typeof state.defaults.Bash !== 'string' || typeof state.askTimeoutMs !== 'number') return null;
+  return {
+    version: health.version || null,           // absent before 0.1.8
+    root: health.root || null,                 // absent before 0.1.8
+    sessions: health.sessions,
+    // Anything actually being decided right now. Killing over one of these
+    // would drop a held request back to the agent's own prompt.
+    waiting: state.sessions.reduce((n, s) => n + (s.pending?.length || 0), 0),
+  };
+}
+
+function pidsOnPort(port) {
+  try {
+    if (isWin) {
+      const out = execFileSync('netstat', ['-ano', '-p', 'TCP'], { encoding: 'utf8', timeout: 5000 });
+      return [...new Set(out.split(/\r?\n/)
+        .filter((l) => /LISTENING/i.test(l) && new RegExp(`[:.]${port}\\s`).test(l))
+        .map((l) => Number(l.trim().split(/\s+/).pop()))
+        .filter((n) => Number.isInteger(n) && n > 0))];
+    }
+    const out = execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t'],
+      { encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+    return [...new Set(out.split(/\s+/).map(Number).filter((n) => Number.isInteger(n) && n > 0))];
+  } catch { return []; }         // lsof or netstat missing, or nothing listening
+}
+
+const freed = async (base) => (await identify(base)) === null;
+
+// Returns what happened, for a caller that wants to say so out loud.
+//
+//   'ours'      the server on this port is this build
+//   'free'      nothing is listening
+//   'busy'      someone else's, but a person is mid-decision — left alone
+//   'stood-down'  it exited when asked (0.1.8 and later)
+//   'ended'     older build, idle, so we closed it
+//   'stuck'     ours by every test, but we could not end it
+export async function reclaim({ port, base, root, kill = process.kill.bind(process) }) {
+  const who = await identify(base);
+  if (!who) return { outcome: 'free' };
+  if (who.root && who.root === root) return { outcome: 'ours', who };
+  if (who.waiting > 0) return { outcome: 'busy', who };
+
+  // The polite path. A build that understands this will refuse if it is busy.
+  try {
+    const r = await fetch(`${base}/exit`, { method: 'POST', signal: AbortSignal.timeout(2000) });
+    if (r.status === 409) return { outcome: 'busy', who };
+    if (r.ok) {
+      for (let i = 0; i < 20; i++) {
+        await new Promise((s) => setTimeout(s, 100));
+        if (await freed(base)) return { outcome: 'stood-down', who };
+      }
+    }
+  } catch { /* older build: no such endpoint */ }
+
+  // Older build. It has already answered as ours on two endpoints and has no
+  // sessions, so ending it costs nobody anything and is the only way its
+  // replacement ever gets to run.
+  if (who.sessions > 0) return { outcome: 'busy', who };
+  for (const pid of pidsOnPort(port)) {
+    if (pid === process.pid) continue;
+    try { kill(pid, 'SIGTERM'); } catch { /* gone, or not ours to signal */ }
+  }
+  for (let i = 0; i < 25; i++) {
+    await new Promise((s) => setTimeout(s, 100));
+    if (await freed(base)) return { outcome: 'ended', who };
+  }
+  return { outcome: 'stuck', who };
+}