@indigoai-us/hq-cli 5.98.3 → 5.99.0

package/dist/lib/doctor/registry.js

@@ -0,0 +1,176 @@
+/**
+ * The doctor engine — an ordered set of check families — and the first family
+ * (hooks).
+ *
+ * The engine is deliberately ignorant of any specific family: `register`
+ * accepts any object implementing {@link CheckFamily}, and `run` iterates them
+ * generically. A new family (vault, sync, MCP, secrets, qmd freshness, …) is
+ * added by registering it — never by editing this class — which is exactly the
+ * property US-002 requires and later stories rely on.
+ *
+ * The hooks family here is intentionally a skeleton: it establishes the family
+ * so the wiring/parity/runtime checks (US-004+) have somewhere to live, and
+ * reports only the presence and validity of `.claude/settings.json`. Those
+ * later stories add per-item results to this family without touching the engine.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { checkCodexWiring } from "./checks/codex-wiring.js";
+import { checkGrokWiring } from "./checks/grok-wiring.js";
+import { checkRuntimeProbe } from "./checks/runtime-probe.js";
+import { fixtureCoverageFamily } from "./fixtures/discover.js";
+import { checkClaudeWiring } from "./checks/claude-wiring.js";
+/**
+ * An ordered, id-keyed set of check families. Registration order is preserved
+ * (Map iteration order), and re-registering an id replaces the family in place
+ * rather than appending a duplicate.
+ */
+export class DoctorRegistry {
+    familiesById = new Map();
+    /** Register a family. Re-registering the same id replaces it, keeping order. */
+    register(family) {
+        this.familiesById.set(family.id, family);
+    }
+    /** The registered families, in registration order. */
+    families() {
+        return [...this.familiesById.values()];
+    }
+    /** Whether a family with this id is registered. */
+    has(id) {
+        return this.familiesById.has(id);
+    }
+    /** Run every family in order and collect grouped results. */
+    async run(context) {
+        const runs = [];
+        for (const family of this.families()) {
+            const results = await family.run(context);
+            runs.push({ family: { id: family.id, title: family.title }, results });
+        }
+        return runs;
+    }
+}
+/** The id of the hooks family — the first, and for now only, check family. */
+export const HOOKS_FAMILY_ID = "hooks";
+/**
+ * The hooks check family. US-002 shipped the skeleton (Claude settings presence
+ * and validity). US-005 adds the Codex and Grok wiring/parity tiers, which run
+ * for every platform regardless of host. US-004+ extend the Claude tier with the
+ * full settings/registration wiring checks. Each tier appends its own results;
+ * the engine (DoctorRegistry) is untouched.
+ */
+export const hooksFamily = {
+    id: HOOKS_FAMILY_ID,
+    title: "Hook wiring",
+    run: (context) => Promise.resolve(runHooksFamily(context)),
+};
+function runHooksFamily(context) {
+    const results = [];
+    results.push(...runClaudeSettingsCheck(context));
+    // Codex and Grok wiring/parity (US-005) run for every platform regardless of
+    // host. Each tier is wrapped so a parse failure in one cannot crash the whole
+    // doctor run — a thrown tier degrades to an UNKNOWN result instead.
+    results.push(...safeTier("hooks.codex", () => checkCodexWiring(context)));
+    results.push(...safeTier("hooks.grok", () => checkGrokWiring(context)));
+    // The runtime probe (US-006) is the live tier: it reads the policy-trigger
+    // ledger to report whether hooks actually FIRED on the detected host, catching
+    // an app/SDK runtime that loads hook config correctly and then never dispatches
+    // it. Runs last so the wiring picture is reported before the runtime verdict.
+    results.push(...safeTier("hooks.runtime", () => checkRuntimeProbe(context)));
+    return results;
+}
+/** Run one hooks tier, converting an unexpected throw into an UNKNOWN result. */
+function safeTier(idPrefix, run) {
+    try {
+        return run();
+    }
+    catch (error) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: `${idPrefix}.error`,
+                message: `${idPrefix} checks could not run: ${error.message}`,
+            },
+        ];
+    }
+}
+function runClaudeSettingsCheck(context) {
+    const settingsPath = path.join(context.hqRoot, ".claude", "settings.json");
+    if (!fs.existsSync(settingsPath)) {
+        return [
+            {
+                status: "FAIL",
+                checkId: "hooks.settings-present",
+                target: settingsPath,
+                message: ".claude/settings.json is missing — no Claude hooks can be wired.",
+                remediation: "Restore it, e.g. `hq rescue -y --paths .claude`.",
+            },
+        ];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    }
+    catch {
+        return [
+            {
+                status: "FAIL",
+                checkId: "hooks.settings-valid-json",
+                target: settingsPath,
+                message: ".claude/settings.json is present but is not valid JSON.",
+            },
+        ];
+    }
+    const count = countHookRegistrations(parsed);
+    return [
+        {
+            status: "PASS",
+            checkId: "hooks.settings-present",
+            target: settingsPath,
+            message: `.claude/settings.json is present and valid (${count} hook registration${count === 1 ? "" : "s"}).`,
+        },
+        // 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
+        // bits) extend the hooks family here without touching the engine.
+        ...checkClaudeWiring(context),
+    ];
+}
+/**
+ * Count command-hook registrations across every lifecycle event in a parsed
+ * `.claude/settings.json`. Tolerant of malformed shapes — any non-conforming
+ * branch contributes zero rather than throwing.
+ */
+function countHookRegistrations(settings) {
+    if (!settings || typeof settings !== "object")
+        return 0;
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return 0;
+    let count = 0;
+    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))
+                count += inner.length;
+        }
+    }
+    return count;
+}
+/**
+ * Build a registry pre-loaded with the default families. Hooks is the first
+ * family; later families are registered here as they are implemented, each
+ * one line, with no engine change.
+ */
+export function createDefaultRegistry() {
+    const registry = new DoctorRegistry();
+    registry.register(hooksFamily);
+    // 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
+    // contract.
+    registry.register(fixtureCoverageFamily);
+    return registry;
+}
+//# sourceMappingURL=registry.js.map

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

