Repin: await the transcript scan, and shorten the backstop to a minute

The scan's cost was never the I/O, it was doing the I/O on the event
loop. claudeTranscriptsSince, transcriptHead, transcriptExists and
claudeCandidate now await instead of using the *Sync calls, and the
watcher tick is async.

Measured against the real bucket directory, same code path either way:

sync wall 1111-1260ms, ALL of it blocking the event loop
async wall 466ms cold / 5-8ms warm, 1ms of block at worst

So the cadence no longer has to trade staleness against freezing, and
SCAN_BACKSTOP_MS drops from 10 minutes to one. It now only limits how
often we walk the bucket for an answer the breadcrumb already gave, and
it doubles as the longest a pin stays stale if a crumb is ever lost.

Rearming moves out of tick into one place. An awaited tick that throws
surfaces as a rejected promise rather than an exception in a setTimeout
callback, so `run` catches, logs, and rearms: dropping the watcher would
silently stop following /clear for the rest of the pane's life. Exactly
one rearm per tick, so a failure can neither kill the watcher nor arm two
timers. The scan also re-reads the pin after awaiting rather than trusting
the value read at the top of the tick.

Left sync: firstLine, on the codex rollout path, which reads CODEX_HOME
on local disk rather than the bucket.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

server/src/runner.js

@@ -2,6 +2,7 @@ import os from 'node:os';
 import path from 'node:path';
 import pty from 'node-pty';
 import fs from 'node:fs';
+import fsp from 'node:fs/promises';
 import { remoteState, setPaused } from './remote.js';
 import { cliById, isRemote, STATE_DIR, WORKSPACES_DIR } from './config.js';
 import { update, list } from './sessions.js';
@@ -703,18 +704,21 @@ function codexRolloutsSince(sinceMs) {
 // truncate the JSON and make every capture silently fail.
 // The first line of a transcript that records a `cwd`, with its timestamp.
 // Bounded on lines AND bytes: a file-history-snapshot line can be megabytes.
-function transcriptHead(p) {
-  // openSync INSIDE the try: on the bucket mount a transcript can rotate away
+// Async, like the rest of the claude scan: every read here is against the FUSE
+// bucket, where a cold one costs tens of ms, and this is on the one event loop
+// that carries every session's PTY. See claudeTranscriptsSince.
+async function transcriptHead(p) {
+  // open() INSIDE the try: on the bucket mount a transcript can rotate away
   // between the stat that found it and this open, and the only caller runs in a
   // setTimeout where a throw is unhandled.
-  let fd = null;
+  let fh = null;
   try {
-    fd = fs.openSync(p, 'r');
+    fh = await fsp.open(p, 'r');
     const CHUNK = 65536, MAX_BYTES = 512 * 1024, MAX_LINES = 64;
     let carry = '', pos = 0, lines = 0;
     while (pos < MAX_BYTES && lines < MAX_LINES) {
       const b = Buffer.alloc(Math.min(CHUNK, MAX_BYTES - pos));
-      const n = fs.readSync(fd, b, 0, b.length, pos);
+      const { bytesRead: n } = await fh.read(b, 0, b.length, pos);
       if (!n) break;
       pos += n;
       carry += b.toString('utf8', 0, n);
@@ -731,7 +735,7 @@ function transcriptHead(p) {
       if (n < b.length) break; // EOF
     }
     return null;
-  } catch { return null; } finally { if (fd !== null) { try { fs.closeSync(fd); } catch {} } }
+  } catch { return null; } finally { if (fh) { try { await fh.close(); } catch {} } }
 }
 
 function firstLine(p) {
@@ -854,47 +858,70 @@ function claudeProjectDirs() {
 }
 
 // Every transcript, newest first, touched since `sinceMs`.
-function claudeTranscriptsSince(sinceMs) {
+//
+// Async, and that is the point rather than a style choice. This is a readdir per
+// project dir plus a stat per transcript, and on the Space CLAUDE_CONFIG_DIR is
+// on the FUSE bucket. Measured there over 32 transcripts: ~3ms when the mount's
+// attribute cache is warm, 1.1-1.3s when it is cold (~37ms per stat round trip).
+// The sync version spent all of that ON the one event loop that also carries
+// every session's PTY, so a cold scan was a hard freeze of every terminal — at
+// the REPIN_MS beat, once per live pane, every ~20 seconds.
+//
+// The awaited version does the same I/O for the same wall time, but on the
+// libuv threadpool: measured over 302 files, 11.6s of wall time for 26ms of
+// event-loop block. Sequential rather than Promise.all on purpose — 32 parallel
+// FUSE stats would saturate the 4-thread pool and push every other fs
+// operation in the process behind them, and nothing here is waiting on the
+// result.
+async function claudeTranscriptsSince(sinceMs) {
   const out = [];
   for (const proj of claudeProjectDirs()) {
     let dirs = [];
-    try { dirs = fs.readdirSync(proj, { withFileTypes: true }); } catch { continue; }
+    try { dirs = await fsp.readdir(proj, { withFileTypes: true }); } catch { continue; }
     for (const d of dirs) {
       if (!d.isDirectory()) continue;
       let files = [];
-      try { files = fs.readdirSync(path.join(proj, d.name)); } catch { continue; }
+      try { files = await fsp.readdir(path.join(proj, d.name)); } catch { continue; }
       for (const f of files) {
         if (!f.endsWith('.jsonl')) continue;
         const p = path.join(proj, d.name, f);
-        try { const st = fs.statSync(p); if (st.mtimeMs >= sinceMs) out.push({ p, m: st.mtimeMs }); } catch {}
+        try { const st = await fsp.stat(p); if (st.mtimeMs >= sinceMs) out.push({ p, m: st.mtimeMs }); } catch {}
       }
     }
   }
   return out.sort((a, b) => b.m - a.m);
 }
 
-const transcriptExists = (uuid) =>
-  !!uuid && claudeProjectDirs().some((proj) => {
+// Async for the same reason as claudeTranscriptsSince — plain loops rather than
+// .some(), which cannot await a predicate. Only reached when a re-pin is about to
+// happen, and only to say which of the two reasons it is.
+async function transcriptExists(uuid) {
+  if (!uuid) return false;
+  for (const proj of claudeProjectDirs()) {
     let dirs = [];
-    try { dirs = fs.readdirSync(proj, { withFileTypes: true }); } catch { return false; }
-    return dirs.some((d) => {
-      if (!d.isDirectory()) return false;
-      try { return fs.readdirSync(path.join(proj, d.name)).some((f) => f.startsWith(uuid)); } catch { return false; }
-    });
-  });
+    try { dirs = await fsp.readdir(proj, { withFileTypes: true }); } catch { continue; }
+    for (const d of dirs) {
+      if (!d.isDirectory()) continue;
+      try {
+        const files = await fsp.readdir(path.join(proj, d.name));
+        if (files.some((f) => f.startsWith(uuid))) return true;
+      } catch { /* dir vanished mid-walk */ }
+    }
+  }
+  return false;
+}
 
 // A transcript's opening cwd/timestamp never changes once written, and the
 // filename IS the conversation id, so a path is never reused for a different
 // conversation. That makes the head safe to remember — which matters because the
-// watcher rescans every REPIN_MS for the life of every session, and on the Space
-// these are synchronous reads against a FUSE mount. Without this, every tick
-// re-read every transcript on disk and would show up as event-loop lag.
+// watcher rescans for the life of every session, and on the Space these are reads
+// against a FUSE mount. Without this, every tick re-read every transcript on disk.
 const headMemo = new Map(); // transcript path -> head
 
-function transcriptHeadCached(p) {
+async function transcriptHeadCached(p) {
   const hit = headMemo.get(p);
   if (hit) return hit;
-  const head = transcriptHead(p);
+  const head = await transcriptHead(p);
   // Only remember a definite answer: null can just mean the file has no cwd line
   // yet (still being written), and caching that would poison it for the process.
   if (head) {
@@ -909,10 +936,10 @@ function transcriptHeadCached(p) {
 // what distinguishes a /clear-spawned successor from the thread it replaced —
 // both keep receiving mtime updates, only the successor is newly born.
 // Exported for server/test/repin.test.mjs.
-export function claudeCandidate(sessionId, workdir, sinceMs) {
+export async function claudeCandidate(sessionId, workdir, sinceMs) {
   const claimed = new Set(list().filter((s) => s.id !== sessionId && s.sessionUuid).map((s) => s.sessionUuid));
   let best = null;
-  for (const c of claudeTranscriptsSince(sinceMs)) {
+  for (const c of await claudeTranscriptsSince(sinceMs)) {
     const uuid = path.basename(c.p).replace(/\.jsonl$/, '');
     if (claimed.has(uuid)) continue;
     // The cwd is NOT on the first line: a transcript opens with metadata lines
@@ -920,7 +947,7 @@ export function claudeCandidate(sessionId, workdir, sinceMs) {
     // that have no cwd, and only the conversation lines carry one — line 4 or 5
     // in every real transcript measured. Reading line 1 made this check always
     // fail, so the re-pin could never actually claim anything.
-    const head = transcriptHeadCached(c.p);
+    const head = await transcriptHeadCached(c.p);
     // Only claim a conversation started in THIS session's folder.
     if (!head || head.cwd !== workdir) continue;
     const start = Date.parse(head.timestamp || '') || 0;
@@ -1066,19 +1093,14 @@ export function installClaudeRepinHook(hookCmd = '/app/scripts/am-repin-hook.sh'
 }
 
 // Once the pane's SessionStart hook has proven itself, the transcript scan is a
-// backstop rather than the mechanism, and it runs on this cadence instead of
-// REPIN_MS. The scan is the expensive half of a tick and the breadcrumb is the
-// authoritative one: `claudeTranscriptsSince` is a readdirSync per project dir
-// plus a statSync per transcript, and on the Space those land on the FUSE bucket
-// (CLAUDE_CONFIG_DIR is under /data). Measured there: ~3ms when the mount's
-// attribute cache is warm, 1.1-1.3s when it is cold — a synchronous block of the
-// one event loop that also carries every session's PTY. At the REPIN_MS beat,
-// once per live pane, that was a terminal freeze roughly every 20 seconds.
-//
-// This is the window in which a pin can be stale if a breadcrumb is ever LOST
-// (the hook fired but its crumb never reached us). The breadcrumb path itself
-// stays on the REPIN_MS beat — it reads one file on local disk and costs nothing.
-const SCAN_BACKSTOP_MS = 10 * 60_000;
+// backstop rather than the mechanism, so it runs on this cadence instead of
+// REPIN_MS. Now that the scan is awaited rather than synchronous this is no longer
+// about event-loop block time — it is only about not walking the bucket 3x a
+// minute per pane for an answer the breadcrumb already gave. So it can be short:
+// this is also the window in which a pin stays stale if a breadcrumb is ever LOST
+// (the hook fired but its crumb never reached us), and a minute of staleness in
+// that already-unlikely case costs one late Overview digest.
+const SCAN_BACKSTOP_MS = 60_000;
 
 /**
  * Should this tick run the transcript scan?
@@ -1105,8 +1127,13 @@ function scheduleClaudeCapture(session, workdir) {
   let hookProven = false;
   let lastScanAt = 0;
 
-  const tick = () => {
-    if (!isRunning(session.id)) { claudeCapturing.delete(session.id); return; }
+  // Returns whether to keep watching. Rearming is the caller's job (see `run`):
+  // the scan awaits now, so a throw lands as a rejected promise rather than as an
+  // exception in a setTimeout callback, and exactly one place deciding the next
+  // beat is what keeps a failed tick from either killing the watcher or arming
+  // two timers.
+  const tick = async () => {
+    if (!isRunning(session.id)) { claudeCapturing.delete(session.id); return false; }
     const pinned = (list().find((s) => s.id === session.id) || session).sessionUuid;
 
     // Breadcrumb first: the pane's own SessionStart hook told us which
@@ -1130,10 +1157,7 @@ function scheduleClaudeCapture(session, workdir) {
       if (verdict.repin) {
         console.warn(`[claude] re-pinning ${session.id}: ${pinned} -> ${verdict.repin} (breadcrumb, source: ${crumb.payload?.source || '?'})`);
         update(session.id, { sessionUuid: verdict.repin });
-        const t = setTimeout(tick, REPIN_MS);
-        if (t.unref) t.unref();
-        claudeCapturing.set(session.id, t);
-        return;
+        return true;
       }
       if (verdict.why !== 'already pinned') console.warn(`[claude] ${session.id}: breadcrumb rejected (${verdict.why})`);
     }
@@ -1144,22 +1168,38 @@ function scheduleClaudeCapture(session, workdir) {
         console.warn(`[claude] ${session.id}: folder shared with another live session — following /clear only via breadcrumbs here`);
       }
     } else if (claudeScanDue({ hookProven, lastScanAt })) {
-      lastScanAt = Date.now();
-      const hit = claudeCandidate(session.id, workdir, since);
-      if (hit && hit.uuid !== pinned) {
-        const why = transcriptExists(pinned) ? 'conversation was replaced (/clear)' : '--session-id was not honoured';
-        console.warn(`[claude] re-pinning ${session.id}: ${pinned} -> ${hit.uuid} (${why})`);
+      lastScanAt = Date.now(); // stamped BEFORE the await, so one scan is in flight at a time
+      const hit = await claudeCandidate(session.id, workdir, since);
+      // The scan yielded, so re-read the pin rather than trusting the one read at
+      // the top of this tick — a breadcrumb tick cannot have run (the next beat is
+      // armed only after this returns), but an explicit relaunch can have re-pinned.
+      const now = (list().find((s) => s.id === session.id) || session).sessionUuid;
+      if (hit && hit.uuid !== now) {
+        const why = await transcriptExists(now) ? 'conversation was replaced (/clear)' : '--session-id was not honoured';
+        console.warn(`[claude] re-pinning ${session.id}: ${now} -> ${hit.uuid} (${why})`);
         update(session.id, { sessionUuid: hit.uuid });
       }
     }
-    const t = setTimeout(tick, REPIN_MS);
+    return true;
+  };
+
+  // One rearm per tick, whatever the tick did. A tick that throws logs and keeps
+  // the watcher alive: dropping it would silently stop following /clear for the
+  // rest of the pane's life, which is the failure this whole mechanism exists for.
+  const run = () => tick()
+    .catch((e) => {
+      console.warn(`[claude] ${session.id}: repin tick failed (${e && e.message}) — retrying next beat`);
+      return isRunning(session.id);
+    })
+    .then((again) => { if (again) rearm(); else claudeCapturing.delete(session.id); });
+
+  function rearm(ms = REPIN_MS) {
+    const t = setTimeout(run, ms);
     if (t.unref) t.unref();
     claudeCapturing.set(session.id, t);
-  };
+  }
 
-  const t0 = setTimeout(tick, 5000);
-  if (t0.unref) t0.unref();
-  claudeCapturing.set(session.id, t0);
+  rearm(5000);
 }
 
 const opencodeCapturing = new Map(); // id -> pending re-pin timer

server/test/repin.test.mjs

@@ -56,25 +56,25 @@ const B = 'bbbbbbbb-0000-0000-0000-000000000002';
 console.log('\n/clear: the later-born conversation in this folder wins');
 transcript(A, { startMs: NOW });
 transcript(B, { startMs: NOW + 60_000 });
-check('follows the successor', runner.claudeCandidate('s1', WORKDIR, SINCE)?.uuid, B);
+check('follows the successor', (await runner.claudeCandidate('s1', WORKDIR, SINCE))?.uuid, B);
 
 console.log('\na conversation in a different folder is never claimed');
 transcript('cccccccc-0000-0000-0000-000000000003',
   { cwd: path.join(cfg.WORKSPACES_DIR, 'proj-b'), startMs: NOW + 120_000, projDir: '-proj-b' });
-check('other folder ignored', runner.claudeCandidate('s1', WORKDIR, SINCE)?.uuid, B);
+check('other folder ignored', (await runner.claudeCandidate('s1', WORKDIR, SINCE))?.uuid, B);
 
 console.log('\nan older thread that merely received writes is not a successor');
 transcript('dddddddd-0000-0000-0000-000000000004', { startMs: NOW - 3600_000, mtimeMs: NOW + 180_000 });
 check('pre-window thread rejected despite a fresh mtime',
-  runner.claudeCandidate('s1', WORKDIR, SINCE)?.uuid, B);
+  (await runner.claudeCandidate('s1', WORKDIR, SINCE))?.uuid, B);
 
 console.log('\na conversation another session has pinned is left to it');
 const rival = sessions.create({ name: 'rival', cli: 'claude', path: 'proj-a' });
 sessions.update(rival.id, { sessionUuid: B });
-check('claimed uuid skipped', runner.claudeCandidate('s1', WORKDIR, SINCE)?.uuid, A);
+check('claimed uuid skipped', (await runner.claudeCandidate('s1', WORKDIR, SINCE))?.uuid, A);
 
 console.log('\nnothing new in the window means no re-pin');
-check('no candidate', runner.claudeCandidate('s1', path.join(cfg.WORKSPACES_DIR, 'empty'), SINCE), null);
+check('no candidate', await runner.claudeCandidate('s1', path.join(cfg.WORKSPACES_DIR, 'empty'), SINCE), null);
 
 // ---------- breadcrumbs: attribution the scan cannot do in shared folders ----------
 const E = 'eeeeeeee-0000-0000-0000-000000000005';
@@ -129,23 +129,23 @@ try {
 }
 
 // ---------- scan cadence: the breadcrumb is the mechanism, the scan a backstop ----------
-// The scan is a readdirSync + a statSync per transcript, and CLAUDE_CONFIG_DIR is
-// on the FUSE bucket on the Space: ~1.2s of blocked event loop whenever the
-// mount's attribute cache is cold. At the REPIN_MS beat that froze the terminal
-// every ~20s per live pane, so once the hook has proven itself it steps down.
+// With the scan awaited the cadence is no longer about event-loop block time — it
+// is about not walking the bucket 3x a minute per pane for an answer the
+// breadcrumb already gave. So the backstop is a minute, and a minute is also the
+// longest a pin can stay stale if a crumb is ever lost.
 const MINUTE = 60_000;
 console.log('\nwithout a proven hook the scan runs every tick (unchanged)');
 check('no proof: due immediately', runner.claudeScanDue({ hookProven: false, lastScanAt: NOW }, NOW), true);
 check('no proof: still due 20s later',
   runner.claudeScanDue({ hookProven: false, lastScanAt: NOW }, NOW + 20_000), true);
 
-console.log('\na proven hook steps the scan down to a backstop cadence');
+console.log('\na proven hook steps the scan down to the backstop cadence');
 check('proven: not due on the next beat',
   runner.claudeScanDue({ hookProven: true, lastScanAt: NOW }, NOW + 20_000), false);
-check('proven: not due after 9 minutes',
-  runner.claudeScanDue({ hookProven: true, lastScanAt: NOW }, NOW + 9 * MINUTE), false);
-check('proven: due again after 10 minutes',
-  runner.claudeScanDue({ hookProven: true, lastScanAt: NOW }, NOW + 10 * MINUTE), true);
+check('proven: not due at 59s',
+  runner.claudeScanDue({ hookProven: true, lastScanAt: NOW }, NOW + MINUTE - 1000), false);
+check('proven: due again at a minute',
+  runner.claudeScanDue({ hookProven: true, lastScanAt: NOW }, NOW + MINUTE), true);
 
 console.log('\na proven pane still scans once before its first backstop');
 check('proven but never scanned: due',