@indigoai-us/hq-cli 5.108.3 → 5.108.5

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [5.108.5] — 2026-09-04
+
+### Added
+
+- `hq meetings import <file>` imports normalized historical meeting transcripts
+  through HQ's managed source pipeline, with immutable idempotent replay and
+  explicit conflict detection when an external source ID is reused with
+  different content.
+
+## [5.108.4] — 2026-09-04
+
+### Fixed
+
+- Mesh daemon presence reconnect backoff no longer shrinks between failures:
+  consecutive errors grow the delay monotonically (full jitter floored at the
+  previous delay) up to the 60 s cap, and the attempt counter resets only after
+  a successful MQTT connect. Server refusals (`404 FEATURE_DISABLED`,
+  `409 REALTIME_CONTRACT_UNSUPPORTED`, and `403`) use a long retry of 10
+  minutes ±20% jitter (override with `HQ_MESH_DAEMON_REFUSED_RETRY_MS`; a
+  `Retry-After` header wins), log one line per refusal episode, and surface the
+  refused state plus next retry time on `hq mesh daemon doctor` and
+  `hq mesh daemon status`.
+
+### Changed
+
+- Clarification: hq-core hooks from the matching Work Mesh Live release require
+  hq-cli **5.108.2** or newer (spool enqueue format and flush semantics). The
+  5.108.2 release notes incorrectly said 5.109.0.
+
 ## [5.108.3] — 2026-09-04
 
 ## [5.108.2] — 2026-09-04

package/dist/commands/meetings.js

@@ -1,6 +1,7 @@
 import chalk from "chalk";
+import { readFile } from "node:fs/promises";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { vaultApiFetch, getCompanyUid, resolveCallerPersonUid, } from "../utils/vault-api.js";
 function formatDuration(seconds) {
     const h = Math.floor(seconds / 3600);
     const m = Math.floor((seconds % 3600) / 60);
@@ -216,6 +217,59 @@ export function registerMeetingsCommand(program) {
         }
     });
     // ── hq meetings invite <meeting-url> ──────────────────────────────
