convene-cli 1.0.5 → 1.1.1

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,9 +86,37 @@ 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 });
     }
+    /**
+     * GET /help — "Ask Convene" self-knowledge (PUBLIC, no tenant data). With `q`
+     * returns the matched topics; powers `convene explain`. Bounded by a short timeout.
+     */
+    help(q, timeoutMs) {
+        const params = new URLSearchParams();
+        if (q)
+            params.set('q', q);
+        const qs = params.toString();
+        return this.request('GET', `/help${qs ? `?${qs}` : ''}`, { timeoutMs });
+    }
     post(slug, body, idempotencyKey, timeoutMs) {
         return this.request('POST', `/projects/${encodeURIComponent(slug)}/messages`, {
             body,
@@ -106,5 +149,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,23 @@ 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.liveSessionCount = liveSessionCount;
+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
@@ -14,8 +28,20 @@ exports.ageSeconds = ageSeconds;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("./config");
+const git_1 = require("./git");
+/**
+ * Per-SESSION local-state key. Two Claude windows in one checkout share a slug,
+ * so slug-only file names collide — they clobber each other's session-instance,
+ * catch-up sentinel, and feed cache. Appending the session discriminator gives
+ * each concurrent session its own files. Absent a discriminator (plain terminal)
+ * this is just the bare slug, so existing single-session files are untouched.
+ */
+function scoped(slug) {
+    const d = (0, git_1.sessionDiscriminator)();
+    return d ? `${slug}#${d}` : slug;
+}
 function cacheFile(slug) {
-    return node_path_1.default.join(config_1.CACHE_DIR, `${slug.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
+    return node_path_1.default.join(config_1.CACHE_DIR, `${scoped(slug).replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
 }
 function readCache(slug) {
     try {
@@ -37,3 +63,236 @@ 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(scoped(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(scoped(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);
+}
+/**
+ * Count DISTINCT sessions that have touched this checkout within `maxAgeSec`, by
+ * scanning the per-session local-state files for `<slug>` (`.json` cache, refreshed
+ * each active prompt, + `.instance`). A bare slug and each `#<disc>` scope counts
+ * once. `doctor` uses this to nudge toward one-worktree-per-session when several
+ * agents share a checkout. Best-effort: any error → 0 (no nudge). The slug is
+ * sanitized to `[A-Za-z0-9_-]` so it is already regex-safe to anchor.
+ */
+function liveSessionCount(slug, maxAgeSec) {
+    try {
+        const san = slug.replace(/[^a-zA-Z0-9_-]/g, '_');
+        const re = new RegExp(`^${san}(_[a-z0-9-]+)?\\.(json|instance)$`);
+        const cutoff = Date.now() - maxAgeSec * 1000;
+        const scopes = new Set();
+        for (const f of node_fs_1.default.readdirSync(config_1.CACHE_DIR)) {
+            const m = f.match(re);
+            if (!m)
+                continue;
+            let mtimeMs;
+            try {
+                mtimeMs = node_fs_1.default.statSync(node_path_1.default.join(config_1.CACHE_DIR, f)).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (mtimeMs < cutoff)
+                continue;
+            scopes.add(m[1] ?? ''); // the `_<disc>` token, or '' for a no-discriminator session
+        }
+        return scopes.size;
+    }
+    catch {
+        return 0;
+    }
+}
+// ── 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(scoped(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,87 @@ 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)`,
+        });
+    }
+    // 7b. parallel sessions sharing ONE checkout. Several agents in the same
+    // working tree clobber each other's uncommitted files and (absent the
+    // discriminator) collapse to one bus identity. Convene now auto-disambiguates
+    // them, but a worktree apiece is the cleaner default — so nudge when ≥2 sessions
+    // have recently touched this checkout. Purely informational (never fails doctor).
+    if (proj?.slug) {
+        const n = (0, cache_1.liveSessionCount)(proj.slug, 30 * 60); // active within the last 30 min
+        if (n >= 2) {
+            checks.push({
+                name: 'sessions',
+                ok: true,
+                detail: `${n} sessions share this checkout (last 30m) — prefer one git worktree each: \`convene worktree <branch>\``,
+            });
+        }
+    }
+    // 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`);
     }