nearly-cli 0.1.12 → 0.1.16

package/README.md

@@ -159,6 +159,19 @@ Nothing to configure, no server to start, and `nearly off` removes all of it.
 Run it again in any other repo you want recorded. After the first time the
 command is just `nearly`.
 
+### Where it installs
+
+`npx nearly-cli` installs a copy into `~/.nearly/runtime`, and the hooks call
+that copy directly. Not `npm install -g`, which it used to use and which failed
+silently in three ordinary situations: on any up-to-date Windows machine, where
+Node will not start `npm.cmd` without a shell; on a Mac whose Node came from the
+official installer, where the global folder belongs to root; and whenever npx
+itself was running it, because npx passes its own settings down to the npm it
+starts. Each failure fell back to a pinned `npx -y nearly-cli@<version>` in every
+hook — slower on every tool call, and stuck on that release for good. A folder
+you always own avoids all three, and if the install still fails, `nearly` now
+prints npm's actual reason instead of a pointer to a log file.
+
 ### Upgrading
 
 It updates itself. When you run a command and a newer version exists, Nearly
@@ -175,7 +188,7 @@ Four rules keep that from being something you regret installing:
   before you trust it.
 - **Never silent.** An update that happened without being mentioned is
   indistinguishable from a compromise, so it always says what it did.
-- **Never fatal.** No network, a locked global directory, a slow registry: you
+- **Never fatal.** No network, a locked folder, a slow registry: you
   keep the version you have, the command you ran still works, and it tells you
   rather than leaving you to assume you are current.
 
@@ -212,18 +225,63 @@ All of them capture the moment a human refuses something. None of them passes it
 
 **The gate here exists to produce the recording.** It is the instrument, not the product. If you already run Prempti, its audit trail is richer than ours and reading it as an input is the obvious next step; see *Roadmap*.
 
+## Unattended by default
+
+Turning Nearly on does not make your agent wait for anyone. Destructive commands
+are refused outright — `rm -rf`, `git push`, `sudo`, anything touching `.env`,
+`curl … | sh` — and everything else runs and is written down.
+
+It used to hold every edit for a person to approve, which only works if a person
+is watching the dashboard, and nothing told a new user it existed. In practice
+that meant a Cursor session unable to write a single file, each edit waiting two
+minutes and then being refused. Holding for approval is now something you turn
+on while you are actually watching:
+
+```bash
+nearly --supervise
+```
+
+This is not weaker than it sounds. The refusals that matter never needed a
+person: they are rules, and they fire with nobody at the keyboard — including
+under Claude Code's `bypassPermissions`, which skips its own prompts but not
+the hooks Nearly runs in. With no one watching, the record is also the only
+account of what the agent did, and it says so on the first line.
+
 ## The consent gradient
 
-Every tool call passes through an HTTP `PreToolUse` hook to this server, which sorts it into a tier:
+Every tool call passes through a `PreToolUse` hook to this server, which sorts it into a tier:
 
-| Tier | What happens | Default for |
+| Tier | What happens | Covers |
 |---|---|---|
-| never | denied, no prompt, logged | `rm -rf`, `git push`, `sudo`, `.env`, `curl … | sh` |
-| ask | held until a human decides in the UI; denied if nobody answers in 2 minutes (fails closed) | Bash, Edit, Write, WebFetch, Task |
-| log | allowed, receipt recorded | Read, Glob, Grep |
+| never | refused, nobody asked, recorded with the reason | anything that cannot be undone — see below |
+| ask | only with `--supervise`: held until you decide; refused if nobody answers in 2 minutes | Bash, Edit, Write, WebFetch, Task |
+| log | allowed and recorded | everything else — and, unattended, everything that would have been asked |
 
 "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`.
 