+    meetings
+        .command("import <file>")
+        .description("Import a normalized historical transcript JSON file")
+        .action(async (file) => {
+        try {
+            const companySlug = meetings.opts().company;
+            if (!companySlug) {
+                throw new Error("--company <slug> is required for historical imports");
+            }
+            const bytes = await readFile(file);
+            if (bytes.byteLength > 5 * 1024 * 1024) {
+                throw new Error("Historical meeting import exceeds 5 MiB");
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(bytes.toString("utf8"));
+            }
+            catch {
+                throw new Error("Historical meeting import file must contain valid JSON");
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error("Historical meeting import file must contain a JSON object");
+            }
+            const token = await ensureCognitoToken();
+            const companyId = await getCompanyUid(token, companySlug);
+            const recorderPersonUid = await resolveCallerPersonUid(token);
+            const res = await vaultApiFetch({
+                token,
+                method: "POST",
+                path: "/v1/meetings/import",
+                body: {
+                    ...parsed,
+                    companyId,
+                    recorderPersonUid,
+                },
+            });
+            if (!res.ok)
+                await handleApiError(res, meetings.opts().json);
+            const result = (await res.json());
+            if (meetings.opts().json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(chalk.green(`\n✓ Historical meeting ${result.outcome}: ${result.meetingId}`));
+            if (result.state)
+                console.log(chalk.dim(`  State: ${result.state}`));
+            console.log();
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
     meetings
         .command("invite <meetingUrl>")
         .description("Invite the meeting bot to a Google Meet, Zoom, or Teams URL")

package/dist/commands/mesh.js

@@ -18,7 +18,7 @@ import { CLI_KIND_TO_SCHEMA, EnqueueValidationError, enqueueSessionEvent, } from
 import { flushSessionEvents } from "../lib/mesh/live/flush.js";
 import { createSessionEventsPoster, resolveVaultApiBase, } from "../lib/mesh/live/session-events-client.js";
 import { workMeshRoot } from "../lib/mesh/live/paths.js";
-import { buildInstallPaths, collectDaemonDoctor, daemonServiceStatus, detectPlatform, formatDaemonDoctor, installDaemonService, runMeshDaemon, uninstallDaemonService, } from "../lib/mesh/live/daemon/index.js";
+import { buildInstallPaths, collectDaemonDoctor, daemonServiceStatus, detectPlatform, formatDaemonDoctor, installDaemonService, readDaemonState, runMeshDaemon, uninstallDaemonService, daemonDir, } from "../lib/mesh/live/daemon/index.js";
 import { workContextRoot } from "../lib/work-context/paths.js";
 import { formatMigrateConfirmation, submitSessionMigration, } from "../lib/work-context/migrate.js";
 import { formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, submitOrganizeDecision, } from "../lib/work-context/organize.js";
@@ -873,6 +873,8 @@ async function runDaemonStatus(opts) {
         platform: detectPlatform(),
         paths: buildInstallPaths({}),
     });
+    const state = readDaemonState(daemonDir());
+    const presenceRefusal = state?.presenceRefusal ?? null;
     if (opts.json) {
         console.log(JSON.stringify({
             ok: true,
@@ -881,10 +883,18 @@ async function runDaemonStatus(opts) {
             running: result.running ?? false,
             dest: result.dest,
             message: result.message,
+            mqttState: state?.mqttState,
+            presenceRefusal,
         }, null, 2));
         return;
     }
     console.log(result.message);
+    if (presenceRefusal) {
+        console.log(`presence refusal: ${presenceRefusal.code} (HTTP ${presenceRefusal.status}); next retry at ${presenceRefusal.nextRetryAt}`);
+    }
+    else if (state?.mqttState) {
+        console.log(`mqtt: ${state.mqttState}`);
+    }
 }
 async function runDaemonDoctorCmd(opts) {
     const report = collectDaemonDoctor();

package/dist/lib/mesh/live/daemon/credentials.d.ts

@@ -8,6 +8,43 @@ export declare const MQTT_KEEPALIVE_SECONDS = 15;
 /** Renew at 80% of credential lifetime. */
 export declare const CREDENTIAL_RENEWAL_FRACTION = 0.8;
 export declare const MIN_RENEWAL_DELAY_MS = 5000;
+/** Long retry when the server refuses credentials (disabled / unsupported). */
+export declare const DEFAULT_REFUSED_RETRY_MS: number;
+export declare const REFUSED_RETRY_ENV = "HQ_MESH_DAEMON_REFUSED_RETRY_MS";
+/**
+ * Node's setTimeout treats delays above this as ~1ms (signed 32-bit overflow).
+ * Always schedule long waits via {@link scheduleBoundedTimeout}.
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** Cap any single retry so a bogus Retry-After cannot park the daemon. */
+export declare const MAX_RETRY_DELAY_MS: number;
+export type CredentialVendFailureKind = "refused" | "transient";
+/**
+ * Typed vend failure. `refused` = server will not vend right now
+ * (FEATURE_DISABLED / REALTIME_CONTRACT_UNSUPPORTED / 403); daemon should
+ * wait a long interval instead of the short network backoff.
+ */
+export declare class CredentialVendError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly kind: CredentialVendFailureKind;
+    readonly retryAfterMs: number | undefined;
+    constructor(input: {
+        status: number;
+        code?: string;
+        kind: CredentialVendFailureKind;
+        retryAfterMs?: number;
+        message?: string;
+    });
+}
+export declare function parseRetryAfterMs(value: string | null | undefined, nowMs?: number): number | undefined;
+export declare function extractVendErrorCode(body: unknown): string | undefined;
+/** True for server "not now" responses that should use the long retry. */
+export declare function isCredentialVendRefused(status: number, code: string | undefined): boolean;
+export declare function classifyCredentialVendFailure(status: number, body: unknown, retryAfterHeader?: string | null, nowMs?: number): CredentialVendError;
+export declare function defaultRefusedRetryMs(env?: NodeJS.ProcessEnv): number;
+/** ±20% jitter around the refused-retry base interval. */
+export declare function refusedRetryDelayMs(baseMs: number, random: () => number): number;
 export interface PresenceCompany {
     companyUid: string;
     presenceTopic: string;
@@ -31,6 +68,22 @@ export interface TimerHost {
     now(): number;
 }
 export declare const realTimerHost: TimerHost;
+/** Clamp a retry delay to [0, MAX_RETRY_DELAY_MS]. */
+export declare function clampRetryDelayMs(delayMs: number): number;
+export interface BoundedTimeoutHandle {
+    clear(): void;
+    /** Absolute epoch-ms deadline this schedule is aiming for. */
+    deadlineMs: number;
+}
+/**
+ * Schedule `fn` after `delayMs`, chaining timers in chunks of at most
+ * `maxChunkMs` so the absolute deadline is preserved under Node's timeout cap.
+ *
+ * Remaining time is tracked by subtracting each armed chunk (so frozen test
+ * clocks still advance the chain) and also clamped to the wall-clock deadline
+ * when `timers.now()` moves forward.
+ */
+export declare function scheduleBoundedTimeout(timers: TimerHost, fn: () => void, delayMs: number, maxChunkMs?: number): BoundedTimeoutHandle;
 export declare function renewalDelayMs(nowMs: number, expirationIso: string): number;
 export declare function normalizeContract3Bundle(raw: unknown): Contract3Bundle;
 /**
@@ -40,16 +93,24 @@ export declare function normalizeContract3Bundle(raw: unknown): Contract3Bundle;
  * No identity file → return the bundle unchanged (person laptop).
  */
 export declare function scopeBundleToAgentIdentity(bundle: Contract3Bundle, env?: NodeJS.ProcessEnv): Contract3Bundle;
+export type CredentialVendPostResult = {
+    status: number;
+    body: unknown;
+    /** Optional header map or Fetch Headers; used for Retry-After. */
+    headers?: Headers | Record<string, string | undefined | null>;
+};
 export declare function createContract3Fetcher(opts: {
     token: string;
     baseUrl?: string;
-    post?: (path: string, body: unknown) => Promise<{
-        status: number;
-        body: unknown;
-    }>;
+    post?: (path: string, body: unknown) => Promise<CredentialVendPostResult>;
     /** Process env for identity-file scoping (tests). */
     env?: NodeJS.ProcessEnv;
 }): CredentialsFetcher;
+export interface CredentialRenewalErrorInfo {
+    /** Absolute ISO timestamp when the renewal retry is scheduled to fire. */
+    nextRetryAt: string;
+    delayMs: number;
+}
 /**
  * Proactive renewal: at 80% of lifetime, fetch fresh creds and call onRenewed.
  * Does not drop the connection itself — caller reconnects with the new URL.
@@ -60,9 +121,11 @@ export declare class CredentialRenewalManager {
     private readonly onError;
     private readonly timers;
     private readonly retryDelayMs;
+    private readonly refusedRetryMs;
+    private readonly random;
     private handle;
     private stopped;
-    constructor(fetchCredentials: CredentialsFetcher, onRenewed: (bundle: Contract3Bundle) => void, onError?: (err: unknown) => void, timers?: TimerHost, retryDelayMs?: number);
+    constructor(fetchCredentials: CredentialsFetcher, onRenewed: (bundle: Contract3Bundle) => void, onError?: (err: unknown, info?: CredentialRenewalErrorInfo) => void, timers?: TimerHost, retryDelayMs?: number, refusedRetryMs?: number, random?: () => number);
     schedule(bundle: Contract3Bundle): void;
     private renew;
     stop(): void;

package/dist/lib/mesh/live/daemon/credentials.js

@@ -10,11 +10,146 @@ export const MQTT_KEEPALIVE_SECONDS = 15;
 /** Renew at 80% of credential lifetime. */
 export const CREDENTIAL_RENEWAL_FRACTION = 0.8;
 export const MIN_RENEWAL_DELAY_MS = 5_000;
+/** Long retry when the server refuses credentials (disabled / unsupported). */
+export const DEFAULT_REFUSED_RETRY_MS = 10 * 60_000;
+export const REFUSED_RETRY_ENV = "HQ_MESH_DAEMON_REFUSED_RETRY_MS";
+/**
+ * Node's setTimeout treats delays above this as ~1ms (signed 32-bit overflow).
+ * Always schedule long waits via {@link scheduleBoundedTimeout}.
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Cap any single retry so a bogus Retry-After cannot park the daemon. */
+export const MAX_RETRY_DELAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Typed vend failure. `refused` = server will not vend right now
+ * (FEATURE_DISABLED / REALTIME_CONTRACT_UNSUPPORTED / 403); daemon should
+ * wait a long interval instead of the short network backoff.
+ */
+export class CredentialVendError extends Error {
+    status;
+    code;
+    kind;
+    retryAfterMs;
+    constructor(input) {
+        const codePart = input.code ? ` ${input.code}` : "";
+        super(input.message ?? `credential vend failed: HTTP ${input.status}${codePart}`);
+        this.name = "CredentialVendError";
+        this.status = input.status;
+        this.code = input.code;
+        this.kind = input.kind;
+        this.retryAfterMs = input.retryAfterMs;
+    }
+}
+export function parseRetryAfterMs(value, nowMs = Date.now()) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.round(seconds * 1000);
+    }
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - nowMs);
+    }
+    return undefined;
+}
+export function extractVendErrorCode(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return undefined;
+    const code = body.code;
+    return typeof code === "string" && code.trim() ? code.trim() : undefined;
+}
+/** True for server "not now" responses that should use the long retry. */
+export function isCredentialVendRefused(status, code) {
+    if (status === 403)
+        return true;
+    if (status === 404 && code === "FEATURE_DISABLED")
+        return true;
+    if (status === 409 && code === "REALTIME_CONTRACT_UNSUPPORTED")
+        return true;
+    return false;
+}
+export function classifyCredentialVendFailure(status, body, retryAfterHeader, nowMs) {
+    const code = extractVendErrorCode(body);
+    const retryAfterMs = parseRetryAfterMs(retryAfterHeader, nowMs);
+    const kind = isCredentialVendRefused(status, code)
+        ? "refused"
+        : "transient";
+    return new CredentialVendError({ status, code, kind, retryAfterMs });
+}
+export function defaultRefusedRetryMs(env = process.env) {
+    const raw = env[REFUSED_RETRY_ENV]?.trim();
+    if (raw) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    return DEFAULT_REFUSED_RETRY_MS;
+}
+/** ±20% jitter around the refused-retry base interval. */
+export function refusedRetryDelayMs(baseMs, random) {
+    const unit = Math.max(0, baseMs);
+    return Math.round(unit * (0.8 + random() * 0.4));
+}
 export const realTimerHost = {
     setTimeout: (fn, ms) => setTimeout(fn, ms),
     clearTimeout: (h) => clearTimeout(h),
     now: () => Date.now(),
 };
