@indigoai-us/hq-cli 5.115.5 → 5.115.6

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## [Unreleased]
 
+## [5.115.6] — 2026-09-16
+
+### Fixed
+
+- `hq doctor --fix` can now refresh a company sync journal that is stale or
+  has never synced, when that company still has a folder under `companies/`.
+  It pulls that company only, keeps your local copy if there is a conflict,
+  and does not push. Company journals left over from memberships you do not
+  keep locally are reported as unused rather than broken, so a session-start
+  health check no longer files "could not repair" reports for folders that
+  were never on this machine. Personal journals are unchanged: they still
+  warn when stale, and `--fix` will not pull your personal vault on its own.
+  The repair pass also skips the integrations inventory, which it cannot
+  repair, so a slow connection check cannot stall the fix.
+
+- HQ's housekeeping pass now clears out add-on shortcuts that lead nowhere,
+  instead of warning about them forever. A pack that stops shipping one of its
+  files, or a pack whose folder was installed from a scratch directory someone
+  later deleted, used to leave shortcuts behind that nothing would ever remove.
+  HQ now clears a shortcut only when it sits in a folder the add-on system
+  manages, only when it points into the add-on folder, and only when the thing
+  it points at is definitely not there. A shortcut it cannot check, one leading
+  somewhere else, or a real folder with real files in it are all left alone. On
+  one real setup this cleared eight dead shortcuts that had been warning on
+  every run.
+
+- Add-on packs now repair their own shortcuts after your HQ folder moves to a
+  new machine. Those shortcuts point at a full path, so on a new computer they
+  all point somewhere that does not exist, and HQ used to leave them alone on
+  the grounds that something was already there. That made the breakage
+  permanent: every later tidy-up skipped them for the same reason. HQ now
+  repoints a shortcut that leads nowhere, while still refusing to touch one
+  that leads to real content. Repairing a tree this way fixed a batch of
+  long-broken pack shortcuts in one pass.
+
 ## [5.115.5] — 2026-09-15
 
 ### Fixed

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

@@ -91,7 +91,26 @@ export interface SyncHealthDeps {
      * scope that is fine.
      */
     unresolvedScopes?: (journals: readonly SyncJournalSummary[]) => readonly string[];
+    /**
+     * Whether a company slug has a local `companies/<slug>` directory in the HQ
+     * tree. Leftover journal shards for companies this machine does not keep
+     * locally are NA, not WARN — a journal without a tree is not a corroborated
+     * unhealthy-sync signal, and `hq doctor --fix` has nothing local to refresh.
+     */
+    localCompanyExists?: (slug: string) => boolean;
 }
+/**
+ * True when `slug` is a filesystem-safe company folder name. Rejects empty
+ * values, path separators, and `..` so a journal slug cannot be used to probe
+ * outside `companies/`.
+ */
+export declare function isSafeCompanySlug(slug: string): boolean;
+/** True when `hqRoot/companies/<slug>` exists as a directory. Never throws. */
+export declare function defaultLocalCompanyExists(hqRoot: string, slug: string): boolean;
+/** True when this journal slug names a company rather than the personal tree. */
+export declare function isCompanyJournalSlug(slug: string): boolean;
+/** Company slug from a `sync.journal.<slug>` check id, or null if not one. */
+export declare function journalSlugFromCheckId(checkId: string): string | null;
 /** The versions/sync check family. Registered in `createDefaultRegistry`. */
 export declare const syncHealthFamily: CheckFamily;
 /** Run every versions/sync check. A thrown check degrades to UNKNOWN. */

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

@@ -47,14 +47,35 @@ export const STALE_JOURNAL_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
 /** The offline update cache written by the check-hq-update SessionStart hook. */
 export const UPDATE_CACHE_RELPATH = path.join("workspace", ".hq-update-check", "last-check.json");
 /** Fill in the optional dependencies so call sites never branch on undefined. */
-function withDefaults(deps) {
+function withDefaults(deps, hqRoot) {
     return {
         ...deps,
         manifestStatuses: deps.manifestStatuses ?? defaultManifestStatuses,
         manifestAvailable: deps.manifestAvailable ?? (() => loadManifestExports() !== null),
         unresolvedScopes: deps.unresolvedScopes ?? defaultUnresolvedScopes,
+        localCompanyExists: deps.localCompanyExists ??
+            ((slug) => defaultLocalCompanyExists(hqRoot, slug)),
     };
 }
+/**
+ * True when `slug` is a filesystem-safe company folder name. Rejects empty
+ * values, path separators, and `..` so a journal slug cannot be used to probe
+ * outside `companies/`.
+ */
+export function isSafeCompanySlug(slug) {
+    return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug);
+}
+/** True when `hqRoot/companies/<slug>` exists as a directory. Never throws. */
+export function defaultLocalCompanyExists(hqRoot, slug) {
+    if (!isSafeCompanySlug(slug))
+        return false;
+    try {
+        return fs.statSync(path.join(hqRoot, "companies", slug)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Company journal shards are unresolvable by the default collector: the
  * snapshot store keys company scopes by `companyUid`, which `listJournals()`
@@ -146,6 +167,15 @@ const NON_COMPANY_JOURNAL_SLUGS = new Set([
     PERSONAL_SCOPE_SLUG,
     PERSONAL_VAULT_SCOPE_SLUG,
 ]);
+/** True when this journal slug names a company rather than the personal tree. */
+export function isCompanyJournalSlug(slug) {
+    return !NON_COMPANY_JOURNAL_SLUGS.has(slug);
+}
+/** Company slug from a `sync.journal.<slug>` check id, or null if not one. */
+export function journalSlugFromCheckId(checkId) {
+    const match = /^sync\.journal\.(.+)$/.exec(checkId);
+    return match ? match[1] : null;
+}
 /** The versions/sync check family. Registered in `createDefaultRegistry`. */
 export const syncHealthFamily = {
     id: SYNC_FAMILY_ID,
@@ -154,7 +184,7 @@ export const syncHealthFamily = {
 };
 /** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
 export function checkSyncHealth(context, rawDeps = DEFAULT_DEPS) {
-    const deps = withDefaults(rawDeps);
+    const deps = withDefaults(rawDeps, context.hqRoot);
     try {
         return [
             ...versionResults(context, deps),
@@ -325,6 +355,29 @@ function journalResults(deps, journals) {
     return journals.map((entry) => {
         const lastSync = entry.journal?.lastSync;
         const checkId = `sync.journal.${entry.slug}`;
+        // A company journal without a local tree is leftover membership state,
+        // not a live sync target. WARN would make `hq doctor --fix` look like it
+        // failed to repair something it was never going to touch (US-015 health
+        // hook files remaining FAIL/WARN after the safe repair pass).
+        if (isCompanyJournalSlug(entry.slug)) {
+            let local;
+            try {
+                local = deps.localCompanyExists(entry.slug);
+            }
+            catch {
+                // Existence probe failed: fall through to the staleness check rather
+                // than hiding a possibly-live company behind NA.
+                local = true;
+            }
+            if (!local) {
+                return {
+                    status: "NA",
+                    checkId,
+                    target: entry.path,
+                    message: `Sync journal '${entry.slug}' is unused on this machine — there is no companies/${entry.slug} directory, so this journal is not a live sync target.`,
+                };
+            }
+        }
         if (typeof lastSync !== "string" || lastSync.length === 0) {
             return {
                 status: "WARN",

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.115.5",
+  "version": "5.115.6",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {