nearly-cli 0.1.6 → 0.1.8

package/README.md

@@ -61,11 +61,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 +118,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.
@@ -210,6 +220,11 @@ Every tool call passes through an HTTP `PreToolUse` hook to this server, which s
 
 "Allow always" and "Never" turn a decision into a rule for the rest of the run, keyed by tool and first word of the command, or file extension for edits. In lab mode every turn is committed in the agent's worktree by the `Stop` hook, so **Undo turn** is a `git reset --hard HEAD~1`.
 
+Lab mode is off by default. `nearly open` shows your own sessions and what
+needs you — the gate, which is what you installed this for. `nearly lab` adds
+the panel for starting agents from the dashboard, which is a different job and
+no longer the first thing a new user is asked about.
+
 Agents in lab mode are real Claude Code sessions (`claude -p`) on your Claude
 subscription, each on its own branch in its own git worktree. You pick which
 repo to branch from — the dashboard offers the ones you have turned Nearly on
@@ -312,6 +327,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.
@@ -368,6 +413,6 @@ The claim this project makes is testable: a reviewer who sees the session record
 - `scripts/build-recap.mjs` + `ui/recap.template.html`, narrated recap page per session
 - `scripts/publish-pages.mjs`, build the `docs/` folder GitHub Pages serves
 - `scripts/install-push-hook.mjs` + `scripts/push-record.mjs`, hand the branch record over at `git push`
-- `~/.nearly/`, where recordings, records and agent worktrees are kept
+- `~/.nearly/`, where recordings, records, settings and agent worktrees are kept — outside the package, so an upgrade cannot destroy them
 - `recordings/<session>.jsonl`, every event and decision; `recordings/demo/` is committed so the records can be rebuilt from source
 - `STUDY.md`, the protocol for testing whether any of this helps a reviewer

package/bin/nearly.mjs

@@ -4,6 +4,7 @@
 //   nearly              turn it on for the repo you are in
 //   nearly off          turn it off again
 //   nearly open         open the dashboard
+//   nearly lab          open it with the panel for starting agents
 //   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
@@ -86,8 +87,10 @@ switch (cmd) {
     return run(join(root, 'server', 'index.mjs'), rest);
   }
 