+/** Clamp a retry delay to [0, MAX_RETRY_DELAY_MS]. */
+export function clampRetryDelayMs(delayMs) {
+    if (!Number.isFinite(delayMs) || delayMs <= 0)
+        return 0;
+    return Math.min(Math.floor(delayMs), MAX_RETRY_DELAY_MS);
+}
+/**
+ * Schedule `fn` after `delayMs`, chaining timers in chunks of at most
+ * `maxChunkMs` so the absolute deadline is preserved under Node's timeout cap.
+ *
+ * Remaining time is tracked by subtracting each armed chunk (so frozen test
+ * clocks still advance the chain) and also clamped to the wall-clock deadline
+ * when `timers.now()` moves forward.
+ */
+export function scheduleBoundedTimeout(timers, fn, delayMs, maxChunkMs = MAX_TIMER_DELAY_MS) {
+    let handle = null;
+    let cancelled = false;
+    const safeDelay = Math.max(0, Number.isFinite(delayMs) ? delayMs : 0);
+    const chunkLimit = Math.max(1, Math.min(maxChunkMs, MAX_TIMER_DELAY_MS));
+    const deadlineMs = timers.now() + safeDelay;
+    let remainingMs = safeDelay;
+    const arm = () => {
+        const chunk = Math.min(remainingMs, chunkLimit);
+        handle = timers.setTimeout(() => {
+            handle = null;
+            if (cancelled)
+                return;
+            remainingMs -= chunk;
+            const byClock = deadlineMs - timers.now();
+            if (byClock < remainingMs) {
+                remainingMs = Math.max(0, byClock);
+            }
+            if (remainingMs <= 0) {
+                fn();
+                return;
+            }
+            arm();
+        }, chunk);
+    };
+    arm();
+    return {
+        deadlineMs,
+        clear() {
+            cancelled = true;
+            if (handle !== null) {
+                timers.clearTimeout(handle);
+                handle = null;
+            }
+        },
+    };
+}
 export function renewalDelayMs(nowMs, expirationIso) {
     const expMs = Date.parse(expirationIso);
     if (Number.isNaN(expMs))
@@ -131,6 +266,16 @@ export function scopeBundleToAgentIdentity(bundle, env = process.env) {
     }
     return { ...bundle, companies: matched };
 }
+function headerGet(headers, name) {
+    if (!headers)
+        return null;
+    if (typeof headers.get === "function") {
+        return headers.get(name);
+    }
+    const rec = headers;
+    const direct = rec[name] ?? rec[name.toLowerCase()];
+    return direct == null ? null : String(direct);
+}
 export function createContract3Fetcher(opts) {
     return async () => {
         let bundle;
@@ -139,7 +284,7 @@ export function createContract3Fetcher(opts) {
                 contractVersion: 3,
             });
             if (res.status < 200 || res.status >= 300) {
-                throw new Error(`credential vend failed: HTTP ${res.status}`);
+                throw classifyCredentialVendFailure(res.status, res.body, headerGet(res.headers, "Retry-After"));
             }
             bundle = normalizeContract3Bundle(res.body);
         }
@@ -162,7 +307,7 @@ export function createContract3Fetcher(opts) {
                 }
             }
             if (!res.ok) {
-                throw new Error(`credential vend failed: HTTP ${res.status}`);
+                throw classifyCredentialVendFailure(res.status, body, res.headers.get("Retry-After"));
             }
             bundle = normalizeContract3Bundle(body);
         }
