convene-cli 1.0.5 → 1.1.0

package/dist/commands/post.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolve = exports.decline = exports.accept = exports.ack = void 0;
+exports.resolve = exports.decline = exports.accept = exports.ack = exports.postInterrupt = exports.postHalt = void 0;
 exports.postStatus = postStatus;
 exports.postQuestion = postQuestion;
 exports.postPropose = postPropose;
@@ -42,6 +42,36 @@ async function postPropose(opts) {
     });
     process.stdout.write(`posted [PROPOSE-PROMPT] ${m.short_id} to ${opts.to}\n`);
 }
+/**
+ * `convene post halt|interrupt --to <member|session> '<reason>'` — DIE-LOUD
+ * (getContext + die on failure). Posts a `halt`/`interrupt` control message with
+ * the reason as the (UNTRUSTED, display-only) body. The TARGET is required: a
+ * halt MUST be directed (`--to`), never broadcast — an undirected halt is
+ * meaningless and the server-side authz keys on the directed member/session.
+ *
+ * `--to` is interpreted as a MEMBER handle by default; a value containing `/` is
+ * treated as a SESSION GLOB (`<member>/<basename>`). The server enforces the owner
+ * authz for a cross-member target — this verb does not pre-judge it.
+ */
+async function postHaltLike(type, reason, opts) {
+    if (!opts.to)
+        (0, ctx_1.die)(`${type} requires --to <member|session> (a halt must be directed, never broadcast)`);
+    if (!reason || !reason.trim())
+        (0, ctx_1.die)(`${type} requires a <reason>`);
+    // A target containing '/' is a session glob; otherwise it's a member handle.
+    const isGlob = opts.to.includes('/');
+    const m = await send(opts.project ?? '__cwd__', {
+        type,
+        body: reason,
+        ...(isGlob ? { to_session_glob: opts.to } : { to: opts.to }),
+    });
+    const label = type === 'halt' ? 'HALT' : 'INTERRUPT';
+    process.stdout.write(`posted [${label}] ${m.short_id} to ${opts.to}\n`);
+}
+const postHalt = (reason, opts) => postHaltLike('halt', reason, opts);
+exports.postHalt = postHalt;
+const postInterrupt = (reason, opts) => postHaltLike('interrupt', reason, opts);
+exports.postInterrupt = postInterrupt;
 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`);

package/dist/commands/session-start.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionStart = sessionStart;
+/**
+ * `convene session-start` — the SessionStart hook command (startup|resume|clear).
+ *
+ * FAIL-OPEN (P0-FAILSAFE), copying the fetch.ts scaffold:
+ *   - hard watchdog at 6000ms → exit 0 no matter what (SessionStart's own default
+ *     timeout is 30s, which would stall a boot — we bound it ourselves);
+ *   - the network GET is bounded at 4000ms;
+ *   - any error / non-bus repo / DEGRADED emits NOTHING and exits 0.
+ *
+ * What it does on a fresh, authenticated bus repo:
+ *   1. Mints an opaque session-instance UUID into CACHE_DIR/<slug>.instance — the
+ *      server stamps holder_instance from this (sent as X-Convene-Session-Instance).
+ *   2. Fetches + advances the catch-up cursor IN ONE server transaction and
+ *      emits the <convene-session-open> block (the auto-greeting).
+ *   3. Writes a per-boot dedup sentinel keyed by the instance so the first
+ *      UserPromptSubmit `fetch` of this boot suppresses a duplicate rollup.
+ */
+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 render_1 = require("../render");
+const catchup_1 = require("./catchup");
+const FETCH_TIMEOUT_MS = 4000;
+const WATCHDOG_MS = 6000;
+const MAX_ITEMS = 400;
+// Don't relaunch the watch daemon if one stamped a heartbeat this recently — a
+// fresh resume/clear SessionStart shouldn't pile up duplicate watchers.
+const WATCH_FRESH_SEC = 60;
+/**
+ * Launch `convene watch` as a DETACHED background daemon (§4.4): the watch runs
+ * for the life of the session surfacing mid-task halts, so it must NOT be a
+ * blocking hook entry. Best-effort + fail-open: any error is swallowed; a launch
+ * failure never wedges the boot. Skipped if a recent heartbeat shows a watcher is
+ * already alive for this slug.
+ */
+function launchWatch(slug) {
+    try {
+        const age = (0, cache_1.watchHeartbeatAgeSec)(slug);
+        if (age !== null && age < WATCH_FRESH_SEC)
+            return; // already watching
+        const child = (0, node_child_process_1.spawn)(process.execPath, [process.argv[1], 'watch'], {
+            detached: true,
+            stdio: 'ignore',
+        });
+        child.unref();
+    }
+    catch {
+        /* fail-open: a missing watcher only narrows mid-turn halt awareness */
+    }
+}
+function emit(s) {
+    process.stdout.write(s + '\n');
+}
+async function run(opts) {
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        return; // not a git repo → silent no-op
+    const proj = (0, config_1.loadProjectConfig)(top);
+    if (!proj?.slug)
+        return; // not on the bus → silent no-op
+    const slug = proj.slug;
+    const cfg = (0, config_1.resolveConfig)();
+    if (!cfg.apiKey || !cfg.member)
+        return; // not authenticated → silent (fail-open)
+    const member = cfg.member;
+    const session = (0, git_1.sessionId)(member, top);
+    // Mint a fresh instance for THIS boot (a fresh boot = a fresh instance).
+    const instance = (0, cache_1.mintSessionInstance)(slug);
+    // Launch the detached watch daemon from the SessionStart path (not a Bash hook).
+    launchWatch(slug);
+    const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+    const since = opts.since != null ? Number(opts.since) : undefined;
+    const res = await api.sessionOpen(slug, { since: Number.isFinite(since) ? since : undefined, advance: true, maxItems: MAX_ITEMS }, FETCH_TIMEOUT_MS);
+    // DEGRADED / failure → emit NOTHING (structural suppression). Still record the
+    // sentinel so the first fetch doesn't double-surface from its own cache path.
+    if (!res.ok || !res.json || res.json.degraded) {
+        (0, cache_1.markCatchupSurfaced)(slug, instance);
+        return;
+    }
+    if (opts.json) {
+        emit(JSON.stringify(res.json));
+    }
+    else {
+        emit((0, render_1.renderSessionOpenBlock)({ slug, member, session, digest: (0, catchup_1.toDigest)(res.json) }));
+    }
+    (0, cache_1.markCatchupSurfaced)(slug, instance);
+}
+async function sessionStart(opts = {}) {
+    const watchdog = setTimeout(() => process.exit(0), WATCHDOG_MS);
+    try {
+        await run(opts);
+    }
+    catch {
+        /* fail-open: SessionStart must never wedge a boot */
+    }
+    clearTimeout(watchdog);
+    process.exit(0);
+}

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/git.js

@@ -18,6 +18,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;
@@ -173,6 +174,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';
     }