convene-cli 1.6.0 → 1.7.0

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;
 }

package/dist/commands/worktree.js

@@ -3,7 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.copyWorktreeIncludes = copyWorktreeIncludes;
+exports.provisionWorktree = provisionWorktree;
 exports.worktree = worktree;
+exports.provisionAutoWorktree = provisionAutoWorktree;
 /**
  * `convene worktree <branch>` — create an isolated git worktree for a parallel
  * session. This is Convene's recommended default for running several coding agents
@@ -14,6 +17,10 @@ exports.worktree = worktree;
  *
  * DIE-LOUD like the other interactive verbs (stderr + non-zero exit on failure).
  * Pure git plumbing — does NOT require the repo to be on the Convene bus.
+ *
+ * The provisioning CORE (`provisionWorktree`) is factored out of the command so
+ * the auto-isolate SessionStart path (`provisionAutoWorktree`) can reuse the exact
+ * same git plumbing + `.worktreeinclude` copy — fail-OPEN there, die-LOUD here.
  */
 const node_child_process_1 = require("node:child_process");
 const node_path_1 = __importDefault(require("node:path"));
@@ -24,6 +31,88 @@ function refExists(ref, cwd) {
     const r = (0, node_child_process_1.spawnSync)('git', ['rev-parse', '--verify', '--quiet', ref], { cwd, encoding: 'utf8' });
     return r.status === 0;
 }
+/**
+ * The `.worktreeinclude` format (read from `<top>/.worktreeinclude`):
+ *   - one relative path per line, resolved against the SOURCE worktree's toplevel;
+ *   - lines beginning with `#` are comments; blank/whitespace-only lines are ignored;
+ *   - a leading `!` or absolute path or `..` traversal is rejected (never escapes <top>);
+ *   - each entry may be a file OR a directory (copied recursively);
+ *   - a missing entry is silently skipped (gitignored config that just isn't present).
+ *
+ * Purpose: carry gitignored local config (e.g. `.env`, `.envrc`, `.claude/settings.local.json`)
+ * from the source checkout into a freshly-provisioned worktree, since git itself
+ * only materializes TRACKED files. Best-effort: any per-entry error is swallowed so
+ * a copy failure can never wedge worktree creation (critical on the auto-isolate path).
+ */
+function copyWorktreeIncludes(top, dest) {
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(node_path_1.default.join(top, '.worktreeinclude'), 'utf8');
+    }
+    catch {
+        return; // no include file → nothing to carry
+    }
+    for (const line of raw.split('\n')) {
+        const entry = line.trim();
+        if (!entry || entry.startsWith('#'))
+            continue;
+        // Reject anything that could escape <top>: leading '!', absolute, or any '..' segment.
+        if (entry.startsWith('!') || node_path_1.default.isAbsolute(entry))
+            continue;
+        const rel = node_path_1.default.normalize(entry);
+        if (rel === '..' || rel.startsWith('..' + node_path_1.default.sep) || rel.split(node_path_1.default.sep).includes('..'))
+            continue;
+        const src = node_path_1.default.join(top, rel);
+        const dst = node_path_1.default.join(dest, rel);
+        try {
+            if (!node_fs_1.default.existsSync(src))
+                continue; // skip missing entries
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(dst), { recursive: true });
+            node_fs_1.default.cpSync(src, dst, { recursive: true });
+        }
+        catch {
+            /* best-effort per entry — never let a copy failure wedge provisioning */
+        }
+    }
+}
+/**
+ * Hard ceiling on `git worktree add` (a full working-tree checkout). On the AUTO
+ * path this runs SYNCHRONOUSLY inside SessionStart, and the boot's async 6s
+ * watchdog cannot interrupt synchronous work — so a large/slow repo could stall the
+ * boot. A bounded spawnSync caps that: a timeout kills git and we fail-open.
+ */
+const WORKTREE_ADD_TIMEOUT_MS = 20_000;
+/**
+ * The reusable provisioning core: resolve the branch (existing local / existing
+ * remote-only / new), run `git worktree add`, then copy `.worktreeinclude` config
+ * into the new tree. Returns {dest, branch} on success or null on ANY failure —
+ * the caller decides whether to die-loud (interactive) or fail-open (auto).
+ */
+function provisionWorktree(args) {
+    const { top, branch, dest, fromRef, quiet } = args;
+    if (node_fs_1.default.existsSync(dest))
+        return null;
+    const localExists = refExists(`refs/heads/${branch}`, top);
+    const remoteExists = !localExists && refExists(`refs/remotes/origin/${branch}`, top);
+    // Existing local branch → check it out; existing remote-only branch → create a
+    // local tracking branch; otherwise → new branch from fromRef (or HEAD).
+    const gitArgs = localExists
+        ? ['worktree', 'add', dest, branch]
+        : remoteExists
+            ? ['worktree', 'add', '-b', branch, dest, `origin/${branch}`]
+            : ['worktree', 'add', '-b', branch, dest, fromRef || 'HEAD'];
+    const r = (0, node_child_process_1.spawnSync)('git', gitArgs, {
+        cwd: top,
+        stdio: quiet ? 'ignore' : 'inherit',
+        timeout: WORKTREE_ADD_TIMEOUT_MS,
+    });
+    if (r.status !== 0)
+        return null;
+    // Carry gitignored local config (e.g. .env) into the new tree — best-effort.
+    copyWorktreeIncludes(top, dest);
+    const branchNote = localExists ? '' : remoteExists ? ` (new, tracking origin/${branch})` : ' (new)';
+    return { dest, branch, branchNote };
+}
 function worktree(branch, opts = {}) {
     const top = (0, git_1.gitToplevel)();
     if (!top)
@@ -35,29 +124,78 @@ function worktree(branch, opts = {}) {
     const dest = node_path_1.default.resolve(opts.path || node_path_1.default.join(node_path_1.default.dirname(top), `${base}-${safeBranch}`));
     if (node_fs_1.default.existsSync(dest))
         (0, ctx_1.die)(`destination already exists: ${dest}`);
-    const localExists = refExists(`refs/heads/${branch}`, top);
-    const remoteExists = !localExists && refExists(`refs/remotes/origin/${branch}`, top);
-    // Existing local branch → check it out; existing remote-only branch → create a
-    // local tracking branch; otherwise → new branch from --from (or HEAD).
-    const args = localExists
-        ? ['worktree', 'add', dest, branch]
-        : remoteExists
-            ? ['worktree', 'add', '-b', branch, dest, `origin/${branch}`]
-            : ['worktree', 'add', '-b', branch, dest, opts.from || 'HEAD'];
-    const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: top, stdio: 'inherit' });
-    if (r.status !== 0)
-        (0, ctx_1.die)(`git worktree add failed (exit ${r.status ?? '?'})`);
-    const branchNote = localExists ? '' : remoteExists ? ` (new, tracking origin/${branch})` : ' (new)';
+    const res = provisionWorktree({ top: top, branch, dest, fromRef: opts.from });
+    if (!res)
+        (0, ctx_1.die)(`git worktree add failed`);
     process.stdout.write([
         ``,
-        `✓ worktree ready: ${dest}`,
-        `  branch: ${branch}${branchNote}`,
+        `✓ worktree ready: ${res.dest}`,
+        `  branch: ${branch}${res.branchNote}`,
         ``,
         `Start a FRESH agent session inside it so it gets its own Convene identity:`,
-        `  cd ${dest}`,
+        `  cd ${res.dest}`,
         `  # install deps for this package if needed, then launch your agent (e.g. \`claude\`)`,
         ``,
-        `Remove it when done:  git worktree remove ${dest}`,
+        `Remove it when done:  git worktree remove ${res.dest}`,
         ``,
     ].join('\n'));
 }
