@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/doctor/client-health-reason-codes-flag.js

@@ -0,0 +1,106 @@
+import { createFlagClient, } from "@indigoai-us/hq-flags-client";
+import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+import { getClientHealthFlagToken } from "./client-health-flag-token.js";
+export const CLIENT_HEALTH_REASON_CODES_FLAG = "client-health-sync-reason-codes";
+export const CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK = false;
+export const CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS = 150;
+function safeErrorClass(error) {
+    const name = error instanceof Error ? error.name : "UnknownError";
+    return /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name) ? name : "UnknownError";
+}
+function reportFlagFailure(error) {
+    process.stderr.write(`HQ client-health reason-code flag lookup failed (${safeErrorClass(error)}); using default off.\n`);
+}
+function combineSignals(first, second) {
+    return first ? AbortSignal.any([first, second]) : second;
+}
+/**
+ * Resolve the privacy gate from hq-flags with a bounded request. Missing
+ * identity, service configuration, and every lookup failure keep diagnostics
+ * off so a flag outage cannot delay the doctor's health result.
+ */
+export async function clientHealthReasonCodesEnabled(dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const companyUid = env.HQ_COMPANY_UID?.trim() || "";
+    if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
+    }
+    return clientHealthReasonCodesEnabledForCompany({
+        companyUid,
+        companySlug: env.HQ_COMPANY_SLUG?.trim() || undefined,
+    }, dependencies, callerSignal);
+}
+/** Resolve the same default-off gate for one explicitly identified company. */
+export async function clientHealthReasonCodesEnabledForCompany(company, dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const endpoint = resolveFlagRegistryEndpoint(undefined, env);
+    const companyUid = company.companyUid.trim();
+    if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
+    }
+    const companySlug = company.companySlug?.trim() || "";
+    if (callerSignal?.aborted)
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
+    let client;
+    let failed = false;
+    let failureReported = false;
+    let enabled = CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
+    const reportFailureOnce = (error) => {
+        failed = true;
+        if (failureReported)
+            return;
+        failureReported = true;
+        (dependencies.reportFailure ?? reportFlagFailure)(error);
+    };
+    let token;
+    try {
+        token = await getClientHealthFlagToken(dependencies.getToken, dependencies.tokenTimeoutMs, callerSignal);
+    }
+    catch (error) {
+        if (!callerSignal?.aborted)
+            reportFailureOnce(error);
+        return CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK;
+    }
+    const deadline = AbortSignal.timeout(CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS);
+    const signal = callerSignal ? AbortSignal.any([callerSignal, deadline]) : deadline;
+    const doFetch = dependencies.fetch ?? globalThis.fetch;
+    try {
+        client = (dependencies.createClient ?? createFlagClient)({
+            endpoint,
+            companyUid,
+            ...(companySlug && /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/.test(companySlug)
+                ? { companyIdentifiers: [companySlug] }
+                : {}),
+            env: {},
+            getToken: () => token,
+            fetch: (input, init) => doFetch(input, {
+                ...init,
+                signal: combineSignals(init?.signal ?? undefined, signal),
+            }),
+            refreshIntervalMs: 0,
+            requestTimeoutMs: CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS,
+            onError: reportFailureOnce,
+        });
+        await client.ready();
+        if (!failed && !signal.aborted) {
+            enabled = client.isEnabled(CLIENT_HEALTH_REASON_CODES_FLAG, {
+                fallback: CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK,
+            });
+        }
+    }
+    catch (error) {
+        reportFailureOnce(error);
+    }
+    finally {
+        try {
+            client?.close();
+        }
+        catch (error) {
+            reportFailureOnce(error);
+        }
+    }
+    return failed || signal.aborted
+        ? CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK
+        : enabled;
+}
+//# sourceMappingURL=client-health-reason-codes-flag.js.map

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

@@ -31,22 +31,6 @@ import type { DoctorJsonDocument } from "./json-output.js";
 export declare const CHECK_HQ_HOOKS_PASS_EXIT = 0;
 /** Exit code check-hq-hooks.sh returns on a health failure. Preserved. */
 export declare const CHECK_HQ_HOOKS_FAIL_EXIT = 2;
