@indigoai-us/hq-cli 5.345.147 → 5.345.148

package/dist/lib/doctor/checks/hook-engine.js

@@ -0,0 +1,16 @@
+import { findHookEngine, hookEngineRequired, pinnedHookEngineMatches, HOOK_ENGINE_REPAIR, HOOK_ENGINE_REPAIR_PIN } from '../../hook-engine/resolve.js';
+export function checkHookEngine() {
+    const required = hookEngineRequired();
+    const fallback = required ? 'Native engine is required; repair before running hooks.' : 'Existing bash hooks remain active.';
+    try {
+        const engine = findHookEngine();
+        if (engine && pinnedHookEngineMatches(engine))
+            return { checkId: 'hooks.native-engine', status: 'PASS', target: engine.pinned, message: `Native hook engine ${engine.version} installed at its version-pinned path.` };
+        return { checkId: 'hooks.native-engine', status: required ? 'FAIL' : 'WARN', message: `Native hook engine is missing or damaged. ${fallback}`, remediation: engine ? `Close HQ sessions, then run ${HOOK_ENGINE_REPAIR_PIN}` : HOOK_ENGINE_REPAIR };
+    }
+    catch (error) {
+        return { checkId: 'hooks.native-engine', status: required ? 'FAIL' : 'WARN', message: `Native hook engine unavailable: ${error.message}. ${fallback}`, remediation: HOOK_ENGINE_REPAIR };
+    }
+}
+export const hookEngineFamily = { id: 'hook-engine', title: 'Native hook engine', run: async () => [checkHookEngine()] };
+//# sourceMappingURL=hook-engine.js.map

package/dist/lib/doctor/checks/sync-health.d.ts

