convene-cli 1.0.4 → 1.1.0

package/dist/api.js

@@ -8,11 +8,24 @@ class ConveneApi {
     apiKey;
     session;
     tool;
-    constructor(baseUrl, apiKey, session = null, tool = null) {
+    instance;
+    constructor(baseUrl, apiKey, session = null, tool = null, 
+    /**
+     * Server-trusted opaque session-instance id (X-Convene-Session-Instance).
+     * The server scopes it to principal.memberId to stamp holder_instance; it
+     * never authorizes anything on its own. Optional — absent on legacy callers.
+     */
+    instance = null) {
         this.baseUrl = baseUrl;
         this.apiKey = apiKey;
         this.session = session;
         this.tool = tool;
+        this.instance = instance;
+    }
+    /** Attach/replace the session-instance id after construction (SessionStart mint). */
+    withInstance(instance) {
+        this.instance = instance;
+        return this;
     }
     async request(method, apiPath, opts = {}) {
         const ctrl = new AbortController();
@@ -25,6 +38,8 @@ class ConveneApi {
                 headers['x-convene-session'] = this.session;
             if (this.tool)
                 headers['x-convene-tool'] = this.tool;
+            if (this.instance)
+                headers['x-convene-session-instance'] = this.instance;
             if (opts.idempotencyKey)
                 headers['idempotency-key'] = opts.idempotencyKey;
             const res = await fetch(`${this.baseUrl}${brand_1.BRAND.apiBase}${apiPath}`, {
@@ -71,6 +86,23 @@ class ConveneApi {
         const p = slug ? `/projects/${encodeURIComponent(slug)}/inbox` : '/inbox';
         return this.request('GET', p, { timeoutMs });
     }
+    /**
+     * GET /poll — the long-poll stream `convene watch` consumes. `since` is the
+     * resume cursor (Last-Event-ID semantics, a messages.id); `wait` is the server
+     * hold (seconds, capped server-side at 50). Returns `{messages, cursor}`; the
+     * server already relevance-filters to this session, the client further filters
+     * to halt/interrupt. The timeout MUST exceed `wait*1000` so the long-poll isn't
+     * aborted before the server's own deadline.
+     */
+    poll(slug, q = {}, timeoutMs) {
+        const params = new URLSearchParams();
+        if (q.since != null)
+            params.set('since', String(q.since));
+        if (q.wait != null)
+            params.set('wait', String(q.wait));
+        const qs = params.toString();
+        return this.request('GET', `/projects/${encodeURIComponent(slug)}/poll${qs ? `?${qs}` : ''}`, { timeoutMs });
+    }
     resolveRepo(repo, timeoutMs) {
         return this.request('GET', `/projects/resolve?repo=${encodeURIComponent(repo)}`, { timeoutMs });
     }
@@ -106,5 +138,64 @@ class ConveneApi {
     getProject(slug, timeoutMs) {
         return this.request('GET', `/projects/${encodeURIComponent(slug)}`, { timeoutMs });
     }
+    // ── Catch-up / session-open (WP2) ──────────────────────────────────────────
+    /**
+     * GET /session-open — the "open already knowing the world" digest. `advance`
+     * advances the read cursor in the SAME server transaction that returns the
+     * digest (rendered ⇒ advanced atomic). `since` overrides the stored cursor.
+     * Bounded by an explicit short timeout — never the 10s default.
+     */
+    sessionOpen(slug, q = {}, timeoutMs) {
+        const params = new URLSearchParams();
+        if (q.since != null)
+            params.set('since', String(q.since));
+        if (q.advance)
+            params.set('advance', 'true');
+        if (q.maxItems != null)
+            params.set('maxItems', String(q.maxItems));
+        const qs = params.toString();
+        return this.request('GET', `/projects/${encodeURIComponent(slug)}/session-open${qs ? `?${qs}` : ''}`, { timeoutMs });
+    }
+    /** POST /catchup/seen — render-then-advance cursor (monotonic GREATEST on the server). */
+    catchupSeen(slug, seq, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/catchup/seen`, {
+            body: { seq },
+            idempotencyKey: `seen:${seq}`,
+            timeoutMs,
+        });
+    }
+    // ── Lanes (WP6) ────────────────────────────────────────────────────────────
+    /** GET /lanes — live board + recent releases (read-only, fail-open). */
+    lanes(slug, timeoutMs) {
+        return this.request('GET', `/projects/${encodeURIComponent(slug)}/lanes`, { timeoutMs });
+    }
+    /** GET /lane-state — the trusted read (server-derived holder_instance_self + ages). */
+    laneState(slug, intent, timeoutMs) {
+        const qs = intent ? `?intent=${encodeURIComponent(intent)}` : '';
+        return this.request('GET', `/projects/${encodeURIComponent(slug)}/lane-state${qs}`, { timeoutMs });
+    }
+    /**
+     * POST /lanes/:lane/claim — 200 {granted:true} on success (incl. self-renew),
+     * 409 LANE_HELD on a foreign conflict. holder_instance is stamped server-side
+     * from the X-Convene-Session-Instance header attached by this client.
+     */
+    laneClaim(slug, lane, body = {}, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/lanes/${encodeURIComponent(lane)}/claim`, { body, timeoutMs });
+    }
+    /** POST /lanes/:lane/release — holder-only; 200 even on a no-op (idempotent). */
+    laneRelease(slug, lane, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/lanes/${encodeURIComponent(lane)}/release`, { timeoutMs });
+    }
+    /** POST /lanes/:lane/force-release — owner-only (server-gated by middleware). */
+    laneForceRelease(slug, lane, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/lanes/${encodeURIComponent(lane)}/force-release`, { timeoutMs });
+    }
+    /**
+     * POST /gate-push — thin-client parity verdict (LANE-AUTHORITATIVE, compat
+     * advisory). Returns {verdict:'allow'|'wait'|'rebase', holder?}.
+     */
+    gatePush(slug, body, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/gate-push`, { body, timeoutMs });
+    }
 }
 exports.ConveneApi = ConveneApi;

package/dist/cache.js

@@ -3,9 +3,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeWatchHighWater = void 0;
 exports.readCache = readCache;
 exports.writeCache = writeCache;
 exports.ageSeconds = ageSeconds;
+exports.readSessionInstance = readSessionInstance;
+exports.mintSessionInstance = mintSessionInstance;
+exports.ensureSessionInstance = ensureSessionInstance;
+exports.markCatchupSurfaced = markCatchupSurfaced;
+exports.catchupAlreadySurfaced = catchupAlreadySurfaced;
+exports.readWatchHighWater = readWatchHighWater;
+exports.persistHighWater = persistHighWater;
+exports.appendWatchEntry = appendWatchEntry;
+exports.appendWatch = appendWatch;
+exports.readWatchSince = readWatchSince;
+exports.touchWatchHeartbeat = touchWatchHeartbeat;
+exports.watchHeartbeatAgeSec = watchHeartbeatAgeSec;
 /**
  * Tiny per-project file cache so rapid successive prompts don't each hit the
  * network (P0-LATENCY). Short TTL; on a fetch failure the stale cache still
@@ -37,3 +50,201 @@ function writeCache(slug, data) {
 function ageSeconds(entry) {
     return Math.max(0, Math.round((Date.now() - entry.fetchedAt) / 1000));
 }
+// ── session-instance id (WP2) ────────────────────────────────────────────────
+// An opaque per-session UUID minted at SessionStart and persisted in CACHE_DIR.
+// Sent as X-Convene-Session-Instance so the server can stamp holder_instance and
+// disambiguate same-basename worktrees / two terminals in one checkout. It NEVER
+// authorizes anything by itself — the server scopes it to principal.memberId.
+function slugFile(slug, ext) {
+    return node_path_1.default.join(config_1.CACHE_DIR, `${slug.replace(/[^a-zA-Z0-9_-]/g, '_')}.${ext}`);
+}
+function newUuid() {
+    try {
+        return require('node:crypto').randomUUID();
+    }
+    catch {
+        return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    }
+}
+/** The opaque session-instance id for this slug, or null if none minted yet. */
+function readSessionInstance(slug) {
+    try {
+        const v = node_fs_1.default.readFileSync(slugFile(slug, 'instance'), 'utf8').trim();
+        return v || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Mint (always overwrite) a fresh opaque session-instance UUID at SessionStart.
+ * A fresh boot is a fresh instance, so overwriting is correct.
+ */
+function mintSessionInstance(slug) {
+    const id = newUuid();
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(slugFile(slug, 'instance'), id + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* best-effort; the caller still uses the in-memory value */
+    }
+    return id;
+}
+/** The session-instance id, minting one if absent (used by non-SessionStart verbs). */
+function ensureSessionInstance(slug) {
+    return readSessionInstance(slug) || mintSessionInstance(slug);
+}
+// ── 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
+// and suppresses a duplicate rollup. Keyed by instance so a NEW boot (new
+// instance) always re-surfaces.
+function sentinelFile(slug) {
+    return slugFile(slug, 'catchup-seen');
+}
+/** Mark that SessionStart has already surfaced a catch-up for this instance. */
+function markCatchupSurfaced(slug, instance) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(sentinelFile(slug), instance + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** True iff a catch-up was already surfaced for this exact session-instance. */
+function catchupAlreadySurfaced(slug, instance) {
+    try {
+        return node_fs_1.default.readFileSync(sentinelFile(slug), 'utf8').trim() === instance;
+    }
+    catch {
+        return false;
+    }
+}
+function watchFile(slug) {
+    return slugFile(slug, 'watch.jsonl');
+}
+function watchHighWaterFile(slug) {
+    return slugFile(slug, 'watch.hw');
+}
+function watchHeartbeatFile(slug) {
+    return slugFile(slug, 'watch.hb');
+}
+/** Read the persisted high-water seq for the watch jsonl (0 if none). */
+function readWatchHighWater(slug) {
+    try {
+        const n = parseInt(node_fs_1.default.readFileSync(watchHighWaterFile(slug), 'utf8').trim(), 10);
+        return Number.isFinite(n) ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Persist the high-water seq for the watch jsonl — MONOTONIC. A lower seq is
+ * ignored (GREATEST semantics) so a reader can never rewind past material it
+ * already drained. NEVER truncates the jsonl.
+ */
+function persistHighWater(slug, seq) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        const cur = readWatchHighWater(slug);
+        if (seq > cur)
+            node_fs_1.default.writeFileSync(watchHighWaterFile(slug), String(seq) + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Back-compat alias for the WP2 stub name; identical monotonic behavior. */
+exports.writeWatchHighWater = persistHighWater;
+/**
+ * APPEND a watch entry to the jsonl (append-only — never rewrites the file).
+ * The append is atomic at the OS level for a single small write, so a concurrent
+ * reader sees whole lines. Best-effort; never throws (the watch daemon is
+ * fail-open). Entries WITHOUT a finite numeric seq are dropped — an un-keyed
+ * entry can't participate in the high-water drain and would be re-rendered
+ * forever.
+ */
+function appendWatchEntry(slug, entry) {
+    if (!entry || typeof entry.seq !== 'number' || !Number.isFinite(entry.seq))
+        return;
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.appendFileSync(watchFile(slug), JSON.stringify(entry) + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Back-compat alias for the WP2 stub name. */
+function appendWatch(slug, entry) {
+    appendWatchEntry(slug, entry);
+}
+/**
+ * Read all watch entries with seq > highWater, ascending by seq, de-duplicated
+ * on seq (the daemon may re-append the same entry after a resume — the reader
+ * tolerates duplicates by keeping the first per seq). Does NOT advance the
+ * high-water and does NOT truncate — the caller decides what was actually
+ * rendered and calls persistHighWater(slug, lastRenderedSeq). A malformed line
+ * is skipped, never fatal.
+ */
+function readWatchSince(slug, highWater) {
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(watchFile(slug), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const seen = new Set();
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const s = line.trim();
+        if (!s)
+            continue;
+        let e;
+        try {
+            e = JSON.parse(s);
+        }
+        catch {
+            continue; // a torn/partial line — skip, the next drain re-reads it whole
+        }
+        if (typeof e.seq !== 'number' || !Number.isFinite(e.seq))
+            continue;
+        if (e.seq <= highWater)
+            continue;
+        if (seen.has(e.seq))
+            continue;
+        seen.add(e.seq);
+        out.push(e);
+    }
+    out.sort((a, b) => a.seq - b.seq);
+    return out;
+}
+// ── watch heartbeat (WP12) ───────────────────────────────────────────────────
+// The daemon stamps a heartbeat each loop iteration; the health line / doctor
+// read its age. A stale/absent heartbeat ⇒ watch is down ⇒ surface DEGRADED.
+/** Stamp the watch heartbeat (epoch ms). Best-effort; never throws. */
+function touchWatchHeartbeat(slug) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(watchHeartbeatFile(slug), String(Date.now()) + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Age of the watch heartbeat in seconds, or null if never stamped/unreadable. */
+function watchHeartbeatAgeSec(slug) {
+    try {
+        const ms = parseInt(node_fs_1.default.readFileSync(watchHeartbeatFile(slug), 'utf8').trim(), 10);
+        if (!Number.isFinite(ms))
+            return null;
+        return Math.max(0, Math.round((Date.now() - ms) / 1000));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/auth.js

@@ -5,15 +5,37 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.login = login;
 exports.whoami = whoami;
+exports.assessLaneIdentity = assessLaneIdentity;
 exports.doctor = doctor;
 /** login / whoami / doctor. */
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_child_process_1 = require("node:child_process");
 const brand_1 = require("../brand");
 const api_1 = require("../api");
 const config_1 = require("../config");
 const git_1 = require("../git");
 const hook_1 = require("../hook");
+const cache_1 = require("../cache");
 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() {
+    try {
+        const bin = process.argv[1] || '';
+        if (!bin)
+            return false;
+        const child = (0, node_child_process_1.spawn)(process.execPath, [bin, 'watch'], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function readStdin() {
     try {
         return node_fs_1.default.readFileSync(0, 'utf8').trim();
@@ -67,6 +89,67 @@ async function whoami() {
     process.stdout.write(`server:   ${me.ok ? 'reachable' : 'UNREACHABLE'}\n`);
     // The API key is never printed.
 }
+/** A lane this session holds whose heartbeat is older than this looks wedged. */
+const LANE_STALE_SEC = 600;
+/**
+ * PLAN §11 "two-humans-on-one-handle" mitigation. `holder_instance` disambiguates
+ * worktrees, but a genuinely shared API key still shares a member identity — so a
+ * deploy lane can be held under YOUR handle by a session that ISN'T this one. This
+ * surfaces that, plus a hold this session owns that has gone stale. Two flags:
+ *   - COLLISION (✗): a live lane held under your handle by a DIFFERENT instance —
+ *     a shared key or a sibling worktree/terminal. A release/force under your key
+ *     affects it, so you should know before you act.
+ *   - STALE-MINE (✗): a lane THIS session holds whose heartbeat has gone cold — a
+ *     likely-wedged hold worth releasing so it stops blocking others.
+ * Pure + deterministic so it unit-tests without the network. When no
+ * session-instance was minted (`haveInstance=false`) we cannot trust
+ * holder_instance_self to tell "me" from "a sibling", so we report UNVERIFIED
+ * rather than false-alarming every lane as a collision.
+ */
+function assessLaneIdentity(lanes, myHandle, haveInstance, staleSec = LANE_STALE_SEC) {
+    const name = 'identity';
+    if (!myHandle)
+        return { name, ok: true, detail: 'skipped (no member identity)' };
+    const mine = lanes.filter((l) => l.holder_handle === myHandle);
+    if (mine.length === 0)
+        return { name, ok: true, detail: 'no deploy lane held under your identity' };
+    const label = (l) => {
+        const bits = [];
+        if (l.holder_tool)
+            bits.push(`tool=${l.holder_tool}`);
+        if (l.holder_session)
+            bits.push(`session=${l.holder_session}`);
+        bits.push(`heartbeat ${l.heartbeat_age_sec}s ago`);
+        return `${l.lane} (${bits.join(', ')})`;
+    };
+    if (!haveInstance) {
+        return {
+            name,
+            ok: true,
+            detail: `holding ${mine.length} lane(s) under your handle, but no session-instance is minted — ` +
+                `"you vs a sibling session under the same key" is UNVERIFIED; run inside a Claude Code session for the full check`,
+        };
+    }
+    const collisions = mine.filter((l) => !l.holder_instance_self);
+    if (collisions.length) {
+        return {
+            name,
+            ok: false,
+            detail: 'lane held under your handle by ANOTHER session — likely a shared API key or a sibling worktree/terminal ' +
+                `(a release/force under your key affects it): ${collisions.map(label).join('; ')}`,
+        };
+    }
+    const stale = mine.filter((l) => l.holder_instance_self && l.heartbeat_age_sec > staleSec);
+    if (stale.length) {
+        return {
+            name,
+            ok: false,
+            detail: 'a lane THIS session holds looks stale — likely a wedged hold; release it if that deploy is done ' +
+                `(\`convene lane release <lane>\`): ${stale.map(label).join('; ')}`,
+        };
+    }
+    return { name, ok: true, detail: `holding ${mine.length} lane(s), all fresh and owned by this session` };
+}
 async function doctor(opts) {
     const checks = [];
     const cfg = (0, config_1.resolveConfig)();
@@ -143,6 +226,72 @@ async function doctor(opts) {
                 ? 'UserPromptSubmit `convene fetch` registered'
                 : 'hook NOT registered (run `convene init` or `convene doctor --fix`)',
     });
+    // 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.
+    if (proj?.slug) {
+        let age = (0, cache_1.watchHeartbeatAgeSec)(proj.slug);
+        let watchOk = age != null && age <= WATCH_STALE_SEC;
+        if (!watchOk && opts.fix) {
+            if (relaunchWatch()) {
+                // Give the freshly-launched daemon a beat to stamp its first heartbeat.
+                const until = Date.now() + 2500;
+                while (Date.now() < until) {
+                    age = (0, cache_1.watchHeartbeatAgeSec)(proj.slug);
+                    if (age != null && age <= WATCH_STALE_SEC)
+                        break;
+                }
+                watchOk = age != null && age <= WATCH_STALE_SEC;
+            }
+        }
+        checks.push({
+            name: 'watch',
+            ok: watchOk,
+            detail: watchOk
+                ? `halt watcher alive (heartbeat ${age}s ago)`
+                : age == null
+                    ? 'halt watcher DOWN — no heartbeat (run `convene doctor --fix` to relaunch)'
+                    : `halt watcher STALE — heartbeat ${age}s ago (run \`convene doctor --fix\` to relaunch)`,
+        });
+    }
+    // 8. lane identity (PLAN §11 two-humans-on-one-handle). A deploy lane held under
+    // your handle by a different session-instance (shared key / sibling worktree) or
+    // a stale hold this session owns. Fail-open: a lane-state read failure is
+    // informational, never a hard doctor failure. Sends this session's minted
+    // instance so the server can compute holder_instance_self trustworthily.
+    if (proj?.slug && cfg.apiKey) {
+        const session = cfg.member && top ? (0, git_1.sessionId)(cfg.member, top) : null;
+        const instance = (0, cache_1.readSessionInstance)(proj.slug);
+        const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+        const [state, board] = await Promise.all([
+            api.laneState(proj.slug, null, 4000),
+            api.lanes(proj.slug, 4000),
+        ]);
+        if (!state.ok || !Array.isArray(state.json?.lanes)) {
+            checks.push({ name: 'identity', ok: true, detail: 'skipped (lane-state unreachable)' });
+        }
+        else {
+            // Enrich each trusted lane-state row with display tool/session from the
+            // board (best-effort — the board read may fail independently).
+            const boardByLane = new Map();
+            if (board.ok && Array.isArray(board.json?.lanes)) {
+                for (const b of board.json.lanes)
+                    boardByLane.set(b.lane, b);
+            }
+            const rows = state.json.lanes.map((l) => {
+                const b = boardByLane.get(l.lane);
+                return {
+                    lane: l.lane,
+                    holder_handle: l.holder_handle ?? null,
+                    holder_instance_self: !!l.holder_instance_self,
+                    heartbeat_age_sec: Number(l.heartbeat_age_sec) || 0,
+                    holder_tool: b?.holder_tool ?? null,
+                    holder_session: b?.holder_session ?? null,
+                };
+            });
+            checks.push(assessLaneIdentity(rows, cfg.member ?? null, instance != null));
+        }
+    }
     for (const c of checks) {
         process.stdout.write(`${c.ok ? '✓' : '✗'} ${c.name.padEnd(8)} ${c.detail}\n`);
     }

package/dist/commands/catchup.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.worktreeBasename = void 0;
+exports.toDigest = toDigest;
+exports.catchup = catchup;
+/**
+ * `convene catchup` (alias `latest`) — the "open already knowing the world"
+ * digest, rendered as the <convene-session-open> block.
+ *
+ * DUAL FAILURE POSTURE (PLAN §4.1):
+ *   - In --session-start mode it is FAIL-OPEN: any error/timeout/DEGRADED exits 0
+ *     silently (a watchdog backstops a hang), because this runs as the
+ *     SessionStart hook and must never wedge a boot.
+ *   - On an EXPLICIT human invocation it DIES LOUD: a fetch failure prints to
+ *     stderr and exits 1, so the human knows the digest is unavailable.
+ *
+ * DEGRADED suppression is structural: the <convene-session-open> block is emitted
+ * ONLY from a fresh res.ok payload. Under DEGRADED (or any failure) we never
+ * reconstruct it from cache — session-start emits nothing; explicit mode dies.
+ */
+const git_1 = require("../git");
+Object.defineProperty(exports, "worktreeBasename", { enumerable: true, get: function () { return git_1.worktreeBasename; } });
+const config_1 = require("../config");
+const cache_1 = require("../cache");
+const api_1 = require("../api");
+const render_1 = require("../render");
+const FETCH_TIMEOUT_MS = 4000;
+const WATCHDOG_MS = 6000;
+const MAX_ITEMS = 400;
+function emit(s) {
+    process.stdout.write(s + '\n');
+}
+/** Map a server /session-open payload into the render digest (display-shaped). */
+function toDigest(payload) {
+    const since = payload?.since ?? {};
+    return {
+        since: {
+            seq: Number(since.seq ?? 0),
+            relative: since.relative ?? null,
+            is_new_member: Boolean(since.is_new_member),
+            truncated: Boolean(since.truncated),
+        },
+        head_seq: Number(payload?.head_seq ?? 0),
+        counts: payload?.catchup?.counts ?? {},
+        sample: Array.isArray(payload?.catchup?.sample) ? payload.catchup.sample : [],
+        lanes: Array.isArray(payload?.lanes) ? payload.lanes : [],
+        inbox: Array.isArray(payload?.inbox) ? payload.inbox : [],
+        halts: Array.isArray(payload?.halts) ? payload.halts : [],
+    };
+}
+/**
+ * Core: fetch + render the catch-up block. Returns the rendered block (or null on
+ * an empty/failed fetch in a way the caller decides how to surface). `failOpen`
+ * controls whether a failure throws (explicit mode) or returns null (hook mode).
+ */
+async function runCatchup(opts) {
+    const failOpen = Boolean(opts.sessionStart);
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        return; // not a git repo
+    const proj = (0, config_1.loadProjectConfig)(top);
+    if (!proj?.slug)
+        return; // not on the bus → no-op
+    const slug = proj.slug;
+    const cfg = (0, config_1.resolveConfig)();
+    if (!cfg.apiKey || !cfg.member) {
+        if (failOpen)
+            return;
+        process.stderr.write('convene: not configured — run `convene login`\n');
+        process.exit(1);
+    }
+    const member = cfg.member;
+    const session = (0, git_1.sessionId)(member, top);
+    const instance = (0, cache_1.ensureSessionInstance)(slug);
+    const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+    const since = opts.since != null ? Number(opts.since) : undefined;
+    // Default advance=true (the cursor moves as material is shown); --no-advance opts out.
+    const advance = opts.advance !== false;
+    const res = await api.sessionOpen(slug, { since: Number.isFinite(since) ? since : undefined, advance, maxItems: MAX_ITEMS }, FETCH_TIMEOUT_MS);
+    if (!res.ok || !res.json || res.json.degraded) {
+        if (opts.json) {
+            emit(JSON.stringify({ degraded: true, error: res.error ?? 'degraded' }));
+            return;
+        }
+        if (failOpen)
+            return; // session-start: emit nothing under DEGRADED/failure
+        process.stderr.write(`convene: catch-up unavailable (${res.status || 'network'}): ${res.error ?? 'could not reach the bus'}\n`);
+        process.exit(1);
+    }
+    if (opts.json) {
+        emit(JSON.stringify(res.json));
+    }
+    else {
+        emit((0, render_1.renderSessionOpenBlock)({ slug, member, session, digest: toDigest(res.json) }));
+    }
+    // In session-start mode, drop the per-boot dedup sentinel so the first
+    // UserPromptSubmit fetch of this boot suppresses a duplicate rollup.
+    if (opts.sessionStart)
+        (0, cache_1.markCatchupSurfaced)(slug, instance);
+}
+/** `convene catchup` / `convene latest`. */
+async function catchup(opts = {}) {
+    if (opts.sessionStart) {
+        // Fail-open hook posture: hard watchdog + swallow everything → exit 0.
+        const watchdog = setTimeout(() => process.exit(0), WATCHDOG_MS);
+        try {
+            await runCatchup(opts);
+        }
+        catch {
+            /* fail-open */
+        }
+        clearTimeout(watchdog);
+        process.exit(0);
+    }
+    // Explicit invocation: die-loud on failure (runCatchup calls process.exit(1)).
+    try {
+        await runCatchup(opts);
+    }
+    catch (err) {
+        process.stderr.write(`convene: ${err?.message || err}\n`);
+        process.exit(1);
+    }
+}