convene-cli 1.9.0 → 1.10.0

package/dist/commands/fetch.js

@@ -20,10 +20,12 @@ exports.runFetch = runFetch;
  *     stale cache and renders DEGRADED (loud-but-non-blocking).
  */
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_child_process_1 = require("node:child_process");
 const git_1 = require("../git");
 const config_1 = require("../config");
 const cache_1 = require("../cache");
 const manifest_1 = require("../catalog/manifest");
+const binding_local_1 = require("../binding-local");
 const api_1 = require("../api");
 const render_1 = require("../render");
 const catchup_1 = require("./catchup");
@@ -145,6 +147,33 @@ function codexCwdFromStdin() {
 function toRenderMessages(arr) {
     return Array.isArray(arr) ? arr : [];
 }
+/**
+ * Front-of-session auto-announce: the FIRST authenticated `fetch` of a session
+ * spawns a DETACHED, fire-and-forget `convene announce` so the bus learns who is
+ * working on what before any push — the cross-tool keystone (this path runs for
+ * Claude Code AND Codex's `fetch --codex-hook`). Detached + unref'd (mirrors
+ * session-start's launchWatch) so the prompt hot path is NEVER slowed by a network
+ * post. Gated by the cheap local (instance, branch) sentinel so we don't spawn a
+ * no-op process every prompt; the announce command re-checks it and carries the
+ * authoritative server idempotency-key, so a same-instant double-spawn is harmless.
+ * Best-effort: any failure only narrows cross-session visibility, never blocks.
+ */
+function maybeAnnounce(slug, top) {
+    try {
+        const instance = (0, cache_1.ensureSessionInstance)(slug);
+        const branch = (0, git_1.currentBranch)(top) ?? 'detached';
+        if ((0, cache_1.announceAlreadyPosted)(slug, instance, branch))
+            return; // already announced this (instance, branch)
+        const child = (0, node_child_process_1.spawn)(process.execPath, [process.argv[1], 'announce'], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+    }
+    catch {
+        /* fail-open */
+    }
+}
 async function runFetch(opts = {}) {
     // Absolute watchdog: under any circumstance, do not hold the prompt past 6s.
     // unref'd so the timer itself is never a live libuv handle at teardown; it still
@@ -173,7 +202,7 @@ async function runFetch(opts = {}) {
         if (!proj?.slug)
             return done(0); // repo not on the bus → silent no-op
         const slug = proj.slug;
-        const cfg = (0, config_1.resolveConfig)();
+        const cfg = (0, config_1.resolveConfigForRepo)(top, proj);
         const lookback = opts.lookback ?? 60;
         const max = opts.max ?? 20;
         const member = cfg.member;
@@ -191,6 +220,9 @@ async function runFetch(opts = {}) {
             }), opts.codexHook);
             return done(0);
         }
+        // Authenticated + on the bus: spawn the front-of-session announce (detached,
+        // once per session/branch). Fires regardless of which render path runs below.
+        maybeAnnounce(slug, top);
         // `--since-last`: render the catch-up digest since the read cursor instead
         // of the time-windowed feed. Read-only (no advance), fail-open. Suppressed if
         // SessionStart already surfaced a catch-up this boot (per-instance sentinel).
@@ -218,6 +250,9 @@ async function runFetch(opts = {}) {
             const nudge = catalogBehindNudge(top);
             if (nudge)
                 process.stdout.write(nudge + '\n');
+            const drift = (0, binding_local_1.localBindingDrift)(top, proj);
+            if (drift)
+                process.stdout.write(drift + '\n');
         };
         // Cache short-circuit for rapid successive prompts.
         const cache = (0, cache_1.readCache)(slug);

package/dist/commands/gate-push.js

@@ -137,7 +137,7 @@ async function run(opts) {
     const slug = opts.project || proj?.slug || null;
     if (!slug)
         return 0; // repo not on the bus → no-op (zero network)
-    const cfg = (0, config_1.resolveConfig)();
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj);
     const member = cfg.member;
     const session = member ? (0, git_1.sessionId)(member, top) : null;
     // Determine the ref(s) being pushed.

package/dist/commands/guard.js

@@ -205,7 +205,7 @@ async function run(opts) {
     const slug = opts.project || proj?.slug || null;
     if (!slug)
         return 0; // not on the bus → no-op (covers BOTH match + non-match)
-    const cfg = (0, config_1.resolveConfig)();
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj);
     const member = cfg.member;
     const session = member ? (0, git_1.sessionId)(member, top) : null;
     if (!cfg.apiKey || !session) {

package/dist/commands/init.js

@@ -7,7 +7,11 @@ exports.AIDER_CONF = exports.CONVENE_PATHS = void 0;
 exports.upsertMarkerBlock = upsertMarkerBlock;
 exports.removeMarkerBlock = removeMarkerBlock;
 exports.removeGitignoreGuard = removeGitignoreGuard;
+exports.writeAgentRules = writeAgentRules;
 exports.removeTomlBlock = removeTomlBlock;
+exports.writeMcpConfigs = writeMcpConfigs;
+exports.writeCoordinationBlocks = writeCoordinationBlocks;
+exports.commitConveneFiles = commitConveneFiles;
 exports.refreshDocs = refreshDocs;
 exports.init = init;
 /**
@@ -275,6 +279,15 @@ const COORD_HOOKS = [
         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)',
+    },
 ];
 /**
  * Wire the WP13 coordination hooks into a settings file (global or committed
@@ -609,7 +622,10 @@ async function refreshDocs(opts) {
     if (!existing?.slug) {
         (0, ctx_1.die)('this repo is not on Convene yet — run `convene setup` first; `--refresh-docs` only re-renders an already-onboarded repo.');
     }
-    const cfg = (0, config_1.resolveConfig)();
+    // Honor a committed host pin so a pinned repo re-renders its carriers at the
+    // bound host, not the ambient one (resolveConfigForRepo); unpinned repos are
+    // unchanged (it falls back to resolveConfig).
+    const cfg = (0, config_1.resolveConfigForRepo)(top, existing);
     const slug = existing.slug;
     const member = cfg.member;
     const baseUrl = cfg.baseUrl;
@@ -647,10 +663,12 @@ async function init(opts) {
         (0, ctx_1.die)('refusing to onboard non-interactively without confirmation — connecting THIS repo to Convene ' +
             'is a deliberate choice, not a side-effect. If you intend it, re-run with `--yes`.');
     }
-    const cfg = (0, config_1.resolveConfig)();
+    const existing = (0, config_1.loadProjectConfig)(top);
+    // Honor a committed host pin on a RE-RUN (a freshly-onboarding repo has none, so
+    // this equals resolveConfig); keeps a re-run targeting the bound bus.
+    const cfg = (0, config_1.resolveConfigForRepo)(top, existing);
     const baseUrl = cfg.baseUrl;
     let member = cfg.member;
-    const existing = (0, config_1.loadProjectConfig)(top);
     const skipHook = opts.noHook === true || opts.hook === false;
     const skipGithook = opts.noGithook === true || opts.githook === false;
     const skipJoinToken = opts.noJoinToken === true || opts.joinToken === false;
@@ -760,7 +778,12 @@ async function init(opts) {
     displayName = displayName || slug;
     // 3. .convene/project.json (committed). The joinToken is a PROJECT-SCOPED
     //    enrollment secret — safe to commit in a PRIVATE repo (repo-read = team).
-    const projFile = (0, config_1.writeProjectConfig)(top, { slug, displayName, ...(joinToken ? { joinToken } : {}) });
+    //    Preserve any sibling committed fields (bestPractices manifest, host-pin
+    //    binding) on a re-run — strip the stale schema so writeProjectConfig
+    //    re-derives it. For a FRESH repo `existing` is null, so this stays
+    //    byte-identical to a plain `{ slug, displayName, joinToken }` schema-1 write.
+    const { schema: _schema, ...preserved } = existing ?? {};
+    const projFile = (0, config_1.writeProjectConfig)(top, { ...preserved, slug, displayName, ...(joinToken ? { joinToken } : {}) });
     log(`✓ ${node_path_1.default.relative(top, projFile)}${joinToken ? ' (incl. join token — private repos only)' : ''}`);
     // 4. .gitignore guard
     ensureGitignoreGuard(top);

package/dist/commands/join.js

@@ -26,7 +26,7 @@ async function join(opts) {
     const token = opts.token || process.env.CONVENE_JOIN_TOKEN || proj?.joinToken;
     if (!token)
         (0, ctx_1.die)('no join token — pass --token <cvj_…>, set CONVENE_JOIN_TOKEN, or ask an owner for one');
-    const cfg = (0, config_1.resolveConfig)();
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj); // redeem against the pinned bus unless --base-url overrides
     const baseUrl = (opts.baseUrl || cfg.baseUrl).replace(/\/$/, '');
     const handle = opts.handle || (0, git_1.deriveHandle)(top ?? undefined);
     const email = opts.email || (0, git_1.gitUserEmail)(top ?? undefined) || undefined;

package/dist/commands/notify.js

@@ -21,6 +21,7 @@ exports.notifyPush = notifyPush;
 const config_1 = require("../config");
 const git_1 = require("../git");
 const api_1 = require("../api");
+const cache_1 = require("../cache");
 const exit_1 = require("../exit");
 const isZero = (sha) => /^0+$/.test(sha);
 /** Parse git's pre-push stdin into the non-deletion refs being pushed. */
@@ -109,10 +110,11 @@ function readStdin(timeoutMs) {
     });
 }
 async function run(opts) {
-    const cfg = (0, config_1.resolveConfig)();
     const top = (0, git_1.gitToplevel)();
+    const proj = (0, config_1.loadProjectConfig)(top);
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj); // honor a committed host pin for the push notify
     const cwd = top || process.cwd();
