convene-cli 1.0.4 → 1.1.0

package/dist/commands/deploy.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deploy = deploy;
+/**
+ * `convene deploy` (WP6) — the ONE verb a human learns. It claims the deploy lane
+ * and runs the compatibility verdict in one shot, then prints what to do.
+ *
+ * DIE-LOUD (exit 1) on a confirmed conflict — this is the explicit, human-run
+ * counterpart to the fail-open `gate-push`/`guard` HOOKS (those are Wave 4 and
+ * NOT implemented here). One verb cannot be both postures, so they are split.
+ *
+ *   convene deploy [--lane <name>] [--eta <min>] [--break-glass [--reason <s>]]
+ *
+ * Lane is LANE-AUTHORITATIVE (server-enforced); the compat (behind-HEAD) half is
+ * advisory and client-attested. holder_instance is server-stamped from the
+ * X-Convene-Session-Instance header this client attaches.
+ *
+ * --break-glass / CONVENE_DEPLOY_BREAKGLASS=1: self-authorized escape hatch.
+ * It force-takes the lane and posts a loud audited status naming who/why — the
+ * observable alternative to silently disabling a hook.
+ */
+const ctx_1 = require("../ctx");
+const cache_1 = require("../cache");
+const git_1 = require("../git");
+const LANE_TIMEOUT_MS = 2500; // explicit short timeout — NEVER the 10s default
+/** Canonical lane name for the current branch (deploy:<ref>), or the override. */
+function resolveLaneName(opts, cwd) {
+    if (opts.lane)
+        return opts.lane.includes(':') ? opts.lane : `deploy:refs/heads/${opts.lane}`;
+    const branch = (0, git_1.currentBranch)(cwd) || 'main';
+    return `deploy:refs/heads/${branch}`;
+}
+async function deploy(opts = {}) {
+    const ctx = (0, ctx_1.getContext)({ project: opts.project });
+    const slug = (0, ctx_1.requireSlug)(ctx);
+    const instance = (0, cache_1.ensureSessionInstance)(slug);
+    ctx.api.withInstance(instance);
+    const top = (0, git_1.gitToplevel)();
+    const cwd = top || process.cwd();
+    const lane = resolveLaneName(opts, cwd);
+    const breakGlass = opts.breakGlass || process.env.CONVENE_DEPLOY_BREAKGLASS === '1';
+    if (breakGlass) {
+        // Force-take the lane (owner-gated server-side) + post a loud audited status.
+        const fr = await ctx.api.laneForceRelease(slug, lane, LANE_TIMEOUT_MS);
+        if (fr.status === 403)
+            (0, ctx_1.die)('break-glass force-release is owner-only — you are not a project owner.');
+        const who = ctx.member;
+        const reason = opts.reason ? ` — ${opts.reason}` : '';
+        await ctx.api.post(slug, { type: 'status', body: `BREAK-GLASS deploy on ${lane} by @${who}${reason}` }, (0, ctx_1.uuid)(), LANE_TIMEOUT_MS);
+    }
+    // Claim the lane (LANE-AUTHORITATIVE). A foreign hold → die-loud 409.
+    const claim = await ctx.api.laneClaim(slug, lane, { eta_minutes: opts.eta ?? null, intent: 'deploy' }, LANE_TIMEOUT_MS);
+    if (claim.status === 409) {
+        const h = claim.json?.details ?? claim.json ?? {};
+        const holder = h.holder_handle ? `@${h.holder_handle}` : 'another session';
+        (0, ctx_1.die)(`deploy lane ${lane} is HELD by ${holder}. ` +
+            'Wait for release, retry with --break-glass (audited), or (owners) `convene lane release --force`.');
+    }
+    if (!claim.ok || !claim.json?.granted) {
+        (0, ctx_1.die)(`could not claim deploy lane (${claim.status}): ${claim.error ?? 'unknown error'}`);
+    }
+    // Compat verdict (advisory): attest HEAD; the server returns allow/rebase/wait.
+    const headSha = (0, git_1.revParse)('HEAD', cwd) ?? '';
+    const verdict = await ctx.api.gatePush(slug, { head_sha: headSha, refs: [lane.replace(/^deploy:/, '')] }, LANE_TIMEOUT_MS);
+    const v = verdict.ok ? verdict.json?.verdict : 'allow';
+    if (v === 'rebase') {
+        process.stdout.write(`convene: lane ${lane} claimed — but HEAD is behind origin. Run \`git pull --rebase\` then push.\n`);
+        return;
+    }
+    process.stdout.write(`convene: lane ${lane} claimed — clear to deploy. Release with \`convene lane release ${lane}\` when done.\n`);
+}

