convene-cli 1.12.0 → 1.13.1

package/dist/api.js

@@ -207,9 +207,11 @@ class ConveneApi {
     }
     /**
      * GET /catalog — the canonical best-practices catalog (PUBLIC, no tenant data).
-     * The CLI prefers this live read but is fully fail-soft: on any non-ok / network
-     * error the caller falls back to the bundled offline mirror. Bounded by a short
-     * timeout — never the 10s default.
+     * The server returns a release ENVELOPE `{ version, contentHash, catalog }`; the
+     * actual Catalog lives under `.catalog` (loadCatalog unwraps it). The CLI prefers
+     * this live read but is fully fail-soft: on any non-ok / network error the caller
+     * falls back to the bundled offline mirror. Bounded by a short timeout — never
+     * the 10s default.
      */
     getCatalog(timeoutMs) {
         return this.request('GET', '/catalog', { timeoutMs });

package/dist/cache.js

@@ -23,6 +23,8 @@ exports.markAutoIsolated = markAutoIsolated;
 exports.autoIsolatedAlready = autoIsolatedAlready;
 exports.announceAlreadyPosted = announceAlreadyPosted;
 exports.markAnnounced = markAnnounced;
+exports.frictionAlreadyPosted = frictionAlreadyPosted;
+exports.markFrictionPosted = markFrictionPosted;
 exports.readLastBroadcastSha = readLastBroadcastSha;
 exports.writeLastBroadcastSha = writeLastBroadcastSha;
 exports.readWatchCursor = readWatchCursor;
@@ -358,6 +360,50 @@ function markAnnounced(slug, instance, branch) {
         /* best-effort */
     }
 }