@@ -0,0 +1,87 @@
+/**
+ * Reporting for `hq doctor`: status counting, the exit-code contract, and the
+ * TTY-aware plain-text renderer.
+ *
+ * Three properties here are load-bearing and deliberately decoupled from any
+ * one check family:
+ *
+ *   1. The exit code is a function of the *results*, not of any family's
+ *      internal logic: exit 1 iff some result is FAIL or UNKNOWN. WARN,
+ *      UNTESTED, NA, and KNOWN-DEFECT never fail the command — a doctor that
+ *      exits non-zero on a healthy install trains users to ignore it, which is
+ *      the exact failure mode `hq doctor` exists to prevent.
+ *
+ *   2. UNTESTED and KNOWN-DEFECT are always visible and always counted
+ *      *separately* from PASS. A wired-but-never-exercised hook (UNTESTED) or a
+ *      tracked-but-unfixed defect (KNOWN-DEFECT) must never blend into the pass
+ *      pile, because that is how a correct-looking setup reads as working
+ *      enforcement when it is not.
+ *
+ *   3. Colour is opt-in per render (`color`), never auto-detected here. The
+ *      command layer decides from `process.stdout.isTTY`; when colour is off the
+ *      output carries no ANSI escape sequences at all, so a run piped to a file
+ *      or consumed by CI has the same information content as an interactive one.
+ *
+ * The platform field is a placeholder in this story (US-015). Host platform
+ * detection is US-003; until it lands, {@link UNKNOWN_PLATFORM} is emitted and
+ * US-003 injects the real value through the same `platform` option.
+ */
+import { type CheckResult, type DoctorStatus, type FamilyRun } from "./types.js";
+/**
+ * The detected agent platform and the evidence for the verdict. A structural
+ * placeholder in US-015: host platform detection (US-003) produces the real
+ * value and passes it through unchanged. `evidence` is intentionally `unknown`
+ * so US-003 can attach whatever signal shape it settles on without a breaking
+ * change here.
+ */
+export interface DoctorPlatform {
+    /** Platform id, e.g. `claude-code-cli`, `codex`, `grok`, or `unknown`. */
+    id: string;
+    /** Evidence that led to the verdict. Shape owned by US-003. */
+    evidence?: unknown;
+}
+/** The placeholder platform emitted until host detection (US-003) lands. */
+export declare const UNKNOWN_PLATFORM: DoctorPlatform;
+/** Per-status tallies across every result of a run. */
+export type StatusCounts = Record<DoctorStatus, number>;
+/**
+ * The statuses that fail the command. This is the whole exit-code contract:
+ * only FAIL and UNKNOWN are here. UNKNOWN counts as failing because "could not
+ * be determined" must never be mistaken for "verified working".
+ */
+export declare const FAILING_STATUSES: readonly DoctorStatus[];
+/** Whether a status fails the command per {@link FAILING_STATUSES}. */
+export declare function isFailingStatus(status: DoctorStatus): boolean;
+/** Flatten grouped family runs into a single ordered result list. */
+export declare function flattenFamilies(families: FamilyRun[]): CheckResult[];
+/** A zeroed {@link StatusCounts} with an entry for every status. */
+export declare function emptyStatusCounts(): StatusCounts;
+/** Tally results by status across all families. */
+export declare function summarize(families: FamilyRun[]): StatusCounts;
+/**
+ * The process exit code for a run: 1 if any result is FAIL or UNKNOWN, else 0.
+ * Independent of rendering so callers and tests can assert the contract without
+ * parsing output.
+ */
+export declare function computeExitCode(families: FamilyRun[]): number;
+/** Options for {@link renderText}. */
+export interface RenderTextOptions {
+    /** The resolved HQ root, printed in the header. */
+    hqRoot: string;
+    /** Grouped per-family results, rendered in order. */
+    families: FamilyRun[];
+    /** Detected platform. Defaults to {@link UNKNOWN_PLATFORM}. */
+    platform?: DoctorPlatform;
+    /** Also print every PASS result. Default: false. */
+    verbose?: boolean;
+    /** Emit ANSI colour. Default: false (no escape sequences). */
+    color?: boolean;
+}
+/**
+ * Render the plain-text report. Results are grouped by family; PASS results are
+ * hidden unless `verbose`, while every non-PASS result — including UNTESTED and
+ * KNOWN-DEFECT — is always shown. A summary block reports per-status counts and
+ * states the exit outcome.
+ */
+export declare function renderText(options: RenderTextOptions): string;
+//# sourceMappingURL=report.d.ts.map

