nearly-cli 0.1.17 → 0.1.20

package/README.md

@@ -146,8 +146,10 @@ npx nearly-cli
 
   · Claude Code sessions here are gated and recorded (run end to end against a live agent)
   · Cursor sessions here are gated and recorded (built to their published hook spec, not yet run against a live agent)
+  · Claude Code sessions opened in another folder are gated too, once they work in this repo
+  · restart any Claude Code or Cursor session already open — hooks are read when a session starts
   · upgrades reach this repo automatically
-  · the record is offered when you push
+  · the record is added to #12 on your next push — sessions from now on
 
   Now just work. Requests that need you appear at http://127.0.0.1:47653
   Nothing to leave running. Turn it off again with --off.
@@ -159,6 +161,25 @@ 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`.
 
+Three things that are easy to miss, and that the command now says out loud:
+
+- **Only sessions from now on.** A session already open keeps the hooks it
+  started with, which here means none. Restart it.
+- **The record reaches a pull request on a push.** Turning Nearly on for a branch
+  whose pull request already exists changes nothing on that pull request until
+  you push again. If that pull request is already merged, open a new one.
+- **Sessions opened somewhere else are covered.** Claude Code only reads a repo's
+  hooks for a session started in that repo, so a session opened one folder up —
+  a parent folder, a monorepo root, your home directory — used to edit the repo
+  with nothing gated and nothing recorded, while `nearly doctor` said all was
+  well. `nearly` now also adds one hook to Claude Code's user settings
+  (`~/.claude/settings.json`). It stays silent unless a call works in a repo
+  Nearly is on for; from then on that session is gated like one started there,
+  including calls that never mention the repo. Sessions that have nothing to do
+  with it pay a process start per tool call and never reach a server. It is
+  removed when you turn Nearly off for the last repo, and `nearly --local-only`
+  skips it.
+
 ### Where it installs
 
 `npx nearly-cli` installs a copy into `~/.nearly/runtime`, and the hooks call
@@ -205,7 +226,7 @@ Nothing about how you work changes. Open the repo in VS Code or a terminal, star
 1. **Reads run silently.** Anything that only looks at your code is allowed and logged.
 2. **Anything that changes or reaches out is held.** It appears at http://127.0.0.1:47653 with the command, what it can affect, and a countdown. Answer with `A` or `D`, or shift for always and never. Nobody answering means denied after two minutes.
 3. **The record builds itself** when the session ends.
-4. **At `git push`** the hook merges every session on that branch, prints what was refused, and asks whether to post it. Say no and the push just continues.
+4. **At `git push`** the hook merges every session on that branch, prints what was refused, and posts it to the branch's open pull request. When the agent opens the pull request itself, the record is posted right then.
 5. **Your reviewer opens the pull request** and the record is there, as one comment that updates on every push rather than a new one each time.
 
 ### For a team
@@ -356,16 +377,23 @@ node scripts/install-push-hook.mjs ~/code/my-app
 ```
 
 That installs a `pre-push` hook. On your next push it builds the branch record,
-prints what it found including anything refused, and — only if there is an open
-pull request — asks whether to post it. Answer `y` and it comments; anything else
-and the push just continues.
+prints what it found including anything refused, and posts it to the branch's
+open pull request — one comment, updated on every push after that.
+
+It used to ask first, in the terminal. That never happened in practice: the push
+that matters is the agent's own ("raise a PR"), an agent's push has no terminal,
+and so nothing was ever posted and every reviewer saw an empty pull request. The
+pull request is also usually opened after that push, so Nearly now posts as soon
+as it sees the agent run `gh pr create` too.
 
 Three rules it follows:
 
 - **It never blocks a push.** No sessions on the branch, no server, a crash, a
   timeout: it prints one dim line at most and exits 0.
-- **It never posts without you.** A record of what you refused is more revealing
-  than a diff. Publishing that to a shared pull request is your call, every time.
+- **Posting is on unless you turn it off.** The record includes every prompt word
+  for word. `nearly --no-post` stops posting for a repo and `nearly --post` turns
+  it back on; `NEARLY_NO_POST=1` stops it everywhere. A merged or closed pull
+  request is never posted to.
 - **It stays fast.** Narration is skipped by default, because a minute of `say`
   at every push is not acceptable. Set `NEARLY_AUDIO=1` when you want the good one.
 
@@ -472,6 +500,7 @@ The claim this project makes is testable: a reviewer who sees the session record
 - `server/index.mjs`, spawn sessions, hooks, policy, recorder, undo
 - `ui/index.html`, sessions, triage of pending approvals, rules, log
 - `scripts/attach.mjs`, install or remove the hooks in a repo of your own; `scripts/post-recap.mjs`, comment the recap on its PR
+- `scripts/outside.mjs`, the hook in Claude Code's user settings that gates sessions opened in another folder
 - `scripts/build-recap.mjs` + `ui/recap.template.html`, narrated recap page per session
 - `scripts/publish-pages.mjs`, build the `docs/` folder GitHub Pages serves
 - `scripts/install-push-hook.mjs` + `scripts/push-record.mjs`, hand the branch record over at `git push`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.17",
+  "version": "0.1.20",
   "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/runtime.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/outside.test.mjs test/posting.test.mjs test/runtime.test.mjs"
   }
 }

package/scripts/attach.mjs

@@ -10,9 +10,11 @@
 //     gated and recorded whether you start them in a terminal, in VS Code or in
 //     JetBrains. Claude Code always; Cursor, Antigravity, Copilot, Codex, Gemini
 //     and Windsurf when the repo shows signs of them, or on --agent=
-//   · a git pre-push hook, so the record is offered when the work leaves your
+//   · a git pre-push hook, so the record is posted when the work leaves your
 //     machine
 //   · where the records are published, read from the Nearly's own remote
+//   · one hook in Claude Code's user settings, so a session opened in another
+//     folder is gated when it works in this repo (--local-only to skip it)
 //
 // There is no server to remember. The hooks start it the first time they need
 // it, and if it cannot start, Claude Code falls back to its own prompts and