@@ -100,6 +100,13 @@ export interface SyncHealthDeps {
      * unhealthy-sync signal, and `hq doctor --fix` has nothing local to refresh.
      */
     localCompanyExists?: (slug: string) => boolean;
+    /**
+     * Whether HQ_SYNC_MANIFEST_DISABLED turns manifest uploads off on this
+     * machine. Defaults to reading the environment the way `hq sync manifest`
+     * does. When true a stale row names the switch and is not auto-fixable,
+     * since a re-upload would exit 0 without uploading.
+     */
+    manifestUploadsDisabled?: () => boolean;
 }
 /**
  * True when `slug` is a filesystem-safe company folder name. Rejects empty

package/dist/lib/doctor/checks/sync-health.js

@@ -33,6 +33,7 @@ import * as path from "node:path";
 import * as hqCloud from "@indigoai-us/hq-cloud";
 import { loadManifestExports, MANIFEST_UNAVAILABLE_REASON, } from "../../hq-cloud-manifest.js";
 import { readCompaniesManifestMap } from "../../work-context/repo-remote.js";
+import { MANIFEST_DISABLED_ENV, manifestUploadsDisabled, } from "../../manifest-disabled.js";
 import { CLI_VERSION } from "../../../cli-version.js";
 import { readSyncVersion } from "../../../utils/feedback-versions.js";
 import { readHqVersion } from "../../../utils/pack-contributions.js";
@@ -58,6 +59,7 @@ function withDefaults(deps, hqRoot) {
         unresolvedScopes: deps.unresolvedScopes ?? ((journals) => defaultUnresolvedScopes(hqRoot, journals)),
         localCompanyExists: deps.localCompanyExists ??
             ((slug) => defaultLocalCompanyExists(hqRoot, slug)),
+        manifestUploadsDisabled: deps.manifestUploadsDisabled ?? (() => manifestUploadsDisabled()),
     };
 }
 /**
@@ -216,6 +218,22 @@ function boundInvalidScopeToken(token) {
         return token;
     return token.slice(0, maxSuffix);
 }
+/**
+ * The `hq sync manifest --scope` value that re-uploads this status's scope:
+ * `personal`, the company slug, or undefined when the scope cannot be named
+ * safely (a company row whose slug was not resolved locally).
+ */
+function manifestUploadScope(entry) {
+    if (entry.scopeKey === "personal")
+        return "personal";
+    if (entry.scopeKey.startsWith("company:") &&
+        entry.companySlug &&
+        isSafeCompanySlug(entry.companySlug) &&
+        !NON_COMPANY_JOURNAL_SLUGS.has(entry.companySlug)) {
+        return entry.companySlug;
+    }
+    return undefined;
+}
 /**
  * Doctor JSON `checkId` for a manifest scope. hq-cloud keys company rows
  * `company:cmp_…`; the colon is replaced so SessionStart health can report
@@ -629,12 +647,30 @@ function manifestResults(deps, journals) {
             : "next pass will send a full manifest";
         if (ageMs > STALE_MANIFEST_THRESHOLD_MS) {
             const days = Math.floor(ageMs / 86_400_000);
+            // `target` is the `hq sync manifest --scope` value `--fix` re-uploads.
+            // Without it the row stays manual-only. Personal must be explicit: a
+            // bare `hq sync manifest` uploads the active company instead.
+            const scope = manifestUploadScope(entry);
+            const command = `hq sync manifest${scope ? ` --scope ${scope}` : ""}`;
+            const message = `Scope '${entry.scopeKey}' last uploaded a sync manifest ${days} day${days === 1 ? "" : "s"} ago (${entry.lastUploadAt}) — the daily audit pass is not running.`;
+            // With the kill switch set the upload exits 0 and sends nothing, so the
+            // row carries no `--fix` target and names the switch instead.
+            if (deps.manifestUploadsDisabled()) {
+                return {
+                    status: "WARN",
+                    checkId,
+                    reasonCode: "stale-threshold",
+                    message: `${message} Manifest uploads are turned off on this machine by ${MANIFEST_DISABLED_ENV}.`,
+                    remediation: `Unset ${MANIFEST_DISABLED_ENV}, then run \`${command}\`.`,
+                };
+            }
             return {
                 status: "WARN",
                 checkId,
                 reasonCode: "stale-threshold",
-                message: `Scope '${entry.scopeKey}' last uploaded a sync manifest ${days} day${days === 1 ? "" : "s"} ago (${entry.lastUploadAt}) — the daily audit pass is not running.`,
-                remediation: `Run \`hq sync manifest${entry.companySlug ? ` --scope ${entry.companySlug}` : ""}\` and check HQ_SYNC_MANIFEST_DISABLED and the sync runner.`,
+                ...(scope ? { target: scope } : {}),
+                message,
+                remediation: `Run \`${command}\` and check ${MANIFEST_DISABLED_ENV} and the sync runner.`,
             };
         }
         return {

package/dist/lib/doctor/checks/temp-homes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Doctor family: abandoned throwaway `$HOME` folders.
+ *
+ * Read-only and cheap. It runs the sweeper in shallow mode: no size walk and
+ * no process probe, so plain `hq doctor` stays fast. It reports how many idle
+ * temp homes it found; `hq doctor --sweep-temp-homes --dry-run` measures them,
+ * and `hq doctor --sweep-temp-homes` removes them.
+ */
+import { type TempHomeSweepOptions } from "../temp-home-sweeper.js";
+import type { CheckFamily, CheckResult } from "../types.js";
+export declare const TEMP_HOMES_FAMILY_ID = "temp-homes";
+export declare const TEMP_HOMES_FAMILY_TITLE = "Temp homes";
+type TempHomesCheckOptions = Omit<TempHomeSweepOptions, "dryRun" | "shallow">;
+/** Build the family; tests pass fake roots and clock through `options`. */
+export declare function createTempHomesFamily(options?: TempHomesCheckOptions): CheckFamily;
+export declare const tempHomesFamily: CheckFamily;
+export declare function checkTempHomes(options?: TempHomesCheckOptions): CheckResult[];
+export {};
+//# sourceMappingURL=temp-homes.d.ts.map

package/dist/lib/doctor/checks/temp-homes.js

