nearly-cli 0.1.7 → 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.
@@ -317,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.7",
+  "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.
@@ -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/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/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 };
+}