-/** Exit code check-hq-hooks.sh returns on a usage error. Preserved. */
-export declare const CHECK_HQ_HOOKS_USAGE_EXIT = 64;
-/** The runtime-probe result id: whether hooks actually fired (the ledger). */
-export declare const RUNTIME_ENFORCEMENT_CHECK_ID = "hooks.runtime.enforcement";
-/**
- * The `hq doctor` check ids that correspond to check-hq-hooks.sh's *settings
- * load* scope — the subset of the hooks family the wrapper is allowed to fail
- * on. Deliberately narrow: it covers a missing/invalid settings file, an
- * unquoted `$CLAUDE_PROJECT_DIR` that word-splits on a spaced root, and a hook
- * command that runs a script which is not on disk — and nothing else. The many
- * richer doctor findings (executable bits, orphaned scripts, three-profile
- * membership, Codex/Grok parity, fixture coverage) are intentionally OUT of
- * scope, so the wrapper stays byte-for-byte compatible with callers that only
- * ever cared whether the hook configuration could load.
- */
-export declare const CHECK_HQ_HOOKS_SETTINGS_SCOPE: readonly string[];
 /**
  * Whether hook dispatch was observed this session. Mirrors the wrapper's
  * `HQ runtime enforcement: …` line. `NOT CHECKED` is the default when

package/dist/lib/doctor/compat.js

@@ -31,9 +31,9 @@ export const CHECK_HQ_HOOKS_PASS_EXIT = 0;
 /** Exit code check-hq-hooks.sh returns on a health failure. Preserved. */
 export const CHECK_HQ_HOOKS_FAIL_EXIT = 2;
 /** Exit code check-hq-hooks.sh returns on a usage error. Preserved. */
-export const CHECK_HQ_HOOKS_USAGE_EXIT = 64;
+const CHECK_HQ_HOOKS_USAGE_EXIT = 64;
 /** The runtime-probe result id: whether hooks actually fired (the ledger). */
-export const RUNTIME_ENFORCEMENT_CHECK_ID = "hooks.runtime.enforcement";
+const RUNTIME_ENFORCEMENT_CHECK_ID = "hooks.runtime.enforcement";
 /**
  * The `hq doctor` check ids that correspond to check-hq-hooks.sh's *settings
  * load* scope — the subset of the hooks family the wrapper is allowed to fail
@@ -45,8 +45,9 @@ export const RUNTIME_ENFORCEMENT_CHECK_ID = "hooks.runtime.enforcement";
  * scope, so the wrapper stays byte-for-byte compatible with callers that only
  * ever cared whether the hook configuration could load.
  */