package/dist/lib/doctor/report.js

@@ -0,0 +1,164 @@
+/**
+ * Reporting for `hq doctor`: status counting, the exit-code contract, and the
+ * TTY-aware plain-text renderer.
+ *
+ * Three properties here are load-bearing and deliberately decoupled from any
+ * one check family:
+ *
+ *   1. The exit code is a function of the *results*, not of any family's
+ *      internal logic: exit 1 iff some result is FAIL or UNKNOWN. WARN,
+ *      UNTESTED, NA, and KNOWN-DEFECT never fail the command — a doctor that
+ *      exits non-zero on a healthy install trains users to ignore it, which is
+ *      the exact failure mode `hq doctor` exists to prevent.
+ *
+ *   2. UNTESTED and KNOWN-DEFECT are always visible and always counted
+ *      *separately* from PASS. A wired-but-never-exercised hook (UNTESTED) or a
+ *      tracked-but-unfixed defect (KNOWN-DEFECT) must never blend into the pass
+ *      pile, because that is how a correct-looking setup reads as working
+ *      enforcement when it is not.
+ *
+ *   3. Colour is opt-in per render (`color`), never auto-detected here. The
+ *      command layer decides from `process.stdout.isTTY`; when colour is off the
+ *      output carries no ANSI escape sequences at all, so a run piped to a file
+ *      or consumed by CI has the same information content as an interactive one.
+ *
+ * The platform field is a placeholder in this story (US-015). Host platform
+ * detection is US-003; until it lands, {@link UNKNOWN_PLATFORM} is emitted and
+ * US-003 injects the real value through the same `platform` option.
+ */
+import { Chalk } from "chalk";
+import { DOCTOR_STATUSES, } from "./types.js";
+import { FIXTURE_COVERAGE_CHECK_ID } from "./fixtures/discover.js";
+/** The placeholder platform emitted until host detection (US-003) lands. */
+export const UNKNOWN_PLATFORM = { id: "unknown" };
+/**
+ * The statuses that fail the command. This is the whole exit-code contract:
+ * only FAIL and UNKNOWN are here. UNKNOWN counts as failing because "could not
+ * be determined" must never be mistaken for "verified working".
+ */
+export const FAILING_STATUSES = ["FAIL", "UNKNOWN"];
+/** Whether a status fails the command per {@link FAILING_STATUSES}. */
+export function isFailingStatus(status) {
+    return FAILING_STATUSES.includes(status);
+}
+/** Flatten grouped family runs into a single ordered result list. */
+export function flattenFamilies(families) {
+    return families.flatMap((run) => run.results);
+}
+/** A zeroed {@link StatusCounts} with an entry for every status. */
+export function emptyStatusCounts() {
+    const counts = {};
+    for (const status of DOCTOR_STATUSES)
+        counts[status] = 0;
+    return counts;
+}
+/** Tally results by status across all families. */
+export function summarize(families) {
+    const counts = emptyStatusCounts();
+    for (const result of flattenFamilies(families))
+        counts[result.status] += 1;
+    return counts;
+}
+/**
+ * The process exit code for a run: 1 if any result is FAIL or UNKNOWN, else 0.
+ * Independent of rendering so callers and tests can assert the contract without
+ * parsing output.
+ */
+export function computeExitCode(families) {
+    return flattenFamilies(families).some((result) => isFailingStatus(result.status))
+        ? 1
+        : 0;
+}
+/** Width the status label is padded to so result lines align. */
+const STATUS_LABEL_WIDTH = Math.max(...DOCTOR_STATUSES.map((s) => s.length));
+/**
+ * Build a status colouriser. When `color` is false a level-0 Chalk instance is
+ * used, which returns its input verbatim — guaranteeing zero ANSI output on the
+ * non-TTY path regardless of the ambient environment.
+ */
+function buildPainter(color) {
+    const chalk = new Chalk({ level: color ? 1 : 0 });
+    const paint = {
+        PASS: (text) => chalk.green(text),
+        FAIL: (text) => chalk.red(text),
+        WARN: (text) => chalk.yellow(text),
+        UNTESTED: (text) => chalk.cyan(text),
+        NA: (text) => chalk.gray(text),
+        UNKNOWN: (text) => chalk.magenta(text),
+        "KNOWN-DEFECT": (text) => chalk.blue(text),
+    };
+    return (status, text) => paint[status](text);
+}
+/**
+ * Render the plain-text report. Results are grouped by family; PASS results are
+ * hidden unless `verbose`, while every non-PASS result — including UNTESTED and
+ * KNOWN-DEFECT — is always shown. A summary block reports per-status counts and
+ * states the exit outcome.
+ */
+export function renderText(options) {
+    const { hqRoot, families } = options;
+    const platform = options.platform ?? UNKNOWN_PLATFORM;
+    const verbose = options.verbose ?? false;
+    const paint = buildPainter(options.color ?? false);
+    const pad = " ".repeat(STATUS_LABEL_WIDTH);
+    const lines = [];
+    lines.push(`hq doctor — HQ root: ${hqRoot}`);
+    lines.push(`Platform: ${platform.id}`);
+    for (const run of families) {
+        lines.push("");
+        lines.push(`${run.family.title} (${run.family.id})`);
+        if (run.results.length === 0) {
+            lines.push("  (no results)");
+            continue;
+        }
+        const visible = run.results.filter((result) => verbose || result.status !== "PASS");
+        if (visible.length === 0) {
+            const n = run.results.length;
+            lines.push(`  all ${n} check${n === 1 ? "" : "s"} passing (use --verbose to list)`);
+            continue;
+        }
+        for (const result of visible) {
+            const label = paint(result.status, result.status.padEnd(STATUS_LABEL_WIDTH));
+            const target = result.target ? ` [${result.target}]` : "";
+            lines.push(`  ${label}  ${result.checkId}${target}: ${result.message}`);
+            if (result.remediation) {
+                lines.push(`  ${pad}  remediation: ${result.remediation}`);
+            }
+        }
+    }
+    lines.push("");
+    lines.push(renderSummary(families, paint));
+    return lines.join("\n") + "\n";
+}
+/**
+ * The summary block: a per-status count line in canonical status order, an
+ * explicit note that UNTESTED and KNOWN-DEFECT are never counted as passing,
+ * and the exit outcome. Rendered from {@link summarize}/{@link computeExitCode}
+ * so it can never disagree with the machine-readable contract.
+ */
+function renderSummary(families, paint) {
+    const counts = summarize(families);
+    const total = DOCTOR_STATUSES.reduce((sum, status) => sum + counts[status], 0);
+    const parts = DOCTOR_STATUSES.map((status) => `${paint(status, status)} ${counts[status]}`);
+    const lines = [
+        `Summary (${total} check${total === 1 ? "" : "s"}): ${parts.join("  ")}`,
+        `UNTESTED (${counts.UNTESTED}) and KNOWN-DEFECT (${counts["KNOWN-DEFECT"]}) ` +
+            `are reported but never counted as passing.`,
+    ];
+    // Surface the fixture-coverage ratio (US-007) in the summary — the forcing
+    // function that keeps a mostly-unfixtured doctor from reading as a clean bill
+    // of health. Emitted by the fixture-coverage family; absent only when that
+    // family did not run.
+    const coverage = flattenFamilies(families).find((result) => result.checkId === FIXTURE_COVERAGE_CHECK_ID);
+    if (coverage)
+        lines.push(coverage.message);
+    if (computeExitCode(families) === 0) {
+        lines.push("Result: OK — no FAIL or UNKNOWN results (exit 0).");
+    }
+    else {
+        lines.push(`Result: ATTENTION — ${counts.FAIL} FAIL, ${counts.UNKNOWN} UNKNOWN ` +
+            `(exit 1).`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=report.js.map

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

@@ -0,0 +1,87 @@
+/**
+ * Core doctor types: the status vocabulary and the check-registry contract.
+ *
+ * The status vocabulary is the load-bearing design decision of `hq doctor`.
+ * UNTESTED (wired but never exercised), NA (untestable on this platform),
+ * UNKNOWN (could not be determined), and KNOWN-DEFECT (tracked and unfixed) must
+ * never collapse into PASS — that separation is what keeps the tool honest and
+ * stops a correct-looking configuration from reading as working enforcement.
+ *
+ * `DoctorStatus` is derived from the `DOCTOR_STATUSES` tuple, so the union is
+ * closed: any consumer that assigns a value outside the tuple is a compile
+ * error, and the vocabulary can only grow by editing the tuple in one place.
+ */
+/** The complete, fixed status vocabulary, in canonical display order. */
+export declare const DOCTOR_STATUSES: readonly ["PASS", "FAIL", "WARN", "UNTESTED", "NA", "UNKNOWN", "KNOWN-DEFECT"];
+/**
+ * A doctor result status. Closed union derived from {@link DOCTOR_STATUSES};
+ * the type system rejects any other string at every call site.
+ */
+export type DoctorStatus = (typeof DOCTOR_STATUSES)[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. */
+export interface CheckResult {
+    /** Status drawn from the fixed vocabulary. */
+    status: DoctorStatus;
+    /** Stable machine id for this item, e.g. `hooks.settings-present`. */
+    checkId: string;
+    /** What was inspected — a path, hook id, etc. Optional. */
+    target?: string;
+    /** Human-readable one-line explanation of the result. */
+    message: string;
+    /** Optional remediation hint (a command or instruction). */
+    remediation?: string;
+}
+/**
+ * The context handed to every check family's `run`. The resolved HQ root is
+ * exposed here so no family re-implements tree discovery; later stories extend
+ * this interface (e.g. detected platform, session id) without touching the
+ * engine, since adding an optional field is non-breaking.
+ */
+export interface CheckContext {
+    /** Absolute, resolved HQ tree root every check reads from. */
+    hqRoot: string;
+    /**
+     * The detected host platform (id, and optionally the evidence behind it).
+     * Host-specific live checks — the US-006 runtime probe — key their
+     * UNKNOWN/FAIL behaviour off this. Absent means host detection has not run and
+     * is treated as `unknown`. Kept structurally minimal so the engine does not
+     * depend on the platform module.
+     */
+    platform?: {
+        id: string;
+        evidence?: unknown;
+    };
+    /**
+     * The session id to scope runtime/ledger checks to (US-006 `--session-id`),
+     * so an older session's ledger cannot be mistaken for the current runtime.
+     * Absent means "any session's ledger counts".
+     */
+    sessionId?: string;
+}
+/**
+ * A check family: an id, a human title, and an async `run` returning per-item
+ * results. Adding a new family (vault, sync, MCP, secrets, qmd freshness, …)
+ * means implementing this interface and registering the object — the engine
+ * needs no changes.
+ */
+export interface CheckFamily {
+    /** Stable family id, e.g. `hooks`. Unique within a registry. */
+    id: string;
+    /** Human-readable family title for grouped output. */
+    title: string;
+    /** Run this family's checks against the resolved tree. */
+    run: (context: CheckContext) => Promise<CheckResult[]>;
+}
+/** The grouped results of running one family. */
+export interface FamilyRun {
+    /** Identifying metadata for the family that produced these results. */
+    family: {
+        id: string;
+        title: string;
+    };
+    /** The per-item results the family returned. */
+    results: CheckResult[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/doctor/types.js

@@ -0,0 +1,29 @@
+/**
+ * Core doctor types: the status vocabulary and the check-registry contract.
+ *
+ * The status vocabulary is the load-bearing design decision of `hq doctor`.
+ * UNTESTED (wired but never exercised), NA (untestable on this platform),
+ * UNKNOWN (could not be determined), and KNOWN-DEFECT (tracked and unfixed) must
+ * never collapse into PASS — that separation is what keeps the tool honest and
+ * stops a correct-looking configuration from reading as working enforcement.
+ *
+ * `DoctorStatus` is derived from the `DOCTOR_STATUSES` tuple, so the union is
+ * closed: any consumer that assigns a value outside the tuple is a compile
+ * error, and the vocabulary can only grow by editing the tuple in one place.
+ */
+/** The complete, fixed status vocabulary, in canonical display order. */
+export const DOCTOR_STATUSES = [
+    "PASS",
+    "FAIL",
+    "WARN",
+    "UNTESTED",
+    "NA",
+    "UNKNOWN",
+    "KNOWN-DEFECT",
+];
+/** Runtime type guard: true only for a member of the fixed vocabulary. */
+export function isDoctorStatus(value) {
+    return (typeof value === "string" &&
+        DOCTOR_STATUSES.includes(value));
+}
+//# sourceMappingURL=types.js.map

package/dist/main.js

@@ -60,6 +60,7 @@ import { registerDbCommand } from "./commands/db.js";
 import { registerCoreCommands } from "./commands/core.js";
 import { registerSearchCommand } from "./commands/search.js";
 import { registerIndexCommand } from "./commands/index-cmd.js";
+import { registerDoctorCommand } from "./commands/doctor.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { networkTransportErrorMessage } from "./utils/network-transport-error.js";
@@ -237,6 +238,11 @@ registerCoreCommands(program);
 // which converges scaffold-owned files and hooks rather than search data.
 registerSearchCommand(program);
 registerIndexCommand(program);
+// Hook guardrail diagnostics (top-level — `hq doctor`). Read-only, offline
+// verification that HQ's hooks are wired and firing, backed by an extensible
+// check registry so later check families (vault, sync, MCP, …) plug in without
+// engine changes.
+registerDoctorCommand(program);
 program.hook("preAction", async () => {
     await emitCliSessionStarted();
 });

package/dist/utils/version-check.js

@@ -5,8 +5,8 @@ import semver from "semver";
 import { CLI_VERSION } from "../cli-version.js";
 const PACKAGE_NAME = "@indigoai-us/hq-cli";
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
-const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-const CACHE_TTL_JITTER_MS = 60 * 60 * 1000;
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1h — catch fresh releases within the hour
+const CACHE_TTL_JITTER_MS = 5 * 60 * 1000; // up to 5m early, to spread a fleet's refreshes off a single instant
 const FETCH_TIMEOUT_MS = 3_000;
 const REFRESH_LOCK_STALE_MS = 10 * 60 * 1000;
 function cachePath() {

package/dist/utils/version-gate.d.ts

@@ -7,7 +7,7 @@
  *
  * Why both?
  *   - `version-check.ts` answers "is there something newer?" by polling npm
- *     directly. It's a soft hint, lives on a 24h cache, and never blocks.
+ *     directly. It's a soft hint, lives on a 1h cache, and never blocks.
  *   - `version-gate.ts` answers "is the team currently allowing your version
  *     to run?" via an authoritative hq-pro endpoint. The server can yank a
  *     known-bad release without waiting for the npm `latest` dist-tag move.

package/dist/utils/version-gate.js

@@ -7,7 +7,7 @@
  *
  * Why both?
  *   - `version-check.ts` answers "is there something newer?" by polling npm
- *     directly. It's a soft hint, lives on a 24h cache, and never blocks.
+ *     directly. It's a soft hint, lives on a 1h cache, and never blocks.
  *   - `version-gate.ts` answers "is the team currently allowing your version
  *     to run?" via an authoritative hq-pro endpoint. The server can yank a
  *     known-bad release without waiting for the npm `latest` dist-tag move.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.98.3",
+  "version": "5.99.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {