@indigoai-us/hq-cli 5.345.169 → 5.345.171

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

@@ -5,15 +5,16 @@
  * legacy units, the desktop app), so enabling a service, creating a bot, or
  * signing in takes effect without restarting the daemon.
  */
-import { type UnitPlan } from "./catalog.js";
+import { type PlanContext, type ServiceName, type UnitPlan } from "./catalog.js";
 import { type LegacyUnit } from "./legacy.js";
 import { type DaemonLockResult } from "./lock.js";
 import { type MachineType } from "./machine-type.js";
 import { type PickedHqCloud } from "./hq-cloud.js";
-import { type HostApp } from "./supervisor.js";
+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[];
 /** A bounded shutdown deadline that can account for sync push persistence. */
 export declare function createShutdownCap(): {
     promise: Promise<"timeout">;

package/dist/lib/daemon/run.js

@@ -22,6 +22,7 @@ import { 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 { assertPersonalServiceSessionCapability, readRemoteControlPoolsConfig, remoteControlPoolSecretsEnv, } from "./remote-control-pools.js";
 import { loadLanesConfig } from "../lanes/config.js";
 import { daemonLanesReconcileHandler } from "../lanes/daemon-reconcile.js";
@@ -54,7 +55,7 @@ import { stageHqChildBootstrap } from "./hq-child-bootstrap-stage.js";
 import { runnerSessionName } from "./remote-control.js";
 import { adoptChild, createChildTracker, finishSuccession, handoffEligible, readProcStart, stopOrphans, successionPaths, systemdKillMode, takeSuccession, writeHandoff, } from "./succession.js";
 import { listSyncRunnerProcesses, readWatchRunnerOwnerStatus, syncHeartbeatTimeoutMs, syncRunnerNodeOptions, watchRunnerOwnerStatusPath, } from "./sync-runner.js";
-import { STOP_ESCALATION_MS, SYNC_RUNNER_PERSIST_GRACE_MS, createSupervisor, } from "./supervisor.js";
+import { STOP_ESCALATION_MS, SYNC_RUNNER_PERSIST_GRACE_MS, createSupervisor, planKey, } from "./supervisor.js";
 import { userToolDirs } from "./tools.js";
 import { logOffset, readLogSince, readUnitHolds, writeUnitHolds } from "./unit-holds.js";
 import { daemonRunGuard } from "./lanes-reconcile-guard.js";
@@ -63,6 +64,19 @@ 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;
+export function planUnitsWithSyncCoreInterlock(services, context, supervisor) {
+    const syncCoreCanaryRunning = supervisor?.runningPlanKey("sync-core-canary") !== undefined;
+    const transitionContext = {
+        ...context,
+        syncCoreCanaryRunning,
+        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);
+    return planUnits(services, { ...transitionContext, legacySyncReadyForCore });
+}
 /** A bounded shutdown deadline that can account for sync push persistence. */
 export function createShutdownCap() {
     const startedAt = Date.now();
@@ -939,7 +953,7 @@ export async function runDaemon(opts) {
             legacy,
             appRunning: () => desktopAppRunning(platform),
         });
-        const plans = planUnits(services, {
+        const context = {
             machineType,
             platform,
             home,
@@ -964,6 +978,11 @@ export async function runDaemon(opts) {
                 return switches;
             })(),
             syncOwner,
+            syncCoreCanary: config.syncCoreCanaryError
+                ? { blockedReason: config.syncCoreCanaryError }
+                : config.syncCoreCanary
+                    ? inspectSyncCoreCanary(home, hqRoot, config.syncCoreCanary, platform)
+                    : undefined,
             desktopAppManagesSync: appManagesSync,
             syncRunnerProcesses,
             syncRunnerOwnerPid,
@@ -991,7 +1010,8 @@ export async function runDaemon(opts) {
             invalidPoolServiceSessions,
             availablePoolFrontends,
             unverifiablePoolFrontends,
-        });
+        };
+        const plans = planUnitsWithSyncCoreInterlock(services, context, supervisor);
         if (startupPlanOpen) {
             const replaceablePackageRoots = cliPackageRoot ? [cliPackageRoot] : [];
             if (hqCloud?.source === "bundled")

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

@@ -179,6 +179,7 @@ export interface Supervisor {
     stop(): Promise<void>;
     reconcile(): void;
     state(): DaemonState;
+    runningPlanKey(unitId: string): string | undefined;
     /** True while a live sync runner has reported that it is persisting pushes. */
     hasStoppingSyncRunner(): boolean;
     /** Stop supervising without signalling any child; returns the long-running units left running. */

package/dist/lib/daemon/supervisor.js

@@ -1399,6 +1399,10 @@ export function createSupervisor(deps) {
         },
         reconcile,
         state: snapshot,
+        runningPlanKey(unitId) {
+            const slot = slots.get(unitId);
+            return slot?.child ? slot.childKey : undefined;
+        },
         hasStoppingSyncRunner: () => [...liveOwners.values()].some(syncRunnerIsStopping),
         release() {
             const released = [];

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

@@ -0,0 +1,12 @@
+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;
+//# sourceMappingURL=sync-core-canary.d.ts.map

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

@@ -0,0 +1,61 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parse as parseToml } from "smol-toml";
+function blocked(config, blockedReason) {
+    return { ...config, blockedReason };
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function inspectSyncCoreCanary(home, hqRoot, config, platform) {
+    if (platform !== "darwin" && platform !== "linux") {
+        return blocked(config, "the sync-core canary requires macOS or Linux");
+    }
+    try {
+        if (!fs.statSync(config.binaryPath).isFile())
+            return blocked(config, "the sync-core binary is missing");
+        fs.accessSync(config.binaryPath, fs.constants.X_OK);
+    }
+    catch {
+        return blocked(config, "the sync-core binary is missing or not executable");
+    }
+    const configPath = path.join(home, ".hq", "sync-core", "config.toml");
+    let sync;
+    try {
+        sync = record(record(parseToml(fs.readFileSync(configPath, "utf8")))?.sync);
+    }
+    catch {
+        return blocked(config, `the sync-core config at ${configPath} is missing or invalid`);
+    }
+    if (sync?.engine !== "rust-test" || sync.mode !== "full") {
+        return blocked(config, "the sync-core config must select engine rust-test in full mode");
+    }
+    const vaults = sync.vaults;
+    if (!Array.isArray(vaults) || vaults.length !== 1 || vaults[0] !== config.vaultUid) {
+        return blocked(config, `the sync-core config must name exactly ${config.vaultUid}`);
+    }
+    if (!hqRoot || typeof sync.hq_root !== "string" || path.resolve(sync.hq_root) !== path.resolve(hqRoot)) {
+        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() : "";
+    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")));
+        if (owned?.vault !== config.vaultUid)
+            throw new Error("mismatch");
+    }
+    catch {
+        return blocked(config, `the sync-core ownership record for ${config.vaultUid} is missing or invalid`);
+    }
+    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

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

@@ -61,7 +61,39 @@ export interface SyncManifestUploadStatus {
     baseUsable: boolean;
     /** Local company slug for company-scoped remediation; absent for personal. */
     companySlug?: string;
+    /**
+     * Last failed pass, from hq-cloud >= 6.18.102 (`readManifestUploadStatus`,
+     * hq-cloud #1050). Fixed tokens only. Absent on older hq-cloud and after a
+     * later pass succeeded.
+     */
+    lastAttemptAt?: string;
+    consecutiveFailures?: number;
+    lastFailureReason?: string;
+    lastFailureKind?: string;
+    lastFailureStatus?: number;
 }
+/**
+ * The last failed pass for a stale scope, when hq-cloud recorded one after the
+ * last successful upload. Undefined means "no evidence a pass ran", which is
+ * the only case where "the daily audit pass is not running" is accurate.
+ */
+export declare function manifestLastFailure(entry: SyncManifestUploadStatus): {
+    reason: string;
+    status?: number;
+    attempts: number;
+    at: string;
+} | undefined;
+/**
+ * Failures a fresh `hq sync manifest` from this machine cannot clear: the
+ * upload route is not deployed (404 soft skip), the server rejected this
+ * identity, or it refused access (403). A 401 is not listed: it can be an
+ * expired token that a fresh run refreshes. Offering `--fix` for these only makes the
+ * health hook report the same row as "repair did not clear" every day.
+ */
+export declare function manifestFailureNotFixable(failure: {
+    reason: string;
+    status?: number;
+}): boolean;
 /** Injectable dependencies — defaults are the real collectors. */
 export interface SyncHealthDeps {
     /** Runner log and conflict signals; omitted in unit tests of other checks. */

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

@@ -52,6 +52,45 @@ const SYNC_FAMILY_TITLE = "Versions & sync";
 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");
+/** Failure tokens hq-cloud stores, restricted the same way hq-cloud reads them. */
+const MANIFEST_FAILURE_TOKEN = /^[a-z][a-z0-9_]{0,39}$/;
+/**
+ * The last failed pass for a stale scope, when hq-cloud recorded one after the
+ * last successful upload. Undefined means "no evidence a pass ran", which is
+ * the only case where "the daily audit pass is not running" is accurate.
+ */
+export function manifestLastFailure(entry) {
+    const reason = entry.lastFailureReason;
+    const at = entry.lastAttemptAt;
+    if (!reason || !MANIFEST_FAILURE_TOKEN.test(reason) || !at)
+        return undefined;
+    const attempts = entry.consecutiveFailures ?? 0;
+    if (!Number.isFinite(attempts) || attempts < 1)
+        return undefined;
+    const atMs = Date.parse(at);
+    if (!Number.isFinite(atMs))
+        return undefined;
+    const uploadedMs = entry.lastUploadAt ? Date.parse(entry.lastUploadAt) : Number.NaN;
+    if (Number.isFinite(uploadedMs) && atMs <= uploadedMs)
+        return undefined;
+    const status = typeof entry.lastFailureStatus === "number" && Number.isInteger(entry.lastFailureStatus)
+        ? entry.lastFailureStatus
+        : undefined;
+    return { reason, attempts: Math.floor(attempts), at, ...(status !== undefined ? { status } : {}) };
+}
+/**
+ * Failures a fresh `hq sync manifest` from this machine cannot clear: the
+ * upload route is not deployed (404 soft skip), the server rejected this
+ * identity, or it refused access (403). A 401 is not listed: it can be an
+ * expired token that a fresh run refreshes. Offering `--fix` for these only makes the
+ * health hook report the same row as "repair did not clear" every day.
+ */
+export function manifestFailureNotFixable(failure) {
+    if (failure.reason === "soft_skip" || failure.reason === "rejected_identity")
+        return true;
+    // 401 is left fixable: an expired token is refreshed by the next run.
+    return failure.status === 403 || failure.status === 404;
+}
 /** Fill in the optional dependencies so call sites never branch on undefined. */
 function withDefaults(deps, hqRoot) {
     return {
@@ -782,7 +821,21 @@ function manifestResults(deps, journals) {
                 }
             }
             const command = `hq sync manifest${scope ? ` --scope ${scope}` : ""}`;
-            const message = `Scope '${entry.scopeKey}' last uploaded a sync manifest ${days} day${days === 1 ? "" : "s"} ago (${entry.lastUploadAt}) — the daily audit pass is not running.`;
+            const failure = manifestLastFailure(entry);
+            const age = `Scope '${entry.scopeKey}' last uploaded a sync manifest ${days} day${days === 1 ? "" : "s"} ago (${entry.lastUploadAt})`;
+            // A pass that ran and failed is not "not running": name the stored reason.
+            const message = failure
+                ? `${age}. The last pass (${failure.at}) failed with ${failure.reason}${failure.status !== undefined ? ` (HTTP ${failure.status})` : ""}, ${failure.attempts} failed pass${failure.attempts === 1 ? "" : "es"} in a row.`
+                : `${age} — the daily audit pass is not running.`;
+            if (failure && manifestFailureNotFixable(failure)) {
+                return {
+                    status: "WARN",
+                    checkId,
+                    reasonCode: "manifest-upload-rejected",
+                    message,
+                    remediation: `--fix cannot clear this from this machine. Check you are signed in to the right HQ account (/hq-whoami), then run \`${command}\` and read its error.`,
+                };
+            }
             // With the kill switch set the upload exits 0 and sends nothing, so the
             // row carries no `--fix` target and names the switch instead.
             if (deps.manifestUploadsDisabled()) {

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

@@ -157,8 +157,13 @@ export interface RefreshManifestTarget {
 }
 /** Outcome of one {@link ApplyFixesOptions.refreshManifest} call. */
 export interface RefreshManifestResult {
-    /** Whether the upload command exited 0. The re-check is the real verdict. */
+    /**
+     * Whether the upload command exited 0 and, when it printed a `--json`
+     * outcome, that outcome was `uploaded`. The re-check is the real verdict.
+     */
     ok: boolean;
+    /** The `hq sync manifest --json` status token, when the pass did not upload. */
+    passStatus?: string;
     /** One-line summary. */
     message: string;
     /**
@@ -333,11 +338,28 @@ export interface RefreshSyncSpawnDeps {
 export declare const REFRESH_SYNC_LOCK_TIMEOUT_SEC = 30;
 /**
  * Default `refresh-manifest` repair: a bounded `hq sync manifest --scope <s>`
- * against the tree `--fix` is repairing. Exit 0 also covers throttled,
- * disabled, and skipped passes, so the post-fix re-check decides whether the
- * row cleared. A timeout or non-zero exit is reported, not thrown.
+ * against the tree `--fix` is repairing, with `--json` so a pass that exits 0
+ * without uploading (soft_skipped, throttled, disabled, locked,
+ * resend_full_scheduled) is reported as not uploaded. A `resend_full` answer
+ * is retried once with `--full`. The post-fix re-check still decides whether
+ * the row cleared. A timeout or non-zero exit is reported, not thrown.
  */
 export declare function defaultRefreshManifest(target: RefreshManifestTarget): Promise<RefreshManifestResult>;
+type ManifestSpawnResult = Pick<SpawnSyncReturns<string>, "error" | "status" | "signal"> & Partial<Pick<SpawnSyncReturns<string>, "stdout" | "stderr">>;
+/**
+ * Run one upload and, when the server answered `resend_full` (it dropped or
+ * refused the delta base), run it once more with `--full`. Without the retry
+ * the scope stays stale until the next day's --fix run, and the health hook
+ * reports it as unrepaired in between (feedback_84d7a862).
+ */
+export declare function refreshManifestWithRetry(scope: string, run: (full: boolean, json: boolean) => ManifestSpawnResult): RefreshManifestResult;
+/** Commander's rejection of `--json` by a binary that predates it. */
+export declare function manifestJsonUnsupported(result: ManifestSpawnResult): boolean;
+/**
+ * The status token from the `hq sync manifest --json` line, or undefined when
+ * the output has none (an older binary, or a pass that printed only a summary).
+ */
+export declare function manifestPassStatus(stdout: string | undefined): string | undefined;
 /**
  * Map one `hq sync manifest` spawn result to a {@link RefreshManifestResult}.
  * A spawn killed by the timeout has a null status, so it is reported as a