package/dist/commands/fetch.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.runFetch = runFetch;
 /**
@@ -14,23 +17,69 @@ exports.runFetch = runFetch;
  *     a 4s fetch timeout bounds the slow path; a failed fetch falls back to the
  *     stale cache and renders DEGRADED (loud-but-non-blocking).
  */
+const node_fs_1 = __importDefault(require("node:fs"));
 const git_1 = require("../git");
 const config_1 = require("../config");
 const cache_1 = require("../cache");
 const api_1 = require("../api");
 const render_1 = require("../render");
+const catchup_1 = require("./catchup");
 const CACHE_TTL_SEC = 3;
 const FETCH_TIMEOUT_MS = 4000;
 const WATCHDOG_MS = 6000;
-function emit(block) {
+/**
+ * Write a rendered block. In `codexHook` mode, wrap it in Codex's UserPromptSubmit
+ * hook envelope so its `additionalContext` lands in the model's per-turn context;
+ * otherwise write the raw block (the Claude Code hook reads stdout directly).
+ */
+function emit(block, codexHook) {
+    if (codexHook) {
+        process.stdout.write(JSON.stringify({
+            hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: block },
+        }) + '\n');
+        return;
+    }
     process.stdout.write(block + '\n');
 }
+/**
+ * Codex passes the hook a JSON object on stdin including `cwd`. Read it best-effort
+ * to resolve the repo when the hook runs from elsewhere. Never blocks on a TTY and
+ * never throws — a missing/garbled payload just means "use the current cwd".
+ */
+function codexCwdFromStdin() {
+    try {
+        if (process.stdin.isTTY)
+            return null;
+        const raw = node_fs_1.default.readFileSync(0, 'utf8');
+        if (!raw)
+            return null;
+        const j = JSON.parse(raw);
+        return typeof j?.cwd === 'string' && j.cwd ? j.cwd : null;
+    }
+    catch {
+        return null;
+    }
+}
 function toRenderMessages(arr) {
     return Array.isArray(arr) ? arr : [];
 }
 async function runFetch(opts = {}) {
     // Absolute watchdog: under any circumstance, do not hold the prompt past 6s.
     const watchdog = setTimeout(() => process.exit(0), WATCHDOG_MS);
+    // Codex hook: honor the stdin `cwd` so the repo resolves correctly, and force
+    // `--json` off (codex-hook is its own output envelope).
+    if (opts.codexHook) {
+        opts = { ...opts, json: false };
+        const cwd = codexCwdFromStdin();
+        if (cwd) {
+            try {
+                process.chdir(cwd);
+            }
+            catch {
+                /* ignore — fall back to the current cwd */
+            }
+        }
+    }
     try {
         const top = (0, git_1.gitToplevel)();
         if (!top)
@@ -54,7 +103,25 @@ async function runFetch(opts = {}) {
                 openItems: [],
                 recent: [],
                 health: { state: 'note', line: 'convene: not configured — run `convene login` (coordination context unavailable)' },
-            }));
+            }), opts.codexHook);
+            return done(0);
+        }
+        // `--since-last`: render the catch-up digest since the read cursor instead
+        // of the time-windowed feed. Read-only (no advance), fail-open. Suppressed if
+        // SessionStart already surfaced a catch-up this boot (per-instance sentinel).
+        if (opts.sinceLast) {
+            const instance = (0, cache_1.readSessionInstance)(slug);
+            if (instance && (0, cache_1.catchupAlreadySurfaced)(slug, instance))
+                return done(0); // already shown this boot
+            const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+            const res = await api.sessionOpen(slug, { advance: false }, FETCH_TIMEOUT_MS);
+            if (res.ok && res.json && !res.json.degraded) {
+                if (opts.json)
+                    emit(JSON.stringify(res.json));
+                else
+                    emit((0, render_1.renderSessionOpenBlock)({ slug, member, session, digest: (0, catchup_1.toDigest)(res.json) }), opts.codexHook);
+            }
+            // DEGRADED/failure under --since-last emits nothing (structural suppression).
             return done(0);
         }
         // Cache short-circuit for rapid successive prompts.
