@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

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

@@ -8,13 +8,11 @@
  *      `.claude/`, `.codex/`, or `.grok/`, `--fix` refuses and exits non-zero
  *      unless `--force`, so a repair can never be tangled up with unrelated
  *      in-flight edits to the security layer.
- *   2. Allowlist only. It repairs the classified safe classes — restore an
- *      execute bit, add a hook id to the gate profiles it is missing from,
- *      re-register a script present on disk, or pull a company whose local
- *      tree exists but whose journal is stale — and NEVER rewrites a hook body
- *      or deletes a file. Classification is owned by {@link deriveRemediation};
- *      a content-drift finding is manual-only and simply never appears in the
- *      fixable set.
+ *   2. Allowlist only. It repairs exactly three classes — restore an execute
+ *      bit, add a hook id to the gate profiles it is missing from, re-register a
+ *      script present on disk — and NEVER rewrites a hook body or deletes a file.
+ *      Classification is owned by {@link deriveRemediation}; a content-drift
+ *      finding is manual-only and simply never appears in the fixable set.
  *   3. Preview + confirmation. Every change is shown diff-style and requires
  *      confirmation, with `--yes` for non-interactive use.
  *   4. Backup first. Before any write, the affected files are copied under
@@ -35,18 +33,9 @@ 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";
-import { botDir } from "../../bot/paths.js";
-import { readBotConfig } from "../../bot/config.js";
-import { buildBotDaemonPaths, rewriteBotDaemonNodePath } from "../../bot/daemon.js";
-import { classifyRefreshSyncOutcome, } from "./refresh-sync-outcome.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export const HOOK_CONFIG_DIRS = [".claude", ".codex", ".grok"];
-/** Per-company bound for the default `hq sync pull` repair. */
-export const REFRESH_SYNC_TIMEOUT_MS = 90_000;
-/** A newly unlocked safe repair can be picked up for at most this many passes. */
-export const MAX_FIX_PASSES = 3;
 /**
  * Apply every auto-fixable finding, honouring the dirty-tree refusal, the
  * preview/confirmation gate, the pre-write backup, and the post-fix re-check.
@@ -64,7 +53,6 @@ export async function applyFixes(options) {
         fixableCount: 0,
         backupDir: null,
         restoreCommand: null,
-        backups: [],
         applied: [],
         ...over,
     });
@@ -80,219 +68,74 @@ export async function applyFixes(options) {
             return empty({ exitCode: 1, refused: "dirty-tree" });
         }
     }
-    const collect = options.runChecks ?? defaultRunChecks;
-    const refreshSync = options.refreshSync ?? defaultRefreshSync;
-    const rewriteBotNodePath = options.rewriteBotNodePath ?? defaultRewriteBotNodePath;
-    // 2. Collect findings, then plan each newly unlocked allowlisted repair.
-    //    Identity is deliberately the check id + target pair: an unsuccessful
-    //    repair must not be applied repeatedly in one invocation.
-    let findings = await collect(hqRoot);
-    const appliedKeys = new Set();
-    const planned = [];
-    const backups = [];
-    let fixableCount = 0;
-    let refused = null;
-    let lastBackupMs = Number.NEGATIVE_INFINITY;
-    const backupClock = () => {
-        const suppliedMs = (options.now ?? (() => new Date()))().getTime();
-        lastBackupMs = Math.max(suppliedMs, lastBackupMs + 1);
-        return new Date(lastBackupMs);
-    };
-    const buildPlans = (results) => {
-        const keysThisPass = new Set();
-        const plans = [];
-        for (const result of results) {
-            const rem = deriveRemediation(result);
-            if (!rem?.autoFixable)
-                continue;
-            const plan = planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath);
-            if (!plan)
-                continue;
-            const key = JSON.stringify([plan.checkId, plan.target]);
-            if (appliedKeys.has(key) || keysThisPass.has(key))
-                continue;
-            keysThisPass.add(key);
-            plans.push(plan);
-        }
-        return plans;
-    };
-    for (let pass = 1; pass <= MAX_FIX_PASSES; pass += 1) {
-        const plans = buildPlans(findings);
-        if (plans.length === 0)
-            break;
-        fixableCount += plans.length;
-        // 3. Preview and require confirmation for every pass unless --yes is set.
-        write(`Pass ${pass}/${MAX_FIX_PASSES}: hq doctor --fix will apply ${plans.length} repair${plans.length === 1 ? "" : "s"}:\n\n`);
-        for (const plan of plans)
-            write(plan.preview + "\n");
-        if (!options.yes) {
-            const confirmed = await Promise.resolve((options.confirm ?? declineByDefault)());
-            if (!confirmed) {
-                refused = "declined";
-                if (planned.length === 0) {
-                    write("Aborted — no changes written.\n");
-                    return empty({ refused, fixableCount });
-                }
-                write(`Pass ${pass} declined — no further changes written.\n`);
-                break;
-            }
-        }
-        // 4. Back up this pass's files before its first write. The clock advances
-        //    at least one millisecond per backup so fast consecutive passes cannot
-        //    overwrite an earlier pass's restore point.
-        const affected = unique(plans.map((plan) => plan.relpath).filter((rel) => rel.length > 0));
-        const backup = affected.length > 0 ? createBackup(hqRoot, affected, backupClock) : null;
-        if (backup) {
-            backups.push({
-                pass,
-                backupDir: backup.dir,
-                restoreCommand: backup.restoreCommand,
-            });
-            write(`\nBacked up ${backup.files.length} file${backup.files.length === 1 ? "" : "s"} for pass ${pass} to ${backup.dir}\n`);
-            write(`To restore: ${backup.restoreCommand}\n`);
-        }
-        // 5. Apply each plan once. Later findings with this check id + target are
-        //    excluded even if this repair did not make its check pass.
-        for (const plan of plans) {
-            appliedKeys.add(JSON.stringify([plan.checkId, plan.target]));
-            planned.push({ plan, pass });
-            await plan.apply();
-        }
-        // 6. Re-run checks. Newly surfaced repairs are considered by the next loop.
-        findings = await collect(hqRoot);
+    // 2. Collect findings and keep only the allowlisted auto-fixable ones.
+    const findings = await runChecks(hqRoot);
+    const fixable = [];
+    for (const result of findings) {
+        const rem = deriveRemediation(result);
+        if (rem && rem.autoFixable)
+            fixable.push({ result, rem });
     }
-    if (planned.length === 0) {
+    if (fixable.length === 0) {
         write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
-        return empty({ refused, fixableCount });
+        return empty();
     }
-    // Show each repair's final post-fix status, including work from earlier passes.
-    const applied = planned.map(({ plan, pass }) => {
-        const refreshSyncOutcome = plan.refreshSyncOutcome?.();
-        return {
-            pass,
-            checkId: plan.checkId,
-            fixClass: plan.fixClass,
-            target: plan.target,
-            summary: plan.summary,
-            postStatus: plan.postStatus(findings),
-            ...(refreshSyncOutcome ? { refreshSyncOutcome } : {}),
-        };
-    });
+    const plans = fixable
+        .map(({ result, rem }) => planFix(hqRoot, result, rem))
+        .filter((plan) => plan !== null);
+    if (plans.length === 0) {
+        write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
+        return empty();
+    }
+    // 3. Diff-style preview + confirmation (AC5).
+    write(`hq doctor --fix will apply ${plans.length} repair${plans.length === 1 ? "" : "s"}:\n\n`);
+    for (const plan of plans)
+        write(plan.preview + "\n");
+    if (!options.yes) {
+        const confirmed = await Promise.resolve((options.confirm ?? declineByDefault)());
+        if (!confirmed) {
+            write("Aborted — no changes written.\n");
+            return empty({ refused: "declined" });
+        }
+    }
+    // 4. Back up every file about to change BEFORE the first write (AC6).
+    const affected = unique(plans.map((plan) => plan.relpath));
+    const backup = createBackup(hqRoot, affected, options.now);
+    // 5. Apply. Each plan reads the current on-disk state, so multiple plans that
+    //    touch the same file (two gate ids) compose correctly.
+    for (const plan of plans)
+        plan.apply();
+    write(`\nBacked up ${backup.files.length} file${backup.files.length === 1 ? "" : "s"} to ${backup.dir}\n`);
+    write(`To restore: ${backup.restoreCommand}\n`);
+    // 6. Re-run the checks and report the post-fix status of each repair (AC7).
+    const after = await runChecks(hqRoot);
+    const applied = plans.map((plan) => ({
+        checkId: plan.checkId,
+        fixClass: plan.fixClass,
+        target: plan.target,
+        summary: plan.summary,
+        postStatus: plan.postStatus(after),
+    }));
     write("\nPost-fix status:\n");
     for (const fix of applied) {
-        write(`  ${fix.postStatus ?? "UNKNOWN"}  ${fix.checkId} [${fix.target}] (pass ${fix.pass})\n`);
-    }
-    // Restore later pass snapshots first. This also returns every file to its
-    // pre-run state when multiple passes touched the same path.
-    const restoreCommand = backups.length > 0
-        ? [...backups].reverse().map(({ restoreCommand: command }) => command).join(" && ")
-        : null;
-    if (restoreCommand)
-        write(`To restore all changes: ${restoreCommand}\n`);
-    if (planned.at(-1)?.pass === MAX_FIX_PASSES && buildPlans(findings).length > 0) {
-        write(`Stopped after ${MAX_FIX_PASSES} repair passes; new auto-fixable findings remain.\n`);
+        write(`  ${fix.postStatus ?? "UNKNOWN"}  ${fix.checkId} [${fix.target}]\n`);
     }
     return {
         exitCode: 0,
         wrote: true,
-        refused,
-        fixableCount,
-        backupDir: backups[0]?.backupDir ?? null,
-        restoreCommand,
-        backups,
+        refused: null,
+        fixableCount: fixable.length,
+        backupDir: backup.dir,
+        restoreCommand: backup.restoreCommand,
         applied,
     };
 }
 /** Run the default (read-only) check registry and flatten to a result list. */
