convene-cli 1.6.0 → 1.8.0

package/dist/api.js

@@ -117,6 +117,15 @@ class ConveneApi {
         const qs = params.toString();
         return this.request('GET', `/help${qs ? `?${qs}` : ''}`, { timeoutMs });
     }
+    /**
+     * POST /presence — UPSERT this session's activity beat. PURELY for observability
+     * (the "Active now" surface); ALWAYS best-effort / fail-open. The body carries
+     * only a COARSE area + edit count — never filenames (the bus is cross-member).
+     * Bounded by a short timeout so the PostToolUse hook never slows an edit.
+     */
+    presence(slug, body, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/presence`, { body, timeoutMs });
+    }
     post(slug, body, idempotencyKey, timeoutMs) {
         return this.request('POST', `/projects/${encodeURIComponent(slug)}/messages`, {
             body,

package/dist/cache.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OVERRIDE_TTL_MS = exports.writeWatchHighWater = exports.LIVE_SESSION_WINDOW_SEC = void 0;
+exports.OVERRIDE_TTL_MS = exports.writeWatchHighWater = exports.LIVE_SESSION_RECENT_SEC = exports.LIVE_SESSION_WINDOW_SEC = void 0;
 exports.readCache = readCache;
 exports.writeCache = writeCache;
 exports.ageSeconds = ageSeconds;
@@ -13,8 +13,12 @@ exports.readSessionInstance = readSessionInstance;
 exports.mintSessionInstance = mintSessionInstance;
 exports.ensureSessionInstance = ensureSessionInstance;
 exports.liveSessionCount = liveSessionCount;
+exports.readBeatState = readBeatState;
+exports.writeBeatState = writeBeatState;
 exports.markCatchupSurfaced = markCatchupSurfaced;
 exports.catchupAlreadySurfaced = catchupAlreadySurfaced;
+exports.markAutoIsolated = markAutoIsolated;
+exports.autoIsolatedAlready = autoIsolatedAlready;
 exports.readWatchHighWater = readWatchHighWater;
 exports.persistHighWater = persistHighWater;
 exports.appendWatchEntry = appendWatchEntry;
@@ -22,6 +26,11 @@ exports.appendWatch = appendWatch;
 exports.readWatchSince = readWatchSince;
 exports.touchWatchHeartbeat = touchWatchHeartbeat;
 exports.watchHeartbeatAgeSec = watchHeartbeatAgeSec;
+exports.writeWatchPid = writeWatchPid;
+exports.readWatchPid = readWatchPid;
+exports.clearWatchPidIfOwner = clearWatchPidIfOwner;
+exports.readAllWatchPids = readAllWatchPids;
+exports.isPidAlive = isPidAlive;
 exports.writeOverrideToken = writeOverrideToken;
 exports.readLiveOverrideToken = readLiveOverrideToken;
 /**
@@ -203,6 +212,33 @@ function liveSessionCount(slug, maxAgeSec) {
         return 0;
     }
 }
+function beatFile(slug) {
+    return slugFile(scoped(slug), 'beat');
+}
+/** Read this session's beat state, or a zeroed default. Best-effort. */
+function readBeatState(slug) {
+    try {
+        const s = JSON.parse(node_fs_1.default.readFileSync(beatFile(slug), 'utf8'));
+        return {
+            lastPostMs: Number.isFinite(s.lastPostMs) ? s.lastPostMs : 0,
+            pendingEdits: Number.isFinite(s.pendingEdits) ? s.pendingEdits : 0,
+            area: typeof s.area === 'string' ? s.area : null,
+        };
+    }
+    catch {
+        return { lastPostMs: 0, pendingEdits: 0, area: null };
+    }
+}
+/** Persist this session's beat state. Best-effort; never throws. */
+function writeBeatState(slug, state) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(beatFile(slug), JSON.stringify(state), { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
 // ── per-boot catch-up dedup sentinel (WP2) ───────────────────────────────────
 // SessionStart writes a sentinel keyed by the session-instance once it has
 // surfaced a catch-up; the first UserPromptSubmit `fetch` of that boot reads it
@@ -230,6 +266,45 @@ function catchupAlreadySurfaced(slug, instance) {
         return false;
     }
 }
+// ── per-instance auto-isolate sentinel (auto-isolate) ─────────────────────────
+// SessionStart relocates a session that boots into an OCCUPIED checkout into a
+// fresh isolated worktree (a SOFT, best-effort move). It records this sentinel
+// keyed by the session-instance so a resume/clear SessionStart of an ALREADY-
+// relocated session does NOT re-provision yet another tree. Keyed by instance
+// (like the catch-up sentinel) so a genuinely NEW boot can still relocate; scoped
+// per-session via `scoped()` so co-tenant sessions don't clobber each other's mark.
+function autoIsolateFile(slug) {
+    return slugFile(scoped(slug), 'auto-isolated');
+}
+/** Mark that this session-instance has already been auto-isolated (relocated). */
+function markAutoIsolated(slug, instance) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(autoIsolateFile(slug), instance + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** True iff this exact session-instance has already been auto-isolated. */
+function autoIsolatedAlready(slug, instance) {
+    try {
+        return node_fs_1.default.readFileSync(autoIsolateFile(slug), 'utf8').trim() === instance;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Tight recency window (sec) for the auto-isolate trigger's relaunch-ghost guard.
+ * The wider LIVE_SESSION_WINDOW_SEC (10 min) deliberately keeps a just-closed
+ * session counted (so a concurrent agent mid-long-turn isn't missed). For the
+ * ACTIVE relocation decision that is too loose: a session that was closed and
+ * relaunched a few minutes ago would otherwise trigger a needless move. We require
+ * a sibling to have pulsed within this tighter window so only a TRULY concurrent
+ * incumbent forces a relocation.
+ */
+exports.LIVE_SESSION_RECENT_SEC = 3 * 60;
 function watchFile(slug) {
     return slugFile(slug, 'watch.jsonl');
 }
@@ -356,6 +431,103 @@ function watchHeartbeatAgeSec(slug) {
         return null;
     }
 }
+function watchPidFile(slug) {
+    return slugFile(scoped(slug), 'watch.pid');
+}
+/** Record (overwrite) THIS watcher as the owner of the session scope. Best-effort. */
+function writeWatchPid(slug, pid = process.pid, startedAt = Date.now()) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(watchPidFile(slug), JSON.stringify({ pid, startedAt }), { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** The recorded owning watcher {pid, startedAt} for this scope, or null. */
+function readWatchPid(slug) {
+    try {
+        const o = JSON.parse(node_fs_1.default.readFileSync(watchPidFile(slug), 'utf8'));
+        if (!o || typeof o.pid !== 'number' || !Number.isFinite(o.pid))
+            return null;
+        if (typeof o.startedAt !== 'number' || !Number.isFinite(o.startedAt))
+            return null;
+        return o;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remove the pidfile ONLY if it still names `pid` (default: this process). A
+ * newer watcher may have overwritten it with its own pid, in which case we must
+ * NOT delete it — that would orphan the new owner's record. Best-effort.
+ */
+function clearWatchPidIfOwner(slug, pid = process.pid) {
+    try {
+        const cur = readWatchPid(slug);
+        if (cur && cur.pid === pid)
+            node_fs_1.default.unlinkSync(watchPidFile(slug));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Every pid recorded in a `*.watch.pid` file across ALL scopes/sessions in
+ * CACHE_DIR. The reaper unions these (filtered to live) to SPARE watchers a
+ * current session still owns — a post-fix watcher always writes its pidfile, so a
+ * live, pidfile-owned watcher is by definition NOT a dead-session orphan even
+ * though it (like every detached watcher) shows ppid 1. Best-effort: a missing
+ * dir, an unreadable file, or a garbage entry is skipped, never thrown.
+ */
+function readAllWatchPids() {
+    const out = [];
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(config_1.CACHE_DIR);
+    }
+    catch {
+        return out;
+    }
+    for (const f of entries) {
+        if (!f.endsWith('.watch.pid'))
+            continue;
+        try {
+            const o = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(config_1.CACHE_DIR, f), 'utf8'));
+            const pid = typeof o?.pid === 'number' ? o.pid : NaN;
+            if (Number.isFinite(pid) && pid > 0)
+                out.push(pid);
+        }
+        catch {
+            /* skip unreadable/garbage pidfiles */
+        }
+    }
+    return out;
+}
+/**
+ * Is `pid` a live process? `process.kill(pid, 0)` sends no signal — it only
+ * probes existence/permission. EPERM ⇒ the process exists but we can't signal it
+ * (still ALIVE); ESRCH ⇒ no such process (DEAD). On win32 signal 0 is unreliable,
+ * so a non-ESRCH error is treated as alive (best-effort). An invalid pid or any
+ * other error ⇒ false. Shared by the spawn-dedup guards (session-start/doctor)
+ * and the reaper's spare-the-living gate.
+ */
+function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        if (e && e.code === 'EPERM')
+            return true; // exists, not ours to signal
+        if (process.platform === 'win32' && e && e.code !== 'ESRCH')
+            return true;
+        return false; // ESRCH (and the win32 fallthrough) ⇒ dead
+    }
+}
 // ── best-practice override token (Phase 3) ───────────────────────────────────
 // `convene override <id> --reason …` writes a short-TTL, expiry-based token that
 // `convene practice-guard <id>` honors → ALLOW. The token is purely LOCAL state

package/dist/commands/auth.js

@@ -20,12 +20,23 @@ const manifest_1 = require("../catalog/manifest");
 const git_1 = require("../git");
 const hook_1 = require("../hook");
 const cache_1 = require("../cache");
+const watch_reap_1 = require("./watch-reap");
 const ctx_1 = require("../ctx");
 /** A watch heartbeat older than this (or absent) means the watcher is down. */
 const WATCH_STALE_SEC = 90;
-/** (Re)launch `convene watch` detached so it outlives this doctor process. */
-function relaunchWatch() {
+/**
+ * (Re)launch `convene watch` detached so it outlives this doctor process — but
+ * SKIP if a live watcher already owns this scope (the daemon-leak dedup guard),
+ * so `doctor --fix` never piles up a duplicate. Returns true iff a watcher is
+ * now (re)launched or already running.
+ */
+function relaunchWatch(slug) {
     try {
+        if (slug) {
+            const owner = (0, cache_1.readWatchPid)(slug);
+            if (owner && (0, cache_1.isPidAlive)(owner.pid))
+                return true; // already watching
+        }
         const bin = process.argv[1] || '';
         if (!bin)
             return false;
@@ -330,7 +341,7 @@ async function doctor(opts) {
         let age = (0, cache_1.watchHeartbeatAgeSec)(proj.slug);
         let watchOk = age != null && age <= WATCH_STALE_SEC;
         if (!watchOk && opts.fix) {
-            if (relaunchWatch()) {
+            if (relaunchWatch(proj.slug)) {
                 // Give the freshly-launched daemon a beat to stamp its first heartbeat.
                 const until = Date.now() + 2500;
                 while (Date.now() < until) {
@@ -350,6 +361,25 @@ async function doctor(opts) {
                     ? 'halt watcher DOWN — no heartbeat (run `convene doctor --fix` to relaunch)'
                     : `halt watcher STALE — heartbeat ${age}s ago (run \`convene doctor --fix\` to relaunch)`,
         });