@@ -179,21 +324,25 @@ export class CredentialRenewalManager {
     onError;
     timers;
     retryDelayMs;
+    refusedRetryMs;
+    random;
     handle = null;
     stopped = false;
-    constructor(fetchCredentials, onRenewed, onError = () => { }, timers = realTimerHost, retryDelayMs = 30_000) {
+    constructor(fetchCredentials, onRenewed, onError = () => { }, timers = realTimerHost, retryDelayMs = 30_000, refusedRetryMs = DEFAULT_REFUSED_RETRY_MS, random = Math.random) {
         this.fetchCredentials = fetchCredentials;
         this.onRenewed = onRenewed;
         this.onError = onError;
         this.timers = timers;
         this.retryDelayMs = retryDelayMs;
+        this.refusedRetryMs = refusedRetryMs;
+        this.random = random;
     }
     schedule(bundle) {
         if (this.stopped)
             return;
         this.clear();
         const delay = renewalDelayMs(this.timers.now(), bundle.expiresAt);
-        this.handle = this.timers.setTimeout(() => void this.renew(), delay);
+        this.handle = scheduleBoundedTimeout(this.timers, () => void this.renew(), delay);
     }
     async renew() {
         if (this.stopped)
@@ -206,11 +355,23 @@ export class CredentialRenewalManager {
             this.schedule(bundle);
         }
         catch (err) {
-            this.onError(err);
             if (this.stopped)
                 return;
             this.clear();
-            this.handle = this.timers.setTimeout(() => void this.renew(), this.retryDelayMs);
+            let delay = this.retryDelayMs;
+            if (err instanceof CredentialVendError && err.kind === "refused") {
+                delay =
+                    err.retryAfterMs !== undefined
+                        ? Math.max(0, err.retryAfterMs)
+                        : refusedRetryDelayMs(this.refusedRetryMs, this.random);
+                delay = clampRetryDelayMs(delay);
+            }
+            const nextRetryAt = new Date(this.timers.now() + delay).toISOString();
+            // Notify with the real deadline before arming so noteRefusal records it.
+            this.onError(err, { nextRetryAt, delayMs: delay });
+            if (this.stopped)
+                return;
+            this.handle = scheduleBoundedTimeout(this.timers, () => void this.renew(), delay);
         }
     }
     stop() {
@@ -219,7 +380,7 @@ export class CredentialRenewalManager {
     }
     clear() {
         if (this.handle !== null) {
-            this.timers.clearTimeout(this.handle);
+            this.handle.clear();
             this.handle = null;
         }
     }

package/dist/lib/mesh/live/daemon/doctor.d.ts

@@ -23,6 +23,8 @@ export interface DaemonDoctorReport {
     tokenSource: CognitoTokenSource;
     /** human | agent | unknown — from token claims / machine signal. */
     actorKind: CognitoActorKind;
+    /** Credential vend refused (disabled / unsupported / 403). */
+    presenceRefusal?: DaemonStateFile["presenceRefusal"];
 }
 export interface DaemonDoctorDeps {
     home?: string;

package/dist/lib/mesh/live/daemon/doctor.js

@@ -91,6 +91,10 @@ export function collectDaemonDoctor(deps = {}) {
     if (deadLetterCount > 0) {
         unhealthyReasons.push(`dead-letter count=${deadLetterCount}`);
     }
+    const presenceRefusal = state?.presenceRefusal ?? null;
+    if (presenceRefusal) {
+        unhealthyReasons.push(`presence credential refused (${presenceRefusal.code}); next retry ${presenceRefusal.nextRetryAt}`);
+    }
     const auth = describeCognitoTokenSource({ home, env });
     return {
         running,
@@ -108,6 +112,7 @@ export function collectDaemonDoctor(deps = {}) {
         oldestSpoolAgeMs,
         tokenSource: auth.tokenSource,
         actorKind: auth.actorKind,
+        presenceRefusal,
     };
 }
 export function formatDaemonDoctor(report) {
@@ -125,6 +130,9 @@ export function formatDaemonDoctor(report) {
             ? ` ok=${report.lastFlushResult.ok} posted=${report.lastFlushResult.posted}`
             : ""}`,
     ];
+    if (report.presenceRefusal) {
+        lines.push(`presence refusal: ${report.presenceRefusal.code} (HTTP ${report.presenceRefusal.status}); next retry at ${report.presenceRefusal.nextRetryAt}`);
+    }
     if (report.unhealthy) {
         lines.push(`health: UNHEALTHY`);
         for (const reason of report.unhealthyReasons) {

package/dist/lib/mesh/live/daemon/index.d.ts

@@ -1,14 +1,14 @@
 export { DAEMON_DIRNAME, DAEMON_LOG_MAX_BYTES, DAEMON_LOG_NAME, DAEMON_PID_NAME, DAEMON_STATE_NAME, LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, daemonDir, daemonLogPath, daemonPidPath, daemonStatePath, sessionBoardPath, } from "./paths.js";
 export { acquirePidLock, defaultPidLockDeps, parsePidLock, pidLockStatus, readPidLock, releasePidLock, resolveDaemonDir, } from "./pid-lock.js";
 export type { PidLockDeps, PidLockRecord, PidLockResult } from "./pid-lock.js";
-export { CREDENTIAL_RENEWAL_FRACTION, MQTT_KEEPALIVE_SECONDS, REALTIME_CREDENTIALS_PATH, CredentialRenewalManager, createContract3Fetcher, normalizeContract3Bundle, realTimerHost, renewalDelayMs, } from "./credentials.js";
-export type { Contract3Bundle, CredentialsFetcher, PresenceCompany, TimerHost, } from "./credentials.js";
+export { CREDENTIAL_RENEWAL_FRACTION, DEFAULT_REFUSED_RETRY_MS, MAX_RETRY_DELAY_MS, MAX_TIMER_DELAY_MS, MQTT_KEEPALIVE_SECONDS, REALTIME_CREDENTIALS_PATH, REFUSED_RETRY_ENV, CredentialRenewalManager, CredentialVendError, classifyCredentialVendFailure, clampRetryDelayMs, createContract3Fetcher, defaultRefusedRetryMs, extractVendErrorCode, isCredentialVendRefused, normalizeContract3Bundle, parseRetryAfterMs, realTimerHost, refusedRetryDelayMs, renewalDelayMs, scheduleBoundedTimeout, } from "./credentials.js";
+export type { BoundedTimeoutHandle, Contract3Bundle, CredentialRenewalErrorInfo, CredentialVendFailureKind, CredentialVendPostResult, CredentialsFetcher, PresenceCompany, TimerHost, } from "./credentials.js";
 export { amzDateOf, hex, presignIotWssUrl, rfc3986Encode } from "./presign.js";
 export type { IotCredentials } from "./presign.js";
 export { PresenceClient, backoffDelayMs, buildPresencePayload, defaultMqttConnect, isOwnPresenceTopic, } from "./presence.js";
-export type { MeshMqttClientLike, MqttConnectFn, MqttConnectionState, PresenceClientOptions, PresencePayload, } from "./presence.js";
+export type { MeshMqttClientLike, MqttConnectFn, MqttConnectionState, PresenceClientOptions, PresencePayload, PresenceRefusal, } from "./presence.js";
 export { defaultDaemonState, patchDaemonState, readDaemonState, writeDaemonState, } from "./state.js";
-export type { DaemonStateFile } from "./state.js";
+export type { DaemonStateFile, PresenceRefusalState } from "./state.js";
 export { appendDaemonLog, daemonLogLine, ensureDaemonLog, resolveDaemonAssetDir, rotateDaemonLogIfNeeded, } from "./log.js";
 export { BOARD_REFRESH_INTERVAL_MS, createVaultBoardReader, formatBoardMarkdown, refreshBoundSessionBoards, writeBoardMarkdown, } from "./board-refresh.js";
 export type { BoardReader, BoardRefreshDeps, BoardStorySnapshot } from "./board-refresh.js";

package/dist/lib/mesh/live/daemon/index.js

@@ -1,6 +1,6 @@
 export { DAEMON_DIRNAME, DAEMON_LOG_MAX_BYTES, DAEMON_LOG_NAME, DAEMON_PID_NAME, DAEMON_STATE_NAME, LAUNCHD_LABEL, SYSTEMD_UNIT_NAME, daemonDir, daemonLogPath, daemonPidPath, daemonStatePath, sessionBoardPath, } from "./paths.js";
 export { acquirePidLock, defaultPidLockDeps, parsePidLock, pidLockStatus, readPidLock, releasePidLock, resolveDaemonDir, } from "./pid-lock.js";
-export { CREDENTIAL_RENEWAL_FRACTION, MQTT_KEEPALIVE_SECONDS, REALTIME_CREDENTIALS_PATH, CredentialRenewalManager, createContract3Fetcher, normalizeContract3Bundle, realTimerHost, renewalDelayMs, } from "./credentials.js";
+export { CREDENTIAL_RENEWAL_FRACTION, DEFAULT_REFUSED_RETRY_MS, MAX_RETRY_DELAY_MS, MAX_TIMER_DELAY_MS, MQTT_KEEPALIVE_SECONDS, REALTIME_CREDENTIALS_PATH, REFUSED_RETRY_ENV, CredentialRenewalManager, CredentialVendError, classifyCredentialVendFailure, clampRetryDelayMs, createContract3Fetcher, defaultRefusedRetryMs, extractVendErrorCode, isCredentialVendRefused, normalizeContract3Bundle, parseRetryAfterMs, realTimerHost, refusedRetryDelayMs, renewalDelayMs, scheduleBoundedTimeout, } from "./credentials.js";
 export { amzDateOf, hex, presignIotWssUrl, rfc3986Encode } from "./presign.js";
 export { PresenceClient, backoffDelayMs, buildPresencePayload, defaultMqttConnect, isOwnPresenceTopic, } from "./presence.js";
 export { defaultDaemonState, patchDaemonState, readDaemonState, writeDaemonState, } from "./state.js";

package/dist/lib/mesh/live/daemon/presence.d.ts

@@ -6,7 +6,8 @@
  * - Publishes retained online ONLY to own presence topics
  * - Offline is server-only (IoT lifecycle → PresenceIngestFunction)
  * - Never subscribes to thread topics
- * - Reconnects with jittered backoff 1s–60s on close / network change
+ * - Reconnects with monotonic full-jitter backoff 1s–60s on close / network
+ * - Server credential refusals use a long retry (default 10m ±20%)
  */
 import { type IClientOptions, type MqttClient } from "mqtt";
 import { type Contract3Bundle, type CredentialsFetcher, type TimerHost } from "./credentials.js";
@@ -30,6 +31,11 @@ export interface MeshMqttClientLike {
     subscribe?: unknown;
 }
 export type MqttConnectFn = (url: string, opts: IClientOptions) => MeshMqttClientLike;
+export interface PresenceRefusal {
+    code: string;
+    status: number;
+    nextRetryAt: string;
+}
 export interface PresenceClientOptions {
     fetchCredentials: CredentialsFetcher;
     mqttConnect?: MqttConnectFn;
@@ -37,14 +43,22 @@ export interface PresenceClientOptions {
     random?: () => number;
     baseBackoffMs?: number;
     maxBackoffMs?: number;
+    /** Base refused-retry interval (tests / HQ_MESH_DAEMON_REFUSED_RETRY_MS). */
+    refusedRetryMs?: number;
     /** Invoked when online is (re)published after connect. */
     onOnline?: (companies: string[]) => void;
     onState?: (state: MqttConnectionState) => void;
     onError?: (err: unknown) => void;
+    /** Fired when refusal appears, code changes, clears, or nextRetryAt updates. */
+    onRefusal?: (refusal: PresenceRefusal | null) => void;
     now?: () => Date;
+    env?: NodeJS.ProcessEnv;
 }
-/** Full-jitter capped exponential backoff (1s base → 60s cap by default). */
-export declare function backoffDelayMs(attempt: number, baseMs: number, maxMs: number, random: () => number): number;
+/**
+ * Full-jitter capped exponential backoff (1s base → 60s cap by default),
+ * floored at `previousMs` so consecutive failures never shrink the delay.
+ */
+export declare function backoffDelayMs(attempt: number, baseMs: number, maxMs: number, random: () => number, previousMs?: number): number;
 export declare function buildPresencePayload(input: {
     status: "online" | "offline";
     actorUid: string;
@@ -62,20 +76,26 @@ export declare class PresenceClient {
     private bundle;
     private state;
     private attempt;
+    private lastBackoffMs;
     private reconnectHandle;
     private stopped;
     private generation;
     private publishedTopics;
+    /** Last refusal code we logged via onError (episode dedupe). */
+    private loggedRefusalKey;
+    private refusal;
     private readonly mqttConnect;
     private readonly timers;
     private readonly random;
     private readonly baseBackoffMs;
     private readonly maxBackoffMs;
+    private readonly refusedRetryMs;
     private readonly renewal;
     private readonly now;
     constructor(options: PresenceClientOptions);
     getConnectionState(): MqttConnectionState;
     getBundle(): Contract3Bundle | null;
+    getRefusal(): PresenceRefusal | null;
     /** Topics this client has published to (for doctor / tests). */
     getPublishedTopics(): readonly string[];
     private setState;
@@ -90,6 +110,10 @@ export declare class PresenceClient {
     reconnectNow(): void;
     private teardownClient;
     private onCredentialsRenewed;
+    private handleRenewalError;
+    private refusalKey;
+    private noteRefusal;
+    private clearRefusal;
     private connectOnce;
     /** Publish retained online to every own presence topic (connect / renew). */
     private publishAll;

package/dist/lib/mesh/live/daemon/presence.js

@@ -6,15 +6,20 @@
  * - Publishes retained online ONLY to own presence topics
  * - Offline is server-only (IoT lifecycle → PresenceIngestFunction)
  * - Never subscribes to thread topics
- * - Reconnects with jittered backoff 1s–60s on close / network change
+ * - Reconnects with monotonic full-jitter backoff 1s–60s on close / network
+ * - Server credential refusals use a long retry (default 10m ±20%)
  */
 import mqtt from "mqtt";
-import { CredentialRenewalManager, MQTT_KEEPALIVE_SECONDS, realTimerHost, } from "./credentials.js";
+import { CredentialVendError, CredentialRenewalManager, MQTT_KEEPALIVE_SECONDS, clampRetryDelayMs, defaultRefusedRetryMs, realTimerHost, refusedRetryDelayMs, scheduleBoundedTimeout, } from "./credentials.js";
 import { presignIotWssUrl } from "./presign.js";
-/** Full-jitter capped exponential backoff (1s base → 60s cap by default). */
-export function backoffDelayMs(attempt, baseMs, maxMs, random) {
+/**
+ * Full-jitter capped exponential backoff (1s base → 60s cap by default),
+ * floored at `previousMs` so consecutive failures never shrink the delay.
+ */
+export function backoffDelayMs(attempt, baseMs, maxMs, random, previousMs = 0) {
     const cap = Math.min(maxMs, baseMs * 2 ** attempt);
-    return Math.max(0, random() * cap);
+    const raw = Math.max(0, random() * cap);
+    return Math.min(maxMs, Math.max(previousMs, raw));
 }
 export function buildPresencePayload(input) {
     return {
@@ -43,15 +48,20 @@ export class PresenceClient {
     bundle = null;
     state = "idle";
     attempt = 0;
+    lastBackoffMs = 0;
     reconnectHandle = null;
     stopped = false;
     generation = 0;
     publishedTopics = [];
+    /** Last refusal code we logged via onError (episode dedupe). */
+    loggedRefusalKey = null;
+    refusal = null;
     mqttConnect;
     timers;
     random;
     baseBackoffMs;
     maxBackoffMs;
+    refusedRetryMs;
     renewal;
     now;
     constructor(options) {
@@ -63,8 +73,10 @@ export class PresenceClient {
         this.random = options.random ?? Math.random;
         this.baseBackoffMs = options.baseBackoffMs ?? 1_000;
         this.maxBackoffMs = options.maxBackoffMs ?? 60_000;
+        this.refusedRetryMs =
+            options.refusedRetryMs ?? defaultRefusedRetryMs(options.env ?? process.env);
         this.now = options.now ?? (() => new Date());
-        this.renewal = new CredentialRenewalManager(options.fetchCredentials, (bundle) => void this.onCredentialsRenewed(bundle), (err) => options.onError?.(err), this.timers);
+        this.renewal = new CredentialRenewalManager(options.fetchCredentials, (bundle) => void this.onCredentialsRenewed(bundle), (err, info) => this.handleRenewalError(err, info), this.timers, 30_000, this.refusedRetryMs, this.random);
     }
     getConnectionState() {
         return this.state;
@@ -72,6 +84,9 @@ export class PresenceClient {
     getBundle() {
         return this.bundle;
     }
+    getRefusal() {
+        return this.refusal;
+    }
     /** Topics this client has published to (for doctor / tests). */
     getPublishedTopics() {
         return this.publishedTopics;
@@ -99,13 +114,21 @@ export class PresenceClient {
         this.renewal.stop();
         this.clearReconnect();
         this.teardownClient(false);
+        this.clearRefusal(/* logClear */ false);
         this.setState("closed");
     }
     /** Force a reconnect cycle (network change / sleep-wake). */
     reconnectNow() {
         if (this.stopped)
             return;
-        this.attempt = 0;
+        // Do not bypass an active refusal / Retry-After wait (network nudges).
+        if (this.refusal) {
+            const nextMs = Date.parse(this.refusal.nextRetryAt);
+            if (!Number.isNaN(nextMs) && nextMs > this.timers.now()) {
+                return;
+            }
+        }
+        // Backoff counters reset only on MQTT connect — not here.
         this.clearReconnect();
         void this.connectOnce();
     }
@@ -128,12 +151,51 @@ export class PresenceClient {
     }
     async onCredentialsRenewed(bundle) {
         this.bundle = bundle;
+        // Successful vend ends a refusal episode (renewal skips connectOnce's vend path).
+        this.clearRefusal(true);
         if (this.stopped)
             return;
-        // Reconnect with the new presigned URL, then re-publish online.
-        this.attempt = 0;
+        // Reconnect with the new presigned URL; backoff resets only on MQTT connect.
         await this.connectOnce();
     }
+    handleRenewalError(err, info) {
+        if (err instanceof CredentialVendError && err.kind === "refused") {
+            this.noteRefusal(err, info?.nextRetryAt);
+            return;
+        }
+        this.options.onError?.(err);
+    }
+    refusalKey(err) {
+        return err.code ?? `HTTP_${err.status}`;
+    }
+    noteRefusal(err, nextRetryAt) {
+        const code = this.refusalKey(err);
+        const keyChanged = this.loggedRefusalKey !== code;
+        if (keyChanged) {
+            this.loggedRefusalKey = code;
+            this.options.onError?.(err);
+        }
+        const refusal = {
+            code,
+            status: err.status,
+            nextRetryAt: nextRetryAt ??
+                this.refusal?.nextRetryAt ??
+                new Date(this.timers.now()).toISOString(),
+        };
+        this.refusal = refusal;
+        this.options.onRefusal?.(refusal);
+    }
+    clearRefusal(logClear) {
+        if (this.loggedRefusalKey === null && this.refusal === null)
+            return;
+        const previous = this.loggedRefusalKey;
+        this.loggedRefusalKey = null;
+        this.refusal = null;
+        if (logClear && previous) {
+            this.options.onError?.(new Error(`presence refusal cleared (was ${previous})`));
+        }
+        this.options.onRefusal?.(null);
+    }
     async connectOnce() {
         if (this.stopped)
             return;
@@ -143,6 +205,8 @@ export class PresenceClient {
         try {
             if (!this.bundle) {
                 this.bundle = await this.options.fetchCredentials();
+                // Successful vend ends a refusal episode (even before MQTT connects).
+                this.clearRefusal(true);
                 this.renewal.schedule(this.bundle);
             }
             const bundle = this.bundle;
@@ -170,6 +234,7 @@ export class PresenceClient {
                 if (this.stopped || generation !== this.generation)
                     return;
                 this.attempt = 0;
+                this.lastBackoffMs = 0;
                 this.setState("connected");
                 void this.publishAll("online").then(() => {
                     this.options.onOnline?.(bundle.companies.map((c) => c.companyUid));
@@ -187,6 +252,10 @@ export class PresenceClient {
             });
         }
         catch (err) {
+            if (err instanceof CredentialVendError && err.kind === "refused") {
+                this.scheduleReconnect({ refused: err });
+                return;
+            }
             this.options.onError?.(err);
             this.scheduleReconnect();
         }
@@ -224,21 +293,43 @@ export class PresenceClient {
             });
         }
     }
-    scheduleReconnect() {
+    scheduleReconnect(opts) {
         if (this.stopped)
             return;
         this.setState("reconnecting");
         this.clearReconnect();
-        const delay = backoffDelayMs(this.attempt, this.baseBackoffMs, this.maxBackoffMs, this.random);
-        this.attempt += 1;
-        this.reconnectHandle = this.timers.setTimeout(() => {
+        let delay;
+        if (opts?.refused) {
+            const refused = opts.refused;
+            if (refused.retryAfterMs !== undefined) {
+                delay = Math.max(0, refused.retryAfterMs);
+            }
+            else {
+                delay = refusedRetryDelayMs(this.refusedRetryMs, this.random);
+            }
+            delay = clampRetryDelayMs(delay);
+            const nextRetryAt = new Date(this.timers.now() + delay).toISOString();
+            this.noteRefusal(refused, nextRetryAt);
+        }
+        else {
+            delay = backoffDelayMs(this.attempt, this.baseBackoffMs, this.maxBackoffMs, this.random, this.lastBackoffMs);
+            this.lastBackoffMs = delay;
+            this.attempt += 1;
+            // Do not clear refusal here — MQTT close must retain doctor/status refusal
+            // until a subsequent credential vend succeeds.
+        }
+        this.reconnectHandle = scheduleBoundedTimeout(this.timers, () => {
             this.reconnectHandle = null;
+            // Drop stale creds so the next attempt re-vends after a refusal/failure.
+            if (opts?.refused) {
+                this.bundle = null;
+            }
             void this.connectOnce();
         }, delay);
     }
     clearReconnect() {
         if (this.reconnectHandle !== null) {
-            this.timers.clearTimeout(this.reconnectHandle);
+            this.reconnectHandle.clear();
             this.reconnectHandle = null;
         }
     }

package/dist/lib/mesh/live/daemon/run.js

@@ -126,6 +126,7 @@ export async function runMeshDaemon(deps = {}) {
             timers,
             random: deps.random,
             now,
+            env,
             onState: (state) => {
                 patchDaemonState(dir, { mqttState: state }, now);
             },
@@ -134,9 +135,18 @@ export async function runMeshDaemon(deps = {}) {
                     mqttState: "connected",
                     companiesOnline: companies,
                     actorUid: presence?.getBundle()?.actorUid,
+                    presenceRefusal: null,
                 }, now);
                 log(dir, `presence online companies=${companies.length}`);
             },
+            onRefusal: (refusal) => {
+                patchDaemonState(dir, {
+                    presenceRefusal: refusal,
+                    lastErrorCode: refusal
+                        ? `refused:${refusal.code}`.slice(0, 120)
+                        : undefined,
+                }, now);
+            },
             onError: (err) => {
                 const msg = err instanceof Error ? err.message : String(err);
                 patchDaemonState(dir, { lastErrorCode: msg.slice(0, 120) }, now);

package/dist/lib/mesh/live/daemon/state.d.ts

@@ -3,6 +3,11 @@
  */
 import type { MqttConnectionState } from "./presence.js";
 import type { FlushSummary } from "../flush.js";
+export interface PresenceRefusalState {
+    code: string;
+    status: number;
+    nextRetryAt: string;
+}
 export interface DaemonStateFile {
     v: 1;
     pid: number;
@@ -15,6 +20,8 @@ export interface DaemonStateFile {
         ok: boolean;
     };
     lastErrorCode?: string;
+    /** Set while credential vend is refused (FEATURE_DISABLED / unsupported / 403). */
+    presenceRefusal?: PresenceRefusalState | null;
     updatedAt: string;
 }
 export declare function defaultDaemonState(pid: number, now?: () => Date): DaemonStateFile;

package/dist/utils/client-health.js

@@ -345,7 +345,23 @@ export function buildCliHeartbeat(input) {
             syncState = "error";
             break;
         default:
-            syncState = lastSyncSuccessAt ? "idle" : "never_synced";
+            // An UNRESOLVED failure streak is a live error state, not idleness.
+            // Reporting `idle` here is what put "BROKEN — Runner failed" next to
+            // "Sync state: idle" on the support view: every later `hq` invocation
+            // overwrote the `error` state the failing sync had reported while
+            // leaving the streak that earned it untouched.
+            //
+            // Only this CLI's own `sync_success` clears the streak. The journal
+            // `lastSync` folded into `lastSyncSuccessAt` below deliberately does
+            // NOT: the engine stamps it per FILE update (hq-cloud journal.ts
+            // `updateEntry`), and a push stamps it before throwing its upload worker
+            // errors — so it means "some file moved", not "a run succeeded", and
+            // must never clear an alarm counter. That is why this branch keys off
+            // the streak rather than off the success timestamp.
+            if (input.state.consecutiveFailures > 0)
+                syncState = "error";
+            else
+                syncState = lastSyncSuccessAt ? "idle" : "never_synced";
             break;
     }
     const heartbeat = {

package/dist/utils/self-update.d.ts

@@ -71,6 +71,15 @@ export type SelfUpdateAction =
  | "update-failed"
 /** Updated, but the re-exec couldn't start; continue on the current (in-memory) version. */
  | "updated-no-reexec"
+/**
+ * The install reported success but the `hq` on PATH still resolves the old
+ * version (a shadowing/ghost install, a prefix/PATH mismatch, or a stale
+ * tarball). Re-installing the same target can never converge, so we do NOT
+ * re-exec, we record the target as ineffective so the startup path stops
+ * auto-retrying it, and the command runs on the current version. This is the
+ * guard against the self-update loop.
+ */
+ | "update-ineffective"
 /** Updated and the command re-ran on the new version; exit with `reexecStatus`. */
  | "reexec"
 /**
@@ -127,6 +136,17 @@ export interface SelfUpdateDeps {
     runner?: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => UpdateResult;
     reexec?: (argv: string[], env: NodeJS.ProcessEnv) => number | null;
     acquireLock?: () => (() => void) | null;
+    /**
+     * Read-your-writes convergence check run after a "successful" install:
+     * returns false only when the `hq` on PATH still resolves a build older than
+     * the target we just installed. Defaults to {@link checkUpdateConvergence}.
+     */
+    checkConvergence?: (targetVersion: string) => boolean;
+    /**
+     * Persist that `version` installed but never took effect, so the startup path
+     * stops auto-retrying it. Defaults to {@link markLatestIneffective}.
+     */
+    markIneffective?: (version: string) => void;
     /**
      * Whether a human is watching this invocation. Defaults to "stderr is a TTY",
      * which is false for exactly the callers that must not replace the CLI

package/dist/utils/self-update.js

@@ -60,8 +60,9 @@ import { spawnSync } from "node:child_process";
 import semver from "semver";
 import chalk from "chalk";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
-import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, inOwnProcessGroup, isLocalDependencyInstall, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
+import { buildBunInstallArgv, buildPnpmInstallArgv, buildPrefixedInstallArgv, buildSpawnPlan, checkUpdateConvergence, inOwnProcessGroup, isLocalDependencyInstall, openInstallOutput, pnpmUpdateEnv, resolveRunningInstall, runUpdateCommand, } from "./version-gate.js";
 import { acquireUpdateLock as acquireSharedUpdateLock } from "./update-lock.js";
+import { markLatestIneffective } from "./version-check.js";
 /**
  * Set on the re-exec'd child so it can never self-update (and re-exec) again.
  * One update + one re-exec per user invocation, ever.
@@ -278,6 +279,26 @@ async function updateAndReexec(argv, flavor, known, deps) {
         console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
         return { action: "update-failed", latest };
     }
+    // Read-your-writes: a "successful" `npm install -g` proves only that the
+    // prefix was rewritten, NOT that the `hq` this user's PATH resolves is the
+    // copy we just wrote. When a ghost/shadowing install keeps winning PATH
+    // resolution (or a prefix/PATH mismatch or stale tarball leaves the running
+    // copy behind), re-exec'ing here runs the command on the SAME stale version,
+    // and — because `staleAgainstCachedLatest` still sees the baked CLI_VERSION
+    // as behind `latest` — the next invocation installs and re-execs again,
+    // forever. The hard version gate already verifies convergence; the soft
+    // startup path did not, which is the 5.105.0 → 5.105.1 self-update loop.
+    //
+    // So verify before announcing success. On non-convergence: mark the target
+    // ineffective (suppresses auto-retry for a cooldown), skip the pointless
+    // re-exec into a stale copy, and let the command run on the current version.
+    const checkConvergence = deps.checkConvergence ?? checkUpdateConvergence;
+    const converged = checkConvergence(latestValid);
+    if (converged === false) {
+        (deps.markIneffective ?? markLatestIneffective)(latest);
+        console.error(chalk.dim(`  Continuing the ${flavor.noun} on ${current}.`));
+        return { action: "update-ineffective", latest };
+    }
     const childEnv = { ...env, [REEXEC_GUARD_ENV]: "1" };
     const status = (deps.reexec ?? reexecHq)([...argv.slice(2)], childEnv);
     if (status === null) {

package/dist/utils/version-check.d.ts

@@ -10,6 +10,13 @@ declare function isKnownNoninteractiveStatusProbe(argv?: readonly string[]): boo
  * command, and warns only if that fails.
  */
 export declare function staleAgainstCachedLatest(now?: number): string | null;
+/**
+ * Record that installing `version` did not move the on-PATH `hq` forward, so
+ * {@link staleAgainstCachedLatest} stops auto-retrying it for a cooldown. Called
+ * by the self-updater's convergence check. Best-effort: a write failure only
+ * means the loop guard is skipped this once, never a broken CLI.
+ */
+export declare function markLatestIneffective(version: string, now?: number): void;
 export declare function refreshVersionCache(): Promise<void>;
 export declare const __test__: {
     CACHE_TTL_MS: number;

package/dist/utils/version-check.js

@@ -9,6 +9,12 @@ const CACHE_TTL_MS = 60 * 60 * 1000; // 1h — catch fresh releases within the h
 const CACHE_TTL_JITTER_MS = 5 * 60 * 1000; // up to 5m early, to spread a fleet's refreshes off a single instant
 const FETCH_TIMEOUT_MS = 3_000;
 const REFRESH_LOCK_STALE_MS = 10 * 60 * 1000;
+/**
+ * How long to stop auto-retrying an `ineffectiveLatest` target. Long enough to
+ * break the per-invocation loop on a busy agent box, short enough that a box
+ * whose PATH is later fixed recovers on its own without a manual `hq rescue`.
+ */
+const INEFFECTIVE_COOLDOWN_MS = 6 * 60 * 60 * 1000; // 6h
 function cachePath() {
     return path.join(os.homedir(), ".hq", "version-check.json");
 }
@@ -26,7 +32,16 @@ function readCache() {
             typeof parsed.fetchedAt !== "number") {
             return null;
         }
-        return { latest: parsed.latest, fetchedAt: parsed.fetchedAt };
+        return {
+            latest: parsed.latest,
+            fetchedAt: parsed.fetchedAt,
+            ...(typeof parsed.ineffectiveLatest === "string"
+                ? { ineffectiveLatest: parsed.ineffectiveLatest }
+                : {}),
+            ...(typeof parsed.ineffectiveAt === "number"
+                ? { ineffectiveAt: parsed.ineffectiveAt }
+                : {}),
+        };
     }
     catch {
         return null;
@@ -119,8 +134,38 @@ export function staleAgainstCachedLatest(now = Date.now()) {
         return null;
     if (!semver.gt(latest, current))
         return null;
+    // Loop guard: a previous self-update installed this exact `latest` but the
+    // on-PATH `hq` never converged to it (see markLatestIneffective). Retrying
+    // the same target re-installs it and re-execs into the same stale copy on
+    // every invocation without ever making progress, so suppress it for a
+    // cooldown. A newer `latest` (different target) is never suppressed.
+    if (entry.ineffectiveLatest === entry.latest &&
+        typeof entry.ineffectiveAt === "number" &&
+        now - entry.ineffectiveAt <= INEFFECTIVE_COOLDOWN_MS) {
+        return null;
+    }
     return entry.latest;
 }
+/**
+ * Record that installing `version` did not move the on-PATH `hq` forward, so
+ * {@link staleAgainstCachedLatest} stops auto-retrying it for a cooldown. Called
+ * by the self-updater's convergence check. Best-effort: a write failure only
+ * means the loop guard is skipped this once, never a broken CLI.
+ */
+export function markLatestIneffective(version, now = Date.now()) {
+    const entry = readCache();
+    if (!entry)
+        return;
+    // Only mark the target we actually believe is `latest`; marking anything else
+    // would risk suppressing a legitimately newer release.
+    if (entry.latest !== version)
+        return;
+    writeCache({
+        ...entry,
+        ineffectiveLatest: version,
+        ineffectiveAt: now,
+    });
+}
 export async function refreshVersionCache() {
     if (isOptedOut())
         return;

package/package.json

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