+/** A safe, filesystem-friendly token from an arbitrary string (for branch/dir names). */
+function safeToken(s) {
+    return s.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'sess';
+}
+/**
+ * The AUTO-ISOLATE provisioning entry point used by SessionStart when a session
+ * boots into a checkout that already has a live sibling. FAIL-OPEN end-to-end:
+ * returns {dest, branch} on success or null on ANY error — the boot proceeds
+ * normally on null.
+ *
+ * Strategy:
+ *   1. Best-effort refresh the base (`git fetch origin main`) so the new tree is
+ *      based on fresh upstream, not a stale local tip. A fetch failure is ignored.
+ *   2. Pick the base ref: the current branch's upstream if it has one, else
+ *      `origin/main` (falling back to `HEAD` only if neither resolves).
+ *   3. Compute a NON-colliding branch name `auto/<disc-or-member>-<short>` and a
+ *      NON-colliding sibling destination, bumping a counter on collision.
+ *   4. provisionWorktree(...) (which also copies `.worktreeinclude`).
+ */
+function provisionAutoWorktree(top, slug) {
+    try {
+        // 1. Best-effort refresh of the canonical base.
+        (0, git_1.gitFetch)('main', 'origin', top);
+        // 2. Base ref: current branch's upstream, else origin/main, else HEAD.
+        let fromRef = 'origin/main';
+        if (!refExists('refs/remotes/origin/main', top))
+            fromRef = 'HEAD';
+        const cur = (0, git_1.currentBranch)(top);
+        if (cur) {
+            const up = (0, node_child_process_1.spawnSync)('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', `${cur}@{upstream}`], {
+                cwd: top,
+                encoding: 'utf8',
+            });
+            const upstream = up.status === 0 ? (up.stdout || '').trim() : '';
+            if (upstream && refExists(`refs/remotes/${upstream}`, top))
+                fromRef = upstream;
+        }
+        // 3. Non-colliding branch name + destination.
+        const disc = (0, git_1.sessionDiscriminator)();
+        const tag = safeToken(disc || slug);
+        const base = (0, git_1.worktreeBasename)(top);
+        const parent = node_path_1.default.dirname(top);
+        let branch = `auto/${tag}`;
+        let dest = node_path_1.default.join(parent, `${base}-auto-${tag}`);
+        let n = 1;
+        while (refExists(`refs/heads/${branch}`, top) || node_fs_1.default.existsSync(dest)) {
+            n += 1;
+            branch = `auto/${tag}-${n}`;
+            dest = node_path_1.default.join(parent, `${base}-auto-${tag}-${n}`);
+            if (n > 50)
+                return null; // pathological — give up rather than spin
+        }
+        const res = provisionWorktree({ top, branch, dest, fromRef, quiet: true });
+        return res ? { dest: res.dest, branch: res.branch } : null;
+    }
+    catch {
+        return null; // fail-open: any error → no relocation, boot proceeds
+    }
+}

