@indigoai-us/hq-cli 5.115.5 → 5.116.0

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

@@ -8,11 +8,13 @@
  *      `.claude/`, `.codex/`, or `.grok/`, `--fix` refuses and exits non-zero
  *      unless `--force`, so a repair can never be tangled up with unrelated
  *      in-flight edits to the security layer.
- *   2. Allowlist only. It repairs exactly three classes — restore an execute
- *      bit, add a hook id to the gate profiles it is missing from, re-register a
- *      script present on disk — and NEVER rewrites a hook body or deletes a file.
- *      Classification is owned by {@link deriveRemediation}; a content-drift
- *      finding is manual-only and simply never appears in the fixable set.
+ *   2. Allowlist only. It repairs the classified safe classes — restore an
+ *      execute bit, add a hook id to the gate profiles it is missing from,
+ *      re-register a script present on disk, or pull a company whose local
+ *      tree exists but whose journal is stale — and NEVER rewrites a hook body
+ *      or deletes a file. Classification is owned by {@link deriveRemediation};
+ *      a content-drift finding is manual-only and simply never appears in the
+ *      fixable set.
  *   3. Preview + confirmation. Every change is shown diff-style and requires
  *      confirmation, with `--yes` for non-interactive use.
  *   4. Backup first. Before any write, the affected files are copied under
@@ -26,7 +28,7 @@
  * (the command resolves it once), keeping this module decoupled from the CLI and
  * trivially testable against a fake tree.
  */
-import type { DoctorStatus } from "../types.js";
+import type { CheckResult, DoctorStatus } from "../types.js";
 import { type GateProfile } from "../hook-gate-profiles.js";
 import { type FixClass } from "./remediation.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
@@ -56,7 +58,35 @@ export interface ApplyFixesOptions {
      * [] when clean or not a git repo. Default shells out to `git status`.
      */
     dirtyCheck?: (hqRoot: string) => string[];
+    /**
+     * Check runner used to collect findings and to re-verify after applying.
+     * Default runs the real registry. Tests inject a fake list so refresh-sync
+     * does not depend on the machine's live journal store.
+     */
+    runChecks?: (hqRoot: string) => Promise<CheckResult[]>;
+    /**
+     * Targeted pull used by the `refresh-sync` class. Default shells out to
+     * `hq sync pull --company <slug> --on-conflict keep`. Tests inject a stub
+     * so `--fix` never hits the network.
+     */
+    refreshSync?: (target: RefreshSyncTarget) => Promise<RefreshSyncResult>;
 }