+// ── in-session friction-capture sentinel ──────────────────────────────────────
+// `convene friction` files ONE feature_feedback row per DISTINCT in-session
+// confusion signal (e.g. an unmatched `convene explain` question). The server
+// idempotency-key is the authoritative dedupe; this local sentinel just spares the
+// redundant post/spawn when the SAME signal recurs within a session. Keyed on the
+// per-boot instance (a fresh boot re-captures) + the signal hash; bounded so a
+// chatty session can't grow the file without limit.
+const FRICTION_MAX_KEYS = 50;
+function frictionFile(slug) {
+    return slugFile(scoped(slug), 'friction');
+}
+/** True iff this (instance, sigHash) friction signal was already posted this boot. */
+function frictionAlreadyPosted(slug, instance, sigHash) {
+    try {
+        const e = JSON.parse(node_fs_1.default.readFileSync(frictionFile(slug), 'utf8'));
+        return !!e && e.instance === instance && Array.isArray(e.hashes) && e.hashes.includes(sigHash);
+    }
+    catch {
+        return false;
+    }
+}
+/** Record (instance, sigHash) as posted. Resets on a new instance; bounded. Best-effort. */
+function markFrictionPosted(slug, instance, sigHash) {
+    try {
+        let e = { instance, hashes: [] };
+        try {
+            const prev = JSON.parse(node_fs_1.default.readFileSync(frictionFile(slug), 'utf8'));
+            if (prev && prev.instance === instance && Array.isArray(prev.hashes))
+                e = prev;
+        }
+        catch {
+            /* no prior entry / new instance → start fresh */
+        }
+        if (!e.hashes.includes(sigHash))
+            e.hashes.push(sigHash);
+        if (e.hashes.length > FRICTION_MAX_KEYS)
+            e.hashes = e.hashes.slice(-FRICTION_MAX_KEYS);
+        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
+        node_fs_1.default.writeFileSync(frictionFile(slug), JSON.stringify(e), { 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),

package/dist/catalog/index.js

@@ -6,16 +6,26 @@ const catalog_generated_1 = require("./catalog.generated");
 Object.defineProperty(exports, "CATALOG", { enumerable: true, get: function () { return catalog_generated_1.CATALOG; } });
 Object.defineProperty(exports, "CATALOG_VERSION", { enumerable: true, get: function () { return catalog_generated_1.CATALOG_VERSION; } });
 /**
- * Load the catalog, preferring the live server copy when `api` is given. Any
- * failure (no client, non-ok status, network error, empty body) silently falls
- * back to the bundled mirror — this never throws.
+ * Load the catalog, preferring the live server copy when `api` is given. Unwraps
+ * the server's release envelope ({ version, contentHash, catalog }) and tolerates
+ * a bare Catalog for back-compat. Any failure (no client, non-ok status, network
+ * error, empty/malformed body) silently falls back to the bundled mirror — this
+ * never throws.
  */
 async function loadCatalog(api, timeoutMs = 5_000) {
     if (api) {
         try {
             const res = await api.getCatalog(timeoutMs);
-            if (res.ok && res.json && Array.isArray(res.json.practices) && res.json.version) {
-                return { catalog: res.json, source: 'live' };
+            // The server wraps the catalog in a release envelope
+            // ({ version, contentHash, catalog }); the Catalog (with `practices`) lives
+            // one level down under `.catalog`. Unwrap that, but also tolerate a bare
+            // Catalog for back-compat with a differently-shaped/older server. VALIDATE
+            // the UNWRAPPED object — the envelope's top-level `version` matches a bare
+            // Catalog's, so guarding on the inner `practices` is what tells them apart.
+            const body = res.json;
+            const cat = body && 'catalog' in body ? body.catalog : body;
+            if (res.ok && cat && Array.isArray(cat.practices) && typeof cat.version === 'string') {
+                return { catalog: cat, source: 'live' };
             }
         }
         catch {

package/dist/catalog/manifest.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.semverLt = semverLt;
 exports.bumpClass = bumpClass;
 exports.compareToCatalog = compareToCatalog;
+exports.catalogBehindLine = catalogBehindLine;
+exports.bestPracticesFreshnessLine = bestPracticesFreshnessLine;
 /**
  * Strict SemVer less-than over the dotted numeric core (pre-release/build
  * metadata ignored — the catalog uses plain X.Y.Z). Missing components read as
@@ -69,3 +71,31 @@ function compareToCatalog(manifest, catalog) {
         unknownIds,
     };
 }
+/**
+ * The canonical "your repo trails the catalog" nudge, shared by `convene doctor`
+ * and the `convene fetch` channel nudge so the SAME sentence ALWAYS means the
+ * same thing: `serverVersion` is the SERVER-published catalog version
+ * (authoritative), `repoVersion` is what this repo adopted. Never call this with
+ * a bundled-mirror version — a stale binary's bundled version is not "available"
+ * on the server (see `bestPracticesFreshnessLine`'s offline branch for that).
+ */
+function catalogBehindLine(serverVersion, repoVersion) {
+    return `server catalog v${serverVersion} available (repo adopted v${repoVersion}) — run \`convene update\``;
+}
+/**
+ * The `convene doctor` best-practices freshness line, given a catalog comparison
+ * and WHERE the catalog came from. Server-truthful by construction: it only makes
+ * an "available"/"up to date" claim when the comparison was against the LIVE
+ * server catalog. When the server was unreachable the comparison is against the
+ * bundled mirror baked into this binary — which may trail OR lead the server — so
+ * it refuses to claim either and just states both versions + that the server is
+ * unknown. Pure (no stdout/network) so it unit-tests directly.
+ */
+function bestPracticesFreshnessLine(cmp, source) {
+    if (source === 'live') {
+        return cmp.behind
+            ? catalogBehindLine(cmp.catalogVersion, cmp.repoVersion)
+            : `best practices up to date with server catalog v${cmp.repoVersion}`;
+    }
+    return `bundled catalog v${cmp.catalogVersion} (offline — server version unknown) vs repo adopted v${cmp.repoVersion}`;
+}

package/dist/commands/adopt.js

@@ -0,0 +1,296 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAdoptTargets = parseAdoptTargets;
+exports.runAdopt = runAdopt;
+exports.adopt = adopt;
+/**
+ * `convene adopt <id|id=level …>` — incrementally adopt catalog best practices into a
+ * repo that already has a manifest, WITHOUT replacing the adopted set.
+ *
+ * This is the missing inverse of the gap `convene update` cannot close. `update` only
+ * re-materializes practices ALREADY in the manifest (bumping them to the live catalog),
+ * and `convene init --practice X` REPLACES the whole adopted set with just X. So when
+ * the catalog GROWS a new practice, neither verb can take it — an agent is forced to
+ * hand-roll buildPracticesDoc/regionHash itself. `adopt` merges the named practice(s)
+ * into the existing set, drift-safely:
+ *
+ *   - Existing adopted practices are PRESERVED byte-for-byte (their on-disk section,
+ *     pinned version, hash, and level). adopt never silently bumps or re-renders them,
+ *     and never clobbers a local edit; it re-renders ONLY the ids it is adding or
+ *     deliberately re-leveling. Mechanism: render the full union (so every section
+ *     lands in CATALOG order), then splice each untouched block back verbatim — the
+ *     same preserve/splice rail `convene update --apply` uses. (Rendering only the new
+ *     ids would REORDER the doc, because splicePreservedBlocks APPENDS any id missing
+ *     from the freshly-rendered doc — see catalog/materialize.ts.)
+ *   - manifest.catalogVersion is NOT advanced. adopt does not take the live catalog for
+ *     EXISTING practices (that is `convene update`'s job, gated by its drift/major
+ *     rails), so the "behind" watermark must stay honest — bumping it would make the
+ *     next `convene update` read "up to date" and strand the existing practices at
+ *     stale bodies. The one exception: bootstrapping an absent manifest stamps it to
+ *     the catalog the first practice came from.
+ *   - Live-catalog-first (so it can take a practice newer than the bundled mirror),
+ *     fail-soft to the bundled mirror offline.
+ *   - NEVER git-adds/commits — changes land in the working tree for the human to review
+ *     + commit, exactly like init/update.
+ *
+ * Apply-by-default: naming a practice IS the deliberate act, so there is no --apply gate
+ * (an apply gate would recreate the very "update available → nothing to apply" dead-end
+ * this command exists to kill).
+ */
+const config_1 = require("../config");
+const git_1 = require("../git");
+const api_1 = require("../api");
+const catalog_1 = require("../catalog");
+const report_1 = require("../catalog/report");
+const manifest_1 = require("../catalog/manifest");
+const materialize_1 = require("../catalog/materialize");
+const ctx_1 = require("../ctx");
+const log = (m) => process.stdout.write(m + '\n');
+/**
+ * Parse + VALIDATE the raw `id` / `id=level` tokens against the catalog. PURE and
+ * THROWS on the first invalid token (no fs side-effects) so the command is atomic —
+ * one bad token aborts before anything is written. Mirrors select.ts parseSelectionFlags.
+ *
+ * A BARE id resolves to the practice's CURRENT adopted level if it is already in the
+ * manifest, else its defaultLevel — so `convene adopt <already-adopted-id>` is always a
+ * deliberate no-op, never an accidental re-level back to the default. Later duplicates
+ * win. `source` only flavors the unknown-id message: offline we cannot tell "the id
+ * does not exist" from "the id exists only in a newer catalog we could not fetch".
+ */
+function parseAdoptTargets(targets, catalog, source, existingById) {
+    const byId = new Map(catalog.practices.map((p) => [p.id, p]));
+    const slot = new Map(); // id → index in `out` (later-wins on dup)
+    const out = [];
+    for (const raw of targets) {
+        const eq = raw.indexOf('=');
+        const id = (eq >= 0 ? raw.slice(0, eq) : raw).trim();
+        const lvlTok = eq >= 0 ? raw.slice(eq + 1).trim() : null;
+        const p = byId.get(id);
+        if (!p) {
+            const near = catalog.practices
+                .filter((x) => x.id.includes(id) || id.includes(x.id))
+                .slice(0, 5)
+                .map((x) => x.id);
+            const hint = near.length ? ` Did you mean: ${near.join(', ')}` : '';
+            if (source === 'bundled') {
+                throw new Error(`unknown practice "${id}" in the bundled catalog v${catalog.version} (offline). ` +
+                    'It may exist in a newer live catalog — reconnect and retry, or refresh the bundled ' +
+                    'mirror (`npm i -g convene-cli@latest`).' +
+                    hint);
+            }
+            throw new Error(`unknown practice "${id}" — not in the catalog (run \`convene practices\` to see ids).${hint}`);
+        }
+        let level;
+        if (lvlTok === null) {
+            level = existingById.get(id)?.level ?? p.defaultLevel;
+        }
+        else {
+            if (!p.availableLevels.includes(lvlTok)) {
+                throw new Error(`invalid level "${lvlTok}" for practice "${id}" — choose one of: ${p.availableLevels.join(', ')}`);
+            }
+            level = lvlTok;
+        }
+        const entry = { id, level, bare: lvlTok === null };
+        if (slot.has(id))
+            out[slot.get(id)] = entry;
+        else {
+            slot.set(id, out.length);
+            out.push(entry);
+        }
+    }
+    return out;
+}
+/**
+ * Core of `convene adopt` with (top, manifest, catalog, parsed) already resolved — the
+ * seam tests drive this directly with a synthetic catalog (no fs/network resolution).
+ * Classifies each target, preserves every untouched section, re-materializes the union,
+ * splices the untouched blocks back, and rewrites the manifest. Never throws on user
+ * error (parseAdoptTargets already validated); never git-commits.
+ */
+async function runAdopt(top, manifest, catalog, source, bootstrapped, parsed, opts) {
+    const byId = new Map(catalog.practices.map((p) => [p.id, p]));
+    const existingById = new Map(manifest.practices.map((e) => [e.id, e]));
+    const drifted = bootstrapped ? new Set() : new Set((0, materialize_1.detectDrift)(top, manifest));
+    // Classify: NEW (not yet adopted) / RELEVEL (adopted, different level) / NOOP
+    // (adopted, same level) / drift-refusal (re-level of a locally-edited section without
+    // --force — a level change forces a re-render whose hash must change, so the splice
+    // cannot preserve the local edit; mirror update's skipForDrift).
+    const newIds = [];
+    const relevel = [];
+    const noops = [];
+    const driftRefusals = [];
+    for (const t of parsed) {
+        const prev = existingById.get(t.id);
+        if (!prev)
+            newIds.push(t);
+        else if (prev.level === t.level)
+            noops.push(t);
+        else if (drifted.has(t.id) && !opts.force)
+            driftRefusals.push(t);
+        else
+            relevel.push(t);
+    }
+    const touched = [...newIds, ...relevel];
+    const touchedIds = new Set(touched.map((t) => t.id));
+    // Nothing changes: report the no-ops / refusals and return WITHOUT writing the
+    // manifest/doc or reporting — a same-level adopt must be byte-identical to a no-op.
+    if (touched.length === 0) {
+        for (const t of noops)
+            log(`· ${t.id} already adopted at ${t.level} — unchanged`);
+        for (const t of driftRefusals) {
+            log(`refusing to re-level ${t.id}: its section was edited locally (drift) — re-run with --force to overwrite your edits, or revert the edit first.`);
+        }
+        if (driftRefusals.length === 0) {
+            log('Nothing to adopt — all named practices already adopted at the requested level.');
+        }
+        return;
+    }
+    // PRESERVE every untouched adopted section byte-for-byte (incl. drifted + removed-
+    // from-catalog ids): snapshot the on-disk blocks BEFORE re-materializing.
+    const allBlocks = (0, materialize_1.extractPracticeBlocks)(top);
+    const preserve = new Map();
+    for (const e of manifest.practices) {
+        if (touchedIds.has(e.id))
+            continue;
+        const b = allBlocks.get(e.id);
+        if (b)
+            preserve.set(e.id, b);
+    }
+    // Render the FULL UNION in catalog order: every adopted id STILL IN THE CATALOG at its
+    // CURRENT manifest level (a placeholder slot so the splice below is an in-place
+    // replace, never an append that would reorder the doc), plus each touched id at its
+    // TARGET level. An id removed from the catalog can't be rendered — it rides through
+    // `preserve` only.
+    const levelMap = new Map();
+    for (const e of manifest.practices)
+        if (byId.has(e.id) && !touchedIds.has(e.id))
+            levelMap.set(e.id, e.level);
+    for (const t of touched)
+        if (byId.has(t.id))
+            levelMap.set(t.id, t.level);
+    const renderSelections = [...levelMap].map(([id, level]) => ({ id, level }));
+    // Respect --no-hook exactly as init does: settingsJson(deny)/gitignore still apply
+    // (they are not Claude-Code hooks); only the settingsHook guards are skipped.
+    const wireHooks = !(opts.noHook === true || opts.hook === false);
+    const reMaterialized = (0, materialize_1.materializePractices)(top, '', renderSelections, catalog, { wireHooks });
+    // Splice the untouched blocks back over their just-rendered placeholders — restoring
+    // each one's original version marker, body (incl. local edits), and therefore its
+    // original regionHash. After this only the touched sections reflect the live catalog.
+    //
+    // Two narrow, accepted edges (shared with `update --apply`'s identical rail):
+    //   (a) An untouched id whose section is MISSING from the doc on disk (a truncated /
+    //       hand-mangled doc) is absent from `preserve`, so its just-rendered live body
+    //       leaks through while its manifest entry stays pinned (a one-time false-drift
+    //       on an already-out-of-sync doc). `update --apply` is the repair path.
+    //   (b) An untouched id REMOVED from the live catalog can't be re-rendered (it isn't
+    //       in renderSelections), so the splice APPENDS its preserved block at the doc
+    //       tail rather than its catalog-order slot — manifest order is still correct;
+    //       only the doc section's position drifts. (We still keep it — better than
+    //       `update --apply`, which drops a removed practice's section entirely.)
+    (0, materialize_1.splicePreservedBlocks)(top, preserve);
+    // Assemble the next manifest: verbatim OLD entry for every untouched id (preserving
+    // version+hash+level so it is never re-flagged as drift), the FRESH entry for each
+    // re-leveled id, and the fresh entry APPENDED for each genuinely-new id (existing
+    // slots keep their order — minimal project.json diff, matching update's no-reorder
+    // convention; the ordering is locked by a test).
+    const freshById = new Map(reMaterialized.map((e) => [e.id, e]));
+    const kept = manifest.practices.map((old) => touchedIds.has(old.id) ? freshById.get(old.id) : old);
+    const existingIds = new Set(manifest.practices.map((e) => e.id));
+    const added = catalog.practices
+        .filter((p) => touchedIds.has(p.id) && !existingIds.has(p.id))
+        .map((p) => freshById.get(p.id));
+    const nextManifest = {
+        catalogVersion: bootstrapped ? catalog.version : manifest.catalogVersion,
+        channel: manifest.channel ?? 'minor',
+        practices: [...kept, ...added],
+    };
+    (0, config_1.writeManifest)(top, nextManifest);
+    // Report adoption to the dashboard — best-effort, fail-OPEN, fire-and-forget (never
+    // fails/slows adopt; skipped silently when --offline or no api key). Same as init/update.
+    const slug = opts.project || (0, config_1.loadProjectConfig)(top)?.slug;
+    if (slug) {
+        const { ok } = await (0, report_1.reportManifest)(top, slug, nextManifest, { offline: opts.offline });
+        if (ok)
+            log('· reported adoption to the dashboard');
+    }
+    // Success summary — the agent-legible centerpiece: a line per target, then the
+    // verbatim never-commit rail so a reading agent knows the exact next step.
+    const offlineNote = source === 'bundled' ? ' — bundled/offline' : '';
+    const reLabel = relevel.length ? ` + re-leveled ${relevel.length}` : '';
+    log(`✓ adopted ${newIds.length}${reLabel} practice(s) into .convene/best-practices.md (catalog v${catalog.version}${offlineNote}):`);
+    for (const t of newIds) {
+        const p = byId.get(t.id);
+        log(`    + ${t.id}  v${p.version}  [${p.tier} · ${t.level}]`);
+    }
+    for (const t of relevel) {
+        const prev = existingById.get(t.id);
+        const fresh = freshById.get(t.id);
+        // Re-leveling re-renders from the LIVE catalog, so it also re-pins the practice to
+        // the live version (and takes the live body) — which can cross a MAJOR boundary.
+        // Disclose that jump rather than presenting a re-level as level-only: an operator
+        // re-leveling a behind practice silently gets the new content otherwise.
+        const verNote = prev.version !== fresh.version
+            ? `  (v${prev.version} → v${fresh.version}${(0, manifest_1.bumpClass)(prev.version, fresh.version) === 'major' ? ', MAJOR catalog bump' : ''})`
+            : '';
+        log(`    ↑ ${t.id}  ${prev.level} → ${t.level}${verNote}`);
+        // A demotion can ORPHAN enforcement artifacts — adopt only ever ADDS (mergeDenyArray
+        // / ensureHook never subtract). Note it whenever the OLD level wired something the
+        // NEW level won't: a hook level → non-hook orphans the settingsHook/gitignore; a
+        // hook-hard → anything-else orphans permissions.deny (wired only at hook-hard, and
+        // only when the practice ships that artifact — else there is nothing to orphan).
+        const hookOrphaned = (0, materialize_1.isHookLevel)(prev.level) && !(0, materialize_1.isHookLevel)(t.level);
+        const denyOrphaned = prev.level === 'hook-hard' &&
+            t.level !== 'hook-hard' &&
+            (byId.get(t.id)?.artifacts.some((a) => a.kind === 'settingsJson') ?? false);
+        if (hookOrphaned || denyOrphaned) {
+            log(`      note: demoting ${t.id} leaves its previously-wired hook/deny entries in .claude/settings.json; remove them by hand if you want enforcement fully relaxed.`);
+        }
+    }
+    for (const t of noops)
+        log(`    · ${t.id} already adopted at ${t.level} — unchanged`);
+    for (const t of driftRefusals) {
+        log(`    refusing to re-level ${t.id}: edited locally (drift) — re-run with --force to overwrite, or revert the edit.`);
+    }
+    log('');
+    log('Changes are in your working tree only. Review with `git diff` and commit yourself — Convene never commits.');
+    log('Learn the why behind any of these: `convene practices <id>`.');
+}
+/**
+ * `convene adopt` entry point: resolve env + catalog (live-first, bundled fallback) +
+ * the repo manifest (bootstrapping one if the repo adopted nothing yet), validate the
+ * targets up front (atomic), then hand off to runAdopt. Fail-soft throughout.
+ */
+async function adopt(targets, opts = {}) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        (0, ctx_1.die)('not a git repository — run `convene adopt` inside a repo');
+    if (!targets || targets.length === 0) {
+        (0, ctx_1.die)('usage: convene adopt <id|id=level> [more...]  (see `convene practices` for ids)');
+    }
+    // Live catalog (fail-soft → bundled). Build an authed client only with a key;
+    // loadCatalog never blocks. Honor a committed host pin (pin-authoritative) so the
+    // catalog fetch + adoption report hit the bound bus — same as `convene update`.
+    const cfg = (0, config_1.resolveConfigForRepo)(top);
+    const api = cfg.apiKey && cfg.member ? new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, (0, git_1.sessionId)(cfg.member, top), cfg.tool) : null;
+    const { catalog, source } = await (0, catalog_1.loadCatalog)(api);
+    // Load or BOOTSTRAP the manifest: adopt must work on a repo onboarded with
+    // --no-practices (or pre-catalog) — there is simply nothing to merge into yet.
+    const existing = (0, config_1.loadManifest)(top);
+    const bootstrapped = existing === null;
+    const manifest = existing ?? {
+        catalogVersion: catalog.version,
+        channel: 'minor',
+        practices: [],
+    };
+    if (bootstrapped)
+        log('· no practices adopted yet — creating the best-practices manifest.');
+    const existingById = new Map(manifest.practices.map((e) => [e.id, e]));
+    let parsed;
+    try {
+        parsed = parseAdoptTargets(targets, catalog, source, existingById);
+    }
+    catch (e) {
+        (0, ctx_1.die)(e.message); // die() exits the process (never returns)
+    }
+    await runAdopt(top, manifest, catalog, source, bootstrapped, parsed, opts);
+}

package/dist/commands/auth.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.assessWatchHealth = assessWatchHealth;
 exports.login = login;
 exports.whoami = whoami;
 exports.assessLaneIdentity = assessLaneIdentity;
@@ -54,6 +55,41 @@ function relaunchWatch(slug) {
         return false;
     }
 }
+/**
+ * PURE health verdict for the `doctor` "watch" line (unit-tested, no I/O). The
+ * watcher is a BEST-EFFORT liveness/notify daemon: it self-terminates once its
+ * owning session goes idle (~30m — see watch.ts) and is only relaunched at the
+ * next SessionStart, so a stale/absent heartbeat is the EXPECTED state for any
+ * quiet or long-lived session, NOT an error. Directed halts still surface via the
+ * pull path (fetch / session-open) and are still BLOCKED by the guard (live
+ * lane-state) whether or not this daemon is up. The check is therefore
+ * informational (never fails doctor); the verdict only drives the human-readable
+ * detail and whether `--fix` offers a relaunch.
+ *   - alive  — heartbeat fresh (age ≤ staleSec).
+ *   - wedged — stale heartbeat but the pidfile owner is STILL ALIVE: a live process
+ *              that has stopped stamping (the one genuinely odd state).
+ *   - idle   — stale/absent heartbeat and no live watcher: simply not running.
+ */
+function assessWatchHealth(args) {
+    const { ageSec, staleSec, hasLiveWatcher } = args;
+    if (ageSec != null && ageSec <= staleSec)
+        return 'alive';
+    if (hasLiveWatcher)
+        return 'wedged';
+    return 'idle';
+}
+/** The `doctor` "watch" detail line for a health state (age in seconds, or null). */
+function watchDetail(state, age) {
+    switch (state) {
+        case 'alive':
+            return `halt watcher alive (heartbeat ${age}s ago)`;
+        case 'wedged':
+            return `halt watcher process up but not heartbeating (${age}s) — restart the session if mid-turn halt pings stop`;
+        case 'idle':
+        default:
+            return 'halt watcher not running — relaunches at next session start (directed halts still surface via the pull path + the guard; `convene doctor --fix` starts one now)';
+    }
+}
 function readStdin() {
     try {
         return node_fs_1.default.readFileSync(0, 'utf8').trim();
@@ -450,33 +486,54 @@ async function doctor(opts) {
     // 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.
+    // 6c. coordination-hook drift — the committed project .claude/settings.json should
+    //     carry the canonical COORD_HOOKS set. The writer (`convene init`) and this
+    //     check share ONE source of truth (../hook), so a hook added to COORD_HOOKS
+    //     (e.g. PR #55's Stop `convene wrap`) can't silently go unwired in a repo
+    //     onboarded earlier. Verbs THIS binary lacks are skipped. ADVISORY (ok:true):
+    //     drift is a nudge, not a hard failure — it must not fail doctor fleet-wide.
+    if (proj?.slug && top) {
+        const projSettings = (0, hook_1.parseSettings)((0, hook_1.readSettingsRaw)((0, hook_1.projectSettingsPath)(top)));
+        if (projSettings != null) {
+            const missing = (0, hook_1.missingCoordHooks)(projSettings);
+            checks.push({
+                name: 'coord-hooks',
+                ok: true,
+                detail: missing.length === 0
+                    ? 'committed coordination hooks match the canonical set'
+                    : `drifted — committed settings missing ${missing
+                        .map((h) => `${h.event} \`${h.command}\``)
+                        .join(', ')}; run \`convene init --refresh-docs\` to wire`,
+            });
+        }
+    }
+    // 7. watch heartbeat — the mid-task halt watcher is a BEST-EFFORT liveness/notify
+    // daemon that self-exits when its session goes idle and only relaunches at the
+    // next SessionStart, so a stale/absent heartbeat is EXPECTED for a quiet or
+    // long-lived session — NOT a failure. Directed halts surface via the pull path
+    // and are blocked by the guard regardless of this daemon. Informational only
+    // (never fails doctor); --fix offers a best-effort relaunch. See assessWatchHealth.
     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(proj.slug)) {
+        const slug = proj.slug;
+        const watcherAlive = () => {
+            const p = (0, cache_1.readWatchPid)(slug);
+            return !!(p && (0, cache_1.isPidAlive)(p.pid));
+        };
+        let age = (0, cache_1.watchHeartbeatAgeSec)(slug);
+        let state = assessWatchHealth({ ageSec: age, staleSec: WATCH_STALE_SEC, hasLiveWatcher: watcherAlive() });
+        if (state !== 'alive' && opts.fix) {
+            if (relaunchWatch(slug)) {
                 // 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);
+                    age = (0, cache_1.watchHeartbeatAgeSec)(slug);
                     if (age != null && age <= WATCH_STALE_SEC)
                         break;
                 }
-                watchOk = age != null && age <= WATCH_STALE_SEC;
+                state = assessWatchHealth({ ageSec: age, staleSec: WATCH_STALE_SEC, hasLiveWatcher: watcherAlive() });
             }
         }
-        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)`,
-        });
+        checks.push({ name: 'watch', ok: true, detail: watchDetail(state, age) });
         // 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
@@ -579,22 +636,35 @@ async function doctor(opts) {
     for (const c of checks) {
         process.stdout.write(`${c.ok ? '✓' : '✗'} ${c.name.padEnd(8)} ${c.detail}\n`);
     }
-    // Best practices (local-only, advisory): adopted-practice inventory + whether
-    // the repo trails the catalog. Fail-soft — never throws and never alters the
-    // doctor exit code.
-    reportBestPractices(top, proj?.slug ?? null);
+    // Best practices (advisory): adopted-practice inventory + whether the repo
+    // trails the catalog. Fail-soft — never throws and never alters the doctor exit
+    // code. Resolve the catalog SERVER-TRUTHFULLY first (prefer the live published
+    // catalog, fall back to the bundled mirror) — the same `loadCatalog` resolver
+    // `convene update` uses — so the "available" line reflects what the SERVER
+    // publishes, not the version baked into this binary. doctor is already async +
+    // already does network I/O (api.me above), so a live fetch here costs nothing
+    // extra; loadCatalog is fail-soft and tags its source, so an unreachable server
+    // simply yields the bundled mirror, labelled honestly as offline.
+    const { catalog: bpCatalog, source: bpSource } = await (0, catalog_1.loadCatalog)(cfg.apiKey ? new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey) : null);
+    reportBestPractices(top, proj?.slug ?? null, bpCatalog, bpSource);
     if (!checks.every((c) => c.ok))
         process.exitCode = 1;
 }
 /**
- * Print doctor's "Best practices" section. Local-only this phase: reads the repo
- * manifest and diffs it against the bundled catalog. Purely informational — it
- * never throws (a malformed manifest is swallowed) and never sets the exit code.
- *   - manifest present → catalog freshness line + each adopted practice + unknowns.
+ * Print doctor's "Best practices" section. Diffs the repo manifest against the
+ * RESOLVED catalog (`catalog`/`source` come from loadCatalog — live-preferred,
+ * bundled fallback). Purely informational — it never throws (a malformed manifest
+ * is swallowed) and never sets the exit code.
+ *   - manifest present → server-truthful freshness line + each adopted practice + unknowns.
  *   - on the bus but no manifest → a single nudge to adopt some.
  *   - not on the bus → nothing.
+ * The freshness wording is server-truthful: an "available"/"up to date" claim is
+ * made only when `source === 'live'`; an unreachable server yields the honest
+ * "bundled catalog … (offline — server version unknown)" line (see
+ * `bestPracticesFreshnessLine`). The same `catalogBehindLine` phrasing is shared
+ * with the `convene fetch` nudge so the sentence never means two different things.
  */
-function reportBestPractices(top, slug) {
+function reportBestPractices(top, slug, catalog, source) {
     try {
         const manifest = (0, config_1.loadManifest)(top);
         if (!manifest) {
@@ -603,10 +673,8 @@ function reportBestPractices(top, slug) {
             }
             return;
         }
-        const cmp = (0, manifest_1.compareToCatalog)(manifest, catalog_1.CATALOG);
-        process.stdout.write(cmp.behind
-            ? `· catalog v${cmp.catalogVersion} available (repo on v${cmp.repoVersion}) — run \`convene update\`\n`
-            : `· best practices up to date at v${cmp.repoVersion}\n`);
+        const cmp = (0, manifest_1.compareToCatalog)(manifest, catalog);
+        process.stdout.write(`· ${(0, manifest_1.bestPracticesFreshnessLine)(cmp, source)}\n`);
         for (const p of cmp.adopted) {
             const flag = p.outdated ? ` (outdated → v${p.catalogVersion})` : '';
             process.stdout.write(`    ${p.id} @ ${p.manifestVersion} [${p.level}]${flag}\n`);