Sessions: let the pane say which conversation it is on (#23)

PR #17 taught the re-pin watcher to follow /clear onto the successor
conversation, but it deliberately refuses in a folder shared by several live
claude sessions — a new transcript there cannot be attributed to a pane by
scanning. Folders like a busy project workspace ALWAYS have rivals, so /clear
there was never followed and a restart still resumed the pre-/clear thread.
Observed live: a pane /cleared on Aug 3, its successor absorbed a day of work,
and the Aug 4 restart brought back the abandoned thread and orphaned the rest.

Scanning cannot attribute, but the pane itself knows. A SessionStart hook
(scripts/am-repin-hook.sh, registered idempotently into settings.json at boot)
runs inside the pane's process tree, where $AM_ID names the pane and the
payload carries the new conversation's id. It drops a breadcrumb on local
disk; the watcher consumes it and re-pins with nothing to guess. The
shared-folder refusal now applies only to the scan fallback, which stays for
panes without a breadcrumb and for codex/opencode.

Breadcrumbs are trusted only after checks, because SessionStart fires more
widely than the docs admit (verified on 2.1.220 — print mode fires it too,
contradicting the documentation):

- $CLAUDE_PID must descend from the pane's tmux root. A nested `claude -p`
run inside a pane inherits $AM_ID and would otherwise claim the pane with a
throwaway conversation — worse than the bug. The hook's
CLAUDE_CODE_ENTRYPOINT=cli filter drops most of these; the pid check is the
backstop.
- The payload cwd must be the pane's folder, the id must not be pinned by
another session, and a no-matcher registration means source:"startup" also
replaces the "--session-id not honoured" heuristic with a fact, while
source:"resume" provably reports the unchanged id and stays a no-op.

Consumed-on-read so a stale crumb can never flip a pin backwards past a later
scan re-pin. Losing breadcrumbs at restart is harmless: the pin persists in
sessions.json and the relaunch's own resume event writes a fresh crumb —
which incidentally verifies the whole chain at every restart. The installer
merges into settings.json (never replaces — it also holds permissions and
model), is idempotent across boots, and refuses to touch a file it cannot
parse. Verified against a live config dir: adding hooks to an already-trusted
dir shows no trust prompt.

Co-authored-by: Claude <noreply@anthropic.com>

scripts/am-repin-hook.sh

@@ -0,0 +1,31 @@
+#!/bin/sh
+# SessionStart breadcrumb for the manager's conversation re-pin (runner.js).
+#
+# Claude Code runs this inside the pane's process tree, so $AM_ID — set by the
+# manager on the tmux session — says WHICH pane the new conversation belongs
+# to. That attribution is the one thing the server cannot work out on its own
+# when several claude panes share a folder, and it is why a /clear there could
+# not be followed before (the folderIsShared refusal in runner.js).
+#
+# stdin is the hook payload: {session_id, transcript_path, cwd, source, ...}.
+# $CLAUDE_PID is the claude process that fired the event; the server verifies
+# it descends from the pane before trusting the breadcrumb, because nested
+# runs (`claude -p` from inside a pane) inherit $AM_ID and would otherwise
+# claim the pane with a throwaway conversation. The entrypoint check below
+# already drops those non-interactive runs; the pid check covers the rest.
+#
+# Breadcrumbs live on LOCAL disk on purpose: losing them at a restart is
+# harmless (the pin itself persists in sessions.json), and the relaunch's own
+# source:"resume" event immediately writes a fresh one.
+[ -n "$AM_ID" ] || exit 0
+case "$AM_ID" in *[!a-zA-Z0-9_-]*) exit 0 ;; esac
+[ "$CLAUDE_CODE_ENTRYPOINT" = "cli" ] || exit 0
+case "$CLAUDE_PID" in '' | *[!0-9]*) CLAUDE_PID=0 ;; esac
+d="${AM_REPIN_DIR:-/tmp/am-repin}"
+mkdir -p "$d" 2>/dev/null || exit 0
+{
+  printf '{"amId":"%s","claudePid":%d,"payload":' "$AM_ID" "$CLAUDE_PID"
+  cat
+  printf '}'
+} > "$d/$AM_ID.json.tmp" 2>/dev/null && mv -f "$d/$AM_ID.json.tmp" "$d/$AM_ID.json"
+exit 0

server/src/index.js