-    const slug = opts.project || (0, config_1.loadProjectConfig)(top)?.slug || null;
+    const slug = opts.project || proj?.slug || null;
     if (!slug)
         return; // not a bus repo — silent no-op, exactly like `convene fetch`
     const stdin = await readStdin(1500);
@@ -142,8 +144,14 @@ async function run(opts) {
     const session = top ? (0, git_1.sessionId)(cfg.member, top) : `${cfg.member}/cli`;
     const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool);
     const res = await api.post(slug, { type: 'status', body }, idem, 4000);
-    if (res.ok && res.json?.message?.short_id) {
-        process.stdout.write(`convene: posted [STATUS] ${res.json.message.short_id} — ${body}\n`);
+    if (res.ok) {
+        // Advance the shared broadcast cursor to the pushed tip so a turn-end `convene
+        // wrap` (Stop hook) doesn't double-post a "wrapped" status for the same commit
+        // the bus just heard about via this push.
+        (0, cache_1.writeLastBroadcastSha)(slug, refs[0].localSha);
+        if (res.json?.message?.short_id) {
+            process.stdout.write(`convene: posted [STATUS] ${res.json.message.short_id} — ${body}\n`);
+        }
     }
 }
 async function notifyPush(opts) {

package/dist/commands/offboard.js

@@ -466,7 +466,7 @@ async function offboard(opts) {
     if (!opts.yes && !dryRun && !process.stdout.isTTY) {
         (0, ctx_1.die)('refusing to off-board non-interactively without confirmation — re-run with `--yes` to confirm removing Convene from THIS repo.');
     }
-    const cfg = (0, config_1.resolveConfig)();
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj); // revoke against the bound bus, not a stale ambient host
     const baseUrl = cfg.baseUrl;
     const slug = proj.slug;
     // 1. Optional server-side token revoke FIRST (before deleting local files, so a
@@ -486,6 +486,31 @@ async function offboard(opts) {
                 : `⚠ could not revoke the join token (${r.error}) — it is owner-only; revoke from the dashboard if needed.`);
         }
     }
