convene-cli 1.12.0 → 1.13.0

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/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

package/dist/commands/explain.js

@@ -11,6 +11,7 @@ exports.explain = explain;
  * offline agent still gets the essentials. The endpoint is unauthenticated, so
  * this works even before `convene login`.
  */
+const node_child_process_1 = require("node:child_process");
 const config_1 = require("../config");
 const api_1 = require("../api");
 const brand_1 = require("../brand");
@@ -45,6 +46,20 @@ async function explain(question) {
             return;
         }
         if (res.ok && res.json && res.json.matched === false) {
+            // The agent asked how something works and Convene had no curated answer —
+            // the cleanest in-session friction signal. Capture it fire-and-forget
+            // (detached + unref'd, exactly as `convene fetch` spawns `convene announce`)
+            // so the product learns from confusion automatically instead of relying on a
+            // voluntary `convene suggest`. Gated on creds: no key/member → no spawn.
+            if (q && cfg.apiKey && cfg.member) {
+                try {
+                    const child = (0, node_child_process_1.spawn)(process.execPath, [process.argv[1], 'friction', '--kind', 'unmatched-explain', '--q', q], { detached: true, stdio: 'ignore' });
+                    child.unref();
+                }
+                catch {
+                    /* fail-open: friction capture must never break `explain` */
+                }
+            }
             // Unmatched query — point at the index + bundled essentials (still exit 0).
             process.stdout.write(`No specific match for "${q}". ${brand_1.BRAND.product} basics:\n\n${bundledSummary(cfg.baseUrl)}\n`);
             return;

package/dist/commands/friction.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.friction = friction;
+/**
+ * `convene friction` — automatic in-session CONFUSION capture. Files ONE
+ * low-severity feature_feedback row (category 'friction') when an agent hits a
+ * product rough edge the platform should learn from — today: an unmatched
+ * `convene explain` query (the agent literally asked how something works and
+ * Convene had no curated answer — the cleanest possible friction signal). It is
+ * spawned fire-and-forget by the surface that detects the friction (exactly as
+ * `convene fetch` spawns `convene announce`), so it NEVER blocks that surface.
+ *
+ * Mirrors `convene announce`'s posture:
+ *  - FAIL-OPEN: any error / missing config / non-bus repo exits 0 silently; a 5s
+ *    watchdog backstops a hang. It can never break the command that spawned it.
+ *  - IDEMPOTENT: a deterministic server idempotency-key
+ *    (`friction:<slug>:<instance>:<sigHash>`) is the authoritative dedupe; a local
+ *    (instance, sigHash) sentinel spares the redundant post when the SAME signal
+ *    recurs in a session.
+ *  - PRIVACY: the captured text is the agent's own words about Convene-the-product
+ *    — the same class of text `convene suggest` already mirrors to maintainers. It
+ *    is CLIPPED and posted only behind a valid key + project membership (the
+ *    authenticated-session gate). It never carries prompt text or work content
+ *    beyond the question the agent typed.
+ */
+const node_crypto_1 = require("node:crypto");
+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");
+const SIGNAL_MAX = 240;
+function clip(s, max) {
+    const t = s.trim();
+    return t.length <= max ? t : t.slice(0, max - 1) + '…';
+}
+/** Stable short hash of the normalized signal — keys both the idempotency key and the local sentinel. */
+function signalHash(kind, signal) {
+    const norm = `${kind}\n${signal.toLowerCase().replace(/\s+/g, ' ').trim()}`;
+    return (0, node_crypto_1.createHash)('sha256').update(norm).digest('hex').slice(0, 16);
+}
+/** Human-readable feedback body for a friction kind. */
+function bodyFor(kind, signal) {
+    const q = clip(signal, SIGNAL_MAX);
+    switch (kind) {
+        case 'unmatched-explain':
+            return `Unmatched \`convene explain\` query (no curated answer): "${q}"`;
+        default:
+            return `[${kind}] ${q}`;
+    }
+}
+async function run(opts) {
+    const kind = (opts.kind ?? '').trim();
+    const signal = (opts.q ?? '').trim();
+    if (!kind || !signal)
+        return; // no signal → nothing to capture
+    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 instance = (0, cache_1.ensureSessionInstance)(slug);
+    const sig = signalHash(kind, signal);
+    const body = bodyFor(kind, signal);
+    if (opts.dryRun) {
+        process.stdout.write(body + '\n');
+        return;
+    }
+    // Already captured this exact signal this session — spare the redundant post.
+    if ((0, cache_1.frictionAlreadyPosted)(slug, instance, sig))
+        return;
+    // The authenticated-session gate: only post with a real key + member.
+    const cfg = (0, config_1.resolveConfig)();
+    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 = `friction:${slug}:${instance}:${sig}`;
+    const res = await api.post(slug, { type: 'feature_feedback', body, category: 'friction', severity: 'low', tags: [kind] }, idem, 4000);
+    if (res.ok) {
+        // Only mark on success so a transient failure retries on the next occurrence.
+        (0, cache_1.markFrictionPosted)(slug, instance, sig);
+        if (res.json?.message?.short_id) {
+            process.stdout.write(`convene: captured [FRICTION] ${res.json.message.short_id} (${kind})\n`);
+        }
+    }
+}
+async function friction(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 friction capture must never break the surface that spawned it */
+    }
+    done();
+}

