convene-cli 1.11.0 → 1.13.0

package/dist/api.js

@@ -42,6 +42,8 @@ class ConveneApi {
                 headers['x-convene-session-instance'] = this.instance;
             if (opts.idempotencyKey)
                 headers['idempotency-key'] = opts.idempotencyKey;
+            if (opts.headers)
+                Object.assign(headers, opts.headers);
             const res = await fetch(`${this.baseUrl}${brand_1.BRAND.apiBase}${apiPath}`, {
                 method,
                 headers,
@@ -154,6 +156,14 @@ class ConveneApi {
     join(slug, body, timeoutMs) {
         return this.request('POST', `/projects/${encodeURIComponent(slug)}/join`, { body, timeoutMs });
     }
+    /** Device enrollment — start (no bearer). Emails the member a confirm link if one exists. */
+    enrollStart(body, timeoutMs) {
+        return this.request('POST', '/enroll/device/start', { body, timeoutMs });
+    }
+    /** Device enrollment — poll for the minted key, presenting the raw device secret (no bearer). */
+    enrollPoll(enrollmentId, rawSecret, timeoutMs) {
+        return this.request('GET', `/enroll/device/poll?id=${encodeURIComponent(String(enrollmentId))}`, { headers: { 'x-device-secret': rawSecret }, timeoutMs });
+    }
     /** Self-recovery: re-grant your own membership via the committed join token (no bearer
      *  auth required). Restores OWNER only from a server-recorded prior-owner row. */
     reclaim(slug, body, timeoutMs) {

package/dist/brand.js

@@ -13,8 +13,8 @@ exports.BRAND = {
     product: 'Convene',
     slug: 'convene',
     bin: 'convene',
-    domain: 'dev.convene.live',
-    baseUrl: 'https://dev.convene.live',
+    domain: 'convene.live',
+    baseUrl: 'https://convene.live',
     /** Public product / front-door base URL for human-facing links (dashboard, /start, docs). */
     siteDomain: 'convene.live',
     siteUrl: 'https://convene.live',

package/dist/cache.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.OVERRIDE_TTL_MS = exports.writeWatchHighWater = exports.LIVE_SESSION_RECENT_SEC = exports.LIVE_SESSION_WINDOW_SEC = void 0;
+exports.OVERRIDE_TTL_MS = exports.LIVE_SESSION_RECENT_SEC = exports.LIVE_SESSION_WINDOW_SEC = void 0;
 exports.readCache = readCache;
 exports.writeCache = writeCache;
 exports.ageSeconds = ageSeconds;
@@ -23,13 +23,12 @@ 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.readWatchHighWater = readWatchHighWater;
-exports.persistHighWater = persistHighWater;
-exports.appendWatchEntry = appendWatchEntry;
-exports.appendWatch = appendWatch;
-exports.readWatchSince = readWatchSince;
+exports.readWatchCursor = readWatchCursor;
+exports.persistWatchCursor = persistWatchCursor;
 exports.touchWatchHeartbeat = touchWatchHeartbeat;
 exports.watchHeartbeatAgeSec = watchHeartbeatAgeSec;
 exports.writeWatchPid = writeWatchPid;
@@ -361,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),
@@ -390,19 +433,32 @@ function writeLastBroadcastSha(slug, sha) {
         /* best-effort */
     }
 }
-function watchFile(slug) {
-    return slugFile(slug, 'watch.jsonl');
-}
-function watchHighWaterFile(slug) {
+// ── watch poll resume cursor (WP12) ──────────────────────────────────────────
+// The `convene watch` daemon (cli/src/commands/watch.ts) long-polls the bus,
+// stamps a liveness heartbeat each iteration (the health line reads its age), and
+// optionally desktop-notifies on a directed halt. It persists a MONOTONIC poll
+// cursor here so a relaunch (every SessionStart) resumes incrementally instead of
+// re-scanning the backlog from zero.
+//
+// The daemon does NOT render anything into agent-facing context: directed halts
+// reach the agent via the server-truth PULL surfaces (fetch / session-open /
+// lane-state), which query the server — the single authority for halt state. (The
+// daemon formerly APPENDED matched halts to a per-slug `.watch.jsonl` for a reader
+// to drain, but that reader was never wired into any surface, and a local cache
+// could drift from server truth and mislead. The jsonl was removed in favor of the
+// pull path; only this resume cursor + the heartbeat remain.)
+function watchCursorFile(slug) {
+    // Legacy `.watch.hw` (high-water) extension retained so existing caches aren't
+    // orphaned on upgrade — the file is now the daemon's own poll resume cursor.
     return slugFile(slug, 'watch.hw');
 }
 function watchHeartbeatFile(slug) {
     return slugFile(slug, 'watch.hb');
 }
-/** Read the persisted high-water seq for the watch jsonl (0 if none). */
-function readWatchHighWater(slug) {
+/** Read the daemon's persisted poll resume cursor (0 if none). */
+function readWatchCursor(slug) {
     try {
-        const n = parseInt(node_fs_1.default.readFileSync(watchHighWaterFile(slug), 'utf8').trim(), 10);
+        const n = parseInt(node_fs_1.default.readFileSync(watchCursorFile(slug), 'utf8').trim(), 10);
         return Number.isFinite(n) ? n : 0;
     }
     catch {
@@ -410,87 +466,21 @@ function readWatchHighWater(slug) {
     }
 }
 /**
- * Persist the high-water seq for the watch jsonl — MONOTONIC. A lower seq is
- * ignored (GREATEST semantics) so a reader can never rewind past material it
- * already drained. NEVER truncates the jsonl.
+ * Persist the daemon's poll resume cursor — MONOTONIC. A lower seq is ignored
+ * (GREATEST semantics) so a relaunch never rewinds the cursor and re-scans
+ * material it already polled past. Best-effort; never throws.
  */
-function persistHighWater(slug, seq) {
+function persistWatchCursor(slug, seq) {
     try {
         node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
-        const cur = readWatchHighWater(slug);
+        const cur = readWatchCursor(slug);
         if (seq > cur)
-            node_fs_1.default.writeFileSync(watchHighWaterFile(slug), String(seq) + '\n', { mode: 0o600 });
+            node_fs_1.default.writeFileSync(watchCursorFile(slug), String(seq) + '\n', { mode: 0o600 });
     }
     catch {
         /* best-effort */
     }
 }
-/** Back-compat alias for the WP2 stub name; identical monotonic behavior. */
-exports.writeWatchHighWater = persistHighWater;
-/**
- * APPEND a watch entry to the jsonl (append-only — never rewrites the file).
- * The append is atomic at the OS level for a single small write, so a concurrent
- * reader sees whole lines. Best-effort; never throws (the watch daemon is
- * fail-open). Entries WITHOUT a finite numeric seq are dropped — an un-keyed
- * entry can't participate in the high-water drain and would be re-rendered
- * forever.
- */
-function appendWatchEntry(slug, entry) {
-    if (!entry || typeof entry.seq !== 'number' || !Number.isFinite(entry.seq))
-        return;
-    try {
-        node_fs_1.default.mkdirSync(config_1.CACHE_DIR, { recursive: true, mode: 0o700 });
-        node_fs_1.default.appendFileSync(watchFile(slug), JSON.stringify(entry) + '\n', { mode: 0o600 });
-    }
-    catch {
-        /* best-effort */
-    }
-}
-/** Back-compat alias for the WP2 stub name. */
-function appendWatch(slug, entry) {
-    appendWatchEntry(slug, entry);
-}
-/**
- * Read all watch entries with seq > highWater, ascending by seq, de-duplicated
- * on seq (the daemon may re-append the same entry after a resume — the reader
- * tolerates duplicates by keeping the first per seq). Does NOT advance the
- * high-water and does NOT truncate — the caller decides what was actually
- * rendered and calls persistHighWater(slug, lastRenderedSeq). A malformed line
- * is skipped, never fatal.
- */
-function readWatchSince(slug, highWater) {
-    let raw;
-    try {
-        raw = node_fs_1.default.readFileSync(watchFile(slug), 'utf8');
-    }
-    catch {
-        return [];
-    }
-    const seen = new Set();
-    const out = [];
-    for (const line of raw.split('\n')) {
-        const s = line.trim();
-        if (!s)
-            continue;
-        let e;
-        try {
-            e = JSON.parse(s);
-        }
-        catch {
-            continue; // a torn/partial line — skip, the next drain re-reads it whole
-        }
-        if (typeof e.seq !== 'number' || !Number.isFinite(e.seq))
-            continue;
-        if (e.seq <= highWater)
-            continue;
-        if (seen.has(e.seq))
-            continue;
-        seen.add(e.seq);
-        out.push(e);
-    }
-    out.sort((a, b) => a.seq - b.seq);
-    return out;
-}
 // ── watch heartbeat (WP12) ───────────────────────────────────────────────────
 // The daemon stamps a heartbeat each loop iteration; the health line / doctor
 // read its age. A stale/absent heartbeat ⇒ watch is down ⇒ surface DEGRADED.

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);
+}