convene-cli 1.0.4 → 1.1.0

package/dist/commands/guard.js

@@ -0,0 +1,313 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyPushRefs = classifyPushRefs;
+exports.classifyCommand = classifyCommand;
+exports.commandFromPayload = commandFromPayload;
+exports.guard = guard;
+/**
+ * `convene guard` (WP9) — the PreToolUse halt+lane gate for Bash commands. Wired
+ * as a PreToolUse `Bash` hook (the WIRING is the WP13 capstone — this is the verb).
+ *
+ * POSTURE = FAIL-OPEN-LOUD (P0-FAILSAFE), exactly like fetch.ts/gate-push.ts:
+ *   - A top-level watchdog force-exits 0 at WATCHDOG_MS=4000.
+ *   - Network calls use an EXPLICIT short timeout (2500ms), never the 10s default.
+ *   - Transport failure / timeout / parse error / DEGRADED / no-bus → exit 0
+ *     (loud systemMessage on a contended bus, silent for a clean non-match).
+ *   - NEVER calls die(); NEVER routes through ctx.getContext() (which die()s on a
+ *     missing config) — it owns its own watchdog.
+ *
+ * ANCHORED command classifier (NOT bare substring): match only command-LEADING
+ * verbs — `git push`, `sls|cdk|serverless deploy`, `kubectl apply`,
+ * `helm upgrade`, `fly deploy`, `vercel --prod`, `gh release`, `npm publish`, and
+ * real `--force`/`-f` FLAGS. It MUST NOT match `grep -r deploy`, `rm -f x`, or a
+ * filename like `release.ts` (those are not command-leading deploy verbs).
+ *   - Non-match → exit 0 with ZERO network.
+ *   - Match → check open directed halts; for DEPLOY commands also check lane-state
+ *     (cached ~3s keyed (slug,intent)).
+ *
+ * exit 2 (BLOCK) ONLY on:
+ *   (a) an open DIRECTED HALT for this session (hard, for ANY matched command), OR
+ *   (b) a CONFIRMED held lane for a DEPLOY command (different instance).
+ * A SOFT held-lane conflict (foreign live lane, no directed halt) → 'ask'.
+ */
+const git_1 = require("../git");
+const config_1 = require("../config");
+const cache_1 = require("../cache");
+const api_1 = require("../api");
+const WATCHDOG_MS = 4000;
+const NET_TIMEOUT_MS = 2500; // explicit short timeout — NEVER the 10s default
+/**
+ * True iff a pushed REF is a deploy ref (the lane is per-target). Used by both
+ * `guard` (push classification) and `gate-push` to keep ONE classifier.
+ * Default deploy refs: refs/heads/main, refs/heads/master, any refs/tags/*.
+ */
+function classifyPushRefs(ref) {
+    const r = ref.trim();
+    if (r.startsWith('refs/tags/'))
+        return true;
+    const head = r.replace(/^refs\/heads\//, '');
+    return head === 'main' || head === 'master';
+}
+/** Split a token off any leading env-assignment / `command` / `exec` prefixes. */
+function leadingTokens(cmd) {
+    // Split on shell connectors so `foo && git push` classifies the `git push`.
+    const segments = cmd.split(/(?:&&|\|\||;|\||\n)/g);
+    const tokens = [];
+    for (const seg of segments) {
+        const words = seg.trim().split(/\s+/).filter(Boolean);
+        // Drop leading VAR=val assignments and a leading `sudo`/`command`/`exec`/`time`.
+        let i = 0;
+        while (i < words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]) || /^(sudo|command|exec|time|env)$/.test(words[i])))
+            i++;
+        if (i < words.length)
+            tokens.push(...words.slice(i));
+        tokens.push('\u0000'); // segment boundary marker
+    }
+    return tokens;
+}
+/**
+ * ANCHORED classifier. Matches command-LEADING verbs only. Never a bare
+ * substring of `deploy`/`release`/`-f` (so `grep -r deploy`, `rm -f x`,
+ * `cat release.ts` do NOT match).
+ */
+function classifyCommand(command) {
+    if (!command || !command.trim())
+        return { kind: 'none' };
+    // Walk each connector-split segment; classify on its FIRST word (the program).
+    const segments = command.split(/(?:&&|\|\||;|\||\n)/g);
+    for (const seg of segments) {
+        const words = seg.trim().split(/\s+/).filter(Boolean);
+        let i = 0;
+        while (i < words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]) || /^(sudo|command|exec|time|env)$/.test(words[i])))
+            i++;
+        const w = words.slice(i);
+        if (!w.length)
+            continue;
+        const prog = w[0];
+        const sub = w[1];
+        const rest = w.slice(1);
+        // git push <remote?> <refspec...> — extract candidate refs.
+        if (prog === 'git' && sub === 'push') {
+            const refs = [];
+            // refspecs are the non-flag args after `push` (skip the remote name heuristically).
+            const args = w.slice(2).filter((a) => !a.startsWith('-'));
+            // args[0] is usually the remote; the rest are refspecs. Normalize each.
+            for (let k = 0; k < args.length; k++) {
+                const a = args[k];
+                if (k === 0 && !a.includes(':') && !a.includes('/'))
+                    continue; // remote name
+                const local = a.includes(':') ? a.split(':')[0] : a;
+                if (!local)
+                    continue;
+                refs.push(local.startsWith('refs/') ? local : `refs/heads/${local}`);
+            }
+            return { kind: 'push', refs };
+        }
+        // Deploy/publish verbs (program + leading subcommand).
+        if ((prog === 'sls' || prog === 'serverless' || prog === 'cdk') && sub === 'deploy')
+            return { kind: 'deploy' };
+        if (prog === 'fly' && sub === 'deploy')
+            return { kind: 'deploy' };
+        if (prog === 'kubectl' && sub === 'apply')
+            return { kind: 'deploy' };
+        if (prog === 'helm' && sub === 'upgrade')
+            return { kind: 'deploy' };
+        if (prog === 'gh' && sub === 'release')
+            return { kind: 'deploy' };
+        if (prog === 'npm' && sub === 'publish')
+            return { kind: 'deploy' };
+        if (prog === 'vercel' && rest.includes('--prod'))
+            return { kind: 'deploy' };
+        // A real --force / -f FLAG on a mutating program (anchored as a flag token,
+        // never a bare substring). `rm -f` is excluded — it's a filesystem op, not a
+        // deploy/push. We only treat --force on push-like programs as deploy-adjacent.
+        const hasForceFlag = rest.some((a) => a === '--force' || /^-[a-eg-zA-Z]*f[a-eg-zA-Z]*$/.test(a) || a === '-f');
+        if (hasForceFlag && (prog === 'git' || prog === 'sls' || prog === 'serverless' || prog === 'cdk' || prog === 'helm')) {
+            return { kind: 'force' };
+        }
+    }
+    return { kind: 'none' };
+}
+/** Async, timeout-bounded stdin read (the PreToolUse payload is JSON). */
+function readStdin(timeoutMs) {
+    if (process.stdin.isTTY)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let data = '';
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            process.stdin.removeAllListeners();
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (c) => {
+            data += c;
+        });
+        process.stdin.on('end', () => finish(data));
+        process.stdin.on('error', () => finish(null));
+        process.stdin.resume();
+    });
+}
+/** Pull the Bash command string out of a PreToolUse hook payload. */
+function commandFromPayload(raw) {
+    if (!raw)
+        return '';
+    try {
+        const j = JSON.parse(raw);
+        const c = j?.tool_input?.command;
+        return typeof c === 'string' ? c : '';
+    }
+    catch {
+        return '';
+    }
+}
+function emitJson(obj) {
+    process.stdout.write(JSON.stringify(obj) + '\n');
+}
+function ask(reason) {
+    emitJson({
+        hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask', permissionDecisionReason: reason },
+    });
+}
+function loudOpen(systemMessage) {
+    emitJson({ systemMessage });
+}
+function blockReason(reason) {
+    process.stderr.write(reason + '\n');
+}
+function safeHandle(s) {
+    if (typeof s !== 'string')
+        return 'another session';
+    const cleaned = s.replace(/[^a-zA-Z0-9_.\-/]+/g, '').slice(0, 64);
+    return cleaned ? `@${cleaned}` : 'another session';
+}
+async function run(opts) {
+    const raw = opts.stdin ? await readStdin(1500) : null;
+    const command = commandFromPayload(raw);
+    const cls = classifyCommand(command);
+    // The DEFAULT path is the WP9 deploy gate: a NON-match exits 0 with ZERO
+    // network (the overwhelming common case). The HALT-ONLY path (the cheap `.*`
+    // matcher, wired in WP13) checks EVERY command for a directed halt, so a long
+    // non-deploy turn aborts at its next tool call. A non-match in halt-only mode
+    // is NOT a free pass — it still does the one cheap cached halt read.
+    if (!opts.haltOnly && cls.kind === 'none')
+        return 0;
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        return 0; // not a git repo → no-op
+    const proj = (0, config_1.loadProjectConfig)(top);
+    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 member = cfg.member;
+    const session = member ? (0, git_1.sessionId)(member, top) : null;
+    if (!cfg.apiKey || !session) {
+        // We cannot verify. The halt-only `.*` matcher stays SILENT (no point shouting
+        // on every Bash); the deploy gate on a MATCHED command fails OPEN-loud.
+        if (!opts.haltOnly && cls.kind !== 'none') {
+            loudOpen('convene: halt/lane state UNVERIFIED — not logged in, proceeding UNGATED.');
+        }
+        return 0;
+    }
+    const instance = (0, cache_1.ensureSessionInstance)(slug);
+    const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+    // ── HALT-ONLY mode: ONE cheap cached halt read for ANY command ──────────────
+    // exit 2 ONLY on a confirmed OPEN DIRECTED halt for this session (the only
+    // confirmed positive). Any uncertainty (state===null) → exit 0 (fail-open). The
+    // "no halt for me" answer is cached for a short TTL so a command burst pays one
+    // GET. NO deploy classification, NO lane read — strictly the halt backstop.
+    if (opts.haltOnly) {
+        const halt = await haltStateCached(api, slug);
+        if (halt && halt.halts.length > 0) {
+            blockReason('convene: BLOCKED — an active halt is directed at this session. Surface to the human; do not proceed.');
+            return 2;
+        }
+        return 0; // null (couldn't verify) OR no halt → fail-open
+    }
+    // ── DEFAULT (deploy) path — unchanged from WP9 ──────────────────────────────
+    // Derive the lane intent for a deploy/push command (null = non-deploy).
+    let ref = null;
+    if (cls.kind === 'push') {
+        const deployRef = cls.refs.find((r) => classifyPushRefs(r));
+        // No deploy ref in the push (e.g. a feature branch) → not a deploy; only the
+        // halt check applies. ref stays null so we don't gate a feature-branch lane.
+        ref = deployRef ?? null;
+    }
+    else if (cls.kind === 'deploy' || cls.kind === 'force') {
+        ref = 'refs/heads/main'; // generic deploy lane intent
+    }
+    const intent = ref ? `deploy:${ref}` : 'deploy';
+    // ONE lane-state GET serves both the halt check and the lane check (cached ~3s
+    // keyed (slug,intent) by laneStateCached). Any failure → fail-open (no block).
+    const state = await laneStateCached(api, slug, intent);
+    if (!state) {
+        loudOpen('convene: halt/lane state UNVERIFIED — bus unreachable, proceeding UNGATED.');
+        return 0;
+    }
+    // (a) An open DIRECTED HALT for this session is a HARD block for ANY matched command.
+    const halts = Array.isArray(state.halts) ? state.halts : [];
+    if (halts.length > 0) {
+        blockReason('convene: BLOCKED — an active halt is directed at this session. Surface to the human; do not proceed.');
+        return 2;
+    }
+    // (b) A held lane only matters for a DEPLOY command (push to a deploy ref, or a
+    // deploy/force verb). A foreign held lane → soft conflict → 'ask' (NOT a hard
+    // deny — the gate-push CAS is the real serializer at push time).
+    const isDeploy = ref != null || cls.kind === 'deploy' || cls.kind === 'force';
+    if (isDeploy) {
+        const lanes = Array.isArray(state.lanes) ? state.lanes : [];
+        const foreign = lanes.find((l) => l && l.holder_instance_self === false);
+        if (foreign) {
+            ask(`A deploy lane is held by ${safeHandle(foreign.holder_handle)}. ` +
+                `The push gate will serialize this — proceed and let it claim, or coordinate first. Allow?`);
+            return 0;
+        }
+    }
+    return 0;
+}
+const STATE_TTL_MS = 3000;
+const stateCache = new Map();
+async function laneStateCached(api, slug, intent) {
+    const key = `${slug}\u0000${intent}`;
+    const hit = stateCache.get(key);
+    if (hit && Date.now() - hit.at < STATE_TTL_MS)
+        return { lanes: hit.lanes, halts: hit.halts };
+    const res = await api.laneState(slug, intent, NET_TIMEOUT_MS).catch(() => null);
+    if (!res || !res.ok || !res.json)
+        return null; // fail-open
+    const lanes = Array.isArray(res.json.lanes) ? res.json.lanes : [];
+    const halts = Array.isArray(res.json.halts) ? res.json.halts : [];
+    stateCache.set(key, { at: Date.now(), lanes, halts });
+    return { lanes, halts };
+}
+const haltCache = new Map();
+async function haltStateCached(api, slug) {
+    const hit = haltCache.get(slug);
+    if (hit && Date.now() - hit.at < STATE_TTL_MS)
+        return { halts: hit.halts };
+    // No intent: a halt is routed by member/session, not by lane — the cheapest read.
+    const res = await api.laneState(slug, null, NET_TIMEOUT_MS).catch(() => null);
+    if (!res || !res.ok || !res.json)
+        return null; // fail-open (and don't cache the miss)
+    const halts = Array.isArray(res.json.halts) ? res.json.halts : [];
+    haltCache.set(slug, { at: Date.now(), halts });
+    return { halts };
+}
+async function guard(opts = {}) {
+    let code = 0;
+    const watchdog = setTimeout(() => process.exit(0), WATCHDOG_MS);
+    try {
+        code = await run(opts);
+    }
+    catch {
+        code = 0; // fail-open: never block on our own error
+    }
+    clearTimeout(watchdog);
+    process.exit(code);
+}

