@indigoai-us/hq-cli 5.115.4 → 5.115.6

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 ## [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
+
+- The setting that turns the end-of-turn checkpoint requirement off,
+  `HQ_CHECKPOINT_GATE`, now works from `.claude/settings.json` on every runtime.
+  Before, only Claude Code passed that setting through to the checkpoint hook,
+  so if you work in Codex or Grok, writing it in the settings file did nothing
+  and there was no sign of why. hq now reads the file itself. As with the other
+  checkpoint settings, `settings.local.json` overrides it, anything you set in
+  your terminal overrides both, and `false` or `0` written as plain JSON works
+  as well as `"0"`. If the value is something the setting does not understand,
+  hq names it and leaves the requirement on rather than guessing.
+
 ## [5.115.4] — 2026-09-15
 
 ### Changed

package/assets/scaffold/core/scripts/checkpoint-stop-gate.sh

@@ -5,6 +5,12 @@
 
 set -uo pipefail
 
+# The main block ends with `} 2>/dev/null`: a Stop hook must not spray
+# diagnostics into a session. Keep one copy of the real stderr so a
+# misconfigured operator switch — the one failure the operator alone can fix,
+# and otherwise invisible — still has somewhere to be said.
+exec 3>&2
+
 {
   self_hq="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." 2>/dev/null && pwd)"
   HQ="${CLAUDE_PROJECT_DIR:-${HQ_ROOT:-$self_hq}}"
@@ -49,6 +55,88 @@ set -uo pipefail
     return 0
   }
 
+  # checkpoint_gate_trim — strips only the edges. Deleting interior whitespace
+  # would quietly repair a typo: "f alse" would become a valid `false` and
+  # disable the gate the operator was trying to keep on.
+  checkpoint_gate_trim() {
+    local s="$1"
+    s="${s#"${s%%[![:space:]]*}"}"
+    s="${s%"${s##*[![:space:]]}"}"
+    printf '%s' "$s"
+  }
+
+  # checkpoint_gate_setting — one operator switch, resolved the way hq-cli
+  # resolves it: the process environment first, then the HQ root's
+  # `.claude/settings.json` `env` block (overlaid by `settings.local.json`, the
+  # order Claude Code merges them).
+  #
+  # Reading the file matters because only Claude Code exports that block into
+  # hook processes. Under Codex or grok the variable is never set, so an
+  # operator who wrote the switch into settings.json would have had it silently
+  # ignored on exactly the runtimes where they cannot see why. Fail-open: any
+  # missing file, absent jq, or unreadable value leaves the gate at its default.
+  #
+  # Prints the raw value and returns 0 when one resolves. Returns 1 when the
+  # highest-priority file that mentions the key holds something unreadable — a
+  # present key stops the lookup rather than falling through, so a stale `"0"`
+  # further down cannot be promoted by a typo in the file above it. Same
+  # precedence the TypeScript resolver uses.
+  checkpoint_gate_setting() {
+    local key="$1" value="" file raw
+    eval "value=\${$key:-}"
+    value="$(checkpoint_gate_trim "$value")"
+    if [ -n "$value" ]; then
+      printf '%s' "$value"
+      return 0
+    fi
+    command -v jq >/dev/null 2>&1 || return 0
+    for file in "$HQ/.claude/settings.local.json" "$HQ/.claude/settings.json"; do
+      [ -r "$file" ] || continue
+      # Strings, and JSON's own true/false/0/1 — the literal an operator reaches
+      # for first — all resolve; null, an object, or an array does not. The
+      # leading marker separates "absent" (no output) from "present but
+      # unreadable" (`-`), which a bare value could not encode.
+      raw="$(jq -r --arg k "$key" '
+        try (
+          if (.env | type) == "object" and (.env | has($k))
+          then (.env[$k]
+                | if type == "string" or type == "boolean" or type == "number"
+                  then "+" + tostring
+                  else "-" end)
+          else empty end
+        ) catch empty' "$file" 2>/dev/null || true)"
+      case "$raw" in
+        "") continue ;;
+        -*) ;;
+        +*)
+          value="$(checkpoint_gate_trim "${raw#+}")"
+          if [ -n "$value" ]; then
+            printf '%s' "$value"
+            return 0
+          fi
+          ;;
+      esac
+      printf 'checkpoint-stop-gate: ignoring %s in %s (not a value it can read; expected a string such as "0" or "1")\n' \
+        "$key" "$file" >&3 2>/dev/null
+      return 1
+    done
+    return 0
+  }
+
+  # Normalizes one switch to 0, 1, or empty (= not set). An unreadable value is
+  # named on stderr rather than passed over: the operator asked for something.
+  checkpoint_gate_switch() {
+    local key="$1" raw
+    raw="$(checkpoint_gate_setting "$key" 2>/dev/null)" || return 0
+    [ -n "$raw" ] || return 0
+    case "$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')" in
+      0|false|off|no) printf '0' ;;
+      1|true|on|yes) printf '1' ;;
+      *) printf 'checkpoint-stop-gate: ignoring %s=%s (expected 0/1, false/true, off/on or no/yes)\n' "$key" "$raw" >&3 2>/dev/null ;;
+    esac
+    return 0
+  }
+
   input="$(cat 2>/dev/null || printf '{}')"
   input_fields="$(printf '%s' "$input" | jq -r '[.transcript_path // "", .session_id // ""] | @tsv' 2>/dev/null)" || exit 0
   IFS=$'\t' read -r transcript_path session_id <<<"$input_fields" || exit 0