-export const CHECK_HQ_HOOKS_SETTINGS_SCOPE = [
+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/deep/effects.js

@@ -36,6 +36,7 @@ import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { isRecord } from "../shared.js";
 /**
  * Parse a fixture case's `effects:` field into a list of {@link
  * EffectExpectation}. Returns the list, or an error string naming what was
@@ -223,7 +224,4 @@ function hashFile(abs) {
         return null;
     }
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 //# sourceMappingURL=effects.js.map

package/dist/lib/doctor/deep/executor.d.ts

@@ -55,7 +55,7 @@ export declare const DEFAULT_PER_CASE_TIMEOUT_MS = 10000;
  */
 export declare const SANDBOX_COPY_RELPATHS: readonly string[];
 /** One gate execution's inputs. */
-export interface GateRunInput {
+interface GateRunInput {
     /** Absolute path to the sandboxed `hook-gate.sh`. */
     gatePath: string;
     /** Absolute path to the sandboxed hook script the gate delegates to. */
@@ -72,7 +72,7 @@ export interface GateRunInput {
     timeoutMs: number;
 }
 /** One gate execution's observed outcome. */
-export interface GateRunResult {
+interface GateRunResult {
     /** True when the execution exceeded {@link GateRunInput.timeoutMs}. */
     timedOut: boolean;
     /** Gate exit code, or null when it did not exit normally (timeout/signal). */
@@ -81,14 +81,7 @@ export interface GateRunResult {
     stderr: string;
 }
 /** Executes one gate invocation. Injectable so the aggregation is unit-testable. */
-export type GateRunner = (input: GateRunInput) => GateRunResult;
-/**
- * The real runner: spawn `bash hook-gate.sh <id> <script>` with the payload on
- * stdin, `HQ_HOOK_PROFILE` set, and a hard timeout. A timeout is detected by the
- * `ETIMEDOUT` error code spawnSync reports; the process is killed with SIGKILL so
- * a hook cannot ignore the bound.
- */
-export declare const defaultGateRunner: GateRunner;
+type GateRunner = (input: GateRunInput) => GateRunResult;
 /** Options for {@link runDeepGuardTests}. All are injectable for testing. */
 export interface DeepTestOptions {
     /** Per-case time bound. Default: {@link DEFAULT_PER_CASE_TIMEOUT_MS}. */
@@ -109,4 +102,5 @@ export declare function cleanupAllDeepSandboxes(): void;
  * an empty list — creating no sandbox — when there is nothing to run.
  */
 export declare function runDeepGuardTests(context: CheckContext, options?: DeepTestOptions): Promise<CheckResult[]>;
+export {};
 //# sourceMappingURL=executor.d.ts.map

package/dist/lib/doctor/deep/executor.js

@@ -74,7 +74,7 @@ export const SANDBOX_COPY_RELPATHS = [
  * `ETIMEDOUT` error code spawnSync reports; the process is killed with SIGKILL so
  * a hook cannot ignore the bound.
  */
-export const defaultGateRunner = (input) => {
+const defaultGateRunner = (input) => {
     const result = spawnSync("bash", [input.gatePath, input.hookId, input.hookScriptPath], {
         input: input.payload,
         cwd: input.cwd,

package/dist/lib/doctor/deep/parity.d.ts

@@ -46,14 +46,6 @@ import { type PlatformId } from "../payload-shapes.js";
 export declare const PARITY_FAMILY_ID = "deep-parity";
 /** Human title of the parity family. */
 export declare const PARITY_FAMILY_TITLE = "Cross-platform parity replay";
-/** Default per-case, per-platform time bound. */
-export declare const DEFAULT_PARITY_TIMEOUT_MS = 10000;
-/** The gate profile the replay runs each hook under. Strict is the broadest
- * allowlist, so profile gating never suppresses the hook whose LOGIC is being
- * compared across platforms — profile-specific behaviour is US-008's concern. */
-export declare const PARITY_GATE_PROFILE = "strict";
-/** The session id stamped onto every replay payload. */
-export declare const PARITY_SESSION_ID = "hq-doctor-parity-replay";
 /** One platform replay's inputs. */
 export interface PlatformRunInput {
     /** Which platform's adapter path to exercise. */
@@ -85,27 +77,7 @@ export interface PlatformRunOutput {
 /** Executes one platform replay. Injectable so the comparison is unit-testable. */
 export type PlatformRunner = (input: PlatformRunInput) => PlatformRunOutput;
 /** The real runner set, keyed by platform. */
-export type PlatformRunners = Record<PlatformId, PlatformRunner>;
-/** The real Claude runner: the canonical script through the Claude gate. */
-export declare const defaultClaudeRunner: PlatformRunner;
-/** The real Codex runner: the duplicated mirror through the Codex gate. */
-export declare const defaultCodexRunner: PlatformRunner;
-/**
- * The real Grok runner. Grok shares the canonical `.claude/hooks/` scripts with
- * Claude — it has no mirror of its own — and its adapter's whole job is to read
- * the camelCase payload, map the tool alias back to canonical, build the Claude
- * JSON, and pipe it to the same `hook-gate.sh`. We reproduce that routing here
- * (via {@link toGrokPayload} + {@link grokToSnakePayload}) rather than spawn the
- * adapter directly, for two reasons: the live adapter runs a whole tool
- * *sequence* where the replay needs one isolated hook, and its user-global
- * bridge cannot be simulated from a project-local run (US-005 keeps bridge
- * presence a wiring check). The Grok block protocol still applies — the gate's
- * non-zero exit is what the adapter would translate into a stdout `deny`
- * ({@link interpretGrokBlock} in verdictFor recognises both).
- */
-export declare const defaultGrokRunner: PlatformRunner;
-/** The default real runner set wired to each platform's real adapter path. */
-export declare const defaultPlatformRunners: PlatformRunners;
+type PlatformRunners = Record<PlatformId, PlatformRunner>;
 /** Options for {@link runParityReplay}. All injectable for testing. */
 export interface ParityOptions {
     /** Per-case, per-platform time bound. Default: {@link DEFAULT_PARITY_TIMEOUT_MS}. */
@@ -126,4 +98,5 @@ export declare function cleanupAllParitySandboxes(): void;
  * empty list — creating no sandbox — when there is nothing to replay.
  */
 export declare function runParityReplay(context: CheckContext, options?: ParityOptions): Promise<CheckResult[]>;
+export {};
 //# sourceMappingURL=parity.d.ts.map

package/dist/lib/doctor/deep/parity.js

@@ -52,13 +52,13 @@ export const PARITY_FAMILY_ID = "deep-parity";
 /** Human title of the parity family. */
 export const PARITY_FAMILY_TITLE = "Cross-platform parity replay";
 /** Default per-case, per-platform time bound. */
-export const DEFAULT_PARITY_TIMEOUT_MS = 10_000;
+const DEFAULT_PARITY_TIMEOUT_MS = 10_000;
 /** The gate profile the replay runs each hook under. Strict is the broadest
  * allowlist, so profile gating never suppresses the hook whose LOGIC is being
  * compared across platforms — profile-specific behaviour is US-008's concern. */
-export const PARITY_GATE_PROFILE = "strict";
+const PARITY_GATE_PROFILE = "strict";
 /** The session id stamped onto every replay payload. */
-export const PARITY_SESSION_ID = "hq-doctor-parity-replay";
+const PARITY_SESSION_ID = "hq-doctor-parity-replay";
 function spawnWithStdin(command, args, stdin, input) {
     const result = spawnSync(command, args, {
         input: stdin,
@@ -96,12 +96,12 @@ function runThroughGate(input, platformDir, payload) {
     return { ...spawned };
 }
 /** The real Claude runner: the canonical script through the Claude gate. */
-export const defaultClaudeRunner = (input) => runThroughGate(input, ".claude", JSON.stringify(toClaudePayload(input.testCase, {
+const defaultClaudeRunner = (input) => runThroughGate(input, ".claude", JSON.stringify(toClaudePayload(input.testCase, {
     cwd: input.sandbox,
     sessionId: PARITY_SESSION_ID,
 })));
 /** The real Codex runner: the duplicated mirror through the Codex gate. */
-export const defaultCodexRunner = (input) => runThroughGate(input, ".codex", JSON.stringify(toCodexPayload(input.testCase, {
+const defaultCodexRunner = (input) => runThroughGate(input, ".codex", JSON.stringify(toCodexPayload(input.testCase, {
     cwd: input.sandbox,
     sessionId: PARITY_SESSION_ID,
 })));
@@ -118,7 +118,7 @@ export const defaultCodexRunner = (input) => runThroughGate(input, ".codex", JSO
  * non-zero exit is what the adapter would translate into a stdout `deny`
  * ({@link interpretGrokBlock} in verdictFor recognises both).
  */
-export const defaultGrokRunner = (input) => {
+const defaultGrokRunner = (input) => {
     const grokPayload = toGrokPayload(input.testCase, {
         cwd: input.sandbox,
         sessionId: PARITY_SESSION_ID,
@@ -127,7 +127,7 @@ export const defaultGrokRunner = (input) => {
     return runThroughGate(input, ".claude", JSON.stringify(snake));
 };
 /** The default real runner set wired to each platform's real adapter path. */
-export const defaultPlatformRunners = {
+const defaultPlatformRunners = {
     claude: defaultClaudeRunner,
     codex: defaultCodexRunner,
     grok: defaultGrokRunner,

package/dist/lib/doctor/deep/sandbox.d.ts

@@ -46,21 +46,10 @@ export declare const DEFAULT_PER_CASE_TIMEOUT_MS = 15000;
  * come under sandboxed execution.
  */
 export type Precondition = "git-repo" | "session-metadata" | "company-scaffold";
-/** Every precondition the default seeder knows how to provide. */
-export declare const KNOWN_PRECONDITIONS: readonly Precondition[];
-/**
- * Tree entries copied from the live tree into every sandbox — the same curated
- * set US-008 uses: the hook scripts and gate, the settings a hook may read, the
- * Codex/Grok mirrors, and `core/` (helpers hooks source). Missing entries are
- * skipped so a partial tree still sandboxes cleanly.
- */
-export declare const SANDBOX_SEED_RELPATHS: readonly string[];
 /** Remove every side-effect sandbox still on disk. Safe to call repeatedly. */
 export declare function cleanupAllSandboxes(): void;
 /** The sandbox roots this process is still tracking (for tests). */
 export declare function trackedSandboxRoots(): string[];
-/** Remove one sandbox and stop tracking it. Idempotent. */
-export declare function destroySandbox(root: string): void;
 /** The outcome of seeding one sandbox. */
 export interface SeedResult {
     /** Absolute, realpath'd sandbox root under the OS temp dir. */
@@ -91,7 +80,7 @@ export interface SeedOptions {
  */
 export declare function seedSandbox(hqRoot: string, opts?: SeedOptions): SeedResult;
 /** One hook execution's inputs. */
-export interface HookRunInput {
+interface HookRunInput {
     /** Absolute path to the sandboxed hook script. */
     hookScriptPath: string;
     /** The JSON payload piped to the hook's stdin. */
@@ -104,7 +93,7 @@ export interface HookRunInput {
     timeoutMs: number;
 }
 /** One hook execution's observed result (exit code is diagnostic only). */
-export interface HookRunResult {
+interface HookRunResult {
     /** True when the execution exceeded {@link HookRunInput.timeoutMs}. */
     timedOut: boolean;
     /** Exit code, or null when it did not exit normally (timeout/signal). */
@@ -113,17 +102,9 @@ export interface HookRunResult {
     stderr: string;
 }
 /** Runs one hook. Injectable so the tier's aggregation is unit-testable. */
-export type HookRunner = (input: HookRunInput) => HookRunResult;
-/**
- * The real runner: fire the hook script directly with the payload on stdin, its
- * cwd and session env pointed at the sandbox, and a hard timeout. Unlike a pure
- * guard (US-008), a side-effecting hook is run directly rather than through the
- * gate — its exit code is irrelevant here; what matters is the effect it leaves
- * on the sandbox, which effects.ts reads afterwards.
- */
-export declare const defaultHookRunner: HookRunner;
+type HookRunner = (input: HookRunInput) => HookRunResult;
 /** One parsed side-effecting fixture case (its own shape, not the US-007 schema). */
-export interface SideEffectCase {
+interface SideEffectCase {
     name: string;
     event: string;
     tool: string;
@@ -136,13 +117,13 @@ export interface SideEffectCase {
     expectedFailure?: ExpectedFailure;
 }
 /** A validated side-effecting fixture. */
-export interface SideEffectFixture {
+interface SideEffectFixture {
     hookId: string;
     relpath: string;
     cases: SideEffectCase[];
 }
 /** A side-effecting fixture that could not be parsed. */
-export interface SideEffectFixtureError {
+interface SideEffectFixtureError {
     hookId: string | null;
     relpath: string;
     message: string;
@@ -187,4 +168,5 @@ export interface SideEffectTestOptions {
  * Returns an empty list when there is nothing side-effecting to run.
  */
 export declare function runSideEffectTests(context: CheckContext, options?: SideEffectTestOptions): Promise<CheckResult[]>;
+export {};
 //# sourceMappingURL=sandbox.d.ts.map

package/dist/lib/doctor/deep/sandbox.js

@@ -39,6 +39,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as yaml from "js-yaml";
+import { isRecord } from "../shared.js";
 import { classifyCaseStatus, looksLikeFixture, } from "../fixtures/schema.js";
 import { HOOK_TESTS_RELDIR, registeredHookIds } from "../fixtures/discover.js";
 import { isSideEffectingHookId } from "./classify.js";
@@ -46,7 +47,7 @@ import { captureEffectBaseline, describeEffect, defaultGitProbe, evaluateEffects
 /** Default per-case time bound. No latency target, but no case may hang. */
 export const DEFAULT_PER_CASE_TIMEOUT_MS = 15_000;
 /** Every precondition the default seeder knows how to provide. */
-export const KNOWN_PRECONDITIONS = [
+const KNOWN_PRECONDITIONS = [
     "git-repo",
     "session-metadata",
     "company-scaffold",
@@ -57,7 +58,7 @@ export const KNOWN_PRECONDITIONS = [
  * Codex/Grok mirrors, and `core/` (helpers hooks source). Missing entries are
  * skipped so a partial tree still sandboxes cleanly.
  */
-export const SANDBOX_SEED_RELPATHS = [
+const SANDBOX_SEED_RELPATHS = [
     ".claude/hooks",
     ".claude/settings.json",
     ".claude/settings.local.json",
@@ -100,7 +101,7 @@ function removeTree(root) {
     }
 }
 /** Remove one sandbox and stop tracking it. Idempotent. */
-export function destroySandbox(root) {
+function destroySandbox(root) {
     removeTree(root);
     trackedSandboxes.delete(root);
 }
@@ -198,7 +199,7 @@ function git(root, args) {
  * gate — its exit code is irrelevant here; what matters is the effect it leaves
  * on the sandbox, which effects.ts reads afterwards.
  */
-export const defaultHookRunner = (input) => {
+const defaultHookRunner = (input) => {
     const result = spawnSync("bash", [input.hookScriptPath], {
         input: input.payload,
         cwd: input.cwd,
@@ -566,7 +567,4 @@ function oneLine(text) {
     const collapsed = text.replace(/\s+/g, " ").trim();
     return collapsed.length > 200 ? `${collapsed.slice(0, 197)}…` : collapsed;
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 //# sourceMappingURL=sandbox.js.map

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

@@ -8,11 +8,13 @@
  *      `.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 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.
+ *   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.
  *   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
@@ -26,9 +28,10 @@
  * (the command resolves it once), keeping this module decoupled from the CLI and
  * trivially testable against a fake tree.
  */
-import type { DoctorStatus } from "../types.js";
+import type { CheckResult, DoctorStatus } from "../types.js";
 import { type GateProfile } from "../hook-gate-profiles.js";
 import { type FixClass } from "./remediation.js";
+import { type RefreshSyncOutcome } from "./refresh-sync-outcome.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export declare const HOOK_CONFIG_DIRS: readonly [".claude", ".codex", ".grok"];
 /** Options for {@link applyFixes}. Everything is injectable for hermetic tests. */
@@ -56,9 +59,50 @@ export interface ApplyFixesOptions {
      * [] when clean or not a git repo. Default shells out to `git status`.
      */
     dirtyCheck?: (hqRoot: string) => string[];
+    /**
+     * Check runner used to collect findings and to re-verify after applying.
+     * Default runs the real registry. Tests inject a fake list so refresh-sync
+     * does not depend on the machine's live journal store.
+     */
+    runChecks?: (hqRoot: string) => Promise<CheckResult[]>;
+    /**
+     * Targeted pull used by the `refresh-sync` class. Default shells out to
+     * `hq sync pull --company <slug> --on-conflict keep`. Tests inject a stub
+     * so `--fix` never hits the network.
+     */
+    refreshSync?: (target: RefreshSyncTarget) => Promise<RefreshSyncResult>;
+    /**
+     * File-only rewrite used by the `bot-node-path` class. Default rewrites
+     * ~/Library/LaunchAgents/ai.getindigo.hq-bot.<name>.plist and never calls
+     * launchctl. Tests inject a stub.
+     */
+    rewriteBotNodePath?: (name: string) => {
+        from: string;
+        to: string;
+    } | null;
 }
+/** One company the `refresh-sync` class will pull. */
+export interface RefreshSyncTarget {
+    /** Company slug from the `sync.journal.<slug>` check id. */
+    slug: string;
+    /** HQ root the pull writes into. */
+    hqRoot: string;
+}
+/** Outcome of one {@link ApplyFixesOptions.refreshSync} call. */
+export interface RefreshSyncResult {
+    /** Whether the pull exited 0. */
+    ok: boolean;
+    /** Closed enum for machine-readable client-health diagnostics. */
+    outcome: RefreshSyncOutcome;
+    /** One-line summary for the post-fix report. */
+    message: string;
+}
+/** Per-company bound for the default `hq sync pull` repair. */
+export declare const REFRESH_SYNC_TIMEOUT_MS = 90000;
 /** One applied (or attempted) repair, with its post-fix re-check status. */
 export interface AppliedFix {
+    /** One-based repair pass in this `hq doctor --fix` invocation. */
+    pass: number;
     /** The check id of the finding that was repaired. */
     checkId: string;
     /** The safe class applied. */
@@ -69,14 +113,27 @@ export interface AppliedFix {
     summary: string;
     /** The status of the re-run check for this target, or null if not found. */
     postStatus: DoctorStatus | null;
+    /** Present for refresh-sync plans; contains no command output or path data. */
+    refreshSyncOutcome?: RefreshSyncOutcome;
 }
+/** Backup and restore information for one pass that wrote files. */
+export interface AppliedFixBackup {
+    /** One-based repair pass that created this backup. */
+    pass: number;
+    /** Absolute path of the backup directory. */
+    backupDir: string;
+    /** Command that restores this pass's pre-write files. */
+    restoreCommand: string;
+}
+/** A newly unlocked safe repair can be picked up for at most this many passes. */
+export declare const MAX_FIX_PASSES = 3;
 /** The outcome of an {@link applyFixes} run. */
 export interface ApplyFixesResult {
-    /** 0 on success or a clean no-op; 1 when the run was refused. */
+    /** 0 on success, decline, or a clean no-op; 1 when a dirty tree is refused. */
     exitCode: number;
     /** Whether any file was written. */
     wrote: boolean;
-    /** Why the run wrote nothing, when it did not: refusal reason or null. */
+    /** Why no further repairs were applied, when the run stopped early. */
     refused: "dirty-tree" | "declined" | null;
     /** How many findings were auto-fixable. */
     fixableCount: number;
@@ -84,6 +141,8 @@ export interface ApplyFixesResult {
     backupDir: string | null;
     /** The restore command, or null when nothing was written. */
     restoreCommand: string | null;
+    /** Every backup made, in pass order. */
+    backups: AppliedFixBackup[];
     /** The applied repairs with their post-fix status. */
     applied: AppliedFix[];
 }
@@ -94,6 +153,13 @@ export interface ApplyFixesResult {
  * assert on it.
  */
 export declare function applyFixes(options: ApplyFixesOptions): Promise<ApplyFixesResult>;
+/**
+ * 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 declare function defaultRefreshSync(target: RefreshSyncTarget): Promise<RefreshSyncResult>;
 /**
  * The uncommitted changes under {@link HOOK_CONFIG_DIRS}, one porcelain line
  * each. Returns [] when the tree is clean OR when `hqRoot` is not a git repo
@@ -101,6 +167,11 @@ export declare function applyFixes(options: ApplyFixesOptions): Promise<ApplyFix
  * the backup still covers the write.
  */
 export declare function uncommittedHookConfigChanges(hqRoot: string): string[];
+/** Default `bot-node-path` repair against the real bot state and LaunchAgents. */
+export declare function defaultRewriteBotNodePath(name: string): {
+    from: string;
+    to: string;
+} | null;
 /**
  * Insert a new `case` arm allowlisting `hookId` (leading to `return 0`) at the
  * top of each named profile function's `case "$1" in` block. Additive: it never