@indigoai-us/hq-cli 5.117.1 → 5.117.3

package/dist/lib/billing/plan-lock.js

@@ -0,0 +1,230 @@
+/**
+ * `plan-lock` (starter-plan-hard-limits / US-011) — the CLI-side read + render
+ * of the workspace plan lock.
+ *
+ * Starter (free) workspaces are capped at 5 members and 0 integrations. Going
+ * over locks the workspace immediately: it becomes read-only until the owner
+ * trims back under the caps or upgrades to HQ Workforce. The lock decision is
+ * NOT made here — hq-pro's `src/billing/plan-lock.ts` is the single source of
+ * truth and ships the answer on `GET /membership/me` as a per-company
+ * `planLock` object. This module only reads that field and renders it.
+ *
+ * Member counts are decoration, never a second opinion: the count comes from
+ * `GET /v1/billing/usage-limits` on a best-effort basis and its absence only
+ * removes the "n of 5" detail from the notice. An absent field is UNKNOWN, so
+ * nothing here ever infers a lock (or an unlock) from missing data
+ * (hq-absent-field-never-means-constraining-value).
+ */
+import chalk from "chalk";
+import { vaultApiFetch } from "../../utils/vault-api.js";
+/** Starter member cap quoted when the server did not send `removeMembersTo`. */
+export const STARTER_MEMBER_TARGET = 5;
+/** Upgrade destination quoted when the server did not send one. */
+export const DEFAULT_UPGRADE_URL = "https://hq.computer/billing";
+/** The paid plan the lock wall sends owners to. Copy lives in ONE place. */
+export const WORKFORCE_PLAN_LABEL = "HQ Workforce ($500/mo)";
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+/**
+ * Defensively parse a `planLock` payload. Anything malformed returns null —
+ * the caller then behaves exactly as if the server had sent nothing, which is
+ * "unknown", not "locked".
+ */
+export function parsePlanLock(value) {
+    const rec = asRecord(value);
+    if (!rec)
+        return null;
+    if (typeof rec.locked !== "boolean")
+        return null;
+    const reasons = [];
+    if (Array.isArray(rec.reasons)) {
+        for (const reason of rec.reasons) {
+            if (reason === "users" || reason === "integrations")
+                reasons.push(reason);
+        }
+    }
+    const fix = asRecord(rec.fixOptions);
+    const removeMembersTo = typeof fix?.removeMembersTo === "number" &&
+        Number.isFinite(fix.removeMembersTo)
+        ? fix.removeMembersTo
+        : STARTER_MEMBER_TARGET;
+    return {
+        locked: rec.locked,
+        reasons,
+        upgradeUrl: typeof rec.upgradeUrl === "string" && rec.upgradeUrl.trim().length > 0
+            ? rec.upgradeUrl.trim()
+            : DEFAULT_UPGRADE_URL,
+        fixOptions: {
+            removeMembersTo,
+            disconnectIntegrations: fix?.disconnectIntegrations === true,
+        },
+    };
+}
+/**
+ * Pick the membership row for `companySlug` (or `cmp_…` uid) out of a decoded
+ * `/membership/me` body and return its parsed lock. No matching row — or no
+ * `planLock` on it — is UNKNOWN, so this returns null rather than guessing.
+ */
+export function selectPlanLock(body, companyRef) {
+    const rec = asRecord(body);
+    const rows = Array.isArray(rec?.memberships) ? rec.memberships : [];
+    const ref = companyRef.trim().toLowerCase();
+    for (const raw of rows) {
+        const row = asRecord(raw);
+        if (!row)
+            continue;
+        if (typeof row.status === "string" && row.status !== "active")
+            continue;
+        const slug = typeof row.companySlug === "string" ? row.companySlug.toLowerCase() : "";
+        const uid = typeof row.companyUid === "string" ? row.companyUid.toLowerCase() : "";
+        if (slug !== ref && uid !== ref)
+            continue;
+        const lock = parsePlanLock(row.planLock);
+        if (!lock)
+            return null;
+        return {
+            lock,
+            companyUid: typeof row.companyUid === "string" ? row.companyUid : undefined,
+        };
+    }
+    return null;
+}
+/** Parse the resolved plan id out of a usage-limits body. Absent → null. */
+export function selectPlan(body) {
+    const plan = asRecord(body)?.plan;
+    return plan === "free" || plan === "paid" || plan === "enterprise"
+        ? plan
+        : null;
+}
+/** Parse the `users` dimension out of a usage-limits body. Absent → null. */
+export function selectMemberUsage(body) {
+    const users = asRecord(asRecord(body)?.users);
+    if (!users)
+        return null;
+    if (typeof users.used !== "number" || !Number.isFinite(users.used)) {
+        return null;
+    }
+    const limit = typeof users.limit === "number" && Number.isFinite(users.limit)
+        ? users.limit
+        : STARTER_MEMBER_TARGET;
+    return { used: users.used, limit };
+}
+/**
+ * Read the live lock for one company: `planLock` from `/membership/me`, plus a
+ * best-effort member count for the notice. Returns null when the server did not
+ * answer with a lock for this company — callers must then say nothing.
+ */
+export async function fetchPlanLockStatus(token, companyRef, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 8000;
+    const res = await vaultApiFetch({
+        token,
+        path: "/membership/me",
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok)
+        return null;
+    const selected = selectPlanLock(await res.json().catch(() => null), companyRef);
+    if (!selected)
+        return null;
+    let members;
+    let plan;
+    // Decoration only. The lock answer above is authoritative; the usage read
+    // adds the member count and the plan id that the notices and the `Plan:`
+    // orientation line quote. A failure here must never suppress — or invent —
+    // a lock, so every field it feeds stays optional.
+    if (selected.companyUid) {
+        try {
+            const usage = await vaultApiFetch({
+                token,
+                path: "/v1/billing/usage-limits",
+                query: { companyUid: selected.companyUid },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (usage.ok) {
+                const body = await usage.json().catch(() => null);
+                members = selectMemberUsage(body) ?? undefined;
+                plan = selectPlan(body) ?? undefined;
+            }
+        }
+        catch {
+            // Network/timeout: leave both unknown.
+        }
+    }
+    return {
+        companySlug: companyRef,
+        companyUid: selected.companyUid,
+        lock: selected.lock,
+        members,
+        plan,
+        checkedAt: new Date().toISOString(),
+    };
+}
+function reasonLabel(reason) {
+    return reason === "users"
+        ? "too many members"
+        : "integrations are not included on Starter";
+}
+/**
+ * The full WORKSPACE LOCKED block: why it locked, where the workspace stands
+ * against the cap, and the two fixes. Plain text — colour is applied by the
+ * caller so scripts capturing stdout get a clean block.
+ */
+export function renderPlanLockNotice(status) {
+    const { lock, members, companySlug } = status;
+    const target = lock.fixOptions.removeMembersTo;
+    const lines = [];
+    lines.push(`WORKSPACE LOCKED — ${companySlug} is over its Starter plan.`);
+    const reasons = lock.reasons.length
+        ? lock.reasons.map(reasonLabel).join("; ")
+        : "over the Starter plan limits";
+    lines.push(`  Why: ${reasons}.`);
+    if (members) {
+        lines.push(`  Members: ${members.used} of ${target}.`);
+    }
+    else {
+        lines.push(`  Members allowed on Starter: ${target}.`);
+    }
+    lines.push("  This workspace is read-only until it is fixed. Two ways out:");
+    lines.push(`    1. Remove members until you are at ${target} or fewer${lock.fixOptions.disconnectIntegrations
+        ? ", and disconnect the workspace's integrations"
+        : ""}.`);
+    lines.push(`    2. Upgrade to ${WORKFORCE_PLAN_LABEL}.`);
+    lines.push(`  Upgrade: ${lock.upgradeUrl}`);
+    return lines.join("\n");
+}
+/**
+ * The one-line form injected on every turn while the workspace stays locked.
+ * Kept to a single line on purpose — it repeats each turn.
+ */
+export function renderPlanLockLine(status) {
+    const target = status.lock.fixOptions.removeMembersTo;
+    const count = status.members
+        ? `${status.members.used} of ${target} members`
+        : `over its ${target}-member limit`;
+    return (`Company ${status.companySlug} is locked on Starter (${count}). ` +
+        `Writes to HQ cloud will fail until fixed: ${status.lock.upgradeUrl}`);
+}
+/**
+ * The `Plan: …` orientation line. Starter only: a paid or enterprise
+ * workspace — and an UNKNOWN plan — gets no line at all.
+ */
+export function renderPlanLine(status) {
+    if (status.lock.locked)
+        return "Plan: Starter — LOCKED";
+    if (status.plan !== "free")
+        return null;
+    const target = status.lock.fixOptions.removeMembersTo;
+    if (status.members) {
+        return `Plan: Starter — ${status.members.used} of ${target} members`;
+    }
+    return `Plan: Starter — ${target} members included`;
+}
+/** Colourised block for interactive output. */
+export function colorizePlanLockNotice(notice) {
+    return chalk.red(notice);
+}
+//# sourceMappingURL=plan-lock.js.map

package/dist/lib/doctor/__testing__/fake-hq-tree.d.ts

@@ -74,7 +74,7 @@ export interface FakeHookSpec {
     mode?: number;
     /** Whether the hook is registered in `.claude/settings.json`. Default: true. */
     registered?: boolean;
-    /** Events the hook registers against. Default: ["PreToolUse"]. */
+    /** Events the hook registers against. Default: SessionStart and PreToolUse. */
     events?: HookEventName[];
     /** Optional settings matcher (e.g. "Bash", "Glob"). */
     matcher?: string;

package/dist/lib/doctor/__testing__/fake-hq-tree.js

@@ -166,7 +166,7 @@ function writeHook(claudeHooksDir, codexHooksDir, hook, defaultMirror) {
     const claudeBody = hook.body ?? DEFAULT_HOOK_BODY;
     const present = hook.present !== false;
     const registered = hook.registered !== false;
-    const events = hook.events ?? ["PreToolUse"];
+    const events = hook.events ?? ["SessionStart", "PreToolUse"];
     const profiles = hook.profiles ?? [...GATE_PROFILES];
     const scriptPath = path.join(claudeHooksDir, `${hook.id}.sh`);
     let mode = null;

package/dist/lib/doctor/checks/claude-wiring.js

@@ -24,6 +24,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { GATE_PROFILES, gateMembership, parseHookGateProfiles, } from "../hook-gate-profiles.js";
+import { countStrayGateEntries } from "../stray-gate-entries.js";
 /** Common id prefix for every result this check family emits. */
 export const CLAUDE_WIRING_PREFIX = "hooks.claude";
 /**
@@ -57,6 +58,35 @@ export function checkClaudeWiring(context) {
     else if (local.present) {
         registrations.push(...enumerateRegistrations(local.value, ".claude/settings.local.json"));
     }
+    // --- Stray matcher-less gate entries (written by old `hq doctor --fix`) -------
+    // Only on master-hook trees: there, per-hook gate entries are never shipped,
+    // so a matcher-less one can only be the doctor-generated stray. A legacy tree
+    // that still registers hooks one by one is left alone.
+    const usesMasterHook = registrations.some((reg) => /\/master-hook\.sh\b/.test(reg.command));
+    for (const [file, parsed] of usesMasterHook ? [
+        ["settings.json", base],
+        ["settings.local.json", local],
+    ] : []) {
+        if (!parsed.present || parsed.invalid)
+            continue;
+        const abs = path.join(claudeDir, file);
+        const stray = countStrayGateEntries(parsed.value);
+        results.push(stray > 0
+            ? {
+                status: "FAIL",
+                checkId: `${CLAUDE_WIRING_PREFIX}.stray-gate-registration`,
+                target: abs,
+                message: `.claude/${file} has ${stray} hook-gate registration${stray === 1 ? "" : "s"} with no matcher. ` +
+                    "They run on every tool call and can block Bash, Skill and Read. An older `hq doctor --fix` wrote them.",
+                remediation: `Remove the matcher-less hook-gate.sh entries from .claude/${file} (hq doctor --fix does this).`,
+            }
+            : {
+                status: "PASS",
+                checkId: `${CLAUDE_WIRING_PREFIX}.stray-gate-registration`,
+                target: abs,
+                message: `.claude/${file} has no stray matcher-less hook-gate registrations.`,
+            });
+    }
     const scans = registrations.map((reg) => ({
         reg,
         scan: scanHookCommand(reg.command),
@@ -116,6 +146,11 @@ export function checkClaudeWiring(context) {
         for (const rp of scan.requiredRelpaths)
             referencedBasenames.add(baseName(rp));
     }
+    // master-hook.sh dispatches the gated hooks listed in hook-registry.json, so
+    // those scripts are registered even though no settings command names them.
+    for (const script of hookRegistryScripts(path.join(hooksDir, "hook-registry.json"))) {
+        referencedBasenames.add(baseName(script));
+    }
     for (const file of listShellScripts(hooksDir)) {
         if (referencedBasenames.has(file))
             continue;
@@ -124,7 +159,7 @@ export function checkClaudeWiring(context) {
             checkId: `${CLAUDE_WIRING_PREFIX}.orphan`,
             target: path.join(hooksDir, file),
             message: `Hook script ${file} is present in .claude/hooks/ but is not registered in any settings file.`,
-            remediation: `Register ${file} in .claude/settings.json or delete it.`,
+            remediation: `Add ${file} to .claude/hooks/hook-registry.json with the right event and matcher, or delete it.`,
         });
     }
     // --- AC4: every gated hook id is in ALL THREE profiles -----------------------
@@ -234,6 +269,31 @@ export function checkClaudeWiring(context) {
  * event in a parsed settings object. Tolerant of malformed shapes — any
  * non-conforming branch contributes nothing rather than throwing.
  */
+/** Every `script` path listed in .claude/hooks/hook-registry.json (empty when absent). */
+function hookRegistryScripts(registryPath) {
+    const parsed = readJsonFile(registryPath);
+    if (!parsed.present || parsed.invalid)
+        return [];
+    const hooks = parsed.value?.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return [];
+    const out = [];
+    for (const entries of Object.values(hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            const inner = entry?.hooks;
+            if (!Array.isArray(inner))
+                continue;
+            for (const item of inner) {
+                const script = item?.script;
+                if (typeof script === "string" && script)
+                    out.push(script);
+            }
+        }
+    }
+    return out;
+}
 function enumerateRegistrations(settings, source) {
     const out = [];
     if (!settings || typeof settings !== "object")

package/dist/lib/doctor/compat.js

@@ -47,6 +47,7 @@ export const RUNTIME_ENFORCEMENT_CHECK_ID = "hooks.runtime.enforcement";
  */
 export const CHECK_HQ_HOOKS_SETTINGS_SCOPE = [
     "hooks.settings-present",
+    "hooks.settings-required-command-hooks",
     "hooks.settings-valid-json",
     "hooks.claude.settings-local-valid-json",
     "hooks.claude.unquoted-project-dir",

package/dist/lib/doctor/fix/apply.js

@@ -35,6 +35,7 @@ import { createDefaultRegistry } from "../registry.js";
 import { flattenFamilies } from "../report.js";
 import { gateMembership, parseHookGateProfiles, } from "../hook-gate-profiles.js";
 import { createBackup } from "./backup.js";
+import { removeStrayGateEntries } from "../stray-gate-entries.js";
 import { deriveRemediation } from "./remediation.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export const HOOK_CONFIG_DIRS = [".claude", ".codex", ".grok"];
@@ -237,8 +238,8 @@ function planFix(hqRoot, result, rem, refreshSync) {
             return planExecutableBit(hqRoot, result, rem);
         case "gate-profile":
             return planGateProfile(hqRoot, result, rem);
-        case "register-hook":
-            return planRegisterHook(hqRoot, result, rem);
+        case "remove-stray-gate-entries":
+            return planRemoveStrayGateEntries(hqRoot, result, rem);
         case "refresh-sync":
             return planRefreshSync(hqRoot, result, rem, refreshSync);
         default:
@@ -328,34 +329,32 @@ function planGateProfile(hqRoot, result, rem) {
         postStatus: (results) => statusForTarget(results, ".gate-profiles", hookId),
     };
 }
-/** Re-register a script that is present on disk but wired in no settings file. */
-function planRegisterHook(hqRoot, result, rem) {
-    const scriptAbs = rem.fixTarget;
-    if (!scriptAbs)
+/** Remove matcher-less hook-gate.sh registrations an older doctor wrote. */
+function planRemoveStrayGateEntries(hqRoot, result, rem) {
+    const settingsPath = rem.fixTarget;
+    if (!settingsPath)
+        return null;
+    const current = readJson(settingsPath);
+    if (!current)
+        return null;
+    const { removed } = removeStrayGateEntries(current);
+    if (removed === 0)
         return null;
-    const settingsPath = path.join(hqRoot, ".claude", "settings.json");
-    const hookId = path.basename(scriptAbs).replace(/\.sh$/, "");
-    const event = "PreToolUse";
-    const command = `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/hook-gate.sh" ${hookId} ` +
-        `"$CLAUDE_PROJECT_DIR/.claude/hooks/${hookId}.sh"`;
     const relpath = toRelpath(hqRoot, settingsPath);
     return {
         checkId: result.checkId,
-        fixClass: "register-hook",
-        target: scriptAbs,
+        fixClass: "remove-stray-gate-entries",
+        target: settingsPath,
         relpath,
         preview: `  ${relpath}\n` +
-            `    + hooks.${event}: register ${hookId} via hook-gate.sh\n` +
-            `      ${command}`,
-        summary: `register ${hookId} on ${event}`,
+            `    - ${removed} matcher-less hook-gate.sh registration${removed === 1 ? "" : "s"} (they fire on every tool call)`,
+        summary: `remove ${removed} stray hook registration${removed === 1 ? "" : "s"} from ${relpath}`,
         apply: () => {
-            const settings = readJson(settingsPath) ?? {};
-            const updated = registerHookInSettings(settings, event, command);
-            fs.writeFileSync(settingsPath, JSON.stringify(updated, null, 2) + "\n");
+            const latest = readJson(settingsPath) ?? {};
+            const cleaned = removeStrayGateEntries(latest).settings;
+            fs.writeFileSync(settingsPath, JSON.stringify(cleaned, null, 2) + "\n");
         },
-        // After registration the script becomes a wired, executable file, reported
-        // by the Claude wiring tier's `…script` PASS keyed on the same path.
-        postStatus: (results) => statusForPath(results, scriptAbs),
+        postStatus: (results) => statusForTarget(results, ".stray-gate-registration", settingsPath),
     };
 }
 // --- Shell / JSON edit primitives ---------------------------------------------

package/dist/lib/doctor/fix/remediation.d.ts

@@ -17,8 +17,11 @@
  *   - `gate-profile`    — add a gated hook id to the `hook-gate.sh` profile
  *                         allowlists it is missing from. Detected by the
  *                         `…gate-profiles` FAIL from the Claude wiring tier.
- *   - `register-hook`   — re-register a script that is present on disk but wired
- *                         nowhere. Detected by the `…orphan` WARN.
+ *   - `remove-stray-gate-entries` — delete matcher-less hook-gate.sh
+ *                         registrations an older `--fix` wrote into
+ *                         settings.json / settings.local.json. Detected by the
+ *                         `…stray-gate-registration` FAIL. (An orphan script is
+ *                         never auto-registered: that is what created them.)
  *   - `refresh-sync`    — run a targeted pull for a company journal that is
  *                         stale or never-synced AND has a local
  *                         `companies/<slug>` tree. Pull-only, `--on-conflict
@@ -35,7 +38,7 @@
  */
 import type { CheckResult } from "../types.js";
 /** The allowlisted safe repair classes `--fix` is permitted to apply. */
-export type FixClass = "executable-bit" | "gate-profile" | "register-hook" | "refresh-sync";
+export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync";
 /**
  * A finding's structured remediation. `autoFixable`, `action`, and `command`
  * are the `--json` surface (AC1); `fixTarget`/`fixClass` are the internal handle
@@ -51,7 +54,7 @@ export interface Remediation {
     /** The safe class when {@link autoFixable}, else null (manual-only). */
     fixClass: FixClass | null;
     /**
-     * The concrete file path (exec-bit, register-hook) or hook id (gate-profile)
+     * The concrete file path (exec-bit, remove-stray-gate-entries) or hook id (gate-profile)
      * the auto-fix operates on. Present only when {@link autoFixable}. Internal —
      * deliberately omitted from the `--json` document.
      */

package/dist/lib/doctor/fix/remediation.js

@@ -17,8 +17,11 @@
  *   - `gate-profile`    — add a gated hook id to the `hook-gate.sh` profile
  *                         allowlists it is missing from. Detected by the
  *                         `…gate-profiles` FAIL from the Claude wiring tier.
- *   - `register-hook`   — re-register a script that is present on disk but wired
- *                         nowhere. Detected by the `…orphan` WARN.
+ *   - `remove-stray-gate-entries` — delete matcher-less hook-gate.sh
+ *                         registrations an older `--fix` wrote into
+ *                         settings.json / settings.local.json. Detected by the
+ *                         `…stray-gate-registration` FAIL. (An orphan script is
+ *                         never auto-registered: that is what created them.)
  *   - `refresh-sync`    — run a targeted pull for a company journal that is
  *                         stale or never-synced AND has a local
  *                         `companies/<slug>` tree. Pull-only, `--on-conflict
@@ -86,14 +89,19 @@ export function deriveRemediation(result) {
             command: remediation ?? `Add ${target} to the missing hook-gate.sh profiles.`,
         };
     }
-    // register-hook — a script on disk that no settings file references.
-    if (checkId.endsWith(".orphan") && target) {
+    // remove-stray-gate-entries — matcher-less hook-gate.sh registrations that an
+    // older doctor wrote. They fire on every tool call and block the session.
+    //
+    // There is deliberately NO auto-fix for an orphan script. Registering it with
+    // no matcher is exactly what created the stray entries; the right event and
+    // matcher can only be chosen by a person (hook-registry.json).
+    if (checkId.endsWith(".stray-gate-registration") && result.status === "FAIL" && target) {
         return {
             autoFixable: true,
-            fixClass: "register-hook",
+            fixClass: "remove-stray-gate-entries",
             fixTarget: target,
-            action: `Re-register ${target} in .claude/settings.json.`,
-            command: remediation ?? `Register ${target} in .claude/settings.json.`,
+            action: `Remove the matcher-less hook-gate.sh registrations from ${target}.`,
+            command: remediation ?? `Remove the matcher-less hook-gate.sh entries from ${target}.`,
         };
     }
     // refresh-sync — a company journal that is stale or never-synced. Only

package/dist/lib/doctor/registry.js

@@ -147,6 +147,7 @@ function runClaudeSettingsCheck(context) {
         ];
     }
     const count = countHookRegistrations(parsed);
+    const missingRequiredEvents = missingRequiredCommandHookEvents(parsed);
     return [
         {
             status: "PASS",
@@ -154,6 +155,17 @@ function runClaudeSettingsCheck(context) {
             target: settingsPath,
             message: `.claude/settings.json is present and valid (${count} hook registration${count === 1 ? "" : "s"}).`,
         },
+        {
+            status: missingRequiredEvents.length === 0 ? "PASS" : "FAIL",
+            checkId: "hooks.settings-required-command-hooks",
+            target: settingsPath,
+            message: missingRequiredEvents.length === 0
+                ? ".claude/settings.json registers command hooks for SessionStart and PreToolUse."
+                : `.claude/settings.json has no command hook for ${missingRequiredEvents.join(" or ")}.`,
+            remediation: missingRequiredEvents.length === 0
+                ? undefined
+                : "Restore the canonical hook registrations, e.g. `hq rescue -y --paths .claude`.",
+        },
         // US-004+: the settings file is present and valid, so the full Claude wiring
         // checks (script existence and executability, orphaned scripts, three-profile
         // membership, unquoted $CLAUDE_PROJECT_DIR, and core/hooks/<Event>/ executable
@@ -184,6 +196,37 @@ function countHookRegistrations(settings) {
     }
     return count;
 }
+/** The lifecycle events whose command hooks make the settings file operational. */
+const REQUIRED_COMMAND_HOOK_EVENTS = ["SessionStart", "PreToolUse"];
+/**
+ * Return each required lifecycle event that has no command hook with a non-empty
+ * command string. This deliberately mirrors check-hq-hooks.sh's jq predicate.
+ */
+function missingRequiredCommandHookEvents(settings) {
+    return REQUIRED_COMMAND_HOOK_EVENTS.filter((event) => !hasCommandHook(settings, event));
+}
+function hasCommandHook(settings, event) {
+    if (!settings || typeof settings !== "object")
+        return false;
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return false;
+    const eventEntries = hooks[event];
+    if (!Array.isArray(eventEntries))
+        return false;
+    return eventEntries.some((entry) => {
+        if (!entry || typeof entry !== "object")
+            return false;
+        const commandHooks = entry.hooks;
+        if (!Array.isArray(commandHooks))
+            return false;
+        return commandHooks.some((hook) => !!hook &&
+            typeof hook === "object" &&
+            hook.type === "command" &&
+            typeof hook.command === "string" &&
+            hook.command.length > 0);
+    });
+}
 /**
  * Build a registry pre-loaded with the default families. Hooks is the first
  * family; later families are registered here as they are implemented, each

package/dist/lib/doctor/stray-gate-entries.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Stray gate registrations written by an old `hq doctor --fix`.
+ *
+ * hq-cli v5.99.0 through v5.118.x "re-registered" every hook script that no
+ * settings command named. Since HQ moved to a single master-hook.sh entry that
+ * dispatches from .claude/hooks/hook-registry.json, EVERY script looked
+ * unregistered, so doctor appended one PreToolUse entry per script with no
+ * matcher:
+ *
+ *   { "hooks": [{ "type": "command", "timeout": 5,
+ *       "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/hook-gate.sh\" <id> \"$CLAUDE_PROJECT_DIR/.claude/hooks/<id>.sh\"" }] }
+ *
+ * With no matcher Claude Code runs each of them on every tool call, so guards
+ * such as block-hq-glob and protect-core block Bash, Skill and Read. An HQ
+ * update later moves them from settings.json into settings.local.json as
+ * "user customizations", where the release reset no longer clears them.
+ *
+ * Detection is deliberately exact: only an entry with no matcher, exactly one
+ * hook, timeout 5, and the doctor-generated command for a matching id counts.
+ * A hand-written hook is never touched.
+ */
+export declare function isStrayGateEntry(entry: unknown): boolean;
+/** Count stray entries across every hook event in a parsed settings object. */
+export declare function countStrayGateEntries(settings: unknown): number;
+/**
+ * Return a copy of `settings` with every stray entry removed. An event array
+ * left empty is dropped, and an empty `hooks` map is dropped, so a file whose
+ * only hooks were strays goes back to its original shape. Everything else,
+ * including permissions and real hooks, is preserved.
+ */
+export declare function removeStrayGateEntries(settings: unknown): {
+    settings: unknown;
+    removed: number;
+};
+//# sourceMappingURL=stray-gate-entries.d.ts.map