@@ -0,0 +1,54 @@
+/**
+ * Doctor family: abandoned throwaway `$HOME` folders.
+ *
+ * Read-only and cheap. It runs the sweeper in shallow mode: no size walk and
+ * no process probe, so plain `hq doctor` stays fast. It reports how many idle
+ * temp homes it found; `hq doctor --sweep-temp-homes --dry-run` measures them,
+ * and `hq doctor --sweep-temp-homes` removes them.
+ */
+import { sweepTempHomes, } from "../temp-home-sweeper.js";
+export const TEMP_HOMES_FAMILY_ID = "temp-homes";
+export const TEMP_HOMES_FAMILY_TITLE = "Temp homes";
+/** Build the family; tests pass fake roots and clock through `options`. */
+export function createTempHomesFamily(options = {}) {
+    return {
+        id: TEMP_HOMES_FAMILY_ID,
+        title: TEMP_HOMES_FAMILY_TITLE,
+        run: () => Promise.resolve(checkTempHomes(options)),
+    };
+}
+export const tempHomesFamily = createTempHomesFamily();
+export function checkTempHomes(options = {}) {
+    let result;
+    try {
+        result = sweepTempHomes({ ...options, shallow: true });
+    }
+    catch (error) {
+        return [{
+                status: "UNKNOWN",
+                checkId: "temp-homes.scan-error",
+                message: `Could not scan temp folders: ${error instanceof Error ? error.message : String(error)}`,
+            }];
+    }
+    const stale = result.entries.filter((entry) => entry.action === "would-remove");
+    if (stale.length === 0) {
+        return [{
+                status: "PASS",
+                checkId: "temp-homes.none",
+                message: "No idle temp homes to sweep.",
+                details: { roots: result.roots.length },
+            }];
+    }
+    return [{
+            status: "WARN",
+            checkId: "temp-homes.stale",
+            message: `${stale.length} idle temp home${stale.length === 1 ? "" : "s"} left in the temp folder. ` +
+                "Run hq doctor --sweep-temp-homes --dry-run to see the disk space they use.",
+            details: {
+                count: stale.length,
+                paths: stale.map((entry) => entry.path),
+            },
+            remediation: "hq doctor --sweep-temp-homes --dry-run, then hq doctor --sweep-temp-homes",
+        }];
+}
+//# sourceMappingURL=temp-homes.js.map

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

@@ -34,6 +34,7 @@
  * (the command resolves it once), keeping this module decoupled from the CLI and
  * trivially testable against a fake tree.
  */
+import { type SpawnSyncReturns } from "node:child_process";
 import type { CheckResult, DoctorStatus } from "../types.js";
 import { type GateProfile } from "../hook-gate-profiles.js";
 import { type FixClass } from "./remediation.js";
