@indigoai-us/hq-cli 5.345.146 → 5.345.148

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

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

@@ -25,6 +25,12 @@ export function buildDoctorFixJson(input) {
                 },
             ]
             : []),
+        unresolved: (input.unresolved ?? []).map(({ checkId, status, reason, nextStep }) => ({
+            checkId,
+            status,
+            reason,
+            nextStep,
+        })),
     };
 }
 export function renderDoctorFixJson(input) {

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

@@ -29,6 +29,12 @@
  *                         keep`, no hook-file rewrite. Leftover shards
  *                         without a local tree stay unfixed (the check reports
  *                         NA).
+ *   - `refresh-manifest` — re-run `hq sync manifest --scope <slug|personal>`
+ *                         for a manifest scope whose last upload is past the
+ *                         stale threshold. Upload-only metadata (file paths
+ *                         and hashes); it never writes the HQ tree. A company
+ *                         scope whose slug did not resolve locally stays
+ *                         manual-only.
  *
  * EVERYTHING else — content drift between platform copies, a missing script, a
  * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
@@ -40,7 +46,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" | "bot-hq-binary";
+export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync" | "refresh-manifest" | "bot-node-path" | "bot-hq-binary";
 /**
  * A finding's structured remediation. `autoFixable`, `action`, and `command`
  * are the `--json` surface (AC1); `fixTarget`/`fixClass` are the internal handle

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

@@ -29,6 +29,12 @@
  *                         keep`, no hook-file rewrite. Leftover shards
  *                         without a local tree stay unfixed (the check reports
  *                         NA).
+ *   - `refresh-manifest` — re-run `hq sync manifest --scope <slug|personal>`
+ *                         for a manifest scope whose last upload is past the
+ *                         stale threshold. Upload-only metadata (file paths
+ *                         and hashes); it never writes the HQ tree. A company
+ *                         scope whose slug did not resolve locally stays
+ *                         manual-only.
  *
  * EVERYTHING else — content drift between platform copies, a missing script, a
  * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
@@ -38,7 +44,7 @@
  * content-drift finding is manual-only, because that boundary is load-bearing:
  * deciding which of two diverged copies is correct needs human judgement.
  */
-import { isCompanyJournalSlug, isPersonalJournalSlug, journalSlugFromCheckId, } from "../checks/sync-health.js";
+import { isCompanyJournalSlug, isSafeCompanySlug, isPersonalJournalSlug, 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+(.+)$/;
 /**
@@ -171,6 +177,22 @@ export function deriveRemediation(result) {
             command: `hq sync pull --company ${journalSlug} --on-conflict keep`,
         };
     }
+    // refresh-manifest — a stale manifest upload. The check sets `target` to the
+    // `--scope` value only when it resolved one it can name safely.
+    if (checkId.startsWith("sync.manifest.") &&
+        result.status === "WARN" &&
+        result.reasonCode === "stale-threshold" &&
+        target &&
+        (target === "personal" || isSafeCompanySlug(target))) {
+        const scopeLabel = target === "personal" ? "the personal vault" : `company '${target}'`;
+        return {
+            autoFixable: true,
+            fixClass: "refresh-manifest",
+            fixTarget: target,
+            action: `Upload a fresh sync manifest for ${scopeLabel}.`,
+            command: `hq sync manifest --scope ${target}`,
+        };
+    }
     // Manual-only: content drift, missing scripts/counterparts, unquoted
     // expansions, stale allowed-divergence entries, invalid settings, etc. `--fix`
     // never touches these.

package/dist/lib/doctor/registry.js

@@ -14,6 +14,7 @@
  * later stories add per-item results to this family without touching the engine.
  */
 import * as fs from "node:fs";
+import { hookEngineFamily } from './checks/hook-engine.js';
 import * as path from "node:path";
 import { checkCodexWiring } from "./checks/codex-wiring.js";
 import { checkGrokWiring } from "./checks/grok-wiring.js";
@@ -26,6 +27,9 @@ import { botsFamily } from "./checks/bots.js";
 import { anywhereFamily } from "./checks/anywhere.js";
 import { scaffoldCliFloorFamily } from "./checks/scaffold-cli-floor.js";
 import { strandedLanesFamily } from "./checks/stranded-lanes.js";
+import { releaseLinksFamily } from "./checks/release-links.js";
+import { cliPathFamily } from "./checks/cli-path.js";
+import { tempHomesFamily } from "./checks/temp-homes.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -239,6 +243,7 @@ function hasCommandHook(settings, event) {
 export function createDefaultRegistry() {
     const registry = new DoctorRegistry();
     registry.register(hooksFamily);
+    registry.register(hookEngineFamily);
     registry.register(scaffoldCliFloorFamily);
     // Fixture coverage (US-007): reports UNTESTED for every registered hook with
     // no fixture and prints the tested/total coverage line. A separate family so
@@ -270,6 +275,14 @@ export function createDefaultRegistry() {
     // Failed keep-alive lead lanes cannot recover themselves; make them visible
     // in the standard local doctor report with the senior recovery command.
     registry.register(strandedLanesFamily);
+    // Release symlinks left pointing at a deleted update staging folder.
+    registry.register(releaseLinksFamily);
+    // Windows: the npm hq.cmd shim folder must be on PATH for a new terminal to
+    // find hq. Registry read only; prints the fix, never edits PATH.
+    registry.register(cliPathFamily);
+    // Idle tmp.* throwaway homes holding a Rust toolchain download. Dry-run
+    // scan only; `hq doctor --sweep-temp-homes` is the delete path.
+    registry.register(tempHomesFamily);
     return registry;
 }
 //# sourceMappingURL=registry.js.map

package/dist/lib/doctor/temp-home-sweeper.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Sweeper for abandoned throwaway `$HOME` folders.
+ *
+ * Commands run as `HOME=$(mktemp -d) <cmd>` leave a `tmp.XXXXXXXX` folder in
+ * the temp dir. When the command touched Rust or pnpm tooling, that folder
+ * holds a full `.rustup` / `.cargo` download (1-2 GB) and nothing deletes it.
+ * On 2026-10-18 about 45 GB refilled within hours of a cleanup this way.
+ * `core/scripts/with-temp-home.sh` makes `hq-temp-home.XXXXXXXX` folders and
+ * removes them on exit, but a wrapper killed with SIGKILL leaves its folder.
+ *
+ * The sweep is deliberately narrow. A folder is removed only when ALL hold:
+ *
+ * - it is a direct child of a temp root (TMPDIR, os.tmpdir(), /tmp,
+ *   /private/tmp, /var/folders/{a}/{b}/T) and its name starts with `tmp.` or
+ *   `hq-temp-home.`;
+ * - `lstat` says it is a real directory (never a symlink) owned by this user;
+ * - a `tmp.*` folder holds a `.rustup` or `.cargo` directory (again by
+ *   `lstat`). An `hq-temp-home.*` folder needs no marker: the name shows the
+ *   wrapper made it;
+ * - nothing inside it, the folder itself included, was modified in the last
+ *   90 minutes;
+ * - no live process uses it: the wrapper's `.hq-temp-home.lock` does not name
+ *   a live pid, and no process of this user has its cwd or an open file
+ *   there (on Linux, or its `HOME` there either).
+ *
+ * The walk uses `lstat` throughout and never descends into a symlink, so a
+ * link inside a temp home that points elsewhere is neither measured nor
+ * followed. `fs.rmSync` unlinks symlinks rather than following them. A folder
+ * that cannot be fully read is kept, because an incomplete scan cannot prove
+ * the folder is idle. When the in-use probe fails, every candidate is kept.
+ *
+ * `shallow` mode is for plain `hq doctor`, which must stay fast. It checks
+ * only the folder and its direct children for recent changes, skips the size
+ * walk and the process probe, and reports no byte counts.
+ */
+import * as fs from "node:fs";
+/** Folders younger than this (by newest mtime anywhere inside) are kept. */
+export declare const TEMP_HOME_MIN_IDLE_MS: number;
+/** Names that mark a `tmp.*` temp home as holding a toolchain download. */
+export declare const TEMP_HOME_TOOLCHAIN_MARKERS: readonly [".rustup", ".cargo"];
+/** Folders made by `HOME=$(mktemp -d)`; swept only with a toolchain marker. */
+export declare const TEMP_HOME_MKTEMP_PREFIX = "tmp.";
+/** Folders made by `core/scripts/with-temp-home.sh`. */
+export declare const TEMP_HOME_WRAPPER_PREFIX = "hq-temp-home.";
+/** Lock file the wrapper writes into its temp home; holds the wrapper pid. */
+export declare const TEMP_HOME_LOCK_FILE = ".hq-temp-home.lock";
+export type TempHomeAction = "removed" | "would-remove" | "kept" | "failed";
+export type TempHomeKeptReason = "symlink" | "not-directory" | "not-owned" | "no-toolchain-marker" | "recent" | "in-use" | "in-use-unknown" | "unreadable" | "changed-before-delete";
+export interface TempHomeEntry {
+    path: string;
+    action: TempHomeAction;
+    /** On-disk bytes. Present when the folder was fully measured. */
+    bytes?: number;
+    /** Why the folder was kept. Present only for `kept`. */
+    reason?: TempHomeKeptReason;
+    /** Error message. Present for `failed`, and for some `kept` entries. */
+    error?: string;
+}
+export interface TempHomeSweepResult {
+    dryRun: boolean;
+    /** True when the sweep ran in shallow mode (no sizes, no process probe). */
+    shallow: boolean;
+    /** Real paths of the temp roots that were scanned, deduplicated. */
+    roots: string[];
+    /** Every matching child that was examined, in scan order. */
+    entries: TempHomeEntry[];
+    /** Bytes removed, or bytes that would be removed in a dry run. 0 when shallow. */
+    bytesFreed: number;
+    /** `bytesFreed` in GB (10^9 bytes), rounded to two decimals. */
+    gbFreed: number;
+}
+/** File system calls the sweeper uses; a seam for tests. */
+export interface TempHomeSweepFs {
+    lstatSync(target: string): fs.Stats;
+    readdirSync(target: string): string[];
+    realpathSync(target: string): string;
+    readFileSync(target: string, encoding: "utf8"): string;
+    rmSync(target: string, options: {
+        recursive: true;
+        force: false;
+    }): void;
+}
+/**
+ * Returns the subset of `homes` that a live process uses: its cwd or an open
+ * file is inside the home (and on Linux, its `HOME` is the home). Throws when
+ * it cannot tell; the sweep then keeps every candidate.
+ */
+export type TempHomeInUseProbe = (homes: readonly string[]) => Set<string>;
+export interface TempHomeSweepOptions {
+    /** Temp roots to scan. Defaults to {@link defaultTempRoots}. */
+    roots?: readonly string[];
+    /** Report what would be removed without deleting anything. */
+    dryRun?: boolean;
+    /**
+     * Cheap scan for plain `hq doctor`: no size walk, no process probe, only
+     * the folder and its direct children checked for recent changes. Implies
+     * `dryRun`.
+     */
+    shallow?: boolean;
+    /** Current time in ms. Defaults to `Date.now()`. */
+    nowMs?: number;
+    /** Minimum idle time in ms. Defaults to {@link TEMP_HOME_MIN_IDLE_MS}. */
+    minIdleMs?: number;
+    /** Owner uid to require. Defaults to `process.getuid()` when it exists. */
+    uid?: number;
+    fs?: TempHomeSweepFs;
+    /** Live-process probe. Defaults to {@link defaultInUseProbe}. */
+    inUse?: TempHomeInUseProbe;
+    /** Whether a pid is alive. Defaults to `process.kill(pid, 0)`. */
+    isPidAlive?: (pid: number) => boolean;
+}
+/**
+ * The temp roots a throwaway home can land in: `$TMPDIR`, `os.tmpdir()`,
+ * `/tmp`, `/private/tmp`, and every per-user macOS temp dir
+ * `/var/folders/{a}/{b}/T`. Missing roots are dropped later by the sweep.
+ */
+export declare function defaultTempRoots(env?: NodeJS.ProcessEnv, fsImpl?: Pick<TempHomeSweepFs, "readdirSync">): string[];
+/** `process.kill(pid, 0)`: alive unless the pid does not exist (ESRCH). */
+export declare function defaultIsPidAlive(pid: number): boolean;
+/**
+ * True when `value` (a cwd or open-file path, or `HOME`) is `home` or a path
+ * inside it. Matched by folder name as a path segment, because the same temp
+ * dir is reachable as `/var/folders/...` and `/private/var/folders/...`; the
+ * random `mktemp` suffix makes the name unique. Over-matching only keeps more.
+ */
+export declare function pathUsesHome(value: string, home: string): boolean;
+/**
+ * Default in-use probe. Only processes of `uid` are checked; other users
+ * cannot own these folders' contents in a way the sweep would delete.
+ *
+ * - Linux: `/proc/{pid}/cwd`, every `/proc/{pid}/fd/*` link, and `HOME` from
+ *   `/proc/{pid}/environ`. Environment values are matched in memory and never
+ *   logged.
+ * - macOS: `lsof -u uid` for every file each process has open, its cwd and
+ *   its executable included. macOS does not show other processes'
+ *   environments (`ps -E` leaves them out), so `HOME` itself is not checked
+ *   there. A process that has HOME set to a temp home but holds nothing open
+ *   inside it is not seen; the wrapper lock and the 90-minute idle check
+ *   cover that case.
+ */
+export declare function defaultInUseProbe(uid: number | undefined): TempHomeInUseProbe;
+/**
+ * Find and (unless `dryRun`) remove idle, unused temp homes. See the module
+ * comment for the exact rules.
+ */
+export declare function sweepTempHomes(options?: TempHomeSweepOptions): TempHomeSweepResult;
+/** Bytes to GB (10^9 bytes), rounded to two decimals. */
+export declare function toGb(bytes: number): number;
+//# sourceMappingURL=temp-home-sweeper.d.ts.map