@@ -57,6 +145,15 @@ set -uo pipefail
   # recursively demand another checkpoint of itself.
   [ "${HQ_CHECKPOINT_SIBLING:-}" = "1" ] && exit 0
 
+  # Resolved once: every branch below reads this instead of the raw variable.
+  gate_switch="$(checkpoint_gate_switch HQ_CHECKPOINT_GATE)"
+  # That was the only diagnostic, so drop the duplicate before anything is
+  # spawned. The detached `nohup ... &` commands below redirect fds 1 and 2
+  # only: a surviving fd 3 would be inherited by them and hold the hook
+  # runner's stderr pipe open, so a runner that reads stderr to EOF would wait
+  # on the supposedly detached checkpoint instead of on this shell.
+  exec 3>&-
+
   # Company-scope gate ---------------------------------------------------------
   # An OPT-IN requirement layered onto this Stop hook: for an operator whose
   # email domain is listed in HQ_CHECKPOINT_SCOPE_GATE_DOMAINS (comma-separated,
@@ -69,7 +166,7 @@ set -uo pipefail
   # alongside the checkpoint gate. Binding is a single recoverable call, so the
   # block loops only until the operator declares a scope.
   gate_domains="${HQ_CHECKPOINT_SCOPE_GATE_DOMAINS:-}"
-  case "${HQ_CHECKPOINT_GATE:-}" in
+  case "$gate_switch" in
     0) ;;
     *)
       gate_session_id="$(printf '%s' "$input" | jq -r '.session_id // ""' 2>/dev/null || true)"
@@ -120,7 +217,7 @@ set -uo pipefail
             *) [ -d "$gate_root/companies/$bound_co" ] && gate_bound=1 ;;
           esac
           if [ "$gate_bound" = 0 ]; then
-            company_reason="$(printf 'This session has not declared its scope, and a scope is required before the turn can end. Decide where this work belongs, then bind the session and finish the turn with your user-facing reply as the final text after the command output:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug <company-slug>\n\nUse a real tenant slug from companies/manifest.yaml — the company this session is actually working in, never an invented one. If this session does no company-scoped work, bind it to the reserved personal scope instead:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug personal\n\nAn operator can also disable this requirement for the run by exporting HQ_CHECKPOINT_GATE=0.' "$gate_root" "$gate_session_id" "$gate_root" "$gate_session_id")"
+            company_reason="$(printf 'This session has not declared its scope, and a scope is required before the turn can end. Decide where this work belongs, then bind the session and finish the turn with your user-facing reply as the final text after the command output:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug <company-slug>\n\nUse a real tenant slug from companies/manifest.yaml — the company this session is actually working in, never an invented one. If this session does no company-scoped work, bind it to the reserved personal scope instead:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug personal\n\nAn operator can also disable this requirement for the run by exporting HQ_CHECKPOINT_GATE=0, or for every runtime by putting \"env\": {\"HQ_CHECKPOINT_GATE\": \"0\"} in .claude/settings.json.' "$gate_root" "$gate_session_id" "$gate_root" "$gate_session_id")"
             printf '{"decision":"block","reason":%s}\n' "$(printf '%s' "$company_reason" | hq_json_encode)"
             exit 0
           fi
@@ -133,7 +230,7 @@ set -uo pipefail
 
   # Operator switches precede runtime and identity eligibility. A forced gate
   # intentionally bypasses the rollout rules for local trials and tests.
-  case "${HQ_CHECKPOINT_GATE:-}" in
+  case "$gate_switch" in
     0) exit 0 ;;
     1) enforce=true ;;
     *)
@@ -151,7 +248,7 @@ set -uo pipefail
 
   refresh_eligibility() {
     command -v hq >/dev/null 2>&1 || return 0
-    (nohup env HQ_CHECKPOINT_RUNTIME="$runtime" hq core checkpoint --gate-probe >/dev/null 2>&1 &)
+    (nohup env HQ_CHECKPOINT_RUNTIME="$runtime" hq core checkpoint --gate-probe >/dev/null 2>&1 3>&- &)
   }
 
   if [ "$runtime" = "codex" ] && [ "$enforce" = false ]; then
@@ -511,7 +608,7 @@ set -uo pipefail
        --trigger stop-gate-auto \
        --transcript "$transcript_path" \
        --summary "turn ended with its user-facing reply already delivered" \
-       >/dev/null 2>&1 &)
+       >/dev/null 2>&1 3>&- &)
     rm -f "$block_count_file" 2>/dev/null || true
     exit 0
   fi

package/dist/commands/core-checkpoint.js

