nearly-cli 0.1.11 → 0.1.16

package/scripts/doctor.mjs

@@ -16,17 +16,19 @@ 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';
+import { ADAPTERS, OURS_RE } 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`;
+// Colour only on a terminal; piped into a file or a CI log it is noise.
+const COLOR = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s) => (COLOR ? `\x1b[2m${s}\x1b[0m` : String(s));
+const bold = (s) => (COLOR ? `\x1b[1m${s}\x1b[0m` : String(s));
+const green = (s) => (COLOR ? `\x1b[32m${s}\x1b[0m` : String(s));
+const red = (s) => (COLOR ? `\x1b[31m${s}\x1b[0m` : String(s));
+const yellow = (s) => (COLOR ? `\x1b[33m${s}\x1b[0m` : String(s));
 
 const blockers = [];
 function say(ok, label, detail, fix) {
@@ -45,7 +47,8 @@ console.log(`  ${bold('Nearly')} ${dim(repo)}`);
 console.log('');
 
 // 1 — a repo at all
-const branch = git(['rev-parse', '--abbrev-ref', 'HEAD']);
+// A repo with no commits has no HEAD to name, but it does have a branch.
+const branch = git(['symbolic-ref', '--short', 'HEAD']) || git(['rev-parse', '--abbrev-ref', 'HEAD']) || '(no branch)';
 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 {
@@ -56,11 +59,69 @@ if (!existsSync(join(repo, '.git'))) {
 // 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; }
+  try { return existsSync(f) && OURS_RE.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');
 
+// Configured is not the same as working, and the difference is invisible.
+// Hooks fail open on purpose — a broken one must never wedge an agent — so a
+// command that cannot be found produces silence, and silence looks exactly like
+// a session nobody ran. Everything above can be green while nothing is gated.
+//
+// So run the hook this repo actually has, the way the agent runs it, and see
+// whether an answer comes back.
+if (gated.length) {
+  const cc = gated.find((a) => a.id === 'claude-code') || gated[0];
+  let cmd = null;
+  try {
+    const cfg = JSON.parse(readFileSync(join(repo, cc.config), 'utf8'));
+    const walk = (o) => {
+      if (!o || typeof o !== 'object') return;
+      if (typeof o.command === 'string' && OURS_RE.test(o.command) && /pre-tool/.test(o.command)) cmd = o.command;
+      for (const v of Object.values(o)) walk(v);
+    };
+    walk(cfg);
+  } catch { /* unreadable config */ }
+
+  if (!cmd) {
+    say(null, 'hooks actually fire', 'could not find the pre-tool hook to try');
+  } else {
+    const probe = JSON.stringify({
+      session_id: `nearly-doctor-${Date.now()}`, cwd: repo,
+      hook_event_name: 'PreToolUse', tool_name: 'Read',
+      tool_input: { file_path: join(repo, 'nearly-doctor-probe') }, tool_use_id: 'doctor',
+    });
+    // shell: true because the agent runs these through a shell, and on Windows
+    // the installed command is a .cmd that will not spawn any other way.
+    // Run it with the PATH the agent will have, not this process's. Launched
+    // through npx, this process has npx's temporary bin first on PATH, holding a
+    // `nearly` that vanishes when npx exits — so a hook calling `nearly` passed
+    // here and could never run for the agent. npm scripts add node_modules/.bin
+    // the same way.
+    const sep = process.platform === 'win32' ? ';' : ':';
+    const agentPath = String(process.env.PATH || process.env.Path || '').split(sep)
+      .filter((d) => d && !/[\\/]_npx[\\/]/.test(d) && !/[\\/]node_modules[\\/]\.bin$/.test(d)).join(sep);
+    const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^npm_/i.test(k)));
+    env.PATH = agentPath;
+    if (process.platform === 'win32') env.Path = agentPath;
+    const r = spawnSync(cmd, { input: probe, shell: true, encoding: 'utf8', timeout: 30_000, env });
+    const decided = /permissionDecision|"decision"|"permission"/.test(r.stdout || '');
+    if (decided) {
+      say(true, 'hooks actually fire', 'the gate answered a test call');
+    } else {
+      const lines = String(r.stderr || '').split('\n').map((l) => l.trim()).filter(Boolean)
+        .filter((l) => !/^(at |node:internal|npm (warn|notice)|\^+$|Node\.js v)/.test(l));
+      const pick = lines.find((l) => /not found|no such file|cannot find|ENOENT|EACCES|permission denied|is not recognized|Error:/i.test(l))
+        || lines[lines.length - 1];
+      const why = (r.error && r.error.message) || pick
+        || (r.status !== 0 ? `the hook command exited ${r.status}` : 'the hook ran but answered nothing');
+      say(false, 'hooks actually fire', why,
+        `the hook command in ${cc.config} does not work here, so nothing is gated and nothing is recorded — check that \`nearly\` runs in a plain shell, then re-run \`nearly\` to rewrite the hooks`);
+    }
+  }
+}
+
 // 3 — the server, and whether it is this build
 let health = null;
 try {
@@ -93,7 +154,11 @@ if (!health) {
 // 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); } };
+const real = (p) => {
+  let r;
+  try { r = realpathSync.native(resolve(p)); } catch { r = resolve(p); }
+  return process.platform === 'win32' ? r.toLowerCase() : r;   // same place, spelled differently
+};
 try {
   for (const f of readdirSync(recDir).filter((f) => f.endsWith('.jsonl'))) {
     let created = null;

package/scripts/hook.mjs

@@ -25,8 +25,9 @@
 import { spawn } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { realpathSync } from 'node:fs';
+import { realpathSync, readFileSync } from 'node:fs';
 import { byId } from '../server/adapters.mjs';
+import { keep } from '../server/reclaim.mjs';
 
 const HOST = '127.0.0.1';
 const PORT = Number(process.env.NEARLY_PORT || 47653);
@@ -41,6 +42,10 @@ if (!event) process.exit(0);
 
 // An unknown id is a typo in a config file, not a reason to wedge the agent.
 const adapter = flag ? byId(flag.slice('--adapter='.length)) : null;
+// Nobody is at the keyboard. Set by attach --auto, carried per repo rather than
+// as machine-wide state, because supervising one project and not another is the
+// normal case.
+const unattended = args.includes('--auto');
 
 const body = await new Promise((r) => {
   let s = '';
@@ -51,6 +56,7 @@ const body = await new Promise((r) => {
 });
 
 const realRoot = (() => { try { return realpathSync(root); } catch { return root; } })();
+const VERSION = (() => { try { return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version; } catch { return null; } })();
 
 // Is the thing on this port *us*?
 //
@@ -63,8 +69,8 @@ async function up(ms = 400) {
     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;
+    if (h.root === realRoot || keep(h.version, VERSION)) return true;
+    return 'stale';   // older, or from before servers said what they were
   } catch { return false; }
 }
 
@@ -88,7 +94,7 @@ if (health === 'stale') {
   // 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 });
+  const { outcome } = await reclaim({ port: PORT, base: BASE, root: realRoot, version: VERSION });
   // '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;
@@ -111,7 +117,8 @@ if (adapter && adapter.normalize) {
 
 try {
   const hold = adapter?.holdMs ? `&hold=${adapter.holdMs}` : '';
-  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}${hold}`, {
+  const auto = unattended ? '&auto=1' : '';
+  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}${hold}${auto}`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: payload,

package/scripts/install-push-hook.mjs

@@ -1,7 +1,7 @@
 // Install a git pre-push hook that builds the branch's session record and
 // offers to post it to the pull request.
 //
-//   node scripts/install-push-hook.mjs <repo-path> [--remove]
+//   node scripts/install-push-hook.mjs <repo-path> [--cmd "<how to run nearly>"] [--remove]
 //
 // Pushing is the moment your work stops being yours and becomes someone else's
 // to review, so it is the right moment to hand over the record. The hook:
@@ -22,7 +22,14 @@ import { fileURLToPath } from 'node:url';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const argv = process.argv.slice(2);
-const repo = resolve(argv.find((a) => !a.startsWith('--')) || '.');
+const cmdAt = argv.indexOf('--cmd');
+// How the hook runs Nearly. attach passes the same command it wrote into the
+// agent hooks, so both survive the same things. The default — this file's own
+// folder — is only right for a checkout: run through npx it was the npx cache,
+// and once npm cleared that every push printed a stack trace while doctor went
+// on reporting the hook as installed.
+const RUN = cmdAt !== -1 && argv[cmdAt + 1] ? argv[cmdAt + 1] : `node ${JSON.stringify(join(root, 'bin', 'nearly.mjs'))}`;
+const repo = resolve(argv.find((a, i) => !a.startsWith('--') && i !== cmdAt + 1) || '.');
 const remove = argv.includes('--remove');
 
 if (!existsSync(join(repo, '.git'))) {
@@ -35,25 +42,37 @@ const MARKER = 'x-session-record-hook';
 const hooksDir = join(repo, '.git', 'hooks');
 const hookPath = join(hooksDir, 'pre-push');
 
+// Ours by the marker, or by the exact comment older versions wrote. Matching the
+// word "nearly" anywhere claimed any hook that happened to mention it.
+const ours = (text) => text.includes(MARKER) || /^# (control-room|nearly): hand the session record/m.test(text);
+
 if (remove) {
-  if (existsSync(hookPath)) { rmSync(hookPath); console.log(`Removed ${hookPath}`); }
-  else console.log('No pre-push hook to remove.');
+  if (!existsSync(hookPath)) { console.log('No pre-push hook to remove.'); process.exit(0); }
+  // Installing refused to overwrite someone else's hook; removing used to delete
+  // it anyway, and said "removed" while doing so.
+  if (!ours(readFileSync(hookPath, 'utf8'))) {
+    console.error(`${hookPath} was not written by Nearly, so it was left alone.`);
+    process.exit(1);
+  }
+  rmSync(hookPath);
+  console.log(`Removed ${hookPath}`);
   process.exit(0);
 }
 
 if (existsSync(hookPath)) {
   const existing = readFileSync(hookPath, 'utf8');
-  // Recognise it by a marker that does not change when the product is renamed,
-  // and still recognise hooks written before this file existed.
-  const mine = existing.includes(MARKER) || /control-room|nearly/.test(existing);
+  const mine = ours(existing);
   if (!mine) {
     console.error(`${hookPath} already exists and was not written by the Nearly.`);
     console.error('Refusing to overwrite it. Move it aside, or add this line to it yourself:');
-    console.error(`  node ${join(root, 'scripts', 'push-record.mjs')} "${repo}" || true`);
+    console.error(`  ${RUN} push-record "${repo}" || true`);
     process.exit(1);
   }
 }
 
+// Safe inside the double quotes of a sh script.
+const shq = (s) => String(s).replace(/[\\"$`]/g, '\\$&');
+
 mkdirSync(hooksDir, { recursive: true });
 writeFileSync(hookPath, `#!/bin/sh
 # ${MARKER}
@@ -69,11 +88,10 @@ writeFileSync(hookPath, `#!/bin/sh
 # ENXIO, when no terminal is attached. The open has to happen inside a subshell
 # too: a failed redirection is reported by the shell itself, so redirecting the
 # command's stderr does not silence it, but redirecting the subshell's does.
-CR="${join(root, 'scripts', 'push-record.mjs')}"
 if (: >/dev/tty) 2>/dev/null; then
-  node "$CR" "${repo}" </dev/tty >/dev/tty 2>&1 || true
+  ${RUN} push-record "${shq(repo)}" </dev/tty >/dev/tty 2>&1 || true
 else
-  NEARLY_NO_TTY=1 node "$CR" "${repo}" || true
+  NEARLY_NO_TTY=1 ${RUN} push-record "${shq(repo)}" || true
 fi
 exit 0
 `);

package/scripts/post-recap.mjs

@@ -59,7 +59,7 @@ lines.push('');
 if (outcome?.notDone?.length) {
   lines.push(`> **${outcome.notDone.length} thing${outcome.notDone.length > 1 ? 's' : ''} the agent wanted to do did not happen.** The diff cannot show you this.`);
   lines.push('>');
-  for (const n of outcome.notDone) lines.push(`> - \`${n.tool}\` · \`${n.what}\` — ${n.by === 'policy' ? 'blocked by policy' : 'refused by the supervisor'}`);
+  for (const n of outcome.notDone) lines.push(`> - \`${n.tool}\` · \`${n.what}\` — ${n.by === 'policy' ? 'blocked by policy' : n.by === 'timeout' ? 'nobody answered, so it was refused' : 'refused by the supervisor'}`);
   lines.push('');
 }
 lines.push('| ' + cover.stats.map(([k]) => k).join(' | ') + ' |');

package/scripts/push-record.mjs

@@ -30,9 +30,11 @@ const URL_BASE = (process.env.NEARLY_URL_BASE || configured() || '').replace(/\/
 // wait at a push. Opt in with NEARLY_AUDIO=1 when you are making the good one.
 const WANT_AUDIO = process.env.NEARLY_AUDIO === '1';
 
-const dim = (s) => `\x1b[2m${s}\x1b[0m`;
-const bold = (s) => `\x1b[1m${s}\x1b[0m`;
-const red = (s) => `\x1b[31m${s}\x1b[0m`;
+// Colour only on a terminal; piped into a file or a CI log it is noise.
+const COLOR = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s) => (COLOR ? `\x1b[2m${s}\x1b[0m` : String(s));
+const bold = (s) => (COLOR ? `\x1b[1m${s}\x1b[0m` : String(s));
+const red = (s) => (COLOR ? `\x1b[31m${s}\x1b[0m` : String(s));
 
 function bail(msg) { if (msg) console.error(dim(`nearly: ${msg}`)); process.exit(0); }
 
@@ -76,7 +78,7 @@ if (notDone.length) {
   console.log('');
   console.log(`  ${red('These never happened, and the diff will not show them:')}`);
   for (const n of notDone) {
-    const by = n.by === 'policy' ? 'blocked by policy' : 'you refused it';
+    const by = n.by === 'policy' ? 'blocked by policy' : n.by === 'timeout' ? 'nobody answered' : 'you refused it';
     console.log(`    · ${n.tool}  ${n.what}  ${dim(`(${by})`)}`);
   }
 }
@@ -91,7 +93,7 @@ console.log('');
 // hear about a fix.
 try {
   const { checkForUpdate, applyUpdate } = await import('./update-check.mjs');
-  applyUpdate(await checkForUpdate());
+  applyUpdate(await checkForUpdate(), { background: true });
 } catch { /* never worth failing a push over */ }
 
 // Finding the pull request needs gh. Not having it and not having a pull

package/scripts/runtime.mjs

@@ -0,0 +1,84 @@
+// Where Nearly installs itself so hooks have something stable to call.
+//
+// Hooks run on every tool call, so they need a command that is fast, will still
+// exist tomorrow, and picks up upgrades. `npm install -g` was supposed to give
+// that and failed in two common ways, both silently:
+//
+//   · Windows: spawning npm.cmd without a shell is refused by every current
+//     Node release (the 2024 fix for CVE-2024-27980). So the install failed on
+//     every up-to-date Windows machine, every time.
+//   · macOS with Node from the official installer: the global prefix is
+//     /usr/local, owned by root, so the install fails without sudo.
+//
+// Either way attach fell back to `npx -y nearly-cli@<version>` in every hook —
+// slower on each call, and pinned, so no fix ever reached that repo again. A
+// Cursor user was stuck on the exact release that was breaking his editor.
+//
+// So install into a directory the user always owns. No root, no PATH, no
+// global prefix to be wrong about.
+
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+
+// Not paths.mjs: from a checkout that resolves to the checkout, and a runtime
+// install must live in the user's own space whatever ran it.
+export const RUNTIME = join(process.env.NEARLY_HOME || join(homedir(), '.nearly'), 'runtime');
+export const ENTRY = join(RUNTIME, 'node_modules', 'nearly-cli', 'bin', 'nearly.mjs');
+
+export const hasRuntime = () => existsSync(ENTRY);
+
+export function isRuntime(root) {
+  const rel = resolve(root);
+  return rel === resolve(RUNTIME) || rel.startsWith(resolve(RUNTIME) + (process.platform === 'win32' ? '\\' : '/'));
+}
+
+// The command a hook runs. Quoted, because a home directory with a space in it
+// is ordinary on Windows and would otherwise split into two arguments.
+export const runtimeCommand = () => `node ${JSON.stringify(ENTRY)}`;
+
+const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+// Everything that installs Nearly runs inside `npx nearly-cli`, and npx hands its
+// own settings to its children as npm_config_* variables. A nested npm install
+// inherits them and obeys them — on one machine `allow_scripts` turned a plain
+// install into EALLOWSCRIPTS, and on another it will be whatever that person's
+// npm config happens to hold. The identical command succeeds with them removed.
+export function cleanEnv() {
+  return Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^npm_/i.test(k)));
+}
+
+// npm reports a failure as key/value lines (`code`, `syscall`, `path`, `errno`)
+// followed by a sentence, and ends almost every one with "A complete log of this
+// run can be found in". Showing the last line pointed people at a log file;
+// showing the first two showed `code ENOENT — syscall open` and dropped the part
+// that says which file. The error code plus npm's own sentence is the answer.
+const KEYS = /^(code|syscall|path|errno|dest|spawnargs|signal|cmd|cwd|file|type|stack|A complete log)\b/i;
+export function npmError(r) {
+  const lines = String(r.stderr || r.stdout || '').split('\n').map((l) => l.trim()).filter(Boolean);
+  const body = (l) => l.replace(/^npm (error|ERR!)\s*/i, '');
+  const errs = lines.filter((l) => /^npm (error|ERR!)/i.test(l)).map(body);
+  const code = errs.find((l) => /^code\b/i.test(l))?.replace(/^code\s+/i, '');
+  const sentence = errs.filter((l) => !KEYS.test(l)).map((l) => l.replace(/^[a-z]+ (?=[A-Z])/, ''))[0];
+  const said = [code, sentence].filter(Boolean);
+  // Drop the code when the sentence already starts with it.
+  if (said.length === 2 && said[1].startsWith(said[0])) said.shift();
+  return said.join(' — ') || lines.filter((l) => !/complete log of this run/i.test(l)).pop() || `npm exited ${r.status}`;
+}
+
+export function installRuntime(version) {
+  try { mkdirSync(RUNTIME, { recursive: true }); } catch (e) { return { ok: false, error: e.message }; }
+  // A tarball or path can stand in for the registry — how the tests install a
+  // build that has not been published yet.
+  const spec = process.env.NEARLY_INSTALL_SPEC || `nearly-cli@${version}`;
+  const r = spawnSync(NPM, ['install', '--prefix', RUNTIME, spec, '--no-save', '--no-fund', '--no-audit', '--loglevel=error'], {
+    encoding: 'utf8', timeout: 180_000,
+    // Windows will not spawn a .cmd any other way.
+    shell: process.platform === 'win32',
+    env: cleanEnv(),
+  });
+  if (r.error) return { ok: false, error: r.error.message };
+  if (r.status !== 0 || !hasRuntime()) return { ok: false, error: npmError(r) };
+  return { ok: true };
+}

package/scripts/update-check.mjs

@@ -19,7 +19,8 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir } from 'node:os';
-import { spawnSync, execFileSync } from 'node:child_process';
+import { spawn, spawnSync, execFileSync } from 'node:child_process';
+import { installRuntime, isRuntime, cleanEnv } from './runtime.mjs';
 
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
 const DAY = 24 * 60 * 60 * 1000;
@@ -27,8 +28,10 @@ const DAY = 24 * 60 * 60 * 1000;
 // npm is a .cmd shim on Windows and Node will not run one through spawn unless
 // it is named exactly. Without this, installing and upgrading both fail there.
 const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-const dim = (s) => `\x1b[2m${s}\x1b[0m`;
-const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+// Colour only on a terminal; piped into a file or a CI log it is noise.
+const COLOR = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s) => (COLOR ? `\x1b[2m${s}\x1b[0m` : String(s));
+const bold = (s) => (COLOR ? `\x1b[1m${s}\x1b[0m` : String(s));
 
 function stampPath() {
   const dir = process.env.XDG_CACHE_HOME || join(homedir() || tmpdir(), '.cache');
@@ -46,6 +49,9 @@ function compare(a, b) {
 // Updating in place only makes sense for a global install. An npx run is
 // ephemeral and a checkout belongs to whoever cloned it.
 function installKind() {
+  // Installed by attach into ~/.nearly/runtime. It upgrades itself in place, so
+  // every repo whose hooks point there moves with it.
+  if (isRuntime(root)) return 'runtime';
   if (/[\\/]_npx[\\/]/.test(root)) return 'npx';
   try {
     const bin = execFileSync(process.platform === 'win32' ? 'where' : 'which', ['nearly'],
@@ -84,7 +90,12 @@ export async function checkForUpdate() {
   } catch { return null; }
 }
 
-export function applyUpdate(u) {
+// `background` is for the push path. An update installing in the foreground
+// held `git push` for up to two minutes, and a push that hangs reads as a push
+// that is broken — which is a strange thing for a tool that must never block a
+// push to do. Commands a person typed and is watching still install in front
+// of them, because there they want to know it happened.
+export function applyUpdate(u, { background = false } = {}) {
   if (!u) return;
 
   if (u.major) {
@@ -95,6 +106,27 @@ export function applyUpdate(u) {
     return;
   }
 
+  if (u.kind === 'runtime') {
+    if (background) {
+      try {
+        const child = spawn(process.execPath, [join(root, 'scripts', 'update-check.mjs'), '--install-runtime', u.to],
+          { detached: true, stdio: 'ignore' });
+        child.on('error', () => { /* next time */ });
+        child.unref();
+        console.log('');
+        console.log(dim(`  Nearly ${u.to} is out (you have ${u.from}) — updating in the background.`));
+      } catch { /* never worth failing a push over */ }
+      return;
+    }
+    process.stdout.write(dim(`  Updating Nearly ${u.from} → ${u.to}… `));
+    const r = installRuntime(u.to);
+    console.log(r.ok ? 'done' : 'could not');
+    if (!r.ok) console.log(`    ${r.error}`);
+    else console.log(dim('  Every repo you turned it on for is now on the new version.'));
+    console.log('');
+    return;
+  }
+
   if (u.kind !== 'global') {
     console.log('');
     console.log(`  ${bold(`Nearly ${u.to} is out`)} ${dim(`(you have ${u.from})`)}`);
@@ -102,9 +134,24 @@ export function applyUpdate(u) {
     return;
   }
 
+  if (background) {
+    try {
+      // Detached and forgotten: the push goes ahead now and the new version is
+      // in place by the next command. A .cmd on Windows only spawns through a
+      // shell, which is the same trap npm itself fell into here once already.
+      const child = spawn(NPM, ['install', '-g', `${u.name}@${u.to}`, '--silent', '--no-fund', '--no-audit'],
+        { detached: true, stdio: 'ignore', shell: process.platform === 'win32', env: cleanEnv() });
+      child.on('error', () => { /* offline, or no permission: next time */ });
+      child.unref();
+      console.log('');
+      console.log(dim(`  Nearly ${u.to} is out (you have ${u.from}) — updating in the background.`));
+    } catch { /* never worth failing a push over */ }
+    return;
+  }
+
   process.stdout.write(dim(`  Updating Nearly ${u.from} → ${u.to}… `));
   const r = spawnSync(NPM, ['install', '-g', `${u.name}@${u.to}`, '--silent', '--no-fund', '--no-audit'],
-    { encoding: 'utf8', timeout: 120_000 });
+    { encoding: 'utf8', timeout: 120_000, shell: process.platform === 'win32', env: cleanEnv() });
 
   if (r.status === 0) {
     console.log('done');
@@ -117,3 +164,9 @@ export function applyUpdate(u) {
   }
   console.log('');
 }
+
+// `node update-check.mjs --install-runtime <version>` — what the background
+// updater runs, detached, so a push never waits on npm.
+if (process.argv[2] === '--install-runtime' && process.argv[3]) {
+  installRuntime(process.argv[3]);
+}

package/server/adapters.mjs

@@ -126,10 +126,20 @@ function writeJson(file, obj) {
   writeFileSync(file, JSON.stringify(obj, null, 2) + '\n');
 }
 
-// Ours is anything that runs nearly. Matching on that rather than on a version
-// or a path is what makes attach safe to re-run, and what stopped a rename from
-// orphaning hooks the last time.
-const isOurs = (h) => /nearly/i.test(JSON.stringify(h ?? ''));
+// Ours: a hook command that runs Nearly's hook, in any form attach has ever
+// written — `nearly hook <event>`, `node "…/nearly.mjs" hook <event>`,
+// `npx -y nearly-cli@x hook <event>`, `node "…/scripts/hook.mjs" <event>`, or
+// the old HTTP hooks. Matching the word "nearly" anywhere claimed any hook that
+// mentioned it, and attach deleted a user's `nearly-finished-notifier/notify.sh`.
+// The quote-and-backslash run tolerates the same command read out of raw JSON.
+export const OURS_RE = /(?:^|[\s"'/\\])(?:nearly(?:\.mjs)?|nearly-cli@\S+?|hook\.mjs)[\\"']*\s+(?:hook\s+)?(?:session-start|prompt|pre-tool|post-tool|stop|session-end|subagent-stop)\b|:\d+\/hooks\/(?:session-start|prompt|pre-tool|post-tool|stop|session-end|subagent-stop)\b/;
+
+export function isOurs(value) {
+  if (value == null) return false;
+  if (typeof value === 'string') return OURS_RE.test(value);
+  if (typeof value === 'object') return Object.values(value).some(isOurs);
+  return false;
+}
 
 // Strip our entries out of an event map shaped { event: [entry, ...] }, and drop
 // events we emptied so the file does not fill with husks.
@@ -226,7 +236,13 @@ export const ADAPTERS = [
       cfg.hooks = stripEvents(cfg.hooks || {});
       for (const [their, ours] of Object.entries(this.events)) {
         cfg.hooks[their] = [...(cfg.hooks[their] || []),
-          { command: cmdFor(ours), timeout: holdFor(ours), failClosed: ours === 'pre-tool' }];
+          // Fail open, as every other harness does. failClosed only ever
+          // applied when the gate did not answer — a slow npx, a server that
+          // had not started — and then it denied every write in the editor.
+          // A reported Cursor session could not edit a single file. The
+          // never-rules do not depend on this: the server enforces them whenever
+          // it is reachable.
+          { command: cmdFor(ours), timeout: holdFor(ours), failClosed: false }];
       }
       writeJson(file, cfg);
       return { file };
@@ -362,11 +378,18 @@ export const ADAPTERS = [
       const cfg = { version: 1, hooks: {} };
       for (const [their, ours] of Object.entries(this.events)) {
         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) }];
+        // Two products read this file and disagree about the key. Copilot CLI
+        // takes `bash` and `powershell`; VS Code's agent mode takes `windows`,
+        // `linux` and `osx` as per-platform overrides and does not document the
+        // other two at all. Writing both sets costs a few bytes. Guessing wrong
+        // means the hook never runs, and a hook that never runs looks exactly
+        // like a week in which nobody did any work.
+        cfg.hooks[their] = [{
+          type: 'command', command: run,
+          bash: run, powershell: run,
+          windows: run, linux: run, osx: run,
+          timeoutSec: holdFor(ours), timeout: holdFor(ours),
+        }];
       }
       writeJson(file, cfg);        // our own file; nobody else's entries to keep
       return { file };

package/server/index.mjs

@@ -351,7 +351,12 @@ function decide(sid, id, decision, why, scope = 'once') {
   clearTimeout(p.timer);
   s.pending.delete(id);
   if (scope === 'always') rules.set(p.key, decision === 'allow' ? 'log' : 'never');
-  p.respond(decision, why);
+  // One call can arrive down more than one hook — VS Code reads both
+  // .claude/settings.local.json and .github/hooks/*.json, so a repo wired for
+  // Claude Code and Copilot fires twice for the same tool_use_id. Everyone who
+  // asked gets the same answer; answering only the last one left the first hook
+  // hanging until the agent's own timeout, which looks like the agent freezing.
+  for (const r of p.responders) r(decision, why);
   record(sid, { type: 'decision', id, decision, why, scope, tool: p.tool, key: p.key, waitedMs: Date.now() - p.at });
   if (s.pending.size === 0 && s.state === 'waiting') s.state = 'working';
   broadcast({ type: 'session-state', session: sid, state: s.state });
@@ -422,7 +427,14 @@ const server = http.createServer(async (req, res) => {
     }
 
     if (ev === 'pre-tool') {
-      const { tier, reason } = classifyWith(hook, rules);
+      // Unattended: nobody is going to answer, so holding a call for two
+      // minutes and then failing closed does not protect anything — it just
+      // stalls the run and teaches people to turn the gate off. The never-rules
+      // still bite, because those never needed a person. Everything that would
+      // have been asked is done and written down instead.
+      const unattended = url.searchParams.get('auto') === '1';
+      let { tier, reason } = classifyWith(hook, rules);
+      if (unattended && tier === 'ask') { tier = 'log'; reason = 'allowed unattended — nobody was asked'; }
       const id = hook.tool_use_id || randomUUID();
       // Policy keys on the canonical name so a rule means the same thing in every
       // harness; the record shows the harness's own name so it stays truthful
@@ -432,17 +444,24 @@ const server = http.createServer(async (req, res) => {
         hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision, permissionDecisionReason: `nearly: ${why}` },
       });
       if (!s) return respond('deny', 'unknown session');
-      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})`); }
+      if (tier === 'never') { record(sid, { type: 'decision', id, decision: 'deny', why: reason, scope: 'policy', tool: shown, input: hook.tool_input, tier, unattended }); return respond('deny', `never (${reason})`); }
+      if (tier === 'log') {
+        record(sid, { type: 'decision', id, decision: 'allow', why: reason, scope: unattended ? 'auto' : 'policy', tool: shown, input: hook.tool_input, tier });
+        return respond('allow', unattended ? reason : `do and log (${reason})`);
+      }
       // ask: hold the response until the UI decides, or fail closed
       // 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 };
+      // Same call, second hook: join the question already being asked rather
+      // than replacing it, so the person is not asked twice about one thing.
+      const already = s.pending.get(id);
+      if (already) { already.responders.push(respond); return; }
+      const item = { id, sid, tool: shown, input: hook.tool_input, tier, reason, key: ruleKey(hook), at: Date.now(), holdMs, responders: [respond] };
       item.timer = setTimeout(() => decide(sid, id, 'deny',
-        `no human answer in ${Math.round(holdMs / 1000)}s; nearly fails closed`), holdMs);
+        `no human answer in ${Math.round(holdMs / 1000)}s; nearly fails closed`, 'timeout'), holdMs);
       s.pending.set(id, item);
       s.state = 'waiting';
       record(sid, { type: 'ask', ...pendingView(item) });