package/dist/commands/init.js

@@ -223,72 +223,9 @@ function registerHook(noHook) {
         log(hookSnippet());
     }
 }
-/**
- * The WP13 coordination hooks, in INSTALL ORDER. Order matters for the two Bash
- * PreToolUse entries: `gate-push --stdin` is wired before `guard`, so `guard` lands
- * LAST among Bash PreToolUse hooks (awareness/ux #10) — the deploy gate runs, then
- * the cheap halt/lane backstop. Each entry names the VERB its binary must support;
- * a stale `convene` missing the verb is skipped (so it can't error on every boot).
- *
- * `convene watch` is NOT a Bash hook — it's a long-running detached daemon that
- * `convene session-start` spawns from the SessionStart path (§4.4). Wiring it as a
- * blocking Bash/PreToolUse entry would stall; launching from session-start keeps it
- * off the discretionary tool path.
- */
-const COORD_HOOKS = [
-    {
-        event: 'SessionStart',
-        matcher: 'startup|resume|clear',
-        command: 'convene session-start',
-        verb: 'session-start',
-        note: 'auto catch-up digest + mints the session-instance + launches `convene watch`',
-    },
-    {
-        event: 'PreToolUse',
-        matcher: 'Bash',
-        command: 'convene gate-push --stdin',
-        verb: 'gate-push',
-        note: 'deploy gate before a push (fail-open-loud)',
-    },
-    // guard is appended AFTER gate-push so it is LAST among Bash PreToolUse hooks.
-    {
-        event: 'PreToolUse',
-        matcher: 'Bash',
-        command: 'convene guard',
-        verb: 'guard',
-        note: 'halt + lane backstop for Bash (fail-open-loud)',
-    },
-    {
-        event: 'PreToolUse',
-        matcher: '.*',
-        command: 'convene guard --halt-only',
-        verb: 'guard',
-        note: 'cheap directed-halt backstop on every tool call',
-    },
-    {
-        event: 'PostToolUse',
-        matcher: 'Bash',
-        command: 'convene gate-push --post',
-        verb: 'gate-push',
-        note: 'release the deploy lane after a push (idempotent)',
-    },
-    {
-        event: 'PostToolUse',
-        matcher: 'Edit|Write|MultiEdit',
-        command: 'convene beat --stdin',
-        verb: 'beat',
-        note: 'debounced session activity-beat so a heads-down session still pulses on the bus',
-    },
-    // Stop fires at every turn-end (no tool matcher); `convene wrap` is idempotent +
-    // debounced via the last-broadcast-sha cursor, so it posts at most one wrap per
-    // stretch of new committed work and stays silent on idle turns. Never blocks.
-    {
-        event: 'Stop',
-        command: 'convene wrap',
-        verb: 'wrap',
-        note: 'session-end wrap status when new committed work landed (idempotent, fail-open)',
-    },
-];
+// COORD_HOOKS (the canonical coordination-hook set, in install order) + the
+// missingCoordHooks drift-check now live in ../hook as the SINGLE source of truth,
+// so the writer here and the `convene doctor` drift-check can never disagree.
 /**
  * Wire the WP13 coordination hooks into a settings file (global or committed
  * project), idempotent + merge-safe via ensureHook (deep-clone, never clobber,
@@ -297,7 +234,7 @@ const COORD_HOOKS = [
  */
 function registerCoordinationHooks(settingsPath, label) {
     let unparseable = false;
-    for (const h of COORD_HOOKS) {
+    for (const h of hook_1.COORD_HOOKS) {
         if (!(0, hook_1.binarySupportsVerb)(h.verb)) {
             log(`· ${label}: skipped \`${h.command}\` — installed \`convene\` lacks \`${h.verb}\` (upgrade the CLI to enable).`);
             continue;

package/dist/commands/update.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.update = update;
+exports.assessBindingCommitSafety = assessBindingCommitSafety;
 exports.runUpdate = runUpdate;
 /**
  * `convene update` — Phase 4: check for + apply best-practices catalog updates.
@@ -147,6 +148,88 @@ function warnStaleCarriers(top, host) {
             `(without --no-mcp) to fix: ${stale.join(', ')}`);
     }
 }
+/**
+ * The managed files a binding re-stamp REWRITES (a curated subset of CONVENE_PATHS) —
+ * the only ones a divergent origin edit can actually CONFLICT on. Deliberately excludes
+ * the append/merge-only members: `.gitignore` (idempotent append-only guard),
+ * `.claude/settings.json` (additive JSON hook-merge), `.githooks/pre-push` (regenerated,
+ * no user content), and `CONVENE_PROTOCOL.md` (write-if-absent — never rewritten). An
+ * unrelated origin edit to one of those auto-merges, so refusing on it is a false alarm.
+ */
+const BINDING_REWRITE_PATHS = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    '.convene/project.json',
+    '.cursor/rules/convene.mdc',
+    '.clinerules/convene.md',
+    '.aider.conf.yml',
+    '.cursor/mcp.json',
+    '.vscode/mcp.json',
+    '.gemini/settings.json',
+    '.codex/config.toml',
+];
+/**
+ * Decide whether committing the convene-managed files on the LOCAL HEAD would collide
+ * with origin. The incident: `convene update --host … --commit` on a checkout whose
+ * origin had ALREADY re-pointed (and committed the same CLAUDE.md/AGENTS.md/.convene
+ * files) produced a commit guaranteed to conflict on coordination-critical files —
+ * manual git-archaeology in front of contributors.
+ *
+ * Fails OPEN on any unverifiable git state (no origin, detached HEAD, fetch failed,
+ * branch absent on origin) — exactly like the deploy compat gate (gate-push.ts), we
+ * never block a commit we cannot PROVE is unsafe. Only a CONFIRMED collision refuses.
+ */
+function assessBindingCommitSafety(top, host) {
+    if (!(0, git_1.originRemote)(top))
+        return { kind: 'ok', reason: 'no origin remote' };
+    const branch = (0, git_1.currentBranch)(top);
+    if (!branch)
+        return { kind: 'ok', reason: 'detached HEAD' };
+    if (!(0, git_1.gitFetch)(branch, 'origin', top))
+        return { kind: 'ok', reason: 'fetch failed (unverifiable)' };
+    const remote = (0, git_1.revParse)(`origin/${branch}`, top);
+    const head = (0, git_1.revParse)('HEAD', top);
+    if (!remote || !head)
+        return { kind: 'ok', reason: 'branch not on origin' };
+    // Origin tip is an ancestor of HEAD → local is up to date or ahead → a commit then
+    // push fast-forwards, no conflict possible.
+    if ((0, git_1.isAncestor)(remote, head, top))
+        return { kind: 'ok', reason: 'up to date / ahead of origin' };
+    // Behind or diverged. Does origin ALREADY carry this exact host binding? (A redundant
+    // re-commit here is the most common foot-gun — surface the friendlier pull message.)
+    const originProj = (0, git_1.gitShow)(`origin/${branch}`, '.convene/project.json', top);
+    if (originProj) {
+        try {
+            const b = JSON.parse(originProj)?.binding;
+            if (b?.host && (0, binding_1.normalizeHost)(b.host) === host)
+                return { kind: 'already-on-origin', branch };
+        }
+        catch {
+            /* unparseable origin project.json → fall through to the managed-file diff */
+        }
+    }
+    // Otherwise refuse ONLY if origin already changed a managed file the re-stamp
+    // REWRITES (BINDING_REWRITE_PATHS) — then a commit on top conflicts on it. A plain
+    // divergence that touched only append/merge-only managed files (or no managed file)
+    // is a routine rebase, not a convene-specific refusal.
+    const files = (0, git_1.changedPaths)('HEAD', `origin/${branch}`, BINDING_REWRITE_PATHS, top);
+    if (files.length)
+        return { kind: 'would-conflict', branch, files };
+    return { kind: 'ok', reason: 'diverged but origin did not touch managed files' };
+}
+/** The refusal/guidance message for a non-ok CommitSafety verdict. */
+function bindingCommitMessage(s, host) {
+    if (s.kind === 'already-on-origin') {
+        return (`origin/${s.branch} already re-points to ${host} — pull (\`git pull --rebase\`), do not re-commit. ` +
+            `Re-stamping with --commit here would create a redundant commit that conflicts on .convene/project.json. (Override: --force.)`);
+    }
+    if (s.kind === 'would-conflict') {
+        return (`refusing to --commit: your branch is behind/diverged from origin/${s.branch}, which already changed ` +
+            `convene-managed files (${s.files.join(', ')}). Committing the re-stamp now will conflict on coordination-critical ` +
+            `files. Run \`git pull --rebase\` first, then re-run. (Override: --force.)`);
+    }
+    return '';
+}
 async function runBindingRefresh(top, opts) {
     const existing = (0, config_1.loadProjectConfig)(top);
     if (!existing?.slug) {
@@ -209,6 +292,13 @@ async function runBindingRefresh(top, opts) {
     }
     const skipAgentRules = opts.noAgentRules === true || opts.agentRules === false;
     const skipMcp = opts.noMcp === true || opts.mcp === false;
+    // Divergence guard: a `--commit` that lands the re-stamped managed files on a local
+    // HEAD behind/diverged from an origin which ALSO changed those files conflicts on
+    // coordination-critical files (the VAcontractorCo incident). Assessed BEFORE any
+    // mutation so a refusal leaves the working tree clean. Only relevant under --commit.
+    const commitSafety = opts.commit
+        ? assessBindingCommitSafety(top, host)
+        : { kind: 'ok', reason: 'no --commit' };
     if (opts.check) {
         log(`Dry run — \`convene update ${opts.host ? `--host ${host}` : '--refresh'}\` would:`);
         log(`  • re-render CLAUDE.md + AGENTS.md coordination blocks at ${host}`);
@@ -221,10 +311,24 @@ async function runBindingRefresh(top, opts) {
             log(`  • update ~/.convene/config.json baseUrl → ${host}`);
         log(`  • write the .convene/project.json binding stamp (schema 3${serverVerified ? ', server-confirmed' : ''})`);
         log(opts.commit ? '  • commit exactly the convene files as one isolated commit' : '  • leave changes in the working tree (no commit without --commit)');
+        if (opts.commit && commitSafety.kind !== 'ok') {
+            log('');
+            log(opts.force
+                ? `  ⚠ origin divergence detected (${commitSafety.kind}); --force is set, so --commit would proceed ANYWAY.`
+                : `  ✗ --commit would be REFUSED — ${bindingCommitMessage(commitSafety, host)}`);
+        }
         log('');
-        log('Nothing written (--check). Re-run without --check to apply.');
+        log(opts.commit
+            ? 'Nothing written — origin was fetched only to assess the --commit divergence guard (no commit, no file changes). Re-run without --check to apply.'
+            : 'Nothing written (--check). Re-run without --check to apply.');
         return;
     }
+    // ENFORCE the divergence guard before mutating anything (clean tree on refusal).
+    if (opts.commit && commitSafety.kind !== 'ok') {
+        if (!opts.force)
+            (0, ctx_1.die)(bindingCommitMessage(commitSafety, host));
+        log(`⚠ --force: committing despite origin divergence (${commitSafety.kind}) — you will need to reconcile with origin afterward.`);
+    }
     log(`${opts.host ? 'Re-pointing' : 'Refreshing'} Convene binding for "${slug}" at ${host}…`);
     (0, init_1.writeCoordinationBlocks)(top, slug, member, host);
     if (!skipAgentRules)
@@ -279,11 +383,18 @@ async function runBindingRefresh(top, opts) {
 async function runUpdate(top, manifest, catalog, source, opts) {
     const rows = classify(manifest, catalog, top);
     const cmp = (0, manifest_1.compareToCatalog)(manifest, catalog);
+    // Newly-available catalog practices this repo has NOT adopted — the delta `update`
+    // is otherwise blind to (it only bumps the already-adopted set). Surfaced in the dry
+    // run + as an apply pointer so the "update available → nothing to apply" dead-end
+    // becomes "the delta is N new practices; run `convene adopt <id>`". update NEVER
+    // auto-adopts — adoption stays a deliberate act (see `convene adopt`).
+    const adoptedIds = new Set(manifest.practices.map((e) => e.id));
+    const available = catalog.practices.filter((p) => !adoptedIds.has(p.id));
     if (!opts.apply) {
-        printDryRun(rows, cmp.repoVersion, catalog.version, source, opts);
+        printDryRun(rows, cmp.repoVersion, catalog.version, source, opts, available);
         return;
     }
-    await applyUpdate(top, manifest, catalog, rows, opts);
+    await applyUpdate(top, manifest, catalog, rows, opts, available);
 }
 /** Build the per-practice rows: status vs. the live catalog + drift flags. */
 function classify(manifest, catalog, top) {
@@ -313,11 +424,20 @@ function classify(manifest, catalog, top) {
         };
     });
 }
-function printDryRun(rows, repoVersion, catalogVersion, source, opts) {
+function printDryRun(rows, repoVersion, catalogVersion, source, opts, available) {
     const behind = repoVersion !== catalogVersion;
-    log(behind
-        ? `Catalog update available: repo on v${repoVersion} → catalog v${catalogVersion}${source === 'bundled' ? ' (bundled — offline)' : ''}`
-        : `Best practices up to date at catalog v${repoVersion}${source === 'bundled' ? ' (bundled — offline)' : ''}`);
+    const hasAdoptedBump = rows.some((r) => hasBump(r));
+    const bundledNote = source === 'bundled' ? ' (bundled — offline)' : '';
+    // The catalog watermark moving does NOT mean an adopted practice has an update: it
+    // also moves when the catalog merely ADDS practices. If nothing adopted has a real
+    // bump, don't imply adopted updates exist — that recreates the dead-end this
+    // surfacing was built to kill. The available-not-adopted block below carries the
+    // actual delta + the `convene adopt` pointer.
+    log(behind && !hasAdoptedBump
+        ? `Adopted practices up to date at catalog v${repoVersion}; catalog is at v${catalogVersion}${bundledNote}`
+        : behind
+            ? `Catalog update available: repo on v${repoVersion} → catalog v${catalogVersion}${bundledNote}`
+            : `Best practices up to date at catalog v${repoVersion}${bundledNote}`);
     log('');
     const idW = Math.max(8, ...rows.map((r) => r.id.length));
     log(`  ${pad('practice', idW)}  ${pad('level', 9)}  ${pad('version', 18)}  change`);
@@ -343,18 +463,54 @@ function printDryRun(rows, repoVersion, catalogVersion, source, opts) {
     const skippedMajor = rows.filter((r) => skipForMajor(r, opts));
     const skippedDrift = rows.filter((r) => skipForDrift(r, opts));
     const skippedPatchGate = rows.filter((r) => skipForPatchGate(r, opts));
-    if (applicable.length === 0 && skippedMajor.length === 0 && skippedDrift.length === 0 && skippedPatchGate.length === 0) {
+    const nothingToApply = applicable.length === 0 && skippedMajor.length === 0 && skippedDrift.length === 0 && skippedPatchGate.length === 0;
+    // The load-bearing fix: when there is nothing to apply to the ADOPTED set, do NOT
+    // dead-end on a bare "Nothing to apply." while newly-available practices go unseen —
+    // fall through to the available block below.
+    if (nothingToApply && available.length === 0) {
         log('Nothing to apply.');
         return;
     }
-    if (applicable.length) {
-        log(`${applicable.length} practice(s) would update on \`convene update --apply\`.`);
+    if (nothingToApply) {
+        log('No updates to apply to your adopted practices.');
     }
-    reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
+    else {
+        if (applicable.length) {
+            log(`${applicable.length} practice(s) would update on \`convene update --apply\`.`);
+        }
+        reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
+    }
+    printAvailable(available, catalogVersion);
+    if (!nothingToApply) {
+        log('');
+        log('Next: `convene update --apply` (review with `git diff` and commit yourself — Convene never commits).');
+    }
+}
+/**
+ * List catalog practices the repo has NOT adopted and point at `convene adopt`. The
+ * delta `convene update` cannot take (it only bumps the already-adopted set) — without
+ * this an agent that saw "Catalog update available: repo on vX → vY" runs `--apply`,
+ * gets "Nothing to apply", and never learns the new practices exist. No-op when empty.
+ */
+function printAvailable(available, catalogVersion) {
+    if (available.length === 0)
+        return;
     log('');
-    log('Next: `convene update --apply` (review with `git diff` and commit yourself — Convene never commits).');
+    log(`${available.length} new practice(s) available in catalog v${catalogVersion} but NOT adopted here:`);
+    const aw = Math.max(8, ...available.map((p) => p.id.length));
+    for (const p of available)
+        log(`  ${pad(p.id, aw)}  ${pad(p.tier, 12)}  ${p.title}`);
+    log('');
+    log('`convene update` only refreshes practices you already adopted — it never adopts new ones for you.');
+    log(`To add one: \`convene adopt <id>\` (e.g. \`convene adopt ${available[0].id}\`). See the why first: \`convene practices <id>\`.`);
+}
+/** One-line apply-path pointer to `convene adopt` for newly-available practices. */
+function availablePointer(available) {
+    if (available.length === 0)
+        return;
+    log(`  ${available.length} new practice(s) available but NOT adopted — \`convene update --apply\` never adopts new ones. Use \`convene adopt <id>\`.`);
 }
-async function applyUpdate(top, manifest, catalog, rows, opts) {
+async function applyUpdate(top, manifest, catalog, rows, opts, available) {
     const byId = new Map(catalog.practices.map((p) => [p.id, p]));
     const toUpdate = rows.filter((r) => isApplicable(r, opts));
     const skippedMajor = rows.filter((r) => skipForMajor(r, opts));
@@ -365,6 +521,7 @@ async function applyUpdate(top, manifest, catalog, rows, opts) {
         log('Nothing applied — no practice was eligible.');
         reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
         reportRemoved(rows);
+        availablePointer(available); // never auto-adopts; just points at `convene adopt`
         return;
     }
     // PRESERVE skipped (drifted / major / patch-gated) sections byte-for-byte: snapshot
@@ -415,6 +572,7 @@ async function applyUpdate(top, manifest, catalog, rows, opts) {
     }
     reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
     reportRemoved(rows);
+    availablePointer(available); // never auto-adopts; just points at `convene adopt`
     log('');
     log('Changes are in your working tree only. Review with `git diff` and commit yourself — Convene never commits.');
 }

package/dist/git.js

@@ -20,6 +20,8 @@ exports.revListCount = revListCount;
 exports.revParse = revParse;
 exports.isAncestor = isAncestor;
 exports.gitFetch = gitFetch;
+exports.gitShow = gitShow;
+exports.changedPaths = changedPaths;
 exports.gitHooksDir = gitHooksDir;
 exports.gitConfigSetLocal = gitConfigSetLocal;
 exports.gitConfigUnsetLocal = gitConfigUnsetLocal;
@@ -240,6 +242,22 @@ function gitFetch(ref, remote = 'origin', cwd = process.cwd()) {
         return false;
     }
 }
+/**
+ * Contents of `ref:relPath` (e.g. `origin/main:.convene/project.json`), or null when
+ * the ref or path does not exist there. Read-only, bounded, never throws — used to
+ * peek at what a remote tip carries without checking it out.
+ */
+function gitShow(ref, relPath, cwd = process.cwd()) {
+    return git(['show', `${ref}:${relPath}`], cwd);
+}
+/**
+ * File paths that DIFFER between two refs, restricted to `paths` (files or dirs):
+ * `git diff --name-only refA refB -- <paths>`. Empty array when identical or on error.
+ */
+function changedPaths(refA, refB, paths, cwd = process.cwd()) {
+    const out = git(['diff', '--name-only', refA, refB, '--', ...paths], cwd);
+    return out ? out.split('\n').map((l) => l.trim()).filter(Boolean) : [];
+}
 /** Absolute path to this repo's hooks directory (resolves worktrees/submodules). */
 function gitHooksDir(cwd = process.cwd()) {
     const p = git(['rev-parse', '--git-path', 'hooks'], cwd);

package/dist/hook.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HOOK_COMMAND = exports.SETTINGS_PATH = void 0;
+exports.COORD_HOOKS = exports.HOOK_COMMAND = exports.SETTINGS_PATH = void 0;
 exports.binarySupportsVerb = binarySupportsVerb;
 exports.readSettingsRaw = readSettingsRaw;
 exports.parseSettings = parseSettings;
@@ -13,6 +13,7 @@ exports.serializeSettings = serializeSettings;
 exports.genericHookIsRegistered = genericHookIsRegistered;
 exports.withGenericHook = withGenericHook;
 exports.ensureHook = ensureHook;
+exports.missingCoordHooks = missingCoordHooks;
 exports.ensureHookRegistered = ensureHookRegistered;
 exports.isConveneHookCommand = isConveneHookCommand;
 exports.conveneHookFingerprint = conveneHookFingerprint;
@@ -174,6 +175,69 @@ function ensureHook(eventName, command, matcher, settingsPath = exports.SETTINGS
         return 'manual';
     }
 }
+exports.COORD_HOOKS = [
+    {
+        event: 'SessionStart',
+        matcher: 'startup|resume|clear',
+        command: 'convene session-start',
+        verb: 'session-start',
+        note: 'auto catch-up digest + mints the session-instance + launches `convene watch`',
+    },
+    {
+        event: 'PreToolUse',
+        matcher: 'Bash',
+        command: 'convene gate-push --stdin',
+        verb: 'gate-push',
+        note: 'deploy gate before a push (fail-open-loud)',
+    },
+    // guard is appended AFTER gate-push so it is LAST among Bash PreToolUse hooks.
+    {
+        event: 'PreToolUse',
+        matcher: 'Bash',
+        command: 'convene guard',
+        verb: 'guard',
+        note: 'halt + lane backstop for Bash (fail-open-loud)',
+    },
+    {
+        event: 'PreToolUse',
+        matcher: '.*',
+        command: 'convene guard --halt-only',
+        verb: 'guard',
+        note: 'cheap directed-halt backstop on every tool call',
+    },
+    {
+        event: 'PostToolUse',
+        matcher: 'Bash',
+        command: 'convene gate-push --post',
+        verb: 'gate-push',
+        note: 'release the deploy lane after a push (idempotent)',
+    },
+    {
+        event: 'PostToolUse',
+        matcher: 'Edit|Write|MultiEdit',
+        command: 'convene beat --stdin',
+        verb: 'beat',
+        note: 'debounced session activity-beat so a heads-down session still pulses on the bus',
+    },
+    // Stop fires at every turn-end (no tool matcher); `convene wrap` is idempotent +
+    // debounced via the last-broadcast-sha cursor, so it posts at most one wrap per
+    // stretch of new committed work and stays silent on idle turns. Never blocks.
+    {
+        event: 'Stop',
+        command: 'convene wrap',
+        verb: 'wrap',
+        note: 'session-end wrap status when new committed work landed (idempotent, fail-open)',
+    },
+];
+/**
+ * COORD_HOOKS entries whose verb THIS binary supports but which are NOT present in
+ * `settings` — i.e. coordination wiring that has drifted from the canonical set.
+ * Verbs the binary lacks are skipped (mirroring registerCoordinationHooks), so an
+ * older CLI is never told to wire something it can't run.
+ */
+function missingCoordHooks(settings) {
+    return exports.COORD_HOOKS.filter((h) => binarySupportsVerb(h.verb) && !genericHookIsRegistered(settings, h.event, h.command, h.matcher));
+}
 /** Ensure the UserPromptSubmit hook is registered (idempotent, backs up). */
 function ensureHookRegistered() {
     const raw = readSettingsRaw();

package/dist/index.js

@@ -44,6 +44,7 @@ const fetch_1 = require("./commands/fetch");
 const notify_1 = require("./commands/notify");
 const announce_1 = require("./commands/announce");
 const wrap_1 = require("./commands/wrap");
+const friction_1 = require("./commands/friction");
 const post = __importStar(require("./commands/post"));
 const inbox_1 = require("./commands/inbox");
 const feedback_1 = require("./commands/feedback");
@@ -71,6 +72,7 @@ const watch_reap_1 = require("./commands/watch-reap");
 const explain_1 = require("./commands/explain");
 const practices_1 = require("./commands/practices");
 const update_1 = require("./commands/update");
+const adopt_1 = require("./commands/adopt");
 const program = new commander_1.Command();
 exports.program = program;
 // Read the version from package.json so `convene --version` always tracks the
@@ -220,6 +222,14 @@ program
     .option('--project <slug>')
     .option('--dry-run', 'print the status it would post; do not post')
     .action((opts) => (0, wrap_1.wrap)(opts));
+program
+    .command('friction')
+    .description('auto-capture in-session confusion as a low-severity [FRICTION] feature_feedback (idempotent, fail-silent)')
+    .option('--kind <kind>', 'friction kind (e.g. unmatched-explain)')
+    .option('--q <text>', "the signal text — the agent's own words about Convene")
+    .option('--project <slug>')
+    .option('--dry-run', 'print what it would capture; do not post')
+    .action((opts) => (0, friction_1.friction)(opts));
 const postCmd = program.command('post').description('post outbound coordination messages');
 postCmd
     .command('status <body>')
@@ -396,6 +406,14 @@ program
     .option('--no-agent-rules', 'skip the cross-agent rule files during --refresh/--host')
     .option('--no-mcp', 'skip the MCP carriers during --refresh/--host')
     .action((opts) => (0, update_1.update)(opts));
+program
+    .command('adopt <targets...>')
+    .description('adopt one or more catalog best practices into this repo (merges into the existing set, drift-safe; review in your working tree, never auto-commits)')
+    .option('--force', 're-level a locally-edited (drifted) practice anyway (overwrites your edits)')
+    .option('--no-hook', 'do not wire settingsHook guards (settingsJson deny + gitignore still apply)')
+    .option('--offline', 'skip the dashboard adoption report')
+    .option('--project <slug>', 'project slug (defaults to .convene/project.json)')
+    .action((targets, opts) => (0, adopt_1.adopt)(targets, opts));
 program.command('doctor').description('diagnose setup').option('--fix', 'attempt safe fixes').action((opts) => (0, auth_1.doctor)(opts));
 if (require.main === module) {
     program.parseAsync(process.argv).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convene-cli",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Convene CLI — AI development coordination bus client + UserPromptSubmit hook. Install: npm i -g convene-cli; then `convene setup`.",
   "license": "MIT",
   "homepage": "https://convene.live",