convene-cli 1.0.0

package/dist/commands/init.js

@@ -0,0 +1,319 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertMarkerBlock = upsertMarkerBlock;
+exports.init = init;
+/**
+ * `convene init` — one-command repo onboarding. IDEMPOTENT + merge-safe
+ * (P0-IDEMPOTENT): running twice yields a byte-identical repo. Every managed file
+ * is upserted by stable markers; edits are backed up and only written when the
+ * content actually changes.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const brand_1 = require("../brand");
+const config_1 = require("../config");
+const git_1 = require("../git");
+const api_1 = require("../api");
+const protocol_1 = require("../protocol");
+const hook_1 = require("../hook");
+const githook_1 = require("../githook");
+const ctx_1 = require("../ctx");
+const log = (m) => process.stdout.write(m + '\n');
+/** Replace content between the convene markers, or append the block if absent. */
+function upsertMarkerBlock(content, block) {
+    const b = brand_1.BRAND.blockBegin;
+    const e = brand_1.BRAND.blockEnd;
+    const start = content.indexOf(b);
+    const end = content.indexOf(e);
+    if (start >= 0 && end > start) {
+        return content.slice(0, start) + block + content.slice(end + e.length);
+    }
+    const sep = content.length === 0 ? '' : content.endsWith('\n') ? '\n' : '\n\n';
+    return content + sep + block + '\n';
+}
+function writeIfChanged(file, content, backup = true) {
+    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';
+}
+/**
+ * A `.gitignore` line that ignores the WHOLE `.convene/` directory (e.g. `.convene/`,
+ * `.convene`, `/.convene`), as opposed to a granular sub-path like `.convene/cache/`.
+ * Comments (`#`) and negations (`!`) are not blanket rules.
+ */
+function isBlanketConveneIgnore(line) {
+    const t = line.trim();
+    if (!t || t.startsWith('#') || t.startsWith('!'))
+        return false;
+    return t.replace(/^\//, '').replace(/\/+$/, '') === '.convene';
+}
+function ensureGitignoreGuard(top) {
+    const file = node_path_1.default.join(top, '.gitignore');
+    const marker = '# convene';
+    const guard = `${marker} (keep local cache out of git; .convene/project.json IS committed)\n.convene/cache/\n.convene/*.local.json\n`;
+    const old = node_fs_1.default.existsSync(file) ? node_fs_1.default.readFileSync(file, 'utf8') : '';
+    // A pre-existing blanket `.convene/` rule ignores the whole directory, so git
+    // never descends into it and the committed `.convene/project.json` (which carries
+    // the join token) stays untracked — `git add .convene/project.json` is a silent
+    // no-op and every teammate's `convene join` fails with "no join token". A
+    // `!.convene/project.json` negation CANNOT rescue a file under an ignored parent,
+    // so we comment the blanket rule out outright and rely on the granular guard below.
+    const rewritten = old
+        .split('\n')
+        .map((line) => isBlanketConveneIgnore(line)
+        ? `# ${line.trim()}   (disabled by convene init: this hid the committed .convene/project.json + its join token)`
+        : line)
+        .join('\n');
+    // Detect the guard by its granular content (not the bare marker) so a stray
+    // "# convene" comment elsewhere can't trick us into skipping the real excludes.
+    const hasGuard = rewritten.includes('.convene/cache/') && rewritten.includes('.convene/*.local.json');
+    let next = rewritten;
+    if (!hasGuard) {
+        const sep = next.length === 0 ? '' : next.endsWith('\n') ? '' : '\n';
+        next = next + sep + guard;
+    }
+    if (next !== old) {
+        if (node_fs_1.default.existsSync(file))
+            node_fs_1.default.writeFileSync(file + '.bak', old);
+        node_fs_1.default.writeFileSync(file, next);
+    }
+    // Belt-and-suspenders: confirm the join-token-bearing file is actually trackable.
+    // A blanket rule may also live in a parent dir's .gitignore or a global excludes
+    // file we don't own — warn loudly rather than let onboarding silently break.
+    if ((0, git_1.gitPathIsIgnored)(top, node_path_1.default.join('.convene', 'project.json'))) {
+        log('⚠ .convene/project.json is STILL git-ignored after writing the guard —');
+        log('  teammates\' `convene join` will fail with "no join token".');
+        log('  Find the offending rule with `git check-ignore -v .convene/project.json`');
+        log('  (it may be in a parent .gitignore or your global core.excludesfile), remove it,');
+        log('  then `git add -f .convene/project.json`.');
+    }
+}
+function hookSnippet() {
+    return JSON.stringify({ hooks: { UserPromptSubmit: [{ hooks: [{ type: 'command', command: hook_1.HOOK_COMMAND }] }] } }, null, 2);
+}
+function registerHook(noHook) {
+    if (noHook) {
+        log('Skipped hook registration (--no-hook). Add this to ~/.claude/settings.json:');
+        log(hookSnippet());
+        return;
+    }
+    const raw = (0, hook_1.readSettingsRaw)();
+    const settings = (0, hook_1.parseSettings)(raw);
+    if (settings === null) {
+        log(`Could not safely parse ${hook_1.SETTINGS_PATH} — add this hook manually:`);
+        log(hookSnippet());
+        return;
+    }
+    if ((0, hook_1.hookIsRegistered)(settings)) {
+        log('Hook already registered (UserPromptSubmit `convene fetch`).');
+        return;
+    }
+    try {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(hook_1.SETTINGS_PATH), { recursive: true });
+        if (raw !== null)
+            node_fs_1.default.writeFileSync(hook_1.SETTINGS_PATH + '.bak', raw);
+        node_fs_1.default.writeFileSync(hook_1.SETTINGS_PATH, (0, hook_1.serializeSettings)((0, hook_1.withHook)(settings)));
+        log(`Registered UserPromptSubmit hook in ${hook_1.SETTINGS_PATH}${raw !== null ? ' (backup: settings.json.bak)' : ''}.`);
+    }
+    catch (err) {
+        log(`Could not write settings (${err?.message}). Add this hook manually:`);
+        log(hookSnippet());
+    }
+}
+function installGitHookStep(top, skip) {
+    if (skip) {
+        log('Skipped git pre-push hook (--no-githook).');
+        return;
+    }
+    const r = (0, githook_1.installGitHooks)(top);
+    switch (r.status) {
+        case 'installed':
+        case 'updated':
+            log(`✓ .githooks/pre-push (${r.status}) + core.hooksPath → auto-posts a [STATUS] on push`);
+            break;
+        case 'already':
+            log('· .githooks/pre-push (already installed)');
+            break;
+        case 'skipped-foreign':
+            log(`· git pre-push hook skipped — core.hooksPath is "${r.hooksPath}". To enable auto-status,`);
+            log('  add `convene notify-push "$@"` to your existing pre-push hook.');
+            break;
+        case 'skipped-localhooks':
+            log(`· git pre-push hook skipped — you have hooks in ${r.hooksDir}; redirecting core.hooksPath`);
+            log('  would disable them. To enable auto-status, add `convene notify-push "$@"` to that pre-push hook.');
+            break;
+        case 'error':
+            log(`· git pre-push hook not installed (${r.message}).`);
+            break;
+    }
+}
+function seedMemory(top, slug, baseUrl) {
+    try {
+        const mangled = top.replace(/\//g, '-');
+        const memDir = node_path_1.default.join((0, config_1.homeBase)(), '.claude', 'projects', mangled, 'memory');
+        node_fs_1.default.mkdirSync(memDir, { recursive: true });
+        const { name, content, indexLine } = (0, protocol_1.memoryEntry)(slug, baseUrl);
+        const memFile = node_path_1.default.join(memDir, `${name}.md`);
+        if (!node_fs_1.default.existsSync(memFile))
+            node_fs_1.default.writeFileSync(memFile, content);
+        const indexFile = node_path_1.default.join(memDir, 'MEMORY.md');
+        const idx = node_fs_1.default.existsSync(indexFile) ? node_fs_1.default.readFileSync(indexFile, 'utf8') : '# Memory Index\n\n';
+        if (!idx.includes(indexLine)) {
+            node_fs_1.default.writeFileSync(indexFile, (idx.endsWith('\n') ? idx : idx + '\n') + indexLine + '\n');
+        }
+    }
+    catch {
+        /* memory seed is best-effort */
+    }
+}
+async function init(opts) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        (0, ctx_1.die)('not a git repository — run `convene init` inside a repo');
+    const cfg = (0, config_1.resolveConfig)();
+    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;
+    let slug = opts.slug || existing?.slug;
+    let displayName = opts.name || existing?.displayName;
+    let joinToken = existing?.joinToken; // reuse if present (keeps init idempotent)
+    if (!opts.offline) {
+        let apiKey = cfg.apiKey;
+        if (!apiKey) {
+            // Self-serve first run: provision a global identity + key — no seed, no
+            // owner-issued key. The new identity has ZERO memberships until this init
+            // creates a project (making me its owner).
+            const handle = (0, git_1.deriveHandle)(top);
+            const email = opts.email || (0, git_1.gitUserEmail)(top) || null;
+            if (!email) {
+                (0, ctx_1.die)('first-time setup needs an email to create your Convene identity — re-run with `--email you@example.com` (or `convene login --api-key -` if you already have a key).');
+            }
+            const anon = new api_1.ConveneApi(baseUrl, null, null, cfg.tool);
+            const prov = await anon.provision({ handle, email: email, tool: cfg.tool }, 8000);
+            if (prov.status === 409) {
+                (0, ctx_1.die)(`an identity already exists for handle "${handle}" / "${email}" — run \`convene login --api-key -\` with your existing key, then re-run init.`);
+            }
+            if (!prov.ok || !prov.json?.api_key)
+                (0, ctx_1.die)(`could not self-provision an identity: ${prov.error}`);
+            apiKey = prov.json.api_key;
+            member = prov.json.member?.handle ?? handle;
+            (0, config_1.saveFileConfig)({ apiKey, baseUrl, member: member ?? undefined });
+            log(`✓ provisioned identity "${member}" (key saved to ~/.convene/config.json, 0600)`);
+        }
+        const api = new api_1.ConveneApi(baseUrl, apiKey, member ? (0, git_1.sessionId)(member, top) : null, cfg.tool);
+        if (slug) {
+            const got = await api.getProject(slug, 8000);
+            if (got.status === 404) {
+                const created = await api.createProject({ slug, name: displayName || slug, repo_patterns: [(0, git_1.worktreeBasename)(top)] }, 8000);
+                if (!created.ok)
+                    (0, ctx_1.die)(`could not create project ${slug}: ${created.error}`);
+                slug = created.json.project.slug;
+                displayName = displayName || created.json.project.name;
+            }
+            else if (got.status === 403) {
+                (0, ctx_1.die)(`project "${slug}" exists but you're not a member — run \`convene join\` (with a token) or ask an owner to add you`);
+            }
+            else if (!got.ok) {
+                (0, ctx_1.die)(`could not resolve project ${slug}: ${got.error}`);
+            }
+            else {
+                displayName = displayName || got.json.project.name;
+            }
+        }
+        else {
+            slug = (0, git_1.worktreeBasename)(top).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+            displayName = displayName || (0, git_1.worktreeBasename)(top);
+            const created = await api.createProject({ slug, name: displayName, repo_patterns: [(0, git_1.worktreeBasename)(top)] }, 8000);
+            if (created.status === 409) {
+                log(`Project "${slug}" already exists — attaching.`);
+            }
+            else if (!created.ok) {
+                (0, ctx_1.die)(`could not create project ${slug}: ${created.error}`);
+            }
+        }
+        // Mint a self-serve join token (owner only) so teammates can `convene join`
+        // straight from the committed repo. Reused if one already exists (idempotent);
+        // skipped silently if we're not the owner (member attach) or --no-join-token.
+        if (!joinToken && !skipJoinToken) {
+            // Public-repo guard: never commit a join token to a repo we can CONFIRM is
+            // public — it would be a world-readable, self-serve credential to the bus.
+            const vis = await (0, git_1.repoIsPublic)(top);
+            if (vis === true && !opts.force) {
+                log('⚠ This repo appears to be PUBLIC — NOT committing a join token (it would be world-readable).');
+                log('  Writing a slug-only .convene/project.json. Distribute a token out of band, or, if you');
+                log('  really intend a committed token here, re-run with --force.');
+            }
+            else {
+                if (vis === null && !opts.force) {
+                    log('⚠ Could not verify repo visibility (no gh / non-GitHub / offline). Committing the join token,');
+                    log('  assuming this repo is PRIVATE. If it is PUBLIC, re-run with `convene init --no-join-token`.');
+                }
+                const jt = await api.createJoinToken(slug, {}, 8000);
+                if (jt.ok && jt.json?.join_token)
+                    joinToken = jt.json.join_token;
+            }
+        }
+    }
+    else if (!slug) {
+        (0, ctx_1.die)('--offline requires --slug (or an existing .convene/project.json)');
+    }
+    slug = slug;
+    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 } : {}) });
+    log(`✓ ${node_path_1.default.relative(top, projFile)}${joinToken ? ' (incl. join token — private repos only)' : ''}`);
+    // 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']) {
+        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));
+        log(`${result === 'unchanged' ? '·' : '✓'} ${fname} (${result})`);
+    }
+    // 6. portable protocol doc — write only if ABSENT (mirrors the memory-seed
+    //    pattern). The doc is hand-enrichable; unconditionally overwriting it with
+    //    the generated stub would clobber any teammate's expanded protocol spec.
+    const protoFile = node_path_1.default.join(top, 'CONVENE_PROTOCOL.md');
+    if (!node_fs_1.default.existsSync(protoFile)) {
+        node_fs_1.default.writeFileSync(protoFile, (0, protocol_1.protocolDoc)(slug, baseUrl));
+        log('✓ CONVENE_PROTOCOL.md (created)');
+    }
+    else {
+        log('· CONVENE_PROTOCOL.md (exists — left as-is)');
+    }
+    // 7. hook
+    registerHook(skipHook);
+    // 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).
+    installGitHookStep(top, skipGithook);
+    // 8. memory seed (best-effort, outside the repo)
+    seedMemory(top, slug, baseUrl);
+    // 9. teammate one-liner
+    log('');
+    log(`Done. Project "${slug}" — dashboard: ${baseUrl}/p/${slug}`);
+    if (joinToken) {
+        log('Teammates (after they have the convene CLI) just run, from this repo:');
+        log(`  ${brand_1.BRAND.bin} join`);
+        log('  …which self-provisions them from the committed join token. Commit .convene/project.json.');
+    }
+    else {
+        log('Teammate onboarding:');
+        log(`  ${brand_1.BRAND.bin} login --api-key -   # paste a cvk_ key issued by an owner`);
+        log(`  ${brand_1.BRAND.bin} init --slug ${slug}`);
+    }
+}

