convene-cli 1.5.1 → 1.7.0

package/dist/commands/init.js

@@ -209,7 +209,10 @@ function registerHook(noHook) {
         if (raw !== null)
             node_fs_1.default.writeFileSync(hook_1.SETTINGS_PATH + '.bak', raw);
         node_fs_1.default.writeFileSync(hook_1.SETTINGS_PATH, (0, hook_1.serializeSettings)((0, hook_1.withHook)(settings)));
-        log(`Registered UserPromptSubmit hook in ${hook_1.SETTINGS_PATH}${raw !== null ? ' (backup: settings.json.bak)' : ''}.`);
+        log(`Registered the lightweight \`convene fetch\` UserPromptSubmit hook in ${hook_1.SETTINGS_PATH}${raw !== null ? ' (backup: settings.json.bak)' : ''}.`);
+        log('  ↳ This is the ONE global write: it fires in every repo (a silent no-op off the bus) and is ' +
+            'ADDITIVE — your own hooks are left untouched. Prefer not to touch ~/.claude? Re-run with ' +
+            '`--no-hook`; the committed project `.claude/settings.json` hook still covers this repo.');
     }
     catch (err) {
         log(`Could not write settings (${err?.message}). Add this hook manually:`);
@@ -265,6 +268,13 @@ const COORD_HOOKS = [
         verb: 'gate-push',
         note: 'release the deploy lane after a push (idempotent)',
     },
+    {
+        event: 'PostToolUse',
+        matcher: 'Edit|Write|MultiEdit',
+        command: 'convene beat --stdin',
+        verb: 'beat',
+        note: 'debounced session activity-beat so a heads-down session still pulses on the bus',
+    },
 ];
 /**
  * Wire the WP13 coordination hooks into a settings file (global or committed

package/dist/commands/session-start.js

@@ -7,7 +7,8 @@ exports.sessionStart = sessionStart;
  * FAIL-OPEN (P0-FAILSAFE), copying the fetch.ts scaffold:
  *   - hard watchdog at 6000ms → exit 0 no matter what (SessionStart's own default
  *     timeout is 30s, which would stall a boot — we bound it ourselves);
- *   - the network GET is bounded at 4000ms;
+ *   - the network GET is bounded at FETCH_TIMEOUT_MS (default 4000ms; overridable
+ *     via CONVENE_FETCH_TIMEOUT_MS for deterministic tests);
  *   - any error / non-bus repo / DEGRADED emits NOTHING and exits 0.
  *
  * What it does on a fresh, authenticated bus repo:
@@ -22,11 +23,14 @@ const node_child_process_1 = require("node:child_process");
 const git_1 = require("../git");
 const config_1 = require("../config");
 const cache_1 = require("../cache");
+const worktree_1 = require("./worktree");
 const api_1 = require("../api");
 const render_1 = require("../render");
 const catchup_1 = require("./catchup");
 const exit_1 = require("../exit");
-const FETCH_TIMEOUT_MS = 4000;
+// Default 4000ms; overridable via CONVENE_FETCH_TIMEOUT_MS (tests drive it small for
+// deterministic, load-independent latency-budget assertions). See config.ts.
+const FETCH_TIMEOUT_MS = (0, config_1.resolveFetchTimeoutMs)();
 const WATCHDOG_MS = 6000;
 const MAX_ITEMS = 400;
 // Don't relaunch the watch daemon if one stamped a heartbeat this recently — a
@@ -36,14 +40,23 @@ const WATCH_FRESH_SEC = 60;
  * Launch `convene watch` as a DETACHED background daemon (§4.4): the watch runs
  * for the life of the session surfacing mid-task halts, so it must NOT be a
  * blocking hook entry. Best-effort + fail-open: any error is swallowed; a launch
- * failure never wedges the boot. Skipped if a recent heartbeat shows a watcher is
- * already alive for this slug.
+ * failure never wedges the boot.
+ *
+ * Two dedup guards (the daemon-leak fix) prevent piling up duplicate watchers:
+ *   1. authoritative — the scope's pidfile names a process that is STILL ALIVE
+ *      (survives even a long quiet gap where the heartbeat would have gone stale);
+ *   2. cheap fast-path — a heartbeat stamped within WATCH_FRESH_SEC.
+ * The detached spawn inherits this process's env (so CLAUDE_CODE_SESSION_ID flows
+ * to the child, scoping its pidfile/liveness to the owning session).
  */
 function launchWatch(slug) {
     try {
+        const owner = (0, cache_1.readWatchPid)(slug);
+        if (owner && (0, cache_1.isPidAlive)(owner.pid))
+            return; // a live watcher already owns this scope
         const age = (0, cache_1.watchHeartbeatAgeSec)(slug);
         if (age !== null && age < WATCH_FRESH_SEC)
-            return; // already watching
+            return; // recently heartbeating
         const child = (0, node_child_process_1.spawn)(process.execPath, [process.argv[1], 'watch'], {
             detached: true,
             stdio: 'ignore',
@@ -57,6 +70,51 @@ function launchWatch(slug) {
 function emit(s) {
     process.stdout.write(s + '\n');
 }
+/**
+ * SOFT auto-isolate: if this session booted INTO a checkout that already has a
+ * live sibling, provision a fresh isolated worktree and return a relocate block
+ * to emit (best-effort, never throws). The deterministic TIEBREAK that prevents a
+ * relocation storm: at SessionStart this session has not yet written its own feed
+ * `.json` (that only happens on the first `convene fetch`), so liveSessionCount is
+ * purely the INCUMBENT count. Only the session booting into an occupied checkout
+ * sees count >= 1 and moves; the incumbents, having no live sibling pulse newer
+ * than their own at their boot, never moved — exactly one side relocates.
+ *
+ * The full gate (ALL must hold):
+ *   - a session discriminator exists (we are a disambiguable concurrent session);
+ *   - >= 1 live sibling within the wide window (a co-tenant exists at all);
+ *   - >= 1 live sibling within the TIGHT recency window (relaunch-ghost guard — a
+ *     stale just-closed sibling's `.json` aged past this window won't trigger);
+ *   - not already auto-isolated for THIS instance (the per-instance sentinel, so a
+ *     resume/clear of an already-relocated session does not re-provision).
+ *
+ * Returns the relocate block string on a successful provision, else null. Fail-OPEN
+ * on every branch — any failure means "no relocation", and the boot proceeds.
+ */
+function maybeAutoIsolate(top, slug, instance) {
+    try {
+        // Gate 1: we must be a disambiguable concurrent session (have a discriminator).
+        if (!(0, git_1.sessionDiscriminator)())
+            return null;
+        // Gate 2: at least one live INCUMBENT sibling exists in the wide window.
+        if ((0, cache_1.liveSessionCount)(slug, cache_1.LIVE_SESSION_WINDOW_SEC) < 1)
+            return null;
+        // Gate 3: recency — a sibling pulsed within the tight window (relaunch-ghost guard).
+        if ((0, cache_1.liveSessionCount)(slug, cache_1.LIVE_SESSION_RECENT_SEC) < 1)
+            return null;
+        // Gate 4: idempotency — already relocated this exact instance? do nothing.
+        if ((0, cache_1.autoIsolatedAlready)(slug, instance))
+            return null;
+        const res = (0, worktree_1.provisionAutoWorktree)(top, slug);
+        if (!res)
+            return null; // provisioning failed → fail-open, no relocation
+        (0, cache_1.markAutoIsolated)(slug, instance);
+        return (0, render_1.renderRelocateBlock)(res);
+    }
+    catch {
+        return null; // fail-open: never let auto-isolate wedge a boot
+    }
+}
 async function run(opts) {
     const top = (0, git_1.gitToplevel)();
     if (!top)
@@ -72,15 +130,24 @@ async function run(opts) {
     const session = (0, git_1.sessionId)(member, top);
     // Mint a fresh instance for THIS boot (a fresh boot = a fresh instance).
     const instance = (0, cache_1.mintSessionInstance)(slug);
+    // SOFT auto-isolate (evaluated NOW, before this session writes its own feed
+    // .json): if a live sibling already occupies this checkout, provision a fresh
+    // isolated worktree and stage a relocate block. Best-effort; null = no move.
+    const relocateBlock = maybeAutoIsolate(top, slug, instance);
     // Launch the detached watch daemon from the SessionStart path (not a Bash hook).
     launchWatch(slug);
     const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
     const since = opts.since != null ? Number(opts.since) : undefined;
     const res = await api.sessionOpen(slug, { since: Number.isFinite(since) ? since : undefined, advance: true, maxItems: MAX_ITEMS }, FETCH_TIMEOUT_MS);
-    // DEGRADED / failure → emit NOTHING (structural suppression). Still record the
-    // sentinel so the first fetch doesn't double-surface from its own cache path.
+    // DEGRADED / failure → emit NOTHING from the catch-up digest (structural
+    // suppression). Still record the sentinel so the first fetch doesn't
+    // double-surface from its own cache path. The relocate block is INDEPENDENT of
+    // the network digest (it is purely local filesystem signal), so it is still
+    // surfaced — moving off an occupied checkout shouldn't depend on bus liveness.
     if (!res.ok || !res.json || res.json.degraded) {
         (0, cache_1.markCatchupSurfaced)(slug, instance);
+        if (relocateBlock)
+            emit(relocateBlock);
         return;
     }
     if (opts.json) {
@@ -89,6 +156,9 @@ async function run(opts) {
     else {
         emit((0, render_1.renderSessionOpenBlock)({ slug, member, session, digest: (0, catchup_1.toDigest)(res.json) }));
     }
+    // Emit the relocate block AFTER the digest (both are surfaced — digest then move).
+    if (relocateBlock)
+        emit(relocateBlock);
     (0, cache_1.markCatchupSurfaced)(slug, instance);
 }
 async function sessionStart(opts = {}) {

package/dist/commands/watch-reap.js

@@ -0,0 +1,212 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseReapableWatchers = parseReapableWatchers;
+exports.excludeSpared = excludeSpared;
+exports.reapWatchers = reapWatchers;
+exports.watchReap = watchReap;
+/**
+ * `convene watch-reap` — the cleanup half of the daemon-leak fix.
+ *
+ * Detached `convene watch` daemons spawned at SessionStart outlive their session
+ * and reparent to PID 1; before the self-termination ceilings (see watch.ts) they
+ * leaked forever (145 observed). New watchers now self-exit, but this verb mops up
+ * the ALREADY-ORPHANED backlog and is also invoked by `convene doctor --fix`.
+ *
+ * THE PPID-1 SUBTLETY (load-bearing): the SessionStart hook spawns the watcher
+ * detached+unref and exits IMMEDIATELY, so a watcher reparents to PID 1 within
+ * seconds EVEN WHILE its session is alive. ppid===1 therefore does NOT distinguish
+ * a dead-session orphan from a live session's watcher. Selection is two-gated:
+ *   1. parseReapableWatchers — ppid===1 + a tight argv match (the candidate set);
+ *   2. SPARE the living — drop any candidate whose pid is named by a `*.watch.pid`
+ *      file AND is still alive. A post-fix watcher always writes its scoped
+ *      pidfile, so a live, pidfile-owned watcher is by definition a current owner,
+ *      never a dead-session orphan.
+ * Caveat: the FIRST reap after a user upgrades may kill their currently-running
+ * OLD-cli watcher — a pre-fix watcher wrote NO pidfile, so it is indistinguishable
+ * from a true orphan. That is acceptable: it self-heals on the next SessionStart,
+ * and from then on every live new-cli watcher carries a pidfile and is spared.
+ *
+ * Fail-open + POSIX-only: any error returns a benign empty result, never throws.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
+const cache_1 = require("../cache");
+/**
+ * PURE candidate selector (unit-tested): from `ps -eo pid,ppid,args` output,
+ * return the pids of processes that LOOK like detached convene watchers orphaned
+ * to init. This is the FIRST of two gates — the live-pidfile spare filter
+ * (see reapWatchers) is the second.
+ *
+ * Match TIGHTLY to avoid collateral damage:
+ *   - the args must reference the convene bin (its basename — `index.js` for the
+ *     installed CLI, or the bin name like `convene`) AND end with `watch` as the
+ *     FINAL token (the detached watcher's exact shape: `node <bin> watch`);
+ *   - never a bare `watch`, an `npm run watch`, or any process that merely
+ *     contains the word watch elsewhere;
+ *   - exclude `selfPid` (the reaper itself, were it ever named similarly);
+ *   - select ONLY ppid === 1 (orphaned to init). NOTE this also catches live
+ *     sessions' watchers (see the header) — the spare gate, not this, protects them.
+ */
+function parseReapableWatchers(psOutput, conveneBin, selfPid) {
+    const binBase = conveneBin ? node_path_1.default.basename(conveneBin) : '';
+    const out = [];
+    for (const line of (psOutput || '').split('\n')) {
+        const s = line.trim();
+        if (!s)
+            continue;
+        // "  PID  PPID  ARGS..." — split off the first two numeric columns; the rest
+        // (which may contain spaces) is the command line.
+        const m = s.match(/^(\d+)\s+(\d+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const pid = parseInt(m[1], 10);
+        const ppid = parseInt(m[2], 10);
+        const args = m[3];
+        if (!Number.isFinite(pid) || !Number.isFinite(ppid))
+            continue;
+        if (pid === selfPid)
+            continue; // never reap ourselves
+        if (ppid !== 1)
+            continue; // only orphans
+        const tokens = args.split(/\s+/).filter(Boolean);
+        if (tokens.length < 2)
+            continue;
+        // `watch` must be the FINAL token (the watcher takes no positional args after
+        // the verb; --notify/--project flags would precede nothing meaningful, but to
+        // stay strict we require it dead-last as the spawn shape guarantees).
+        if (tokens[tokens.length - 1] !== 'watch')
+            continue;
+        // The bin must appear among the args (basename match handles absolute paths).
+        const looksConvene = (binBase && tokens.some((t) => node_path_1.default.basename(t) === binBase)) ||
+            tokens.some((t) => node_path_1.default.basename(t) === 'convene' || node_path_1.default.basename(t) === 'index.js');
+        if (!looksConvene)
+            continue;
+        out.push(pid);
+    }
+    return out;
+}
+/**
+ * PURE second gate (unit-tested): the candidates NOT in `sparePids`. A spared pid
+ * is a live, pidfile-owned watcher (a current session's owner) — never reaped.
+ */
+function excludeSpared(candidatePids, sparePids) {
+    const spare = new Set(sparePids);
+    return candidatePids.filter((p) => !spare.has(p));
+}
+/**
+ * Synchronous bounded sleep for the SIGTERM→SIGKILL grace. Uses `sleep(1)` (POSIX
+ * — and we're already past the win32 guard) so it does NOT peg a core like a busy
+ * spin would; reapWatchers stays synchronous so doctor can call it inline. Falls
+ * back to a brief busy-wait only if `sleep` is somehow unavailable.
+ */
+const sleepSync = (sec) => {
+    try {
+        const r = (0, node_child_process_1.spawnSync)('sleep', [String(sec)], { timeout: Math.ceil(sec * 1000) + 1000 });
+        if (r.status === 0)
+            return;
+    }
+    catch {
+        /* fall through to the busy-wait */
+    }
+    const until = Date.now() + sec * 1000;
+    while (Date.now() < until) {
+        /* fallback only */
+    }
+};
+/**
+ * Find + (unless dryRun) kill orphaned convene watchers, SPARING any watcher a
+ * live session still owns (named by a live `*.watch.pid`). SIGTERM each, give a
+ * short grace, then SIGKILL any survivor. Never throws — every failure path
+ * returns a benign result. POSIX-only (win32 returns an empty noted result).
+ */
+function reapWatchers({ dryRun = false } = {}) {
+    if (process.platform === 'win32') {
+        return { found: 0, killed: 0, pids: [], spared: 0, note: 'reap is POSIX-only' };
+    }
+    let psOut = '';
+    try {
+        const r = (0, node_child_process_1.spawnSync)('ps', ['-eo', 'pid,ppid,args'], { encoding: 'utf8', timeout: 5000 });
+        if (r.status !== 0 || !r.stdout)
+            return { found: 0, killed: 0, pids: [], spared: 0, note: 'ps unavailable' };
+        psOut = r.stdout;
+    }
+    catch {
+        return { found: 0, killed: 0, pids: [], spared: 0, note: 'ps failed' };
+    }
+    const bin = process.argv[1] || '';
+    const candidates = parseReapableWatchers(psOut, bin, process.pid);
+    // SPARE live-owned watchers: a current session's watcher is ppid 1 too (see the
+    // header), so the only safe discriminator is its live pidfile. Union all scopes'
+    // recorded pids, keep the live ones, and exclude them from the kill-set.
+    const sparePids = (0, cache_1.readAllWatchPids)().filter(cache_1.isPidAlive);
+    const pids = excludeSpared(candidates, sparePids);
+    const spared = candidates.length - pids.length;
+    if (dryRun || pids.length === 0) {
+        return { found: pids.length, killed: 0, pids, spared };
+    }
+    // SIGTERM each (best-effort, per-pid try so one EPERM doesn't abort the sweep).
+    for (const pid of pids) {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch {
+            /* already gone / not ours */
+        }
+    }
+    // Brief grace, then SIGKILL any survivor.
+    sleepSync(1.5);
+    let killed = 0;
+    for (const pid of pids) {
+        let alive = false;
+        try {
+            process.kill(pid, 0);
+            alive = true;
+        }
+        catch {
+            alive = false; // ESRCH ⇒ the SIGTERM took
+        }
+        if (alive) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                /* lost the race / not ours */
+            }
+        }
+        // Count it killed if it is now gone.
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            killed++;
+        }
+    }
+    return { found: pids.length, killed, pids, spared };
+}
+/** CLI action for `convene watch-reap`. Prints a one-line summary. Never throws. */
+async function watchReap(opts = {}) {
+    try {
+        const res = reapWatchers({ dryRun: opts.dryRun });
+        if (res.note) {
+            process.stdout.write(`watch-reap: ${res.note}\n`);
+            return;
+        }
+        const sparedTail = res.spared > 0 ? `; spared ${res.spared} live-owned` : '';
+        if (opts.dryRun) {
+            process.stdout.write(res.found === 0
+                ? `watch-reap: no orphaned watchers to reap${sparedTail}\n`
+                : `watch-reap: would reap ${res.found} orphaned watcher(s): ${res.pids.join(', ')}${sparedTail}\n`);
+        }
+        else {
+            process.stdout.write(res.found === 0
+                ? `watch-reap: no orphaned watchers to reap${sparedTail}\n`
+                : `watch-reap: reaped ${res.killed}/${res.found} orphaned watcher(s)${sparedTail}\n`);
+        }
+    }
+    catch {
+        /* fail-open: cleanup must never crash */
+    }
+}

package/dist/commands/watch.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.watchShouldExit = watchShouldExit;
 exports.watch = watch;
 /**
  * `convene watch` (WP12) — a DETACHED long-poll on the existing /poll stream,
@@ -41,6 +42,42 @@ const POLL_WAIT_SEC = 25; // server holds up to ~25s; capped at 50 server-side
 const POLL_TIMEOUT_MS = POLL_WAIT_SEC * 1000 + 5000; // MUST exceed wait*1000
 const BACKOFF_BASE_MS = 1000;
 const BACKOFF_MAX_MS = 30_000;
+/**
+ * SELF-TERMINATION (the daemon-leak fix). A `convene watch` is spawned
+ * detached+unref at SessionStart, so it OUTLIVES its session and reparents to
+ * PID 1 — and the original loop had NO exit path, leaking ~one orphan per boot
+ * (145 observed, ~1 day old). Two independent ceilings now guarantee it dies:
+ *
+ *   - MAX_RUNTIME_MS — an absolute lifetime cap (12h prod; tests set it tiny). A
+ *     watcher can never outlive this no matter what.
+ *   - IDLE_EXIT_MS — exit once the OWNING session has gone quiet. The watcher
+ *     inherits CLAUDE_CODE_SESSION_ID, so liveSessionCount(slug, window) reports
+ *     whether the owner is still actively fetching (it rewrites its feed .json
+ *     each prompt). Zero live sessions ⇒ start an idle clock; 20 min idle ⇒ exit.
+ *
+ * Total time-to-die for a genuinely-closed session ≈ LIVE_SESSION_WINDOW_SEC
+ * (10m, for the owner's last .json to age out) + IDLE_EXIT_MS (20m) ≈ 30m. That
+ * is deliberately longer than any plausible heads-down turn, and is FAIL-OPEN:
+ * if we kill a watcher whose session is merely mid-long-turn, the next
+ * SessionStart relaunches one — the only cost is a brief mid-turn-halt blind
+ * spot, never a crash. A newer watcher taking over the same scope (pidfile
+ * newest-wins) also retires the older one immediately.
+ */
+const MAX_RUNTIME_MS = (0, config_1.resolveWatchMaxMs)();
+const IDLE_EXIT_MS = 20 * 60 * 1000;
+/**
+ * PURE termination decision (unit-tested). Exit when the absolute lifetime cap is
+ * hit, OR the owner has been idle past the idle ceiling. `idleSince == null`
+ * means the owner is currently live → never an idle exit.
+ */
+function watchShouldExit(args) {
+    const { startedAt, now, maxRuntimeMs, idleSince, idleExitMs } = args;
+    if (now - startedAt >= maxRuntimeMs)
+        return true;
+    if (idleSince != null && now - idleSince >= idleExitMs)
+        return true;
+    return false;
+}
 const HALT_TYPES = new Set(['halt', 'interrupt']);
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Map a server feed/poll message to an inert WatchEntry. Returns null for non-halts. */
@@ -102,36 +139,82 @@ async function loop(opts) {
     let backoff = BACKOFF_BASE_MS;
     let iterations = 0;
     const limit = typeof opts.maxIterations === 'number' ? opts.maxIterations : Infinity;
+    // Claim ownership of this session's scope + record our birth time. The pidfile
+    // makes us discoverable to the spawn-dedup guards and enables newest-wins
+    // handover (a later watcher overwrites it, and we notice + exit).
+    const startedAt = Date.now();
+    (0, cache_1.writeWatchPid)(slug);
+    let idleSince = null;
     // Heartbeat up-front so a just-launched watch reads as healthy immediately.
     (0, cache_1.touchWatchHeartbeat)(slug);
-    while (iterations < limit) {
-        const res = await api.poll(slug, { since: cursor, wait: POLL_WAIT_SEC }, POLL_TIMEOUT_MS).catch(() => null);
-        // Every loop iteration stamps liveness — even an empty/failed poll proves the
-        // daemon is alive (the health line distinguishes "down" from "quiet").
-        (0, cache_1.touchWatchHeartbeat)(slug);
-        if (!res || !res.ok || !res.json) {
-            // Transport failure / timeout / parse error → self-heal with backoff.
-            await sleep(backoff);
-            backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
-            continue;
-        }
-        backoff = BACKOFF_BASE_MS; // recovered
-        const msgs = Array.isArray(res.json.messages) ? res.json.messages : [];
-        for (const m of msgs) {
-            const entry = toEntry(m);
-            if (!entry)
+    try {
+        while (iterations < limit) {
+            // Termination checks run at the TOP of every iteration so they fire
+            // regardless of poll success/backoff. Wrapped fail-open: any error here
+            // SKIPS the check and continues — a termination-check fault must never crash
+            // the daemon (and a wrongly-killed watcher would only be relaunched).
+            try {
+                // Newest-wins: a DIFFERENT pid in our scope's pidfile means a fresher
+                // watcher took over — retire ourselves immediately.
+                const owner = (0, cache_1.readWatchPid)(slug);
+                if (owner && owner.pid !== process.pid)
+                    break;
+                // Owner liveness: zero live sessions ⇒ the owning session has gone quiet,
+                // so start (or keep) the idle clock; any live session resets it.
+                const live = (0, cache_1.liveSessionCount)(slug, cache_1.LIVE_SESSION_WINDOW_SEC);
+                if (live === 0) {
+                    if (idleSince == null)
+                        idleSince = Date.now();
+                }
+                else {
+                    idleSince = null;
+                }
+                if (watchShouldExit({
+                    startedAt,
+                    now: Date.now(),
+                    maxRuntimeMs: MAX_RUNTIME_MS,
+                    idleSince,
+                    idleExitMs: IDLE_EXIT_MS,
+                })) {
+                    break;
+                }
+            }
+            catch {
+                /* fail-open: a faulty termination check never crashes the daemon */
+            }
+            const res = await api.poll(slug, { since: cursor, wait: POLL_WAIT_SEC }, POLL_TIMEOUT_MS).catch(() => null);
+            // Every loop iteration stamps liveness — even an empty/failed poll proves the
+            // daemon is alive (the health line distinguishes "down" from "quiet").
+            (0, cache_1.touchWatchHeartbeat)(slug);
+            if (!res || !res.ok || !res.json) {
+                // Transport failure / timeout / parse error → self-heal with backoff.
+                await sleep(backoff);
+                backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
                 continue;
-            (0, cache_1.appendWatchEntry)(slug, entry);
-            if (opts.notify)
-                notifyBestEffort(entry);
+            }
+            backoff = BACKOFF_BASE_MS; // recovered
+            const msgs = Array.isArray(res.json.messages) ? res.json.messages : [];
+            for (const m of msgs) {
+                const entry = toEntry(m);
+                if (!entry)
+                    continue;
+                (0, cache_1.appendWatchEntry)(slug, entry);
+                if (opts.notify)
+                    notifyBestEffort(entry);
+            }
+            // Advance the resume cursor to the server's reported cursor (monotonic). This
+            // is the long-poll resume seq, NOT the reader's high-water — the daemon must
+            // move past EVERY message it saw (incl. non-halts) or it would re-fetch them
+            // forever. The reader's high-water only advances over rendered halts.
+            if (typeof res.json.cursor === 'number' && res.json.cursor > cursor)
+                cursor = res.json.cursor;
+            iterations++;
         }
-        // Advance the resume cursor to the server's reported cursor (monotonic). This
-        // is the long-poll resume seq, NOT the reader's high-water — the daemon must
-        // move past EVERY message it saw (incl. non-halts) or it would re-fetch them
-        // forever. The reader's high-water only advances over rendered halts.
-        if (typeof res.json.cursor === 'number' && res.json.cursor > cursor)
-            cursor = res.json.cursor;
-        iterations++;
+    }
+    finally {
+        // Release our scope's pidfile so the next SessionStart spawns freely — but
+        // ONLY if it still names us (a newer watcher may already own it).
+        (0, cache_1.clearWatchPidIfOwner)(slug);
     }
     return 0;
 }