@@ -86,7 +153,7 @@ async function runFetch(opts = {}) {
             openItems: toRenderMessages(cache?.data?.inbox ?? []),
             recent: toRenderMessages(cache?.data?.messages ?? []),
             health,
-        }));
+        }), opts.codexHook);
         return done(0);
     }
     catch {
@@ -110,6 +177,6 @@ async function runFetch(opts = {}) {
             openItems: toRenderMessages(data?.inbox ?? []),
             recent: toRenderMessages(data?.messages ?? []),
             health: { state: 'ok', syncedAgoSec: ctx.syncedAgoSec, openCount: Number(data?.open_for_you ?? (data?.inbox?.length ?? 0)) },
-        }));
+        }), opts.codexHook);
     }
 }

package/dist/commands/gate-push.js

@@ -0,0 +1,331 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatePush = gatePush;
+/**
+ * `convene gate-push` (WP9) — the PUSH GATE. Wired as a PreToolUse hook on
+ * `Bash(git push …)` (PreToolUse mode) and a PostToolUse hook (`--post`) that
+ * releases the lane. The hook WIRING itself is the WP13 capstone — this file is
+ * only the verb.
+ *
+ * POSTURE = FAIL-OPEN-LOUD (P0-FAILSAFE):
+ *   - A top-level watchdog force-exits 0 at WATCHDOG_MS=4000 no matter what, so a
+ *     hung network/git can NEVER wedge a push.
+ *   - Network calls (claim / lane-state) use an EXPLICIT short timeout (2500ms),
+ *     never the api.ts 10s default; local git (isAncestor/revParse) runs in
+ *     PARALLEL with the network call.
+ *   - TRANSPORT failure (ApiResult.status===0 = connection-refused/DNS) →
+ *     fail-OPEN-LOUD immediately (exit 0 + a `systemMessage` "deploy lane
+ *     UNVERIFIED — proceeding UNGATED").
+ *   - TIMEOUT / 5xx (bus up but contended) → retry 2× with backoff INSIDE the
+ *     watchdog, then still fail-open-loud + best-effort post a [STATUS]
+ *     "gate skipped" so the skip is auditable in real time.
+ *
+ * exit 2 (BLOCK) ONLY on a CONFIRMED positive:
+ *   (a) LANE_HELD by a DIFFERENT instance (409 from the claim CAS), OR
+ *   (b) an open DIRECTED HALT for this session (from lane-state.halts), OR
+ *   (c) HEAD CONFIRMED-BEHIND after `git fetch origin <ref>` then
+ *       isAncestor(remote, HEAD) === false.
+ * A SOFT foreign-lane conflict (a foreign live lane but no directed halt) is NOT
+ * a hard deny — it emits permissionDecision:'ask'.
+ *
+ * Auto-CLAIM on the way through: when the lane is free we CLAIM it (serialize via
+ * the server CAS, not a read-then-decide race). --post releases it (on success
+ * AND failure), an idempotent no-op if this instance no longer holds.
+ *
+ * --break-glass / CONVENE_DEPLOY_BREAKGLASS=1 → exit 0 + a loud audited takeover.
+ *
+ * NEVER calls die() and NEVER routes through ctx.getContext() (which die()s on a
+ * missing config) — it owns its own watchdog exactly like fetch.ts.
+ *
+ * The exit-2 stderr reason is a FIXED TEMPLATE with NO free-text interpolation of
+ * intent / holder_session / body — only a validated holder_handle, a numeric
+ * heartbeat age, and the one-step recovery hint.
+ */
+const git_1 = require("../git");
+const config_1 = require("../config");
+const cache_1 = require("../cache");
+const api_1 = require("../api");
+const guard_1 = require("./guard");
+const WATCHDOG_MS = 4000;
+const NET_TIMEOUT_MS = 2500; // explicit short timeout — NEVER the api.ts 10s default
+const RETRIES = 2;
+/** Only `holder_handle` (validated) reaches the model-facing reason. */
+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';
+}
+function fmtAge(sec) {
+    const n = typeof sec === 'number' && Number.isFinite(sec) ? Math.max(0, Math.round(sec)) : null;
+    if (n == null)
+        return 'unknown';
+    if (n < 60)
+        return `${n}s`;
+    const m = Math.round(n / 60);
+    return m < 60 ? `${m}m` : `${Math.floor(m / 60)}h`;
+}
+/** A transport failure (connection-refused/DNS) is status 0; a timeout/5xx is "up but contended". */
+function isTransportFailure(status) {
+    return status === 0;
+}
+function isRetryable(status) {
+    // 408 request-timeout, 429 too-many, 5xx — bus up but contended → retry inside the watchdog.
+    return status === 408 || status === 429 || status >= 500;
+}
+/** Parse git's pre-push stdin into the deploy-ish ref(s) being pushed. */
+function parseRefsFromStdin(stdin) {
+    const refs = [];
+    for (const line of stdin.split('\n')) {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length < 4)
+            continue;
+        const [localRef, localSha] = parts;
+        if (!localSha || /^0+$/.test(localSha))
+            continue; // deletion — nothing landed
+        if (localRef.startsWith('refs/heads/') || localRef.startsWith('refs/tags/'))
+            refs.push(localRef);
+    }
+    return refs;
+}
+/** Async, timeout-bounded stdin read (git closes the pipe immediately). */
+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();
+    });
+}
+function emitJson(obj) {
+    process.stdout.write(JSON.stringify(obj) + '\n');
+}
+/** PreToolUse "allow but tell the human" verdict — NOT a hard deny. */
+function ask(reason) {
+    emitJson({
+        hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'ask', permissionDecisionReason: reason },
+    });
+}
+/** A loud, non-blocking advisory (fail-open) surfaced to the agent. */
+function loudOpen(systemMessage) {
+    emitJson({ systemMessage });
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function run(opts) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        return 0; // not a git repo → no-op
+    const cwd = top;
+    const proj = (0, config_1.loadProjectConfig)(top);
+    const slug = opts.project || proj?.slug || null;
+    if (!slug)
+        return 0; // repo not on the bus → no-op (zero network)
+    const cfg = (0, config_1.resolveConfig)();
+    const member = cfg.member;
+    const session = member ? (0, git_1.sessionId)(member, top) : null;
+    // Determine the ref(s) being pushed.
+    let refs;
+    if (opts.stdin) {
+        const stdin = await readStdin(1500);
+        const trimmed = (stdin ?? '').trim();
+        if (trimmed.startsWith('{')) {
+            // Claude Code PreToolUse/PostToolUse payload (JSON). Gate ONLY a real
+            // `git push` — classify the command with the SAME anchored classifier as
+            // `guard`, so an ordinary Bash command (even one whose ARGS contain
+            // "deploy"/"release"/a ref name) is a zero-network no-op and NEVER claims a
+            // lane. A bare `git push` (no refspec) falls back to the current branch.
+            const cls = (0, guard_1.classifyCommand)((0, guard_1.commandFromPayload)(stdin));
+            if (cls.kind === 'push') {
+                const cb = (0, git_1.currentBranch)(cwd);
+                refs = cls.refs.length ? cls.refs : cb ? [`refs/heads/${cb}`] : [];
+            }
+            else {
+                refs = [];
+            }
+        }
+        else {
+            // git pre-push hook context: real refspecs arrive on stdin.
+            refs = stdin ? parseRefsFromStdin(stdin) : [];
+            if (!refs.length) {
+                const b = (0, git_1.currentBranch)(cwd);
+                refs = b ? [`refs/heads/${b}`] : [];
+            }
+        }
+    }
+    else {
+        // Explicit invocation (e.g. `convene deploy`): gate the current branch.
+        const b = (0, git_1.currentBranch)(cwd);
+        refs = b ? [`refs/heads/${b}`] : [];
+    }
+    // A deploy ref is one the anchored classifier recognizes (heads/main, tags, …).
+    const deployRefs = refs.filter((r) => (0, guard_1.classifyPushRefs)(r));
+    const ref = deployRefs[0] ?? refs[0] ?? 'refs/heads/main';
+    const lane = `deploy:${ref}`;
+    // PostToolUse: release the lane (idempotent no-op if we no longer hold it).
+    if (opts.post) {
+        if (!cfg.apiKey || !session)
+            return 0;
+        const instance = (0, cache_1.ensureSessionInstance)(slug);
+        const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+        await api.laneRelease(slug, lane, NET_TIMEOUT_MS).catch(() => undefined);
+        return 0;
+    }
+    // Non-deploy ref → allow instantly with ZERO network.
+    if (!deployRefs.length)
+        return 0;
+    // Break-glass: self-authorized takeover. Exit 0 + a loud audited status.
+    const breakGlass = opts.breakGlass || process.env.CONVENE_DEPLOY_BREAKGLASS === '1';
+    // Not authenticated → fail-OPEN-loud (we cannot verify the lane).
+    if (!cfg.apiKey || !session) {
+        loudOpen('convene: deploy lane 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);
+    if (breakGlass) {
+        // Self-authorized: the verdict is ALLOW (exit 0) regardless of the bus. Emit
+        // the loud audited advisory FIRST, then do the force-take + status + claim as
+        // BEST-EFFORT in parallel under a single short cap — so a slow/unreachable bus
+        // can never push break-glass past the watchdog (it must still exit 0 promptly).
+        loudOpen(`convene: BREAK-GLASS — forced deploy lane ${lane}. This takeover is audited.`);
+        await Promise.race([
+            Promise.allSettled([
+                api.laneForceRelease(slug, lane, NET_TIMEOUT_MS),
+                api.post(slug, { type: 'status', body: `BREAK-GLASS deploy on ${lane} by @${member}` }, `bg:${lane}:${Date.now()}`, NET_TIMEOUT_MS),
+                api.laneClaim(slug, lane, { intent: 'deploy' }, NET_TIMEOUT_MS),
+            ]),
+            sleep(NET_TIMEOUT_MS), // never block the exit-0 verdict longer than one timeout
+        ]).catch(() => undefined);
+        return 0;
+    }
+    if (opts.dryRun) {
+        loudOpen(`convene: gate-push would gate lane ${lane} (dry-run, no network).`);
+        return 0;
+    }
+    // ── Local git (compat) runs in PARALLEL with the network claim ──────────────
+    const headSha = (0, git_1.revParse)('HEAD', cwd) ?? '';
+    // The compat check fetches the real remote tip, then tests fast-forward.
+    const compatP = (async () => {
+        try {
+            const fetched = (0, git_1.gitFetch)(ref, 'origin', cwd);
+            if (!fetched)
+                return { behind: false }; // can't verify → don't block on compat
+            const remote = (0, git_1.revParse)(`origin/${ref.replace(/^refs\/heads\//, '')}`, cwd) ?? (0, git_1.revParse)(`origin/${ref}`, cwd);
+            if (!remote || !headSha)
+                return { behind: false };
+            // behind ⇔ remote is NOT an ancestor of HEAD (a non-fast-forward push).
+            return { behind: !(0, git_1.isAncestor)(remote, headSha, cwd) };
+        }
+        catch {
+            return { behind: false };
+        }
+    })();
+    // ── Network claim with transport/timeout discrimination + retry ─────────────
+    let claimRes = null;
+    for (let attempt = 0; attempt <= RETRIES; attempt++) {
+        claimRes = await api.laneClaim(slug, lane, { intent: 'deploy' }, NET_TIMEOUT_MS);
+        if (claimRes.status === 200 || claimRes.status === 409)
+            break; // resolved
+        if (isTransportFailure(claimRes.status)) {
+            // Genuinely unreachable → fail-OPEN-loud immediately, no retry.
+            loudOpen(`convene: deploy lane UNVERIFIED — bus unreachable, proceeding UNGATED on ${lane}.`);
+            return 0;
+        }
+        if (!isRetryable(claimRes.status))
+            break;
+        if (attempt < RETRIES)
+            await sleep(150 * (attempt + 1)); // backoff inside the watchdog
+    }
+    // 409 LANE_HELD by a different instance → check for a directed halt (hard) vs
+    // soft foreign lane (ask). exit 2 only on a CONFIRMED positive.
+    if (claimRes && claimRes.status === 409) {
+        const d = claimRes.json?.details ?? claimRes.json ?? {};
+        const holder = safeHandle(d.holder_handle);
+        // Is there an open DIRECTED HALT for this session? That is a HARD block.
+        const halt = await directedHaltFor(api, slug, ref);
+        if (halt) {
+            blockReason(`convene: BLOCKED — an active halt is directed at this session. Surface to the human; do not push.`);
+            return 2;
+        }
+        // Soft foreign-lane conflict: ask, don't hard-deny.
+        const age = fmtAge(typeof d.heartbeat_age_sec === 'number' ? d.heartbeat_age_sec : undefined);
+        ask(`Deploy lane ${lane} is held by ${holder} (heartbeat ${age} ago). ` +
+            `To proceed anyway: \`convene deploy --break-glass\` (audited), or wait for release. Allow this push?`);
+        return 0;
+    }
+    // Timeout/5xx after retries (bus up but contended) → fail-OPEN-LOUD + audit post.
+    if (!claimRes || (claimRes.status !== 200 && claimRes.status !== 409)) {
+        await api
+            .post(slug, { type: 'status', body: `gate skipped on ${lane} — bus contended/unverified at push time` }, `gateskip:${lane}:${Date.now()}`, NET_TIMEOUT_MS)
+            .catch(() => undefined);
+        loudOpen(`convene: deploy lane UNVERIFIED — bus contended, proceeding UNGATED on ${lane} (skip posted).`);
+        return 0;
+    }
+    // 200 → we hold the lane (claimed fresh or self-reclaimed). Now the COMPAT gate.
+    const compat = await compatP;
+    if (compat.behind) {
+        // Behind HEAD after a fresh fetch → CONFIRMED positive → release + hard block.
+        await api.laneRelease(slug, lane, NET_TIMEOUT_MS).catch(() => undefined);
+        blockReason(`convene: BLOCKED — HEAD is behind origin/${ref.replace(/^refs\/heads\//, '')} after fetch. ` +
+            `Run \`git pull --rebase\` then push again.`);
+        return 2;
+    }
+    // Also honor a directed halt even when the lane was free (defense in depth).
+    const halt = await directedHaltFor(api, slug, ref);
+    if (halt) {
+        await api.laneRelease(slug, lane, NET_TIMEOUT_MS).catch(() => undefined);
+        blockReason(`convene: BLOCKED — an active halt is directed at this session. Surface to the human; do not push.`);
+        return 2;
+    }
+    // Clear: lane claimed, fast-forward. Allow (PostToolUse releases later).
+    return 0;
+}
+/**
+ * Fixed-template block reason on stderr (PreToolUse exit 2 surfaces stderr to the
+ * agent). NO free-text interpolation of intent/holder_session/body.
+ */
+function blockReason(reason) {
+    process.stderr.write(reason + '\n');
+}
+/**
+ * Is there an open halt/interrupt directed at THIS session? The server computes
+ * relevance from principal + session (the client never passes a session string
+ * that authorizes which halts apply). Any uncertainty (transport/parse) → no
+ * halt (fail-open). Returns true only on a confirmed, server-relevance-filtered
+ * directed halt.
+ */
+async function directedHaltFor(api, slug, ref) {
+    const res = await api.laneState(slug, `deploy:${ref}`, NET_TIMEOUT_MS).catch(() => null);
+    if (!res || !res.ok || !res.json)
+        return false; // can't verify → fail-open
+    const halts = Array.isArray(res.json.halts) ? res.json.halts : [];
+    return halts.length > 0;
+}
+async function gatePush(opts = {}) {
+    let code = 0;
+    const watchdog = setTimeout(() => process.exit(0), WATCHDOG_MS);
+    try {
+        code = await run(opts);
+    }
+    catch {
+        code = 0; // fail-open: never wedge a push on our own error
+    }
+    clearTimeout(watchdog);
+    process.exit(code);
+}