@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -7,8 +7,8 @@
  * classes, and if so exactly which file or hook id to act on. This module is the
  * single classifier that turns a {@link CheckResult} into that structured shape.
  *
- * The three — and only three — auto-fixable classes are a deliberate, security
- * -reviewed allowlist (see the PRD decision record):
+ * The auto-fixable classes are a deliberate, security-reviewed allowlist
+ * (see the PRD decision record):
  *
  *   - `executable-bit`  — restore the execute bit on a hook script that exists
  *                         but lost `+x`. Detected by the shared `chmod +x …`
@@ -17,8 +17,16 @@
  *   - `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
+ *                         keep`, no hook-file rewrite. Personal journals and
+ *                         leftover shards without a local tree stay manual.
  *
  * EVERYTHING else — content drift between platform copies, a missing script, a
  * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
@@ -28,6 +36,7 @@
  * content-drift finding is manual-only, because that boundary is load-bearing:
  * deciding which of two diverged copies is correct needs human judgement.
  */
+import { isCompanyJournalSlug, journalSlugFromCheckId, } from "../checks/sync-health.js";
 /** Matches an exec-bit remediation command, quoted or not: `chmod +x <path>`. */
 const CHMOD_EXEC = /^chmod\s+\+x\s+(.+)$/;
 /**
@@ -80,14 +89,45 @@ 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}.`,
+        };
+    }
+    // bot-node-path — a bot LaunchAgent that names node by a versioned path
+    // (…/Cellar/node/<v>/bin/node) that an upgrade removed or will remove.
+    // The repair rewrites only the plist file; it never reloads launchd, so it
+    // cannot cut a running turn short or start a stopped bot.
+    if (checkId.endsWith(".daemon-node") && checkId.startsWith("bots.") && target) {
+        return {
+            autoFixable: true,
+            fixClass: "bot-node-path",
+            fixTarget: target,
+            action: `Rewrite the ${target} startup agent to run node from its upgrade-stable path (applies at the bot's next start).`,
+            command: remediation ?? `hq bot start ${target}`,
+        };
+    }
+    // refresh-sync — a company journal that is stale or never-synced. Only
+    // company slugs: personal shards have no companies/<slug> tree and a
+    // SessionStart `--fix --yes` must not pull the personal vault unprompted.
+    const journalSlug = journalSlugFromCheckId(checkId);
+    if (journalSlug && isCompanyJournalSlug(journalSlug)) {
+        return {
+            autoFixable: true,
+            fixClass: "refresh-sync",
+            fixTarget: journalSlug,
+            action: `Pull company '${journalSlug}' to refresh its sync journal (keeps local conflict copies).`,
+            command: `hq sync pull --company ${journalSlug} --on-conflict keep`,
         };
     }
     // Manual-only: content drift, missing scripts/counterparts, unquoted

package/dist/lib/doctor/fixtures/schema.js

@@ -27,6 +27,7 @@
  *     module owns only the classification semantics, so both the doctor and its
  *     tests agree on what a case outcome means.
  */
+import { isRecord } from "../shared.js";
 /**
  * Every fixture schema version this build of the CLI can interpret. A fixture
  * declaring a version outside this set is reported UNKNOWN, never PASS — see
@@ -242,7 +243,4 @@ export function classifyCaseStatus(met, expectedFailure) {
         return met ? "WARN" : "KNOWN-DEFECT";
     return met ? "PASS" : "FAIL";
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 //# sourceMappingURL=schema.js.map

package/dist/lib/doctor/json-output.d.ts

@@ -18,7 +18,7 @@
  * per-item result shape where both are optional.
  */
 import { type DoctorPlatform, type StatusCounts } from "./report.js";
-import type { DoctorStatus, FamilyRun } from "./types.js";
+import type { DoctorStatus, FamilyRun, SyncReasonCode } from "./types.js";
 /**
  * The `--json` schema version. Bump on any breaking change to the document
  * shape; the snapshot test in report.test.ts fails until the bump is
@@ -50,6 +50,10 @@ export interface DoctorJsonResult {
     family: string;
     /** Stable machine id for the check, e.g. `hooks.settings-present`. */
     checkId: string;
+    /** Stable classification for the sync family; contains no customer data. */
+    reasonCode?: SyncReasonCode;
+    /** Present only when this result's company opted in through hq-flags. */
+    clientHealthReasonCodesEnabled?: true;
     /** What was inspected. Present only when the result carries one. */
     target?: string;
     /** Human-readable explanation. */