package/dist/config.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CACHE_DIR = exports.CONFIG_FILE = exports.CONFIG_DIR = void 0;
 exports.homeBase = homeBase;
 exports.resolveFetchTimeoutMs = resolveFetchTimeoutMs;
+exports.resolveWatchMaxMs = resolveWatchMaxMs;
 exports.isWorldReadable = isWorldReadable;
 exports.loadFileConfig = loadFileConfig;
 exports.loadProjectConfig = loadProjectConfig;
@@ -42,6 +43,21 @@ function resolveFetchTimeoutMs(fallback = 4000) {
     const n = raw ? Number(raw) : NaN;
     return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
 }
+/**
+ * Hard ceiling (ms) on a single `convene watch` daemon's total lifetime — the
+ * absolute-runtime half of the leak fix (the other half is idle exit; see
+ * watch.ts). A detached watcher self-terminates once it has run this long so an
+ * orphaned daemon can never live forever (the 145-leaked-watchers bug). Mirrors
+ * resolveFetchTimeoutMs: a positive finite CONVENE_WATCH_MAX_MS wins (floored),
+ * else the fallback. Tests drive it tiny for a deterministic exit; the production
+ * default is 12h — comfortably longer than any real heads-down turn, and a fresh
+ * watcher is relaunched at the next SessionStart regardless.
+ */
+function resolveWatchMaxMs(fallback = 12 * 60 * 60 * 1000) {
+    const raw = process.env.CONVENE_WATCH_MAX_MS;
+    const n = raw ? Number(raw) : NaN;
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
 exports.CONFIG_DIR = node_path_1.default.join(homeBase(), brand_1.BRAND.configDir);
 exports.CONFIG_FILE = node_path_1.default.join(exports.CONFIG_DIR, 'config.json');
 exports.CACHE_DIR = node_path_1.default.join(exports.CONFIG_DIR, 'cache');

package/dist/index.js

@@ -57,9 +57,11 @@ const lane_1 = require("./commands/lane");
 const deploy_1 = require("./commands/deploy");
 const guard_1 = require("./commands/guard");
 const gate_push_1 = require("./commands/gate-push");
+const beat_1 = require("./commands/beat");
 const practice_guard_1 = require("./commands/practice-guard");
 const override_1 = require("./commands/override");
 const watch_1 = require("./commands/watch");
+const watch_reap_1 = require("./commands/watch-reap");
 const explain_1 = require("./commands/explain");
 const practices_1 = require("./commands/practices");
 const update_1 = require("./commands/update");
@@ -168,12 +170,22 @@ program
     .option('--reason <text>', 'why the gate is being overridden (required; attributed to the bus)')
     .option('--project <slug>')
     .action((id, opts) => (0, override_1.override)(id, opts));
+program
+    .command('beat')
+    .description('PostToolUse hook: debounced session activity-beat (presence), fail-open + fast')
+    .option('--stdin', 'read the PostToolUse JSON payload from stdin (to derive the coarse area)')
+    .action((opts) => (0, beat_1.beat)(opts));
 program
     .command('watch')
     .description('SessionStart-launched detached long-poll for directed halts (fail-open, self-healing)')
     .option('--notify', 'best-effort desktop notification per surfaced halt')
     .option('--project <slug>')
     .action((opts) => (0, watch_1.watch)(opts));
+program
+    .command('watch-reap')
+    .description('reap orphaned (PID-1) detached `convene watch` daemons (POSIX-only, fail-open)')
+    .option('--dry-run', 'list reapable watchers; kill nothing')
+    .action((opts) => (0, watch_reap_1.watchReap)({ dryRun: opts.dryRun }));
 program
     .command('notify-push')
     .description('git pre-push hook: post a [STATUS] summarizing the push (fail-silent)')