-  case 'open': {
-    const url = 'http://127.0.0.1:47653';
+  case 'lab': case 'open': {
+    // `open` is the gate: your sessions and what needs you. `lab` adds the
+    // panel for starting agents from here, which is a different job.
+    const url = 'http://127.0.0.1:47653' + (cmd === 'lab' ? '/?lab=1' : '');
     spawn(process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open',
       [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
     console.log(url);
@@ -99,6 +102,7 @@ switch (cmd) {
   nearly              turn it on for the repo you are in
   nearly off          turn it off again
   nearly open         open the dashboard
+  nearly lab          open it with the panel for starting agents
   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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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.
@@ -160,6 +160,11 @@ for (const a of chosen) {
 // by simply turning Nearly on again.
 try {
   const f = paths.repos();
+  // On a machine that has never run Nearly, ~/.nearly does not exist yet and
+  // this write fails with ENOENT. It used to fail into a bare catch, so the
+  // list was silently never created and the dashboard could never offer a repo
+  // — invisible on every machine except a genuinely fresh one.
+  mkdirSync(dirname(f), { recursive: true });
   let list = [];
   try { list = JSON.parse(readFileSync(f, 'utf8')); } catch { /* first one */ }
   // Prune as we go: a repo that has been moved or deleted is noise in a list
@@ -167,7 +172,31 @@ try {
   list = list.filter((r) => r !== repo && existsSync(join(r, '.git')));
   if (!off) list.unshift(repo);
   writeFileSync(f, JSON.stringify(list.slice(0, 50), null, 2) + '\n');
-} catch { /* the dashboard still works without it */ }
+} catch (e) {
+  // Not fatal — the gate does not depend on it — but not silent either.
+  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
@@ -199,20 +228,26 @@ function pagesUrl() {
 // An address already configured wins: it was either set deliberately or worked
 // out here before, and it survives the project being renamed.
 function configured() {
-  try {
-    const f = join(root, '.nearly.json');
-    if (existsSync(f)) return JSON.parse(readFileSync(f, 'utf8')).urlBase || null;
-  } catch { /* fall through */ }
+  // The legacy path is read, never written: an upgrade destroys it, so the
+  // first run after this change is the last chance to carry it forward.
+  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 one */ }
+  }
   return null;
 }
 const derived = pagesUrl();
 const base = process.env.NEARLY_URL_BASE || configured() || derived;
 if (base && !off) {
   try {
-    const cfg = join(root, '.nearly.json');
+    const cfg = paths.config();
     const prev = existsSync(cfg) ? JSON.parse(readFileSync(cfg, 'utf8')) : {};
     writeFileSync(cfg, JSON.stringify({ ...prev, urlBase: base }, null, 2) + '\n');
-  } catch { /* the env var still works */ }
+  } catch (e) { notes.push(`could not save where records publish: ${e.message}`); }
 }
 
 // ---------------------------------------------------------------------------
@@ -246,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/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
@@ -87,7 +110,8 @@ if (adapter && adapter.normalize) {
 }
 
 try {
-  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}`, {
+  const hold = adapter?.holdMs ? `&hold=${adapter.holdMs}` : '';
+  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}${hold}`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: payload,

package/scripts/push-record.mjs

@@ -15,10 +15,14 @@ import { paths } from '../server/paths.mjs';
 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 */ }
+  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 one */ }
+  }
   return '';
 }
 const URL_BASE = (process.env.NEARLY_URL_BASE || configured() || '').replace(/\/$/, '');

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 };
@@ -534,6 +544,13 @@ export const ADAPTERS = [
     name: 'Windsurf',
     verified: null,
     config: '.windsurf/hooks.json',
+    // Windsurf is the only harness with no way to say how long a hook may take,
+    // and an abandoned pre-hook does not block — Cascade treats anything but
+    // exit 2 as "proceed". So a request held past whatever Cascade's own limit
+    // is would be allowed, by Cascade, silently. Decide well inside any
+    // plausible limit instead: a deny we issue is recorded and explains itself,
+    // where a timeout we lose is an allow nobody chose.
+    holdMs: 20_000,
     // The odd one out twice over. Windsurf has no JSON answer at all — a pre
     // hook blocks by exiting 2 with the reason on stderr — and it has no single
     // pre-tool event, so the gate is spread across three.

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';
@@ -67,7 +80,7 @@ function summary(s) {
   };
 }
 function pendingView(p) {
-  return { id: p.id, session: p.sid, tool: p.tool, input: p.input, tier: p.tier, reason: p.reason, key: p.key, at: p.at };
+  return { id: p.id, session: p.sid, tool: p.tool, input: p.input, tier: p.tier, reason: p.reason, key: p.key, at: p.at, holdMs: p.holdMs };
 }
 
 function hooksSettings(sid) {
@@ -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');
 
@@ -419,8 +435,14 @@ const server = http.createServer(async (req, res) => {
       if (tier === 'never') { record(sid, { type: 'decision', id, decision: 'deny', why: reason, scope: 'policy', tool: shown, input: hook.tool_input, tier }); return respond('deny', `never (${reason})`); }
       if (tier === 'log') { record(sid, { type: 'decision', id, decision: 'allow', why: reason, scope: 'policy', tool: shown, input: hook.tool_input, tier }); return respond('allow', `do and log (${reason})`); }
       // ask: hold the response until the UI decides, or fail closed
-      const item = { id, sid, tool: shown, input: hook.tool_input, tier, reason, key: ruleKey(hook), at: Date.now(), respond };
-      item.timer = setTimeout(() => decide(sid, id, 'deny', 'no human answer; nearly fails closed'), ASK_TIMEOUT_MS);
+      // A harness may say it will not wait as long as we would. It can shorten
+      // the deadline, never lengthen it: the point of the cap is that nobody
+      // else gets to decide by not answering.
+      const asked = Number(url.searchParams.get('hold')) || 0;
+      const holdMs = asked > 0 ? Math.min(asked, ASK_TIMEOUT_MS) : ASK_TIMEOUT_MS;
+      const item = { id, sid, tool: shown, input: hook.tool_input, tier, reason, key: ruleKey(hook), at: Date.now(), holdMs, respond };
+      item.timer = setTimeout(() => decide(sid, id, 'deny',
+        `no human answer in ${Math.round(holdMs / 1000)}s; nearly fails closed`), holdMs);
       s.pending.set(id, item);
       s.state = 'waiting';
       record(sid, { type: 'ask', ...pendingView(item) });
@@ -464,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' });
@@ -576,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/paths.mjs

@@ -24,6 +24,15 @@ export const dataRoot = fromCheckout
   ? pkgRoot
   : join(process.env.NEARLY_HOME || join(homedir(), '.nearly'));
 
+// A file, with its directory guaranteed to exist — including when the path came
+// from an environment variable, which is where this went wrong the first time:
+// the default path was fixed and the override was left to fail on its own.
+function dataFile(envVar, name) {
+  const f = process.env[envVar] || join(dataRoot, name);
+  try { mkdirSync(dirname(f), { recursive: true }); } catch { /* caller will report */ }
+  return f;
+}
+
 export function dataDir(...parts) {
   const p = join(dataRoot, ...parts);
   try { mkdirSync(p, { recursive: true }); } catch { /* caller will report */ }
@@ -44,5 +53,11 @@ export const paths = {
   // you work in before any session has run in it — otherwise the only repos it
   // can offer are ones that are already going, which is no help when you are
   // trying to start the first one.
-  repos: () => process.env.NEARLY_REPOS || join(dataRoot, 'repos.json'),
+  repos: () => dataFile('NEARLY_REPOS', 'repos.json'),
+  // Where records are published, so a pull-request comment can link them. This
+  // lived in the package directory, which `npm install -g` replaces wholesale:
+  // the address was quietly lost on every upgrade and the next record went out
+  // with no link. Same lesson as recordings — anything a person configured
+  // belongs in their space, not in ours.
+  config: () => dataFile('NEARLY_CONFIG', 'config.json'),
 };

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 };
+}

package/ui/index.html

@@ -121,6 +121,7 @@
 
   /* ---------- fleet ---------- */
   .new { margin: 0 12px 14px; display: grid; gap: 7px; }
+  .new[hidden] { display: none; }
   .formErr { margin: 0; font-size: 12px; line-height: 1.45; color: var(--deny); }
   .fleet { padding: 0 12px 18px; display: grid; gap: 8px; }
   .agent {
@@ -239,7 +240,7 @@
 <main>
   <div class="col">
     <div class="col-h"><span class="lbl">Agents</span><span class="count" id="fleetCount">0</span></div>
-    <form class="new" id="newForm">
+    <form class="new" id="newForm" hidden>
       <input name="name" placeholder="Name, e.g. docs" required autocomplete="off">
       <input name="repo" id="repoField" placeholder="Repo to branch from" list="repoList" autocomplete="off">
       <datalist id="repoList"></datalist>
@@ -264,6 +265,10 @@
 </main>
 
 <script>
+  // Lab mode — starting agents from the dashboard — is a different job from
+  // watching your own sessions be gated. It is the demo, not the product, so it
+  // is off unless asked for.
+  const LAB = new URLSearchParams(location.search).has('lab');
   const S = { sessions: new Map(), rules: {}, defaults: {}, askTimeoutMs: 120000 };
   const $ = (id) => document.getElementById(id);
   const fmtT = (ms) => new Date(ms).toLocaleTimeString([], { hour12: false });
@@ -317,7 +322,19 @@
         </div>`;
       el.appendChild(d);
     }
-    if (!S.sessions.size) el.innerHTML = '<div class="empty">No agents yet. Start one above and it runs on your Claude subscription, in its own git worktree.</div>';
+    if (!S.sessions.size) {
+      // What a person who just installed this is actually waiting for is their
+      // own next session, not a button. Saying otherwise taught the wrong
+      // product on the first screen anybody sees.
+      el.innerHTML = LAB
+        ? '<div class="empty">No agents yet. Start one above and it runs on your Claude subscription, on its own branch.</div>'
+        : `<div class="empty"><b>No sessions yet.</b>
+             Work as you normally would. Every session you run in a repo you have turned
+             Nearly on for appears here, and anything that needs you shows up alongside.
+             <div class="keys"><span><kbd>nearly agents</kbd><span>what is gated in a repo</span></span>
+             <span><kbd>nearly lab</kbd><span>start an agent from here instead</span></span></div>
+           </div>`;
+    }
   }
 
   function renderAsks() {
@@ -353,7 +370,7 @@
           <span class="tool">${esc(p.tool)}</span>
           <span class="who">${esc(p.sname)}</span>
           <span class="tag" title="Always and Never attach to this key">${esc(p.key || p.tool)}</span>
-          <span class="clock" data-wait="${p.at}"></span>
+          <span class="clock" data-wait="${p.at}" data-limit="${p.holdMs || ''}"></span>
         </div>
         <pre>${esc(prettyInput(p.tool, p.input))}</pre>
         <div class="blast"><span class="ic">▲</span><span>${blast(p.tool)}</span></div>
@@ -363,7 +380,7 @@
           <button data-v="deny" data-decide="deny" data-scope="once">Deny<kbd>D</kbd></button>
           <button data-v="deny" data-decide="deny" data-scope="always" title="Never allow ${esc(p.key || p.tool)} again this run">Never<kbd>⇧D</kbd></button>
         </div>
-        <div class="deadline" data-wait-bar="${p.at}">
+        <div class="deadline" data-wait-bar="${p.at}" data-limit="${p.holdMs || ''}">
           <div class="bar"><i></i></div>
           <div class="cap"></div>
         </div>
@@ -455,6 +472,8 @@
   }
   connect();
 
+  if (LAB) $('newForm').hidden = false;
+
   $('newForm').onsubmit = async (e) => {
     e.preventDefault();
     const f = new FormData(e.target);
@@ -518,13 +537,17 @@
 
   // One ticker for every countdown on the page.
   function tickWaits() {
-    const limit = S.askTimeoutMs;
+    // Each request carries its own deadline: some harnesses will not wait as
+    // long as the rest, and a bar that drains at the wrong rate is worse than
+    // no bar.
     document.querySelectorAll('[data-wait]').forEach((el) => {
+      const limit = +el.dataset.limit || S.askTimeoutMs;
       const held = Date.now() - +el.dataset.wait;
       el.textContent = `held ${Math.round(held / 1000)}s`;
       el.dataset.urgent = held > limit * 0.75 ? '2' : held > limit * 0.4 ? '1' : '0';
     });
     document.querySelectorAll('[data-wait-bar]').forEach((el) => {
+      const limit = +el.dataset.limit || S.askTimeoutMs;
       const held = Date.now() - +el.dataset.waitBar;
       const left = Math.max(0, limit - held);
       const frac = Math.max(0, Math.min(1, left / limit));