@@ -71,6 +75,14 @@ export interface DoctorJsonDocument {
     summary: StatusCounts;
     /** The exit code this run produced: 0, or 1 when any FAIL/UNKNOWN is present. */
     exitCode: number;
+    /**
+     * The check families this run was restricted to (`--only`), in registration
+     * order. ABSENT on a full run, which is the only reading a consumer may treat
+     * as a verdict on the whole tree: a scoped document reports nothing at all
+     * about the families that never ran, and "no FAILs" in it must not be
+     * mistaken for a healthy tree.
+     */
+    scope?: string[];
     /** The full, flattened result list in family/registration order. */
     results: DoctorJsonResult[];
 }
@@ -82,6 +94,10 @@ export interface BuildDoctorJsonInput {
     families: FamilyRun[];
     /** Detected platform. Defaults to {@link UNKNOWN_PLATFORM}. */
     platform?: DoctorPlatform;
+    /** Families this run was restricted to. Omitted on a full run. */
+    scope?: readonly string[];
+    /** Check ids whose own company enabled diagnostic reason codes in hq-flags. */
+    clientHealthReasonCodesEnabledCheckIds?: ReadonlySet<string>;
 }
 /** Assemble the machine-readable document from a completed run. */
 export declare function buildDoctorJson(input: BuildDoctorJsonInput): DoctorJsonDocument;

package/dist/lib/doctor/json-output.js

