@indigoai-us/hq-cli 5.345.170 → 5.345.172

package/dist/lib/daemon/catalog.d.ts

@@ -11,11 +11,11 @@
  */
 import type { MachineType } from "./machine-type.js";
 import type { SyncOwner } from "./config.js";
-import type { SyncCoreCanaryPlan } from "./sync-core-canary.js";
+import { type SyncCoreVaultPlan } from "../sync-core/engine-home.js";
 import type { RemoteControlPoolsConfig } from "./remote-control-pools.js";
 import { type SyncRunnerProcess } from "./sync-runner.js";
 import { type VaultSyncSwitches } from "../vault-sync-switches.js";
-export declare const SERVICE_NAMES: readonly ["sync", "mesh", "heartbeat", "inbox", "bots", "remote-control", "codex-remote-control", "session-host", "lanes-reconcile", "search-index", "jobs-reconcile", "updater", "housekeeping"];
+export declare const SERVICE_NAMES: readonly ["sync", "sync-core", "mesh", "heartbeat", "inbox", "bots", "remote-control", "codex-remote-control", "session-host", "lanes-reconcile", "search-index", "jobs-reconcile", "updater", "housekeeping"];
 export type ServiceName = (typeof SERVICE_NAMES)[number];
 export declare function isServiceName(value: unknown): value is ServiceName;
 export declare const SERVICE_DESCRIPTIONS: Record<ServiceName, string>;
@@ -86,6 +86,13 @@ export interface UnitPlan {
         idleIntervalSec: number;
     };
 }
