convene-cli 1.9.0 → 1.11.0

package/dist/api.js

@@ -154,6 +154,18 @@ class ConveneApi {
     join(slug, body, timeoutMs) {
         return this.request('POST', `/projects/${encodeURIComponent(slug)}/join`, { body, timeoutMs });
     }
+    /** Self-recovery: re-grant your own membership via the committed join token (no bearer
+     *  auth required). Restores OWNER only from a server-recorded prior-owner row. */
+    reclaim(slug, body, timeoutMs) {
+        return this.request('POST', `/projects/${encodeURIComponent(slug)}/reclaim`, { body, timeoutMs });
+    }
+    /** Owner: PERMANENTLY delete your own project (typed confirm_slug; owner-role-gated). */
+    deleteProjectOwner(slug, confirmSlug, timeoutMs) {
+        return this.request('DELETE', `/projects/${encodeURIComponent(slug)}`, {
+            body: { confirm_slug: confirmSlug },
+            timeoutMs,
+        });
+    }
     /** Self-serve: provision a brand-new global identity + key (no bearer auth). */
     provision(body, timeoutMs) {
         return this.request('POST', '/provision', { body, timeoutMs });

package/dist/binding-local.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localBindingDrift = localBindingDrift;
+/**
+ * The local-only (network-free) host-pin drift line shared by the two hot paths —
+ * the `convene fetch` UserPromptSubmit nudge and the `convene session-start` boot
+ * banner. Kept separate from the pure `binding.ts` comparator because it touches
+ * the filesystem (the committed hook settings) and the running CLI version; both
+ * callers must NEVER hit the network on the boot/hot path, so this reads only local
+ * state and fails open to null.
+ *
+ * The host axis is intentionally absent: an authoritative pin makes the resolved
+ * host == the pin, so host divergence is a `convene doctor` concern (where /me adds
+ * server ground truth), not a hot-path one. What CAN drift locally is the CLI
+ * (older than the CLI that bound the repo — the stale-CLI problem) and the
+ * committed hook wiring (no longer matching the stamped fingerprint).
+ */
+const manifest_1 = require("./catalog/manifest");
+const hook_1 = require("./hook");
+const version_1 = require("./version");
+function localBindingDrift(top, proj) {
+    try {
+        const binding = proj?.binding;
+        if (!binding)
+            return null;
+        if ((0, manifest_1.semverLt)((0, version_1.cliVersion)(), binding.cliVersion)) {
+            return `convene: CLI v${(0, version_1.cliVersion)()} is older than this repo's binding (v${binding.cliVersion}) — \`npm i -g convene-cli@latest\``;
+        }
+        const committed = (0, hook_1.conveneHookFingerprint)((0, hook_1.parseSettings)((0, hook_1.readSettingsRaw)((0, hook_1.projectSettingsPath)(top))));
+        if (committed !== binding.hookFingerprint) {
+            return 'convene: repo hook wiring changed since it was bound — run `convene update --refresh`';
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/binding.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeHost = normalizeHost;
+exports.assessBinding = assessBinding;
+/**
+ * Pure binding ⇄ live-state comparison — the local-only diff that powers the
+ * host-pin / freshness surfacing in `convene doctor`, `convene fetch`, and
+ * `convene session-start`.
+ *
+ * A repo's `.convene/project.json` `binding` stamp (schema 3) records what the
+ * repo was last RECONCILED against: the canonical bus host, the CLI version that
+ * stamped it, the catalog version, and a fingerprint of the COMMITTED hook wiring.
+ * This module compares that stamp against the live runtime truth (the resolved
+ * host, the running CLI, the server-echoed canonical host, the on-disk committed
+ * hook fingerprint) and classifies each axis.
+ *
+ * Modeled on `compareToCatalog` (catalog/manifest.ts): dependency-free and
+ * side-effect-free (no fs, no network, never throws) so it unit-tests offline and
+ * is safe to call on the fetch hot path. The ONLY non-stdlib dependency is the
+ * existing `semverLt` — the binding's CLI-version axis is the one semver-shaped
+ * dimension; the host axis is plain canonicalized string equality.
+ */
+const manifest_1 = require("./catalog/manifest");
+/**
+ * Canonicalize a host/base-URL for equality so the pin and the resolved/ server-
+ * echoed host compare equal across cosmetic differences: trim, lowercase, strip a
+ * trailing-slash-only path, and drop an explicit DEFAULT port (:443 for https, :80
+ * for http) — `https://x` and `https://x:443/` address the same endpoint. Scheme is
+ * preserved (http vs https is a REAL difference — the in-process test server). Pure
+ * + never throws: a value the URL parser rejects falls back to trim/lowercase/strip.
+ */
+function normalizeHost(s) {
+    const trimmed = s.trim();
+    try {
+        const u = new URL(trimmed);
+        const scheme = u.protocol.toLowerCase(); // e.g. 'https:'
+        const defaultPort = scheme === 'https:' ? '443' : scheme === 'http:' ? '80' : '';
+        const port = u.port && u.port !== defaultPort ? `:${u.port}` : '';
+        const tail = u.pathname === '/' ? '' : u.pathname.replace(/\/+$/, '');
+        return `${scheme}//${u.hostname}${port}${tail}`.toLowerCase();
+    }
+    catch {
+        return trimmed.toLowerCase().replace(/\/+$/, '');
+    }
+}
+/**
+ * Compare a committed binding stamp against live runtime state. Pure; never throws.
+ *
+ * Host axis (HARD): a mismatch iff the EFFECTIVE host differs from the pin, OR the
+ *   server actually reached (via /me) self-identifies as a different canonical host
+ *   than the pin. An absent server host is fail-open (cannot contradict ⇒ not a
+ *   mismatch) — never brick a new CLI against an old server that omits the field.
+ * CLI axis (SOFT): directional via semverLt — `behind` when the running CLI is
+ *   older than the stamping CLI (update your CLI), `ahead` when newer (consider
+ *   re-stamping). bumpClass is deliberately NOT used: it collapses "ahead" to
+ *   "none" and so cannot express the stale-CLI direction this feature targets.
+ * Hook axis (SOFT): committed fingerprint vs the stamped one; `unknown` when the
+ *   committed fingerprint is unreadable.
+ */
+function assessBinding(stamp, live) {
+    const stampHost = normalizeHost(stamp.host);
+    const resolvedHost = normalizeHost(live.host);
+    const serverHost = live.serverHost ? normalizeHost(live.serverHost) : null;
+    let hostStatus;
+    if (resolvedHost !== stampHost)
+        hostStatus = 'mismatch';
+    else if (serverHost !== null && serverHost !== stampHost)
+        hostStatus = 'mismatch';
+    else
+        hostStatus = 'ok';
+    let cliStatus = 'ok';
+    if ((0, manifest_1.semverLt)(live.cliVersion, stamp.cliVersion))
+        cliStatus = 'behind';
+    else if ((0, manifest_1.semverLt)(stamp.cliVersion, live.cliVersion))
+        cliStatus = 'ahead';
+    const committed = live.committedHookFingerprint ?? null;
+    let hookStatus;
+    if (committed === null)
+        hookStatus = 'unknown';
+    else if (committed === stamp.hookFingerprint)
+        hookStatus = 'ok';
+    else
+        hookStatus = 'drift';
+    return {
+        host: { stamp: stampHost, resolved: resolvedHost, serverHost, status: hostStatus },
+        cli: { stamp: stamp.cliVersion, running: live.cliVersion, status: cliStatus },
+        hook: { stamp: stamp.hookFingerprint, committed, status: hookStatus },
+        hostMismatch: hostStatus === 'mismatch',
+    };
+}

package/dist/cache.js

@@ -9,6 +9,8 @@ exports.writeCache = writeCache;
 exports.ageSeconds = ageSeconds;
 exports.readCatalogVersion = readCatalogVersion;
 exports.writeCatalogVersion = writeCatalogVersion;
+exports.readCliVersionCheck = readCliVersionCheck;
+exports.writeCliVersionCheck = writeCliVersionCheck;
 exports.readSessionInstance = readSessionInstance;
 exports.mintSessionInstance = mintSessionInstance;
 exports.ensureSessionInstance = ensureSessionInstance;
@@ -19,6 +21,10 @@ exports.markCatchupSurfaced = markCatchupSurfaced;
 exports.catchupAlreadySurfaced = catchupAlreadySurfaced;
 exports.markAutoIsolated = markAutoIsolated;
 exports.autoIsolatedAlready = autoIsolatedAlready;
+exports.announceAlreadyPosted = announceAlreadyPosted;
+exports.markAnnounced = markAnnounced;
+exports.readLastBroadcastSha = readLastBroadcastSha;
+exports.writeLastBroadcastSha = writeLastBroadcastSha;
 exports.readWatchHighWater = readWatchHighWater;
 exports.persistHighWater = persistHighWater;
 exports.appendWatchEntry = appendWatchEntry;
@@ -103,6 +109,33 @@ function writeCatalogVersion(version) {
         /* best-effort */
     }
 }
+function cliVersionFile() {
+    return node_path_1.default.join(config_1.CACHE_DIR, 'cli-version.json');
+}
+/** The cached latest-published CLI version if present AND within `ttlSec`, else null. */
+function readCliVersionCheck(ttlSec) {
+    try {
+        const e = JSON.parse(node_fs_1.default.readFileSync(cliVersionFile(), 'utf8'));
+        if (!e || typeof e.version !== 'string' || typeof e.fetchedAt !== 'number')
+            return null;
+        if ((Date.now() - e.fetchedAt) / 1000 >= ttlSec)
+            return null;
+        return e.version || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the latest-published CLI version (best-effort; never throws). */
+function writeCliVersionCheck(version) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(cliVersionFile(), JSON.stringify({ fetchedAt: Date.now(), version }), { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
 // ── 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
@@ -305,6 +338,58 @@ function autoIsolatedAlready(slug, instance) {
  * incumbent forces a relocation.
  */
 exports.LIVE_SESSION_RECENT_SEC = 3 * 60;
+function announcedFile(slug) {
+    return slugFile(scoped(slug), 'announced');
+}
+/** True iff this exact (instance, branch) has already been announced. */
+function announceAlreadyPosted(slug, instance, branch) {
+    try {
+        const e = JSON.parse(node_fs_1.default.readFileSync(announcedFile(slug), 'utf8'));
+        return !!e && e.instance === instance && e.branch === branch;
+    }
+    catch {
+        return false;
+    }
+}
+/** Record that (instance, branch) has been announced. Best-effort; never throws. */
+function markAnnounced(slug, instance, branch) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(announcedFile(slug), JSON.stringify({ instance, branch }), { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+// ── last-broadcast-sha (announce ↔ wrap ↔ push dedup) ─────────────────────────
+// The most recent HEAD sha this session has already told the bus about — written
+// by `convene announce` (the session-start tip), `convene wrap` (a turn-end wrap),
+// and `convene notify-push` (a push). `convene wrap` (a Stop hook, so it fires at
+// every turn-end) reads it to stay quiet: it only posts when HEAD has advanced
+// PAST this sha, so it never re-wraps a tip the bus already heard about (from the
+// announce, a prior wrap, or the pre-push hook) and never spams an idle session.
+function broadcastShaFile(slug) {
+    return slugFile(scoped(slug), 'broadcast-sha');
+}
+/** The last HEAD sha broadcast to the bus for this session, or null. */
+function readLastBroadcastSha(slug) {
+    try {
+        return node_fs_1.default.readFileSync(broadcastShaFile(slug), 'utf8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Record the HEAD sha just broadcast to the bus. Best-effort; never throws. */
+function writeLastBroadcastSha(slug, sha) {
+    try {
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(broadcastShaFile(slug), sha + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* best-effort */
+    }
+}
 function watchFile(slug) {
     return slugFile(slug, 'watch.jsonl');
 }

package/dist/catalog/catalog.generated.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CATALOG_VERSION = exports.CATALOG = void 0;
 exports.CATALOG = {
-    "version": "1.0.0",
+    "version": "1.1.0",
     "tiers": [
         {
             "id": "essentials",
@@ -213,6 +213,31 @@ exports.CATALOG = {
                 "https://editorconfig.org/"
             ]
         },
+        {
+            "id": "announce-session-intent",
+            "version": "1.0.0",
+            "title": "Announce what you are working on at session start and end",
+            "category": "Parallel & Multi-Session Coordination",
+            "tier": "essentials",
+            "what": "At the start of a work session, broadcast what you are taking on; when you wrap (or land/push commits), broadcast what you did — `convene post status \"<one line>\"`. Do not rely on memory or on others reading your diff. Convene also auto-posts a terse backstop at these points (a \"started on <branch>\" line on the first prompt for every tool, a push status via the pre-push hook, and — in Claude Code — a turn-end wrap once commits land), but a hand-written line with real context is the goal; the auto-posts only guarantee a session is never dark.",
+            "why": "The most common multi-session failure is a silent session: an agent (often a non-Claude tool with no SessionStart/Stop hook) works for an hour and no peer knows where it is, so two sessions collide or duplicate work. Inbound context is automatic and cross-tool; outbound was voluntary prose and got skipped — a Codex session edited the marketing site and never touched the bus. Per `hooks-for-must-haves`, the fix is to make the announce automatic (a hook), with the agent line as enrichment. Production-learned at Convene.",
+            "defaultLevel": "advisory",
+            "availableLevels": [
+                "advisory"
+            ],
+            "optInDefault": "on",
+            "productionLearned": true,
+            "artifacts": [
+                {
+                    "kind": "claudeMd",
+                    "body": "Post what you are taking on at the start of a work session and what you did when you wrap — `convene post status \"<one line>\"` — so concurrent sessions across tools see who owns what.\nA terse start/wrap line is auto-posted as a backstop; your own hand-written status is richer and is what peers rely on."
+                }
+            ],
+            "sourceUrls": [
+                "https://code.claude.com/docs/en/hooks",
+                "https://code.claude.com/docs/en/best-practices"
+            ]
+        },
         {
             "id": "worktree-per-session",
             "version": "1.0.0",
@@ -857,4 +882,4 @@ exports.CATALOG = {
         }
     ]
 };
-exports.CATALOG_VERSION = "1.0.0";
+exports.CATALOG_VERSION = "1.1.0";

package/dist/commands/announce.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.announce = announce;
+/**
+ * `convene announce` — the front-of-session auto-announce. Posts ONE [STATUS]
+ * ("started session on <branch>") the first time a session is seen, so concurrent
+ * sessions across every tool know who is working on what BEFORE any push. This is
+ * the cross-tool keystone that closes the dark-session gap: it is spawned
+ * fire-and-forget by `convene fetch` on the first prompt of a session, which runs
+ * for BOTH Claude Code (UserPromptSubmit hook) and Codex (`fetch --codex-hook`).
+ *
+ * FAIL-OPEN, exactly like `convene notify-push` (P0-FAILSAFE): any error / missing
+ * config / non-bus repo exits 0 silently; a 5s watchdog backstops a hang. It NEVER
+ * blocks anything — it is detached from the prompt hot path.
+ *
+ * IDEMPOTENT on two levels: a local (instance, branch) sentinel spares the
+ * redundant post/spawn, and a deterministic server idempotency-key
+ * (`announce:<slug>:<instance>:<branch>`) is the authoritative dedupe so a retry
+ * or a same-instant double-spawn collapses to one message.
+ *
+ * PRIVACY: the body carries ONLY the branch name — never the user's prompt text.
+ * The bus is cross-member, so prompt text must never land on it automatically.
+ */
+const git_1 = require("../git");
+const config_1 = require("../config");
+const cache_1 = require("../cache");
+const api_1 = require("../api");
+const exit_1 = require("../exit");
+function clip(s, max) {
+    return s.length <= max ? s : s.slice(0, max - 1) + '…';
+}
+async function run(opts) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        return; // not a git repo → silent no-op
+    const slug = opts.project || (0, config_1.loadProjectConfig)(top)?.slug || null;
+    if (!slug)
+        return; // repo not on the bus → silent no-op
+    const cfg = (0, config_1.resolveConfig)();
+    // The instance is minted at SessionStart for Claude Code; for Codex (no
+    // SessionStart) ensure one here so the (instance, branch) sentinel is stable.
+    const instance = (0, cache_1.ensureSessionInstance)(slug);
+    const branch = (0, git_1.currentBranch)(top); // null on a detached HEAD
+    const branchKey = branch ?? 'detached';
+    // Already announced this (instance, branch) — nothing to do (skip in dry-run so
+    // it always prints what it WOULD post).
+    if (!opts.dryRun && (0, cache_1.announceAlreadyPosted)(slug, instance, branchKey))
+        return;
+    const body = clip(branch ? `started session on ${branch}` : 'started session (detached HEAD)', 200);
+    if (opts.dryRun) {
+        process.stdout.write(body + '\n');
+        return;
+    }
+    // Credentials are only needed for the real post (dry-run works offline).
+    if (!cfg.apiKey || !cfg.member)
+        return;
+    const session = (0, git_1.sessionId)(cfg.member, top);
+    const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+    const idem = `announce:${slug}:${instance}:${branchKey}`;
+    const res = await api.post(slug, { type: 'status', body }, idem, 4000);
+    if (res.ok) {
+        // Only mark on success so a transient failure retries on the next prompt.
+        (0, cache_1.markAnnounced)(slug, instance, branchKey);
+        // Seed the broadcast cursor with the session-start tip so a turn-end `wrap`
+        // only fires once HEAD has advanced past it (no spurious wrap of the start tip).
+        const head = (0, git_1.revParse)('HEAD', top);
+        if (head)
+            (0, cache_1.writeLastBroadcastSha)(slug, head);
+        if (res.json?.message?.short_id) {
+            process.stdout.write(`convene: posted [STATUS] ${res.json.message.short_id} — ${body}\n`);
+        }
+    }
+}
+async function announce(opts = {}) {
+    // Backstop: force-exit on every path so a keep-alive socket can't linger.
+    const watchdog = setTimeout(() => (0, exit_1.exitClean)(0), 5000);
+    watchdog.unref();
+    const done = () => {
+        clearTimeout(watchdog);
+        (0, exit_1.exitClean)(0);
+    };
+    try {
+        await run(opts);
+    }
+    catch {
+        /* fail-open: a coordination post must never break a prompt or a boot */
+    }
+    done();
+}

package/dist/commands/auth.js

@@ -7,6 +7,7 @@ exports.login = login;
 exports.whoami = whoami;
 exports.assessLaneIdentity = assessLaneIdentity;
 exports.assessSettingsIntegrity = assessSettingsIntegrity;
+exports.assessFreshness = assessFreshness;
 exports.doctor = doctor;
 /** login / whoami / doctor. */
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -17,6 +18,8 @@ const api_1 = require("../api");
 const config_1 = require("../config");
 const catalog_1 = require("../catalog");
 const manifest_1 = require("../catalog/manifest");
+const binding_1 = require("../binding");
+const version_1 = require("../version");
 const git_1 = require("../git");
 const hook_1 = require("../hook");
 const cache_1 = require("../cache");
@@ -83,13 +86,14 @@ async function login(opts) {
     process.stdout.write(`Config saved to ${config_1.CONFIG_FILE} (0600).\n`);
 }
 async function whoami() {
-    const cfg = (0, config_1.resolveConfig)();
+    const top = (0, git_1.gitToplevel)();
+    const proj = (0, config_1.loadProjectConfig)(top);
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj); // report the host commands actually use (the pin, if any)
     if (!cfg.apiKey) {
         process.stdout.write('Not logged in. Run `convene login`.\n');
         return;
     }
-    const top = (0, git_1.gitToplevel)();
-    const onBus = !!(0, config_1.loadProjectConfig)(top)?.slug;
+    const onBus = !!proj?.slug;
     const session = cfg.member && top ? (0, git_1.sessionId)(cfg.member, top) : cfg.member ? `${cfg.member}/cli` : '(unknown)';
     let serverMember = cfg.member;
     const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool);
@@ -100,7 +104,7 @@ async function whoami() {
     process.stdout.write(`base:     ${cfg.baseUrl}\n`);
     process.stdout.write(`tool:     ${cfg.tool}\n`);
     process.stdout.write(`session:  ${session}\n`);
-    process.stdout.write(`this repo on the bus: ${onBus ? `yes (${(0, config_1.loadProjectConfig)(top).slug})` : 'no'}\n`);
+    process.stdout.write(`this repo on the bus: ${onBus ? `yes (${proj.slug})` : 'no'}\n`);
     process.stdout.write(`server:   ${me.ok ? 'reachable' : 'UNREACHABLE'}\n`);
     // The API key is never printed.
 }
@@ -255,9 +259,122 @@ function assessSettingsIntegrity(top, globalSettingsPath = hook_1.SETTINGS_PATH)
     const tail = notes.length ? ` (${notes.join('; ')})` : '';
     return { name, ok: true, detail: `settings JSON valid + marker blocks intact; Convene edits are additive${tail}` };
 }
+/** Cache TTL for the latest-published CLI version probe — long (24h), advisory. */
+const CLI_VERSION_TTL_SEC = 24 * 60 * 60;
+/**
+ * The latest published `convene-cli` version, 24h-cached and FAIL-SOFT: a cache hit
+ * returns instantly; a miss runs a bounded `npm view` and caches the result; any
+ * failure (offline / no npm / timeout) returns null so the cli-version arm is simply
+ * omitted — doctor never blocks on, or fails because of, this network probe.
+ */
+function latestCliVersion() {
+    const cached = (0, cache_1.readCliVersionCheck)(CLI_VERSION_TTL_SEC);
+    if (cached)
+        return cached;
+    try {
+        const r = (0, node_child_process_1.spawnSync)('npm', ['view', 'convene-cli', 'version'], { timeout: 4000, encoding: 'utf8' });
+        if (r.error || typeof r.status !== 'number' || r.status !== 0)
+            return null;
+        const v = (r.stdout || '').trim();
+        if (!/^\d+\.\d+\.\d+/.test(v))
+            return null;
+        (0, cache_1.writeCliVersionCheck)(v);
+        return v;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Pure freshness/host-pin assessment for `convene doctor` — mirrors
+ * assessLaneIdentity/assessSettingsIntegrity (takes inputs, returns Check[], no
+ * network/fs inside, unit-testable). Exactly ONE check is HARD:
+ *   - host-pin (HARD, ok:false ⇒ doctor exits 1): the repo's pinned host diverges
+ *     from the host the CLI reaches OR from the server's self-identified canonical
+ *     host. An UNSTAMPED on-bus repo yields a single SOFT nudge instead.
+ * Every other arm is SOFT (ok:true, advisory — never flips the exit code):
+ *   - hook-fp: committed hook wiring drifted from the stamp (names the committed file);
+ *   - cli-stamp: running CLI older than the CLI that bound the repo;
+ *   - cli-version: running CLI older than the latest published release.
+ * (Catalog freshness stays in reportBestPractices.) Off-bus → no checks.
+ */
+function assessFreshness(inp) {
+    const out = [];
+    if (!inp.onBus)
+        return out;
+    if (!inp.binding) {
+        out.push({
+            name: 'host-pin',
+            ok: true,
+            detail: 'repo not host-pinned — run `convene update --refresh` to bind it to this bus (records host + CLI + hook state)',
+        });
+    }
+    else {
+        const a = (0, binding_1.assessBinding)(inp.binding, {
+            host: inp.resolvedHost,
+            cliVersion: inp.runningCliVersion,
+            serverHost: inp.serverHost,
+            committedHookFingerprint: inp.committedHookFingerprint,
+        });
+        out.push({
+            name: 'host-pin',
+            ok: !a.hostMismatch,
+            detail: a.hostMismatch
+                ? `HOST MISMATCH — repo pinned to ${a.host.stamp} but ` +
+                    (a.host.resolved !== a.host.stamp
+                        ? `resolving to ${a.host.resolved}`
+                        : `the server self-identifies as ${a.host.serverHost}`) +
+                    ' (re-point deliberately with `convene update --host <url>`, or fix your config)'
+                : `pinned to ${a.host.stamp}${a.host.serverHost ? ' — server-confirmed' : ' (server host unverified)'}`,
+        });
+        // Ambient-vs-pin divergence: a stale CONVENE_BASE_URL / global baseUrl that
+        // disagrees with the pin. Pinned commands honor the pin (so this is SOFT, not a
+        // mismatch), but the user should know their environment points elsewhere — it is
+        // exactly the dev/prod confusion this feature exists to surface, and the
+        // authoritative resolvedHost would otherwise hide it.
+        if ((0, binding_1.normalizeHost)(inp.ambientHost) !== (0, binding_1.normalizeHost)(inp.binding.host)) {
+            out.push({
+                name: 'host-env',
+                ok: true,
+                detail: `your environment resolves to ${(0, binding_1.normalizeHost)(inp.ambientHost)} but this repo is pinned to ${(0, binding_1.normalizeHost)(inp.binding.host)} — the pin wins for convene commands; unset CONVENE_BASE_URL / fix ~/.convene/config.json to avoid confusion`,
+            });
+        }
+        if (a.hook.status === 'drift') {
+            out.push({
+                name: 'hook-fp',
+                ok: true,
+                detail: 'committed .claude/settings.json hook wiring changed since the repo was bound — `convene update --refresh` to re-stamp',
+            });
+        }
+        if (a.cli.status === 'behind') {
+            out.push({
+                name: 'cli-stamp',
+                ok: true,
+                detail: `CLI v${a.cli.running} is older than the CLI that bound this repo (v${a.cli.stamp}) — \`npm i -g convene-cli@latest\``,
+            });
+        }
+    }
+    if (inp.latestCliVersion && (0, manifest_1.semverLt)(inp.runningCliVersion, inp.latestCliVersion)) {
+        out.push({
+            name: 'cli-version',
+            ok: true,
+            detail: `convene-cli v${inp.latestCliVersion} available (running v${inp.runningCliVersion}) — \`npm i -g convene-cli@latest\``,
+        });
+    }
+    return out;
+}
 async function doctor(opts) {
     const checks = [];
-    const cfg = (0, config_1.resolveConfig)();
+    // Resolve the git toplevel + committed project config UP FRONT so config
+    // resolution can honor a committed host pin (resolveConfigForRepo) — the same
+    // host the rest of doctor talks to and reports. `top`/`proj` are reused by the
+    // git/project/freshness checks below instead of being re-read.
+    const top = (0, git_1.gitToplevel)();
+    const proj = (0, config_1.loadProjectConfig)(top);
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj);
+    // /me response, captured by the auth check and REUSED by the freshness host arm
+    // (the server-echoed canonical_host) — never a second /me round-trip.
+    let meJson = null;
     // 1. binary
     checks.push({ name: 'binary', ok: true, detail: `convene running from ${process.argv[1] || process.execPath}` });
     // 2. config + perms
@@ -290,6 +407,7 @@ async function doctor(opts) {
     if (cfg.apiKey) {
         const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey);
         const me = await api.me(6000);
+        meJson = me.json;
         checks.push({
             name: 'auth',
             ok: me.ok,
@@ -300,10 +418,8 @@ async function doctor(opts) {
         checks.push({ name: 'auth', ok: false, detail: 'skipped (no key)' });
     }
     // 4. git toplevel
-    const top = (0, git_1.gitToplevel)();
     checks.push({ name: 'git', ok: !!top, detail: top ? `worktree: ${(0, git_1.worktreeBasename)(top)}` : 'not in a git repo' });
     // 5. project on bus
-    const proj = (0, config_1.loadProjectConfig)(top);
     checks.push({
         name: 'project',
         ok: !!proj?.slug,
@@ -438,6 +554,28 @@ async function doctor(opts) {
             checks.push(assessLaneIdentity(rows, cfg.member ?? null, instance != null));
         }
     }
+    // 9. host-pin / freshness. The host arm is HARD (a pin/server divergence flips the
+    // exit code via the every() gate below — exactly the dev/prod-confusion guard);
+    // cli-version / hook-fp / cli-stamp are SOFT advisories. Inputs are gathered here
+    // (reusing the /me already fetched + a 24h-cached `npm view`); the verdict is the
+    // pure assessFreshness. doctor NEVER re-stamps/re-points — that is the deliberate
+    // `convene update --refresh` / `--host`; --fix touches only config perms + the
+    // GLOBAL hook + watch (never the binding).
+    if (top) {
+        const committedHookFingerprint = (0, hook_1.conveneHookFingerprint)((0, hook_1.parseSettings)((0, hook_1.readSettingsRaw)((0, hook_1.projectSettingsPath)(top))));
+        for (const c of assessFreshness({
+            binding: proj?.binding ?? null,
+            onBus: !!proj?.slug,
+            resolvedHost: cfg.baseUrl,
+            ambientHost: (0, config_1.resolveConfig)().baseUrl, // binding-BLIND, to catch a stale env/global host
+            runningCliVersion: (0, version_1.cliVersion)(),
+            serverHost: meJson?.canonical_host ?? null,
+            committedHookFingerprint,
+            latestCliVersion: cfg.apiKey ? latestCliVersion() : null,
+        })) {
+            checks.push(c);
+        }
+    }
     for (const c of checks) {
         process.stdout.write(`${c.ok ? '✓' : '✗'} ${c.name.padEnd(8)} ${c.detail}\n`);
     }

package/dist/commands/catchup.js

@@ -65,7 +65,7 @@ async function runCatchup(opts) {
     if (!proj?.slug)
         return; // not on the bus → no-op
     const slug = proj.slug;
-    const cfg = (0, config_1.resolveConfig)();
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj);
     if (!cfg.apiKey || !cfg.member) {
         if (failOpen)
             return;