convene-cli 1.11.0 → 1.13.0

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/commands/watch.js

@@ -17,21 +17,24 @@ exports.watch = watch;
  *   - A bounded run (no live config / not on the bus) exits 0 silently so a
  *     SessionStart launch on a non-bus repo is a no-op.
  *
- * APPEND-ONLY + HIGH-WATER (awareness/concurrency #5 — the lost-interrupt race):
- *   - Each matched halt/interrupt is APPENDED to a per-slug jsonl via
- *     appendWatchEntry. The daemon NEVER truncates the log.
- *   - Readers (fetch / doctor / the health line) render entries with seq >
- *     high-water and advance a MONOTONIC high-water with persistHighWater. The
- *     reader, not the writer, owns the cursor, so a read can never race an append
- *     into losing an interrupt.
+ * RENDERING IS NOT THIS DAEMON'S JOB. Directed halts reach the agent's context
+ * via the server-truth PULL surfaces (fetch / session-open / lane-state), which
+ * query the server — the single authority for halt state. This daemon only:
+ *   - stamps a liveness heartbeat each iteration (the health line reads its age,
+ *     surfacing DEGRADED if the watcher is down);
+ *   - optionally fires a best-effort desktop notification per matched halt
+ *     (--notify; off by default — never enabled by the SessionStart spawn);
+ *   - persists a MONOTONIC poll cursor so a relaunch (every SessionStart) resumes
+ *     incrementally instead of re-scanning the backlog.
+ * It formerly appended matched halts to a per-slug jsonl for a reader to drain,
+ * but that reader was never wired up and a local cache could drift from server
+ * truth and mislead — so the jsonl was removed in favor of the pull path.
  *
- * TRUST: the daemon writes the message TYPE + server-derived routing/handles +
- * the (UNTRUSTED) body verbatim into the jsonl. The body is NEVER interpreted
- * here — the consumer renders it inert. The block DECISION is the guard's, from
- * lane-state; watch only narrows the window for non-deploy turns.
+ * TRUST: the block DECISION is the guard's, from lane-state. A halt body is
+ * UNTRUSTED and is NEVER interpreted here — the notification is a fixed template
+ * that never splices the body. watch only narrows the window for non-deploy turns.
  *
- * --notify: best-effort desktop ping per surfaced halt (delegates to the notify
- * verb's mechanism if present; otherwise silently skipped). Never blocks the loop.
+ * --notify: best-effort desktop ping per matched halt. Never blocks the loop.
  */
 const node_child_process_1 = require("node:child_process");
 const git_1 = require("../git");
@@ -80,30 +83,12 @@ function watchShouldExit(args) {
 }
 const HALT_TYPES = new Set(['halt', 'interrupt']);
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** Map a server feed/poll message to an inert WatchEntry. Returns null for non-halts. */
-function toEntry(m) {
-    if (!m || typeof m !== 'object')
-        return null;
-    const type = typeof m.type === 'string' ? m.type : '';
-    if (!HALT_TYPES.has(type))
-        return null;
-    // seq is the messages.id (enrich exposes it as `seq`, falling back to numeric id).
-    const seq = typeof m.seq === 'number' ? m.seq : typeof m.id === 'number' ? m.id : Number(m.id);
-    if (!Number.isFinite(seq))
-        return null;
-    return {
-        seq,
-        type,
-        short_id: typeof m.short_id === 'string' ? m.short_id : null,
-        // from/to/body are DISPLAY/UNTRUSTED — copied verbatim, never interpreted here.
-        from: typeof m.from_handle === 'string' ? m.from_handle : typeof m.from === 'string' ? m.from : null,
-        to: typeof m.to === 'string' ? m.to : typeof m.to_member === 'string' ? m.to_member : null,
-        body: typeof m.body === 'string' ? m.body : null,
-        at: typeof m.created_at === 'string' ? m.created_at : null,
-    };
+/** True if a server feed/poll message is a halt/interrupt control message. */
+function isHaltMessage(m) {
+    return !!m && typeof m === 'object' && typeof m.type === 'string' && HALT_TYPES.has(m.type);
 }
 /** Best-effort desktop notification; never blocks or throws. */
-function notifyBestEffort(entry) {
+function notifyBestEffort() {
     try {
         if (process.platform === 'darwin') {
             // A halt is a control signal; the body is UNTRUSTED so we do NOT splice it
@@ -132,10 +117,9 @@ async function loop(opts) {
         return 0; // can't authenticate → silent no-op
     const instance = (0, cache_1.ensureSessionInstance)(slug);
     const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
-    // Resume cursor: start from the persisted high-water so a relaunch never
-    // re-reads material the reader already drained. (The reader's high-water is the
-    // canonical "already surfaced" mark; the daemon resumes from there.)
-    let cursor = (0, cache_1.readWatchHighWater)(slug);
+    // Resume from the persisted poll cursor so a relaunch (every SessionStart)
+    // resumes incrementally instead of re-scanning the backlog from zero.
+    let cursor = (0, cache_1.readWatchCursor)(slug);
     let backoff = BACKOFF_BASE_MS;
     let iterations = 0;
     const limit = typeof opts.maxIterations === 'number' ? opts.maxIterations : Infinity;
@@ -195,19 +179,17 @@ async function loop(opts) {
             backoff = BACKOFF_BASE_MS; // recovered
             const msgs = Array.isArray(res.json.messages) ? res.json.messages : [];
             for (const m of msgs) {
-                const entry = toEntry(m);
-                if (!entry)
+                if (!isHaltMessage(m))
                     continue;
-                (0, cache_1.appendWatchEntry)(slug, entry);
                 if (opts.notify)
-                    notifyBestEffort(entry);
+                    notifyBestEffort();
             }
-            // Advance the resume cursor to the server's reported cursor (monotonic). This
-            // is the long-poll resume seq, NOT the reader's high-water — the daemon must
-            // move past EVERY message it saw (incl. non-halts) or it would re-fetch them
-            // forever. The reader's high-water only advances over rendered halts.
-            if (typeof res.json.cursor === 'number' && res.json.cursor > cursor)
+            // Advance the resume cursor past EVERY message seen (incl. non-halts) so the
+            // daemon never re-fetches them, and PERSIST it so a relaunch resumes here.
+            if (typeof res.json.cursor === 'number' && res.json.cursor > cursor) {
                 cursor = res.json.cursor;
+                (0, cache_1.persistWatchCursor)(slug, cursor);
+            }
             iterations++;
         }
     }

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,10 +44,12 @@ 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");
 const auth_1 = require("./commands/auth");
+const enroll_1 = require("./commands/enroll");
 const init_1 = require("./commands/init");
 const offboard_1 = require("./commands/offboard");
 const join_1 = require("./commands/join");
@@ -70,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
@@ -94,6 +97,15 @@ program
     .option('--api-key <key>', 'API key, or "-" to read from stdin (no shell history)')
     .option('--base-url <url>', 'Convene base URL')
     .action((opts) => (0, auth_1.login)(opts));
+program
+    .command('enroll-device')
+    .description('connect THIS machine to your existing identity via an emailed link (no key copying)')
+    .option('--email <email>', 'email of your existing identity (defaults to git user.email)')
+    .option('--base-url <url>', 'Convene base URL')
+    .option('--label <label>', 'a label for this device (defaults to hostname)')
+    .action(async (opts) => {
+    await (0, enroll_1.enrollDevice)({ email: opts.email, baseUrl: opts.baseUrl, label: opts.label });
+});
 program.command('whoami').description('show identity, base URL, session, bus status').action(() => (0, auth_1.whoami)());
 program
     .command('fetch')
@@ -210,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>')
@@ -386,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,9 +1,9 @@
 {
   "name": "convene-cli",
-  "version": "1.11.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://dev.convene.live",
+  "homepage": "https://convene.live",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alex-hawkinson/Convene.git",