@@ -26,6 +28,9 @@ 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';
+import { installOutside, removeOutside, attachedRepos, userSettingsFile } from './outside.mjs';
+import { prForBranch } from './pr-state.mjs';
+import { postingOff, setPosting } from './posting.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const HOOK = join(root, 'scripts', 'hook.mjs');
@@ -146,6 +151,7 @@ const off = argv.includes('--off') || argv.includes('--detach');
 // 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 localOnly = argv.includes('--local-only');
 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
@@ -259,6 +265,28 @@ try {
   notes.push(`could not remember this repo for the dashboard: ${e.message}`);
 }
 
+// ---------------------------------------------------------------------------
+// Sessions opened in another folder
+// ---------------------------------------------------------------------------
+// Claude Code only reads this repo's hooks when a session starts here. The hook
+// in its user settings covers the rest, and stays only while some repo still
+// has Nearly on. Never from a pinned npx call: that would put a registry lookup
+// in front of every tool call in every session on the machine.
+if (!off && (argv.includes('--no-post') || argv.includes('--post'))) {
+  try { setPosting(repo, argv.includes('--post')); } catch (e) { notes.push(`could not save the posting choice: ${e.message}`); }
+}
+
+let reach = null;
+const claudeWired = wired.some((a) => a.id === 'claude-code');
+if (!off && claudeWired && !localOnly && (installed || runtime || !fromPackage)) {
+  try {
+    reach = installOutside((ev) => hookCmd(ev));
+    if (reach.error) { notes.push(`sessions opened in other folders are not covered: ${reach.error}`); reach = null; }
+  } catch (e) { notes.push(`sessions opened in other folders are not covered: ${e.message}`); }
+} else if (off || localOnly) {
+  try { if (!attachedRepos().length) removeOutside(); } catch { /* leave it: it answers nothing without repos */ }
+}
+
 // ---------------------------------------------------------------------------
 // A server from somewhere else, already holding the port
 // ---------------------------------------------------------------------------
@@ -347,6 +375,7 @@ if (off) {
     ? `  hooks removed: ${wired.map((a) => a.name).join(', ')}`
     : '  no agent hooks of ours were installed');
   console.log(push.status === 0 ? '  pre-push hook removed' : dim('  pre-push hook was not ours, left alone'));
+  console.log(dim('  restart any agent session open here; it keeps the hooks it started with'));
   console.log('');
   process.exit(0);
 }
@@ -364,9 +393,32 @@ 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}`);
 }
+if (reach) {
+  console.log(`  ${ok('·')} Claude Code sessions opened in another folder are gated too, once they work in this repo`);
+  console.log(`    ${dim(`a hook in ${userSettingsFile().replace(process.env.HOME || '~', '~')}; it stays silent everywhere else`)}`);
+} else if (claudeWired && !off) {
+  console.log(`  ${ok('·')} ${dim('only Claude Code sessions started in this folder are gated')}`);
+}
+// Hooks are read when a session starts. Someone who turns this on and carries on
+// in the window they already had is not gated at all, and nothing says so.
+if (wired.length) {
+  console.log(`  ${bold('·')} ${bold(`restart any ${wired.map((a) => a.name).join(' or ')} session already open`)} ${dim('— hooks are read when a session starts')}`);
+}
 console.log(`  ${ok('·')} ${dim(updateNote())}`);
 if (push.status === 0) {
-  console.log(`  ${ok('·')} the record is offered when you push`);
+  // Only sessions from now on are recorded, and the record reaches a pull
+  // request on a push. Said here, because the natural thing is to look at a pull
+  // request that already exists and wonder where the record is.
+  const pr = prForBranch(repo);
+  if (postingOff(repo)) {
+    console.log(`  ${ok('·')} the record is built on push but not posted ${dim('— nearly --post puts it on the pull request')}`);
+  } else if (pr.state === 'open') {
+    console.log(`  ${ok('·')} the record is posted to #${pr.number} on your next push ${dim('— sessions from now on; nearly --no-post stops it')}`);
+  } else if (pr.state === 'merged' || pr.state === 'closed') {
+    console.log(`  ${ok('·')} the record is posted on your next push ${dim(`— #${pr.number} for this branch is ${pr.state}, so open a new pull request first`)}`);
+  } else {
+    console.log(`  ${ok('·')} the record is posted to the pull request when it is opened, and updated on every push ${dim('— nearly --no-post stops it')}`);
+  }
 } 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.

package/scripts/build-recap.mjs