+    // 1.5 Optional owner hard-delete of the project server-side (--delete-project). This
+    //     PERMANENTLY removes the project + ALL its messages for EVERY member (owner-only,
+    //     typed confirm = the slug itself). Warn (don't fail) on 403/error, then continue
+    //     with the local off-board — the reversible default is to leave the project intact.
+    if (opts.deleteProject) {
+        if (dryRun) {
+            log(`· would PERMANENTLY delete the project "${slug}" server-side (--delete-project).`);
+        }
+        else if (!cfg.apiKey) {
+            log('⚠ --delete-project: not logged in; skipping the server-side delete.');
+        }
+        else {
+            const api = new api_1.ConveneApi(baseUrl, cfg.apiKey, cfg.member ? (0, git_1.sessionId)(cfg.member, top) : null, cfg.tool);
+            const r = await api.deleteProjectOwner(slug, slug, 8000);
+            if (r.ok) {
+                log(`✓ PERMANENTLY deleted the project "${slug}" server-side (all members + messages; slug tombstoned).`);
+            }
+            else if (r.status === 403) {
+                log(`⚠ --delete-project: only an owner can delete "${slug}" — left it intact; off-boarding locally only.`);
+            }
+            else {
+                log(`⚠ --delete-project: could not delete "${slug}" (${r.error}) — left it intact; off-boarding locally only.`);
+            }
+        }
+    }
     // 2. Local footprint removal.
     const touched = [];
     // Read the adopted-practices manifest BEFORE any deletion — delPath('.convene')