@@ -78,6 +79,12 @@ export interface ApplyFixesOptions {
      * Tests inject a stub so `--fix` never hits the network.
      */
     refreshSync?: (target: RefreshSyncTarget) => Promise<RefreshSyncResult>;
+    /**
+     * Manifest upload used by the `refresh-manifest` class. Default shells out
+     * to `hq sync manifest --scope <slug|personal>`. Tests inject a stub so
+     * `--fix` never hits the network.
+     */
+    refreshManifest?: (target: RefreshManifestTarget) => Promise<RefreshManifestResult>;
     /**
      * File-only rewrite used by the `bot-node-path` class. Default rewrites
      * ~/Library/LaunchAgents/ai.getindigo.hq-bot.<name>.plist and never calls
@@ -117,6 +124,42 @@ export interface RefreshSyncResult {
 }
 /** Per-company bound for the default `hq sync pull` repair. */
 export declare const REFRESH_SYNC_TIMEOUT_MS = 90000;
+/** One manifest scope the `refresh-manifest` class will upload. */
+export interface RefreshManifestTarget {
+    /** `personal` or a company slug, as `hq sync manifest --scope` takes it. */
+    scope: string;
+    /** HQ root the manifest is built from. */
+    hqRoot: string;
+}
+/** Outcome of one {@link ApplyFixesOptions.refreshManifest} call. */
+export interface RefreshManifestResult {
+    /** Whether the upload command exited 0. The re-check is the real verdict. */
+    ok: boolean;
+    /** One-line summary. */
+    message: string;
+    /**
+     * Why the upload failed, in plain words with no paths or slugs, for the
+     * unresolved-check next step. Absent when the upload exited 0.
+     */
+    reason?: string;
+}
+/**
+ * Why a sync check is still FAIL or WARN after `--fix`:
+ *
+ *   - `manual-only`          — no safe automatic repair exists.
+ *   - `repair-did-not-clear` — `--fix` ran its repair and the re-check still fails.
+ *   - `not-attempted`        — a repair exists but this run did not get to it
+ *                              (per-run cap, declined, dirty tree, pass limit).
+ */
+export type UnresolvedSyncReason = "manual-only" | "repair-did-not-clear" | "not-attempted";
+/** A sync check `--fix` left FAIL or WARN, with the next step in plain words. */
+export interface UnresolvedSyncCheck {
+    checkId: string;
+    status: DoctorStatus;
+    reason: UnresolvedSyncReason;
+    /** What the user should do next. Never the finding message (it can hold paths). */
+    nextStep: string;
+}
 /** 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. */
@@ -145,7 +188,11 @@ export interface AppliedFixBackup {
 }
 /** A newly unlocked safe repair can be picked up for at most this many passes. */
 export declare const MAX_FIX_PASSES = 3;
-/** Two 90s pulls leave 120s for startup and check overhead under the hook's 300s ceiling. */
+/**
+ * Two 90s network repairs leave 120s for startup and check overhead under the
+ * hook's 300s ceiling. Journal pulls and manifest uploads share this budget;
+ * pulls go first and uploads take any slot left.
+ */
 export declare const MAX_REFRESH_SYNC_PLANS_PER_RUN = 2;
 /** The outcome of an {@link applyFixes} run. */
 export interface ApplyFixesResult {
@@ -165,6 +212,27 @@ export interface ApplyFixesResult {
     backups: AppliedFixBackup[];
     /** The applied repairs with their post-fix status. */
     applied: AppliedFix[];
+    /** Sync checks still FAIL or WARN when the run ended, with the next step. */
+    unresolved: UnresolvedSyncCheck[];
+}
+/** A concrete, planned change: its preview, the file it touches, and its apply. */
+interface FixPlan {
+    checkId: string;
+    fixClass: FixClass;
+    target: string;
+    /** HQ-root-relative path of the single file this plan writes. Empty when none. */
+    relpath: string;
+    /** Diff-style preview lines. */
+    preview: string;
+    /** One-line summary for the post-fix report. */
+    summary: string;
+    /** Apply the change. Reads the current on-disk state each time. */
+    apply: () => void | Promise<void>;
+    /** The status of `results` this target maps to after the fix. */
+    postStatus: (results: CheckResult[]) => DoctorStatus | null;
+    refreshSyncOutcome?: () => RefreshSyncOutcome | undefined;
+    /** Why the last apply's command failed (path-free), when it reported one. */
+    failureReason?: () => string | undefined;
 }
 /**
  * Apply every auto-fixable finding, honouring the dirty-tree refusal, the
@@ -173,6 +241,13 @@ export interface ApplyFixesResult {
  * assert on it.
  */
 export declare function applyFixes(options: ApplyFixesOptions): Promise<ApplyFixesResult>;
+/**
+ * The sync checks still FAIL or WARN in `findings`, each with why `--fix` left
+ * it and what to do next. Reported on every run, independent of the
+ * manual-only flag: the SessionStart health hook files a bug for any sync row
+ * left after `--fix`, so the user must see the same rows and a next step.
+ */
+export declare function unresolvedSyncChecks(findings: readonly CheckResult[], attempted: readonly Pick<FixPlan, "checkId" | "fixClass" | "summary" | "failureReason">[]): UnresolvedSyncCheck[];
 /**
  * Default `refresh-sync` repair: a bounded, pull-only, keep-conflicts
  * `hq sync pull --company <slug>` (or `--personal`) against the tree
@@ -180,6 +255,19 @@ export declare function applyFixes(options: ApplyFixesOptions): Promise<ApplyFix
  * non-zero exit is reported rather than thrown so later plans still run.
  */
 export declare function defaultRefreshSync(target: RefreshSyncTarget): Promise<RefreshSyncResult>;
+/**
+ * Default `refresh-manifest` repair: a bounded `hq sync manifest --scope <s>`
+ * against the tree `--fix` is repairing. Exit 0 also covers throttled,
+ * disabled, and skipped passes, so the post-fix re-check decides whether the
+ * row cleared. A timeout or non-zero exit is reported, not thrown.
+ */
+export declare function defaultRefreshManifest(target: RefreshManifestTarget): Promise<RefreshManifestResult>;
+/**
+ * Map one `hq sync manifest` spawn result to a {@link RefreshManifestResult}.
+ * A spawn killed by the timeout has a null status, so it is reported as a
+ * timeout rather than as an exit code.
+ */
+export declare function manifestUploadResult(scope: string, result: Pick<SpawnSyncReturns<string>, "error" | "status" | "signal">): RefreshManifestResult;
 /**
  * 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
@@ -218,4 +306,5 @@ export declare function addHookIdToGateProfiles(source: string, hookId: string,
  * non-object `hooks` value — it is replaced rather than trusted.
  */
 export declare function registerHookInSettings(settings: unknown, event: string, command: string): Record<string, unknown>;
+export {};
 //# sourceMappingURL=apply.d.ts.map

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

@@ -56,7 +56,11 @@ export const HOOK_CONFIG_DIRS = [".claude", ".codex", ".grok"];
 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;
-/** Two 90s pulls leave 120s for startup and check overhead under the hook's 300s ceiling. */
+/**
+ * Two 90s network repairs leave 120s for startup and check overhead under the
+ * hook's 300s ceiling. Journal pulls and manifest uploads share this budget;
+ * pulls go first and uploads take any slot left.
+ */
 export const MAX_REFRESH_SYNC_PLANS_PER_RUN = 2;
 function rotateRefreshSyncPlans(plans, afterSlug) {
     const ordered = [...plans].sort((a, b) => a.target < b.target ? -1 : a.target > b.target ? 1 : 0);
@@ -85,6 +89,7 @@ export async function applyFixes(options) {
         restoreCommand: null,
         backups: [],
         applied: [],
+        unresolved: [],
         ...over,
     });
     // 1. Dirty-tree refusal (AC8). Never write over uncommitted security-layer
@@ -99,7 +104,9 @@ export async function applyFixes(options) {
         // Journal refreshes never write hook files. Allow them by class, not
         // only by empty relpath, so a personal-vault pull and a company pull
         // still run when SessionStart `--fix --yes` cannot pass `--force`.
-        const allowed = plans.filter((plan) => plan.fixClass === "refresh-sync" || plan.relpath.length === 0);
+        const allowed = plans.filter((plan) => plan.fixClass === "refresh-sync" ||
+            plan.fixClass === "refresh-manifest" ||
+            plan.relpath.length === 0);
         if (allowed.length === plans.length)
             return plans;
         if (allowed.length === 0)
@@ -109,12 +116,14 @@ export async function applyFixes(options) {
             `re-run with --force to repair hook files.\n`);
         return allowed;
     };
-    const refuseDirtyTree = () => {
+    const refuseDirtyTree = (results) => {
         writeErr(`hq doctor --fix: refusing to run — uncommitted changes under ` +
             `${HOOK_CONFIG_DIRS.join(", ")}:\n` +
             dirty.map((line) => `  ${line}`).join("\n") +
             `\nCommit or stash them, or re-run with --force.\n`);
-        return empty({ exitCode: 1, refused: "dirty-tree" });
+        const unresolved = unresolvedSyncChecks(results, []);
+        writeUnresolvedSyncChecks(unresolved, write);
+        return empty({ exitCode: 1, refused: "dirty-tree", unresolved });
     };
     // Resolve the customer-visible manual-only output gate once per fix run.
     // Fail open to the pre-change output if the identity is absent or the
@@ -129,6 +138,7 @@ export async function applyFixes(options) {
     }
     const collect = options.runChecks ?? defaultRunChecks;
     const refreshSync = options.refreshSync ?? defaultRefreshSync;
+    const refreshManifest = options.refreshManifest ?? defaultRefreshManifest;
     const rewriteBotNodePath = options.rewriteBotNodePath ?? defaultRewriteBotNodePath;
     const repairBotHqBinary = options.repairBotHqBinary ?? defaultRepairBotHqBinary;
     // 2. Collect findings, then plan each newly unlocked allowlisted repair.
@@ -137,6 +147,7 @@ export async function applyFixes(options) {
     let findings = await collect(hqRoot);
     let lastAttemptedRefreshSyncSlug = readRefreshSyncProgress(hqRoot)?.lastAttemptedSlug ?? null;
     let refreshSyncAppliedThisRun = 0;
+    let refreshManifestAppliedThisRun = 0;
     const appliedKeys = new Set();
     const planned = [];
     const backups = [];
@@ -155,7 +166,7 @@ export async function applyFixes(options) {
             const rem = deriveRemediation(result);
             if (!rem?.autoFixable)
                 continue;
-            const plan = planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath, repairBotHqBinary);
+            const plan = planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath, repairBotHqBinary, refreshManifest);
             if (!plan)
                 continue;
             const key = JSON.stringify([plan.checkId, plan.target]);
@@ -171,16 +182,25 @@ export async function applyFixes(options) {
             seenRefreshTargets.add(plan.target);
             return true;
         }).slice(0, Math.max(0, MAX_REFRESH_SYNC_PLANS_PER_RUN - refreshSyncAppliedThisRun));
+        // Manifest uploads take whatever network budget the pulls left.
+        const manifestPlans = plans
+            .filter((plan) => plan.fixClass === "refresh-manifest")
+            .sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0))
+            .slice(0, Math.max(0, MAX_REFRESH_SYNC_PLANS_PER_RUN -
+            refreshSyncAppliedThisRun -
+            refreshManifestAppliedThisRun -
+            refreshPlans.length));
         return [
-            ...plans.filter((plan) => plan.fixClass !== "refresh-sync"),
+            ...plans.filter((plan) => plan.fixClass !== "refresh-sync" && plan.fixClass !== "refresh-manifest"),
             ...refreshPlans,
+            ...manifestPlans,
         ];
     };
     for (let pass = 1; pass <= MAX_FIX_PASSES; pass += 1) {
         const plannedThisPass = refuseDirtyHookWrites(buildPlans(findings));
         if (plannedThisPass === "refuse") {
             if (planned.length === 0)
-                return refuseDirtyTree();
+                return refuseDirtyTree(findings);
             write(`Pass ${pass}/${MAX_FIX_PASSES}: remaining repairs write hook files; ` +
                 `stopped because the tree is dirty.\n`);
             refused = "dirty-tree";
@@ -202,7 +222,9 @@ export async function applyFixes(options) {
                     write("Aborted — no changes written.\n");
                     if (showManualOnlyRemediations)
                         writeManualOnlyRemediations(findings, write);
-                    return empty({ refused, fixableCount });
+                    const unresolved = unresolvedSyncChecks(findings, []);
+                    writeUnresolvedSyncChecks(unresolved, write);
+                    return empty({ refused, fixableCount, unresolved });
                 }
                 write(`Pass ${pass} declined — no further changes written.\n`);
                 break;
@@ -233,6 +255,8 @@ export async function applyFixes(options) {
                 lastAttemptedRefreshSyncSlug = plan.target;
                 refreshSyncAppliedThisRun += 1;
             }
+            if (plan.fixClass === "refresh-manifest")
+                refreshManifestAppliedThisRun += 1;
             appliedKeys.add(JSON.stringify([plan.checkId, plan.target]));
             planned.push({ plan, pass });
             await plan.apply();
@@ -244,7 +268,9 @@ export async function applyFixes(options) {
         write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
         if (showManualOnlyRemediations)
             writeManualOnlyRemediations(findings, write);
-        return empty({ refused, fixableCount });
+        const unresolved = unresolvedSyncChecks(findings, []);
+        writeUnresolvedSyncChecks(unresolved, write);
+        return empty({ refused, fixableCount, unresolved });
     }
     // Show each repair's final post-fix status, including work from earlier passes.
     const applied = planned.map(({ plan, pass }) => {
@@ -283,6 +309,8 @@ export async function applyFixes(options) {
     }
     if (showManualOnlyRemediations)
         writeManualOnlyRemediations(findings, write);
+    const unresolved = unresolvedSyncChecks(findings, planned.map(({ plan }) => plan));
+    writeUnresolvedSyncChecks(unresolved, write);
     return {
         exitCode: 0,
         wrote: true,
@@ -292,11 +320,81 @@ export async function applyFixes(options) {
         restoreCommand,
         backups,
         applied,
+        unresolved,
     };
 }
+/**
+ * The sync checks still FAIL or WARN in `findings`, each with why `--fix` left
+ * it and what to do next. Reported on every run, independent of the
+ * manual-only flag: the SessionStart health hook files a bug for any sync row
+ * left after `--fix`, so the user must see the same rows and a next step.
+ */
+export function unresolvedSyncChecks(findings, attempted) {
+    return findings.flatMap((result) => {
+        if (!result.checkId.startsWith("sync."))
+            return [];
+        const remediation = deriveRemediation(result);
+        if (!remediation)
+            return [];
+        const tried = attempted.find((plan) => plan.checkId === result.checkId);
+        const command = remediation.command.trim();
+        if (tried) {
+            const failure = tried.failureReason?.();
+            const outcome = failure
+                ? `--fix tried to ${tried.summary}, but ${failure}, so the check still shows ${result.status}.`
+                : `--fix tried to ${tried.summary}, but the check still shows ${result.status}.`;
+            return [
+                {
+                    checkId: result.checkId,
+                    status: result.status,
+                    reason: "repair-did-not-clear",
+                    nextStep: command
+                        ? `${outcome} Run \`${command}\` yourself and read its error.`
+                        : `${outcome} Run \`hq doctor --only sync\` for details.`,
+                },
+            ];
+        }
+        if (remediation.autoFixable) {
+            return [
+                {
+                    checkId: result.checkId,
+                    status: result.status,
+                    reason: "not-attempted",
+                    nextStep: `--fix did not get to this one in this run. Run \`hq doctor --fix\` again, or run \`${command}\` now.`,
+                },
+            ];
+        }
+        // The action is the check's remediation (or a classifier override). When
+        // it is only the finding message, give a generic step: messages can hold
+        // paths, and the JSON surface carries none.
+        const nextStep = remediation.action && remediation.action !== result.message
+            ? remediation.action
+            : "Run `hq doctor --only sync` to see the details, then fix what it describes.";
+        return [
+            {
+                checkId: result.checkId,
+                status: result.status,
+                reason: "manual-only",
+                nextStep: `--fix cannot repair this automatically. ${nextStep}`,
+            },
+        ];
+    });
+}
+/** Print the sync checks `--fix` left unresolved, or nothing when there are none. */
+function writeUnresolvedSyncChecks(unresolved, write) {
+    if (unresolved.length === 0)
+        return;
+    write("\nSync checks still not resolved after --fix:\n");
+    for (const entry of unresolved) {
+        write(`  ${entry.status}  ${entry.checkId}\n    Next step: ${entry.nextStep}\n`);
+    }
+}
 /** Print the available user action for findings that `--fix` deliberately skips. */
 function writeManualOnlyRemediations(findings, write) {
     const manual = findings.flatMap((result) => {
+        // Sync rows are always listed by writeUnresolvedSyncChecks.
+        if (result.checkId.startsWith("sync."))
+            return [];
         const remediation = deriveRemediation(result);
         return remediation && !remediation.autoFixable
             ? [{ result, remediation }]
@@ -403,6 +501,49 @@ export function defaultRefreshSync(target) {
         message: `pulled '${target.slug}'`,
     });
 }
+/**
+ * Default `refresh-manifest` repair: a bounded `hq sync manifest --scope <s>`
+ * against the tree `--fix` is repairing. Exit 0 also covers throttled,
+ * disabled, and skipped passes, so the post-fix re-check decides whether the
+ * row cleared. A timeout or non-zero exit is reported, not thrown.
+ */
+export function defaultRefreshManifest(target) {
+    const hqBin = process.argv[1];
+    const args = ["sync", "manifest", "--scope", target.scope, "--hq-root", target.hqRoot];
+    const result = spawnSync(hqBin ? process.execPath : "hq", hqBin ? [hqBin, ...args] : args, {
+        encoding: "utf8",
+        timeout: REFRESH_SYNC_TIMEOUT_MS,
+        cwd: target.hqRoot,
+    });
+    return Promise.resolve(manifestUploadResult(target.scope, result));
+}
+/**
+ * Map one `hq sync manifest` spawn result to a {@link RefreshManifestResult}.
+ * A spawn killed by the timeout has a null status, so it is reported as a
+ * timeout rather than as an exit code.
+ */
+export function manifestUploadResult(scope, result) {
+    const errorCode = result.error?.code;
+    if (errorCode === "ETIMEDOUT" || (result.status === null && result.signal)) {
+        const reason = `the upload timed out after ${REFRESH_SYNC_TIMEOUT_MS / 1000}s`;
+        return { ok: false, reason, message: `manifest upload for '${scope}' timed out` };
+    }
+    if (result.error) {
+        return {
+            ok: false,
+            reason: `the upload could not start${errorCode ? ` (${errorCode})` : ""}`,
+            message: `could not upload the manifest for '${scope}': ${result.error.message}`,
+        };
+    }
+    if (result.status !== 0) {
+        return {
+            ok: false,
+            reason: `the upload exited with code ${result.status}`,
+            message: `manifest upload for '${scope}' exited ${result.status}`,
+        };
+    }
+    return { ok: true, message: `uploaded the manifest for '${scope}'` };
+}
 // --- Dirty-tree probe ----------------------------------------------------------
 /**
  * The uncommitted changes under {@link HOOK_CONFIG_DIRS}, one porcelain line
@@ -422,7 +563,7 @@ 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, repairBotHqBinary = defaultRepairBotHqBinary) {
+function planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath = defaultRewriteBotNodePath, repairBotHqBinary = defaultRepairBotHqBinary, refreshManifest = defaultRefreshManifest) {
     switch (rem.fixClass) {
         case "bot-node-path":
             return planBotNodePath(result, rem, rewriteBotNodePath);
@@ -436,6 +577,8 @@ function planFix(hqRoot, result, rem, refreshSync, rewriteBotNodePath = defaultR
             return planRemoveStrayGateEntries(hqRoot, result, rem);
         case "refresh-sync":
             return planRefreshSync(hqRoot, result, rem, refreshSync);
+        case "refresh-manifest":
+            return planRefreshManifest(hqRoot, result, rem, refreshManifest);
         default:
             return null;
     }
@@ -555,6 +698,29 @@ function planRefreshSync(hqRoot, result, rem, refreshSync) {
         postStatus: (results) => results.find((entry) => entry.checkId === result.checkId)?.status ?? null,
     };
 }
+/** Re-upload one stale sync manifest scope. Writes nothing under the HQ tree. */
+function planRefreshManifest(hqRoot, result, rem, refreshManifest) {
+    const scope = rem.fixTarget;
+    if (!scope)
+        return null;
+    let failureReason;
+    return {
+        checkId: result.checkId,
+        fixClass: "refresh-manifest",
+        target: scope,
+        relpath: "",
+        preview: `  sync manifest (${scope === "personal" ? "personal vault" : `company ${scope}`})\n` +
+            `    ~ hq sync manifest --scope ${scope}\n` +
+            `      upload a fresh file manifest for the sync audit (no local files change)`,
+        summary: `upload a fresh sync manifest for ${scope}`,
+        apply: async () => {
+            const outcome = await refreshManifest({ scope, hqRoot });
+            failureReason = outcome.ok ? undefined : outcome.reason;
+        },
+        postStatus: (results) => results.find((entry) => entry.checkId === result.checkId)?.status ?? null,
+        failureReason: () => failureReason,
+    };
+}
 /** Restore the execute bit on a hook script. */
 function planExecutableBit(hqRoot, result, rem) {
     const abs = rem.fixTarget;

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

@@ -1,4 +1,4 @@
-import type { AppliedFix, AppliedFixBackup, ApplyFixesResult } from "./apply.js";
+import type { AppliedFix, AppliedFixBackup, ApplyFixesResult, UnresolvedSyncCheck } from "./apply.js";
 export interface DoctorFixJsonResult {
     schemaVersion: number;
     exitCode: number;
@@ -15,6 +15,8 @@ export interface DoctorFixJsonResult {
         outcome: NonNullable<AppliedFix["refreshSyncOutcome"]>;
         postStatus: AppliedFix["postStatus"];
     }[];
+    /** Sync checks still FAIL or WARN after the run, with the next step. */
+    unresolved: Pick<UnresolvedSyncCheck, "checkId" | "status" | "reason" | "nextStep">[];
 }
 /** Build the intentionally narrow JSON surface for `hq doctor --fix --json`. */
 export declare function buildDoctorFixJson(input: {
@@ -22,6 +24,7 @@ export declare function buildDoctorFixJson(input: {
     refused: ApplyFixesResult["refused"] | "outside-hq-tree";
     applied: readonly AppliedFix[];
     backups?: readonly AppliedFixBackup[];
+    unresolved?: readonly UnresolvedSyncCheck[];
 }): DoctorFixJsonResult;
 export declare function renderDoctorFixJson(input: Parameters<typeof buildDoctorFixJson>[0]): string;
 //# sourceMappingURL=json-output.d.ts.map