+        // 7a. reap orphaned watchers — the cleanup half of the daemon-leak fix. Only
+        // under --fix (running `ps` on every doctor would slow the fast path). Runs
+        // AFTER the relaunch + heartbeat-wait above so the freshly-relaunched watcher
+        // has already written its pidfile and is SPARED (a live, pidfile-owned watcher
+        // is never reaped — only true dead-session orphans are). Reports the kill +
+        // spare counts. Fail-open: a reap fault is informational, never a doctor failure.
+        if (opts.fix) {
+            const reaped = (0, watch_reap_1.reapWatchers)({});
+            const sparedTail = reaped.spared > 0 ? ` (spared ${reaped.spared} live-owned)` : '';
+            checks.push({
+                name: 'reap',
+                ok: true,
+                detail: reaped.note
+                    ? `watcher reap skipped (${reaped.note})`
+                    : reaped.found === 0
+                        ? `no orphaned watchers to reap${sparedTail}`
+                        : `reaped ${reaped.killed}/${reaped.found} orphaned watcher(s)${sparedTail}`,
+            });
+        }
     }
     // 7b. parallel sessions sharing ONE checkout. Several agents in the same
     // working tree clobber each other's uncommitted files and (absent the

package/dist/commands/beat.js

@@ -0,0 +1,145 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coarseArea = coarseArea;
+exports.filePathFromPayload = filePathFromPayload;
+exports.beat = beat;
+/**
+ * `convene beat` — the session activity-beat emitter (a PostToolUse hook on
+ * Edit|Write|MultiEdit). It closes the dark-session gap: a session heads-down
+ * editing for many minutes before it pushes still pulses on the bus, so siblings
+ * (and humans on the dashboard) can see it is alive and roughly where it works.
+ *
+ * Posture (mirrors session-start): FAIL-OPEN and FAST. Not a git repo / not on the
+ * bus / not authenticated ⇒ silent exit 0. A hard watchdog guarantees it never
+ * holds a tool call. It is DEBOUNCED client-side: every edit bumps a per-session
+ * pending counter, but it only actually POSTs presence once the window elapses
+ * (≤1 network call per window per session). The first edit of a session posts
+ * immediately (lastPostMs=0), giving a prompt "started working" signal.
+ *
+ * PRIVACY: the beat carries only a COARSE area — the first path segment of the
+ * edited file relative to the repo (e.g. 'web', 'cli', 'server') — never a
+ * filename. The bus is cross-member, so a full path would leak repo structure.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const git_1 = require("../git");
+const config_1 = require("../config");
+const api_1 = require("../api");
+const cache_1 = require("../cache");
+/** ≤1 presence POST per this window per session; edits between are coalesced. */
+const DEBOUNCE_MS = 90_000;
+/** Short, bounded post — a PostToolUse hook must never slow an edit. */
+const POST_TIMEOUT_MS = 2500;
+/** Absolute backstop: never hold the tool call past this. */
+const WATCHDOG_MS = 3500;
+/** First path segment of `file` relative to `top` — a coarse, privacy-safe area. */
+function coarseArea(file, top) {
+    if (!file)
+        return null;
+    let rel = file;
+    try {
+        if (node_path_1.default.isAbsolute(file))
+            rel = node_path_1.default.relative(top, file);
+    }
+    catch {
+        rel = file;
+    }
+    if (!rel || rel.startsWith('..'))
+        return null; // outside the repo — don't broadcast
+    const norm = rel.replace(/\\/g, '/').replace(/^\.\//, '');
+    const seg = norm.split('/')[0] || '';
+    if (!seg || seg === norm)
+        return '(root)'; // a top-level file → no directory to name
+    const clean = seg.replace(/[^A-Za-z0-9._-]/g, '').slice(0, 32);
+    return clean || null;
+}
+/** Pull the edited file path out of a PostToolUse stdin payload. */
+function filePathFromPayload(raw) {
+    if (!raw)
+        return null;
+    try {
+        const j = JSON.parse(raw);
+        const ti = j?.tool_input ?? {};
+        const p = ti.file_path ?? ti.notebook_path ?? ti.path ?? null;
+        return typeof p === 'string' && p ? p : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readStdin(timeoutMs) {
+    if (process.stdin.isTTY)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let data = '';
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            process.stdin.removeAllListeners();
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (c) => (data += c));
+        process.stdin.on('end', () => finish(data));
+        process.stdin.on('error', () => finish(null));
+        process.stdin.resume();
+    });
+}
+async function run(opts) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        return; // not a git repo → silent no-op
+    const proj = (0, config_1.loadProjectConfig)(top);
+    if (!proj?.slug)
+        return; // repo not on the bus → silent no-op
+    const slug = proj.slug;
+    const cfg = (0, config_1.resolveConfig)();
+    if (!cfg.apiKey || !cfg.member)
+        return; // not authenticated → silent
+    const session = (0, git_1.sessionId)(cfg.member, top);
+    const raw = opts.stdin ? await readStdin(800) : null;
+    const area = coarseArea(filePathFromPayload(raw), top);
+    // Coalesce: bump the pending counter / freshest area every edit.
+    const state = (0, cache_1.readBeatState)(slug);
+    state.pendingEdits += 1;
+    if (area)
+        state.area = area;
+    const now = Date.now();
+    if (state.lastPostMs && now - state.lastPostMs < DEBOUNCE_MS) {
+        // Inside the window — accumulate locally, no network.
+        (0, cache_1.writeBeatState)(slug, state);
+        return;
+    }
+    // Window elapsed (or first edit): POST presence, then reset the window.
+    const instance = (0, cache_1.ensureSessionInstance)(slug);
+    const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+    const res = await api.presence(slug, { area: state.area, edits: state.pendingEdits }, POST_TIMEOUT_MS);
+    // Always advance the window so a failed beat can't hammer the network on every
+    // edit; only clear the pending count on a confirmed post (so a transient blip
+    // doesn't drop the magnitude).
+    (0, cache_1.writeBeatState)(slug, {
+        lastPostMs: now,
+        pendingEdits: res.ok ? 0 : state.pendingEdits,
+        area: state.area,
+    });
+}
+async function beat(opts = {}) {
+    const watchdog = setTimeout(() => process.exit(0), WATCHDOG_MS);
+    watchdog.unref();
+    try {
+        await run(opts);
+    }
+    catch {
+        /* fail-open: a presence beat must never disrupt the session */
+    }
+    finally {
+        clearTimeout(watchdog);
+        process.exit(0);
+    }
+}

