@indigoai-us/hq-cli 5.345.146 → 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/release-links.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Release-shipped links (hq-core mode 120000). An update that junctions a
+ * directory at the staging clone, then deletes that clone, leaves a link that
+ * does not resolve (feedback_3e1a7445). `hq doctor` reports those and the
+ * repair step. A link that resolves somewhere else inside the HQ root is a
+ * user customization and is left alone.
+ */
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+export declare const RELEASE_LINKS_FAMILY_ID = "release-links";
+export declare const RELEASE_LINKS_FAMILY_TITLE = "Release links";
+export declare const RELEASE_LINKS_CHECK_ID = "release-links.resolve";
+export declare const RELEASE_LINK_REMEDIATION = "Run `hq rescue -y` again. On Windows without Developer Mode, a directory link is written as a junction and a file link as a copy.";
+interface ReleaseLink {
+    rel: string;
+    linkText: string;
+    kind: "dir" | "file";
+}
+/** Paths git records as symlinks in the hq-core release. */
+export declare const RELEASE_LINKS: readonly ReleaseLink[];
+export declare const releaseLinksFamily: CheckFamily;
+export declare function checkReleaseLinks(context: CheckContext): CheckResult[];
+export {};
+//# sourceMappingURL=release-links.d.ts.map

package/dist/lib/doctor/checks/release-links.js

@@ -0,0 +1,152 @@
+/**
+ * Release-shipped links (hq-core mode 120000). An update that junctions a
+ * directory at the staging clone, then deletes that clone, leaves a link that
+ * does not resolve (feedback_3e1a7445). `hq doctor` reports those and the
+ * repair step. A link that resolves somewhere else inside the HQ root is a
+ * user customization and is left alone.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const RELEASE_LINKS_FAMILY_ID = "release-links";
+export const RELEASE_LINKS_FAMILY_TITLE = "Release links";
+export const RELEASE_LINKS_CHECK_ID = "release-links.resolve";
+export const RELEASE_LINK_REMEDIATION = "Run `hq rescue -y` again. On Windows without Developer Mode, a directory link is written as a junction and a file link as a copy.";
+const CYGWIN_SYMLINK_COOKIE = Buffer.from("!<symlink>", "latin1");
+/** Paths git records as symlinks in the hq-core release. */
+export const RELEASE_LINKS = [
+    { rel: ".agents/skills", linkText: "../.claude/skills", kind: "dir" },
+    { rel: ".codex/claude", linkText: "../.claude", kind: "dir" },
+    {
+        rel: ".codex/output-style.md",
+        linkText: "../.claude/output-styles/hq.md",
+        kind: "file",
+    },
+    { rel: "AGENTS.md", linkText: ".claude/CLAUDE.md", kind: "file" },
+    {
+        rel: "companies/_template/.obsidian",
+        linkText: "../../.obsidian",
+        kind: "dir",
+    },
+];
+export const releaseLinksFamily = {
+    id: RELEASE_LINKS_FAMILY_ID,
+    title: RELEASE_LINKS_FAMILY_TITLE,
+    run: (context) => Promise.resolve(checkReleaseLinks(context)),
+};
+export function checkReleaseLinks(context) {
+    const present = RELEASE_LINKS.filter((entry) => lstatOrNull(path.join(context.hqRoot, entry.rel)) !== null);
+    if (present.length === 0) {
+        return [
+            {
+                status: "NA",
+                checkId: RELEASE_LINKS_CHECK_ID,
+                target: context.hqRoot,
+                message: "Skipped: this HQ root has none of the release-shipped links.",
+            },
+        ];
+    }
+    const failures = [];
+    for (const entry of present) {
+        const problem = releaseLinkProblem(context.hqRoot, entry);
+        if (!problem)
+            continue;
+        failures.push({
+            status: "FAIL",
+            checkId: RELEASE_LINKS_CHECK_ID,
+            target: entry.rel,
+            message: `${entry.rel} ${problem}`,
+            remediation: RELEASE_LINK_REMEDIATION,
+        });
+    }
+    if (failures.length > 0)
+        return failures;
+    return [
+        {
+            status: "PASS",
+            checkId: RELEASE_LINKS_CHECK_ID,
+            target: context.hqRoot,
+            message: "Release links resolve inside this HQ root.",
+        },
+    ];
+}
+function releaseLinkProblem(hqRoot, entry) {
+    const destination = path.join(hqRoot, entry.rel);
+    const lst = lstatOrNull(destination);
+    if (!lst)
+        return null;
+    if (lst.isSymbolicLink()) {
+        let resolved;
+        try {
+            resolved = fs.realpathSync.native(destination);
+        }
+        catch {
+            return "does not resolve. Its target is missing, often because an update linked it at a staging folder that was then deleted.";
+        }
+        if (!pathIsInside(hqRoot, resolved)) {
+            return "points outside this HQ root, so it does not resolve to the shipped target.";
+        }
+        return null;
+    }
+    if (lst.isFile()) {
+        const bytes = readFileOrNull(destination);
+        if (bytes && isSymlinkStub(bytes, entry.linkText)) {
+            return "is still a Git symlink stub, not a working link.";
+        }
+        if (entry.kind === "dir") {
+            return "is a file, not a directory link.";
+        }
+        const expected = containedTarget(hqRoot, entry);
+        if (expected) {
+            const target = readFileOrNull(expected);
+            if (target && bytes && bytes.equals(target))
+                return null;
+        }
+        // A regular file that is not the stub is a user edit or a Windows copy
+        // of the target. Either way the path is usable.
+        return null;
+    }
+    // A real directory in place of a directory link is a user replacement.
+    return null;
+}
+function containedTarget(hqRoot, entry) {
+    const destination = path.join(hqRoot, entry.rel);
+    const resolved = path.resolve(path.dirname(destination), entry.linkText);
+    return pathIsInside(hqRoot, resolved) ? resolved : null;
+}
+function isSymlinkStub(bytes, linkText) {
+    if (bytes.equals(Buffer.from(linkText, "utf8")))
+        return true;
+    return (bytes.length >= CYGWIN_SYMLINK_COOKIE.length &&
+        bytes.subarray(0, CYGWIN_SYMLINK_COOKIE.length).equals(CYGWIN_SYMLINK_COOKIE));
+}
+function pathIsInside(parent, child) {
+    const parentAbs = path.resolve(parent);
+    const childAbs = path.resolve(child);
+    if (childAbs === parentAbs || childAbs.startsWith(parentAbs + path.sep))
+        return true;
+    try {
+        const parentReal = fs.realpathSync.native(parentAbs);
+        const childReal = fs.realpathSync.native(childAbs);
+        return childReal === parentReal || childReal.startsWith(parentReal + path.sep);
+    }
+    catch {
+        return false;
+    }
+}
+function lstatOrNull(target) {
+    try {
+        return fs.lstatSync(target);
+    }
+    catch {
+        return null;
+    }
+}
+function readFileOrNull(target) {
+    try {
+        return fs.readFileSync(target);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=release-links.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