+A call nobody answered is refused, but nobody refused it, and the record says so
+— "nobody answered" — rather than crediting you with a decision you never made.
+
+### What "never" means
+
+One rule: **refuse what cannot be undone.**
+
+- **Deleting.** Inside the repo, git gives it back, so `rm -rf node_modules` runs. Outside the repo, in your home directory, at the root, `.git` itself, or a path only known at run time (`$SOME_VAR`) is refused. Scratch space under the system temp folder is allowed, except for the temp folder itself, a folder that holds this repo, or another git repository.
+- **Pushing.** A feature branch is how work reaches review, so it runs. A force-push, deleting a remote branch, `--mirror`, or pushing straight to `main`, `master` or the remote's default branch is refused — a bare `git push` asks git which branch you are on.
+- **Local history git never had.** `git clean -fd`, `git reset --hard` over uncommitted work, `reflog expire`, `gc --prune=now` and `stash clear` are refused. `git clean -fdX`, which only removes ignored build output, is not.
+- **Secrets.** Refused when a real secret would be shown to the agent, sent somewhere, or carried out of the repo: `cat .env`, `curl -F file=@.env`, `cp .env /tmp`, the Read tool on `.env`, `~/.aws/credentials`, `~/.ssh`. Not refused: `.env.example`, `--env-file .env`, `source .env`, `test -f .env`, `cp .env .env.bak`, and any file git already tracks, since that is already readable by anyone with the repo.
+- **The rest.** `sudo` and its relatives, a download piped into anything that runs it, world-writable `chmod`, disk and filesystem tools, deleting a GitHub repository.
+
+It reads a command the way a shell runs it: `cd ~ && rm -rf Documents` is refused because the `cd` moves where the delete lands; `bash -c`, `eval`, `$(…)`, `xargs`, `find -exec` and `npx rimraf` are unwrapped and checked; `\rm` and `/bin/rm` are `rm`; a path is followed through symlinks; `git -c x=y push --force` is still a force-push; `git checkout main && git push` is still a push to main. Windows `Remove-Item`, `rd /s` and `del /s` are covered. Any tool carrying a command is checked, not only one named `Bash`.
+
+### What it is not
+
+**It is not a sandbox.** It catches what a well-meaning agent actually types, and it was built by collecting every bypass two independent test runs could find — 126 destructive commands, all refused, and 97 ordinary ones, none refused, all kept as tests. But a determined or compromised agent can still get past a rule that reads text: code handed to an interpreter (`python -c`, `node -e`) is only inspected for the obvious, and a script the agent writes to a file and then runs is not inspected at all.
+
+For isolation, run the agent in a container, a VM, or Claude Code's own sandbox, and use Nearly for what it is for — a record of what happened, including what was stopped, that reaches the person reviewing the code.
+
+### Lab mode
+
 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

package/bin/nearly.mjs