package/dist/commands/join.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.join = join;
+/**
+ * `convene join` — self-provision / plug in. The single verb for both cases:
+ *   - Not logged in yet  → redeems the token, CREATES your identity + key.
+ *   - Already logged in  → redeems the token to ADD your existing identity to
+ *                          this project (no new key). Idempotent if already a member.
+ * Then registers the per-prompt hook. Token + handle/email default from
+ * .convene/project.json and git config.
+ */
+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 join(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 — pass --token <cvj_…>, set CONVENE_JOIN_TOKEN, or ask an owner for one');
+    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 (adds existing identity);
+    // unauthenticated mode otherwise (creates a new identity + key).
+    const api = new api_1.ConveneApi(baseUrl, cfg.apiKey ?? null);
+    const res = await api.join(slug, { token, handle, email, display_name: handle, tool: 'cli' }, 10_000);
+    if (res.status === 409)
+        (0, ctx_1.die)(`the handle "${handle}" is already taken — re-run with --handle <unique-handle>`);
+    if (res.status === 401 && cfg.apiKey)
+        (0, ctx_1.die)('join token is invalid/expired/revoked, or your saved key is bad — ask an owner');
+    if (res.status === 401)
+        (0, ctx_1.die)('join token is invalid, expired, or revoked — ask an owner for a fresh one');
+    if (res.status === 403)
+        (0, ctx_1.die)(res.error || 'cannot join: your account is in a different org');
+    if (!res.ok && res.status !== 200)
+        (0, ctx_1.die)(`join failed (${res.status}): ${res.error ?? 'unknown error'}`);
+    const memberHandle = res.json?.member?.handle ?? handle;
+    if (res.json?.api_key) {
+        // New identity created — save the key.
+        (0, config_1.saveFileConfig)({ apiKey: res.json.api_key, baseUrl, member: memberHandle });
+        log(`Joined "${slug}" as ${memberHandle} (new identity). Logged in (config 0600).`);
+    }
+    else if (res.json?.already) {
+        log(`Already a member of "${slug}" as ${memberHandle}. You're operational.`);
+    }
+    else {
+        log(`Added to "${slug}" as ${memberHandle}.`);
+    }
+    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.');
+    // The tool-agnostic backstop: auto-post a [STATUS] when you push (works even
+    // for tools without a per-prompt hook).
+    if (top) {
+        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].');
+        }
+        else if (gh.status === 'skipped-foreign') {
+            log(`Git pre-push hook skipped — core.hooksPath is "${gh.hooksPath}"; add \`convene notify-push "$@"\` to it.`);
+        }
+        else if (gh.status === 'skipped-localhooks') {
+            log(`Git pre-push hook skipped — existing hooks in ${gh.hooksDir}; add \`convene notify-push "$@"\` to your pre-push.`);
+        }
+    }
+    log(`You are operational on ${brand_1.BRAND.product}. Try: convene whoami`);
+}

