nearly-cli 0.1.6 → 0.1.7

package/README.md

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

package/bin/nearly.mjs

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

package/package.json

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

package/scripts/attach.mjs

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

package/scripts/hook.mjs

@@ -87,7 +87,8 @@ if (adapter && adapter.normalize) {
 }
 
 try {
-  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}`, {
+  const hold = adapter?.holdMs ? `&hold=${adapter.holdMs}` : '';
+  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}${hold}`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: payload,

package/scripts/push-record.mjs

@@ -15,10 +15,14 @@ import { paths } from '../server/paths.mjs';
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const repo = resolve(process.argv[2] || '.');
 function configured() {
-  try {
-    const f = join(root, '.nearly.json');
-    if (existsSync(f)) return JSON.parse(readFileSync(f, 'utf8')).urlBase || '';
-  } catch { /* fall through to the env var */ }
+  for (const f of [paths.config(), join(root, '.nearly.json')]) {
+    try {
+      if (existsSync(f)) {
+        const u = JSON.parse(readFileSync(f, 'utf8')).urlBase;
+        if (u) return u;
+      }
+    } catch { /* try the next one */ }
+  }
   return '';
 }
 const URL_BASE = (process.env.NEARLY_URL_BASE || configured() || '').replace(/\/$/, '');

package/server/adapters.mjs

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

package/server/index.mjs

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

package/server/paths.mjs

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

package/ui/index.html

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