@@ -160,6 +160,22 @@ function patch(cwd, range, maxLines = 48) {
 const short = (s, n = 90) => { s = String(s ?? '').replace(/\s+/g, ' ').trim(); return s.length > n ? s.slice(0, n - 1) + '…' : s; };
 const secs = (ms) => (ms / 1000).toFixed(1);
 const plural = (n, w, ws = w + 's') => `${n} ${n === 1 ? w : ws}`;
+// "5221s" is a number nobody reads as an hour and a half.
+const clock = (s) => {
+  s = Math.round(s);
+  if (s < 90) return `${s}s`;
+  const h = Math.floor(s / 3600), m = Math.round((s % 3600) / 60);
+  return h ? `${h}h ${String(m).padStart(2, '0')}m` : `${Math.round(s / 60)}m`;
+};
+const spoken = (s) => {
+  s = Math.round(s);
+  if (s < 90) return plural(s, 'second');
+  const h = Math.floor(s / 3600), m = Math.round((s % 3600) / 60);
+  return h ? `${plural(h, 'hour')}${m ? ` ${plural(m, 'minute')}` : ''}` : plural(Math.round(s / 60), 'minute');
+};
+// Tools that only look. Anything else allowed without asking changed something,
+// and calling it read-only told a reviewer that edits were only reads.
+const READS = new Set(['Read', 'Grep', 'Glob', 'LS', 'WebFetch', 'WebSearch', 'TodoWrite']);
 
 function describeInput(tool, input = {}) {
   if (tool === 'Bash') return input.command || '';
@@ -253,6 +269,9 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
   // 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');
+  // With nobody watching, "waiting on a human: 0.0s" and "asked Anuj: 0" are not
+  // facts about the work, just columns about a supervisor who was not there.
+  const nobodyThere = unattended && !humanDecisions.length && !humanWaitMs && !asks.length;
   scenes.push({
     kind: 'cover',
     title: headlineBits.length ? headlineBits.join(', ') : 'A session with nothing to flag',
@@ -268,14 +287,14 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
     repo: worktree ? basename(worktree) : null,
     branch: created?.branch || null,
     stats: [
-      ['Ran for', `${durS.toFixed(0)}s`, ''],
-      [V('Waiting on a human', 'Waiting on you'), `${secs(humanWaitMs)}s`, 'ask'],
+      ['Ran for', clock(durS), ''],
+      ...(nobodyThere ? [] : [[V('Waiting on a human', 'Waiting on you'), `${secs(humanWaitMs)}s`, 'ask']]),
       ['Tool calls', String(toolUses.length), ''],
-      [V('Asked ' + AUTHOR, 'Asked you'), String(humanDecisions.length), ''],
+      ...(nobodyThere ? [] : [[V('Asked ' + AUTHOR, 'Asked you'), String(humanDecisions.length), '']]),
       ['Refused', String(denied.length), denied.length ? 'deny' : ''],
       ['Rolled back', String(undos.length), undos.length ? 'undo' : ''],
     ],
-    narration: `${sbRuns > 1 ? `${plural(sbRuns, 'agent session')} on this branch, ${durS.toFixed(0)} seconds in total` : `Agent ${name} ran for ${durS.toFixed(0)} seconds`} under ${supPoss} supervision. ${plural(toolUses.length, 'tool call')}, ${humanDecisions.length} held for a decision, ${denied.length} refused${undos.length ? `, ${plural(undos.length, 'turn')} rolled back` : ''}.`,
+    narration: `${sbRuns > 1 ? `${plural(sbRuns, 'agent session')} on this branch, ${spoken(durS)} in total` : `Agent ${name} ran for ${spoken(durS)}`}${nobodyThere ? ', with nobody watching' : ` under ${supPoss} supervision`}. ${plural(toolUses.length, 'tool call')}, ${nobodyThere ? '' : `${humanDecisions.length} held for a decision, `}${denied.length} refused${undos.length ? `, ${plural(undos.length, 'turn')} rolled back` : ''}.`,
   });
 
   // 2. intent. One scene per thing that was asked for, in order, so a branch
@@ -290,10 +309,13 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
   const flushQuiet = () => {
     if (!quiet.length) return;
     const tools = [...new Set(quiet.map((q) => q.tool))];
+    const onlyReads = quiet.every((q) => READS.has(q.tool));
+    const byRule = quiet.every((q) => !q.auto);
     scenes.push({
       kind: 'quiet',
+      onlyReads,
       items: quiet.map((q) => ({ tool: q.tool, sub: short(describeInput(q.tool, q.input), 80) })),
-      narration: `${plural(quiet.length, 'read-only step')} ran without asking: ${tools.join(', ')}. Logged, not gated.`,
+      narration: `${plural(quiet.length, onlyReads ? 'read-only step' : 'step')} ran without asking: ${tools.join(', ')}. ${onlyReads || byRule ? 'Logged, not gated.' : 'Nobody was watching, so nobody was asked; every one is logged.'}`,
     });
     quiet = [];
   };
@@ -318,7 +340,7 @@ function buildStoryboard({ id, events, runs: sbRuns = 1 }) {
       const tool = e.tool;
       const input = ask?.input ?? e.input ?? {};
       const res = results.find((r) => r.id === e.id);
-      if (e.tier === 'log') { quiet.push({ tool, input }); continue; }
+      if (e.tier === 'log') { quiet.push({ tool, input, auto: e.scope === 'auto' }); continue; }
       flushQuiet();
       const human = e.waitedMs != null;
       const w = human ? secs(e.waitedMs) : null;

package/scripts/doctor.mjs

@@ -17,6 +17,8 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { paths, dataRoot } from '../server/paths.mjs';
 import { ADAPTERS, OURS_RE } from '../server/adapters.mjs';
+import { outsideInstalled } from './outside.mjs';
+import { prForBranch } from './pr-state.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const repo = resolve(process.argv.slice(2).find((a) => !a.startsWith('--')) || process.cwd());
@@ -122,6 +124,13 @@ if (gated.length) {
   }
 }
 
+// A repo's own hooks only run for sessions started in it. Everything above can
+// be green while every session is opened one folder up and none of it is seen.
+if (gated.some((a) => a.id === 'claude-code')) {
+  if (outsideInstalled()) say(true, 'sessions opened in other folders', 'gated once they work in this repo');
+  else say(null, 'sessions opened in other folders', 'not gated — only Claude Code sessions started in this folder are. Run `nearly` here to cover them');
+}
+
 // 3 — the server, and whether it is this build
 let health = null;
 try {
@@ -207,14 +216,11 @@ if (!ghOk) {
   const auth = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8' }).status === 0;
   say(auth, 'GitHub CLI (gh)', auth ? 'installed and signed in' : 'installed but not signed in', 'run `gh auth login`');
   if (auth) {
-    const pr = spawnSync('gh', ['pr', 'view', '--json', 'number,url'], { cwd: repo, encoding: 'utf8' });
-    if (pr.status === 0) {
-      let url = '';
-      try { url = JSON.parse(pr.stdout).url; } catch { /* keep it blank */ }
-      say(true, 'open pull request', url);
-    } else {
-      say(null, 'open pull request', `none for ${branch} — raise one, then push again`);
-    }
+    const pr = prForBranch(repo);
+    if (pr.state === 'open') say(true, 'open pull request', pr.url);
+    else if (pr.state === 'merged' || pr.state === 'closed') {
+      say(null, 'open pull request', `none — #${pr.number} for ${branch} is ${pr.state}. Open a new one, then push again`);
+    } else say(null, 'open pull request', `none for ${branch} — raise one, then push again`);
   }
 }
 

package/scripts/hook.mjs

@@ -37,7 +37,8 @@ const root = join(dirname(fileURLToPath(import.meta.url)), '..');
 const args = process.argv.slice(2);
 const flag = args.find((a) => a.startsWith('--adapter='));
 const positional = args.filter((a) => !a.startsWith('--'));
-const [event, name = 'repo'] = positional;
+const [event] = positional;
+let name = positional[1] || 'repo';
 if (!event) process.exit(0);
 
 // An unknown id is a typo in a config file, not a reason to wedge the agent.
@@ -45,7 +46,9 @@ 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');
+let unattended = args.includes('--auto');
+// Written into Claude Code's user settings rather than a repo's: see outside.mjs.
+const outside = args.includes('--outside');
 
 const body = await new Promise((r) => {
   let s = '';
@@ -87,6 +90,28 @@ async function start() {
   return false;
 }
 
+// A session opened somewhere else. Decide whether this call is any of our
+// business before doing anything that costs more than reading a few small files.
+// Nothing goes to a server unless the answer is yes.
+let extra = '';
+if (outside) {
+  let hook = {};
+  try { hook = JSON.parse(body || '{}'); } catch { /* nothing to go on */ }
+  const { attachedRepos, concerns, launchedIn, rememberedRepo } = await import('./outside.mjs');
+  const repos = attachedRepos();
+  if (!repos.length) process.exit(0);
+  // Started in one of them: its own hooks are running, and answering twice would
+  // record every call twice. A subfolder is not certain to load them, so there
+  // both fire and the server keeps whichever arrives first.
+  if (repos.some((r) => r.real === launchedIn(hook))) process.exit(0);
+  const hit = ((event === 'pre-tool' || event === 'post-tool') ? concerns(hook, repos) : null)
+    || rememberedRepo(hook.session_id, repos);
+  if (!hit) process.exit(0);
+  name = hit.name;
+  unattended = hit.auto;
+  extra = `&outside=1&repo=${encodeURIComponent(hit.repo)}`;
+}
+
 let health = await up();
 if (health === 'stale') {
   // Take the port back rather than run whatever is already there. Nobody reads
@@ -118,7 +143,7 @@ if (adapter && adapter.normalize) {
 try {
   const hold = adapter?.holdMs ? `&hold=${adapter.holdMs}` : '';
   const auto = unattended ? '&auto=1' : '';
-  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}${hold}${auto}`, {
+  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}${hold}${auto}${extra}`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: payload,

package/scripts/outside.mjs

@@ -0,0 +1,173 @@
+// Sessions opened somewhere else.
+//
+// Claude Code reads a repo's .claude/settings.local.json only when a session is
+// started in that repo. Open it one folder up — a parent folder, a monorepo
+// root, your home directory — and edit the repo from there, and the repo's hooks
+// never run. Nothing was recorded, nothing was refused, and `nearly doctor`,
+// which checks the repo, said everything was fine. That was found by the person
+// who built this, which is how sure we can be that everyone else will hit it.
+//
+// So attach also writes one hook into Claude Code's user settings, which every
+// session reads. It is silent unless a call touches a repo Nearly is on for:
+//
+//   - a session started in such a repo already has that repo's own hooks, so
+//     this one steps aside;
+//   - a call whose working directory or file is inside such a repo is gated and
+//     recorded as that repo's, with that repo's own settings (--auto or not);
+//   - once a session has been gated this way, the rest of its calls are too —
+//     `rm -rf ~` does not mention the repo, and a gate that only looked at the
+//     repo's own paths would wave it through;
+//   - anything else answers nothing and costs a process start.
+//
+// The repo's own hook config stays the source of truth. The user-level hook
+// holds no list of its own; it reads which repos are on, and how, from the
+// repos themselves.
+
+import { readFileSync, existsSync, realpathSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname, resolve, sep, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { paths } from '../server/paths.mjs';
+import { OURS_RE, isOurs } from '../server/adapters.mjs';
+
+// Claude Code's user settings. CLAUDE_CONFIG_DIR moves them, and is also how the
+// tests keep this away from the real file.
+export const userSettingsFile = () =>
+  join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'settings.json');
+
+// The events worth hearing from a session opened elsewhere. SessionStart says
+// nothing about where the session will work, so it is left out.
+export const OUTSIDE_EVENTS = {
+  UserPromptSubmit: 'prompt', PreToolUse: 'pre-tool', PostToolUse: 'post-tool',
+  Stop: 'stop', SessionEnd: 'session-end',
+};
+
+const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+
+// The real path of p, or of its nearest existing parent with the rest appended:
+// a file the agent is about to create does not exist yet, and still belongs to
+// the repo it is being created in.
+export function realish(p) {
+  if (!p) return null;
+  let abs = resolve(String(p).replace(/^~(?=$|[\\/])/, homedir()));
+  const tail = [];
+  for (;;) {
+    try { return fold(join(realpathSync.native(abs), ...tail.reverse())); }
+    catch {
+      const up = dirname(abs);
+      if (up === abs) return fold(resolve(p));
+      tail.push(abs.slice(up.length).replace(/^[\\/]/, ''));
+      abs = up;
+    }
+  }
+}
+
+export const inside = (child, parent) =>
+  !!child && !!parent && (child === parent || child.startsWith(parent.endsWith(sep) ? parent : parent + sep));
+
+// The repos Nearly is on for with Claude Code, and how each was turned on. A repo
+// in the list whose hooks have since been removed by hand is not one.
+export function attachedRepos() {
+  let list = [];
+  try { list = JSON.parse(readFileSync(paths.repos(), 'utf8')); } catch { return []; }
+  const out = [];
+  for (const repo of Array.isArray(list) ? list : []) {
+    let cmd = null;
+    try {
+      const s = JSON.parse(readFileSync(join(repo, '.claude', 'settings.local.json'), 'utf8').replace(/^\uFEFF/, ''));
+      cmd = (s.hooks?.PreToolUse || []).flatMap((e) => e.hooks || []).map((h) => h.command)
+        .find((c) => typeof c === 'string' && OURS_RE.test(c));
+    } catch { continue; }
+    if (!cmd) continue;
+    const name = (cmd.match(/\bpre-tool\s+([a-z0-9-]+)/i) || [])[1] || 'repo';
+    out.push({ repo, real: realish(repo), name, auto: /\s--auto\b/.test(cmd) });
+  }
+  return out;
+}
+
+// Every path a call names: where it runs, the file it reads or writes, and any
+// absolute or home-relative path in a shell command.
+function pathsOf(hook) {
+  const found = [];
+  const i = hook.tool_input || {};
+  for (const k of ['file_path', 'path', 'notebook_path']) if (typeof i[k] === 'string') found.push(isAbsolute(i[k]) ? i[k] : resolve(hook.cwd || '.', i[k]));
+  if (hook.cwd) found.push(hook.cwd);
+  if (typeof i.command === 'string') {
+    // Rough on purpose. Reading a path that is not one costs a gated call at
+    // worst; missing one that is lets the call through ungated.
+    const words = i.command.split(/[\s;|&<>()]+/).map((w) => w.replace(/^[^\w~./\\:-]+|["']+$/g, '').replace(/^["']+/, '')).filter(Boolean);
+    words.forEach((w, n) => {
+      const afterCd = /^(?:cd|pushd)$/.test(words[n - 1] || '');
+      if (/^(?:~|\/|[A-Za-z]:[\\/])/.test(w)) found.push(w);
+      else if (afterCd || /[\\/]/.test(w)) found.push(resolve(hook.cwd || '.', w));
+    });
+  }
+  return found;
+}
+
+// The attached repo this call touches, if any.
+export function concerns(hook, repos) {
+  const touched = pathsOf(hook).map(realish);
+  return repos.find((r) => touched.some((p) => inside(p, r.real))) || null;
+}
+
+// Sessions already gated this way are remembered by the server; see marks.mjs.
+export { rememberOutside, rememberedRepo } from '../server/marks.mjs';
+
+// Where the session was started. Claude Code tells hooks outright; the payload's
+// cwd is the fallback, and is the same place until the agent changes directory.
+export const launchedIn = (hook) => realish(process.env.CLAUDE_PROJECT_DIR || hook.cwd);
+
+// ---------------------------------------------------------------------------
+// Writing and removing the user-level hook
+// ---------------------------------------------------------------------------
+
+function readSettings(file) {
+  if (!existsSync(file)) return null;
+  try { return JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, '')); }
+  catch { return undefined; }   // present but unreadable: never overwrite it
+}
+
+const outsideEntry = (e) => isOurs(e) && /--outside\b/.test(JSON.stringify(e));
+
+// cmdFor(event) is the same command the repo hooks run, without a repo name.
+export function installOutside(cmdFor) {
+  const file = userSettingsFile();
+  const s = readSettings(file);
+  if (s === undefined) return { error: `${file} could not be read, so it was left alone` };
+  const settings = s || {};
+  const hooks = settings.hooks || {};
+  for (const ev of Object.keys(hooks)) {
+    const kept = (hooks[ev] || []).filter((e) => !outsideEntry(e));
+    if (kept.length) hooks[ev] = kept; else delete hooks[ev];
+  }
+  for (const [their, ours] of Object.entries(OUTSIDE_EVENTS)) {
+    hooks[their] = [...(hooks[their] || []),
+      { hooks: [{ type: 'command', command: `${cmdFor(ours)} --outside`, timeout: ours === 'pre-tool' ? 600 : ours === 'session-end' ? 120 : 30 }] }];
+  }
+  settings.hooks = hooks;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { file };
+}
+
+export function removeOutside() {
+  const file = userSettingsFile();
+  const settings = readSettings(file);
+  if (!settings || !settings.hooks) return { removed: false };
+  let removed = false;
+  for (const ev of Object.keys(settings.hooks)) {
+    const before = settings.hooks[ev] || [];
+    const kept = before.filter((e) => !outsideEntry(e));
+    if (kept.length !== before.length) removed = true;
+    if (kept.length) settings.hooks[ev] = kept; else delete settings.hooks[ev];
+  }
+  if (!removed) return { removed: false };
+  if (!Object.keys(settings.hooks).length) delete settings.hooks;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { removed: true, file };
+}
+
+export function outsideInstalled() {
+  const s = readSettings(userSettingsFile());
+  return !!(s && s.hooks && Object.values(s.hooks).some((list) => (list || []).some(outsideEntry)));
+}

package/scripts/posting.mjs

@@ -0,0 +1,21 @@
+// Whether a repo's record is posted to its pull request on push. On unless it
+// was turned off for that repo, or for everything with NEARLY_NO_POST=1.
+
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
+import { paths } from '../server/paths.mjs';
+
+const key = (repo) => { try { return realpathSync.native(repo); } catch { return repo; } };
+const read = () => { try { return existsSync(paths.config()) ? JSON.parse(readFileSync(paths.config(), 'utf8')) : {}; } catch { return {}; } };
+
+export function postingOff(repo) {
+  if (process.env.NEARLY_NO_POST === '1') return true;
+  return (read().noPost || []).includes(key(repo));
+}
+
+export function setPosting(repo, on) {
+  const cfg = read();
+  const list = new Set(cfg.noPost || []);
+  if (on) list.delete(key(repo)); else list.add(key(repo));
+  cfg.noPost = [...list];
+  writeFileSync(paths.config(), JSON.stringify(cfg, null, 2) + '\n');
+}

package/scripts/pr-state.mjs

@@ -0,0 +1,20 @@
+// The pull request for the branch you are on, and whether it can still take a record.
+//
+// `gh pr view` finds a branch's pull request whatever state it is in. Everything
+// here used to read "found" as "open", so doctor reported a merged pull request
+// as the open one, and a push offered to post a record onto a conversation that
+// had already ended — where nobody reviewing will ever see it.
+
+import { spawnSync } from 'node:child_process';
+
+export function prForBranch(repo) {
+  if (spawnSync('gh', ['--version'], { encoding: 'utf8' }).status !== 0) return { state: 'no-gh' };
+  const r = spawnSync('gh', ['pr', 'view', '--json', 'number,url,state'], { cwd: repo, encoding: 'utf8', timeout: 15_000 });
+  if (r.status !== 0) {
+    return /not logged|authentication|gh auth/i.test(r.stderr || '') ? { state: 'signed-out' } : { state: 'none' };
+  }
+  try {
+    const { number, url, state } = JSON.parse(r.stdout);
+    return { state: String(state || 'OPEN').toLowerCase(), number, url };
+  } catch { return { state: 'none' }; }
+}

package/scripts/push-record.mjs

@@ -1,5 +1,11 @@
 // What the pre-push hook runs. Builds the branch's session record, shows what
-// it found, and asks whether to hand it to the reviewer.
+// it found, and puts it on the branch's open pull request.
+//
+// It used to ask first, in the terminal. But the push that matters is usually
+// made by the agent — "raise a PR" — and an agent's push has no terminal, so the
+// question was never asked and nothing was ever posted. The reviewer saw an
+// empty pull request on every branch Nearly had recorded. Now it posts, as one
+// comment that each push updates; `nearly --no-post` stops it for a repo.
 //
 //   node scripts/push-record.mjs <repo-path>
 //
@@ -9,7 +15,6 @@ import { readFileSync, existsSync } from 'node:fs';
 import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, spawnSync } from 'node:child_process';
-import { createInterface } from 'node:readline';
 import { paths } from '../server/paths.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
@@ -108,30 +113,23 @@ if (!hasGh) {
   console.log('');
   process.exit(0);
 }
-const pr = spawnSync('gh', ['pr', 'view', '--json', 'number,url'], { cwd: repo, encoding: 'utf8' });
-if (pr.status !== 0) {
-  const why = /not logged|authentication|gh auth/i.test(pr.stderr || '')
+const { prForBranch } = await import('./pr-state.mjs');
+const pr = prForBranch(repo);
+if (pr.state !== 'open') {
+  const why = pr.state === 'signed-out'
     ? 'gh is installed but not signed in. Run `gh auth login`, then push again.'
-    : 'No open pull request for this branch yet. Raise one, then push again to attach the record.';
+    : pr.state === 'merged' || pr.state === 'closed'
+      // Posting onto a finished conversation reaches nobody who is reviewing.
+      ? `The pull request for this branch, #${pr.number}, is already ${pr.state}. Open a new one, then push again to attach the record.`
+      : 'No open pull request for this branch yet. Raise one, then push again to attach the record.';
   console.log(dim(`  ${why}`));
   console.log('');
   process.exit(0);
 }
-const prUrl = (() => { try { return JSON.parse(pr.stdout).url; } catch { return null; } })();
-
-if (process.env.NEARLY_NO_TTY === '1' || !process.stdin.isTTY) {
-  console.log(dim('  No terminal to ask on, so nothing was posted.'));
-  console.log(dim(`  Post it yourself: node scripts/post-recap.mjs ${slug}${URL_BASE ? ` --url-base ${URL_BASE}` : ''}`));
-  console.log('');
-  process.exit(0);
-}
-
-const rl = createInterface({ input: process.stdin, output: process.stdout });
-const answer = await new Promise((r) => rl.question(`  Post this record to ${prUrl || 'the pull request'}? [y/N] `, r))
-  .finally(() => rl.close());
 
-if (!/^y(es)?$/i.test(String(answer).trim())) {
-  console.log(dim('  Not posted. Push continues.'));
+const { postingOff } = await import('./posting.mjs');
+if (postingOff(repo)) {
+  console.log(dim(`  Not posted: posting is off for this repo. \`nearly --post\` turns it back on.`));
   console.log('');
   process.exit(0);
 }
@@ -140,7 +138,7 @@ const postArgs = [join(root, 'scripts', 'post-recap.mjs'), slug];
 if (URL_BASE) postArgs.push('--url-base', URL_BASE);
 const post = spawnSync(process.execPath, postArgs, { cwd: root, encoding: 'utf8', timeout: 60_000 });
 console.log(post.status === 0
-  ? `  Posted. ${(post.stdout || '').trim()}`
+  ? `  Record ${(post.stdout || '').trim()} ${dim('(nearly --no-post stops this)')}`
   : red(`  Could not post: ${(post.stderr || post.stdout || '').trim().split('\n').pop()}`));
 console.log('');
 process.exit(0);

package/server/index.mjs

@@ -12,6 +12,7 @@ import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_TIER, ruleKey, classify as classifyWith } from './policy.mjs';
 import { paths } from './paths.mjs';
+import { rememberOutside } from './marks.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const PORT = Number(process.env.NEARLY_PORT || 47653);
@@ -242,6 +243,46 @@ function modelFromTranscript(p) {
   return null;
 }
 
+// "Raise a PR" pushes the branch first and opens the pull request second. The
+// push found no pull request to post to, and nothing happens after the pull
+// request exists — so on the agent's own branch, the one thing a reviewer opens
+// never had a record on it. When an agent opens one, post straight away, from a
+// process of its own so the agent is not kept waiting.
+const OPENED = /\bgh\s+pr\s+create\b/;
+function postWhenOpened(s, hook) {
+  const cmd = hook.tool_input?.command;
+  if (typeof cmd !== 'string' || !OPENED.test(cmd)) return;
+  const said = typeof hook.tool_response === 'string' ? hook.tool_response : JSON.stringify(hook.tool_response ?? '');
+  if (!/\/pull\/\d+/.test(said)) return;              // it did not open one
+  try {
+    const child = spawn(process.execPath, [path.join(ROOT, 'scripts', 'push-record.mjs'), s.worktree], {
+      cwd: s.worktree, detached: true, stdio: 'ignore',
+      env: { ...process.env, NEARLY_NO_UPDATE: '1', NEARLY_NO_TTY: '1' },
+    });
+    child.on('error', () => { /* the next push posts it */ });
+    child.unref();
+    record(s.id, { type: 'hook', event: 'record-posting', detail: 'pull request opened' });
+  } catch { /* the next push posts it */ }
+}
+
+// The most recent thing the person typed, from a Claude Code transcript.
+function promptFromTranscript(p) {
+  if (!p || !fs.existsSync(p)) return null;
+  try {
+    let last = null;
+    for (const l of fs.readFileSync(p, 'utf8').split('\n')) {
+      if (!l) continue;
+      let j; try { j = JSON.parse(l); } catch { continue; }
+      if (j.type !== 'user' || j.isMeta) continue;
+      const c = j.message?.content;
+      const text = typeof c === 'string' ? c
+        : Array.isArray(c) && !c.some((x) => x?.type === 'tool_result') ? c.filter((x) => x?.type === 'text').map((x) => x.text).join('\n') : '';
+      if (text && !/^<(?:command-|local-command|system-reminder)/.test(text.trim())) last = text;
+    }
+    return last;
+  } catch { return null; }
+}
+
 function turnDiff(cwd, base, maxLines = 200) {
   const from = base || 'HEAD';
   const numstat = git(cwd, ['diff', '--numstat', from]);
@@ -357,6 +398,8 @@ function decide(sid, id, decision, why, scope = 'once') {
   // 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);
+  s.answered ||= new Map();
+  s.answered.set(id, [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 });
@@ -389,10 +432,30 @@ const server = http.createServer(async (req, res) => {
     try { hook = JSON.parse(await readBody(req) || '{}'); } catch { /* keep {} */ }
     const ev = url.pathname.slice('/hooks/'.length);
     const attach = url.searchParams.get('attach');
+    // From the hook in Claude Code's user settings: a session started outside the
+    // repo. With a repo it touched that repo; without one, it is ours only if an
+    // earlier call already made it so, and otherwise gets no answer at all.
+    const outside = url.searchParams.get('outside') === '1';
+    const outsideRepo = outside ? url.searchParams.get('repo') : null;
+    if (outside && !attach && !(hook.session_id && sessions.has(hook.session_id))) return hookOk(res);
     let sidResolved = sidParam;
-    if (!sidResolved && attach && hook.session_id) {
+    if (!sidResolved && (attach || outside) && hook.session_id) {
       sidResolved = hook.session_id;
-      if (!sessions.has(sidResolved)) attachSession({ id: sidResolved, name: attach.replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 24) || 'repo', cwd: hook.cwd || process.cwd() });
+      if (!sessions.has(sidResolved) && attach) {
+        const made = attachSession({ id: sidResolved, name: attach.replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 24) || 'repo', cwd: outsideRepo || hook.cwd || process.cwd() });
+        // Its prompt went by before anything said the session was ours. The
+        // transcript still has it, and a record that starts mid-task without
+        // saying what was asked is missing the part a reviewer reads first.
+        if (outsideRepo) {
+          made.outside = true;
+          try { rememberOutside(sidResolved, outsideRepo); } catch { /* it is re-found by path next time */ }
+          // Later calls from this session may not mention the repo, and arrive
+          // without its settings; they keep the ones it was gated with.
+          made.auto = url.searchParams.get('auto') === '1';
+          const asked = promptFromTranscript(hook.transcript_path);
+          if (asked) { made.lastPrompt = { text: asked, at: Date.now() }; record(sidResolved, { type: 'prompt', text: asked.slice(0, 4000) }); }
+        }
+      }
     }
     const s = sessions.get(sidResolved);
     const sid = sidResolved;
@@ -410,7 +473,10 @@ const server = http.createServer(async (req, res) => {
       return hookOk(res);
     }
     if (ev === 'prompt') {
-      if (s) { s.state = 'working'; record(sid, { type: 'prompt', text: String(hook.prompt || '').slice(0, 4000) }); broadcast({ type: 'session-state', session: sid, state: s.state }); }
+      // The same prompt twice within a few seconds is one prompt heard by two hooks.
+      const text = String(hook.prompt || '');
+      const echo = s && s.lastPrompt && s.lastPrompt.text === text && Date.now() - s.lastPrompt.at < 5000;
+      if (s && !echo) { s.lastPrompt = { text, at: Date.now() }; s.state = 'working'; record(sid, { type: 'prompt', text: text.slice(0, 4000) }); broadcast({ type: 'session-state', session: sid, state: s.state }); }
       return hookOk(res);
     }
     if (ev === 'session-end') {
@@ -432,7 +498,7 @@ const server = http.createServer(async (req, res) => {
       // 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';
+      const unattended = url.searchParams.get('auto') === '1' || (outside && !!s?.auto);
       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();
@@ -444,10 +510,22 @@ 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, unattended }); return respond('deny', `never (${reason})`); }
+      // Already answered: the same call through a second hook — a repo's own and
+      // the user-level one, or VS Code reading two config files. Same answer,
+      // written down once.
+      if (hook.tool_use_id && s.answered?.has(id)) return respond(...s.answered.get(id));
+      const answer = (decision, why) => {
+        if (hook.tool_use_id) {
+          s.answered ||= new Map();
+          s.answered.set(id, [decision, why]);
+          if (s.answered.size > 500) s.answered.delete(s.answered.keys().next().value);
+        }
+        return respond(decision, why);
+      };
+      if (tier === 'never') { record(sid, { type: 'decision', id, decision: 'deny', why: reason, scope: 'policy', tool: shown, input: hook.tool_input, tier, unattended }); return answer('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})`);
+        return answer('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
@@ -470,10 +548,16 @@ const server = http.createServer(async (req, res) => {
     }
 
     if (ev === 'post-tool') {
-      if (s) record(sid, { type: 'post_tool', id: hook.tool_use_id, tool: hook.tool_label || hook.tool_name, duration_ms: hook.duration_ms, response: trim(hook.tool_response ?? '') });
+      const seen = s && hook.tool_use_id && s.posted?.has(hook.tool_use_id);
+      if (s && hook.tool_use_id) { s.posted ||= new Set(); s.posted.add(hook.tool_use_id); if (s.posted.size > 500) s.posted.delete(s.posted.values().next().value); }
+      if (s && !seen) record(sid, { type: 'post_tool', id: hook.tool_use_id, tool: hook.tool_label || hook.tool_name, duration_ms: hook.duration_ms, response: trim(hook.tool_response ?? '') });
+      if (s && !seen && s.attached && s.worktree) postWhenOpened(s, hook);
       return hookOk(res);
     }
     if (ev === 'stop') {
+      // One turn ending, heard by two hooks, is still one turn.
+      if (s && s.attached && s.lastStopAt && Date.now() - s.lastStopAt < 3000) return hookOk(res);
+      if (s && s.attached) s.lastStopAt = Date.now();
       if (s && s.attached) {
         s.turns += 1;
         s.state = 'idle';

package/server/marks.mjs

@@ -0,0 +1,40 @@
+// Claude Code sessions opened outside a repo, remembered once they have been
+// gated in it. Written by the server, read by the hook (scripts/outside.mjs).
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { paths } from './paths.mjs';
+
+// One small file per session, naming the repo.
+//
+// Later calls from such a session may not mention the repo at all, and still
+// have to be gated. Asking the server would put a network round trip in front of
+// every tool call of every Claude Code session on the machine, and asking one
+// from an older build got every one of those calls refused as an unknown
+// session. A file lookup costs neither.
+const safeId = (sid) => String(sid || '').replace(/[^A-Za-z0-9_-]/g, '').slice(0, 80);
+const WEEK = 7 * 24 * 60 * 60 * 1000;
+
+export function rememberOutside(sid, repo) {
+  const id = safeId(sid);
+  if (!id) return;
+  const dir = paths.outside();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, id), String(repo));
+  try {
+    for (const f of readdirSync(dir)) {
+      const full = join(dir, f);
+      if (Date.now() - statSync(full).mtimeMs > WEEK) rmSync(full, { force: true });
+    }
+  } catch { /* tidying is optional */ }
+}
+
+export function rememberedRepo(sid, repos) {
+  const id = safeId(sid);
+  if (!id) return null;
+  try {
+    const repo = readFileSync(join(paths.outside(), id), 'utf8').trim();
+    return repos.find((r) => r.repo === repo) || null;
+  } catch { return null; }
+}
+

package/server/paths.mjs

@@ -60,4 +60,7 @@ export const paths = {
   // with no link. Same lesson as recordings — anything a person configured
   // belongs in their space, not in ours.
   config: () => dataFile('NEARLY_CONFIG', 'config.json'),
+  // Claude Code sessions opened outside a repo that have been gated in it, so the
+  // hook can keep gating them without asking the server. See scripts/outside.mjs.
+  outside: () => process.env.NEARLY_OUTSIDE || join(dataRoot, 'outside'),
 };

package/server/policy.mjs

@@ -270,7 +270,10 @@ function expand(raw, st) {
   let s = String(raw);
   if (s === '~' || s.startsWith('~/') || s.startsWith('~\\')) s = path.join(os.homedir(), s.slice(1));
   else if (/^~[^/\\]/.test(s)) return { unknown: `another user's home directory (${raw})` };
-  const vars = { HOME: os.homedir(), USERPROFILE: os.homedir(), TMPDIR: process.env.TMPDIR || os.tmpdir(), TMP: os.tmpdir(), TEMP: os.tmpdir(), PWD: st.cwd };
+  // Variables set earlier on the same line count: `S=/tmp/scratch; rm -f $S/x`
+  // is a scratch file, and refusing it as "decided at run time" stopped real work.
+  // One set to something unknowable stays unknowable (null).
+  const vars = { HOME: os.homedir(), USERPROFILE: os.homedir(), TMPDIR: process.env.TMPDIR || os.tmpdir(), TMP: os.tmpdir(), TEMP: os.tmpdir(), PWD: st.cwd, ...(st.vars || {}) };
   s = s.replace(/\$\(\s*pwd\s*\)/g, () => st.cwd ?? '\0');
   s = s.replace(/\$\{?env:([A-Za-z_]+)\}?/gi, (_, k) => vars[k.toUpperCase()] ?? '\0');
   s = s.replace(/\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/g, (_, k) => vars[k] ?? '\0');
@@ -742,7 +745,13 @@ function stageReason(stage, pipe, idx, st, depth) {
 
 // What a command changes for the commands after it on the same line.
 function applyState(stage, st) {
-  const { argv, prog } = unwrap(stage.words);
+  const { argv, prog, assigns } = unwrap(stage.words);
+  // `NAME=value` on its own sets a shell variable for the rest of the line. With
+  // a command after it, it only sets that command's environment, and the shell
+  // has already expanded the line by then — so it changes nothing here.
+  const remember = (k, v) => { const x = expand(v, st); (st.vars ||= {})[k] = x.path ?? null; };
+  if (!prog) { for (const [k, v] of Object.entries(assigns)) remember(k, v); return; }
+  if (prog === 'unset') { for (const a of argv.slice(1)) if (st.vars) delete st.vars[a]; return; }
   if (['cd', 'pushd', 'set-location', 'sl', 'chdir'].includes(prog)) {
     const target = argv.slice(1).find((a) => !a.startsWith('-'));
     if (!target) { st.cwd = os.homedir(); return; }
@@ -753,7 +762,12 @@ function applyState(stage, st) {
   }
   if (prog === 'popd') { st.cwd = null; return; }
   if (prog === 'export') {
-    for (const a of argv.slice(1)) { const m = a.match(/^GIT_DIR=(.*)$/); if (m) st.gitDir = m[1]; }
+    for (const a of argv.slice(1)) {
+      const m = a.match(/^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/);
+      if (!m) continue;
+      if (m[1] === 'GIT_DIR') st.gitDir = m[2];
+      remember(m[1], m[2]);
+    }
     return;
   }
   if (prog !== 'git') return;
@@ -795,7 +809,7 @@ function analyze(src, st, depth = 0) {
 function stateFor(cwd) {
   const dir = cwd ? (real(cwd) || cwd) : null;
   const top = dir ? git(dir, ['rev-parse', '--show-toplevel']) : null;
-  return { cwd: dir, root: top ? (real(top) || top) : null, branch: null, gitDir: null, aliases: {} };
+  return { cwd: dir, root: top ? (real(top) || top) : null, branch: null, gitDir: null, aliases: {}, vars: {} };
 }
 
 // The reason a command must never run, or null. Exported for the tests, which

package/ui/recap.template.html

@@ -300,7 +300,7 @@ const render = {
   quiet: (s) => `
     <div class="eyebrow"><span class="lbl">Ran without asking</span>${T('auto', 'log tier')}</div>
     <div class="rows">${s.items.map((i) => `<div class="row"><span class="t">${esc(i.tool)}</span><span class="s" title="${esc(i.sub)}">${esc(i.sub)}</span>${T('auto', 'receipt')}</div>`).join('')}</div>
-    <div class="sub" style="margin-top:auto">Read-only tools run on the log tier. Nobody was asked, but every call is on the record.</div>`,
+    <div class="sub" style="margin-top:auto">${s.onlyReads === false ? 'Allowed without anyone being asked. Every call is on the record.' : 'Read-only tools run on the log tier. Nobody was asked, but every call is on the record.'}</div>`,
 
   decision: (s) => {
     const d = s.tier === 'never' ? 'never' : s.decision;