@indigoai-us/hq-cli 5.345.170 → 5.345.171

package/dist/lib/bot/local-config.js

@@ -9,7 +9,7 @@
  * checks the result before it leaves this machine: a bot's machine credentials
  * live only in ~/.hq/bots/<name>/machine-creds.json and never travel here.
  */
-import { botMemoryMode, effectiveBotCompanies, effectiveBotKind, isBotKind, isBotMemoryMode, isBotRuntimeId, } from "./config.js";
+import { botMemoryMode, effectiveBotCompanies, effectiveBotKind, isBotKind, isBotEngineMetadata, isBotMemoryMode, isBotRuntimeId, } from "./config.js";
 /** Same limit the server enforces on the stored value. */
 const BOT_LOCAL_CONFIG_MAX_BYTES = 8 * 1024;
 /** Key names the server rejects outright (case-insensitive, substring). */
@@ -41,7 +41,8 @@ export function buildBotLocalConfig(config) {
     const companies = effectiveBotCompanies(config);
     const local = {
         v: 1,
-        runtime: config.runtime,
+        ...(config.engine ? {} : { runtime: config.runtime }),
+        ...(config.engine ? { engine: config.engine } : {}),
         workerSource: config.workerSource ?? "scaffold",
         ...(config.workerId ? { workerId: config.workerId } : {}),
         ...(config.companySlug ? { companySlug: config.companySlug } : {}),
@@ -80,6 +81,8 @@ export function parseBotLocalConfig(value) {
     const runtime = str("runtime");
     if (isBotRuntimeId(runtime))
         out.runtime = runtime;
+    if (isBotEngineMetadata(raw.engine))
+        out.engine = raw.engine;
     const workerSource = str("workerSource");
     if (workerSource === "worker" || workerSource === "scaffold")
         out.workerSource = workerSource;

package/dist/lib/bot/promote.d.ts

@@ -1,5 +1,14 @@
 import type { BotApi, BotPromotionState } from "./api.js";
 import type { BotConfig } from "./config.js";
+import type { BotMachineCreds } from "./creds.js";
+/** A bot whose process and HQ machine credential live outside its state folder,
+ * such as an HQ Fleet Runtime bot: promotion stops its service through the
+ * runtime and reads the credential from the runtime's secure store.
+ */
+export interface LocalBotPromotionRuntime {
+    stop(): void;
+    machineCredential(): BotMachineCreds;
+}
 /** One recoverable local-to-cloud step, used by CLI and desktop. Never kills the
  * local runtime, recopies provider login files, or changes another bot.
  */
@@ -9,6 +18,7 @@ export declare function promoteLocalBot(input: {
     companyUid: string;
     api: BotApi;
     drainTimeoutMs?: number;
+    runtime?: LocalBotPromotionRuntime;
 }): Promise<{
     promotion: BotPromotionState;
     pending: boolean;

package/dist/lib/bot/promote.js

@@ -41,7 +41,7 @@ function readPrivateJson(file, limit) {
  * local runtime, recopies provider login files, or changes another bot.
  */
 export async function promoteLocalBot(input) {
-    const { dir, config, companyUid, api } = input;
+    const { dir, config, companyUid, api, runtime } = input;
     const existing = await api.promotionStatus(config.agentUid, companyUid);
     const holdFile = path.join(dir, "promotion-hold.json");
     const localHold = fs.existsSync(holdFile) ? readPrivateJson(holdFile, 2048) : null;
@@ -58,6 +58,7 @@ export async function promoteLocalBot(input) {
         recordActivePromotion(dir, hold, existing);
         return { promotion: existing, pending: false };
     }
+    runtime?.stop();
     await waitForPromotionDrain(dir, input.drainTimeoutMs ?? 60_000);
     const file = path.join(dir, `promotion-snapshot-${operationId}.json`);
     if (!fs.existsSync(file)) {
@@ -83,7 +84,7 @@ export async function promoteLocalBot(input) {
         throw new Error("Frozen snapshot does not match the cloud operation");
     let state = existing;
     if (!state || state.phase === "preparing") {
-        const machine = readPrivateJson(botCredsPath(dir), 8192);
+        const machine = runtime ? runtime.machineCredential() : readPrivateJson(botCredsPath(dir), 8192);
         if (!machine || typeof machine !== "object" || typeof machine.secret !== "string")
             throw new Error("Invalid bot machine credential");
         try {

package/dist/lib/bot/runtime/index.js

@@ -1,7 +1,6 @@
 import { execFileSync, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { planBotRuntimeSpawn } from "./windows.js";
 import { GrokAcpClient } from "./grok-acp.js";
@@ -9,6 +8,7 @@ import { createClaudeRuntime } from "./claude.js";
 import { createCodexRuntime } from "./codex.js";
 import { createGrokRuntime, grokRetryArgsAfterInvalidOutputFormat, probeGrokOutputFormat } from "./grok.js";
 import { stripControlTokens } from "./sanitize.js";
+import { createTurnScratchDir } from "./scratch-dir.js";
 import { isRuntimeVersionTooOld, versionTooOldModel } from "../runtime-failure.js";
 import { parseJsonLine, RuntimeError, turnTimeoutMs, stderrExcerpt, MAX_MODEL_FALLBACK_RETRIES, } from "./types.js";
 export * from "./types.js";
@@ -345,10 +345,13 @@ export function forgetModelFallbacks() {
  */
 export async function runRuntimeTurn(runtime, input, deps = {}) {
     const spawnImpl = deps.spawnImpl ?? defaultSpawn;
-    const scratchDir = deps.scratchDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "hq-bot-turn-"));
+    const turnEnv = input.env ?? deps.env ?? process.env;
+    const turnPlatform = deps.platform ?? input.platform ?? process.platform;
+    const scratch = deps.scratchDir ? { dir: deps.scratchDir } : createTurnScratchDir("hq-bot-turn-", { platform: turnPlatform });
+    const scratchDir = scratch.dir;
     const outputFile = path.join(scratchDir, "last-message.txt");
     const newSessionId = input.newSessionId ?? (deps.newSessionId ?? randomUUID)();
-    const turnInput = { ...input, platform: deps.platform ?? input.platform ?? process.platform };
+    const turnInput = { ...input, platform: turnPlatform };
     const nowMs = deps.now ?? Date.now;
     const memoKey = fallbackKey(runtime, input.model);
     const memo = rememberedModelFallbacks.get(memoKey);
@@ -358,7 +361,8 @@ export async function runRuntimeTurn(runtime, input, deps = {}) {
     const args = runtime.buildArgs(remembered ? { ...turnInput, model: remembered.to } : turnInput, { outputFile, newSessionId });
     // Enforce at the model boundary too: old plists and direct `bot run` callers
     // may lack the guard. A bot prompt must never quit the user's desktop app.
-    const baseEnv = { ...(input.env ?? deps.env ?? process.env), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
+    // When TMPDIR was unwritable, hand the runtime CLI the working temp root too.
+    const baseEnv = { ...turnEnv, ...(scratch.fallbackRoot ? { TMPDIR: scratch.fallbackRoot } : {}), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
     const env = { ...(runtime.runtimeEnv?.(baseEnv) ?? baseEnv), HQ_NO_ENSURE_HQ_DESKTOP: "1" };
     const binary = runtime.resolveBinary?.(env, input.cwd, turnInput.platform) ?? runtime.binary;
     const stdin = runtime.stdinInput?.(turnInput);

package/dist/lib/bot/runtime/scratch-dir.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-turn scratch folder for the local bot runtime (feedback_f0131909).
+ *
+ * A bot started by launchd/systemd at login can inherit a TMPDIR it cannot
+ * write yet (an external volume that is not mounted or not yet readable by the
+ * agent), so `mkdtemp` failed with EPERM on every turn until `hq bot restart`
+ * re-launched it with a working TMPDIR. Try the configured folder first, then
+ * /tmp, then ~/.hq/tmp. When TMPDIR works nothing changes.
+ */
+export interface TurnScratchDir {
+    /** The created scratch folder. */
+    dir: string;
+    /** The temp root used, when it is not the configured one. */
+    fallbackRoot?: string;
+}
+export interface TurnScratchDeps {
+    /** The configured temp root. Defaults to os.tmpdir(), exactly as before. */
+    tmpdir?: string;
+    platform?: NodeJS.Platform;
+    home?: string;
+    warn?: (line: string) => void;
+}
+export declare function createTurnScratchDir(prefix: string, deps?: TurnScratchDeps): TurnScratchDir;
+//# sourceMappingURL=scratch-dir.d.ts.map

package/dist/lib/bot/runtime/scratch-dir.js

@@ -0,0 +1,41 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** Warn once per unwritable folder per bot process, not on every turn. */
+const warned = new Set();
+/** Errors that mean "this folder cannot be used"; anything else is rethrown. */
+const UNUSABLE = new Set(["EPERM", "EACCES", "ENOENT", "ENOTDIR", "EROFS"]);
+export function createTurnScratchDir(prefix, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const home = deps.home ?? os.homedir();
+    const warn = deps.warn ?? ((line) => process.stderr.write(`${line}\n`));
+    const configured = deps.tmpdir ?? os.tmpdir();
+    const fallbacks = [];
+    if (platform !== "win32")
+        fallbacks.push("/tmp");
+    fallbacks.push(path.join(home, ".hq", "tmp"));
+    let firstError;
+    for (const root of [configured, ...fallbacks.filter((f) => f !== configured)]) {
+        try {
+            if (root !== configured)
+                fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+            const dir = fs.mkdtempSync(path.join(root, prefix));
+            if (root === configured) {
+                warned.delete(configured);
+                return { dir };
+            }
+            if (!warned.has(configured))
+                warn(`hq bot: temp folder ${configured} is not writable (${firstError?.code ?? "error"}); using ${root} instead. Fix TMPDIR or run hq bot restart.`);
+            warned.add(configured);
+            return { dir, fallbackRoot: root };
+        }
+        catch (err) {
+            const e = err;
+            if (!e.code || !UNUSABLE.has(e.code))
+                throw err;
+            firstError ??= e;
+        }
+    }
+    throw new Error(`hq bot cannot create a temporary folder: ${configured} is not writable (${firstError?.code ?? "error"}), and ${fallbacks.join(" and ")} did not work either. Fix TMPDIR or run hq bot restart.`);
+}
+//# sourceMappingURL=scratch-dir.js.map

package/dist/lib/caller-principal.d.ts

@@ -0,0 +1,4 @@
+export declare function callerIsMachinePrincipal(env?: NodeJS.ProcessEnv): boolean;
+/** True when the token names an agent (agt_) or outpost (out_) identity. */
+export declare function tokenIsMachinePrincipal(token: string): boolean;
+//# sourceMappingURL=caller-principal.d.ts.map

package/dist/lib/caller-principal.js

@@ -0,0 +1,40 @@
+/**
+ * Whether the current caller is a machine principal (a local bot, an
+ * agent-kit agent, a hosted agent or an outpost) or a person login.
+ *
+ * The answer comes from the credentials the request will actually use, never
+ * from a user flag:
+ * - CLI sends go through `ensureCognitoToken()`, which picks machine tokens
+ *   exactly when `wantsMachineCognitoTokens()` is true (HQ_MACHINE_CREDS_FILE
+ *   set and valid, or the default machine creds file on a box with no person
+ *   session). This check reads local state only and makes no network call.
+ * - Callers that already hold a token (the agent-kit MCP tools) use
+ *   `tokenIsMachinePrincipal`, which reads the token's identity claims.
+ */
+import { wantsMachineCognitoTokens } from "../utils/machine-principal-state.js";
+import { peekIdToken } from "../utils/id-token.js";
+export function callerIsMachinePrincipal(env = process.env) {
+    try {
+        return wantsMachineCognitoTokens({}, env);
+    }
+    catch {
+        return false;
+    }
+}
+const MACHINE_ENTITY_TYPES = new Set(["agent", "outpost", "company-outpost"]);
+/** True when the token names an agent (agt_) or outpost (out_) identity. */
+export function tokenIsMachinePrincipal(token) {
+    let claims;
+    try {
+        claims = peekIdToken(token);
+    }
+    catch {
+        return false;
+    }
+    const type = claims["custom:entityType"];
+    if (typeof type === "string" && MACHINE_ENTITY_TYPES.has(type))
+        return true;
+    const uid = claims["custom:entityUid"];
+    return typeof uid === "string" && /^(agt|out)_/.test(uid);
+}
+//# sourceMappingURL=caller-principal.js.map

package/dist/lib/capacity/collectors/grok.js

@@ -192,7 +192,10 @@ export function mapGrokBillingBody(body, options) {
 export async function collectGrok(options = {}) {
     const ledger = ledgerOptions(options);
     const root = ledger.root ?? capacityRoot(ledger.env, ledger.home);
-    const scoped = { ...ledger, root };
+    // Forward the injected clock so ledger retention and now.json use the same
+    // instant as observedAt; otherwise retention runs on the wall clock and can
+    // delete readings this call just wrote.
+    const scoped = { ...ledger, root, now: options.now ?? ledger.now };
     if (readCollectorMark(scoped)?.enabled === false && !options.allowDisabled) {
         return { readings: [], failures: [], view: null, skipped: "disabled", accountId: null };
     }
@@ -474,7 +477,10 @@ function stampAccount(row, options, planType) {
 async function collectEnumeratedGrok(options) {
     const ledger = ledgerOptions(options);
     const root = ledger.root ?? capacityRoot(ledger.env, ledger.home);
-    const scoped = { ...ledger, root };
+    // Forward the injected clock so ledger retention and now.json use the same
+    // instant as observedAt; otherwise retention runs on the wall clock and can
+    // delete readings this call just wrote.
+    const scoped = { ...ledger, root, now: options.now ?? ledger.now };
     const clock = options.now ?? ledger.now ?? (() => new Date());
     const cliVersion = options.cliVersion ?? readInstalledGrokVersion(options.readVersion);
     const groups = new Map();

package/dist/lib/cli-flag-keys.d.ts

@@ -1,6 +1,8 @@
 /** hq-flags keys used by CLI-wide routes. */
 export declare const CLI_COMMAND_HELP_CATALOG_FLAG = "cli.command-help-catalog";
 export declare const MULTI_COMPANY_SESSION_LOCK_FLAG = "hooks.multi-company-session-lock";
+/** Kill switch (default on) for company-scoped `hq core rebuild-index` root indexes. */
+export declare const CORE_COMPANY_INDEX_SCOPE_FLAG = "cli.rebuild-index-company-scope";
 /**
  * hq-flags key for HQ Storage (`hq storage` and Settings > Storage in the
  * desktop app). Shared with hq-desktop-app, so it carries no `cli.` prefix,

package/dist/lib/cli-flag-keys.js

@@ -1,6 +1,8 @@
 /** hq-flags keys used by CLI-wide routes. */
 export const CLI_COMMAND_HELP_CATALOG_FLAG = "cli.command-help-catalog";
 export const MULTI_COMPANY_SESSION_LOCK_FLAG = "hooks.multi-company-session-lock";
+/** Kill switch (default on) for company-scoped `hq core rebuild-index` root indexes. */
+export const CORE_COMPANY_INDEX_SCOPE_FLAG = "cli.rebuild-index-company-scope";
 /**
  * hq-flags key for HQ Storage (`hq storage` and Settings > Storage in the
  * desktop app). Shared with hq-desktop-app, so it carries no `cli.` prefix,

package/dist/lib/daemon/catalog.js

@@ -185,7 +185,9 @@ function planService(service, ctx) {
                 return [unit];
             const core = base(service, {
                 id: "sync-core-canary",
-                description: "keeps one personal-vault canary in sync with sync-core",
+                description: ctx.syncCoreCanary.fullVault
+                    ? "keeps the personal vault in sync with sync-core"
+                    : "keeps one personal-vault canary in sync with sync-core",
                 command: ctx.syncCoreCanary.binaryPath
                     ? { type: "exec", file: ctx.syncCoreCanary.binaryPath, args: ["start", "--loop"] }
                     : null,
@@ -195,6 +197,7 @@ function planService(service, ctx) {
                     HQ_SYNC_PROTOCOL: "1",
                     ...(ctx.syncCoreCanary.vaultUid ? { HQ_SYNC_CANARY_VAULT: ctx.syncCoreCanary.vaultUid } : {}),
                     ...(ctx.syncCoreCanary.canaryPath ? { HQ_SYNC_CANARY_PATH: ctx.syncCoreCanary.canaryPath } : {}),
+                    ...(ctx.syncCoreCanary.fullVault ? { HQ_SYNC_FULL_VAULT: "1" } : {}),
                 },
                 heartbeatTimeoutMs: 180_000,
                 blocked: firstBlock([

package/dist/lib/daemon/sync-core-canary.d.ts

@@ -2,7 +2,10 @@ import type { SyncCoreCanaryConfig } from "./config.js";
 export interface SyncCoreCanaryPlan {
     binaryPath?: string;
     vaultUid?: string;
+    /** The one file the engine may change; absent when `fullVault` is set. */
     canaryPath?: string;
+    /** The engine applies every planned small file in the vault (`sync.full_vault = true`). */
+    fullVault?: boolean;
     blockedReason?: string;
 }
 export declare function inspectSyncCoreCanary(home: string, hqRoot: string | undefined, config: SyncCoreCanaryConfig, platform: NodeJS.Platform): SyncCoreCanaryPlan;

package/dist/lib/daemon/sync-core-canary.js

@@ -40,8 +40,13 @@ export function inspectSyncCoreCanary(home, hqRoot, config, platform) {
         return blocked(config, "the sync-core config must use the daemon's HQ folder");
     }
     const canaryPath = typeof sync.canary_path === "string" ? sync.canary_path.trim() : "";
-    if (!canaryPath)
-        return blocked(config, "the sync-core config must name one canary path");
+    const fullVault = sync.full_vault === true;
+    if (fullVault && canaryPath) {
+        return blocked(config, "the sync-core config must set either full_vault = true or canary_path, not both");
+    }
+    if (!fullVault && !canaryPath) {
+        return blocked(config, "the sync-core config must name one canary path or set full_vault = true");
+    }
     const ownedPath = path.join(home, ".hq", "sync-core", "owned", `${config.vaultUid}.json`);
     try {
         const owned = record(JSON.parse(fs.readFileSync(ownedPath, "utf8")));
@@ -51,6 +56,6 @@ export function inspectSyncCoreCanary(home, hqRoot, config, platform) {
     catch {
         return blocked(config, `the sync-core ownership record for ${config.vaultUid} is missing or invalid`);
     }
-    return { ...config, canaryPath };
+    return fullVault ? { ...config, fullVault: true } : { ...config, canaryPath };
 }
 //# sourceMappingURL=sync-core-canary.js.map

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

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

@@ -6,11 +6,15 @@
  * user customization and is left alone.
  */
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
+import { removeLinkOnly } from "../../../utils/safe-link.js";
 export const RELEASE_LINKS_FAMILY_ID = "release-links";
 export const RELEASE_LINKS_FAMILY_TITLE = "Release links";
 export const RELEASE_LINKS_CHECK_ID = "release-links.resolve";
-export const RELEASE_LINK_REMEDIATION = "Run `hq rescue -y` again. On Windows without Developer Mode, a directory link is written as a junction and a file link as a copy.";
+export 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 const DANGLING_RELEASE_LINK_PROBLEM = "does not resolve.";
 const CYGWIN_SYMLINK_COOKIE = Buffer.from("!<symlink>", "latin1");
 /** Paths git records as symlinks in the hq-core release. */
 export const RELEASE_LINKS = [
@@ -80,7 +84,11 @@ function releaseLinkProblem(hqRoot, entry) {
             resolved = fs.realpathSync.native(destination);
         }
         catch {
-            return "does not resolve. Its target is missing, often because an update linked it at a staging folder that was then deleted.";
+            const current = readlinkAbsOrNull(destination);
+            if (current !== null && !isRepairableDanglingTarget(hqRoot, current)) {
+                return `points at ${current}, which is missing and outside this HQ root. It is treated as your own link and left alone; fix or remove it yourself.`;
+            }
+            return `${DANGLING_RELEASE_LINK_PROBLEM} Its target is missing, often because an update linked it at a staging folder that was then deleted.`;
         }
         if (!pathIsInside(hqRoot, resolved)) {
             return "points outside this HQ root, so it does not resolve to the shipped target.";
@@ -108,6 +116,42 @@ function releaseLinkProblem(hqRoot, entry) {
     // A real directory in place of a directory link is a user replacement.
     return null;
 }
+function readlinkAbsOrNull(destination) {
+    try {
+        return path.resolve(path.dirname(destination), fs.readlinkSync(destination));
+    }
+    catch {
+        return null;
+    }
+}
+/** Prefix of the folder hq-cloud's rescue creates with mkdtemp. */
+const RESCUE_STAGING_SEGMENT_PREFIX = "hq-replace-rescue-";
+/**
+ * The rescue staging roots, mirroring hq-cloud's `resolveRescueStagingRoot`:
+ * the system temp folder, or `tmp` beside the backup root (`~/.hq/tmp`, or
+ * next to `$HQ_BACKUP_DIR`) when the temp folder is on another filesystem.
+ */
+function rescueStagingRoots(deps) {
+    const backupRoot = deps.backupRoot ?? process.env.HQ_BACKUP_DIR ?? path.join(os.homedir(), ".hq", "backups");
+    return [
+        ...tempRoots(deps.tmpDir ?? os.tmpdir()),
+        ...tempRoots(path.join(path.dirname(path.resolve(backupRoot)), "tmp")),
+    ];
+}
+/**
+ * A dangling link HQ may repair. Its current target is under the HQ root,
+ * under the system temp folder, under the rescue staging root beside the
+ * backup root, or has a path segment starting with `hq-replace-rescue-` (the
+ * rescue's mkdtemp folder, wherever it was staged). Anything else is the
+ * user's own link and is left alone.
+ */
+function isRepairableDanglingTarget(hqRoot, current, deps = {}) {
+    const segments = path.resolve(current).split(path.sep);
+    if (segments.some((segment) => segment.startsWith(RESCUE_STAGING_SEGMENT_PREFIX)))
+        return true;
+    const roots = [...tempRoots(path.resolve(hqRoot)), ...rescueStagingRoots(deps)];
+    return roots.some((root) => isUnder(root, current));
+}
 function containedTarget(hqRoot, entry) {
     const destination = path.join(hqRoot, entry.rel);
     const resolved = path.resolve(path.dirname(destination), entry.linkText);
@@ -149,4 +193,146 @@ function readFileOrNull(target) {
         return null;
     }
 }
+/**
+ * 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 function repairDanglingReleaseLinks(hqRoot, deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    let rootReal;
+    try {
+        rootReal = fs.realpathSync.native(path.resolve(hqRoot));
+    }
+    catch {
+        return [];
+    }
+    const repairs = [];
+    for (const entry of RELEASE_LINKS) {
+        if (deps.only !== undefined && entry.rel !== deps.only)
+            continue;
+        const destination = path.join(rootReal, entry.rel);
+        const lst = lstatOrNull(destination);
+        if (!lst || !lst.isSymbolicLink())
+            continue;
+        if (resolvesOrNull(destination) !== null)
+            continue;
+        const parentReal = resolvesOrNull(path.dirname(destination));
+        if (parentReal === null || !isUnder(rootReal, parentReal))
+            continue;
+        const target = path.resolve(path.dirname(destination), entry.linkText);
+        if (!isUnder(rootReal, target))
+            continue;
+        let current;
+        try {
+            current = path.resolve(path.dirname(destination), fs.readlinkSync(destination));
+        }
+        catch (err) {
+            repairs.push({ rel: entry.rel, action: "failed", reason: errorMessage(err) });
+            continue;
+        }
+        if (!isRepairableDanglingTarget(rootReal, current, { tmpDir: deps.tmpDir, backupRoot: deps.backupRoot })) {
+            repairs.push({
+                rel: entry.rel,
+                action: "skipped",
+                reason: `it points at ${current}, outside the HQ root, so it is left as your own link`,
+            });
+            continue;
+        }
+        const targetStat = statOrNull(target);
+        const targetUsable = targetStat !== null &&
+            (entry.kind === "dir" ? targetStat.isDirectory() : targetStat.isFile()) &&
+            isUnder(rootReal, resolvesOrNull(target) ?? "");
+        try {
+            removeLinkOnly(destination);
+            if (!targetUsable) {
+                repairs.push({ rel: entry.rel, action: "removed" });
+                continue;
+            }
+            const linkText = writeReleaseLink(entry, target, destination, platform);
+            repairs.push({ rel: entry.rel, action: "repointed", target, linkText });
+        }
+        catch (err) {
+            repairs.push({ rel: entry.rel, action: "failed", reason: errorMessage(err) });
+        }
+    }
+    return repairs;
+}
+/** Write the link and return the text it carries. */
+function writeReleaseLink(entry, target, destination, platform) {
+    if (platform !== "win32") {
+        fs.symlinkSync(entry.linkText, destination, entry.kind);
+        return entry.linkText;
+    }
+    if (entry.kind === "dir") {
+        fs.symlinkSync(target, destination, "junction");
+        return target;
+    }
+    try {
+        fs.symlinkSync(target, destination, "file");
+        return target;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "EPERM" && code !== "EACCES")
+            throw err;
+        // Windows without the symlink privilege: the check accepts a copy whose
+        // bytes equal the target.
+        fs.copyFileSync(target, destination);
+        return target;
+    }
+}
+function tempRoots(tmpDir) {
+    const roots = [path.resolve(tmpDir)];
+    const real = resolvesOrNull(tmpDir);
+    if (real && !roots.includes(real))
+        roots.push(real);
+    return roots;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function isUnder(rootReal, candidate) {
+    if (!candidate)
+        return false;
+    const abs = path.resolve(candidate);
+    const base = rootReal.endsWith(path.sep) ? rootReal.slice(0, -1) : rootReal;
+    return abs === base || abs.startsWith(base + path.sep);
+}
+function resolvesOrNull(target) {
+    try {
+        return fs.realpathSync.native(target);
+    }
+    catch {
+        return null;
+    }
+}
+function statOrNull(target) {
+    try {
+        return fs.statSync(target);
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=release-links.js.map