@@ -17,6 +17,7 @@
 // because the useful thing is what people type first.
 
 import { spawn, spawnSync, execFileSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -61,6 +62,12 @@ switch (cmd) {
   case 'hook':
     return run(s('hook.mjs'), rest);
 
+  // internal: what the git pre-push hook runs. It goes through this command
+  // rather than a path to the script, so it survives the same upgrades and
+  // cache clears the agent hooks do.
+  case 'push-record':
+    return run(s('push-record.mjs'), rest);
+
   case 'record': case 'recap': {
     // Default to the branch you are on, since that is what gets reviewed.
     if (rest.length) return run(s('build-recap.mjs'), rest);
@@ -86,7 +93,7 @@ switch (cmd) {
     return run(s('build-recap.mjs'), ['--voices']);
 
   case 'server': {
-    console.log('Nearly on http://127.0.0.1:47653');
+    console.log(`Nearly on http://127.0.0.1:${process.env.NEARLY_PORT || 47653}`);
     console.log('You do not normally need this: the hooks start it when they need it.');
     return run(join(root, 'server', 'index.mjs'), rest);
   }
@@ -94,7 +101,7 @@ switch (cmd) {
   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' : '');
+    const url = `http://127.0.0.1:${process.env.NEARLY_PORT || 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);
@@ -118,6 +125,9 @@ switch (cmd) {
   }
 
   default:
+    // `nearly ~/code/app` — a path, not a command. The "not a git repository"
+    // message told people to pass one, and then this said "Unknown command".
+    if (existsSync(cmd) && statSync(cmd).isDirectory()) return run(s('attach.mjs'), [cmd, ...rest]);
     console.error(`Unknown command: ${cmd}`);
     console.error('Try: nearly help');
     process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.12",
+  "version": "0.1.16",
   "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/stale-server.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 test/runtime.test.mjs"
   }
 }

package/scripts/agents.mjs

@@ -11,12 +11,14 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { ADAPTERS } from '../server/adapters.mjs';
+import { ADAPTERS, OURS_RE } from '../server/adapters.mjs';
 import { detect, installed } from './detect.mjs';
 
-const dim = (s) => `\x1b[2m${s}\x1b[0m`;
-const bold = (s) => `\x1b[1m${s}\x1b[0m`;
-const ok = (s) => `\x1b[32m${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 ok = (s) => (COLOR ? `\x1b[32m${s}\x1b[0m` : String(s));
 
 const repo = resolve(process.argv.slice(2).find((a) => !a.startsWith('--')) || process.cwd());
 const here = new Set(detect(repo).map((d) => d.id));
@@ -28,7 +30,7 @@ const machine = new Set(installed().map((d) => d.id));
 const gated = (a) => {
   const f = join(repo, a.config);
   if (!existsSync(f)) return false;
-  try { return /nearly/i.test(readFileSync(f, 'utf8')); } catch { return false; }
+  try { return OURS_RE.test(readFileSync(f, 'utf8')); } catch { return false; }
 };
 
 const width = Math.max(...ADAPTERS.map((a) => a.name.length));
@@ -40,7 +42,9 @@ console.log('');
 for (const a of ADAPTERS) {
   const on = gated(a);
   const mark = on ? ok('●') : dim('○');
-  const state = on ? 'gated here' : here.has(a.id) ? 'used here, not gated' : machine.has(a.id) ? 'installed, unused here' : 'not in use here';
+  // "Wired", not "gated": a hook being in the config says nothing about whether
+  // it runs. `nearly doctor` fires one to find out.
+  const state = on ? 'wired here' : here.has(a.id) ? 'used here, not wired' : machine.has(a.id) ? 'installed, unused here' : 'not in use here';
   console.log(`  ${mark} ${bold(pad(a.name))}  ${pad2(state)} ${dim(a.config)}`);
 }
 function pad2(s) { return s + ' '.repeat(Math.max(0, 22 - s.length)); }

package/scripts/attach.mjs

@@ -18,12 +18,13 @@
 // it, and if it cannot start, Claude Code falls back to its own prompts and
 // nothing breaks.
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync, readdirSync, rmdirSync, rmSync } from 'node:fs';
 import { join, resolve, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { dataRoot, paths } from '../server/paths.mjs';
 import { choose, installed as agentsOnMachine } from './detect.mjs';
+import { installRuntime, hasRuntime, isRuntime, runtimeCommand } from './runtime.mjs';
 import { ADAPTERS } from '../server/adapters.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
@@ -76,57 +77,112 @@ const viaNpx = /[\\/]_npx[\\/]/.test(root);
 
 // `npx nearly-cli` should be the whole of it. An npx run is a temporary
 // download, so hooks pointing at it would pin a version in a directory npm
-// clears, and no fix would ever reach this repo. Install it properly instead,
-// once, out loud, so the one command someone types actually leaves them with a
-// working tool. --no-install skips it.
-function installGlobally() {
-  if (!viaNpx || onPath() || argv.includes('--no-install') || process.env.NEARLY_NO_INSTALL === '1') return false;
-  process.stdout.write(dim(`  Installing nearly so upgrades reach you… `));
-  const r = spawnSync(NPM, ['install', '-g', `nearly-cli@${pkgVersion()}`, '--silent', '--no-fund', '--no-audit'],
-    { encoding: 'utf8', timeout: 180_000 });
-  if (r.status === 0 && onPath()) { console.log('done'); return true; }
-  console.log(dim('skipped'));
-  console.log(dim('    Running from npx instead. Upgrades will not reach this repo automatically;'));
-  console.log(dim('    npm install -g nearly-cli when you want that.'));
+// clears, and no fix would ever reach this repo.
+//
+// This used to `npm install -g`, which failed silently on every up-to-date
+// Windows machine (Node will not spawn npm.cmd without a shell) and on any Mac
+// whose Node came from the official installer (a root-owned prefix). Each fell
+// back to a pinned npx call in every hook: slower on every tool call, and stuck
+// on that release for good. So it installs into ~/.nearly/runtime instead —
+// somewhere the user always owns. --no-install skips it.
+function installRuntimeOnce() {
+  if (!fromPackage || onPath() || hasRuntime() || isRuntime(root)) return hasRuntime();
+  if (argv.includes('--no-install') || process.env.NEARLY_NO_INSTALL === '1') return false;
+  process.stdout.write(dim('  Installing nearly so upgrades reach you… '));
+  const r = installRuntime(pkgVersion());
+  if (r.ok) { console.log('done'); return true; }
+  console.log(dim('could not'));
+  // The reason, in full. "skipped" in grey is how the last version of this
+  // left someone pinned to a broken release without ever knowing why.
+  console.log(`    ${r.error}`);
+  console.log(dim('    Falling back to npx, which is slower on every tool call and will not'));
+  console.log(dim('    pick up fixes. Run nearly again here once the problem above is solved.'));
   return false;
 }
+
+// Preference, fastest and most durable first:
+//   1. a `nearly` on PATH that is really this tool
+//   2. the runtime install in ~/.nearly/runtime
+//   3. a pinned npx call — works, but slow and never upgrades
+//   4. the checkout's own script, for someone developing this
 let installed = onPath();
+let runtime = hasRuntime();
 const hookCmd = (ev) => installed
-  ? `nearly hook ${ev}`   // verified above to survive this process
-  : fromPackage
-    ? `npx -y nearly-cli@${pkgVersion()} hook ${ev}`
-    : `node ${JSON.stringify(HOOK)} ${ev}`;
-// A function, not a value: the install below changes the answer, and computing
-// it early told a fresh install it was pinned when it was not.
-const updateNote = () => installed
+  ? `nearly hook ${ev}`
+  : runtime
+    ? `${runtimeCommand()} hook ${ev}`
+    : fromPackage
+      ? `npx -y nearly-cli@${pkgVersion()} hook ${ev}`
+      : `node ${JSON.stringify(HOOK)} ${ev}`;
+// A function, not a value: the install below changes the answer.
+const updateNote = () => (installed || runtime)
   ? 'upgrades reach this repo automatically'
   : fromPackage
-    ? `pinned to v${pkgVersion()} — run nearly again here after upgrading`
+    ? `pinned to v${pkgVersion()} — slow, and fixes will not reach it until you run nearly again`
     : 'running from a checkout — git pull updates it';
 
-const argv = process.argv.slice(2);
+// Flags take a value either way: `--agent=cursor` or `--agent cursor`. Only the
+// first worked, so `nearly --agent cursor` read "cursor" as the repo path and
+// said it was not a git repository.
+const VALUED = new Set(['--agent', '--name']);
+const argv = (() => {
+  const raw = process.argv.slice(2), out = [];
+  for (let i = 0; i < raw.length; i++) {
+    if (VALUED.has(raw[i]) && raw[i + 1] !== undefined && !raw[i + 1].startsWith('--')) { out.push(`${raw[i]}=${raw[i + 1]}`); i++; }
+    else out.push(raw[i]);
+  }
+  return out;
+})();
+const flagValue = (f) => argv.find((a) => a.startsWith(`${f}=`))?.slice(f.length + 1);
 const off = argv.includes('--off') || argv.includes('--detach');
-const repo = resolve(argv.find((a) => !a.startsWith('--')) || process.cwd());
-const nameIdx = argv.indexOf('--name');
-const name = (nameIdx !== -1 ? argv[nameIdx + 1] : basename(repo))
+// Unattended unless you ask to supervise.
+//
+// Holding a call for a human only works if a human is looking at the dashboard,
+// and nothing tells a new user it exists. So the default used to be: every edit
+// silently waits two minutes and is then refused. That made a Cursor session
+// unable to write a single file, and turned a fifteen-second task into five
+// minutes under auto mode. Two real failures of the same default.
+//
+// Now the never-rules block with nobody present, everything else is done and
+// recorded, and holding for approval is something you turn on while watching.
+const supervise = argv.includes('--supervise');
+const auto = !supervise;
+// The repo is wherever git says its top is. Looking only for a .git folder in
+// the current directory rejected every subfolder, which is where people usually
+// are when they first try something.
+const asked = resolve(argv.find((a) => !a.startsWith('--')) || process.cwd());
+const repo = (() => {
+  try {
+    const top = execFileSync('git', ['rev-parse', '--show-toplevel'],
+      { cwd: asked, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (!top) return asked;
+    // Keep the path as it was typed when it already is the top; git hands back
+    // the resolved one (/private/var for /var on macOS), which is the same place
+    // spelled in a way nobody wrote.
+    return realpathSync.native(asked) === realpathSync.native(top) ? asked : resolve(top);
+  } catch { return asked; }
+})();
+const name = (flagValue('--name') ?? basename(repo))
   .replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 24) || 'repo';
 
 // 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`;
-const ok = (s) => `\x1b[32m${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 ok = (s) => (COLOR ? `\x1b[32m${s}\x1b[0m` : String(s));
 
 if (!existsSync(join(repo, '.git'))) {
-  console.error(`${repo} is not a git repository.`);
+  console.error(`${asked} is not inside a git repository.`);
   console.error('Run this inside the repo you want recorded, or pass its path.');
   process.exit(1);
 }
 
 // Do this before the hooks are written, so they can point at the installed
 // command rather than a temporary npx download.
-if (!off && installGlobally()) installed = onPath();
+if (!off) runtime = installRuntimeOnce() || hasRuntime();
 
 // ---------------------------------------------------------------------------
 // Agent hooks
@@ -143,7 +199,9 @@ if (unknown.length) {
 const wired = [];
 const notes = [];
 for (const a of chosen) {
-  const cmdFor = (ev) => `${hookCmd(ev)} ${name}` + (a.id === 'claude-code' ? '' : ` --adapter=${a.id}`);
+  const cmdFor = (ev) => `${hookCmd(ev)} ${name}`
+    + (a.id === 'claude-code' ? '' : ` --adapter=${a.id}`)
+    + (auto ? ' --auto' : '');
   try {
     const r = off ? a.uninstall({ repo }) : a.install({ repo, cmdFor, name });
     if (r?.error) { notes.push(`${a.name}: ${r.error}`); continue; }
@@ -155,6 +213,30 @@ for (const a of chosen) {
   }
 }
 
+// Leave nothing behind. Turning off used to strip the hooks and keep an empty
+// `{}` file and empty `.cursor/ .agents/ .codex/ .gemini/ .windsurf/` folders —
+// and the next `nearly` read those folders as signs of use and wired all seven
+// agents. Only what is empty goes; nothing of anyone else's is touched, and
+// nothing above the repo.
+if (off) {
+  for (const a of ADAPTERS) {
+    const file = join(repo, a.config);
+    try {
+      if (existsSync(file)) {
+        const v = JSON.parse(readFileSync(file, 'utf8'));
+        const hollow = v && typeof v === 'object' && Object.entries(v)
+          .filter(([k]) => k !== 'version')
+          .every(([, x]) => x == null || (typeof x === 'object' && !Object.keys(x).length));
+        if (hollow) rmSync(file);
+      }
+      for (let dir = dirname(file); dir !== repo && dir.startsWith(repo); dir = dirname(dir)) {
+        if (!existsSync(dir) || readdirSync(dir).length) break;
+        rmdirSync(dir);
+      }
+    } catch { /* unreadable or busy: leave it */ }
+  }
+}
+
 // Remember this repo, so the dashboard can offer it before anything has run in
 // it. A list of paths and nothing else: it is a convenience, and it is rebuilt
 // by simply turning Nearly on again.
@@ -193,7 +275,7 @@ async function checkPort() {
   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 });
+    return await reclaim({ port: PORT, base: `http://127.0.0.1:${PORT}`, root: mine, version: pkgVersion() });
   } catch { return null; }
 }
 const port = off ? null : await checkPort();
@@ -201,8 +283,15 @@ const port = off ? null : await checkPort();
 // ---------------------------------------------------------------------------
 // git pre-push hook
 // ---------------------------------------------------------------------------
+const baseCmd = () => installed
+  ? 'nearly'
+  : runtime
+    ? runtimeCommand()
+    : fromPackage
+      ? `npx -y nearly-cli@${pkgVersion()}`
+      : `node ${JSON.stringify(join(root, 'bin', 'nearly.mjs'))}`;
 const push = spawnSync(process.execPath,
-  [join(root, 'scripts', 'install-push-hook.mjs'), repo, ...(off ? ['--remove'] : [])],
+  [join(root, 'scripts', 'install-push-hook.mjs'), repo, '--cmd', baseCmd(), ...(off ? ['--remove'] : [])],
   { encoding: 'utf8' });
 
 // ---------------------------------------------------------------------------
@@ -264,12 +353,27 @@ if (off) {
 
 console.log(`${ok('✓')} ${bold('Nearly is on')} for ${bold(name)}  ${dim(repo)}`);
 console.log('');
+if (supervise) {
+  console.log(`  ${ok('·')} ${bold('supervised')} ${dim(`— risky calls wait for you at http://127.0.0.1:${PORT}`)}`);
+  console.log(`    ${dim('keep that page open, or every one of them is refused after two minutes')}`);
+} else {
+  console.log(`  ${ok('·')} ${dim('destructive commands are blocked; everything else runs and is recorded')}`);
+  console.log(`    ${dim('to approve risky calls yourself: nearly --supervise')}`);
+}
 for (const a of wired) {
   const how = a.verified ? dim(`(${a.verified})`) : dim('(built to their published hook spec, not yet run against a live agent)');
   console.log(`  ${ok('·')} ${a.name} sessions here are gated and recorded ${how}`);
 }
 console.log(`  ${ok('·')} ${dim(updateNote())}`);
-console.log(`  ${ok('·')} ${push.status === 0 ? 'the record is offered when you push' : dim('pre-push hook skipped: ' + (push.stderr || '').trim().split('\n')[0])}`);
+if (push.status === 0) {
+  console.log(`  ${ok('·')} the record is offered when you push`);
+} else {
+  // All of it: when a pre-push hook of yours is already there, the lines after
+  // the first are the ones that say how to add Nearly to it by hand.
+  const said = (push.stderr || '').trim().split('\n').filter(Boolean);
+  console.log(`  ${ok('·')} ${dim(`pre-push hook skipped: ${said[0] || 'unknown reason'}`)}`);
+  for (const line of said.slice(1)) console.log(`    ${dim(line)}`);
+}
 if (base) {
   console.log(`  ${ok('·')} records publish to ${base}`);
 } else {
@@ -311,6 +415,8 @@ if (elsewhere.length) {
 }
 
 console.log('');
-console.log(`  Now just work. Requests that need you appear at ${bold(`http://127.0.0.1:${PORT}`)}`);
+console.log(supervise
+  ? `  Now just work. Requests that need you appear at ${bold(`http://127.0.0.1:${PORT}`)}`
+  : `  Now just work. Nothing will wait for you.`);
 console.log(dim('  Nothing to leave running. Turn it off again with --off.'));
 console.log('');

package/scripts/build-recap.mjs

@@ -100,7 +100,7 @@ function samePath(a, b) {
   if (!a || !b) return false;
   const real = (p) => {
     let r;
-    try { r = realpathSync(resolve(p)); } catch { r = resolve(p); }
+    try { r = realpathSync.native(resolve(p)); } catch { r = resolve(p); }
     // Windows spells the same directory more than one way and means the same
     // place. Comparing those as strings loses every session on that machine,
     // the same way /var against /private/var did on this one.
@@ -220,10 +220,17 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
   const undos = events.filter((e) => e.type === 'undo');
   const finals = events.filter((e) => e.type === 'result');
   const texts = events.filter((e) => e.type === 'text');
-  const humanDecisions = decisions.filter((d) => d.waitedMs != null);
+  // A held call nobody answered is denied, but nobody decided it. Counting it as
+  // a decision made the headline claim "7 decisions by Anuj" and the comment say
+  // "refused by the supervisor" about calls no person ever looked at — the one
+  // kind of claim a reviewer has no way to check. Recordings from before the
+  // server marked timeouts are recognised by their reason.
+  const timedOut = (d) => d.scope === 'timeout' || /no human answer/.test(d.why || '');
+  const humanDecisions = decisions.filter((d) => d.waitedMs != null && !timedOut(d));
   const denied = decisions.filter((d) => d.decision === 'deny');
   const blocked = decisions.filter((d) => d.tier === 'never');
-  const humanWaitMs = humanDecisions.reduce((n, d) => n + d.waitedMs, 0);
+  // The wait still happened, answered or not.
+  const humanWaitMs = decisions.filter((d) => d.waitedMs != null).reduce((n, d) => n + d.waitedMs, 0);
   const lastResult = finals.at(-1);
 
   const name = created?.name ?? id.slice(0, 8);
@@ -241,13 +248,23 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
   if (undos.length) headlineBits.push(`${plural(undos.length, 'turn')} rolled back`);
   if (humanDecisions.length) headlineBits.push(plural(humanDecisions.length, 'decision') + V(` by ${AUTHOR}`, ' from you'));
   if (!denied.length && !undos.length && checkpoints.length) headlineBits.push(plural(checkpoints.length, 'turn') + (attached ? '' : ' committed'));
+
+  // An unattended run is the one case where the absence of human decisions is
+  // itself the fact. Leaving it implied reads as "nothing needed approving"
+  // when what happened is that nobody was asked.
+  const unattended = decisions.some((d) => d.scope === 'auto');
   scenes.push({
     kind: 'cover',
     title: headlineBits.length ? headlineBits.join(', ') : 'A session with nothing to flag',
     runs: sbRuns,
+    unattended,
     orient: forReviewer
-      ? `An agent wrote the branch you are about to review${sbRuns > 1 ? `, across ${plural(sbRuns, 'session')}` : ''}. This is what happened while it was writing it — including the things it was stopped from doing, which the diff cannot show you.`
-      : `Everything your agent did in this session, including what you stopped it from doing.`,
+      ? (unattended
+        ? `An agent wrote the branch you are about to review${sbRuns > 1 ? `, across ${plural(sbRuns, 'session')}` : ''}, with nobody watching it work. Nothing here was approved by a person — the rules did the stopping. This is the only account of what it did.`
+        : `An agent wrote the branch you are about to review${sbRuns > 1 ? `, across ${plural(sbRuns, 'session')}` : ''}. This is what happened while it was writing it — including the things it was stopped from doing, which the diff cannot show you.`)
+      : (unattended
+        ? `Everything your agent did while you were not watching, including what the rules stopped it from doing.`
+        : `Everything your agent did in this session, including what you stopped it from doing.`),
     repo: worktree ? basename(worktree) : null,
     branch: created?.branch || null,
     stats: [
@@ -311,6 +328,8 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
       let narration;
       if (e.tier === 'never') {
         narration = `${asked.replace('It asked', 'It tried')}. A never rule blocked it before ${V('anyone', 'you')} saw it.`;
+      } else if (timedOut(e)) {
+        narration = `${asked}. Nobody answered in ${w} seconds, so it was refused rather than allowed. The agent carried on without it.`;
       } else if (e.decision === 'allow') {
         narration = `${asked}. ${SUP} allowed it${e.scope === 'always' ? ' as a rule' : ''} after ${w} seconds.`;
       } else {
@@ -382,7 +401,7 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
   const notDone = denied.map((d) => {
     const ask = asks.find((a) => a.id === d.id);
     const input = ask?.input ?? d.input ?? {};
-    return { tool: d.tool, what: short(describeInput(d.tool, input), 90), by: d.tier === 'never' ? 'policy' : 'you' };
+    return { tool: d.tool, what: short(describeInput(d.tool, input), 90), by: d.tier === 'never' ? 'policy' : timedOut(d) ? 'timeout' : 'you' };
   });
   const head = canGit && !created?.attached ? git(worktree, ['rev-parse', '--short', 'HEAD']) : null;
   scenes.push({
@@ -391,11 +410,13 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
     narration: (() => {
       let n = `The agent reported: ${short(finalText, 150)}`;
       if (!notDone.length) return n;
-      const byHuman = notDone.filter((x) => x.by !== 'policy').length;
-      const byPolicy = notDone.length - byHuman;
+      const byHuman = notDone.filter((x) => x.by === 'you').length;
+      const byPolicy = notDone.filter((x) => x.by === 'policy').length;
+      const byTimeout = notDone.filter((x) => x.by === 'timeout').length;
       const parts = [];
       if (byHuman) parts.push(`${byHuman} ${byHuman === 1 ? 'was' : 'were'} refused by ${sup}`);
       if (byPolicy) parts.push(`${byPolicy} ${byPolicy === 1 ? 'was' : 'were'} blocked by policy before anyone saw ${byPolicy === 1 ? 'it' : 'them'}`);
+      if (byTimeout) parts.push(`${byTimeout} ${byTimeout === 1 ? 'was' : 'were'} refused because nobody answered`);
       return `${n} Read that with a caveat: ${plural(notDone.length, 'requested step')} never ran. ${parts.join(', and ')}.`;
     })(),
   });
@@ -650,10 +671,28 @@ const slug = BRANCH ? `${safe(sb.name)}--${safe(BRANCH)}` : `${sb.name}-${sb.id.
 const jsonPath = join(storyDirOut, `${slug}.json`);
 writeFileSync(jsonPath, JSON.stringify({ ...sb, scenes: sb.scenes.map(({ audio, ...s }) => s) }, null, 2));
 
+// Everything in a record came from an agent, so everything is hostile until
+// proven otherwise.
+//
+// This used to be `.replace('__RECAP__', json)`. With a string as the
+// replacement, JavaScript reads `$&`, `$\``, `$'` in it as instructions — so a
+// command containing `$\`` pasted the page's whole <head> into the record's
+// data, broke out of the script block, and ran text from the agent's command as
+// code in the reviewer's browser. Reproduced: the tab retitled itself. A
+// function as the replacement is taken literally.
+//
+// And inside a <script>, escaping `</script>` is not enough: `<!--` and
+// `<script` change how the HTML parser reads the block. Encoding every `<`, `>`
+// and `&` as \u escapes leaves nothing for it to act on, and JSON.parse reads
+// them back unchanged. U+2028/2029 are line terminators to older JavaScript.
+const scriptSafe = (value) => JSON.stringify(value)
+  .replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026')
+  .replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+const htmlSafe = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
 const html = readFileSync(templatePath, 'utf8')
-  .replace('__RECAP__', JSON.stringify(sb).replace(/<\/script>/gi, '<\\/script>'))
-  .replaceAll('__TITLE__', `${sb.name} · ${sb.scenes[0].title}`)
-  .replaceAll('__DESC__', `Recap of a Nearly session: ${sb.scenes[0].narration}`);
+  .replace('__RECAP__', () => scriptSafe(sb))
+  .replaceAll('__TITLE__', () => htmlSafe(`${sb.name} · ${sb.scenes[0].title}`))
+  .replaceAll('__DESC__', () => htmlSafe(`Recap of a Nearly session: ${sb.scenes[0].narration}`));
 const outPath = join(outDir, `${slug}.html`);
 writeFileSync(outPath, html);
 

package/scripts/detect.mjs

@@ -63,7 +63,8 @@ export function installed() {
 //   --agent=cursor,gemini   exactly these
 //   --agent=all             every adapter there is
 export function choose(repo, argv = []) {
-  const flag = argv.find((a) => a.startsWith('--agent='));
+  const at = argv.indexOf('--agent');
+  const flag = argv.find((a) => a.startsWith('--agent=')) ?? (at !== -1 && argv[at + 1] ? `--agent=${argv[at + 1]}` : undefined);
   if (flag) {
     const want = flag.slice('--agent='.length).split(',').map((s) => s.trim()).filter(Boolean);
     if (want.includes('all')) return { chosen: ADAPTERS, unknown: [] };