@@ -557,4 +582,13 @@ async function offboard(opts) {
         log('The shared `convene fetch` hook was kept so your OTHER Convene repos keep working — re-run');
         log('with `--remove-global` if this was your last Convene repo and you want the machine fully clean.');
     }
+    // Reclaim guidance: unless the project was just deleted, off-board is LOCAL-ONLY — the
+    // project + your membership still exist server-side. This is the clarity that the
+    // orphaned-off-board incident lacked (people assumed off-board tore down the server side).
+    if (!opts.deleteProject) {
+        log('');
+        log(`Server-side, the project "${slug}" and your membership are untouched — off-board removed Convene`);
+        log('from THIS checkout only. To reconnect later: restore .convene/project.json from git history, then');
+        log('run `convene reclaim` (re-grants your membership via the committed token).');
+    }
 }

package/dist/commands/override.js

@@ -43,7 +43,7 @@ async function override(id, opts = {}) {
     const tok = (0, cache_1.writeOverrideToken)(slug, id, reason);
     // 2) Best-effort attributed [STATUS] to the bus. FAIL-OPEN: a bus failure warns
     //    but never blocks — the local token already stands.
-    const cfg = (0, config_1.resolveConfig)();
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj);
     const member = cfg.member;
     const session = member && top ? (0, git_1.sessionId)(member, top) : null;
     let posted = false;

package/dist/commands/reclaim.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reclaim = reclaim;
+/**
+ * `convene reclaim` — self-recovery for an owner/member locked out of a project they
+ * can still READ (they hold the committed cvj_ token in .convene/project.json). It
+ * re-grants your own membership server-side. Like `join`, the committed token proves
+ * "can read the repo" and grants MEMBER only; OWNER is restored ONLY when the server
+ * has a recorded prior-owner row for you (your membership was soft-removed, not erased).
+ *
+ * This is the recurrence-fix for the orphaned-off-board incident: a returning owner no
+ * longer dead-ends on a 403, they run `convene reclaim`. If only `member` comes back,
+ * an owner/superadmin must promote you (the dashboard repair path).
+ */
+const brand_1 = require("../brand");
+const api_1 = require("../api");
+const config_1 = require("../config");
+const git_1 = require("../git");
+const hook_1 = require("../hook");
+const githook_1 = require("../githook");
+const ctx_1 = require("../ctx");
+const log = (m) => process.stdout.write(m + '\n');
+async function reclaim(opts) {
+    const top = (0, git_1.gitToplevel)();
+    const proj = (0, config_1.loadProjectConfig)(top);
+    const slug = opts.slug || proj?.slug;
+    if (!slug)
+        (0, ctx_1.die)('no project — run inside a `convene init`-ed repo, or pass --slug <slug>');
+    const token = opts.token || process.env.CONVENE_JOIN_TOKEN || proj?.joinToken;
+    if (!token) {
+        (0, ctx_1.die)('no join token — reclaim needs the committed token from .convene/project.json (restore it from git history if off-board removed it), or pass --token <cvj_…>');
+    }
+    const cfg = (0, config_1.resolveConfig)();
+    const baseUrl = (opts.baseUrl || cfg.baseUrl).replace(/\/$/, '');
+    const handle = opts.handle || (0, git_1.deriveHandle)(top ?? undefined);
+    const email = opts.email || (0, git_1.gitUserEmail)(top ?? undefined) || undefined;
+    // Authenticated mode if we already have a key (re-grants the existing identity, and
+    // can restore owner from a prior-owner row); unauthenticated mints a fresh identity
+    // (member only — a new identity has no prior-owner row to match).
+    const api = new api_1.ConveneApi(baseUrl, cfg.apiKey ?? null);
+    const res = await api.reclaim(slug, { token, handle, email, display_name: handle, tool: 'cli' }, 10_000);
+    if (res.status === 409 && res.json?.code === 'SLUG_REBOUND') {
+        (0, ctx_1.die)('this token predates the current project at this slug — a different project now owns it. Ask a superadmin to repair, or re-onboard with `convene init`.');
+    }
+    if (res.status === 409)
+        (0, ctx_1.die)(`the handle "${handle}" is already taken — re-run with --handle <unique-handle>, or \`convene login\` with your existing key first`);
+    if (res.status === 401)
+        (0, ctx_1.die)('the committed join token is invalid, expired, or revoked — ask an owner/superadmin for a fresh one (or use the dashboard repair path).');
+    if (!res.ok && res.status !== 200)
+        (0, ctx_1.die)(`reclaim failed (${res.status}): ${res.error ?? 'unknown error'}`);
+    const memberHandle = res.json?.member?.handle ?? handle;
+    const grantedRole = res.json?.project?.role ?? 'member';
+    const ownerRestored = res.json?.owner_restored === true;
+    if (res.json?.api_key) {
+        (0, config_1.saveFileConfig)({ apiKey: res.json.api_key, baseUrl, member: memberHandle });
+        log(`Reclaimed "${slug}" as ${memberHandle} (new identity, role: ${grantedRole}). Logged in (config 0600).`);
+    }
+    else if (res.json?.already) {
+        log(`Already an active member of "${slug}" as ${memberHandle} (role: ${grantedRole}). Nothing to reclaim.`);
+    }
+    else {
+        log(`Reclaimed "${slug}" as ${memberHandle} (role: ${grantedRole}).`);
+    }
+    if (ownerRestored) {
+        log('✓ Owner restored — the server had a recorded prior-owner row for you.');
+    }
+    else if (grantedRole !== 'owner') {
+        log('You were re-granted MEMBER. If you should be an owner, ask an existing owner or a');
+        log('superadmin to promote you (superadmin dashboard → project → "Make owner").');
+    }
+    // Same hook re-registration tail as `join`, so the recovered checkout is fully wired.
+    const hook = (0, hook_1.ensureHookRegistered)();
+    log(hook === 'registered'
+        ? 'Registered the convene fetch hook in ~/.claude/settings.json.'
+        : hook === 'already'
+            ? 'Hook already registered.'
+            : 'Could not auto-register the hook — run `convene doctor --fix` or add it manually.');
+    if (top) {
+        const pr = (0, hook_1.ensureProjectHookRegistered)(top);
+        if (pr === 'registered')
+            log('Wrote committed project hook (.claude/settings.json) — commit it so teammates auto-connect.');
+        const gh = (0, githook_1.installGitHooks)(top);
+        if (gh.status === 'installed' || gh.status === 'updated') {
+            log('Installed the git pre-push hook (.githooks/pre-push) — pushes auto-post a [STATUS].');
+        }
+    }
+    log(`You are operational on ${brand_1.BRAND.product}. Try: convene whoami`);
+}