@@ -49,6 +49,12 @@ const GROK_SIBLING_MAX_TURNS = "100";
  * hosts never read it.
  */
 const SIBLING_SETTING = "HQ_CHECKPOINT_AGENT";
+/**
+ * The Stop gate's own switch. Resolved through the same settings file as the
+ * sibling switch so it reaches Codex and grok, whose hosts never export the
+ * `.claude/settings.json` `env` block into a hook process.
+ */
+const GATE_SETTING = "HQ_CHECKPOINT_GATE";
 const SIBLING_SETTING_OFF = new Set(["0", "false", "off", "no"]);
 const SIBLING_SETTING_ON = new Set(["1", "true", "on", "yes"]);
 const FALLBACK_BACKEND_ORDER = ["claude", "codex", "grok"];
@@ -445,12 +451,13 @@ function checkpointGateRuntime() {
         return runtime;
     return "other";
 }
-function gateEligibility(runtime) {
-    const forced = process.env.HQ_CHECKPOINT_GATE;
-    if (forced === "0")
-        return false;
-    if (forced === "1")
-        return true;
+function gateEligibility(runtime, liveRoot) {
+    // An operator switch precedes runtime and identity eligibility, and is read
+    // from the settings file as well as the environment: under Codex and grok the
+    // environment is the one place the operator cannot reach.
+    const forced = resolveSwitchSetting(liveRoot, GATE_SETTING);
+    if (forced !== undefined)
+        return forced;
     if (runtime === "claude")
         return true;
     if (runtime !== "codex")
@@ -472,7 +479,7 @@ function writeGateVerdict(liveRoot) {
     const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
     fs.mkdirSync(stateDir, { recursive: true });
     const runtime = checkpointGateRuntime();
-    const eligible = gateEligibility(runtime);
+    const eligible = gateEligibility(runtime, liveRoot);
     fs.writeFileSync(path.join(stateDir, `checkpoint-gate-eligible-${runtime}`), eligible ? "1" : "0");
     printResult(eligible ? "eligible" : "ineligible");
 }
@@ -637,36 +644,45 @@ function settingsEnvValue(liveRoot, key) {
     return { kind: "absent" };
 }
 /** Maps one resolved value onto the switch, reporting a vocabulary it cannot read. */
-function parseSiblingSetting(raw, source) {
+function parseSwitchSetting(key, raw, source) {
     const value = raw.toLowerCase();
     if (SIBLING_SETTING_OFF.has(value))
         return false;
     if (SIBLING_SETTING_ON.has(value))
         return true;
-    printError(`checkpoint: ignoring ${SIBLING_SETTING}=${raw} from ${source} ` +
+    printError(`checkpoint: ignoring ${key}=${raw} from ${source} ` +
         "(expected 0/1, false/true, off/on or no/yes)");
-    return true;
+    return undefined;
 }
 /**
- * Whether the maintenance sibling may run at all. The process environment wins
- * over the settings file, so a one-off `HQ_CHECKPOINT_AGENT=0 hq core
- * checkpoint …` still works and a host that exports the settings `env` block
- * (Claude Code does) agrees with a host that does not.
+ * One operator switch: the process environment first, then the HQ root's
+ * Claude settings. `undefined` means nobody set it — distinct from a setting
+ * that says "off", and distinct from one this cannot read (reported, then
+ * treated as unset so a typo never silently flips a default).
  */
-export function siblingEnabledBySetting(liveRoot) {
-    const fromEnv = process.env[SIBLING_SETTING]?.trim();
+function resolveSwitchSetting(liveRoot, key) {
+    const fromEnv = process.env[key]?.trim();
     if (fromEnv)
-        return parseSiblingSetting(fromEnv, "the environment");
-    const lookup = settingsEnvValue(liveRoot, SIBLING_SETTING);
+        return parseSwitchSetting(key, fromEnv, "the environment");
+    const lookup = settingsEnvValue(liveRoot, key);
     if (lookup.kind === "absent")
-        return true;
+        return undefined;
     if (lookup.kind === "invalid") {
-        printError(`checkpoint: ignoring ${SIBLING_SETTING} in ${lookup.source}: ` +
+        printError(`checkpoint: ignoring ${key} in ${lookup.source}: ` +
             `${JSON.stringify(lookup.raw) ?? String(lookup.raw)} is not a value it can read ` +
             '(expected a string such as "0" or "1")');
-        return true;
+        return undefined;
     }
-    return parseSiblingSetting(lookup.value, lookup.source);
+    return parseSwitchSetting(key, lookup.value, lookup.source);
+}
+/**
+ * Whether the maintenance sibling may run at all. The process environment wins
+ * over the settings file, so a one-off `HQ_CHECKPOINT_AGENT=0 hq core
+ * checkpoint …` still works and a host that exports the settings `env` block
+ * (Claude Code does) agrees with a host that does not.
+ */
+export function siblingEnabledBySetting(liveRoot) {
+    return resolveSwitchSetting(liveRoot, SIBLING_SETTING) ?? true;
 }
 /** Rejects an unknown `--backend` without paying for the probe that resolves one. */
 function assertKnownBackend(requested) {

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.4",
+  "version": "5.115.6",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {