convene-cli 1.5.1 → 1.7.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/catalog/prompt.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.practiceBlurb = practiceBlurb;
 exports.pickPracticesInteractively = pickPracticesInteractively;
 /**
  * Interactive best-practices picker for `convene init` / `convene setup`.
@@ -16,6 +17,24 @@ exports.pickPracticesInteractively = pickPracticesInteractively;
 const promises_1 = __importDefault(require("node:readline/promises"));
 const select_1 = require("./select");
 const out = (m) => process.stdout.write(m + '\n');
+/** Truncate to ~n chars on a soft boundary, adding an ellipsis when clipped. */
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return s.slice(0, n - 1).trimEnd() + '…';
+}
+/**
+ * The provenance/rationale context shown above each practice in the customizer, so
+ * a user can make an INFORMED adoption choice (feedback 52269531 — the picker used
+ * to show only a bare title). Renders the practice title, a production-learned
+ * marker (the provenance the Practice.productionLearned comment promises), and a
+ * truncated `why`. Pure + exported so it can be asserted without a TTY.
+ */
+function practiceBlurb(p) {
+    const mark = p.productionLearned ? ' ★ production-learned' : '';
+    const why = p.why ? `\n    why: ${truncate(p.why, 110)}` : '';
+    return `  ${p.title}${mark}${why}`;
+}
 /** Count of opt-in (default-ON) practices in the named tiers — for the menu labels. */
 function presetCount(catalog, preset) {
     return (0, select_1.presetSelections)(catalog, preset).length;
@@ -55,22 +74,25 @@ async function pickPracticesInteractively(catalog) {
     }
 }
 /**
- * Customize from the recommended preset: for each chosen practice show
- * `title [defaultLevel]` and accept enter=keep, 's'=skip, or a level name from
- * availableLevels. Skimmable; unknown levels re-prompt-free (keep at default).
+ * Customize from the recommended preset: for each chosen practice show its title,
+ * provenance, and a one-line `why` (via practiceBlurb), then accept enter=keep,
+ * 's'=skip, or a level name from availableLevels. Skimmable; unknown levels
+ * re-prompt-free (keep at default).
  */
 async function customize(catalog, rl) {
     const base = (0, select_1.presetSelections)(catalog, 'recommended');
     const byId = new Map(catalog.practices.map((p) => [p.id, p]));
     const result = [];
     out('');
-    out('Customize — for each: [enter] keep · [s] skip · or type a level name.');
+    out('Customize — for each: [enter] keep the suggested level · [s] skip · or type a level name.');
     for (const sel of base) {
         const p = byId.get(sel.id);
         if (!p)
             continue;
         const levels = p.availableLevels.join('/');
-        const ans = (await rl.question(`  ${p.title} [${sel.level}] (${levels}): `)).trim().toLowerCase();
+        out('');
+        out(practiceBlurb(p));
+        const ans = (await rl.question(`    [${sel.level}] (${levels}): `)).trim().toLowerCase();
         if (ans === 's' || ans === 'skip')
             continue;
         if (ans === '') {

package/dist/commands/auth.js

@@ -6,9 +6,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.login = login;
 exports.whoami = whoami;
 exports.assessLaneIdentity = assessLaneIdentity;
+exports.assessSettingsIntegrity = assessSettingsIntegrity;
 exports.doctor = doctor;
 /** login / whoami / doctor. */
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 const brand_1 = require("../brand");
 const api_1 = require("../api");
@@ -18,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;
@@ -152,6 +165,96 @@ function assessLaneIdentity(lanes, myHandle, haveInstance, staleSec = LANE_STALE
     }
     return { name, ok: true, detail: `holding ${mine.length} lane(s), all fresh and owned by this session` };
 }
+/** Count non-overlapping occurrences of `sub` in `s`. */
+function countOccurrences(s, sub) {
+    if (!sub)
+        return 0;
+    let n = 0;
+    let i = s.indexOf(sub);
+    while (i >= 0) {
+        n++;
+        i = s.indexOf(sub, i + sub.length);
+    }
+    return n;
+}
+/**
+ * Non-destructiveness assertion (feedback 3749eac9 / dhparmele): Convene earns
+ * authority by scope + ADDITIVE merge, never by overwriting user-owned files. This
+ * check confirms that posture is intact:
+ *   - the global + project `.claude/settings.json` parse as JSON (a file Convene
+ *     would otherwise leave untouched but also could not merge into — worth flagging);
+ *   - any Convene hook coexists with user-owned hooks (additivity, not whole-object
+ *     replace) — reported as a positive note, NEVER a failure;
+ *   - the CLAUDE.md / AGENTS.md Convene marker blocks are well-formed (a balanced,
+ *     non-inverted begin/end pair) so a `--refresh-docs` re-render stays surgical.
+ * Fails (ok:false) ONLY on genuine corruption (invalid JSON / malformed markers),
+ * never on a user simply having their own hooks. Diagnostic only — no auto-repair.
+ * Exported + parameterized so it can be asserted hermetically without a TTY/network.
+ */
+function assessSettingsIntegrity(top, globalSettingsPath = hook_1.SETTINGS_PATH) {
+    const name = 'settings';
+    const problems = [];
+    const notes = [];
+    const settingsFiles = [{ label: 'global', file: globalSettingsPath }];
+    if (top)
+        settingsFiles.push({ label: 'project', file: (0, hook_1.projectSettingsPath)(top) });
+    for (const { label, file } of settingsFiles) {
+        if (!node_fs_1.default.existsSync(file))
+            continue;
+        let parsed;
+        try {
+            const raw = node_fs_1.default.readFileSync(file, 'utf8');
+            parsed = raw.trim() === '' ? {} : JSON.parse(raw);
+        }
+        catch {
+            problems.push(`${label} settings.json is not valid JSON — Convene leaves it untouched but cannot merge into it (${file})`);
+            continue;
+        }
+        if (parsed && typeof parsed === 'object' && parsed.hooks && typeof parsed.hooks === 'object') {
+            let convene = 0;
+            let foreign = 0;
+            for (const ev of Object.keys(parsed.hooks)) {
+                const groups = Array.isArray(parsed.hooks[ev]) ? parsed.hooks[ev] : [];
+                for (const g of groups) {
+                    const isConvene = Array.isArray(g?.hooks) &&
+                        g.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('convene'));
+                    if (isConvene)
+                        convene++;
+                    else
+                        foreign++;
+                }
+            }
+            if (foreign > 0)
+                notes.push(`${label}: ${foreign} user-owned hook(s) preserved alongside ${convene} Convene hook(s)`);
+        }
+    }
+    if (top) {
+        for (const fname of ['CLAUDE.md', 'AGENTS.md']) {
+            const p = node_path_1.default.join(top, fname);
+            if (!node_fs_1.default.existsSync(p))
+                continue;
+            let content;
+            try {
+                content = node_fs_1.default.readFileSync(p, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const begins = countOccurrences(content, brand_1.BRAND.blockBegin);
+            const ends = countOccurrences(content, brand_1.BRAND.blockEnd);
+            if (begins !== ends || begins > 1) {
+                problems.push(`${fname} has a malformed Convene marker block (${begins} begin / ${ends} end) — repair the markers before a refresh`);
+            }
+            else if (begins === 1 && content.indexOf(brand_1.BRAND.blockBegin) > content.indexOf(brand_1.BRAND.blockEnd)) {
+                problems.push(`${fname} Convene marker block is inverted (begin after end) — repair the markers`);
+            }
+        }
+    }
+    if (problems.length)
+        return { name, ok: false, detail: problems.join('; ') };
+    const tail = notes.length ? ` (${notes.join('; ')})` : '';
+    return { name, ok: true, detail: `settings JSON valid + marker blocks intact; Convene edits are additive${tail}` };
+}
 async function doctor(opts) {
     const checks = [];
     const cfg = (0, config_1.resolveConfig)();
@@ -228,6 +331,9 @@ async function doctor(opts) {
                 ? 'UserPromptSubmit `convene fetch` registered'
                 : 'hook NOT registered (run `convene init` or `convene doctor --fix`)',
     });
+    // 6b. settings non-destructiveness — Convene's edits stay additive + marker-scoped;
+    //     user-owned hooks/files are never clobbered. Fails only on genuine corruption.
+    checks.push(assessSettingsIntegrity(top));
     // 7. watch heartbeat — a stale/absent heartbeat means the mid-task halt watcher
     // is DOWN (so directed halts won't surface between turns). Only meaningful for a
     // repo on the bus; --fix may (re)launch `convene watch` detached.
@@ -235,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) {
@@ -255,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/catchup.js

@@ -25,7 +25,9 @@ const cache_1 = require("../cache");
 const api_1 = require("../api");
 const exit_1 = require("../exit");
 const render_1 = require("../render");
-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;
 function emit(s) {

package/dist/commands/fetch.js

@@ -29,7 +29,9 @@ const render_1 = require("../render");
 const catchup_1 = require("./catchup");
 const exit_1 = require("../exit");
 const CACHE_TTL_SEC = 3;
-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;
 /** Catalog-version cache TTL for the behind-nudge — long enough to stay off the hot path. */
 const CATALOG_VERSION_TTL_SEC = 3600;
@@ -50,8 +52,9 @@ const CATALOG_VERSION_TTL_SEC = 3600;
 // fast blip, given the bus normally answers in ~0.15s.
 /** Total network budget for the feed fetch across all attempts (== FETCH_TIMEOUT_MS). */
 const FEED_BUDGET_MS = FETCH_TIMEOUT_MS;
-/** First-attempt timeout. ~500ms under FETCH_TIMEOUT_MS, leaving room for a retry. */
-const FEED_ATTEMPT_MS = 3500;
+/** First-attempt timeout. ~500ms under FETCH_TIMEOUT_MS, leaving room for a retry.
+ *  Derived from FETCH_TIMEOUT_MS so a small env override never exceeds the budget. */
+const FEED_ATTEMPT_MS = Math.max(250, FETCH_TIMEOUT_MS - 500);
 /** A failure faster than this is treated as a transient blip worth one retry. */
 exports.FEED_FAST_FAIL_MS = 1200;
 /** Brief pause before the retry, to let a restarting task come back. */
@@ -284,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 };
+    });
+}