convene-cli 1.1.1 → 1.3.0

package/dist/commands/offboard.js

@@ -0,0 +1,526 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.offboard = offboard;
+/**
+ * `convene off-board` — the exact inverse of `convene init`. Cleanly removes this
+ * repo from Convene in ONE isolated commit, instead of the ~14-file manual surgery
+ * the VAcontractorCo cleanup needed.
+ *
+ * Principles (mirrors init's discipline):
+ *  - Surgical: strip only the convene-managed block from CLAUDE.md/AGENTS.md and the
+ *    convene server/hook entries from shared config files — never clobber a user's
+ *    own content. Delete a file only when it was convene's alone (empty after strip,
+ *    or byte-identical to what init wrote).
+ *  - Isolated: stage ONLY the touched convene paths into one commit, never `git add -A`.
+ *  - Identity-preserving: the machine identity in ~/.convene/config.json is shared
+ *    across repos and is NEVER removed here.
+ *  - Idempotent: safe to re-run; a repo with no project.json is a clean no-op.
+ */
+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");
+const hook_1 = require("../hook");
+const githook_1 = require("../githook");
+const init_1 = require("./init");
+const materialize_1 = require("../catalog/materialize");
+const catalog_1 = require("../catalog");
+const protocol_1 = require("../protocol");
+const ctx_1 = require("../ctx");
+/**
+ * Every permissions.deny entry the catalog's settingsJson artifacts contribute —
+ * the EXACT set materialize.ts can write into .claude/settings.json at hook-hard.
+ * Off-board subtracts exactly these (and only these), so a teammate's own deny rule
+ * is never removed. Computed from CATALOG so it tracks the catalog automatically.
+ */
+function catalogManagedDenyEntries() {
+    const out = new Set();
+    for (const p of catalog_1.CATALOG.practices) {
+        for (const a of p.artifacts) {
+            if (a.kind === 'settingsJson') {
+                for (const d of (0, materialize_1.denyEntriesOf)(a))
+                    out.add(d);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Every .gitignore line the catalog's gitignore artifacts contribute — the set
+ * materialize.ts appends at any hook level. Off-board removes exactly these.
+ */
+function catalogManagedGitignoreLines() {
+    const out = [];
+    for (const p of catalog_1.CATALOG.practices) {
+        for (const a of p.artifacts) {
+            if (a.kind === 'gitignore')
+                out.push(...a.lines);
+        }
+    }
+    return out;
+}
+const log = (m) => process.stdout.write(m + '\n');
+const abs = (top, rel) => node_path_1.default.join(top, rel);
+const jsonOut = (obj) => JSON.stringify(obj, null, 2) + '\n';
+/** Delete a file/dir that is unambiguously convene's (e.g. `.convene/`, dedicated rule files). */
+function delPath(top, rel, touched, dryRun) {
+    const p = abs(top, rel);
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    touched.push({ rel, action: 'delete' });
+    if (!dryRun)
+        node_fs_1.default.rmSync(p, { recursive: true, force: true });
+}
+/**
+ * A CONVENE_PROTOCOL.md that init generated, recognized by its stable opening rather
+ * than byte-equality — byte-equality breaks across CLI versions AND across the
+ * convene.stateful.world → dev.convene.live baseURL migration (the URL is baked into
+ * the doc). A doc whose intro was hand-replaced (e.g. the Convene repo's own) is preserved.
+ */
+function isGeneratedProtocolDoc(content) {
+    return (content.startsWith('# Convene Protocol\n') &&
+        content.includes('This repository participates in **Convene**, a hosted, multi-tenant'));
+}
+function handleProtocolDoc(top, touched, dryRun) {
+    const rel = 'CONVENE_PROTOCOL.md';
+    const p = abs(top, rel);
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    if (!isGeneratedProtocolDoc(node_fs_1.default.readFileSync(p, 'utf8'))) {
+        log(`· ${rel} (left as-is — hand-authored; remove manually if you meant to)`);
+        return;
+    }
+    touched.push({ rel, action: 'delete' });
+    if (!dryRun)
+        node_fs_1.default.rmSync(p, { force: true });
+}
+/** Delete a file ONLY if it is byte-identical to what init wrote (else it was hand-edited — leave it). */
+function delIfOurs(top, rel, expected, touched, dryRun) {
+    const p = abs(top, rel);
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(p, 'utf8');
+    }
+    catch {
+        return;
+    }
+    if (content !== expected) {
+        log(`· ${rel} (left as-is — edited since onboarding; remove manually if you meant to)`);
+        return;
+    }
+    touched.push({ rel, action: 'delete' });
+    if (!dryRun)
+        node_fs_1.default.rmSync(p, { force: true });
+}
+/**
+ * Strip BOTH convene-managed regions from a Markdown doc — the main coordination
+ * block AND the Phase-2 best-practices ref region (`<!-- convene:practices:begin -->`
+ * …) — in ONE read/write so the file is reported (and staged) at most once. Deletes
+ * the file if nothing else remains. The dedicated `.convene/best-practices.md` +
+ * `.convene/practices/` docs are removed wholesale by `delPath('.convene')`.
+ */
+function stripMarker(top, rel, touched, dryRun) {
+    const p = abs(top, rel);
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    const orig = node_fs_1.default.readFileSync(p, 'utf8');
+    const block = (0, init_1.removeMarkerBlock)(orig);
+    const ref = (0, materialize_1.removeRefRegion)(block.content);
+    if (!block.removed && !ref.removed)
+        return;
+    applyStripOrDelete(top, rel, ref.content, touched, dryRun);
+}
+/** Strip the convene block from a Codex config.toml; delete if nothing else remains. */
+function stripToml(top, rel, touched, dryRun) {
+    const p = abs(top, rel);
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    const { content, removed } = (0, init_1.removeTomlBlock)(node_fs_1.default.readFileSync(p, 'utf8'));
+    if (!removed)
+        return;
+    applyStripOrDelete(top, rel, content, touched, dryRun);
+}
+function applyStripOrDelete(top, rel, content, touched, dryRun) {
+    const p = abs(top, rel);
+    if (content.trim().length === 0) {
+        touched.push({ rel, action: 'delete' });
+        if (!dryRun)
+            node_fs_1.default.rmSync(p, { force: true });
+    }
+    else {
+        touched.push({ rel, action: 'strip' });
+        if (!dryRun)
+            node_fs_1.default.writeFileSync(p, content);
+    }
+}
+/** Remove the `convene` MCP server from a JSON config (Cursor `mcpServers`, VS Code `servers`). */
+function stripJsonServer(top, rel, topKey, touched, dryRun) {
+    const p = abs(top, rel);
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    let obj;
+    try {
+        obj = JSON.parse(node_fs_1.default.readFileSync(p, 'utf8')) || {};
+    }
+    catch {
+        log(`· ${rel} (left as-is — unparseable JSON)`);
+        return;
+    }
+    if (!obj[topKey] || !obj[topKey].convene)
+        return;
+    delete obj[topKey].convene;
+    if (Object.keys(obj[topKey]).length === 0)
+        delete obj[topKey];
+    finalizeJson(top, rel, obj, touched, dryRun);
+}
+/** Gemini settings carry BOTH the convene MCP server and the AGENTS.md context entry. */
+function stripGemini(top, rel, touched, dryRun) {
+    const p = abs(top, rel);
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    let obj;
+    try {
+        obj = JSON.parse(node_fs_1.default.readFileSync(p, 'utf8')) || {};
+    }
+    catch {
+        log(`· ${rel} (left as-is — unparseable JSON)`);
+        return;
+    }
+    let changed = false;
+    if (obj.mcpServers && obj.mcpServers.convene) {
+        delete obj.mcpServers.convene;
+        if (Object.keys(obj.mcpServers).length === 0)
+            delete obj.mcpServers;
+        changed = true;
+    }
+    if (obj.context && obj.context.fileName) {
+        const names = Array.isArray(obj.context.fileName) ? obj.context.fileName : [obj.context.fileName];
+        const filtered = names.filter((n) => n !== 'AGENTS.md');
+        if (filtered.length !== names.length) {
+            changed = true;
+            if (filtered.length === 0) {
+                delete obj.context.fileName;
+                if (Object.keys(obj.context).length === 0)
+                    delete obj.context;
+            }
+            else {
+                obj.context.fileName = filtered;
+            }
+        }
+    }
+    if (!changed)
+        return;
+    finalizeJson(top, rel, obj, touched, dryRun);
+}
+function finalizeJson(top, rel, obj, touched, dryRun) {
+    const p = abs(top, rel);
+    if (Object.keys(obj).length === 0) {
+        touched.push({ rel, action: 'delete' });
+        if (!dryRun)
+            node_fs_1.default.rmSync(p, { force: true });
+    }
+    else {
+        touched.push({ rel, action: 'strip' });
+        if (!dryRun)
+            node_fs_1.default.writeFileSync(p, jsonOut(obj));
+    }
+}
+/**
+ * Strip convene-managed content from the committed .claude/settings.json — both the
+ * convene-authored hooks (withoutConveneHooks, which also matches the materialized
+ * `convene practice-guard …` PreToolUse/Stop hooks) AND the Phase-3 permissions.deny
+ * entries materialize.ts merged in (subtract EXACTLY the catalog's managed set;
+ * drop permissions.deny if it empties, then permissions if it empties). A teammate's
+ * own hooks / deny rules / settings are preserved. Delete the file if nothing remains.
+ */
+function stripClaudeSettings(top, rel, touched, dryRun) {
+    const p = abs(top, rel);
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    let obj;
+    try {
+        obj = JSON.parse(node_fs_1.default.readFileSync(p, 'utf8'));
+    }
+    catch {
+        log(`· ${rel} (left as-is — unparseable JSON)`);
+        return;
+    }
+    const stripped = (0, hook_1.withoutConveneHooks)(obj);
+    let removed = stripped.removed;
+    const settings = stripped.settings;
+    // Subtract the convene-managed permissions.deny entries (only ours).
+    const managedDeny = catalogManagedDenyEntries();
+    const deny = settings?.permissions?.deny;
+    if (Array.isArray(deny) && managedDeny.size) {
+        const kept = deny.filter((d) => !(typeof d === 'string' && managedDeny.has(d)));
+        if (kept.length !== deny.length) {
+            removed = true;
+            if (kept.length > 0) {
+                settings.permissions.deny = kept;
+            }
+            else {
+                delete settings.permissions.deny;
+                if (settings.permissions && Object.keys(settings.permissions).length === 0)
+                    delete settings.permissions;
+            }
+        }
+    }
+    if (!removed)
+        return;
+    if ((0, hook_1.settingsIsEmpty)(settings)) {
+        touched.push({ rel, action: 'delete' });
+        if (!dryRun)
+            node_fs_1.default.rmSync(p, { force: true });
+    }
+    else {
+        touched.push({ rel, action: 'strip' });
+        if (!dryRun)
+            node_fs_1.default.writeFileSync(p, jsonOut(settings));
+    }
+}
+/** Remove the committed git pre-push hook + relinquish core.hooksPath (only if ours). */
+function handleGitHook(top, touched, dryRun) {
+    const rel = '.githooks/pre-push';
+    const p = abs(top, rel);
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    if (!/convene:githook/.test(node_fs_1.default.readFileSync(p, 'utf8'))) {
+        log('· .githooks/pre-push (left as-is — not a convene hook)');
+        return;
+    }
+    if (dryRun) {
+        touched.push({ rel, action: 'delete' });
+        return;
+    }
+    const r = (0, githook_1.uninstallGitHooks)(top);
+    if (r.status === 'removed')
+        touched.push({ rel, action: 'delete' });
+    else if (r.status === 'skipped-foreign')
+        log('· .githooks/pre-push (left as-is — foreign hook)');
+}
+/**
+ * Reverse BOTH .gitignore footprints: init's cache guard (removeGitignoreGuard, which
+ * also re-enables any blanket rule init disabled) AND the Phase-3 practices lines +
+ * managed marker materialize.ts appended (removeGitignoreLines). Done in one
+ * read/write so the file is reported/staged at most once; deletes the file if empty.
+ */
+function handleGitignore(top, touched, dryRun) {
+    const rel = '.gitignore';
+    const p = abs(top, rel);
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    const old = node_fs_1.default.readFileSync(p, 'utf8');
+    const practiceLines = catalogManagedGitignoreLines();
+    const practicesProbe = (0, materialize_1.removeGitignoreLines)(old, practiceLines);
+    const willChangeGuard = old.includes('.convene/cache/') ||
+        old.includes('.convene/*.local.json') ||
+        old.includes('# convene (keep local cache') ||
+        /\(disabled by convene init/.test(old);
+    if (!willChangeGuard && !practicesProbe.removed)
+        return;
+    if (dryRun) {
+        touched.push({ rel, action: 'strip' });
+        return;
+    }
+    // 1. Strip the Phase-3 practices lines first (write-back so removeGitignoreGuard
+    //    operates on the practices-free body).
+    if (practicesProbe.removed) {
+        if (practicesProbe.content.trim().length === 0)
+            node_fs_1.default.rmSync(p, { force: true });
+        else
+            node_fs_1.default.writeFileSync(p, practicesProbe.content);
+    }
+    // 2. Then reverse init's cache guard (no-op if the file was already deleted).
+    const guardChanged = node_fs_1.default.existsSync(p) ? (0, init_1.removeGitignoreGuard)(top) : false;
+    if (practicesProbe.removed || guardChanged) {
+        touched.push({ rel, action: node_fs_1.default.existsSync(p) ? 'strip' : 'delete' });
+    }
+}
+/** Drop now-empty convene dirs. Order matters: nested dirs (.cursor/rules) before parents. */
+function cleanupEmptyDirs(top) {
+    for (const d of ['.cursor/rules', '.cursor', '.clinerules', '.gemini', '.codex', '.vscode', '.claude', '.githooks']) {
+        const p = abs(top, d);
+        try {
+            if (node_fs_1.default.existsSync(p) && node_fs_1.default.readdirSync(p).length === 0)
+                node_fs_1.default.rmdirSync(p);
+        }
+        catch {
+            /* not empty / already gone */
+        }
+    }
+}
+/** Remove the per-machine `convene fetch` hook from ~/.claude/settings.json (keeps a .bak). */
+function removeGlobalHook(dryRun) {
+    if (!node_fs_1.default.existsSync(hook_1.SETTINGS_PATH))
+        return;
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(hook_1.SETTINGS_PATH, 'utf8');
+    }
+    catch {
+        return;
+    }
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        log('· ~/.claude/settings.json (left as-is — unparseable)');
+        return;
+    }
+    const { settings, removed } = (0, hook_1.withoutConveneHooks)(obj);
+    if (!removed)
+        return;
+    if (dryRun) {
+        log('· would remove the global `convene fetch` hook from ~/.claude/settings.json');
+        return;
+    }
+    try {
+        node_fs_1.default.writeFileSync(hook_1.SETTINGS_PATH + '.bak', raw);
+        if ((0, hook_1.settingsIsEmpty)(settings))
+            node_fs_1.default.rmSync(hook_1.SETTINGS_PATH, { force: true });
+        else
+            node_fs_1.default.writeFileSync(hook_1.SETTINGS_PATH, jsonOut(settings));
+        log('✓ removed the global `convene fetch` hook (backup: ~/.claude/settings.json.bak)');
+    }
+    catch {
+        log('· could not update ~/.claude/settings.json — remove the `convene fetch` hook manually.');
+    }
+}
+/** Remove the seeded memory file + its MEMORY.md index line (best-effort). */
+function removeSeededMemory(top, slug, baseUrl, dryRun) {
+    try {
+        const mangled = top.replace(/\//g, '-');
+        const memDir = node_path_1.default.join((0, config_1.homeBase)(), '.claude', 'projects', mangled, 'memory');
+        const { name, indexLine } = (0, protocol_1.memoryEntry)(slug, baseUrl);
+        const memFile = node_path_1.default.join(memDir, `${name}.md`);
+        const indexFile = node_path_1.default.join(memDir, 'MEMORY.md');
+        if (node_fs_1.default.existsSync(memFile)) {
+            if (dryRun)
+                log(`· would remove seeded memory ${name}.md`);
+            else
+                node_fs_1.default.rmSync(memFile, { force: true });
+        }
+        if (!dryRun && node_fs_1.default.existsSync(indexFile)) {
+            const idx = node_fs_1.default.readFileSync(indexFile, 'utf8');
+            if (idx.includes(indexLine)) {
+                const next = idx
+                    .split('\n')
+                    .filter((l) => l.trim() !== indexLine.trim())
+                    .join('\n');
+                node_fs_1.default.writeFileSync(indexFile, next);
+            }
+        }
+    }
+    catch {
+        /* memory cleanup is best-effort */
+    }
+}
+async function offboard(opts) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        (0, ctx_1.die)('not a git repository — run `convene off-board` inside a repo');
+    const proj = (0, config_1.loadProjectConfig)(top);
+    if (!proj?.slug) {
+        log('This repo is not on Convene — nothing to off-board.');
+        return;
+    }
+    const dryRun = !!opts.dryRun;
+    // Consent gate: off-board is destructive. A human at a TTY confirms by running it;
+    // an agent / CI (no TTY) must pass `--yes`. A dry-run changes nothing, so it's exempt.
+    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 baseUrl = cfg.baseUrl;
+    const slug = proj.slug;
+    // 1. Optional server-side token revoke FIRST (before deleting local files, so a
+    //    failure leaves the repo recoverable). Owner-only — warn (don't fail) on 403.
+    if (opts.revokeToken && proj.joinToken) {
+        if (dryRun) {
+            log('· would revoke the committed join token server-side (--revoke-token).');
+        }
+        else if (!cfg.apiKey) {
+            log('⚠ --revoke-token: not logged in; skipping the server-side revoke.');
+        }
+        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.revokeJoinToken(slug, proj.joinToken.slice(0, 14), 8000);
+            log(r.ok
+                ? '✓ revoked the committed join token server-side.'
+                : `⚠ could not revoke the join token (${r.error}) — it is owner-only; revoke from the dashboard if needed.`);
+        }
+    }
+    // 2. Local footprint removal.
+    const touched = [];
+    stripMarker(top, 'CLAUDE.md', touched, dryRun);
+    stripMarker(top, 'AGENTS.md', touched, dryRun);
+    handleProtocolDoc(top, touched, dryRun);
+    delIfOurs(top, '.aider.conf.yml', init_1.AIDER_CONF, touched, dryRun);
+    delPath(top, '.convene', touched, dryRun);
+    delPath(top, '.cursor/rules/convene.mdc', touched, dryRun);
+    delPath(top, '.clinerules/convene.md', touched, dryRun);
+    stripClaudeSettings(top, '.claude/settings.json', touched, dryRun);
+    stripToml(top, '.codex/config.toml', touched, dryRun);
+    stripJsonServer(top, '.cursor/mcp.json', 'mcpServers', touched, dryRun);
+    stripJsonServer(top, '.vscode/mcp.json', 'servers', touched, dryRun);
+    stripGemini(top, '.gemini/settings.json', touched, dryRun);
+    handleGitHook(top, touched, dryRun);
+    handleGitignore(top, touched, dryRun);
+    if (!dryRun)
+        cleanupEmptyDirs(top);
+    // 3. Repo-specific seeded memory is always cleaned (it's keyed to THIS repo's path).
+    //    The machine-wide ~/.claude `convene fetch` hook is SHARED by every Convene repo
+    //    on this machine, so off-boarding ONE repo must NOT remove it by default — that
+    //    would silently stop auto-injection in your other Convene repos. Remove it only
+    //    with --remove-global. NEVER touch ~/.convene/config.json (the machine identity).
+    removeSeededMemory(top, slug, baseUrl, dryRun);
+    if (opts.removeGlobal)
+        removeGlobalHook(dryRun);
+    // 4. Report + isolated commit.
+    if (touched.length === 0) {
+        log(`Convene files already absent — repo "${slug}" is clean.`);
+        return;
+    }
+    log('');
+    log(`${dryRun ? 'Would remove' : 'Removed'} Convene from "${slug}":`);
+    for (const t of touched)
+        log(`  ${t.action === 'delete' ? '✗ delete' : '~ strip '} ${t.rel}`);
+    if (dryRun) {
+        log('');
+        log('(dry-run — nothing was changed.)');
+        return;
+    }
+    const doCommit = opts.commit !== false; // default on; --no-commit disables
+    if (doCommit) {
+        // Stage ONLY the tracked convene paths (deletions + strips), never `git add -A`,
+        // so the off-board lands as one isolated commit and can't sweep in other work.
+        const repoPaths = touched.map((t) => t.rel).filter((rel) => (0, git_1.pathIsTracked)(rel, top));
+        if (repoPaths.length && (0, git_1.gitAddPaths)(repoPaths, top) && (0, git_1.hasStagedChanges)(top)) {
+            const res = (0, git_1.gitCommit)('Off-board from Convene coordination bus', repoPaths, top);
+            if (res.ok)
+                log(`✓ committed the removal as one isolated commit${res.sha ? ` (${res.sha})` : ''}.`);
+            else
+                log('· could not create the off-board commit — commit the changes manually.');
+        }
+        else {
+            log('· nothing to commit (the convene files were untracked) — they are removed from the working tree.');
+        }
+    }
+    else {
+        log('· skipped commit (--no-commit) — review with `git status` and commit when ready.');
+    }
+    log('');
+    log('Off-boarded. The per-machine identity in ~/.convene/config.json was left intact (it is shared');
+    log('across repos).');
+    if (!opts.removeGlobal) {
+        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.');
+    }
+}

package/dist/commands/override.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.override = override;
+/**
+ * `convene override <id> --reason "<why>"` (Phase 3) — the attributed, short-lived
+ * bypass for a best-practice gate. Writes a LOCAL, expiry-based override token that
+ * `convene practice-guard <id>` honors → ALLOW, and best-effort posts an attributed
+ * [STATUS] to the bus so the bypass is auditable in real time.
+ *
+ * POSTURE:
+ *   - DIE-LOUD on a missing/empty --reason (an unattributed override is the whole
+ *     thing we are guarding against) and on a missing project.
+ *   - FAIL-OPEN on the BUS: the local token is the source of truth for the gate;
+ *     if the bus is unreachable we STILL write the token and WARN — an override must
+ *     never be blocked by a flaky network. The status post is attribution, not
+ *     authorization.
+ */
+const config_1 = require("../config");
+const git_1 = require("../git");
+const api_1 = require("../api");
+const cache_1 = require("../cache");
+const ctx_1 = require("../ctx");
+const NET_TIMEOUT_MS = 2500; // explicit short timeout — never the api.ts 10s default
+function fmtTtl(ms) {
+    const sec = Math.round(ms / 1000);
+    if (sec < 60)
+        return `${sec}s`;
+    const m = Math.round(sec / 60);
+    return m === 1 ? '1 minute' : `${m} minutes`;
+}
+async function override(id, opts = {}) {
+    if (!id || !id.trim())
+        (0, ctx_1.die)('override requires a practice <id> (e.g. `convene override protect-shared-files --reason "…"`)');
+    const reason = (opts.reason ?? '').trim();
+    if (!reason)
+        (0, ctx_1.die)('override requires --reason "<why>" — an unattributed override defeats the gate');
+    const top = (0, git_1.gitToplevel)();
+    const proj = (0, config_1.loadProjectConfig)(top);
+    const slug = opts.project || proj?.slug || null;
+    if (!slug)
+        (0, ctx_1.die)('no project — run inside a `convene init`-ed repo, or pass --project <slug>');
+    // 1) Write the LOCAL token first — this is what the gate honors. Source of truth.
+    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 member = cfg.member;
+    const session = member && top ? (0, git_1.sessionId)(member, top) : null;
+    let posted = false;
+    if (cfg.apiKey && session) {
+        try {
+            const instance = (0, cache_1.ensureSessionInstance)(slug);
+            const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+            const res = await api.post(slug, { type: 'status', body: `practice ${id} gate overridden — ${reason}` }, (0, ctx_1.uuid)(), NET_TIMEOUT_MS);
+            posted = !!res.ok;
+        }
+        catch {
+            posted = false;
+        }
+    }
+    process.stdout.write(`override active for ${id} (${fmtTtl(cache_1.OVERRIDE_TTL_MS)}) — the next edits gated by this practice will be allowed.\n`);
+    if (!posted) {
+        process.stderr.write('convene: WARNING bus unreachable — override applied locally but NOT announced to the channel.\n');
+    }
+}