+/** One company the `refresh-sync` class will pull. */
+export interface RefreshSyncTarget {
+    /** Company slug from the `sync.journal.<slug>` check id. */
+    slug: string;
+    /** HQ root the pull writes into. */
+    hqRoot: string;
+}
+/** Outcome of one {@link ApplyFixesOptions.refreshSync} call. */
+export interface RefreshSyncResult {
+    /** Whether the pull exited 0. */
+    ok: boolean;
+    /** One-line summary for the post-fix report. */
+    message: string;
+}
+/** Per-company bound for the default `hq sync pull` repair. */
+export declare const REFRESH_SYNC_TIMEOUT_MS = 90000;
 /** One applied (or attempted) repair, with its post-fix re-check status. */
 export interface AppliedFix {
     /** The check id of the finding that was repaired. */
@@ -94,6 +124,13 @@ export interface ApplyFixesResult {
  * assert on it.
  */
 export declare function applyFixes(options: ApplyFixesOptions): Promise<ApplyFixesResult>;
+/**
+ * Default `refresh-sync` repair: a bounded, pull-only, keep-conflicts
+ * `hq sync pull --company <slug>` against the tree `--fix` is repairing.
+ * Never a push, never interactive. A timeout or non-zero exit is reported
+ * rather than thrown so later plans still run.
+ */
+export declare function defaultRefreshSync(target: RefreshSyncTarget): Promise<RefreshSyncResult>;
 /**
  * The uncommitted changes under {@link HOOK_CONFIG_DIRS}, one porcelain line
  * each. Returns [] when the tree is clean OR when `hqRoot` is not a git repo

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

@@ -8,11 +8,13 @@
  *      `.claude/`, `.codex/`, or `.grok/`, `--fix` refuses and exits non-zero
  *      unless `--force`, so a repair can never be tangled up with unrelated
  *      in-flight edits to the security layer.
- *   2. Allowlist only. It repairs exactly three classes — restore an execute
- *      bit, add a hook id to the gate profiles it is missing from, re-register a
- *      script present on disk — and NEVER rewrites a hook body or deletes a file.
- *      Classification is owned by {@link deriveRemediation}; a content-drift
- *      finding is manual-only and simply never appears in the fixable set.
+ *   2. Allowlist only. It repairs the classified safe classes — restore an
+ *      execute bit, add a hook id to the gate profiles it is missing from,
+ *      re-register a script present on disk, or pull a company whose local
+ *      tree exists but whose journal is stale — and NEVER rewrites a hook body
+ *      or deletes a file. Classification is owned by {@link deriveRemediation};
+ *      a content-drift finding is manual-only and simply never appears in the
+ *      fixable set.
  *   3. Preview + confirmation. Every change is shown diff-style and requires
  *      confirmation, with `--yes` for non-interactive use.
  *   4. Backup first. Before any write, the affected files are copied under
@@ -36,6 +38,8 @@ import { createBackup } from "./backup.js";
 import { deriveRemediation } from "./remediation.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export const HOOK_CONFIG_DIRS = [".claude", ".codex", ".grok"];
+/** Per-company bound for the default `hq sync pull` repair. */
+export const REFRESH_SYNC_TIMEOUT_MS = 90_000;
 /**
  * Apply every auto-fixable finding, honouring the dirty-tree refusal, the
  * preview/confirmation gate, the pre-write backup, and the post-fix re-check.
@@ -68,8 +72,10 @@ export async function applyFixes(options) {
             return empty({ exitCode: 1, refused: "dirty-tree" });
         }
     }
+    const collect = options.runChecks ?? defaultRunChecks;
+    const refreshSync = options.refreshSync ?? defaultRefreshSync;
     // 2. Collect findings and keep only the allowlisted auto-fixable ones.
-    const findings = await runChecks(hqRoot);
+    const findings = await collect(hqRoot);
     const fixable = [];
     for (const result of findings) {
         const rem = deriveRemediation(result);
@@ -81,7 +87,7 @@ export async function applyFixes(options) {
         return empty();
     }
     const plans = fixable
-        .map(({ result, rem }) => planFix(hqRoot, result, rem))
+        .map(({ result, rem }) => planFix(hqRoot, result, rem, refreshSync))
         .filter((plan) => plan !== null);
     if (plans.length === 0) {
         write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
@@ -99,16 +105,20 @@ export async function applyFixes(options) {
         }
     }
     // 4. Back up every file about to change BEFORE the first write (AC6).
-    const affected = unique(plans.map((plan) => plan.relpath));
-    const backup = createBackup(hqRoot, affected, options.now);
+    //    refresh-sync plans have no hook file; skip the backup pass when nothing
+    //    in the tree is about to be copied.
+    const affected = unique(plans.map((plan) => plan.relpath).filter((rel) => rel.length > 0));
+    const backup = affected.length > 0 ? createBackup(hqRoot, affected, options.now) : null;
     // 5. Apply. Each plan reads the current on-disk state, so multiple plans that
     //    touch the same file (two gate ids) compose correctly.
     for (const plan of plans)
-        plan.apply();
-    write(`\nBacked up ${backup.files.length} file${backup.files.length === 1 ? "" : "s"} to ${backup.dir}\n`);
-    write(`To restore: ${backup.restoreCommand}\n`);
+        await plan.apply();
+    if (backup) {
+        write(`\nBacked up ${backup.files.length} file${backup.files.length === 1 ? "" : "s"} to ${backup.dir}\n`);
+        write(`To restore: ${backup.restoreCommand}\n`);
+    }
     // 6. Re-run the checks and report the post-fix status of each repair (AC7).
-    const after = await runChecks(hqRoot);
+    const after = await collect(hqRoot);
     const applied = plans.map((plan) => ({
         checkId: plan.checkId,
         fixClass: plan.fixClass,
@@ -125,17 +135,83 @@ export async function applyFixes(options) {
         wrote: true,
         refused: null,
         fixableCount: fixable.length,
-        backupDir: backup.dir,
-        restoreCommand: backup.restoreCommand,
+        backupDir: backup?.dir ?? null,
+        restoreCommand: backup?.restoreCommand ?? null,
         applied,
     };
 }
 /** Run the default (read-only) check registry and flatten to a result list. */
-async function runChecks(hqRoot) {
-    const context = { hqRoot, platform: { id: "unknown" } };
+async function defaultRunChecks(hqRoot) {
+    // `--fix` never repairs the integrations family (networked inventory), so
+    // skip it: a hung control-plane read must not stall the safe repair pass.
+    const context = {
+        hqRoot,
+        platform: { id: "unknown" },
+        integrations: false,
+    };
     const families = await createDefaultRegistry().run(context);
     return flattenFamilies(families);
 }
+/**
+ * Default `refresh-sync` repair: a bounded, pull-only, keep-conflicts
+ * `hq sync pull --company <slug>` against the tree `--fix` is repairing.
+ * Never a push, never interactive. A timeout or non-zero exit is reported
+ * rather than thrown so later plans still run.
+ */
+export function defaultRefreshSync(target) {
+    const hqBin = process.argv[1];
+    const args = hqBin
+        ? [
+            hqBin,
+            "sync",
+            "pull",
+            "--company",
+            target.slug,
+            "--hq-root",
+            target.hqRoot,
+            "--on-conflict",
+            "keep",
+            "--lock-timeout",
+            "30",
+        ]
+        : [
+            "sync",
+            "pull",
+            "--company",
+            target.slug,
+            "--hq-root",
+            target.hqRoot,
+            "--on-conflict",
+            "keep",
+            "--lock-timeout",
+            "30",
+        ];
+    const result = spawnSync(hqBin ? process.execPath : "hq", args, {
+        encoding: "utf8",
+        timeout: REFRESH_SYNC_TIMEOUT_MS,
+        cwd: target.hqRoot,
+    });
+    if (result.error) {
+        const timedOut = result.error.message.includes("ETIMEDOUT") || result.signal === "SIGTERM";
+        return Promise.resolve({
+            ok: false,
+            message: timedOut
+                ? `timed out pulling '${target.slug}'`
+                : `could not start pull for '${target.slug}': ${result.error.message}`,
+        });
+    }
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.stdout || "").trim().split("\n").at(-1) ?? "";
+        return Promise.resolve({
+            ok: false,
+            message: `pull of '${target.slug}' exited ${result.status}${detail ? `: ${detail}` : ""}`,
+        });
+    }
+    return Promise.resolve({
+        ok: true,
+        message: `pulled '${target.slug}'`,
+    });
+}
 // --- Dirty-tree probe ----------------------------------------------------------
 /**
  * The uncommitted changes under {@link HOOK_CONFIG_DIRS}, one porcelain line
@@ -155,7 +231,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) {
+function planFix(hqRoot, result, rem, refreshSync) {
     switch (rem.fixClass) {
         case "executable-bit":
             return planExecutableBit(hqRoot, result, rem);
@@ -163,10 +239,32 @@ function planFix(hqRoot, result, rem) {
             return planGateProfile(hqRoot, result, rem);
         case "register-hook":
             return planRegisterHook(hqRoot, result, rem);
+        case "refresh-sync":
+            return planRefreshSync(hqRoot, result, rem, refreshSync);
         default:
             return null;
     }
 }
+/** Pull one company to refresh a stale or never-synced journal. */
+function planRefreshSync(hqRoot, result, rem, refreshSync) {
+    const slug = rem.fixTarget;
+    if (!slug)
+        return null;
+    return {
+        checkId: result.checkId,
+        fixClass: "refresh-sync",
+        target: slug,
+        relpath: "",
+        preview: `  companies/${slug}\n` +
+            `    ~ hq sync pull --company ${slug} --on-conflict keep\n` +
+            `      refresh the stale sync journal (keeps local conflict copies)`,
+        summary: `pull ${slug} to refresh its sync journal`,
+        apply: async () => {
+            await refreshSync({ slug, hqRoot });
+        },
+        postStatus: (results) => results.find((entry) => entry.checkId === result.checkId)?.status ?? null,
+    };
+}
 /** Restore the execute bit on a hook script. */
 function planExecutableBit(hqRoot, result, rem) {
     const abs = rem.fixTarget;

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

@@ -7,8 +7,8 @@
  * classes, and if so exactly which file or hook id to act on. This module is the
  * single classifier that turns a {@link CheckResult} into that structured shape.
  *
- * The three — and only three — auto-fixable classes are a deliberate, security
- * -reviewed allowlist (see the PRD decision record):
+ * The auto-fixable classes are a deliberate, security-reviewed allowlist
+ * (see the PRD decision record):
  *
  *   - `executable-bit`  — restore the execute bit on a hook script that exists
  *                         but lost `+x`. Detected by the shared `chmod +x …`
@@ -19,6 +19,11 @@
  *                         `…gate-profiles` FAIL from the Claude wiring tier.
  *   - `register-hook`   — re-register a script that is present on disk but wired
  *                         nowhere. Detected by the `…orphan` WARN.
+ *   - `refresh-sync`    — run a targeted pull for a company journal that is
+ *                         stale or never-synced AND has a local
+ *                         `companies/<slug>` tree. Pull-only, `--on-conflict
+ *                         keep`, no hook-file rewrite. Personal journals and
+ *                         leftover shards without a local tree stay manual.
  *
  * EVERYTHING else — content drift between platform copies, a missing script, a
  * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
@@ -30,7 +35,7 @@
  */
 import type { CheckResult } from "../types.js";
 /** The allowlisted safe repair classes `--fix` is permitted to apply. */
-export type FixClass = "executable-bit" | "gate-profile" | "register-hook";
+export type FixClass = "executable-bit" | "gate-profile" | "register-hook" | "refresh-sync";
 /**
  * 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

@@ -7,8 +7,8 @@
  * classes, and if so exactly which file or hook id to act on. This module is the
  * single classifier that turns a {@link CheckResult} into that structured shape.
  *
- * The three — and only three — auto-fixable classes are a deliberate, security
- * -reviewed allowlist (see the PRD decision record):
+ * The auto-fixable classes are a deliberate, security-reviewed allowlist
+ * (see the PRD decision record):
  *
  *   - `executable-bit`  — restore the execute bit on a hook script that exists
  *                         but lost `+x`. Detected by the shared `chmod +x …`
@@ -19,6 +19,11 @@
  *                         `…gate-profiles` FAIL from the Claude wiring tier.
  *   - `register-hook`   — re-register a script that is present on disk but wired
  *                         nowhere. Detected by the `…orphan` WARN.
+ *   - `refresh-sync`    — run a targeted pull for a company journal that is
+ *                         stale or never-synced AND has a local
+ *                         `companies/<slug>` tree. Pull-only, `--on-conflict
+ *                         keep`, no hook-file rewrite. Personal journals and
+ *                         leftover shards without a local tree stay manual.
  *
  * EVERYTHING else — content drift between platform copies, a missing script, a
  * missing Codex counterpart, an unquoted `$CLAUDE_PROJECT_DIR`, a stale
@@ -28,6 +33,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, 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+(.+)$/;
 /**
@@ -90,6 +96,19 @@ export function deriveRemediation(result) {
             command: remediation ?? `Register ${target} in .claude/settings.json.`,
         };
     }
+    // refresh-sync — a company journal that is stale or never-synced. Only
+    // company slugs: personal shards have no companies/<slug> tree and a
+    // SessionStart `--fix --yes` must not pull the personal vault unprompted.
+    const journalSlug = journalSlugFromCheckId(checkId);
+    if (journalSlug && isCompanyJournalSlug(journalSlug)) {
+        return {
+            autoFixable: true,
+            fixClass: "refresh-sync",
+            fixTarget: journalSlug,
+            action: `Pull company '${journalSlug}' to refresh its sync journal (keeps local conflict copies).`,
+            command: `hq sync pull --company ${journalSlug} --on-conflict keep`,
+        };
+    }
     // Manual-only: content drift, missing scripts/counterparts, unquoted
     // expansions, stale allowed-divergence entries, invalid settings, etc. `--fix`
     // never touches these.

package/dist/lib/scan-packages/index.js

@@ -3,6 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from 'js-yaml';
 import { contributionLinks } from '../../utils/pack-contributions.js';
+import { CONTRIBUTION_TABLE } from '../../utils/contribution-table.js';
 function isDirectory(target) { try {
     return fs.statSync(target).isDirectory();
 }
@@ -140,6 +141,23 @@ function workerIdClashes(hqRoot, source) {
     }
     return undefined;
 }
+/**
+ * What a symlink's target resolves to: `present`, `absent`, or the errno of a
+ * lookup that answered neither. Only ENOENT (nothing there) and ENOTDIR (a
+ * path component is not a directory, so the target cannot exist) mean absent.
+ * EACCES, ELOOP and friends mean the question went unanswered, which is not a
+ * licence to destroy what the link points at.
+ */
+function targetLookup(target) {
+    try {
+        fs.statSync(target);
+        return 'present';
+    }
+    catch (error) {
+        const code = error.code;
+        return code === 'ENOENT' || code === 'ENOTDIR' ? 'absent' : code ?? 'unknown error';
+    }
+}
 function ensureSymlink(link, info, warn) {
     if (!existsOrSymlink(link.src)) {
         warn(`payload missing: ${link.src} (declared but not shipped)`);
@@ -152,6 +170,26 @@ function ensureSymlink(link, info, warn) {
             const existing = fs.readlinkSync(link.dst);
             if (existing === link.src)
                 return;
+            // "Host content wins" protects content. A symlink that does not resolve
+            // is not content — and it is the shape every pack link takes when a tree
+            // moves between machines, because these links are absolute and the old
+            // HQ root does not exist on the new host. Skipping it would make that
+            // state permanent: stale on this run, and on every run after it.
+            //
+            // Only a lookup that specifically says "not there" earns a relink.
+            // fs.existsSync also answers false for EACCES, which would read content
+            // this user merely cannot traverse as absent and delete the link to it.
+            const lookup = targetLookup(link.dst);
+            if (lookup === 'absent') {
+                fs.rmSync(link.dst, { force: true });
+                fs.symlinkSync(link.src, link.dst);
+                info(`relinked ${link.dst} -> ${link.src} (was ${existing}, which does not exist here)`);
+                return;
+            }
+            if (lookup !== 'present') {
+                warn(`collision: ${link.dst} points at ${existing}, which could not be checked (${lookup}) — leaving it alone`);
+                return;
+            }
             warn(`collision: ${link.dst} already points at ${existing} (wanted ${link.src}) — skipping`);
             return;
         }
@@ -165,6 +203,102 @@ function ensureSymlink(link, info, warn) {
     fs.symlinkSync(link.src, link.dst);
     info(`linked ${link.dst} -> ${link.src}`);
 }
+/**
+ * The link text, when `entry` is a symlink whose target is definitively not
+ * there; `undefined` for anything else — a real file or directory, a link that
+ * resolves, or a lookup that failed for a reason other than absence.
+ */
+function danglingLinkTarget(entry) {
+    let link;
+    try {
+        if (!fs.lstatSync(entry).isSymbolicLink())
+            return undefined;
+        link = fs.readlinkSync(entry);
+    }
+    catch {
+        return undefined;
+    }
+    return targetLookup(entry) === 'absent' ? link : undefined;
+}
+/** Host directories the table routes symlinks into, HQ-root relative. */
+function symlinkHostRoots() {
+    const roots = new Set();
+    for (const row of Object.values(CONTRIBUTION_TABLE)) {
+        if (row.wire === 'symlink')
+            roots.add(row.host);
+    }
+    return [...roots].sort();
+}
+/**
+ * Remove host symlinks that point into `core/packages/` at a payload that is
+ * no longer there.
+ *
+ * Wiring only ever adds. A contribution a pack stops shipping, or a pack whose
+ * directory is itself a link into a deleted worktree, leaves its host links
+ * pointing at nothing, and nothing removed them — so they accumulated and
+ * warned on every run forever.
+ *
+ * Scoped three ways so this only reaps what the pack system wired:
+ *   - only inside the host roots the contribution table declares,
+ *   - only symlinks whose target resolves inside `core/packages/`,
+ *   - only when the lookup specifically says the target is absent. EACCES and
+ *     friends mean the question went unanswered, which is not a licence to
+ *     delete (same discipline as the relink path).
+ *
+ * A symlinked directory is classified, never descended into: a Dirent reports
+ * it as a symlink rather than a directory, so the walk cannot wander out of
+ * the host roots through one.
+ */
+function reapOrphanedLinks(hqRoot, info, warn) {
+    const packagesRoot = path.join(hqRoot, 'core/packages') + path.sep;
+    for (const hostRelative of symlinkHostRoots()) {
+        const stack = [path.join(hqRoot, hostRelative)];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            let entries;
+            try {
+                entries = fs.readdirSync(current, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+            for (const entry of entries) {
+                const absolute = path.join(current, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(absolute);
+                    continue;
+                }
+                if (!entry.isSymbolicLink())
+                    continue;
+                let target;
+                try {
+                    target = fs.readlinkSync(absolute);
+                }
+                catch {
+                    continue;
+                }
+                const resolved = path.resolve(path.dirname(absolute), target);
+                if (!resolved.startsWith(packagesRoot))
+                    continue;
+                const lookup = targetLookup(absolute);
+                if (lookup === 'present')
+                    continue;
+                if (lookup !== 'absent') {
+                    warn(`${absolute} points into core/packages at ${resolved}, which could not be checked (${lookup}) — leaving it alone`);
+                    continue;
+                }
+                try {
+                    fs.rmSync(absolute, { force: true });
+                    info(`unwired ${absolute} (its pack payload ${resolved} is gone)`);
+                }
+                catch (error) {
+                    warn(`could not unwire ${absolute} (${error.message})`);
+                }
+            }
+        }
+    }
+}
 /** Wire installed pack contributions into their table-declared host locations. */
 export function scanPackages(hqRoot, options = {}) {
     const log = options.log ?? ((message) => process.stdout.write(`${message}\n`));
@@ -174,6 +308,9 @@ export function scanPackages(hqRoot, options = {}) {
     const warn = (message) => warnSink(`  [warn] ${message}`);
     const packages = path.join(hqRoot, 'core/packages');
     if (!isDirectory(packages)) {
+        // Still sweep: a packages directory that is gone entirely is exactly when
+        // every link into it is an orphan.
+        reapOrphanedLinks(hqRoot, info, warn);
         info('[scan-packages] no core/packages/ dir; nothing to wire');
         return { status: 0 };
     }
@@ -190,7 +327,24 @@ export function scanPackages(hqRoot, options = {}) {
         for (const name of packageNames) {
             const packDir = path.join(packages, name);
             const manifest = path.join(packDir, 'package.yaml');
-            if (!isDirectory(packDir) || !fs.existsSync(manifest))
+            if (!isDirectory(packDir)) {
+                // A dangling entry in core/packages/ is not a pack and cannot become
+                // one — typically an install from a worktree that was later removed.
+                // Only a symlink to nothing qualifies: a real directory holds real
+                // files whatever its manifest situation, and is left alone.
+                const danglingTarget = danglingLinkTarget(packDir);
+                if (danglingTarget !== undefined) {
+                    try {
+                        fs.rmSync(packDir, { force: true });
+                        info(`[scan-packages] removed ${name}: its payload is gone (was a link to ${danglingTarget})`);
+                    }
+                    catch (error) {
+                        warn(`could not remove the dangling pack entry ${packDir} (${error.message})`);
+                    }
+                }
+                continue;
+            }
+            if (!fs.existsSync(manifest))
                 continue;
             any = true;
             info(`[scan-packages] wiring ${name}`);
@@ -211,6 +365,9 @@ export function scanPackages(hqRoot, options = {}) {
         warnSink(`[scan-packages] error: ${error.message}`);
         return { status: 1 };
     }
+    // After wiring, so anything just created or repointed is present and only
+    // genuine orphans are left to reap.
+    reapOrphanedLinks(hqRoot, info, warn);
     if (!any)
         info('[scan-packages] no hq-pack manifests found in core/packages');
     return { status: 0 };

package/dist/lib/service-manager/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Install / uninstall / status for a SET of user-level services, dispatching
+ * to launchd or systemd. All filesystem and process-control effects are
+ * injectable so the kit tests exercise the real rendering and dispatch
+ * without touching the host's service manager.
+ */
+import * as fs from "node:fs";
+import { type RunCommand } from "./launchd.js";
+import { type ServiceHostPaths, type ServicePlatform, type ServiceSpec } from "./types.js";
+export type { ServiceSpec, ServiceHostPaths, ServicePlatform } from "./types.js";
+export { detectServicePlatform } from "./types.js";
+export { renderLaunchdPlist } from "./launchd.js";
+export { renderSystemdUserUnit, systemdUnitName } from "./systemd.js";
+export declare const defaultRunCommand: RunCommand;
+export interface ServiceManagerDeps {
+    platform?: ServicePlatform;
+    run?: RunCommand;
+    writeFileSync?: typeof fs.writeFileSync;
+    mkdirSync?: typeof fs.mkdirSync;
+    unlinkSync?: typeof fs.unlinkSync;
+    existsSync?: typeof fs.existsSync;
+    /** When false, render + write units but do not (de)activate them. */
+    activate?: boolean;
+}
+export interface ServiceUnitResult {
+    name: string;
+    unitPath: string;
+    rendered?: string;
+    installed: boolean;
+    running?: boolean;
+    error?: string;
+}
+export interface ServiceSetResult {
+    platform: ServicePlatform;
+    units: ServiceUnitResult[];
+    /** Human hint when the platform has no service manager integration. */
+    manualCommands?: string[];
+}
+export declare function renderUnit(platform: ServicePlatform, spec: ServiceSpec, host: ServiceHostPaths): string;
+export declare function installServices(specs: ServiceSpec[], host: ServiceHostPaths, deps?: ServiceManagerDeps): ServiceSetResult;
+export declare function uninstallServices(specs: ServiceSpec[], host: ServiceHostPaths, deps?: ServiceManagerDeps): ServiceSetResult;
+export declare function servicesStatus(specs: ServiceSpec[], host: ServiceHostPaths, deps?: ServiceManagerDeps): ServiceSetResult;
+//# sourceMappingURL=index.d.ts.map