@@ -16,7 +16,7 @@ import * as store from './sessions.js';
 import * as groups from './groups.js';
 import * as order from './order.js';
 import * as demo from './demo.js';
-import { attach, agentInfo, deriveState, stop, stopAll, ensureRunning, sendInput, isRunning, capturePane, ghosttyReady, ghosttyError } from './runner.js';
+import { attach, agentInfo, deriveState, stop, stopAll, ensureRunning, sendInput, isRunning, capturePane, ghosttyReady, ghosttyError, installClaudeRepinHook } from './runner.js';
 
 // Control frames ride the terminal socket behind a leading NUL pair, which real
 // PTY output never begins with. Same sentinel the old copy-mode hint used, so the
@@ -37,6 +37,10 @@ store.init();
 groups.init();
 order.init();
 demo.init();
+// Claude panes report conversation resets (e.g. /clear) through a SessionStart
+// hook, so the re-pin watcher can follow them even in shared folders where the
+// transcript scan must refuse to guess. Non-fatal if it can't be installed.
+installClaudeRepinHook();
 
 // One-time migration to the explicit-path model: sessions used to own a folder
 // named after them (renamed along with them), or inherit their group's shared

server/src/runner.js

@@ -944,6 +944,111 @@ function folderIsShared(sessionId, workdir, cli) {
 // session forward onto whatever conversation Claude is actually writing. One
 // mechanism now covers both failure modes: the launch-time fallback (pin never
 // honoured) and a /clear at any later point.
+
+// ---------- breadcrumbs: the pane tells us, so we don't have to guess ----------
+// The transcript scan above cannot attribute a new conversation when several
+// live claude panes share a folder — folderIsShared refuses, and a /clear in
+// such a folder was never followed. But the pane itself KNOWS: a SessionStart
+// hook (installed into settings.json below, script at scripts/am-repin-hook.sh)
+// runs inside the pane's process tree, where $AM_ID names the pane and the
+// payload carries the new conversation's id. It drops that as a breadcrumb
+// here; the watcher consumes it and re-pins with no guessing at all. The scan
+// stays as the fallback for panes without a breadcrumb (hook newly installed,
+// crumb lost) — and for codex/opencode, which have no hook mechanism.
+const REPIN_DIR = process.env.AM_REPIN_DIR || '/tmp/am-repin';
+
+// Read AND remove the pane's breadcrumb — consumed on read, so a stale crumb
+// can never flip a pin backwards after a later, scan-based re-pin.
+function takeClaudeBreadcrumb(sessionId) {
+  const p = path.join(REPIN_DIR, `${sessionId}.json`);
+  let raw;
+  try { raw = fs.readFileSync(p, 'utf8'); } catch { return null; }
+  try { fs.unlinkSync(p); } catch {}
+  try { return JSON.parse(raw); } catch { return null; }
+}
+
+// The pane's root process (what tmux spawned). After `exec claude` this IS
+// claude; in the `claude --session-id … || exec claude` branch claude is a
+// child of it. Either way the hook's $CLAUDE_PID must descend from it.
+function paneRootPid(sessionId) {
+  try {
+    const out = execFileSync('tmux', ['list-panes', '-t', tmuxName(sessionId), '-F', '#{pane_pid}'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: TERM_ENV });
+    const pid = parseInt(out.trim().split('\n')[0], 10);
+    return Number.isInteger(pid) && pid > 1 ? pid : null;
+  } catch { return null; }
+}
+
+// Walk /proc ppid links. comm in /proc/<pid>/stat may contain spaces and
+// parens, so split after the LAST ') '.
+function pidHasAncestor(pid, ancestor, readStat = (p) => fs.readFileSync(`/proc/${p}/stat`, 'utf8')) {
+  for (let p = pid, hops = 0; Number.isInteger(p) && p > 1 && hops < 64; hops++) {
+    if (p === ancestor) return true;
+    let stat;
+    try { stat = readStat(p); } catch { return false; }
+    const tail = stat.slice(stat.lastIndexOf(') ') + 2).split(' ');
+    p = parseInt(tail[1], 10); // state ppid …
+  }
+  return false;
+}
+
+// Pure verdict on one breadcrumb, exported for server/test/repin.test.mjs.
+// `facts` carries everything environmental: { workdir, pinned, claimed (Set of
+// uuids other sessions pin), pidTrusted (bool: claudePid descends from the
+// pane) }. Returns { repin: uuid } or { repin: null, why }.
+export function breadcrumbVerdict(crumb, sessionId, facts) {
+  if (!crumb || typeof crumb !== 'object') return { repin: null, why: 'unreadable' };
+  if (crumb.amId !== sessionId) return { repin: null, why: 'amId mismatch' };
+  const uuid = crumb.payload?.session_id;
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(uuid || ''))
+    return { repin: null, why: 'no session_id' };
+  // A crumb written before a pane was moved to another folder must not follow
+  // it there — same folder-scoping rule the transcript scan applies.
+  if (crumb.payload?.cwd !== facts.workdir) return { repin: null, why: 'cwd mismatch' };
+  // Nested `claude -p` runs inherit $AM_ID and fire SessionStart too (verified
+  // on 2.1.220 — the docs say -p skips hooks; it does not). The hook filters
+  // on CLAUDE_CODE_ENTRYPOINT, and this is the backstop: only a process that
+  // descends from the pane speaks for the pane.
+  if (!facts.pidTrusted) return { repin: null, why: 'pid not in pane' };
+  if (facts.claimed?.has(uuid)) return { repin: null, why: 'claimed by another session' };
+  if (uuid === facts.pinned) return { repin: null, why: 'already pinned' };
+  return { repin: uuid };
+}
+
+// Register the SessionStart hook in $CLAUDE_CONFIG_DIR/settings.json. Merge,
+// never replace: the file also holds permissions/model/theme. Idempotent — a
+// second boot finds the entry and writes nothing. A file that exists but does
+// not parse is left alone (clobbering the user's settings to install a hook
+// would be a terrible trade), and every failure is non-fatal: without the
+// hook the watcher simply keeps today's behaviour.
+export function installClaudeRepinHook(hookCmd = '/app/scripts/am-repin-hook.sh') {
+  const dir = process.env.CLAUDE_CONFIG_DIR;
+  if (!dir) return false;
+  const file = path.join(dir, 'settings.json');
+  let cfg = {};
+  try {
+    cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    if (e.code !== 'ENOENT') { console.warn(`[claude] not installing repin hook: ${file} unreadable (${e.message})`); return false; }
+  }
+  if (typeof cfg !== 'object' || cfg === null || Array.isArray(cfg)) { console.warn(`[claude] not installing repin hook: ${file} is not an object`); return false; }
+  const entries = Array.isArray(cfg.hooks?.SessionStart) ? cfg.hooks.SessionStart : [];
+  const present = entries.some((m) => (m?.hooks || []).some((h) => String(h?.command || '').includes('am-repin-hook.sh')));
+  if (present) return true;
+  // No matcher: fire for every source. `startup` replaces the "--session-id
+  // not honoured" heuristic with a fact, `resume` is a proven no-op (same id),
+  // and `clear` is the case this exists for. Filtering happens server-side.
+  cfg.hooks = cfg.hooks || {};
+  cfg.hooks.SessionStart = [...entries, { hooks: [{ type: 'command', command: hookCmd, timeout: 5 }] }];
+  try {
+    const tmp = `${file}.am-tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + '\n');
+    fs.renameSync(tmp, file);
+    console.warn(`[claude] repin hook installed in ${file}`);
+    return true;
+  } catch (e) { console.warn(`[claude] repin hook install failed: ${e.message}`); return false; }
+}
+
 function scheduleClaudeCapture(session, workdir) {
   // A relaunch restarts the watch with a fresh window, so `since` can't drift
   // older and start admitting pre-relaunch threads as candidates.
@@ -954,13 +1059,37 @@ function scheduleClaudeCapture(session, workdir) {
 
   const tick = () => {
     if (!isRunning(session.id)) { claudeCapturing.delete(session.id); return; }
+    const pinned = (list().find((s) => s.id === session.id) || session).sessionUuid;
+
+    // Breadcrumb first: the pane's own SessionStart hook told us which
+    // conversation it is on, so no guessing — and no shared-folder refusal —
+    // is needed. Consumed on read; a rejected crumb falls through to the scan.
+    const crumb = takeClaudeBreadcrumb(session.id);
+    if (crumb) {
+      const root = paneRootPid(session.id);
+      const verdict = breadcrumbVerdict(crumb, session.id, {
+        workdir,
+        pinned,
+        claimed: new Set(list().filter((s) => s.id !== session.id && s.sessionUuid).map((s) => s.sessionUuid)),
+        pidTrusted: !!root && pidHasAncestor(crumb.claudePid, root),
+      });
+      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;
+      }
+      if (verdict.why !== 'already pinned') console.warn(`[claude] ${session.id}: breadcrumb rejected (${verdict.why})`);
+    }
+
     if (folderIsShared(session.id, workdir, 'claude')) {
       if (!warnedShared) {
         warnedShared = true;
-        console.warn(`[claude] ${session.id}: folder shared with another live session — not following /clear here`);
+        console.warn(`[claude] ${session.id}: folder shared with another live session — following /clear only via breadcrumbs here`);
       }
     } else {
-      const pinned = (list().find((s) => s.id === session.id) || session).sessionUuid;
       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';

server/test/repin.test.mjs

@@ -76,6 +76,56 @@ check('claimed uuid skipped', runner.claudeCandidate('s1', WORKDIR, SINCE)?.uuid
 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);
 
+// ---------- breadcrumbs: attribution the scan cannot do in shared folders ----------
+const E = 'eeeeeeee-0000-0000-0000-000000000005';
+const crumb = (over = {}) => ({
+  amId: 's1', claudePid: 4242,
+  payload: { session_id: E, cwd: WORKDIR, source: 'clear' },
+  ...over,
+});
+const facts = (over = {}) => ({
+  workdir: WORKDIR, pinned: A, claimed: new Set([B]), pidTrusted: true, ...over,
+});
+const verdict = (c, f) => runner.breadcrumbVerdict(c, 's1', f);
+
+console.log('\na trusted breadcrumb re-pins, no folder-sharing question asked');
+check('clean crumb accepted', verdict(crumb(), facts()).repin, E);
+
+console.log('\na breadcrumb only speaks for the pane that wrote it');
+check('amId mismatch rejected', verdict(crumb({ amId: 's2' }), facts()).repin, null);
+check('cwd mismatch rejected',
+  verdict(crumb({ payload: { session_id: E, cwd: '/elsewhere', source: 'clear' } }), facts()).repin, null);
+
+console.log('\na nested claude -p cannot claim the pane (pid not under the pane root)');
+check('untrusted pid rejected', verdict(crumb(), facts({ pidTrusted: false })).repin, null);
+check('untrusted pid says why', verdict(crumb(), facts({ pidTrusted: false })).why, 'pid not in pane');
+
+console.log('\nno-ops and garbage stay no-ops');
+check('already-pinned crumb is a no-op',
+  verdict(crumb({ payload: { session_id: A, cwd: WORKDIR, source: 'resume' } }), facts()).why, 'already pinned');
+check('claimed uuid left to its session',
+  verdict(crumb({ payload: { session_id: B, cwd: WORKDIR, source: 'clear' } }), facts()).why, 'claimed by another session');
+check('malformed session_id rejected',
+  verdict(crumb({ payload: { session_id: 'not-a-uuid', cwd: WORKDIR } }), facts()).repin, null);
+check('null crumb rejected', verdict(null, facts()).repin, null);
+
+// ---------- hook installer: merge, never replace; idempotent; refuse corrupt ----------
+console.log('\ninstaller merges into existing settings and is idempotent');
+const settings = path.join(CFG, 'settings.json');
+fs.writeFileSync(settings, JSON.stringify({ model: 'opus', permissions: { allow: ['Bash'] } }));
+check('installs into existing file', runner.installClaudeRepinHook('/app/scripts/am-repin-hook.sh'), true);
+let s = JSON.parse(fs.readFileSync(settings, 'utf8'));
+check('other keys kept', s.model, 'opus');
+check('hook entry present', s.hooks.SessionStart.length, 1);
+check('second run is a no-op', runner.installClaudeRepinHook('/app/scripts/am-repin-hook.sh'), true);
+s = JSON.parse(fs.readFileSync(settings, 'utf8'));
+check('no duplicate entry', s.hooks.SessionStart.length, 1);
+
+console.log('\ninstaller refuses to clobber a corrupt settings file');
+fs.writeFileSync(settings, '{ not json');
+check('corrupt file left alone', runner.installClaudeRepinHook('/x.sh'), false);
+check('corrupt content untouched', fs.readFileSync(settings, 'utf8'), '{ not json');
+
 console.log(`\n${pass} passed, ${fail} failed`);
 fs.rmSync(TMP, { recursive: true, force: true });
 process.exit(fail ? 1 : 0);