@indigoai-us/hq-cli 5.345.147 → 5.345.149

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";
@@ -27,6 +28,8 @@ 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";
 /**
@@ -240,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
@@ -273,6 +277,12 @@ export function createDefaultRegistry() {
     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

package/dist/lib/doctor/temp-home-sweeper.js

@@ -0,0 +1,418 @@
+/**
+ * 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 { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** Folders younger than this (by newest mtime anywhere inside) are kept. */
+export const TEMP_HOME_MIN_IDLE_MS = 90 * 60 * 1000;
+/** Names that mark a `tmp.*` temp home as holding a toolchain download. */
+export const TEMP_HOME_TOOLCHAIN_MARKERS = [".rustup", ".cargo"];
+/** Folders made by `HOME=$(mktemp -d)`; swept only with a toolchain marker. */
+export const TEMP_HOME_MKTEMP_PREFIX = "tmp.";
+/** Folders made by `core/scripts/with-temp-home.sh`. */
+export const TEMP_HOME_WRAPPER_PREFIX = "hq-temp-home.";
+/** Lock file the wrapper writes into its temp home; holds the wrapper pid. */
+export const TEMP_HOME_LOCK_FILE = ".hq-temp-home.lock";
+const BYTES_PER_GB = 1_000_000_000;
+const nodeFs = {
+    lstatSync: (target) => fs.lstatSync(target),
+    readdirSync: (target) => fs.readdirSync(target),
+    realpathSync: (target) => fs.realpathSync(target),
+    readFileSync: (target, encoding) => fs.readFileSync(target, encoding),
+    rmSync: (target, options) => fs.rmSync(target, options),
+};
+/**
+ * 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 function defaultTempRoots(env = process.env, fsImpl = nodeFs) {
+    const roots = [];
+    if (env.TMPDIR)
+        roots.push(env.TMPDIR);
+    roots.push(os.tmpdir(), "/tmp", "/private/tmp");
+    for (const a of safeReaddir(fsImpl, "/var/folders")) {
+        for (const b of safeReaddir(fsImpl, path.join("/var/folders", a))) {
+            roots.push(path.join("/var/folders", a, b, "T"));
+        }
+    }
+    return roots;
+}
+function safeReaddir(fsImpl, target) {
+    try {
+        return fsImpl.readdirSync(target);
+    }
+    catch {
+        return [];
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** `process.kill(pid, 0)`: alive unless the pid does not exist (ESRCH). */
+export function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * 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 function pathUsesHome(value, home) {
+    const name = path.basename(home);
+    if (value === name)
+        return true;
+    const marker = `/${name}`;
+    let index = value.indexOf(marker);
+    while (index !== -1) {
+        const next = value[index + marker.length];
+        if (next === undefined || next === "/")
+            return true;
+        index = value.indexOf(marker, index + 1);
+    }
+    return false;
+}
+function runProbe(command, args) {
+    const result = spawnSync(command, args, { encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0 && !result.stdout) {
+        throw new Error(`${command} exited ${result.status ?? result.signal}`);
+    }
+    return result.stdout;
+}
+/**
+ * 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 function defaultInUseProbe(uid) {
+    return (homes) => {
+        const used = new Set();
+        if (homes.length === 0)
+            return used;
+        const values = [];
+        if (process.platform === "linux") {
+            for (const pid of fs.readdirSync("/proc").filter((name) => /^\d+$/.test(name))) {
+                try {
+                    if (uid !== undefined && fs.statSync(`/proc/${pid}`).uid !== uid)
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                try {
+                    values.push(fs.readlinkSync(`/proc/${pid}/cwd`));
+                }
+                catch {
+                    // The process exited or the link is unreadable.
+                }
+                try {
+                    for (const fd of fs.readdirSync(`/proc/${pid}/fd`)) {
+                        try {
+                            values.push(fs.readlinkSync(`/proc/${pid}/fd/${fd}`));
+                        }
+                        catch {
+                            // The descriptor closed.
+                        }
+                    }
+                }
+                catch {
+                    // Same.
+                }
+                try {
+                    for (const entry of fs.readFileSync(`/proc/${pid}/environ`, "utf8").split("\0")) {
+                        if (entry.startsWith("HOME="))
+                            values.push(entry.slice(5));
+                    }
+                }
+                catch {
+                    // Same.
+                }
+            }
+        }
+        else {
+            const userArgs = uid !== undefined ? ["-u", String(uid)] : [];
+            // -w: no warnings; -n and -P: no host or port name lookups.
+            const lsof = runProbe("lsof", ["-w", "-n", "-P", "-Fn", ...userArgs]);
+            for (const line of lsof.split("\n")) {
+                if (line.startsWith("n"))
+                    values.push(line.slice(1));
+            }
+        }
+        for (const home of homes) {
+            if (values.some((value) => pathUsesHome(value, home)))
+                used.add(home);
+        }
+        return used;
+    };
+}
+/** On-disk size of one lstat result: allocated blocks when known, else size. */
+function diskBytes(stat) {
+    return typeof stat.blocks === "number" && stat.blocks >= 0 ? stat.blocks * 512 : stat.size;
+}
+/**
+ * Measure a folder with `lstat`, never descending into symlinks. Stops as soon
+ * as it sees an entry modified after `cutoffMs`, since such a folder is kept
+ * and its size is not needed. With `maxDepth` 1 it reads only direct children.
+ */
+function walk(fsImpl, dir, dirStat, cutoffMs, maxDepth = Number.POSITIVE_INFINITY) {
+    if (dirStat.mtimeMs > cutoffMs)
+        return { complete: true, recent: true, bytes: 0 };
+    let bytes = diskBytes(dirStat);
+    const stack = [{ dir, depth: 0 }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let names;
+        try {
+            names = fsImpl.readdirSync(current.dir);
+        }
+        catch {
+            return { complete: false, recent: false, bytes };
+        }
+        for (const name of names) {
+            const child = path.join(current.dir, name);
+            let stat;
+            try {
+                stat = fsImpl.lstatSync(child);
+            }
+            catch {
+                return { complete: false, recent: false, bytes };
+            }
+            if (stat.mtimeMs > cutoffMs)
+                return { complete: true, recent: true, bytes };
+            bytes += diskBytes(stat);
+            if (stat.isDirectory() && !stat.isSymbolicLink() && current.depth + 1 < maxDepth) {
+                stack.push({ dir: child, depth: current.depth + 1 });
+            }
+        }
+    }
+    return { complete: true, recent: false, bytes };
+}
+function hasToolchainMarker(fsImpl, dir) {
+    return TEMP_HOME_TOOLCHAIN_MARKERS.some((marker) => {
+        try {
+            const stat = fsImpl.lstatSync(path.join(dir, marker));
+            return stat.isDirectory() && !stat.isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** True when the wrapper's lock file in `dir` names a live pid. */
+function lockHeldByLiveProcess(fsImpl, dir, isPidAlive) {
+    let text;
+    try {
+        const lock = path.join(dir, TEMP_HOME_LOCK_FILE);
+        if (!fsImpl.lstatSync(lock).isFile())
+            return false;
+        text = fsImpl.readFileSync(lock, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const pid = Number.parseInt(text.trim(), 10);
+    return Number.isInteger(pid) && pid > 0 && isPidAlive(pid);
+}
+function resolveRoots(fsImpl, roots) {
+    const seen = new Set();
+    const resolved = [];
+    for (const root of roots) {
+        let real;
+        try {
+            real = fsImpl.realpathSync(root);
+            if (!fsImpl.lstatSync(real).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        resolved.push(real);
+    }
+    return resolved;
+}
+/**
+ * Find and (unless `dryRun`) remove idle, unused temp homes. See the module
+ * comment for the exact rules.
+ */
+export function sweepTempHomes(options = {}) {
+    const fsImpl = options.fs ?? nodeFs;
+    const shallow = options.shallow === true;
+    const dryRun = shallow || options.dryRun === true;
+    const nowMs = options.nowMs ?? Date.now();
+    const cutoffMs = nowMs - (options.minIdleMs ?? TEMP_HOME_MIN_IDLE_MS);
+    const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined);
+    const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
+    const roots = resolveRoots(fsImpl, options.roots ?? defaultTempRoots());
+    // Pass 1: decide per folder from the file system alone.
+    const entries = [];
+    const candidates = [];
+    for (const root of roots) {
+        const names = safeReaddir(fsImpl, root)
+            .filter((name) => name.startsWith(TEMP_HOME_MKTEMP_PREFIX) || name.startsWith(TEMP_HOME_WRAPPER_PREFIX))
+            .sort();
+        for (const name of names) {
+            const candidate = path.join(root, name);
+            let stat;
+            try {
+                stat = fsImpl.lstatSync(candidate);
+            }
+            catch (error) {
+                entries.push({ path: candidate, action: "kept", reason: "unreadable", error: errorMessage(error) });
+                continue;
+            }
+            if (stat.isSymbolicLink()) {
+                entries.push({ path: candidate, action: "kept", reason: "symlink" });
+                continue;
+            }
+            if (!stat.isDirectory()) {
+                entries.push({ path: candidate, action: "kept", reason: "not-directory" });
+                continue;
+            }
+            if (uid !== undefined && stat.uid !== uid) {
+                entries.push({ path: candidate, action: "kept", reason: "not-owned" });
+                continue;
+            }
+            if (name.startsWith(TEMP_HOME_MKTEMP_PREFIX) && !hasToolchainMarker(fsImpl, candidate)) {
+                entries.push({ path: candidate, action: "kept", reason: "no-toolchain-marker" });
+                continue;
+            }
+            const measured = walk(fsImpl, candidate, stat, cutoffMs, shallow ? 1 : undefined);
+            if (measured.recent) {
+                entries.push({ path: candidate, action: "kept", reason: "recent" });
+                continue;
+            }
+            if (!measured.complete) {
+                entries.push({ path: candidate, action: "kept", reason: "unreadable" });
+                continue;
+            }
+            if (lockHeldByLiveProcess(fsImpl, candidate, isPidAlive)) {
+                entries.push({ path: candidate, action: "kept", reason: "in-use" });
+                continue;
+            }
+            candidates.push({ path: candidate, stat, bytes: shallow ? undefined : measured.bytes });
+        }
+    }
+    // Pass 2: one process probe for every remaining candidate. Shallow mode
+    // only reports, so it skips the probe; the full sweep runs it.
+    let inUse = new Set();
+    if (!shallow && candidates.length > 0) {
+        const probe = options.inUse ?? defaultInUseProbe(uid);
+        try {
+            inUse = probe(candidates.map((candidate) => candidate.path));
+        }
+        catch (error) {
+            const message = errorMessage(error);
+            for (const candidate of candidates) {
+                entries.push({ path: candidate.path, action: "kept", reason: "in-use-unknown", error: message });
+            }
+            return finish(entries, roots, dryRun, shallow);
+        }
+    }
+    // Pass 3: remove, or report what would be removed.
+    for (const candidate of candidates) {
+        if (inUse.has(candidate.path)) {
+            entries.push({ path: candidate.path, action: "kept", reason: "in-use" });
+            continue;
+        }
+        if (dryRun) {
+            entries.push(withBytes({ path: candidate.path, action: "would-remove" }, candidate.bytes));
+            continue;
+        }
+        // Re-check right before deleting: the path must still be the same real
+        // directory, untouched since it was measured, and not newly locked.
+        let again;
+        try {
+            again = fsImpl.lstatSync(candidate.path);
+        }
+        catch (error) {
+            entries.push({ path: candidate.path, action: "kept", reason: "changed-before-delete", error: errorMessage(error) });
+            continue;
+        }
+        if (again.isSymbolicLink() ||
+            !again.isDirectory() ||
+            again.ino !== candidate.stat.ino ||
+            again.dev !== candidate.stat.dev ||
+            again.mtimeMs > cutoffMs ||
+            lockHeldByLiveProcess(fsImpl, candidate.path, isPidAlive)) {
+            entries.push({ path: candidate.path, action: "kept", reason: "changed-before-delete" });
+            continue;
+        }
+        try {
+            fsImpl.rmSync(candidate.path, { recursive: true, force: false });
+            entries.push(withBytes({ path: candidate.path, action: "removed" }, candidate.bytes));
+        }
+        catch (error) {
+            entries.push(withBytes({ path: candidate.path, action: "failed", error: errorMessage(error) }, candidate.bytes));
+        }
+    }
+    return finish(entries, roots, dryRun, shallow);
+}
+function withBytes(entry, bytes) {
+    return bytes === undefined ? entry : { ...entry, bytes };
+}
+function finish(entries, roots, dryRun, shallow) {
+    const bytesFreed = entries
+        .filter((entry) => entry.action === "removed" || entry.action === "would-remove")
+        .reduce((sum, entry) => sum + (entry.bytes ?? 0), 0);
+    return { dryRun, shallow, roots, entries, bytesFreed, gbFreed: toGb(bytesFreed) };
+}
+/** Bytes to GB (10^9 bytes), rounded to two decimals. */
+export function toGb(bytes) {
+    return Math.round((bytes / BYTES_PER_GB) * 100) / 100;
+}
+//# sourceMappingURL=temp-home-sweeper.js.map