-async function defaultRunChecks(hqRoot) {
-    // `--fix` never repairs the integrations family (networked inventory), so
-    // skip it: a hung control-plane read must not stall the safe repair pass.
-    const context = {
-        hqRoot,
-        platform: { id: "unknown" },
-        integrations: false,
-    };
+async function runChecks(hqRoot) {
+    const context = { hqRoot, platform: { id: "unknown" } };
     const families = await createDefaultRegistry().run(context);
     return flattenFamilies(families);
 }
-/**
- * Default `refresh-sync` repair: a bounded, pull-only, keep-conflicts
- * `hq sync pull --company <slug>` against the tree `--fix` is repairing.
- * Never a push, never interactive. A timeout or non-zero exit is reported
- * rather than thrown so later plans still run.
- */
-export function defaultRefreshSync(target) {
-    const hqBin = process.argv[1];
-    const args = hqBin
-        ? [
-            hqBin,
-            "sync",
-            "pull",
-            "--company",
-            target.slug,
-            "--hq-root",
-            target.hqRoot,
-            "--on-conflict",
-            "keep",
-            "--lock-timeout",
-            "30",
-        ]
-        : [
-            "sync",
-            "pull",
-            "--company",
-            target.slug,
-            "--hq-root",
-            target.hqRoot,
-            "--on-conflict",
-            "keep",
-            "--lock-timeout",
-            "30",
-        ];
-    const result = spawnSync(hqBin ? process.execPath : "hq", args, {
-        encoding: "utf8",
-        timeout: REFRESH_SYNC_TIMEOUT_MS,
-        cwd: target.hqRoot,
-    });
-    if (result.error) {
-        const spawnError = result.error;
-        const outcome = classifyRefreshSyncOutcome({
-            errorCode: spawnError.code,
-            ...(result.error.message.includes("ETIMEDOUT")
-                ? { errorCode: "ETIMEDOUT" }
-                : {}),
-            signal: result.signal,
-            status: result.status,
-            stdout: result.stdout,
-            stderr: result.stderr,
-        });
-        return Promise.resolve({
-            ok: false,
-            outcome,
-            message: outcome === "pull-timeout"
-                ? `timed out pulling '${target.slug}'`
-                : `could not start pull for '${target.slug}': ${result.error.message}`,
-        });
-    }
-    if (result.status !== 0) {
-        const outcome = classifyRefreshSyncOutcome({
-            status: result.status,
-            stdout: result.stdout,
-            stderr: result.stderr,
-        });
-        const detail = (result.stderr || result.stdout || "").trim().split("\n").at(-1) ?? "";
-        return Promise.resolve({
-            ok: false,
-            outcome,
-            message: `pull of '${target.slug}' exited ${result.status}${detail ? `: ${detail}` : ""}`,
-        });
-    }
-    return Promise.resolve({
-        ok: true,
-        outcome: "pull-succeeded",
-        message: `pulled '${target.slug}'`,
-    });
-}
 // --- Dirty-tree probe ----------------------------------------------------------
 /**
  * The uncommitted changes under {@link HOOK_CONFIG_DIRS}, one porcelain line
@@ -312,75 +155,18 @@ export function uncommittedHookConfigChanges(hqRoot) {
 }
 // --- Fix planning --------------------------------------------------------------
 /** Build the concrete plan for one auto-fixable finding, or null if unplannable. */
-function planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath = defaultRewriteBotNodePath) {
+function planFix(hqRoot, result, rem) {
     switch (rem.fixClass) {
-        case "bot-node-path":
-            return planBotNodePath(result, rem, rewriteBotNodePath);
         case "executable-bit":
             return planExecutableBit(hqRoot, result, rem);
         case "gate-profile":
             return planGateProfile(hqRoot, result, rem);
-        case "remove-stray-gate-entries":
-            return planRemoveStrayGateEntries(hqRoot, result, rem);
-        case "refresh-sync":
-            return planRefreshSync(hqRoot, result, rem, refreshSync);
+        case "register-hook":
+            return planRegisterHook(hqRoot, result, rem);
         default:
             return null;
     }
 }
-/** Rewrite one bot LaunchAgent's node path (file only; launchd untouched). */
-function planBotNodePath(result, rem, rewrite) {
-    const name = rem.fixTarget;
-    if (!name)
-        return null;
-    return {
-        checkId: result.checkId,
-        fixClass: "bot-node-path",
-        target: name,
-        relpath: "",
-        preview: `  ~/Library/LaunchAgents/ai.getindigo.hq-bot.${name}.plist\n` +
-            `    ~ node path -> upgrade-stable alias of the same node\n` +
-            `      file only: the bot is not stopped or started; the new path loads at its next start`,
-        summary: `rewrite ${name} startup agent node path`,
-        apply: () => {
-            rewrite(name);
-        },
-        postStatus: (results) => results.find((entry) => entry.checkId === result.checkId)?.status ?? null,
-    };
-}
-/** Default `bot-node-path` repair against the real bot state and LaunchAgents. */
-export function defaultRewriteBotNodePath(name) {
-    if (process.platform !== "darwin")
-        return null;
-    const dir = botDir(name);
-    const config = readBotConfig(dir);
-    if (!config)
-        return null;
-    return rewriteBotDaemonNodePath(buildBotDaemonPaths({ name, botDir: dir, hqRoot: config.hqRoot, hqBinary: "hq" }), { platform: "darwin" });
-}
-/** Pull one company to refresh a stale or never-synced journal. */
-function planRefreshSync(hqRoot, result, rem, refreshSync) {
-    const slug = rem.fixTarget;
-    if (!slug)
-        return null;
-    let outcome;
-    return {
-        checkId: result.checkId,
-        fixClass: "refresh-sync",
-        target: slug,
-        relpath: "",
-        preview: `  companies/${slug}\n` +
-            `    ~ hq sync pull --company ${slug} --on-conflict keep\n` +
-            `      refresh the stale sync journal (keeps local conflict copies)`,
-        summary: `pull ${slug} to refresh its sync journal`,
-        apply: async () => {
-            const result = await refreshSync({ slug, hqRoot });
-            outcome = result.outcome;
-        },
-        refreshSyncOutcome: () => outcome,
-        postStatus: (results) => results.find((entry) => entry.checkId === result.checkId)?.status ?? null,
-    };
-}
 /** Restore the execute bit on a hook script. */
 function planExecutableBit(hqRoot, result, rem) {
     const abs = rem.fixTarget;
@@ -444,32 +230,34 @@ function planGateProfile(hqRoot, result, rem) {
         postStatus: (results) => statusForTarget(results, ".gate-profiles", hookId),
     };
 }
-/** 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)
+/** 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)
         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: "remove-stray-gate-entries",
-        target: settingsPath,
+        fixClass: "register-hook",
+        target: scriptAbs,
         relpath,
         preview: `  ${relpath}\n` +
-            `    - ${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}`,
+            `    + hooks.${event}: register ${hookId} via hook-gate.sh\n` +
+            `      ${command}`,
+        summary: `register ${hookId} on ${event}`,
         apply: () => {
-            const latest = readJson(settingsPath) ?? {};
-            const cleaned = removeStrayGateEntries(latest).settings;
-            fs.writeFileSync(settingsPath, JSON.stringify(cleaned, null, 2) + "\n");
+            const settings = readJson(settingsPath) ?? {};
+            const updated = registerHookInSettings(settings, event, command);
+            fs.writeFileSync(settingsPath, JSON.stringify(updated, null, 2) + "\n");
         },
-        postStatus: (results) => statusForTarget(results, ".stray-gate-registration", settingsPath),
+        // 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),
     };
 }
 // --- Shell / JSON edit primitives ---------------------------------------------

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

@@ -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 auto-fixable classes are a deliberate, security-reviewed allowlist
- * (see the PRD decision record):
+ * The three — and only three — 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,16 +17,8 @@
  *   - `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.
- *   - `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.
+ *   - `register-hook`   — re-register a script that is present on disk but wired
+ *                         nowhere. Detected by the `…orphan` WARN.
  *
  * EVERYTHING else — content drift between platform copies, a missing script, a
  * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
@@ -38,7 +30,7 @@
  */
 import type { CheckResult } from "../types.js";
 /** The allowlisted safe repair classes `--fix` is permitted to apply. */
-export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync" | "bot-node-path";
+export type FixClass = "executable-bit" | "gate-profile" | "register-hook";
 /**
  * A finding's structured remediation. `autoFixable`, `action`, and `command`
  * are the `--json` surface (AC1); `fixTarget`/`fixClass` are the internal handle
@@ -54,7 +46,7 @@ export interface Remediation {
     /** The safe class when {@link autoFixable}, else null (manual-only). */
     fixClass: FixClass | null;
     /**
-     * The concrete file path (exec-bit, remove-stray-gate-entries) or hook id (gate-profile)
+     * The concrete file path (exec-bit, register-hook) 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

@@ -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 auto-fixable classes are a deliberate, security-reviewed allowlist
- * (see the PRD decision record):
+ * The three — and only three — 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,16 +17,8 @@
  *   - `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.
- *   - `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.
+ *   - `register-hook`   — re-register a script that is present on disk but wired
+ *                         nowhere. Detected by the `…orphan` WARN.
  *
  * EVERYTHING else — content drift between platform copies, a missing script, a
  * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
@@ -36,7 +28,6 @@
  * 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+(.+)$/;
 /**
@@ -89,45 +80,14 @@ export function deriveRemediation(result) {
             command: remediation ?? `Add ${target} to the missing hook-gate.sh profiles.`,
         };
     }
-    // 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) {
+    // register-hook — a script on disk that no settings file references.
+    if (checkId.endsWith(".orphan") && target) {
         return {
             autoFixable: true,
-            fixClass: "remove-stray-gate-entries",
+            fixClass: "register-hook",
             fixTarget: target,
-            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`,
+            action: `Re-register ${target} in .claude/settings.json.`,
+            command: remediation ?? `Register ${target} in .claude/settings.json.`,
         };
     }
     // Manual-only: content drift, missing scripts/counterparts, unquoted

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

@@ -27,7 +27,6 @@
  *     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
@@ -243,4 +242,7 @@ 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, SyncReasonCode } from "./types.js";
+import type { DoctorStatus, FamilyRun } 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,10 +50,6 @@ 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. */
@@ -75,14 +71,6 @@ 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[];
 }
@@ -94,10 +82,6 @@ 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;