package/dist/commands/migrate.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrate = migrate;
+/**
+ * `convene migrate` — Observability cutover helper. Runs `init` for this repo,
+ * then prints the cutover reminders. The full, ordered runbook lives in
+ * MIGRATION_OBSERVABILITY.md (it is a deliverable, not executed automatically).
+ */
+const init_1 = require("./init");
+const log = (m) => process.stdout.write(m + '\n');
+async function migrate(opts) {
+    log('Convene migration helper — cutting this repo over to Convene.');
+    log('Full ordered runbook: MIGRATION_OBSERVABILITY.md\n');
+    await (0, init_1.init)(opts);
+    log('');
+    log('Cutover reminders (see the runbook for exact commands):');
+    log('  1. Replace any old `coord-fetch.sh` UserPromptSubmit hook in ~/.claude/settings.json with `convene fetch`.');
+    log('  2. Remove legacy Slack / PowerShell / curl coordination hooks.');
+    log('  3. Retire coord-identity / coord-repos / coord.env and ROTATE the old Slack token.');
+    log('  4. Humans use the Convene dashboard as the backstop view.');
+}

package/dist/commands/notify.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parsePrePush = parsePrePush;
+exports.summarizePush = summarizePush;
+exports.idemKey = idemKey;
+exports.notifyPush = notifyPush;
+/**
+ * `convene notify-push` — the git pre-push hook's bus poster. Fail-OPEN like
+ * `convene fetch` (P0-FAILSAFE): any error, missing config, or non-bus repo exits
+ * 0 silently, so it can NEVER block a push. Every path force-exits via done() (a
+ * lingering keep-alive/abort socket must not extend the process and stall the
+ * push); a 5s watchdog backstops anything that still hangs in async code.
+ *
+ * It reads git's pre-push payload from stdin — one line per pushed ref,
+ * `<local_ref> <local_sha> <remote_ref> <remote_sha>` — to summarize exactly what
+ * is being pushed, and posts ONE [STATUS] with a DETERMINISTIC idempotency key
+ * keyed on the (ref, local sha, remote sha) tuples, so a retried/identical push
+ * dedupes while genuinely new work (a new branch, a second remote, a force-push)
+ * always posts.
+ */
+const config_1 = require("../config");
+const git_1 = require("../git");
+const api_1 = require("../api");
+const isZero = (sha) => /^0+$/.test(sha);
+/** Parse git's pre-push stdin into the non-deletion refs being pushed. */
+function parsePrePush(stdin) {
+    const refs = [];
+    for (const line of stdin.split('\n')) {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length < 4)
+            continue;
+        const [localRef, localSha, , remoteSha] = parts;
+        if (!localSha || isZero(localSha))
+            continue; // branch/tag deletion — nothing landed
+        const isTag = localRef.startsWith('refs/tags/');
+        const branch = isTag
+            ? `tag:${localRef.replace(/^refs\/tags\//, '')}`
+            : localRef.replace(/^refs\/heads\//, '');
+        refs.push({ branch, localSha, remoteSha: remoteSha || '', isNew: !remoteSha || isZero(remoteSha), isTag });
+    }
+    return refs;
+}
+function clip(s, max) {
+    return s.length <= max ? s : s.slice(0, max - 1) + '…';
+}
+/** A one-line human summary of the push (the [STATUS] body). */
+function summarizePush(refs, cwd) {
+    const r = refs[0];
+    const subject = (0, git_1.commitSubject)(r.localSha, cwd) || '(no commit message)';
+    const short = (0, git_1.shortSha)(r.localSha, cwd) || r.localSha.slice(0, 7);
+    let head;
+    if (r.isTag) {
+        head = `pushed ${r.branch.replace(/^tag:/, 'tag ')}`;
+    }
+    else if (r.isNew) {
+        head = `pushed new branch ${r.branch}`;
+    }
+    else if (!r.remoteSha) {
+        head = `pushed ${r.branch}`; // remote tip unknown (manual run)
+    }
+    else if (!(0, git_1.isAncestor)(r.remoteSha, r.localSha, cwd)) {
+        head = `force-pushed ${r.branch}`; // history rewritten — a plain count would mislead
+    }
+    else {
+        const n = (0, git_1.revListCount)(`${r.remoteSha}..${r.localSha}`, cwd);
+        head = n && n > 0 ? `pushed ${n} commit${n === 1 ? '' : 's'} to ${r.branch}` : `pushed to ${r.branch}`;
+    }
+    let body = `${head} · ${subject} (${short})`;
+    const more = refs.length - 1;
+    if (more > 0)
+        body += ` (+${more} more ref${more === 1 ? '' : 's'})`;
+    return clip(body, 200);
+}
+/** Deterministic dedupe key: the full (ref, local, remote) tuples, order-independent. */
+function idemKey(slug, refs) {
+    return `push:${slug}:${refs.map((r) => `${r.branch}@${r.localSha}<-${r.remoteSha}`).sort().join(',')}`;
+}
+/**
+ * Read git's pre-push payload from stdin — ASYNCHRONOUSLY and timeout-bounded, so
+ * a stdin that never closes (an idle pipe held open by a wrapper) can't wedge the
+ * event loop the way a synchronous readFileSync(0) would. git writes the payload
+ * and closes the pipe immediately, so 'end' normally fires in well under a
+ * millisecond; the timeout only matters for pathological callers. A TTY (manual
+ * run) reads nothing and falls through to the HEAD summary.
+ */
+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();
+    });
+}
+async function run(opts) {
+    const cfg = (0, config_1.resolveConfig)();
+    const top = (0, git_1.gitToplevel)();
+    const cwd = top || process.cwd();
+    const slug = opts.project || (0, config_1.loadProjectConfig)(top)?.slug || null;
+    if (!slug)
+        return; // not a bus repo — silent no-op, exactly like `convene fetch`
+    const stdin = await readStdin(1500);
+    let refs;
+    if (stdin !== null) {
+        // Invoked by git: trust the payload. No non-deletion refs ⇒ nothing landed ⇒ no-op.
+        refs = parsePrePush(stdin);
+        if (!refs.length)
+            return;
+    }
+    else {
+        // Manual run with no pipe — synthesize a ref from HEAD as a convenience.
+        const localSha = (0, git_1.revParse)('HEAD', cwd);
+        if (!localSha)
+            return; // nothing meaningful to say
+        refs = [{ branch: (0, git_1.currentBranch)(cwd) || 'HEAD', localSha, remoteSha: '', isNew: false, isTag: false }];
+    }
+    const body = summarizePush(refs, cwd);
+    const idem = idemKey(slug, refs);
+    if (opts.dryRun) {
+        process.stdout.write(body + '\n');
+        return;
+    }
+    // Credentials are only needed for the real post (dry-run works offline).
+    if (!cfg.apiKey || !cfg.member)
+        return;
+    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`);
+    }
+}
+async function notifyPush(opts) {
+    // Backstop only: every path below force-exits via done(), so the process never
+    // lingers on a keep-alive/orphaned socket and stalls the push. The watchdog
+    // catches anything that hangs in async code despite that.
+    const watchdog = setTimeout(() => process.exit(0), 5000);
+    const done = () => {
+        clearTimeout(watchdog);
+        process.exit(0);
+    };
+    try {
+        await run(opts);
+    }
+    catch {
+        /* fail-open: a coordination post must never break a push */
+    }
+    done();
+}

package/dist/commands/post.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolve = exports.decline = exports.accept = exports.ack = void 0;
+exports.postStatus = postStatus;
+exports.postQuestion = postQuestion;
+exports.postPropose = postPropose;
+exports.answer = answer;
+/**
+ * Outbound + interactive verbs. Unlike `fetch`, these are NON-silent: on failure
+ * they print to stderr and exit non-zero so the agent tells the human.
+ */
+const ctx_1 = require("../ctx");
+async function send(slug, body) {
+    const ctx = (0, ctx_1.getContext)({ project: slug === '__cwd__' ? undefined : slug });
+    const realSlug = (0, ctx_1.requireSlug)(ctx);
+    const res = await ctx.api.post(realSlug, body, (0, ctx_1.uuid)());
+    if (!res.ok)
+        (0, ctx_1.die)(`post failed (${res.status}): ${res.error ?? 'unknown error'}`);
+    return res.json?.message;
+}
+async function postStatus(body, opts) {
+    const m = await send(opts.project ?? '__cwd__', { type: 'status', body });
+    process.stdout.write(`posted [STATUS] ${m.short_id}\n`);
+}
+async function postQuestion(body, opts) {
+    // Pass `to` through as-is (undefined when omitted => dropped by JSON.stringify
+    // => "anyone"); never coerce to null.
+    const m = await send(opts.project ?? '__cwd__', { type: 'question', body, to: opts.to });
+    process.stdout.write(`posted [QUESTION] ${m.short_id}${opts.to ? ` to ${opts.to}` : ' (anyone)'}\n`);
+}
+async function postPropose(opts) {
+    if (!opts.to)
+        (0, ctx_1.die)('propose requires --to <member>');
+    if (!opts.prompt)
+        (0, ctx_1.die)('propose requires --prompt "<literal next prompt>"');
+    const m = await send(opts.project ?? '__cwd__', {
+        type: 'propose_prompt',
+        to: opts.to,
+        to_session_glob: opts.sessionGlob,
+        context: opts.context,
+        prompt: opts.prompt,
+    });
+    process.stdout.write(`posted [PROPOSE-PROMPT] ${m.short_id} to ${opts.to}\n`);
+}
+async function answer(id, body, opts) {
+    const m = await send(opts.project ?? '__cwd__', { type: 'answer', in_reply_to: id, body });
+    process.stdout.write(`answered ${id} (${m.short_id})\n`);
+}
+async function transition(id, action, body) {
+    const ctx = (0, ctx_1.getContext)();
+    const res = await ctx.api.transition(id, action, body);
+    if (res.status === 409)
+        (0, ctx_1.die)(`already closed — ${id} was resolved by someone else`);
+    if (!res.ok)
+        (0, ctx_1.die)(`${action} failed (${res.status}): ${res.error ?? 'unknown error'}`);
+    process.stdout.write(`${action}d ${id}\n`);
+}
+const ack = (id) => transition(id, 'ack');
+exports.ack = ack;
+const accept = (id) => transition(id, 'accept');
+exports.accept = accept;
+const decline = (id, opts) => transition(id, 'decline', { reason: opts.reason });
+exports.decline = decline;
+const resolve = (id) => transition(id, 'resolve');
+exports.resolve = resolve;