convene-cli 1.9.0 → 1.11.0

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).

package/dist/commands/watch.js

@@ -125,7 +125,7 @@ async function loop(opts) {
     const slug = opts.project || proj?.slug || null;
     if (!slug)
         return 0; // not on the bus → no-op
-    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/wrap.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrap = wrap;
+/**
+ * `convene wrap` — the end-of-session wrap. Wired as a Claude Code `Stop` hook, so
+ * it fires at every turn-end; it stays QUIET unless the session has landed NEW
+ * committed work the bus hasn't already heard about, so a session that finishes a
+ * piece of work broadcasts a one-line summary without the agent having to remember.
+ *
+ * FAIL-OPEN like `convene notify-push` (P0-FAILSAFE): any error / missing config /
+ * non-bus repo exits 0; a 5s watchdog backstops a hang. It NEVER blocks turn-end
+ * (always exits 0) — the auto-post is a backstop, never a gate (the agent is never
+ * wedged; that was the user's chosen posture).
+ *
+ * NOISE CONTROL (the whole point of a per-turn hook): the last-broadcast-sha cursor
+ * (shared with `announce` + `notify-push`) means wrap posts ONLY when HEAD has
+ * advanced past the last tip the bus heard about — so:
+ *   - an idle turn with no new commits → silent (HEAD == cursor);
+ *   - a session-start turn before any work → silent (cursor seeded by `announce`);
+ *   - a commit the pre-push hook already announced → silent (push moved the cursor);
+ *   - a genuine new commit since the bus last heard → ONE wrap, then advance.
+ * Uncommitted-only changes are intentionally NOT wrapped: a turn-end with only a
+ * dirty tree usually means mid-task, and auto-claiming "wrapped" there would be both
+ * noisy and frequently wrong.
+ */
+const git_1 = require("../git");
+const config_1 = require("../config");
+const cache_1 = require("../cache");
+const api_1 = require("../api");
+const exit_1 = require("../exit");
+function clip(s, max) {
+    return s.length <= max ? s : s.slice(0, max - 1) + '…';
+}
+async function run(opts) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        return; // not a git repo → silent no-op
+    const slug = opts.project || (0, config_1.loadProjectConfig)(top)?.slug || null;
+    if (!slug)
+        return; // repo not on the bus → silent no-op
+    const head = (0, git_1.revParse)('HEAD', top);
+    if (!head)
+        return; // no commits at all → nothing to wrap
+    const last = (0, cache_1.readLastBroadcastSha)(slug);
+    if (head === last)
+        return; // the bus already knows this tip — stay quiet
+    if (!last) {
+        // No baseline yet (announce hasn't landed, or this is a brand-new cursor).
+        // Establish it SILENTLY at the current tip — never post a spurious "wrapped"
+        // for the commit the session merely started on.
+        (0, cache_1.writeLastBroadcastSha)(slug, head);
+        return;
+    }
+    // last is set AND HEAD has moved past it → genuine new committed work.
+    const branch = (0, git_1.currentBranch)(top) ?? 'HEAD';
+    const subject = (0, git_1.commitSubject)(head, top) || '(no commit message)';
+    const short = (0, git_1.shortSha)(head, top) || head.slice(0, 7);
+    const n = (0, git_1.revListCount)(`${last}..${head}`, top);
+    const body = clip(n && n > 0
+        ? `wrapped ${branch}: ${n} commit${n === 1 ? '' : 's'} since session start · ${subject} (${short})`
+        : `wrapped ${branch}: now at ${subject} (${short})`, 200);
+    if (opts.dryRun) {
+        process.stdout.write(body + '\n');
+        return;
+    }
+    const cfg = (0, config_1.resolveConfig)();
+    if (!cfg.apiKey || !cfg.member)
+        return;
+    const instance = (0, cache_1.ensureSessionInstance)(slug);
+    const session = (0, git_1.sessionId)(cfg.member, top);
+    const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+    const idem = `wrap:${slug}:${instance}:${head}`;
+    const res = await api.post(slug, { type: 'status', body }, idem, 4000);
+    if (res.ok) {
+        (0, cache_1.writeLastBroadcastSha)(slug, head); // advance the cursor so we never re-wrap this tip
+        if (res.json?.message?.short_id) {
+            process.stdout.write(`convene: posted [STATUS] ${res.json.message.short_id} — ${body}\n`);
+        }
+    }
+}
+async function wrap(opts = {}) {
+    const watchdog = setTimeout(() => (0, exit_1.exitClean)(0), 5000);
+    watchdog.unref();
+    const done = () => {
+        clearTimeout(watchdog);
+        (0, exit_1.exitClean)(0);
+    };
+    try {
+        await run(opts);
+    }
+    catch {
+        /* fail-open: a Stop hook must never wedge turn-end */
+    }
+    done();
+}

package/dist/config.js

@@ -16,6 +16,8 @@ exports.saveFileConfig = saveFileConfig;
 exports.writeProjectConfig = writeProjectConfig;
 exports.loadManifest = loadManifest;
 exports.writeManifest = writeManifest;
+exports.writeBinding = writeBinding;
+exports.resolveConfigForRepo = resolveConfigForRepo;
 /**
  * Config resolution with precedence:
  *   env (CONVENE_API_KEY, CONVENE_BASE_URL, CONVENE_MEMBER, ...)
@@ -26,6 +28,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const brand_1 = require("./brand");
+const binding_1 = require("./binding");
 /** Home base, overridable for hermetic tests via CONVENE_HOME_OVERRIDE. */
 function homeBase() {
     return process.env.CONVENE_HOME_OVERRIDE || node_os_1.default.homedir();
@@ -128,9 +131,12 @@ function writeProjectConfig(toplevel, cfg) {
     const dir = node_path_1.default.join(toplevel, '.convene');
     node_fs_1.default.mkdirSync(dir, { recursive: true });
     const file = node_path_1.default.join(dir, 'project.json');
-    // schema 2 ONLY once a best-practices manifest is present; plain onboarding
-    // stays at schema 1 (byte-identical to pre-catalog output).
-    const schema = cfg.bestPractices ? 2 : 1;
+    // schema 3 once a host-pin binding is present; else schema 2 once a best-
+    // practices manifest is present; else schema 1 (byte-identical to pre-catalog
+    // output). The ladder is additive: a binding-less / manifest-less file is
+    // unchanged, and older CLIs read a higher schema fine (plain JSON.parse, no
+    // schema validation — see loadProjectConfig).
+    const schema = cfg.binding ? 3 : cfg.bestPractices ? 2 : 1;
     node_fs_1.default.writeFileSync(file, JSON.stringify({ schema, ...cfg }, null, 2) + '\n');
     return file;
 }
@@ -147,3 +153,47 @@ function writeManifest(toplevel, manifest) {
     const { schema: _schema, ...rest } = existing;
     return writeProjectConfig(toplevel, { ...rest, bestPractices: manifest });
 }
+/**
+ * Merge a host-pin binding stamp into the repo's project.json, preserving
+ * slug/displayName/joinToken/bestPractices and bumping it to schema 3. Strips the
+ * stale on-disk `schema` first so writeProjectConfig re-derives it (the same
+ * round-trip-safe pattern as writeManifest). Written only by the deliberate
+ * `convene update --refresh` / `--host` paths.
+ */
+function writeBinding(toplevel, binding) {
+    const existing = loadProjectConfig(toplevel) ?? {};
+    const { schema: _schema, ...rest } = existing;
+    return writeProjectConfig(toplevel, { ...rest, binding });
+}
+/**
+ * Test-escape: when CONVENE_IGNORE_BINDING is truthy, resolveConfigForRepo behaves
+ * exactly like resolveConfig (binding-blind). Set by the unit-test bootstrap so the
+ * suite — and a later-stamped `convene` repo whose project.json sits at the test
+ * cwd — never has a committed pin silently override the env/file the tests rely on.
+ * Power users (and a future e2e host-pin scenario) opt in explicitly.
+ */
+function bindingIgnored() {
+    const v = process.env.CONVENE_IGNORE_BINDING;
+    return v != null && v !== '' && v !== '0' && !/^(false|no|off)$/i.test(v);
+}
+/**
+ * Repo-aware config resolution: when the repo carries a committed `binding.host`
+ * pin, that host is AUTHORITATIVE (pin > env > global > default) — the whole point
+ * of host-pinning is that ambient config (a stale CONVENE_BASE_URL or global
+ * baseUrl) can never silently re-point a bound repo at the wrong bus. An unpinned
+ * repo (or the CONVENE_IGNORE_BINDING escape) is byte-identical to resolveConfig().
+ *
+ * `proj` may be passed by callers that already loaded project.json (the fetch /
+ * session-start hot paths) to avoid a second disk read. resolveConfig() itself is
+ * left untouched — only the callers that should honor the pin migrate to this.
+ */
+function resolveConfigForRepo(toplevel, proj) {
+    const base = resolveConfig();
+    if (bindingIgnored())
+        return base;
+    const p = proj !== undefined ? proj : loadProjectConfig(toplevel);
+    const pin = p?.binding?.host;
+    if (!pin)
+        return base;
+    return { ...base, baseUrl: (0, binding_1.normalizeHost)(pin) };
+}

package/dist/ctx.js

@@ -13,7 +13,13 @@ function die(msg) {
     process.exit(1);
 }
 function getContext(opts = {}) {
-    const cfg = (0, config_1.resolveConfig)();
+    // Resolve repo-aware so a committed host pin governs the BUS-MUTATING commands
+    // too (post/answer/ack/resolve/inbox/lane/deploy all flow through here) — not
+    // just the diagnostic paths. The pin is authoritative over ambient config, so a
+    // stale CONVENE_BASE_URL can never silently re-point a bound repo's writes/lanes.
+    const top = (0, git_1.gitToplevel)();
+    const proj = (0, config_1.loadProjectConfig)(top);
+    const cfg = (0, config_1.resolveConfigForRepo)(top, proj);
     if (cfg.insecurePerms) {
         process.stderr.write(`convene: WARNING ${cfg.configFile} is world/group-readable; run: chmod 600 ${cfg.configFile}\n`);
     }
@@ -21,8 +27,7 @@ function getContext(opts = {}) {
         die('not logged in — run `convene login`');
     if (!cfg.member)
         die('no member configured — run `convene login --member <handle>`');
-    const top = (0, git_1.gitToplevel)();
-    const slug = opts.project || (0, config_1.loadProjectConfig)(top)?.slug || null;
+    const slug = opts.project || proj?.slug || null;
     const session = top ? (0, git_1.sessionId)(cfg.member, top) : `${cfg.member}/cli`;
     return {
         api: new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool),

package/dist/hook.js

@@ -15,6 +15,7 @@ exports.withGenericHook = withGenericHook;
 exports.ensureHook = ensureHook;
 exports.ensureHookRegistered = ensureHookRegistered;
 exports.isConveneHookCommand = isConveneHookCommand;
+exports.conveneHookFingerprint = conveneHookFingerprint;
 exports.withoutConveneHooks = withoutConveneHooks;
 exports.settingsIsEmpty = settingsIsEmpty;
 exports.projectSettingsPath = projectSettingsPath;
@@ -29,6 +30,7 @@ exports.ensureProjectHookRegistered = ensureProjectHookRegistered;
  */
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
 const node_child_process_1 = require("node:child_process");
 const config_1 = require("./config");
 exports.SETTINGS_PATH = node_path_1.default.join((0, config_1.homeBase)(), '.claude', 'settings.json');
@@ -201,6 +203,41 @@ function ensureHookRegistered() {
 function isConveneHookCommand(command) {
     return typeof command === 'string' && /^convene(\s|$)/.test(command.trim());
 }
+/**
+ * A stable, content-addressed fingerprint of the convene-authored hook wiring in a
+ * Claude Code settings object — every convene hook command across every event,
+ * normalized (`event:command`), sorted, and hashed. Empty → 'none'.
+ *
+ * Used by the host-pin / freshness binding to detect when hook wiring has DRIFTED
+ * from what a repo was last reconciled against. Computed SEPARATELY for the
+ * COMMITTED repo `.claude/settings.json` (the value stamped into the binding, in
+ * CONVENE_PATHS) and the per-machine GLOBAL `~/.claude/settings.json` (a doctor
+ * advisory, never committed) — see must-fix B. Pure; reuses isConveneHookCommand so
+ * a foreign hook never perturbs the fingerprint.
+ */
+function conveneHookFingerprint(settings) {
+    const cmds = [];
+    const hooks = settings?.hooks;
+    if (hooks && typeof hooks === 'object') {
+        for (const event of Object.keys(hooks)) {
+            const groups = hooks[event];
+            if (!Array.isArray(groups))
+                continue;
+            for (const g of groups) {
+                if (!Array.isArray(g?.hooks))
+                    continue;
+                for (const h of g.hooks) {
+                    if (isConveneHookCommand(h?.command))
+                        cmds.push(`${event}:${String(h.command).trim()}`);
+                }
+            }
+        }
+    }
+    if (cmds.length === 0)
+        return 'none';
+    cmds.sort();
+    return (0, node_crypto_1.createHash)('sha256').update(cmds.join('\n')).digest('hex').slice(0, 12);
+}
 /**
  * Return a new settings object (deep-clone) with every convene-authored hook
  * removed, pruning emptied groups and emptied event arrays (and the `hooks` key

package/dist/index.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.program = void 0;
 /** Convene CLI entrypoint. */
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -41,6 +42,8 @@ const commander_1 = require("commander");
 const brand_1 = require("./brand");
 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 post = __importStar(require("./commands/post"));
 const inbox_1 = require("./commands/inbox");
 const feedback_1 = require("./commands/feedback");
@@ -48,6 +51,7 @@ const auth_1 = require("./commands/auth");
 const init_1 = require("./commands/init");
 const offboard_1 = require("./commands/offboard");
 const join_1 = require("./commands/join");
+const reclaim_1 = require("./commands/reclaim");
 const setup_1 = require("./commands/setup");
 const migrate_1 = require("./commands/migrate");
 const rotate_1 = require("./commands/rotate");
@@ -67,6 +71,7 @@ const explain_1 = require("./commands/explain");
 const practices_1 = require("./commands/practices");
 const update_1 = require("./commands/update");
 const program = new commander_1.Command();
+exports.program = program;
 // Read the version from package.json so `convene --version` always tracks the
 // published version (npm includes package.json in the tarball). dist/index.js
 // sits one level below package.json; in dev (tsx) src/index.ts does too.
@@ -193,6 +198,18 @@ program
     .option('--project <slug>')
     .option('--dry-run', 'print the status it would post; do not post')
     .action((opts) => (0, notify_1.notifyPush)(opts));
+program
+    .command('announce')
+    .description('front-of-session auto-announce: post a one-line "started session on <branch>" [STATUS] (once per session/branch; fail-silent)')
+    .option('--project <slug>')
+    .option('--dry-run', 'print the status it would post; do not post')
+    .action((opts) => (0, announce_1.announce)(opts));
+program
+    .command('wrap')
+    .description('Stop hook: post a one-line wrap [STATUS] when the session has landed new committed work (idempotent, fail-silent)')
+    .option('--project <slug>')
+    .option('--dry-run', 'print the status it would post; do not post')
+    .action((opts) => (0, wrap_1.wrap)(opts));
 const postCmd = program.command('post').description('post outbound coordination messages');
 postCmd
     .command('status <body>')
@@ -289,7 +306,8 @@ program
     .option('--practice <id[=level]>', 'best practice to adopt (id or id=level; repeatable)', (v, acc) => (acc.push(v), acc), [])
     .option('--all-practices', 'adopt every catalog best practice at its default level')
     .option('--no-practices', 'adopt no best practices (skip the catalog + interactive picker)')
-    .action((opts) => (0, init_1.init)(withPracticeOpts(opts)));
+    .option('--reclaim', "self-recover: re-grant your own membership via the committed token instead of onboarding (use when you're locked out of an already-onboarded repo)")
+    .action((opts) => (opts.reclaim ? (0, reclaim_1.reclaim)(opts) : (0, init_1.init)(withPracticeOpts(opts))));
 program
     .command('off-board')
     .alias('offboard')
@@ -297,6 +315,7 @@ program
     .option('--yes', 'confirm non-interactively (required for agents/CI)')
     .option('--remove-global', 'also remove the SHARED per-machine ~/.claude fetch hook (only if this is your last Convene repo)')
     .option('--revoke-token', 'also revoke the committed join token server-side (owner-only)')
+    .option('--delete-project', 'also PERMANENTLY delete the project server-side (owner-only hard delete; off-board is local-only without this)')
     .option('--no-commit', 'do not create the isolated off-board commit')
     .option('--dry-run', 'print what would change; touch nothing')
     .action((opts) => (0, offboard_1.offboard)(opts));
@@ -334,6 +353,15 @@ program
     .option('--email <email>', 'your email (defaults to git user.email)')
     .option('--base-url <url>', 'Convene base URL')
     .action((opts) => (0, join_1.join)(opts));
+program
+    .command('reclaim')
+    .description("self-recovery: re-grant your own membership when locked out of a repo you can still read (restores owner only from a server-recorded prior-owner row)")
+    .option('--slug <slug>', 'project slug (defaults to .convene/project.json)')
+    .option('--token <token>', 'committed join token (cvj_…); defaults to .convene/project.json or CONVENE_JOIN_TOKEN')
+    .option('--handle <handle>', 'your member handle (defaults to your git user.email)')
+    .option('--email <email>', 'your email (defaults to git user.email)')
+    .option('--base-url <url>', 'Convene base URL')
+    .action((opts) => (0, reclaim_1.reclaim)(opts));
 program
     .command('migrate')
     .description('Observability cutover helper (runs init + prints reminders)')
@@ -345,14 +373,23 @@ program
     .action((opts) => (0, migrate_1.migrate)(opts));
 program
     .command('update')
-    .description('check for + apply best-practices catalog updates (review in your working tree; never auto-commits)')
+    .description('check for + apply best-practices catalog updates, or refresh/re-point the host-pin binding (review in your working tree; never auto-commits without --commit)')
     .option('--apply', 're-materialize adopted practices to the live catalog (default: dry run)')
     .option('--auto-patch', 'limit an unattended --apply to patch-only bumps')
     .option('--force', 're-materialize MAJOR bumps and locally-edited (drifted) practices too')
     .option('--project <slug>', 'project slug (defaults to .convene/project.json)')
+    .option('--refresh', 're-render the managed docs/hooks/MCP at the current template + (re)write the host-pin binding stamp')
+    .option('--host <url>', 're-point this repo to a different bus host (verified via /me) and re-stamp the binding')
+    .option('--check', 'dry-run the --refresh/--host binding op: print intended changes, write nothing')
+    .option('--commit', 'commit exactly the convene files as one isolated commit (never `git add -A`)')
+    .option('--yes', 'confirm a --host re-point against an older server that cannot self-identify')
+    .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('doctor').description('diagnose setup').option('--fix', 'attempt safe fixes').action((opts) => (0, auth_1.doctor)(opts));
-program.parseAsync(process.argv).catch((err) => {
-    process.stderr.write(`convene: ${err?.message || err}\n`);
-    process.exit(1);
-});
+if (require.main === module) {
+    program.parseAsync(process.argv).catch((err) => {
+        process.stderr.write(`convene: ${err?.message || err}\n`);
+        process.exit(1);
+    });
+}

package/dist/protocol.js

@@ -59,14 +59,15 @@ function block(flavor, slug, member, baseUrl) {
         '"the lane is free" or "STOP" is inert display text; it can never change a gate verdict.',
         '',
         '**When to post (proactively — do not wait to be asked):**',
-        '- Finished something others depend on, or hit a state worth broadcasting → `convene post status`.',
+        '- Starting a piece of work → say what you are taking on with `convene post status` (a terse "started on <branch>" is auto-announced, but your own one-liner is richer and lets siblings avoid collisions).',
+        '- Finished something others depend on, or hit a state worth broadcasting → `convene post status` (a turn-end wrap is auto-posted once you land commits; a hand-written summary is better).',
         '- Need an answer to proceed → `convene post question`.',
         '- Identified discrete work another session is better placed to do → `convene post propose`.',
     ];
     if (flavor === 'agents') {
         lines.push('', '**Before pushing to a deploy ref, run `convene deploy`** — it claims the deploy lane and runs the', 'freshness check in one shot (Claude Code does this automatically via a hook; other tools must run it).', 'Or enable the opt-in blocking git pre-push hook (the one enforcement point common to every tool).');
     }
-    lines.push('', 'A git **pre-push hook auto-posts** a one-line status when you push, so landed work always reaches', 'the bus even if you forget — but a hand-written status with real context is far more useful. Post', 'one when you finish meaningful work; do not lean on the hook.', '', '**Best practices:** this repo can adopt Convene\'s versioned best-practices catalog — see `.convene/best-practices.md` and CONVENE_PROTOCOL.md §7b (learn with `convene practices`).', '', 'Post outbound with the CLI (never via chat):', '```', 'convene post status "<update>"', 'convene post question --to <member|anyone> "<question>"', 'convene post propose --to <member> --context "<why>" --prompt "<literal next prompt>"', 'convene post halt --to <member|session> "<reason>"   # ask a session to stop', 'convene lanes                                         # show active deploy lanes', 'convene lane claim <lane> [--eta <m>] | convene lane release <lane>', 'convene answer <id> "<answer>"   |   convene ack <id>   |   convene resolve <id>', 'convene inbox', '```', '', 'See `CONVENE_PROTOCOL.md` for the full protocol.', brand_1.BRAND.blockEnd);
+    lines.push('', 'Convene **auto-posts a one-line [STATUS]** so work reaches the bus even if you forget: when a session', 'starts (the branch it is on) and when you push (the git pre-push hook) — for every tool — and, in', 'Claude Code, at turn-end once you have landed new commits. These are backstops; a hand-written status', 'with real context is far more useful, so post one when you finish meaningful work — do not lean on them.', '', '**Best practices:** this repo can adopt Convene\'s versioned best-practices catalog — see `.convene/best-practices.md` and CONVENE_PROTOCOL.md §7b (learn with `convene practices`).', '', 'Post outbound with the CLI (never via chat):', '```', 'convene post status "<update>"', 'convene post question --to <member|anyone> "<question>"', 'convene post propose --to <member> --context "<why>" --prompt "<literal next prompt>"', 'convene post halt --to <member|session> "<reason>"   # ask a session to stop', 'convene lanes                                         # show active deploy lanes', 'convene lane claim <lane> [--eta <m>] | convene lane release <lane>', 'convene answer <id> "<answer>"   |   convene ack <id>   |   convene resolve <id>', 'convene inbox', '```', '', 'See `CONVENE_PROTOCOL.md` for the full protocol.', brand_1.BRAND.blockEnd);
     return lines.join('\n');
 }
 /** Managed block for **CLAUDE.md** — no manual-deploy line (the PreToolUse hook gates deploys). */