@@ -34,7 +34,7 @@ export function buildDoctorJson(input) {
     const results = [];
     for (const run of input.families) {
         for (const result of run.results) {
-            results.push(toJsonResult(run.family.id, result));
+            results.push(toJsonResult(run.family.id, result, input.clientHealthReasonCodesEnabledCheckIds));
         }
     }
     return {
@@ -43,16 +43,21 @@ export function buildDoctorJson(input) {
         hqRoot: input.hqRoot,
         summary: summarize(input.families),
         exitCode: computeExitCode(input.families),
+        ...(input.scope && input.scope.length > 0 ? { scope: [...input.scope] } : {}),
         results,
     };
 }
 /** Convert one {@link CheckResult} into its JSON form, omitting empty optionals. */
-function toJsonResult(familyId, result) {
+function toJsonResult(familyId, result, clientHealthReasonCodesEnabledCheckIds) {
     const remediation = deriveRemediation(result);
     return {
         status: result.status,
         family: familyId,
         checkId: result.checkId,
+        ...(result.reasonCode !== undefined ? { reasonCode: result.reasonCode } : {}),
+        ...(clientHealthReasonCodesEnabledCheckIds?.has(result.checkId)
+            ? { clientHealthReasonCodesEnabled: true }
+            : {}),
         ...(result.target !== undefined ? { target: result.target } : {}),
         message: result.message,
         ...(result.remediation !== undefined

package/dist/lib/doctor/platform.d.ts

@@ -126,24 +126,8 @@ export declare function claudeCodeFlagEvidence(env: NodeJS.ProcessEnv): Platform
  * `com.googlecode.iterm2`), so this fires only under a real desktop host.
  */
 export declare function bundleIdEvidence(env: NodeJS.ProcessEnv): PlatformEvidence | null;
-/**
- * Codex runtime environment variables, kept in parity with the canonical shell
- * detector `core/scripts/lib/detect-codex.sh`. Presence of any is a strong Codex
- * signal. One evidence entry is produced per variable found so a single Codex
- * signal can be tested in isolation.
- */
-export declare const CODEX_ENV_VARS: readonly ["CODEX_SANDBOX", "CODEX_SESSION_ID", "CODEX_EXECUTION_ID", "CODEX_AGENT_ID", "CODEX_THREAD_ID", "CODEX_SHELL", "CODEX_CI", "CODEX_INTERNAL_ORIGINATOR_OVERRIDE", "OPENAI_CODEX"];
 /** Every Codex environment signal present in `env`, one entry per variable. */
 export declare function codexEnvEvidence(env: NodeJS.ProcessEnv): PlatformEvidence[];
-/**
- * Grok runtime environment variables. Restricted to variables the Grok host
- * exports into the session (a session id, its workspace root) — HQ's own Grok
- * *launcher* variables (`GROK_BIN`, `GROK_CONFIG`, `XAI_API_KEY`, …) are
- * excluded on purpose: those can be set inside a Claude or Codex session that is
- * merely preparing to launch Grok, and treating them as "we are running under
- * Grok" would be a false positive.
- */
-export declare const GROK_ENV_VARS: readonly ["GROK_SESSION_ID", "GROK_WORKSPACE_ROOT"];
 /** Every Grok environment signal present in `env`, one entry per variable. */
 export declare function grokEnvEvidence(env: NodeJS.ProcessEnv): PlatformEvidence[];
 /**
@@ -157,10 +141,6 @@ export declare function grokEnvEvidence(env: NodeJS.ProcessEnv): PlatformEvidenc
  * on its environment signals instead, and this function does not guess it.
  */
 export declare function ancestryEvidence(ancestors: AncestorProcess[]): PlatformEvidence[];
-/** The one command this module ever launches to read process ancestry. */
-export declare const PS_COMMAND = "ps";
-/** `ps` arguments: every process as `pid ppid comm`, header-suppressed. */
-export declare const PS_ARGS: readonly ["-Ao", "pid=,ppid=,comm="];
 /**
  * Low-level process-table provider: runs a command and returns its stdout, or
  * `null` on failure. This is the single seam through which any process is
@@ -186,12 +166,6 @@ export interface ReadAncestryOptions {
  * environment signals rather than throwing.
  */
 export declare function readProcessAncestry(options?: ReadAncestryOptions): AncestorProcess[];
-/**
- * Collect the environment signals, in a stable order: entrypoint, the Claude
- * flag, bundle id, Codex vars, then Grok vars. Process ancestry is collected
- * separately (and lazily) by {@link detectPlatform}.
- */
-export declare function collectEnvEvidence(env: NodeJS.ProcessEnv): PlatformEvidence[];
 /**
  * Collect every signal from an environment and an explicit ancestor chain, in a
  * stable order: environment signals first, then process ancestry. Exposed for

package/dist/lib/doctor/platform.js

@@ -150,7 +150,7 @@ function looksLikeClaudeDesktopBundle(id) {
  * signal. One evidence entry is produced per variable found so a single Codex
  * signal can be tested in isolation.
  */
-export const CODEX_ENV_VARS = [
+const CODEX_ENV_VARS = [
     "CODEX_SANDBOX",
     "CODEX_SESSION_ID",
     "CODEX_EXECUTION_ID",
@@ -185,7 +185,7 @@ export function codexEnvEvidence(env) {
  * merely preparing to launch Grok, and treating them as "we are running under
  * Grok" would be a false positive.
  */
-export const GROK_ENV_VARS = ["GROK_SESSION_ID", "GROK_WORKSPACE_ROOT"];
+const GROK_ENV_VARS = ["GROK_SESSION_ID", "GROK_WORKSPACE_ROOT"];
 /** Every Grok environment signal present in `env`, one entry per variable. */
 export function grokEnvEvidence(env) {
     const found = [];
@@ -249,9 +249,9 @@ const DEFAULT_MAX_HOPS = 20;
 /** Wall-clock bound for the single `ps` snapshot, keeping startup fast. */
 const PS_TIMEOUT_MS = 250;
 /** The one command this module ever launches to read process ancestry. */
-export const PS_COMMAND = "ps";
+const PS_COMMAND = "ps";
 /** `ps` arguments: every process as `pid ppid comm`, header-suppressed. */
-export const PS_ARGS = ["-Ao", "pid=,ppid=,comm="];
+const PS_ARGS = ["-Ao", "pid=,ppid=,comm="];
 /**
  * Read this process's ancestor chain (nearest parent first) by taking one `ps`
  * snapshot of the process table and walking parent pointers upward. A single
@@ -330,7 +330,7 @@ function defaultPsSpawner(command, args) {
  * flag, bundle id, Codex vars, then Grok vars. Process ancestry is collected
  * separately (and lazily) by {@link detectPlatform}.
  */
-export function collectEnvEvidence(env) {
+function collectEnvEvidence(env) {
     const evidence = [];
     const entrypoint = entrypointEvidence(env);
     if (entrypoint)

package/dist/lib/doctor/registry.d.ts

@@ -27,6 +27,20 @@ export declare class DoctorRegistry {
     families(): CheckFamily[];
     /** Whether a family with this id is registered. */
     has(id: string): boolean;
+    /** The registered family ids, in registration order. */
+    ids(): string[];
+    /**
+     * A registry holding only the named families, still in REGISTRATION order —
+     * the caller's argument order is a selection, not a reordering, so a scoped
+     * report reads the same way as a full one.
+     *
+     * Unknown ids are returned rather than ignored: running zero checks and
+     * reporting success would describe a tree nothing looked at.
+     */
+    select(ids: readonly string[]): {
+        registry: DoctorRegistry;
+        unknown: string[];
+    };
     /** Run every family in order and collect grouped results. */
     run(context: CheckContext): Promise<FamilyRun[]>;
 }

package/dist/lib/doctor/registry.js

@@ -22,6 +22,8 @@ import { runtimeHealthFamily } from "./checks/runtime-health.js";
 import { integrationsFamily } from "./checks/integrations.js";
 import { syncHealthFamily } from "./checks/sync-health.js";
 import { workContextFamily } from "./checks/work-context.js";
+import { botsFamily } from "./checks/bots.js";
+import { scaffoldCliFloorFamily } from "./checks/scaffold-cli-floor.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -43,6 +45,28 @@ export class DoctorRegistry {
     has(id) {
         return this.familiesById.has(id);
     }
+    /** The registered family ids, in registration order. */
+    ids() {
+        return [...this.familiesById.keys()];
+    }
+    /**
+     * A registry holding only the named families, still in REGISTRATION order —
+     * the caller's argument order is a selection, not a reordering, so a scoped
+     * report reads the same way as a full one.
+     *
+     * Unknown ids are returned rather than ignored: running zero checks and
+     * reporting success would describe a tree nothing looked at.
+     */
+    select(ids) {
+        const wanted = new Set(ids);
+        const unknown = [...wanted].filter((id) => !this.familiesById.has(id));
+        const registry = new DoctorRegistry();
+        for (const family of this.families()) {
+            if (wanted.has(family.id))
+                registry.register(family);
+        }
+        return { registry, unknown };
+    }
     /** Run every family in order and collect grouped results. */
     async run(context) {
         const runs = [];
@@ -125,6 +149,7 @@ function runClaudeSettingsCheck(context) {
         ];
     }
     const count = countHookRegistrations(parsed);
+    const missingRequiredEvents = missingRequiredCommandHookEvents(parsed);
     return [
         {
             status: "PASS",
@@ -132,6 +157,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
@@ -162,6 +198,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
@@ -170,6 +237,7 @@ function countHookRegistrations(settings) {
 export function createDefaultRegistry() {
     const registry = new DoctorRegistry();
     registry.register(hooksFamily);
+    registry.register(scaffoldCliFloorFamily);
     // Fixture coverage (US-007): reports UNTESTED for every registered hook with
     // no fixture and prints the tested/total coverage line. A separate family so
     // it needs no change to the hooks tier, per the registry's extensibility
@@ -191,6 +259,9 @@ export function createDefaultRegistry() {
     // Work context (US-007A): session state files, outbox depth/quarantine,
     // and default-company mode. Local-only reads under ~/.hq/work-context.
     registry.register(workContextFamily);
+    // Local bots: inbox/heartbeat reachability and a LaunchAgent whose hq
+    // path survived an HQ toolchain move. Local-only reads.
+    registry.register(botsFamily);
     return registry;
 }
 //# sourceMappingURL=registry.js.map

package/dist/lib/doctor/report.js

@@ -103,7 +103,7 @@ export function renderText(options) {
     const pad = " ".repeat(STATUS_LABEL_WIDTH);
     const lines = [];
     lines.push(`hq doctor — HQ root: ${hqRoot}`);
-    lines.push(`Platform: ${platform.id}`);
+    lines.push(`Agent platform: ${platform.id}`);
     for (const run of families) {
         lines.push("");
         lines.push(`${run.family.title} (${run.family.id})`);

package/dist/lib/doctor/shared.d.ts

@@ -0,0 +1,8 @@
+/** Collect every `command` string from a `{hooks:{Event:[{hooks:[…]}]}}` doc. */
+export declare function collectCommands(parsed: unknown): string[];
+export declare function fileState(target: string): {
+    present: boolean;
+    executable: boolean;
+};
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+//# sourceMappingURL=shared.d.ts.map

package/dist/lib/doctor/shared.js

@@ -0,0 +1,38 @@
+import * as fs from "node:fs";
+/** Collect every `command` string from a `{hooks:{Event:[{hooks:[…]}]}}` doc. */
+export function collectCommands(parsed) {
+    const commands = [];
+    if (!parsed || typeof parsed !== "object")
+        return commands;
+    const hooks = parsed.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return commands;
+    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 hook of inner) {
+                const command = hook?.command;
+                if (typeof command === "string")
+                    commands.push(command);
+            }
+        }
+    }
+    return commands;
+}
+export function fileState(target) {
+    try {
+        const stat = fs.statSync(target);
+        return { present: stat.isFile(), executable: (stat.mode & 0o111) !== 0 };
+    }
+    catch {
+        return { present: false, executable: false };
+    }
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=shared.js.map

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

package/dist/lib/doctor/stray-gate-entries.js

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+const GENERATED_COMMAND = /^bash "\$CLAUDE_PROJECT_DIR\/\.claude\/hooks\/hook-gate\.sh" ([A-Za-z0-9._-]+) "\$CLAUDE_PROJECT_DIR\/\.claude\/hooks\/([A-Za-z0-9._-]+)\.sh"$/;
+export function isStrayGateEntry(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return false;
+    const e = entry;
+    if (e.matcher !== undefined)
+        return false;
+    const keys = Object.keys(e);
+    if (keys.length !== 1 || keys[0] !== "hooks")
+        return false;
+    if (!Array.isArray(e.hooks) || e.hooks.length !== 1)
+        return false;
+    const hook = e.hooks[0];
+    if (!hook || hook.type !== "command" || hook.timeout !== 5 || typeof hook.command !== "string")
+        return false;
+    const m = GENERATED_COMMAND.exec(hook.command);
+    return !!m && m[1] === m[2];
+}
+/** Count stray entries across every hook event in a parsed settings object. */
+export function countStrayGateEntries(settings) {
+    const hooks = settings?.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return 0;
+    let n = 0;
+    for (const entries of Object.values(hooks)) {
+        if (Array.isArray(entries))
+            n += entries.filter(isStrayGateEntry).length;
+    }
+    return n;
+}
+/**
+ * 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 function removeStrayGateEntries(settings) {
+    if (!settings || typeof settings !== "object" || Array.isArray(settings))
+        return { settings, removed: 0 };
+    const root = { ...settings };
+    const hooks = root.hooks;
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        return { settings, removed: 0 };
+    let removed = 0;
+    const next = {};
+    for (const [event, entries] of Object.entries(hooks)) {
+        if (!Array.isArray(entries)) {
+            next[event] = entries;
+            continue;
+        }
+        const kept = entries.filter((e) => !isStrayGateEntry(e));
+        removed += entries.length - kept.length;
+        if (kept.length > 0 || entries.length === 0)
+            next[event] = kept;
+    }
+    if (Object.keys(next).length > 0)
+        root.hooks = next;
+    else
+        delete root.hooks;
+    return { settings: root, removed };
+}
+//# sourceMappingURL=stray-gate-entries.js.map

package/dist/lib/doctor/types.d.ts

@@ -18,6 +18,9 @@ export declare const DOCTOR_STATUSES: readonly ["PASS", "FAIL", "WARN", "UNTESTE
  * the type system rejects any other string at every call site.
  */
 export type DoctorStatus = (typeof DOCTOR_STATUSES)[number];
+/** Stable, privacy-safe diagnostics emitted by the sync health family. */
+export declare const SYNC_REASON_CODES: readonly ["core-version-unavailable", "core-update-available", "no-local-tree", "never-synced", "invalid-last-sync", "stale-threshold", "manifest-unavailable", "manifest-state-unavailable", "no-manifest-scopes", "never-uploaded", "invalid-upload-time", "unresolved-company-uid", "realtime-lag-stuck", "receiver-permission-denied", "runner-restart-loop", "device-limit-backoff", "repeated-conflicts"];
+export type SyncReasonCode = (typeof SYNC_REASON_CODES)[number];
 /** Runtime type guard: true only for a member of the fixed vocabulary. */
 export declare function isDoctorStatus(value: unknown): value is DoctorStatus;
 /** A single per-item result produced by a check family. */
@@ -26,6 +29,8 @@ export interface CheckResult {
     status: DoctorStatus;
     /** Stable machine id for this item, e.g. `hooks.settings-present`. */
     checkId: string;
+    /** Closed diagnostic enum; never contains paths, company slugs, or prose. */
+    reasonCode?: SyncReasonCode;
     /** What was inspected — a path, hook id, etc. Optional. */
     target?: string;
     /** Human-readable one-line explanation of the result. */

package/dist/lib/doctor/types.js

@@ -21,6 +21,26 @@ export const DOCTOR_STATUSES = [
     "UNKNOWN",
     "KNOWN-DEFECT",
 ];
+/** Stable, privacy-safe diagnostics emitted by the sync health family. */
+export const SYNC_REASON_CODES = [
+    "core-version-unavailable",
+    "core-update-available",
+    "no-local-tree",
+    "never-synced",
+    "invalid-last-sync",
+    "stale-threshold",
+    "manifest-unavailable",
+    "manifest-state-unavailable",
+    "no-manifest-scopes",
+    "never-uploaded",
+    "invalid-upload-time",
+    "unresolved-company-uid",
+    "realtime-lag-stuck",
+    "receiver-permission-denied",
+    "runner-restart-loop",
+    "device-limit-backoff",
+    "repeated-conflicts",
+];
 /** Runtime type guard: true only for a member of the fixed vocabulary. */
 export function isDoctorStatus(value) {
     return (typeof value === "string" &&