package/dist/commands/fetch.js

@@ -287,7 +287,21 @@ async function runFetch(opts = {}) {
             lookbackMin: ctx.lookback,
             openItems: toRenderMessages(data?.inbox ?? []),
             recent: toRenderMessages(data?.messages ?? []),
+            presence: toRenderPresence(data?.presence ?? [], data?.server_time),
             health: { state: 'ok', syncedAgoSec: ctx.syncedAgoSec, openCount: Number(data?.open_for_you ?? (data?.inbox?.length ?? 0)) },
         }), opts.codexHook);
     }
 }
+/** Map feed presence rows → RenderPresence, deriving age from the server clock. */
+function toRenderPresence(rows, serverTime) {
+    if (!Array.isArray(rows))
+        return [];
+    const nowMs = serverTime ? Date.parse(serverTime) : Date.now();
+    return rows
+        .filter((r) => r && typeof r.session === 'string')
+        .map((r) => {
+        const seen = r.last_seen_at ? Date.parse(r.last_seen_at) : NaN;
+        const ageSec = Number.isFinite(seen) && Number.isFinite(nowMs) ? Math.max(0, (nowMs - seen) / 1000) : null;
+        return { session: r.session, area: r.area ?? null, edits: Number(r.edits) || 0, ageSec };
+    });
+}

package/dist/commands/init.js

@@ -268,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

@@ -23,6 +23,7 @@ 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");
@@ -39,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',
@@ -60,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)
@@ -75,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) {
@@ -92,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 = {}) {