+export interface SyncCoreRunning {
+    personal: boolean;
+    companies: ReadonlySet<string>;
+}
+export declare const SYNC_CORE_RECONCILE_UNIT = "sync-core";
+export declare const SYNC_CORE_RECONCILE_INTERVAL_SEC = 600;
+export declare const SYNC_CORE_LEGACY_SETTLE_MS: number;
 export interface PlanContext {
     machineType: MachineType;
     platform: NodeJS.Platform;
@@ -113,9 +120,10 @@ export interface PlanContext {
     vaultSync?: VaultSyncSwitches;
     /** Persisted/effective owner selected for this machine. */
     syncOwner: SyncOwner;
-    syncCoreCanary?: SyncCoreCanaryPlan;
+    syncCoreVaults?: readonly SyncCoreVaultPlan[];
+    syncCoreRunning?: SyncCoreRunning;
     legacySyncReadyForCore?: boolean;
-    syncCoreCanaryRunning?: boolean;
+    now?: number;
     /** A legacy desktop app or sync unit is still managing sync. */
     desktopAppManagesSync: boolean;
     /** Full process list, or null when the daemon could not read it. */

package/dist/lib/daemon/catalog.js

@@ -9,10 +9,13 @@
  * with no entrypoint yet stay in the catalog as `unavailable` so status shows
  * them instead of silently dropping them.
  */
+import * as path from "node:path";
+import { syncCoreUnitId } from "../sync-core/engine-home.js";
 import { SYNC_RUNNER_OWNER, syncRunnerUnleasedBlockReason } from "./sync-runner.js";
 import { vaultSkipEnv } from "../vault-sync-switches.js";
 export const SERVICE_NAMES = [
     "sync",
+    "sync-core",
     "mesh",
     "heartbeat",
     "inbox",
@@ -31,6 +34,7 @@ export function isServiceName(value) {
 }
 export const SERVICE_DESCRIPTIONS = {
     sync: "keeps company vaults in sync with the cloud",
+    "sync-core": "moves vaults to the new sync engine when their company's switch is on",
     mesh: "Work Mesh Live presence",
     heartbeat: "reports this machine's status to HQ",
     inbox: "picks up the agent's incoming messages and tasks",
@@ -46,9 +50,10 @@ export const SERVICE_DESCRIPTIONS = {
 };
 /** The services each machine type runs without being asked. */
 export const DEFAULT_SERVICES = {
-    desktop: ["sync", "mesh", "heartbeat", "bots", "lanes-reconcile", "search-index", "updater", "housekeeping"],
+    desktop: ["sync", "sync-core", "mesh", "heartbeat", "bots", "lanes-reconcile", "search-index", "updater", "housekeeping"],
     "self-hosted": [
         "sync",
+        "sync-core",
         "mesh",
         "heartbeat",
         "bots",
@@ -79,6 +84,9 @@ export function enabledServices(machineType, overrides) {
     const defaults = DEFAULT_SERVICES[machineType];
     return SERVICE_NAMES.filter((s) => (defaults.includes(s) || overrides.enable.includes(s)) && !overrides.disable.includes(s));
 }
+export const SYNC_CORE_RECONCILE_UNIT = "sync-core";
+export const SYNC_CORE_RECONCILE_INTERVAL_SEC = 600;
+export const SYNC_CORE_LEGACY_SETTLE_MS = 10 * 60 * 1000;
 function base(service, over = {}) {
     return {
         id: service,
@@ -123,11 +131,12 @@ function planService(service, ctx) {
     const agentMachine = ctx.machineType === "agent-kit" || ctx.machineType === "agent-box";
     switch (service) {
         case "sync": {
-            const vaultSync = ctx.syncCoreCanaryRunning
+            const running = ctx.syncCoreRunning;
+            const vaultSync = running && (running.personal || running.companies.size > 0)
                 ? {
                     allOff: ctx.vaultSync?.allOff === true,
-                    personalOff: true,
-                    offCompanies: ctx.vaultSync?.offCompanies ?? new Set(),
+                    personalOff: ctx.vaultSync?.personalOff === true || running.personal,
+                    offCompanies: new Set([...(ctx.vaultSync?.offCompanies ?? []), ...running.companies]),
                 }
                 : ctx.vaultSync;
             let ownerBlock;
@@ -181,30 +190,67 @@ function planService(service, ctx) {
                     blocked: commonBlock,
                 })
                 : unavailable(service, "the hq-cloud sync runner is missing from this CLI install");
-            if (!ctx.syncCoreCanary)
-                return [unit];
-            const core = base(service, {
-                id: "sync-core-canary",
-                description: "keeps one personal-vault canary in sync with sync-core",
-                command: ctx.syncCoreCanary.binaryPath
-                    ? { type: "exec", file: ctx.syncCoreCanary.binaryPath, args: ["start", "--loop"] }
-                    : null,
-                env: {
-                    HQ_SYNC_ENGINE: "rust-test",
-                    HQ_SYNC_MODE: "full",
-                    HQ_SYNC_PROTOCOL: "1",
-                    ...(ctx.syncCoreCanary.vaultUid ? { HQ_SYNC_CANARY_VAULT: ctx.syncCoreCanary.vaultUid } : {}),
-                    ...(ctx.syncCoreCanary.canaryPath ? { HQ_SYNC_CANARY_PATH: ctx.syncCoreCanary.canaryPath } : {}),
+            return [unit];
+        }
+        case "sync-core": {
+            if (ctx.platform !== "darwin" && ctx.platform !== "linux") {
+                return [unavailable(service, "the new sync engine runs on macOS and Linux only")];
+            }
+            const reconcile = base(service, {
+                id: SYNC_CORE_RECONCILE_UNIT,
+                kind: "scheduled",
+                intervalSec: SYNC_CORE_RECONCILE_INTERVAL_SEC,
+                initialDelaySec: 30,
+                command: {
+                    type: "hq",
+                    args: ["daemon", "service", "sync-core-reconcile", ...(ctx.hqRoot ? ["--hq-root", ctx.hqRoot] : [])],
                 },
-                heartbeatTimeoutMs: 180_000,
+                env: { HQ_NO_UPDATE_CHECK: "1" },
                 blocked: firstBlock([
-                    [!!commonBlock, commonBlock?.reason ?? ""],
-                    [!!ctx.syncCoreCanary.blockedReason, ctx.syncCoreCanary.blockedReason ?? ""],
-                    [ctx.vaultSync?.personalOff !== true, "turn the personal vault off in the current sync before starting the sync-core canary"],
-                    [ctx.legacySyncReadyForCore !== true, "waiting for legacy sync to run its company-only plan"],
+                    [!ctx.hqRoot, NO_HQ_ROOT],
+                    [!ctx.signedIn, NOT_SIGNED_IN],
                 ]),
             });
-            return [unit, core];
+            const now = ctx.now ?? Date.now();
+            const engines = (ctx.syncCoreVaults ?? []).map((vault) => {
+                const full = vault.phase === "full";
+                const legacyOff = vault.kind === "personal"
+                    ? ctx.vaultSync?.personalOff === true
+                    : ctx.vaultSync?.offCompanies.has(vault.slug ?? "") === true;
+                const offSince = vault.legacyOffSince ? Date.parse(vault.legacyOffSince) : Number.NaN;
+                const settled = Number.isFinite(offSince) && now - offSince >= SYNC_CORE_LEGACY_SETTLE_MS;
+                const legacyReady = ctx.legacySyncReadyForCore === true && (!ctx.desktopAppManagesSync || settled);
+                const what = vault.kind === "personal" ? "the personal vault" : `the ${vault.slug} vault`;
+                return base(service, {
+                    id: syncCoreUnitId(vault.uid),
+                    description: full
+                        ? `keeps ${what} in sync with the new sync engine (${vault.release})`
+                        : `warms the new sync engine's index for ${what} (${vault.release}, read-only)`,
+                    command: { type: "exec", file: vault.binaryPath, args: ["start", "--loop"] },
+                    env: {
+                        HOME: vault.engineHome,
+                        HQ_STATE_DIR: path.join(ctx.home, ".hq"),
+                        HQ_SYNC_ENGINE: "rust-test",
+                        HQ_SYNC_MODE: full ? "full" : "readonly",
+                        ...(full ? { HQ_SYNC_FULL_VAULT: "1" } : {}),
+                        HQ_SYNC_PROTOCOL: "1",
+                        HQ_SYNC_CORE_RELEASE: vault.release,
+                    },
+                    heartbeatTimeoutMs: 180_000,
+                    blocked: firstBlock([
+                        [ctx.syncPaused, "sync is paused (run `hq daemon sync resume`)"],
+                        [ctx.vaultSync?.allOff === true, "cloud sync is off for every vault on this computer (turn it back on in HQ Settings > Sync)"],
+                        [!ctx.hqRoot, NO_HQ_ROOT],
+                        [!ctx.signedIn, NOT_SIGNED_IN],
+                        [!!vault.blockedReason, vault.blockedReason ?? ""],
+                        [full && !legacyOff, `waiting for the current sync to be turned off for ${what}`],
+                        [full && !legacyReady, ctx.legacySyncReadyForCore !== true
+                                ? "waiting for the current sync to run its plan without this vault"
+                                : "waiting for the desktop app's sync to pick up the off-switch"],
+                    ]),
+                });
+            });
+            return [reconcile, ...engines];
         }
         case "mesh": {
             const args = ["mesh", "daemon", "run", ...(ctx.hqRoot ? ["--hq-root", ctx.hqRoot] : [])];

package/dist/lib/daemon/config.d.ts

@@ -18,19 +18,12 @@ export interface DaemonConfig {
     instantSyncEnabled?: boolean;
     /** Explicit desktop handoff; absent values preserve the legacy per-machine owner. */
     syncOwner?: SyncOwner;
-    syncCoreCanary?: SyncCoreCanaryConfig;
-    syncCoreCanaryError?: string;
-    syncCoreCanaryInvalid?: unknown;
     /** Services turned on here beyond the machine type's defaults. */
     enable: string[];
     /** Default services turned off here. */
     disable: string[];
 }
 export type SyncOwner = "daemon" | "desktop-app";
-export interface SyncCoreCanaryConfig {
-    binaryPath: string;
-    vaultUid: string;
-}
 export declare function effectiveSyncOwner(config: Pick<DaemonConfig, "syncOwner">, machineType: MachineType): SyncOwner;
 export declare function readDaemonConfig(file: string): DaemonConfig;
 export declare function writeDaemonConfig(file: string, config: DaemonConfig): void;

package/dist/lib/daemon/config.js

@@ -19,27 +19,6 @@ function emptyDaemonConfig() {
 function stringList(value) {
     return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
 }
-function syncCoreCanary(value, file) {
-    if (value === undefined)
-        return {};
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return { error: `hq daemon config at ${file} has invalid syncCoreCanary`, invalid: value };
-    }
-    const candidate = value;
-    if (typeof candidate.binaryPath !== "string" || !path.isAbsolute(candidate.binaryPath)) {
-        return {
-            error: `hq daemon config at ${file} has invalid syncCoreCanary: binaryPath must be absolute`,
-            invalid: value,
-        };
-    }
-    if (typeof candidate.vaultUid !== "string" || !/^prs_[A-Za-z0-9][A-Za-z0-9_-]*$/.test(candidate.vaultUid)) {
-        return {
-            error: `hq daemon config at ${file} has invalid syncCoreCanary: vaultUid must name one personal vault`,
-            invalid: value,
-        };
-    }
-    return { config: { binaryPath: candidate.binaryPath, vaultUid: candidate.vaultUid } };
-}
 export function readDaemonConfig(file) {
     let text;
     try {
@@ -72,13 +51,6 @@ export function readDaemonConfig(file) {
         config.machineType = obj.machineType;
     if (obj.syncOwner === "daemon" || obj.syncOwner === "desktop-app")
         config.syncOwner = obj.syncOwner;
-    const parsedCanary = syncCoreCanary(obj.syncCoreCanary, file);
-    if (parsedCanary.config)
-        config.syncCoreCanary = parsedCanary.config;
-    if (parsedCanary.error)
-        config.syncCoreCanaryError = parsedCanary.error;
-    if (parsedCanary.error)
-        config.syncCoreCanaryInvalid = parsedCanary.invalid;
     if (typeof obj.hqRoot === "string" && obj.hqRoot.trim())
         config.hqRoot = obj.hqRoot;
     if (typeof obj.hqCloudVersion === "string" && validSemver(obj.hqCloudVersion) === obj.hqCloudVersion) {
@@ -101,10 +73,6 @@ export function writeDaemonConfig(file, config) {
         ordered.instantSyncEnabled = config.instantSyncEnabled;
     if (config.syncOwner)
         ordered.syncOwner = config.syncOwner;
-    if (config.syncCoreCanary)
-        ordered.syncCoreCanary = config.syncCoreCanary;
-    else if (config.syncCoreCanaryError)
-        ordered.syncCoreCanary = config.syncCoreCanaryInvalid;
     ordered.enable = config.enable;
     ordered.disable = config.disable;
     fs.writeFileSync(tmp, `${JSON.stringify(ordered, null, 2)}\n`, { mode: 0o600 });

package/dist/lib/daemon/run.d.ts

@@ -14,7 +14,7 @@ import { type HostApp, type Supervisor } from "./supervisor.js";
 export declare const LOG_ROTATE_BYTES: number;
 /** Exit code for "restart me": non-zero so every service manager relaunches (Windows tasks only restart on failure). */
 export declare const RESTART_EXIT_CODE = 75;
-export declare function planUnitsWithSyncCoreInterlock(services: readonly ServiceName[], context: PlanContext, supervisor: Pick<Supervisor, "runningPlanKey"> | null | undefined): UnitPlan[];
+export declare function planUnitsWithSyncCoreInterlock(services: readonly ServiceName[], context: PlanContext, supervisor: Pick<Supervisor, "runningPlanKey" | "state"> | null | undefined): UnitPlan[];
 /** A bounded shutdown deadline that can account for sync push persistence. */
 export declare function createShutdownCap(): {
     promise: Promise<"timeout">;
@@ -94,6 +94,10 @@ export declare function daemonSyncUnitIsPresent(units: readonly {
 export declare function resolveSyncRunnerPath(): string | null;
 /** The hosted desktop app uses this env value when planning daemon services. */
 export declare function daemonInstantSyncEnabled(env: NodeJS.ProcessEnv, configured?: boolean): boolean;
+/**
+ * The bots the daemon runs itself. A bot on the HQ Fleet Runtime has its own
+ * background service, so it is not one of them.
+ */
 export declare function listLocalBots(root?: string): string[];
 export declare function windowsTaskExists(taskName: string): boolean;
 export declare function probeLegacyUnits(platform: NodeJS.Platform, home: string): LegacyUnit[];

package/dist/lib/daemon/run.js

@@ -18,11 +18,12 @@ import { anywhereRuntimeAllowed, readHqAnywherePersonSetting, stickyPersonSettin
 import { currentPackageUseLeaseInstall, currentPackageUseUpdateRequested } from "../../utils/package-use-lease.js";
 import { isLocalDependencyInstall, resolveRunningInstall } from "../../utils/version-gate.js";
 import { agentKitPaths } from "../agent-kit/paths.js";
-import { readBotConfig } from "../bot/config.js";
+import { HQ_FLEET_RUNTIME_ENGINE_ID, readBotConfig } from "../bot/config.js";
 import { botsRoot } from "../bot/paths.js";
 import { CLAUDE_RUNNER_SCRIPT, CODEX_RUNNER_SCRIPT, enabledServices, planUnits } from "./catalog.js";
 import { effectiveSyncOwner, readDaemonConfig } from "./config.js";
-import { inspectSyncCoreCanary } from "./sync-core-canary.js";
+import { inspectEngineHome } from "../sync-core/engine-home.js";
+import { readSyncCoreRolloutState } from "../sync-core/rollout-state.js";
 import { assertPersonalServiceSessionCapability, readRemoteControlPoolsConfig, remoteControlPoolSecretsEnv, } from "./remote-control-pools.js";
 import { loadLanesConfig } from "../lanes/config.js";
 import { daemonLanesReconcileHandler } from "../lanes/daemon-reconcile.js";
@@ -64,17 +65,48 @@ export const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
 export const RESTART_EXIT_CODE = 75;
 const NON_SYNC_SHUTDOWN_CAP_MS = STOP_ESCALATION_MS + 5_000;
 const SYNC_RUNNER_SHUTDOWN_CAP_MS = STOP_ESCALATION_MS + SYNC_RUNNER_PERSIST_GRACE_MS + 5_000;
+function syncCoreVaultPlans(home, hqRoot, platform) {
+    const state = readSyncCoreRolloutState(home);
+    if (!state)
+        return [];
+    return state.vaults.map((vault) => inspectEngineHome(home, hqRoot, {
+        uid: vault.uid,
+        kind: vault.kind,
+        ...(vault.slug ? { slug: vault.slug } : {}),
+        phase: vault.phase,
+        engineHome: vault.engineHome,
+        binaryPath: state.binaryPath,
+        release: state.release,
+        ...(vault.legacyOffSince ? { legacyOffSince: vault.legacyOffSince } : {}),
+    }, platform));
+}
+const rememberedSyncCoreVaults = new Map();
 export function planUnitsWithSyncCoreInterlock(services, context, supervisor) {
-    const syncCoreCanaryRunning = supervisor?.runningPlanKey("sync-core-canary") !== undefined;
+    const companies = new Set();
+    let personal = false;
+    for (const vault of context.syncCoreVaults ?? []) {
+        rememberedSyncCoreVaults.set(vault.uid, { kind: vault.kind, slug: vault.slug, full: vault.phase === "full" });
+    }
+    for (const unit of supervisor?.state().units ?? []) {
+        if (!unit.id.startsWith("sync-core:") || supervisor?.runningPlanKey(unit.id) === undefined)
+            continue;
+        const vault = rememberedSyncCoreVaults.get(unit.id.slice("sync-core:".length));
+        if (!vault?.full)
+            continue;
+        if (vault.kind === "personal")
+            personal = true;
+        else if (vault.slug)
+            companies.add(vault.slug);
+    }
     const transitionContext = {
         ...context,
-        syncCoreCanaryRunning,
+        syncCoreRunning: { personal, companies },
         legacySyncReadyForCore: false,
     };
     const waiting = planUnits(services, transitionContext);
     const legacy = waiting.find((unit) => unit.id === "sync");
     const legacySyncReadyForCore = legacy !== undefined
-        && supervisor?.runningPlanKey("sync") === planKey(legacy, CLI_VERSION);
+        && (legacy.blocked !== undefined || supervisor?.runningPlanKey("sync") === planKey(legacy, CLI_VERSION));
     return planUnits(services, { ...transitionContext, legacySyncReadyForCore });
 }
 /** A bounded shutdown deadline that can account for sync push persistence. */
@@ -260,12 +292,21 @@ export function resolveSyncRunnerPath() {
 export function daemonInstantSyncEnabled(env, configured) {
     return configured ?? env.HQ_DAEMON_INSTANT_SYNC !== "0";
 }
+/**
+ * The bots the daemon runs itself. A bot on the HQ Fleet Runtime has its own
+ * background service, so it is not one of them.
+ */
 export function listLocalBots(root = botsRoot()) {
     if (!fs.existsSync(root))
         return [];
     return fs
         .readdirSync(root, { withFileTypes: true })
-        .filter((d) => d.isDirectory() && readBotConfig(path.join(root, d.name)) !== null)
+        .filter((d) => {
+        if (!d.isDirectory())
+            return false;
+        const config = readBotConfig(path.join(root, d.name));
+        return config !== null && config.engine?.id !== HQ_FLEET_RUNTIME_ENGINE_ID;
+    })
         .map((d) => d.name)
         .sort();
 }
@@ -978,11 +1019,7 @@ export async function runDaemon(opts) {
                 return switches;
             })(),
             syncOwner,
-            syncCoreCanary: config.syncCoreCanaryError
-                ? { blockedReason: config.syncCoreCanaryError }
-                : config.syncCoreCanary
-                    ? inspectSyncCoreCanary(home, hqRoot, config.syncCoreCanary, platform)
-                    : undefined,
+            syncCoreVaults: syncCoreVaultPlans(home, hqRoot, platform),
             desktopAppManagesSync: appManagesSync,
             syncRunnerProcesses,
             syncRunnerOwnerPid,

package/dist/lib/daemon/supervisor.js

@@ -87,7 +87,7 @@ function keyHash(key) {
     return createHash("sha256").update(key).digest("hex");
 }
 function recoverableHold(plan, hold) {
-    return plan.kind === "long-running" && (plan.service === "sync" || plan.service === "mesh")
+    return plan.kind === "long-running" && (plan.service === "sync" || plan.service === "sync-core" || plan.service === "mesh")
         && hold?.kind === "exhausted" && hold.cause === "transient";
 }
 function heldReason(unitId, hold) {
@@ -388,6 +388,8 @@ export function createSupervisor(deps) {
         const cause = classifyExit(evidence);
         if (cause.kind !== "permanent")
             return false;
+        if (slot.plan.service === "sync-core" && cause.cause === "bad-config")
+            return false;
         slot.failures += 1;
         holdUnit(slot, "permanent", cause.cause, cause.detail);
         return true;

package/dist/lib/doctor/checks/release-links.d.ts

@@ -9,7 +9,9 @@ import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
 export declare const RELEASE_LINKS_FAMILY_ID = "release-links";
 export declare const RELEASE_LINKS_FAMILY_TITLE = "Release links";
 export declare const RELEASE_LINKS_CHECK_ID = "release-links.resolve";
-export declare const RELEASE_LINK_REMEDIATION = "Run `hq rescue -y` again. On Windows without Developer Mode, a directory link is written as a junction and a file link as a copy.";
+export declare const RELEASE_LINK_REMEDIATION = "Run `hq doctor --fix` (or `hq rescue -y`) to restore the shipped link. A dangling link that points outside the HQ root and the temp folder is treated as your own and left alone. On Windows, a directory link is written as a junction and a file link as a copy when symlinks are not allowed.";
+/** Message prefix for a link whose target is missing; `--fix` keys off it. */
+export declare const DANGLING_RELEASE_LINK_PROBLEM = "does not resolve.";
 interface ReleaseLink {
     rel: string;
     linkText: string;
@@ -19,5 +21,64 @@ interface ReleaseLink {
 export declare const RELEASE_LINKS: readonly ReleaseLink[];
 export declare const releaseLinksFamily: CheckFamily;
 export declare function checkReleaseLinks(context: CheckContext): CheckResult[];
+/** Where a rescue may stage its extraction folder. */
+export interface RescueStagingDeps {
+    /** The system temp folder. Default `os.tmpdir()`. */
+    tmpDir?: string;
+    /** The rescue backup root. Default `$HQ_BACKUP_DIR` or `~/.hq/backups`. */
+    backupRoot?: string;
+}
+/** What {@link repairDanglingReleaseLinks} did to one release link. */
+export interface ReleaseLinkRepair {
+    rel: string;
+    /**
+     * `repointed`: the link was rewritten (see `linkText`). `removed`: the
+     * shipped target is missing too, so the dangling link was deleted.
+     * `skipped`: the link points outside the HQ root and the temp folder, so it
+     * is treated as the user's own link and left alone (see `reason`).
+     * `failed`: the repair threw for this link only (see `reason`).
+     */
+    action: "repointed" | "removed" | "skipped" | "failed";
+    /** The absolute target the link now resolves to (repointed only). */
+    target?: string;
+    /** The text written into the link (repointed only). */
+    linkText?: string;
+    reason?: string;
+}
+export interface RepairReleaseLinksDeps {
+    platform?: NodeJS.Platform;
+    /** Repair only this release link (a `RELEASE_LINKS` rel). */
+    only?: string;
+    /** The temp folder a rescue extracts into. Default `os.tmpdir()`. */
+    tmpDir?: string;
+    /** The rescue backup root. Default `$HQ_BACKUP_DIR` or `~/.hq/backups`. */
+    backupRoot?: string;
+}
+/**
+ * Repair HQ-managed release links whose target no longer exists, such as a
+ * `.agents/skills` or `.codex/claude` link an earlier rescue pointed at its
+ * deleted temp extraction folder (feedback_2ab63e50).
+ *
+ * Only the fixed {@link RELEASE_LINKS} paths are considered, and only when the
+ * entry itself is a symlink or junction that does not resolve. A real file or
+ * directory is never touched, a link that resolves anywhere is left alone, and
+ * the link's parent folder must sit inside the HQ root, so a `.agents` folder
+ * that is itself a link out of the tree is skipped.
+ *
+ * Ownership rule: a dangling link is repaired only when its current target is
+ * under the HQ root or under the system temp folder (where a rescue extracts
+ * its staging copy). A dangling link anywhere else, such as `/Volumes/X`, is
+ * the user's own link to a drive that is not mounted; it is left alone and
+ * reported as `skipped`.
+ *
+ * The repaired link carries the text HQ ships (`../.claude/skills`), so the
+ * git-tracked link is unchanged. On Windows a directory link is an absolute
+ * junction and a file link an absolute symlink, falling back to a copy. When
+ * the shipped target is missing too, the dangling link is removed and nothing
+ * is created. The old entry is removed with {@link removeLinkOnly}, which never
+ * follows it. A failure on one link is reported as `failed` and the remaining
+ * links are still repaired.
+ */
+export declare function repairDanglingReleaseLinks(hqRoot: string, deps?: RepairReleaseLinksDeps): ReleaseLinkRepair[];
 export {};
 //# sourceMappingURL=release-links.d.ts.map