package/dist/commands/init.js

@@ -34,13 +34,15 @@ function upsertMarkerBlock(content, block) {
     const sep = content.length === 0 ? '' : content.endsWith('\n') ? '\n' : '\n\n';
     return content + sep + block + '\n';
 }
-function writeIfChanged(file, content, backup = true) {
+// Every file this writes lives inside the git repo, so git history IS the backup —
+// dropping a sibling `.bak` just litters the working tree (and shows up as untracked
+// noise / risks being committed). The only `.bak` we keep is for the user's GLOBAL
+// ~/.claude/settings.json, which is outside any repo (see registerHook).
+function writeIfChanged(file, content) {
     const exists = node_fs_1.default.existsSync(file);
     const old = exists ? node_fs_1.default.readFileSync(file, 'utf8') : null;
     if (old === content)
         return 'unchanged';
-    if (exists && backup)
-        node_fs_1.default.writeFileSync(file + '.bak', old);
     node_fs_1.default.writeFileSync(file, content);
     return exists ? 'updated' : 'created';
 }
@@ -81,8 +83,7 @@ function ensureGitignoreGuard(top) {
         next = next + sep + guard;
     }
     if (next !== old) {
-        if (node_fs_1.default.existsSync(file))
-            node_fs_1.default.writeFileSync(file + '.bak', old);
+        // .gitignore is git-tracked — no .bak (git history is the backup).
         node_fs_1.default.writeFileSync(file, next);
     }
     // Belt-and-suspenders: confirm the join-token-bearing file is actually trackable.
@@ -128,6 +129,82 @@ function registerHook(noHook) {
         log(hookSnippet());
     }
 }
+/**
+ * The WP13 coordination hooks, in INSTALL ORDER. Order matters for the two Bash
+ * PreToolUse entries: `gate-push --stdin` is wired before `guard`, so `guard` lands
+ * LAST among Bash PreToolUse hooks (awareness/ux #10) — the deploy gate runs, then
+ * the cheap halt/lane backstop. Each entry names the VERB its binary must support;
+ * a stale `convene` missing the verb is skipped (so it can't error on every boot).
+ *
+ * `convene watch` is NOT a Bash hook — it's a long-running detached daemon that
+ * `convene session-start` spawns from the SessionStart path (§4.4). Wiring it as a
+ * blocking Bash/PreToolUse entry would stall; launching from session-start keeps it
+ * off the discretionary tool path.
+ */
+const COORD_HOOKS = [
+    {
+        event: 'SessionStart',
+        matcher: 'startup|resume|clear',
+        command: 'convene session-start',
+        verb: 'session-start',
+        note: 'auto catch-up digest + mints the session-instance + launches `convene watch`',
+    },
+    {
+        event: 'PreToolUse',
+        matcher: 'Bash',
+        command: 'convene gate-push --stdin',
+        verb: 'gate-push',
+        note: 'deploy gate before a push (fail-open-loud)',
+    },
+    // guard is appended AFTER gate-push so it is LAST among Bash PreToolUse hooks.
+    {
+        event: 'PreToolUse',
+        matcher: 'Bash',
+        command: 'convene guard',
+        verb: 'guard',
+        note: 'halt + lane backstop for Bash (fail-open-loud)',
+    },
+    {
+        event: 'PreToolUse',
+        matcher: '.*',
+        command: 'convene guard --halt-only',
+        verb: 'guard',
+        note: 'cheap directed-halt backstop on every tool call',
+    },
+    {
+        event: 'PostToolUse',
+        matcher: 'Bash',
+        command: 'convene gate-push --post',
+        verb: 'gate-push',
+        note: 'release the deploy lane after a push (idempotent)',
+    },
+];
+/**
+ * Wire the WP13 coordination hooks into a settings file (global or committed
+ * project), idempotent + merge-safe via ensureHook (deep-clone, never clobber,
+ * parseSettings-null → 'manual' so we never clobber unparseable JSON). Skips any
+ * hook whose verb the installed binary doesn't support.
+ */
+function registerCoordinationHooks(settingsPath, label) {
+    let unparseable = false;
+    for (const h of COORD_HOOKS) {
+        if (!(0, hook_1.binarySupportsVerb)(h.verb)) {
+            log(`· ${label}: skipped \`${h.command}\` — installed \`convene\` lacks \`${h.verb}\` (upgrade the CLI to enable).`);
+            continue;
+        }
+        const r = (0, hook_1.ensureHook)(h.event, h.command, h.matcher, settingsPath);
+        if (r === 'manual') {
+            unparseable = true;
+            break;
+        }
+    }
+    if (unparseable) {
+        log(`· ${label}: left as-is (existing settings unparseable) — add the coordination hooks manually.`);
+    }
+    else {
+        log(`✓ ${label}: coordination hooks wired (SessionStart catch-up, PreToolUse gate/guard, PostToolUse release).`);
+    }
+}
 function installGitHookStep(top, skip) {
     if (skip) {
         log('Skipped git pre-push hook (--no-githook).');
@@ -234,6 +311,84 @@ function writeAgentRules(top, slug, member, baseUrl) {
     writeGeminiSettings(top);
     writeAiderConf(top);
 }
+// ── MCP client configs ───────────────────────────────────────────────────────
+// Tools that speak MCP get the `convene` server auto-registered so the agent can
+// call convene_fetch / post / lanes / etc. The published `convene-mcp` runs via
+// `npx -y` (no global install); it resolves the API key from ~/.convene/config.json
+// (written by `convene login` / `setup`), so the COMMITTED config carries NO secret
+// — only the non-secret base URL. Idempotent JSON/TOML merge; never clobbers other
+// servers. Codex ALSO gets a UserPromptSubmit hook (true per-turn injection, the
+// cross-tool analog of the Claude Code fetch hook). Claude Code is intentionally
+// EXCLUDED — its richer hook + CLI integration already covers it. Cline & Windsurf
+// register MCP only via a USER-GLOBAL file (outside the repo), so init can't commit
+// them — they're documented for manual setup instead.
+const MCP_PKG = 'convene-mcp';
+const TOML_BEGIN = '# >>> convene (managed) — do not edit between these markers';
+const TOML_END = '# <<< convene (managed)';
+/** Replace the convene block between TOML markers, or append it (TOML-comment markers). */
+function upsertTomlBlock(content, block) {
+    const s = content.indexOf(TOML_BEGIN);
+    const e = content.indexOf(TOML_END);
+    if (s >= 0 && e > s) {
+        return content.slice(0, s) + block + content.slice(e + TOML_END.length);
+    }
+    const sep = content.length === 0 ? '' : content.endsWith('\n') ? '\n' : '\n\n';
+    return content + sep + block + '\n';
+}
+/**
+ * Ensure the `convene` server in a JSON MCP config under `topKey` (`mcpServers` for
+ * Cursor/Gemini, `servers` for VS Code). `stdioType` adds `"type":"stdio"` (VS Code
+ * wants it; the others infer stdio from `command`). Preserves other servers + keys;
+ * leaves an unparseable file untouched.
+ */
+function ensureJsonMcpServer(file, topKey, baseUrl, stdioType, label) {
+    let obj = {};
+    if (node_fs_1.default.existsSync(file)) {
+        try {
+            obj = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8')) || {};
+        }
+        catch {
+            log(`· ${label} (left as-is — unparseable JSON)`);
+            return;
+        }
+    }
+    if (!obj[topKey] || typeof obj[topKey] !== 'object')
+        obj[topKey] = {};
+    obj[topKey].convene = stdioType
+        ? { type: 'stdio', command: 'npx', args: ['-y', MCP_PKG], env: { CONVENE_BASE_URL: baseUrl } }
+        : { command: 'npx', args: ['-y', MCP_PKG], env: { CONVENE_BASE_URL: baseUrl } };
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    const r = writeIfChanged(file, JSON.stringify(obj, null, 2) + '\n');
+    log(`${r === 'unchanged' ? '·' : '✓'} ${label} (${r})`);
+}
+/** Codex: project `.codex/config.toml` with the MCP server AND the UserPromptSubmit hook. */
+function writeCodexConfig(top, baseUrl) {
+    const file = node_path_1.default.join(top, '.codex', 'config.toml');
+    const block = `${TOML_BEGIN}\n` +
+        `[mcp_servers.convene]\n` +
+        `command = "npx"\n` +
+        `args = ["-y", "${MCP_PKG}"]\n` +
+        `[mcp_servers.convene.env]\n` +
+        `CONVENE_BASE_URL = "${baseUrl}"\n` +
+        `\n` +
+        `[[hooks.UserPromptSubmit]]\n` +
+        `type = "command"\n` +
+        `command = "convene fetch --codex-hook"\n` +
+        `timeout = 10\n` +
+        `${TOML_END}`;
+    const old = node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file, 'utf8') : '';
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    const r = writeIfChanged(file, upsertTomlBlock(old, block));
+    log(`${r === 'unchanged' ? '·' : '✓'} .codex/config.toml (${r}) — Codex per-turn fetch hook + MCP server (trust the project once via \`/hooks\`; needs the \`convene\` CLI on PATH)`);
+}
+/** Write MCP client configs for the tools that take a committable project file. */
+function writeMcpConfigs(top, baseUrl) {
+    ensureJsonMcpServer(node_path_1.default.join(top, '.cursor', 'mcp.json'), 'mcpServers', baseUrl, false, '.cursor/mcp.json — Cursor MCP server');
+    ensureJsonMcpServer(node_path_1.default.join(top, '.vscode', 'mcp.json'), 'servers', baseUrl, true, '.vscode/mcp.json — VS Code / Copilot MCP server');
+    ensureJsonMcpServer(node_path_1.default.join(top, '.gemini', 'settings.json'), 'mcpServers', baseUrl, false, '.gemini/settings.json — Gemini CLI MCP server');
+    writeCodexConfig(top, baseUrl);
+    log('· Cline & Windsurf register MCP only in a user-global file — add `convene` (`npx -y convene-mcp`) there manually; see CONVENE_PROTOCOL.md.');
+}
 async function init(opts) {
     const top = (0, git_1.gitToplevel)();
     if (!top)
@@ -246,6 +401,7 @@ async function init(opts) {
     const skipGithook = opts.noGithook === true || opts.githook === false;
     const skipJoinToken = opts.noJoinToken === true || opts.joinToken === false;
     const skipAgentRules = opts.noAgentRules === true || opts.agentRules === false;
+    const skipMcp = opts.noMcp === true || opts.mcp === false;
     let slug = opts.slug || existing?.slug;
     let displayName = opts.name || existing?.displayName;
     let joinToken = existing?.joinToken; // reuse if present (keeps init idempotent)
@@ -338,9 +494,16 @@ async function init(opts) {
     // 4. .gitignore guard
     ensureGitignoreGuard(top);
     log('✓ .gitignore guard');
-    // 5. CLAUDE.md + AGENTS.md managed block
-    const block = (0, protocol_1.conveneBlock)(slug, member, baseUrl);
-    for (const fname of ['CLAUDE.md', 'AGENTS.md']) {
+    // 5. CLAUDE.md + AGENTS.md managed block. The two blocks INTENTIONALLY DIVERGE:
+    //    CLAUDE.md uses conveneBlock (no manual-deploy line — the PreToolUse hook
+    //    gates deploys), AGENTS.md uses conveneAgentsBlock (adds the explicit
+    //    `convene deploy` line for tools with no in-time gate). Each is PURE, so a
+    //    re-run is byte-identical per file (P0-IDEMPOTENT).
+    const fileBlocks = [
+        ['CLAUDE.md', (0, protocol_1.conveneBlock)(slug, member, baseUrl)],
+        ['AGENTS.md', (0, protocol_1.conveneAgentsBlock)(slug, member, baseUrl)],
+    ];
+    for (const [fname, block] of fileBlocks) {
         const file = node_path_1.default.join(top, fname);
         const old = node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file, 'utf8') : '';
         const result = writeIfChanged(file, upsertMarkerBlock(old, block));
@@ -378,6 +541,19 @@ async function init(opts) {
                 log('    otherwise they connect via `convene setup`.');
             }
         }
+        // 7a-bis. The WP13 coordination hooks (SessionStart catch-up, PreToolUse
+        //   gate-push + guard + halt-only, PostToolUse release) — wired idempotently via
+        //   the generalized ensureHook into the committed PROJECT settings ONLY, never
+        //   global. These are BLOCKING PreToolUse/SessionStart hooks: writing them into
+        //   ~/.claude/settings.json would fire them (and shell out to `convene`) in EVERY
+        //   repo on the machine, gating unrelated work behind a tool that no-ops there.
+        //   The committed .claude/settings.json already covers this checkout (Claude Code
+        //   applies project hooks after a one-time per-repo trust prompt) AND lets
+        //   teammates inherit them — so global is both redundant and a footgun. Only the
+        //   lightweight `convene fetch` UserPromptSubmit hook stays global (registerHook
+        //   above). guard lands LAST among Bash PreToolUse; verbs the binary lacks are
+        //   skipped so a stale CLI never errors on boot.
+        registerCoordinationHooks((0, hook_1.projectSettingsPath)(top), '.claude/settings.json (committed)');
     }
     // 7b. committed git pre-push hook — the tool-agnostic backstop that auto-posts a
     //     [STATUS] when work is pushed (fires for Codex/Cowork/humans, not just Claude).
@@ -390,6 +566,15 @@ async function init(opts) {
     else {
         writeAgentRules(top, slug, member, baseUrl);
     }
+    // 7d. MCP client configs — register the `convene` MCP server (and, for Codex, a
+    //     per-turn fetch hook) so MCP-speaking tools get the bus without the CLI
+    //     hooks. Committed + secret-free (key resolved from ~/.convene/config.json).
+    if (skipMcp) {
+        log('Skipped MCP client configs (--no-mcp).');
+    }
+    else {
+        writeMcpConfigs(top, baseUrl);
+    }
     // 8. memory seed (best-effort, outside the repo)
     seedMemory(top, slug, baseUrl);
     // 9. teammate one-liner