package/dist/commands/rotate.js

@@ -21,10 +21,10 @@ async function rotateJoinToken(opts) {
     const top = (0, git_1.gitToplevel)();
     if (!top)
         (0, ctx_1.die)('not a git repository — run inside a repo');
-    const cfg = (0, config_1.resolveConfig)();
+    const existing = (0, config_1.loadProjectConfig)(top);
+    const cfg = (0, config_1.resolveConfigForRepo)(top, existing); // mint/revoke against the pinned bus
     if (!cfg.apiKey)
         (0, ctx_1.die)('not logged in — run `convene login`');
-    const existing = (0, config_1.loadProjectConfig)(top);
     const slug = opts.slug || existing?.slug;
     if (!slug)
         (0, ctx_1.die)('no project — run from a repo with .convene/project.json, or pass --slug');
@@ -39,8 +39,15 @@ async function rotateJoinToken(opts) {
     if (!minted.ok || !minted.json?.join_token)
         (0, ctx_1.die)(`could not mint a new join token: ${minted.error}`);
     const newToken = minted.json.join_token;
-    // 2. write project.json (so we never lose a working token even if revoke fails)
+    // 2. write project.json (so we never lose a working token even if revoke fails).
+    //    Preserve every OTHER committed field (bestPractices manifest, host-pin
+    //    binding, …) — only the token changes here. Strip the stale `schema` so
+    //    writeProjectConfig re-derives it (round-trip-safe; same discipline as
+    //    writeManifest/writeBinding). Without this, rotating the token would silently
+    //    un-pin the repo and drop its adopted practices.
+    const { schema: _schema, ...rest } = existing ?? {};
     const projFile = (0, config_1.writeProjectConfig)(top, {
+        ...rest,
         slug: slug,
         displayName: existing?.displayName || slug,
         joinToken: newToken,

package/dist/commands/session-start.js

@@ -22,6 +22,7 @@ exports.sessionStart = sessionStart;
 const node_child_process_1 = require("node:child_process");
 const git_1 = require("../git");
 const config_1 = require("../config");
+const binding_local_1 = require("../binding-local");
 const cache_1 = require("../cache");
 const worktree_1 = require("./worktree");
 const api_1 = require("../api");
@@ -123,7 +124,14 @@ async function run(opts) {
     if (!proj?.slug)
         return; // not on the bus → silent no-op
     const slug = proj.slug;
-    const cfg = (0, config_1.resolveConfig)();
+    // Host-pin drift banner — LOCAL ONLY, emitted BEFORE the network call so it
+    // survives an offline/DEGRADED boot (where the catch-up block is suppressed) and
+    // never adds boot latency. Fail-open: localBindingDrift returns null on no binding
+    // or any error, and the whole run() is inside sessionStart's try/catch + watchdog.
+    const drift = (0, binding_local_1.localBindingDrift)(top, proj);
+    if (drift)
+        emit(drift);
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj);
     if (!cfg.apiKey || !cfg.member)
         return; // not authenticated → silent (fail-open)
     const member = cfg.member;

package/dist/commands/update.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.update = update;
 exports.runUpdate = runUpdate;
@@ -24,6 +27,8 @@ exports.runUpdate = runUpdate;
  * Fail-soft throughout: offline → bundled catalog; a malformed manifest or any
  * unexpected error prints a clear note and exits non-fatally for the dry run.
  */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
 const config_1 = require("../config");
 const git_1 = require("../git");
 const api_1 = require("../api");
@@ -31,6 +36,10 @@ const catalog_1 = require("../catalog");
 const report_1 = require("../catalog/report");
 const manifest_1 = require("../catalog/manifest");
 const materialize_1 = require("../catalog/materialize");
+const init_1 = require("./init");
+const hook_1 = require("../hook");
+const binding_1 = require("../binding");
+const version_1 = require("../version");
 const ctx_1 = require("../ctx");
 const log = (m) => process.stdout.write(m + '\n');
 /** A practice has an actual bump available to take (patch/minor/major). */
@@ -69,18 +78,198 @@ async function update(opts = {}) {
     const top = (0, git_1.gitToplevel)();
     if (!top)
         (0, ctx_1.die)('not a git repository — run `convene update` inside a repo');
+    // Host-pin / freshness binding paths (`--refresh` / `--host`) are INDEPENDENT of
+    // the best-practices catalog — they re-render the managed surfaces + (re)write the
+    // schema-3 binding stamp, and must work even on a repo that adopted no practices.
+    // Route them before the manifest gate; the default + `--apply` keep the existing
+    // catalog-update flow unchanged.
+    if (opts.refresh || opts.host) {
+        return runBindingRefresh(top, opts);
+    }
     const manifest = (0, config_1.loadManifest)(top);
     if (!manifest) {
         log('· no best practices adopted — nothing to update. Run `convene init` to choose some.');
         return;
     }
     // Live catalog (fail-soft → bundled). Build an authed client only if we have a
-    // key; loadCatalog itself falls back on any failure, so this never blocks.
-    const cfg = (0, config_1.resolveConfig)();
+    // key; loadCatalog itself falls back on any failure, so this never blocks. Honor a
+    // committed host pin so the catalog fetch + adoption report hit the bound bus.
+    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);
     await runUpdate(top, manifest, catalog, source, opts);
 }
+/**
+ * `convene update --refresh` / `--host <url>` — the deliberate host-pin / freshness
+ * actions. Re-render the managed surfaces (CLAUDE.md/AGENTS.md coordination blocks,
+ * cross-agent rules, all four MCP carriers) at the AUTHORITATIVE host, re-wire the
+ * `convene fetch` hook (committed + global), recompute the committed-hook
+ * fingerprint, and WRITE the schema-3 binding stamp. This is the ONLY path that
+ * stamps a binding — `init` never does (it would break the byte-identical schema-1
+ * onboarding), and `doctor` never does (it is read-only w.r.t. the binding).
+ *
+ * Rails (same discipline as init/refresh-docs): `--check` is a dry run that writes
+ * NOTHING; without `--commit` the changes land in the working tree only (never
+ * `git add -A`); with `--commit` exactly the CONVENE_PATHS land as one isolated
+ * commit. `--host` additionally VERIFIES the target via GET /me before stamping
+ * (must-fix A: a typed host that the server does not self-identify as is refused),
+ * and moves the global config baseUrl so the CLI and the carriers cannot drift.
+ */
+/** The four committable MCP carriers a re-point must keep in sync (see init.ts). */
+const MCP_CARRIERS = ['.cursor/mcp.json', '.vscode/mcp.json', '.gemini/settings.json', '.codex/config.toml'];
+/**
+ * After a refresh/re-point, warn about any MCP carrier whose embedded
+ * CONVENE_BASE_URL no longer matches the bound host — an unparseable carrier that
+ * was silently skipped, or a carrier deliberately not touched under --no-mcp.
+ * Advisory only (never throws / never fails the command); a carrier with no convene
+ * entry, or absent entirely, is not flagged. Matches the JSON (`"CONVENE_BASE_URL":
+ * "…"`) and TOML (`CONVENE_BASE_URL = "…"`) forms with one regex.
+ */
+function warnStaleCarriers(top, host) {
+    const want = (0, binding_1.normalizeHost)(host);
+    const stale = [];
+    for (const rel of MCP_CARRIERS) {
+        let body;
+        try {
+            body = node_fs_1.default.readFileSync(node_path_1.default.join(top, rel), 'utf8');
+        }
+        catch {
+            continue; // carrier absent — nothing to keep in sync
+        }
+        const m = body.match(/CONVENE_BASE_URL"?\s*[:=]\s*"([^"]+)"/);
+        if (!m)
+            continue; // present but carries no convene server entry
+        if ((0, binding_1.normalizeHost)(m[1]) !== want)
+            stale.push(`${rel} → ${m[1]}`);
+    }
+    if (stale.length) {
+        log(`⚠ ${stale.length} MCP carrier(s) still point elsewhere — re-run \`convene update --refresh\` ` +
+            `(without --no-mcp) to fix: ${stale.join(', ')}`);
+    }
+}
+async function runBindingRefresh(top, opts) {
+    const existing = (0, config_1.loadProjectConfig)(top);
+    if (!existing?.slug) {
+        (0, ctx_1.die)('this repo is not on Convene yet — run `convene setup` first; `convene update --refresh` only re-stamps an already-onboarded repo.');
+    }
+    const slug = existing.slug;
+    const repoCfg = (0, config_1.resolveConfigForRepo)(top, existing);
+    const member = repoCfg.member;
+    if (!member)
+        (0, ctx_1.die)('not configured — run `convene login` first (a binding records who stamped it).');
+    // ── Resolve the target host + (best-effort / required) server confirmation ──
+    let host;
+    let serverVerified = false;
+    let serverHost = null;
+    let deploymentId;
+    if (opts.host) {
+        // --host re-point: REFUSE to stamp unless the target self-identifies as itself.
+        host = (0, binding_1.normalizeHost)(opts.host);
+        const api = new api_1.ConveneApi(host, repoCfg.apiKey, (0, git_1.sessionId)(member, top), repoCfg.tool);
+        const me = await api.me(8000);
+        if (!me.ok || !me.json) {
+            (0, ctx_1.die)(`cannot reach ${host} to verify it (${me.status}: ${me.error ?? 'unreachable'}) — refusing to re-point.`);
+        }
+        serverHost = me.json.canonical_host ? (0, binding_1.normalizeHost)(me.json.canonical_host) : null;
+        deploymentId = me.json.deployment_id;
+        if (serverHost) {
+            if (serverHost !== host) {
+                (0, ctx_1.die)(`refusing to pin: ${host} self-identifies as canonical host ${serverHost}, not ${host} ` +
+                    `(it may be a front-door/redirect). Pin to ${serverHost} instead, or check the URL.`);
+            }
+            serverVerified = true;
+        }
+        else if (!opts.yes) {
+            (0, ctx_1.die)(`the server at ${host} does not report a canonical host (older server) — cannot verify it is the bus you intend.\n` +
+                `  server says: member=${me.json.member} org_id=${me.json.org_id} kind=${me.json.kind}\n` +
+                `  re-run with --yes to pin anyway.`);
+        }
+        else {
+            log(`⚠ ${host} did not self-identify (older server); pinning anyway per --yes ` +
+                `(member=${me.json.member} org_id=${me.json.org_id} kind=${me.json.kind}).`);
+        }
+    }
+    else {
+        // --refresh: re-stamp the host the repo already resolves to (pin if pinned, else
+        // ambient). Server confirmation is best-effort + NON-fatal here.
+        host = (0, binding_1.normalizeHost)(repoCfg.baseUrl);
+        if (repoCfg.apiKey) {
+            const api = new api_1.ConveneApi(host, repoCfg.apiKey, (0, git_1.sessionId)(member, top), repoCfg.tool);
+            const me = await api.me(8000);
+            if (me.ok && me.json) {
+                serverHost = me.json.canonical_host ? (0, binding_1.normalizeHost)(me.json.canonical_host) : null;
+                deploymentId = me.json.deployment_id;
+                if (serverHost && serverHost === host)
+                    serverVerified = true;
+                else if (serverHost && serverHost !== host) {
+                    log(`⚠ the server at ${host} self-identifies as ${serverHost} — stamping ${host} (what this repo talks to); \`convene doctor\` will flag the divergence.`);
+                }
+            }
+        }
+    }
+    const skipAgentRules = opts.noAgentRules === true || opts.agentRules === false;
+    const skipMcp = opts.noMcp === true || opts.mcp === false;
+    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}`);
+        if (!skipAgentRules)
+            log('  • re-render the cross-agent rule files');
+        if (!skipMcp)
+            log(`  • re-render all MCP carriers with CONVENE_BASE_URL=${host}`);
+        log('  • ensure the committed + global `convene fetch` hook');
+        if (opts.host)
+            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)');
+        log('');
+        log('Nothing written (--check). Re-run without --check to apply.');
+        return;
+    }
+    log(`${opts.host ? 'Re-pointing' : 'Refreshing'} Convene binding for "${slug}" at ${host}…`);
+    (0, init_1.writeCoordinationBlocks)(top, slug, member, host);
+    if (!skipAgentRules)
+        (0, init_1.writeAgentRules)(top, slug, member, host);
+    if (!skipMcp)
+        (0, init_1.writeMcpConfigs)(top, host);
+    // Re-wire the `convene fetch` hook in BOTH the committed repo settings (in
+    // CONVENE_PATHS — its fingerprint is stamped) and the per-machine global settings
+    // (advisory; never committed). Both idempotent.
+    (0, hook_1.ensureProjectHookRegistered)(top);
+    (0, hook_1.ensureHook)('UserPromptSubmit', hook_1.HOOK_COMMAND);
+    // Recompute the committed-hook fingerprint AFTER wiring so the stamp matches disk.
+    const hookFingerprint = (0, hook_1.conveneHookFingerprint)((0, hook_1.parseSettings)((0, hook_1.readSettingsRaw)((0, hook_1.projectSettingsPath)(top))));
+    const binding = {
+        host,
+        cliVersion: (0, version_1.cliVersion)(),
+        hookFingerprint,
+        stampedAt: new Date().toISOString(),
+        stampedBy: member,
+        serverVerified,
+        ...(existing.bestPractices?.catalogVersion ? { catalogVersion: existing.bestPractices.catalogVersion } : {}),
+        ...(deploymentId && deploymentId !== 'unknown' ? { deploymentId } : {}),
+    };
+    (0, config_1.writeBinding)(top, binding);
+    // A --host re-point moves the global config baseUrl too, or the CLI (which reads
+    // file.baseUrl) and the carriers diverge. Do it LAST — after the stamp + carriers
+    // have all been written — so a mid-sequence failure never leaves the global config
+    // pointed at <new> with the repo still UNPINNED (stamp-then-move keeps the pin the
+    // single authority).
+    if (opts.host)
+        (0, config_1.saveFileConfig)({ baseUrl: host });
+    log(`✓ .convene/project.json binding stamped — host ${host}, CLI v${binding.cliVersion}${serverVerified ? ', server-confirmed' : ''}.`);
+    // Carrier consistency: warn (do NOT fail) about any MCP carrier still pointing
+    // elsewhere — covers a carrier skipped because its JSON was unparseable, and the
+    // --no-mcp case where carriers were deliberately not touched. No freshness check
+    // reads a carrier's host, so without this a stale carrier would be silent.
+    warnStaleCarriers(top, host);
+    if (opts.commit) {
+        (0, init_1.commitConveneFiles)(top, opts.host ? `Re-point Convene to ${host}` : 'Refresh Convene binding to current template', opts.host ? 'the re-point' : 'the binding refresh');
+    }
+    else {
+        log('');
+        log('Changes are in your working tree only. Review with `git diff` and commit yourself (or re-run with `--commit`).');
+    }
+}
 /**
  * Core of `convene update`, with the resolved (top, manifest, catalog) already in
  * hand — the seam tests drive with a synthetic catalog (no fs/network resolution).