convene-cli 1.0.5 → 1.1.1

package/dist/commands/watch.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watch = watch;
+/**
+ * `convene watch` (WP12) — a DETACHED long-poll on the existing /poll stream,
+ * FILTERED to halt/interrupt, that surfaces mid-task halts for a heads-down
+ * agent BETWEEN turns. SessionStart launches it (the hook WIRING is the WP13
+ * capstone — this file is only the verb).
+ *
+ * POSTURE = FAIL-OPEN, self-healing (P0-FAILSAFE):
+ *   - It NEVER crashes the session and NEVER blocks anything: it's a background
+ *     loop that writes a file. It does not die(), does not getContext().
+ *   - It self-heals via a Last-Event-ID resume cursor: a transport failure /
+ *     timeout / parse error just sleeps with backoff and retries; the resume seq
+ *     means a reconnect never re-reads or skips material.
+ *   - A bounded run (no live config / not on the bus) exits 0 silently so a
+ *     SessionStart launch on a non-bus repo is a no-op.
+ *
+ * APPEND-ONLY + HIGH-WATER (awareness/concurrency #5 — the lost-interrupt race):
+ *   - Each matched halt/interrupt is APPENDED to a per-slug jsonl via
+ *     appendWatchEntry. The daemon NEVER truncates the log.
+ *   - Readers (fetch / doctor / the health line) render entries with seq >
+ *     high-water and advance a MONOTONIC high-water with persistHighWater. The
+ *     reader, not the writer, owns the cursor, so a read can never race an append
+ *     into losing an interrupt.
+ *
+ * TRUST: the daemon writes the message TYPE + server-derived routing/handles +
+ * the (UNTRUSTED) body verbatim into the jsonl. The body is NEVER interpreted
+ * here — the consumer renders it inert. The block DECISION is the guard's, from
+ * lane-state; watch only narrows the window for non-deploy turns.
+ *
+ * --notify: best-effort desktop ping per surfaced halt (delegates to the notify
+ * verb's mechanism if present; otherwise silently skipped). Never blocks the loop.
+ */
+const node_child_process_1 = require("node:child_process");
+const git_1 = require("../git");
+const config_1 = require("../config");
+const cache_1 = require("../cache");
+const api_1 = require("../api");
+const POLL_WAIT_SEC = 25; // server holds up to ~25s; capped at 50 server-side
+const POLL_TIMEOUT_MS = POLL_WAIT_SEC * 1000 + 5000; // MUST exceed wait*1000
+const BACKOFF_BASE_MS = 1000;
+const BACKOFF_MAX_MS = 30_000;
+const HALT_TYPES = new Set(['halt', 'interrupt']);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Map a server feed/poll message to an inert WatchEntry. Returns null for non-halts. */
+function toEntry(m) {
+    if (!m || typeof m !== 'object')
+        return null;
+    const type = typeof m.type === 'string' ? m.type : '';
+    if (!HALT_TYPES.has(type))
+        return null;
+    // seq is the messages.id (enrich exposes it as `seq`, falling back to numeric id).
+    const seq = typeof m.seq === 'number' ? m.seq : typeof m.id === 'number' ? m.id : Number(m.id);
+    if (!Number.isFinite(seq))
+        return null;
+    return {
+        seq,
+        type,
+        short_id: typeof m.short_id === 'string' ? m.short_id : null,
+        // from/to/body are DISPLAY/UNTRUSTED — copied verbatim, never interpreted here.
+        from: typeof m.from_handle === 'string' ? m.from_handle : typeof m.from === 'string' ? m.from : null,
+        to: typeof m.to === 'string' ? m.to : typeof m.to_member === 'string' ? m.to_member : null,
+        body: typeof m.body === 'string' ? m.body : null,
+        at: typeof m.created_at === 'string' ? m.created_at : null,
+    };
+}
+/** Best-effort desktop notification; never blocks or throws. */
+function notifyBestEffort(entry) {
+    try {
+        if (process.platform === 'darwin') {
+            // A halt is a control signal; the body is UNTRUSTED so we do NOT splice it
+            // into the notification — a fixed template only.
+            (0, node_child_process_1.spawnSync)('osascript', ['-e', 'display notification "An active halt is directed at this session." with title "Convene: halt"'], {
+                timeout: 1500,
+            });
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+async function loop(opts) {
+    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
+    const cfg = (0, config_1.resolveConfig)();
+    const member = cfg.member;
+    const session = member ? (0, git_1.sessionId)(member, top) : null;
+    if (!cfg.apiKey || !session)
+        return 0; // can't authenticate → silent no-op
+    const instance = (0, cache_1.ensureSessionInstance)(slug);
+    const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+    // Resume cursor: start from the persisted high-water so a relaunch never
+    // re-reads material the reader already drained. (The reader's high-water is the
+    // canonical "already surfaced" mark; the daemon resumes from there.)
+    let cursor = (0, cache_1.readWatchHighWater)(slug);
+    let backoff = BACKOFF_BASE_MS;
+    let iterations = 0;
+    const limit = typeof opts.maxIterations === 'number' ? opts.maxIterations : Infinity;
+    // Heartbeat up-front so a just-launched watch reads as healthy immediately.
+    (0, cache_1.touchWatchHeartbeat)(slug);
+    while (iterations < limit) {
+        const res = await api.poll(slug, { since: cursor, wait: POLL_WAIT_SEC }, POLL_TIMEOUT_MS).catch(() => null);
+        // Every loop iteration stamps liveness — even an empty/failed poll proves the
+        // daemon is alive (the health line distinguishes "down" from "quiet").
+        (0, cache_1.touchWatchHeartbeat)(slug);
+        if (!res || !res.ok || !res.json) {
+            // Transport failure / timeout / parse error → self-heal with backoff.
+            await sleep(backoff);
+            backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
+            continue;
+        }
+        backoff = BACKOFF_BASE_MS; // recovered
+        const msgs = Array.isArray(res.json.messages) ? res.json.messages : [];
+        for (const m of msgs) {
+            const entry = toEntry(m);
+            if (!entry)
+                continue;
+            (0, cache_1.appendWatchEntry)(slug, entry);
+            if (opts.notify)
+                notifyBestEffort(entry);
+        }
+        // Advance the resume cursor to the server's reported cursor (monotonic). This
+        // is the long-poll resume seq, NOT the reader's high-water — the daemon must
+        // move past EVERY message it saw (incl. non-halts) or it would re-fetch them
+        // forever. The reader's high-water only advances over rendered halts.
+        if (typeof res.json.cursor === 'number' && res.json.cursor > cursor)
+            cursor = res.json.cursor;
+        iterations++;
+    }
+    return 0;
+}
+async function watch(opts = {}) {
+    let code = 0;
+    try {
+        code = await loop(opts);
+    }
+    catch {
+        code = 0; // fail-open: a background watcher never crashes the session
+    }
+    process.exit(code);
+}

package/dist/commands/worktree.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.worktree = worktree;
+/**
+ * `convene worktree <branch>` — create an isolated git worktree for a parallel
+ * session. This is Convene's recommended default for running several coding agents
+ * on one repo at once: a checkout apiece stops them clobbering each other's
+ * uncommitted files AND (each worktree has its own basename) gives each a distinct
+ * bus identity, so they can see and coordinate with one another instead of
+ * collapsing into one session talking to itself.
+ *
+ * DIE-LOUD like the other interactive verbs (stderr + non-zero exit on failure).
+ * Pure git plumbing — does NOT require the repo to be on the Convene bus.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const git_1 = require("../git");
+const ctx_1 = require("../ctx");
+function refExists(ref, cwd) {
+    const r = (0, node_child_process_1.spawnSync)('git', ['rev-parse', '--verify', '--quiet', ref], { cwd, encoding: 'utf8' });
+    return r.status === 0;
+}
+function worktree(branch, opts = {}) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        (0, ctx_1.die)('not a git repository — run inside a repo');
+    if (!branch || !branch.trim())
+        (0, ctx_1.die)('usage: convene worktree <branch> [--from <ref>] [--path <dir>]');
+    const base = (0, git_1.worktreeBasename)(top);
+    const safeBranch = branch.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'wt';
+    const dest = node_path_1.default.resolve(opts.path || node_path_1.default.join(node_path_1.default.dirname(top), `${base}-${safeBranch}`));
+    if (node_fs_1.default.existsSync(dest))
+        (0, ctx_1.die)(`destination already exists: ${dest}`);
+    const localExists = refExists(`refs/heads/${branch}`, top);
+    const remoteExists = !localExists && refExists(`refs/remotes/origin/${branch}`, top);
+    // Existing local branch → check it out; existing remote-only branch → create a
+    // local tracking branch; otherwise → new branch from --from (or HEAD).
+    const args = localExists
+        ? ['worktree', 'add', dest, branch]
+        : remoteExists
+            ? ['worktree', 'add', '-b', branch, dest, `origin/${branch}`]
+            : ['worktree', 'add', '-b', branch, dest, opts.from || 'HEAD'];
+    const r = (0, node_child_process_1.spawnSync)('git', args, { cwd: top, stdio: 'inherit' });
+    if (r.status !== 0)
+        (0, ctx_1.die)(`git worktree add failed (exit ${r.status ?? '?'})`);
+    const branchNote = localExists ? '' : remoteExists ? ` (new, tracking origin/${branch})` : ' (new)';
+    process.stdout.write([
+        ``,
+        `✓ worktree ready: ${dest}`,
+        `  branch: ${branch}${branchNote}`,
+        ``,
+        `Start a FRESH agent session inside it so it gets its own Convene identity:`,
+        `  cd ${dest}`,
+        `  # install deps for this package if needed, then launch your agent (e.g. \`claude\`)`,
+        ``,
+        `Remove it when done:  git worktree remove ${dest}`,
+        ``,
+    ].join('\n'));
+}

package/dist/exit.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Windows-safe process exit for the hook commands.
+ *
+ * Every Convene hook (fetch, guard, gate-push, session-start, notify-push,
+ * catchup) writes its payload to stdout and then exits. stdout, when the binary
+ * runs as a hook, is a PIPE captured by the host tool (Claude Code / Codex), and
+ * a pipe write on Node is async/buffered. Calling `process.exit()` while that
+ * write is still in flight tears the event loop down mid-write — on Windows that
+ * aborts the process with a libuv assertion (`UV_HANDLE_CLOSING`, win/async.c)
+ * and a 127 exit code. The visible damage is that the host tool sees a failed
+ * hook and SILENTLY DROPS the block we had already printed (reported on
+ * convene-cli v1.0.5, Windows).
+ *
+ * We can't simply fall through to a natural exit: the CLI uses global `fetch`
+ * (undici keeps sockets alive for seconds), which would hold the prompt open
+ * past the latency budget — that's why the hooks force-exit in the first place.
+ * So the fix is to force-exit, but only AFTER stdout has drained.
+ *
+ * `exitClean(code)` waits for stdout to flush, then exits with `code`, capped by
+ * a short unref'd backstop so a stuck stream can never hold the prompt open.
+ * Idempotent: the watchdog and the cooperative exit path can both call it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exitClean = exitClean;
+/** Cap on how long we wait for stdout to drain before forcing the exit. */
+const FLUSH_CAP_MS = 500;
+let exiting = false;
+function exitClean(code) {
+    if (exiting)
+        return;
+    exiting = true;
+    const hardExit = () => process.exit(code);
+    try {
+        // Reader already gone / stream torn down — nothing left to flush.
+        if (process.stdout.writableEnded || process.stdout.destroyed)
+            return hardExit();
+        // An empty write's callback fires only after all previously buffered data has
+        // been handed to the OS (writes drain FIFO), i.e. once the pipe handle is
+        // quiescent and exiting no longer races an in-flight async write.
+        process.stdout.write('', () => hardExit());
+        // Backstop so we never hang on the flush; unref'd so it cannot, by itself,
+        // keep the loop alive past a clean drain.
+        setTimeout(hardExit, FLUSH_CAP_MS).unref();
+    }
+    catch {
+        hardExit();
+    }
+}

package/dist/git.js

@@ -8,6 +8,7 @@ exports.worktreeBasename = worktreeBasename;
 exports.originRemote = originRemote;
 exports.parseGitHubRemote = parseGitHubRemote;
 exports.repoIsPublic = repoIsPublic;
+exports.sessionDiscriminator = sessionDiscriminator;
 exports.sessionId = sessionId;
 exports.gitConfigGet = gitConfigGet;
 exports.deriveHandle = deriveHandle;
@@ -18,6 +19,7 @@ exports.currentBranch = currentBranch;
 exports.revListCount = revListCount;
 exports.revParse = revParse;
 exports.isAncestor = isAncestor;
+exports.gitFetch = gitFetch;
 exports.gitHooksDir = gitHooksDir;
 exports.gitConfigSetLocal = gitConfigSetLocal;
 exports.gitPathIsIgnored = gitPathIsIgnored;
@@ -100,9 +102,53 @@ async function repoIsPublic(cwd = process.cwd()) {
     }
     return null; // non-GitHub host and no gh ⇒ unknown
 }
-/** Derive the ephemeral session tag "<member>/<worktree-basename>". */
+/**
+ * A short, stable per-process discriminator that tells apart concurrent sessions
+ * sharing ONE checkout (same member, same worktree basename). Without it, two
+ * Claude windows `cd`'d into the same repo both resolve to `<member>/<basename>`
+ * — the bus sees one identity talking to itself, and each treats the other's
+ * posts as its own. The signal:
+ *
+ *   1. `CONVENE_SESSION_SUFFIX` — an explicit override any tool/terminal can set
+ *      (sanitized + capped). Lets Codex/plain shells opt a session into a stable
+ *      distinct identity, and makes the behavior testable.
+ *   2. `CLAUDE_CODE_SESSION_ID` — Claude Code exports this to BOTH its hooks and
+ *      every Bash tool call in the same session, so the derived suffix is
+ *      identical across the `fetch`/`session-start` hooks AND any manual
+ *      `convene post`/`lane`/`deploy` call — yet distinct across concurrent
+ *      sessions. We hash it to a short, opaque, tag-safe token.
+ *
+ * Absent both (a plain human terminal) → '' → identity stays exactly
+ * `<member>/<basename>`, unchanged from before.
+ */
+function sessionDiscriminator() {
+    const override = (process.env.CONVENE_SESSION_SUFFIX || '').trim();
+    if (override) {
+        const clean = override.toLowerCase().replace(/[^a-z0-9-]+/g, '').slice(0, 8);
+        if (clean)
+            return clean;
+    }
+    const raw = (process.env.CLAUDE_CODE_SESSION_ID || '').trim();
+    if (!raw)
+        return '';
+    // djb2 → base36, 4 chars: stable for a given session id, collision-safe across
+    // the handful of sessions that realistically share one checkout.
+    let h = 5381;
+    for (let i = 0; i < raw.length; i++)
+        h = ((h * 33) ^ raw.charCodeAt(i)) >>> 0;
+    return h.toString(36).slice(-4).padStart(4, '0');
+}
+/**
+ * Derive the session tag "<member>/<worktree-basename>", with a "#<disc>" suffix
+ * when concurrent same-checkout sessions need disambiguating (see
+ * `sessionDiscriminator`). `#` is safe everywhere the tag travels: the server
+ * splits a session on its FIRST `/` (so member/worktree parsing is unaffected),
+ * `<member>/*` globs still match, and it round-trips through storage + display.
+ */
 function sessionId(member, toplevel) {
-    return `${member}/${worktreeBasename(toplevel)}`;
+    const base = `${member}/${worktreeBasename(toplevel)}`;
+    const disc = sessionDiscriminator();
+    return disc ? `${base}#${disc}` : base;
 }
 function gitConfigGet(key, cwd = process.cwd()) {
     return git(['config', '--get', key], cwd);
@@ -173,6 +219,21 @@ function isAncestor(ancestor, descendant, cwd = process.cwd()) {
         return false;
     }
 }
+/**
+ * Bounded `git fetch <remote> <ref>` for the deploy compat gate. The gate needs
+ * the real remote tip before checking ancestry so "behind" reflects origin, not
+ * a stale tracking ref. Returns true iff the fetch succeeded; a timeout/error
+ * returns false so the caller fails open rather than blocking on a slow network.
+ */
+function gitFetch(ref, remote = 'origin', cwd = process.cwd()) {
+    try {
+        const r = (0, node_child_process_1.spawnSync)('git', ['fetch', '--quiet', remote, ref], { cwd, timeout: 2500 });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
 /** Absolute path to this repo's hooks directory (resolves worktrees/submodules). */
 function gitHooksDir(cwd = process.cwd()) {
     const p = git(['rev-parse', '--git-path', 'hooks'], cwd);

package/dist/githook.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GITHOOK_MARKER = exports.GITHOOKS_DIR = void 0;
+exports.GITHOOK_MARKER_V1 = exports.GITHOOK_MARKER = exports.GITHOOKS_DIR = void 0;
 exports.prePushScript = prePushScript;
 exports.installGitHooks = installGitHooks;
 /**
@@ -22,18 +22,54 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const git_1 = require("./git");
 exports.GITHOOKS_DIR = '.githooks';
-exports.GITHOOK_MARKER = 'convene:githook v1';
-/** The committed pre-push script. Deterministic (P0-IDEMPOTENT). */
+/** Current managed marker. Bumped v1→v2 for the opt-in blocking mode (WP13). */
+exports.GITHOOK_MARKER = 'convene:githook v2';
+/** Prior marker — a hook carrying it is still OURS (upgradeable in place). */
+exports.GITHOOK_MARKER_V1 = 'convene:githook v1';
+/** Markers that identify a pre-push hook as one WE authored (any version). */
+function isOurHook(content) {
+    return content.includes(exports.GITHOOK_MARKER) || content.includes(exports.GITHOOK_MARKER_V1);
+}
+/**
+ * The committed pre-push script. Deterministic (P0-IDEMPOTENT) — a pure function
+ * of its inputs, so re-running init is byte-identical.
+ *
+ * DEFAULT mode is FAIL-OPEN (exit 0): it only posts a [STATUS] via `notify-push`
+ * and never blocks a push — preserving P0-FAILSAFE for every clone.
+ *
+ * OPT-IN BLOCKING mode (per-clone, never committed-on by default) is enabled by
+ * the local git config `convene.blockingPush=true` (or env CONVENE_BLOCKING_PUSH=1).
+ * When on, the hook calls `convene gate-push` and propagates its exit code, so a
+ * confirmed LANE_HELD / behind-HEAD can ABORT the push (exit 1) — the one
+ * cross-tool enforcement point (Codex/Cursor/human). It still fails OPEN on a
+ * bus-unreachable error: `gate-push` is itself fail-open-loud, so an unreachable
+ * bus yields exit 0 and the push proceeds.
+ */
 function prePushScript() {
     return ([
         '#!/usr/bin/env sh',
-        `# ${exports.GITHOOK_MARKER} — auto-post a Convene [STATUS] when work is pushed.`,
-        '# Fail-OPEN: this never blocks a push. The pre-push payload on stdin is',
-        "# forwarded to the CLI. Disable with: git config --unset core.hooksPath",
-        '# (or delete this file).',
-        'if command -v convene >/dev/null 2>&1; then',
-        '  convene notify-push "$@" || true',
+        `# ${exports.GITHOOK_MARKER} — Convene pre-push hook.`,
+        '# DEFAULT: fail-OPEN — post a [STATUS] and never block the push.',
+        '# OPT-IN blocking gate (per clone, off by default — preserves the fail-open default):',
+        '#   git config --local convene.blockingPush true   (or env CONVENE_BLOCKING_PUSH=1)',
+        '# enables a deploy-lane gate that can ABORT the push (exit 1) on a confirmed',
+        '# conflict. It still fails open if the bus is unreachable.',
+        '# Disable entirely with: git config --unset core.hooksPath (or delete this file).',
+        'if ! command -v convene >/dev/null 2>&1; then',
+        '  exit 0',
+        'fi',
+        '# Always post the after-push status (fail-open).',
+        'convene notify-push "$@" || true',
+        '# Opt-in blocking gate.',
+        'blocking="${CONVENE_BLOCKING_PUSH:-}"',
+        'if [ -z "$blocking" ]; then',
+        '  blocking=$(git config --bool --get convene.blockingPush 2>/dev/null || true)',
         'fi',
+        'case "$blocking" in',
+        '  1|true|yes|on)',
+        '    convene gate-push --stdin || exit $?',
+        '    ;;',
+        'esac',
         'exit 0',
     ].join('\n') + '\n');
 }
@@ -86,7 +122,9 @@ function installGitHooks(top) {
         const desired = prePushScript();
         const current = node_fs_1.default.existsSync(hookFile) ? node_fs_1.default.readFileSync(hookFile, 'utf8') : null;
         // A pre-push we didn't author lives here — back away rather than overwrite it.
-        if (current !== null && !current.includes(exports.GITHOOK_MARKER)) {
+        // A v1-marked hook IS ours (upgradeable in place to v2); a foreign/populated
+        // hook with neither marker is still refused.
+        if (current !== null && !isOurHook(current)) {
             return { status: 'skipped-foreign', hooksPath: exports.GITHOOKS_DIR };
         }
         let fileResult;

package/dist/hook.js

@@ -4,11 +4,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HOOK_COMMAND = exports.SETTINGS_PATH = void 0;
+exports.binarySupportsVerb = binarySupportsVerb;
 exports.readSettingsRaw = readSettingsRaw;
 exports.parseSettings = parseSettings;
 exports.hookIsRegistered = hookIsRegistered;
 exports.withHook = withHook;
 exports.serializeSettings = serializeSettings;
+exports.genericHookIsRegistered = genericHookIsRegistered;
+exports.withGenericHook = withGenericHook;
+exports.ensureHook = ensureHook;
 exports.ensureHookRegistered = ensureHookRegistered;
 exports.projectSettingsPath = projectSettingsPath;
 exports.ensureProjectHookRegistered = ensureProjectHookRegistered;
@@ -22,9 +26,46 @@ exports.ensureProjectHookRegistered = ensureProjectHookRegistered;
  */
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
 const config_1 = require("./config");
 exports.SETTINGS_PATH = node_path_1.default.join((0, config_1.homeBase)(), '.claude', 'settings.json');
 exports.HOOK_COMMAND = 'convene fetch';
+/**
+ * Does the installed `convene` binary support a given verb? init uses this to skip
+ * wiring a hook whose binary can't service it — so a STALE npm-linked / globally
+ * installed `convene` (predating WP13's verbs) doesn't error on every boot
+ * (catchup/cross-tool #2). We probe `convene <verb> --help`: Commander exits 0 for
+ * a known command and non-zero (with "unknown command") for an unknown one.
+ *
+ * Hermetic-test override: `CONVENE_INIT_VERBS` short-circuits the probe. Set it to
+ * a comma-list of supported verbs (or `*` for "all supported", `-` / empty for
+ * "none supported") so init.test.ts never shells out to a real binary.
+ */
+function binarySupportsVerb(verb) {
+    const override = process.env.CONVENE_INIT_VERBS;
+    if (override !== undefined) {
+        if (override === '*')
+            return true;
+        const set = new Set(override
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean));
+        return set.has(verb);
+    }
+    try {
+        const r = (0, node_child_process_1.spawnSync)('convene', [verb, '--help'], { timeout: 4000, encoding: 'utf8' });
+        if (r.error || typeof r.status !== 'number')
+            return false;
+        if (r.status !== 0)
+            return false;
+        // Defense in depth: Commander prints "unknown command" to stderr on a miss.
+        const out = `${r.stdout || ''}${r.stderr || ''}`;
+        return !/unknown command/i.test(out);
+    }
+    catch {
+        return false;
+    }
+}
 function readSettingsRaw(p = exports.SETTINGS_PATH) {
     try {
         return node_fs_1.default.readFileSync(p, 'utf8');
@@ -64,6 +105,70 @@ function withHook(settings) {
 function serializeSettings(settings) {
     return JSON.stringify(settings, null, 2) + '\n';
 }
+// ── Generic hook registration (WP2) ──────────────────────────────────────────
+// The existing withHook/ensureHookRegistered above are UserPromptSubmit-specific
+// and stay INTACT (init.ts still uses them). This generalizes registration to
+// ANY Claude Code hook event (SessionStart, PreToolUse, PostToolUse, …) with an
+// optional matcher. WIRING new events into init.ts is deferred to WP13 — these
+// are the helpers WP13 will call.
+/**
+ * Is a hook with this command AND matcher already registered for this event?
+ * Matching on command (substring) AND matcher AND event prevents both
+ * double-registration and clobbering an unrelated hook on the same event.
+ */
+function genericHookIsRegistered(settings, eventName, command, matcher) {
+    const groups = settings?.hooks?.[eventName];
+    if (!Array.isArray(groups))
+        return false;
+    return groups.some((g) => 
+    // A group with no matcher matches a query with no matcher; otherwise exact.
+    (matcher === undefined ? g?.matcher === undefined : g?.matcher === matcher) &&
+        Array.isArray(g?.hooks) &&
+        g.hooks.some((h) => typeof h?.command === 'string' && h.command.includes(command)));
+}
+/** Return a new settings object with a generic hook ensured (deep-clone, idempotent). */
+function withGenericHook(settings, eventName, command, matcher) {
+    const next = settings ? JSON.parse(JSON.stringify(settings)) : {};
+    next.hooks = next.hooks || {};
+    if (!Array.isArray(next.hooks[eventName]))
+        next.hooks[eventName] = [];
+    if (!genericHookIsRegistered(next, eventName, command, matcher)) {
+        const group = { hooks: [{ type: 'command', command }] };
+        if (matcher !== undefined)
+            group.matcher = matcher;
+        next.hooks[eventName].push(group);
+    }
+    return next;
+}
+/**
+ * Ensure a generic hook (any event + optional matcher) in a settings file,
+ * idempotent + merge-safe. parseSettings → null (unparseable) returns 'manual'
+ * WITHOUT clobbering. Defaults to the global ~/.claude/settings.json; pass
+ * `settingsPath` for the repo-committed file.
+ *
+ * `backup` controls the .bak: ON (default) for the GLOBAL settings (it lives
+ * outside any repo, so a .bak is the only recovery). OFF for a repo-committed file
+ * — git history IS the backup, and a sibling .bak would litter the working tree
+ * (P0-IDEMPOTENT: no .bak inside the repo).
+ */
+function ensureHook(eventName, command, matcher, settingsPath = exports.SETTINGS_PATH, backup = settingsPath === exports.SETTINGS_PATH) {
+    const raw = readSettingsRaw(settingsPath);
+    const settings = parseSettings(raw);
+    if (settings === null)
+        return 'manual'; // unparseable — do NOT clobber
+    if (genericHookIsRegistered(settings, eventName, command, matcher))
+        return 'already';
+    try {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(settingsPath), { recursive: true });
+        if (backup && raw !== null)
+            node_fs_1.default.writeFileSync(settingsPath + '.bak', raw);
+        node_fs_1.default.writeFileSync(settingsPath, serializeSettings(withGenericHook(settings, eventName, command, matcher)));
+        return 'registered';
+    }
+    catch {
+        return 'manual';
+    }
+}
 /** Ensure the UserPromptSubmit hook is registered (idempotent, backs up). */
 function ensureHookRegistered() {
     const raw = readSettingsRaw();
@@ -104,8 +209,9 @@ function ensureProjectHookRegistered(toplevel) {
         return 'already';
     try {
         node_fs_1.default.mkdirSync(node_path_1.default.dirname(p), { recursive: true });
-        if (raw !== null)
-            node_fs_1.default.writeFileSync(p + '.bak', raw);
+        // NO .bak here: this is a repo-committed file — git history IS the backup, and a
+        // sibling .bak would litter the working tree (P0-IDEMPOTENT: no .bak inside the repo).
+        // Mirrors the generalized ensureHook's backup=(settingsPath===SETTINGS_PATH) discipline.
         node_fs_1.default.writeFileSync(p, serializeSettings(withHook(settings)));
         return 'registered';
     }