@indigoai-us/hq-cli 5.119.1 → 5.119.5

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 ## [Unreleased]
 
+## [5.119.5] — 2026-09-17
+
+### Fixed
+
+- When a new Slack agent is waiting for a Socket Mode app-level token, `hq
+  agents status` now shows a link to create the token and a direct link to the
+  HQ form where it can be pasted. The same links are included in JSON output.
+
+### Changed
+
+- Starter now includes 1 integration instead of none, and the lock copy says
+  so. The notice reads "too many integrations", quotes "Integrations allowed
+  on Starter: 1", and tells you to "disconnect integrations until you are at 1
+  or fewer"; the per-turn line reads "over its 1-integration limit". Nothing in
+  the CLI says Starter has no integrations any more.
+
+## [5.119.4] — 2026-09-17
+
+### Fixed
+
+- On a host with no usable service manager, `hq agent kit install` now installs
+  the `@reboot` crontab entry that restarts the kit, instead of printing the
+  line and trusting it to be pasted. A supervisor that does not survive a
+  reboot is not a supervisor: on the Muse pilot the host restarted, the
+  supervisor died with it, nothing brought it back, and the agent silently
+  stopped seeing new messages while every surface still reported healthy. The
+  entry is marked and replaced on reinstall rather than stacked, and every
+  other crontab line is preserved. If the crontab cannot be written the install
+  still succeeds but says so in red, naming the consequence and printing the
+  line to add by hand.
+
+## [5.119.3] — 2026-09-17
+
+### Fixed
+
+- `hq agent inbox` now merges the agent's own server inbox with the kit's local
+  mirror instead of reading the mirror alone. The mirror is only as fresh as
+  the kit's poller, and when that process dies nothing says so — the listing
+  simply stops growing. On the Muse pilot the host rebooted, the kit supervisor
+  died with it and was never restarted, and the command kept confidently
+  answering with the eight messages from before the reboot while the server had
+  every newer one: no error, no empty result, no stale marker, just an agent
+  that had gone deaf and could not tell. When the server cannot be reached the
+  mirror is still returned, with a note saying it may be stale. `hq_inbox_read`
+  already merged; both now share one implementation.
+
+## [5.119.2] — 2026-09-17
+
+### Fixed
+
+- The work-mesh listener falls back to its periodic refetch when the MQTT
+  doorbell is unreachable, instead of retrying forever and reporting
+  `component-mesh=error` the whole time. The doorbell is an optimisation over a
+  REST source of truth, so a host that cannot reach AWS IoT has a slower
+  doorbell, not a broken agent. Some bot sandboxes sit behind an egress proxy
+  that intercepts the connection and answers with non-TLS bytes
+  (`tls_validate_record_header:wrong version number`). After five failed
+  attempts the listener says so once, keeps the cache current on the periodic
+  cadence, and retries MQTT every 30 minutes so a bot moved to an unrestricted
+  network recovers its instant doorbell on its own. Incoming DMs are
+  unaffected either way — the inbox poller is a separate service.
+
 ## [5.119.1] — 2026-09-17
 
 ### Fixed

package/dist/commands/agent-inbox.js

@@ -8,7 +8,7 @@ import chalk from "chalk";
 import * as os from "node:os";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
-import { markInboxDone, readDoneIds, readMirroredInbox, summarizeInboxEntry } from "../lib/agent-kit/inbox-state.js";
+import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../lib/agent-kit/inbox-state.js";
 import { agentKitPaths } from "../lib/agent-kit/paths.js";
 import { requireExternalCreds } from "./agent-kit.js";
 const ID_RE = /^[A-Za-z0-9._:-]{1,200}$/;
@@ -18,16 +18,31 @@ export function registerAgentInboxCommand(agent) {
         .description("List this agent's pending HQ messages (mirrored by the kit), or mark them handled")
         .option("--all", "Include items already marked handled")
         .option("--json", "Print machine-readable JSON")
-        .action((opts) => {
+        .action(async (opts) => {
         const paths = agentKitPaths(os.homedir(), process.env);
+        const creds = requireExternalCreds(paths);
         const done = readDoneIds(paths);
-        const rows = readMirroredInbox(paths)
+        // Merged with the server, never the local mirror alone: a dead kit
+        // poller would otherwise make this command answer confidently with
+        // yesterday's mail and no sign anything was wrong.
+        const { entries, note } = await mergeAgentInbox(paths, async () => {
+            const token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
+            const res = await vaultApiFetch({
+                token,
+                baseUrl: creds.apiBaseUrl,
+                path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`,
+            });
+            return { status: res.status, body: await res.json().catch(() => ({})) };
+        });
+        const rows = entries
             .filter((e) => opts.all || !done.has(e.id))
             .map((e) => summarizeInboxEntry(e, done.has(e.id)));
         if (opts.json) {
-            console.log(JSON.stringify({ count: rows.length, messages: rows }, null, 2));
+            console.log(JSON.stringify({ count: rows.length, messages: rows, ...(note ? { note } : {}) }, null, 2));
             return;
         }
+        if (note)
+            console.error(chalk.yellow(note));
         if (rows.length === 0) {
             console.log(opts.all ? "Inbox is empty." : "No pending messages.");
             return;

package/dist/commands/agent-kit.d.ts

@@ -22,7 +22,7 @@ import { type KitConfig } from "../lib/agent-kit/kit-config.js";
 import { type KitLogger } from "../lib/agent-kit/log.js";
 import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
 import { type KitService } from "../lib/agent-kit/services.js";
-import { type DetachedSpawn, type KillFn } from "../lib/agent-kit/fallback.js";
+import { type CronRunner, type RebootCronResult, type DetachedSpawn, type KillFn } from "../lib/agent-kit/fallback.js";
 import { type ServiceHostPaths, type ServiceManagerDeps, type ServiceSetResult } from "../lib/service-manager/index.js";
 export declare class KitError extends Error {
     constructor(message: string);
@@ -48,8 +48,10 @@ export interface KitFallbackInfo {
     pid: number;
     pidFile: string;
     logPath: string;
-    /** Add to `crontab -e` so the supervisor survives a reboot. */
+    /** The @reboot entry that restarts the supervisor. */
     crontab: string;
+    /** Whether that entry was installed for you, and why not if it was not. */
+    reboot: RebootCronResult;
 }
 export interface KitInstallResult {
     config: KitConfig;
@@ -60,6 +62,8 @@ export interface KitInstallResult {
 export interface KitFallbackDeps {
     spawn?: DetachedSpawn;
     kill?: KillFn;
+    /** Injected crontab runner (tests). */
+    cron?: CronRunner;
 }
 export declare function installKit(paths: AgentKitPaths, opts: KitInstallOptions, host: ServiceHostPaths, deps?: ServiceManagerDeps, fallbackDeps?: KitFallbackDeps): KitInstallResult;
 export declare function formatServiceSet(result: ServiceSetResult): string[];

package/dist/commands/agent-kit.js

@@ -30,7 +30,7 @@ import { writeKitSkills } from "../lib/agent-kit/skills.js";
 import { runHeartbeatLoop } from "../lib/agent-kit/run/heartbeat.js";
 import { pollInboxOnce, runInboxLoop } from "../lib/agent-kit/run/inbox.js";
 import { superviseKitServices } from "../lib/agent-kit/run/supervisor.js";
-import { fallbackStatus, rebootCrontabLine, shouldUseFallback, startFallback, stopFallback, } from "../lib/agent-kit/fallback.js";
+import { fallbackStatus, rebootCrontabLine, ensureRebootCrontab, shouldUseFallback, startFallback, stopFallback, } from "../lib/agent-kit/fallback.js";
 import { serviceLogPath } from "../lib/agent-kit/paths.js";
 import { spawn } from "node:child_process";
 import { startMeshListener } from "../lib/agent-kit/run/mesh-listener.js";
@@ -99,11 +99,19 @@ export function installKit(paths, opts, host, deps = {}, fallbackDeps = {}) {
     });
     if (shouldUseFallback(services, activate)) {
         const started = startFallback(paths, host, fallbackDeps);
+        // A supervisor that does not survive a reboot is not a supervisor. Install
+        // the @reboot entry rather than printing it and hoping.
+        const reboot = ensureRebootCrontab(paths, host, fallbackDeps.cron);
         return {
             config,
             skills,
             services,
-            fallback: { mode: "fallback", ...started, crontab: rebootCrontabLine(paths, host) },
+            fallback: {
+                mode: "fallback",
+                ...started,
+                crontab: rebootCrontabLine(paths, host),
+                reboot,
+            },
         };
     }
     return { config, skills, services };
@@ -309,8 +317,15 @@ export function registerAgentKitCommand(agent) {
                     `(hq agent kit run all, pid ${result.fallback.pid})`));
                 console.log(`  pidfile:   ${result.fallback.pidFile}`);
                 console.log(`  kit log:   ${result.fallback.logPath}`);
-                console.log("  To restart it after a reboot, add this line with `crontab -e`:");
-                console.log(`    ${result.fallback.crontab}`);
+                if (result.fallback.reboot.installed) {
+                    console.log(chalk.green("  reboot:    a @reboot crontab entry was installed, so the kit restarts with the host"));
+                }
+                else {
+                    console.log(chalk.red(`  reboot:    NOT protected — ${result.fallback.reboot.reason}. Until this is fixed the kit ` +
+                        "stops at the next restart and this agent silently stops seeing new messages."));
+                    console.log("  Add this line yourself with `crontab -e`:");
+                    console.log(`    ${result.fallback.crontab}`);
+                }
             }
             else {
                 console.log("  services:");

package/dist/commands/agents.js

@@ -445,6 +445,26 @@ function currentDeviceSignInAction(status) {
 }
 function pendingSlackAction(status) {
     const agent = recordValue(status.agent);
+    const configuredSlack = recordValue(recordValue(agent?.channels)?.slack);
+    const appId = nonEmptyString(configuredSlack?.appId);
+    const agentUid = nonEmptyString(agent?.uid);
+    const companyUid = nonEmptyString(agent?.companyUid);
+    const tokenPage = safeActionUrl(configuredSlack?.appTokenPendingUrl);
+    if (tokenPage &&
+        appId && /^A[A-Z0-9]+$/.test(appId) &&
+        new URL(tokenPage).hostname === "api.slack.com" &&
+        agentUid && AGENT_UID_PATTERN.test(agentUid) &&
+        companyUid && /^cmp_[A-Za-z0-9_-]+$/.test(companyUid)) {
+        return {
+            type: "slack-app-token",
+            title: `Finish ${nonEmptyString(agent?.name) ?? "the agent"}'s Slack connection`,
+            summary: "connect it to Slack",
+            instruction: "Create an app-level token with the connections:write scope, then paste it into HQ. HQ verifies the token and resumes setup; if Slack asks you to install the app, follow the install link shown there.",
+            url: `https://api.slack.com/apps/${appId}/general`,
+            urlLabel: "Get token",
+            pasteUrl: `https://hq.computer/companies/${encodeURIComponent(companyUid)}/agents?setup=${encodeURIComponent(agentUid)}`,
+        };
+    }
     const diagnostics = recordValue(agent?.channelDiagnostics);
     const slack = recordValue(diagnostics?.slack);
     const url = safeActionUrl(slack?.pendingInstallUrl);
@@ -483,11 +503,12 @@ function pendingOperatorActions(status) {
     ].filter((action) => action !== null);
 }
 function pendingActionsJson(actions) {
-    return actions.map(({ type, title, instruction, url, code }) => ({
+    return actions.map(({ type, title, instruction, url, pasteUrl, code }) => ({
         type,
         title,
         instruction,
         ...(url ? { url } : {}),
+        ...(pasteUrl ? { pasteUrl } : {}),
         ...(code ? { code } : {}),
     }));
 }
@@ -514,6 +535,8 @@ function printPendingOperatorActions(slug, actions) {
         console.log(action.instruction);
         if (action.url)
             console.log(chalk.cyan(`${action.urlLabel ?? "Open"}: ${action.url}`));
+        if (action.pasteUrl)
+            console.log(chalk.cyan(`Paste token: ${action.pasteUrl}`));
         if (action.code)
             console.log(chalk.bold(`Code: ${action.code}`));
     }

package/dist/lib/agent-kit/fallback.d.ts

@@ -60,4 +60,39 @@ export declare function startFallback(paths: AgentKitPaths, host: ServiceHostPat
     logPath: string;
     pidFile: string;
 };
+/**
+ * Marker for the crontab entry this module owns. Present so a reinstall
+ * replaces its own line instead of stacking duplicates, and so a human reading
+ * their crontab can see what wrote it and that removing it is safe.
+ */
+export declare const REBOOT_CRON_MARKER = "# hq-agent-kit (managed): restart the HQ agent kit after a reboot";
+export interface CronRunner {
+    (args: string[], input?: string): {
+        status: number;
+        stdout: string;
+        stderr: string;
+    };
+}
+export interface RebootCronResult {
+    installed: boolean;
+    /** Why it could not be installed, for the caller to print verbatim. */
+    reason?: string;
+}
+/** Drop any previously managed block, leaving every other entry untouched. */
+export declare function stripManagedCron(existing: string): string;
+/**
+ * Install the @reboot entry that brings the fallback supervisor back after a
+ * restart.
+ *
+ * Printing the line and trusting it to be pasted is what the installer used to
+ * do, and it is how the Muse pilot lost its messages: the host rebooted, the
+ * supervisor died with it, nothing restarted it, and the bot went quiet while
+ * every surface still reported healthy. A supervisor that does not survive a
+ * reboot is not a supervisor, so the entry is now written for real.
+ *
+ * Failure is NOT fatal — a host with no crontab is still a working kit until
+ * it restarts — but it is reported, so the caller can tell the operator the
+ * one thing they must then do by hand.
+ */
+export declare function ensureRebootCrontab(paths: Pick<AgentKitPaths, "agentDir" | "logsDir">, host: ServiceHostPaths, run?: CronRunner): RebootCronResult;
 //# sourceMappingURL=fallback.d.ts.map

package/dist/lib/agent-kit/fallback.js

@@ -7,7 +7,7 @@
  * ~/.hq-agent/logs/kit.log and its pid recorded in ~/.hq-agent/kit.pid.
  * `kit status` reads the pidfile; `kit uninstall` kills it and removes it.
  */
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { kitServiceEnv } from "./services.js";
@@ -126,4 +126,68 @@ export function startFallback(paths, host, deps = {}) {
         fs.closeSync(fd);
     }
 }
+/**
+ * Marker for the crontab entry this module owns. Present so a reinstall
+ * replaces its own line instead of stacking duplicates, and so a human reading
+ * their crontab can see what wrote it and that removing it is safe.
+ */
+export const REBOOT_CRON_MARKER = "# hq-agent-kit (managed): restart the HQ agent kit after a reboot";
+/** Drop any previously managed block, leaving every other entry untouched. */
+export function stripManagedCron(existing) {
+    const lines = existing.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === REBOOT_CRON_MARKER) {
+            // Skip the marker and the entry it introduces.
+            if (i + 1 < lines.length && lines[i + 1].startsWith("@reboot"))
+                i += 1;
+            continue;
+        }
+        out.push(lines[i]);
+    }
+    return out.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
+}
+/**
+ * Install the @reboot entry that brings the fallback supervisor back after a
+ * restart.
+ *
+ * Printing the line and trusting it to be pasted is what the installer used to
+ * do, and it is how the Muse pilot lost its messages: the host rebooted, the
+ * supervisor died with it, nothing restarted it, and the bot went quiet while
+ * every surface still reported healthy. A supervisor that does not survive a
+ * reboot is not a supervisor, so the entry is now written for real.
+ *
+ * Failure is NOT fatal — a host with no crontab is still a working kit until
+ * it restarts — but it is reported, so the caller can tell the operator the
+ * one thing they must then do by hand.
+ */
+export function ensureRebootCrontab(paths, host, run) {
+    const exec = run ??
+        ((args, input) => {
+            const r = spawnSync("crontab", args, { input, encoding: "utf8" });
+            if (r.error)
+                return { status: 127, stdout: "", stderr: r.error.message };
+            return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+        });
+    const listed = exec(["-l"]);
+    // An empty crontab exits non-zero with "no crontab for <user>"; that is not
+    // a failure, it just means there is nothing to preserve. Anything else is.
+    const noCrontabYet = listed.status !== 0 && /no crontab for/i.test(listed.stderr);
+    if (listed.status !== 0 && !noCrontabYet) {
+        return {
+            installed: false,
+            reason: `could not read the crontab (${(listed.stderr || "").trim() || `exit ${listed.status}`})`,
+        };
+    }
+    const kept = stripManagedCron(noCrontabYet ? "" : listed.stdout);
+    const body = `${kept.trimEnd()}\n${REBOOT_CRON_MARKER}\n${rebootCrontabLine(paths, host)}\n`.replace(/^\n+/, "");
+    const wrote = exec(["-"], body);
+    if (wrote.status !== 0) {
+        return {
+            installed: false,
+            reason: `could not write the crontab (${(wrote.stderr || "").trim() || `exit ${wrote.status}`})`,
+        };
+    }
+    return { installed: true };
+}
 //# sourceMappingURL=fallback.js.map

package/dist/lib/agent-kit/inbox-state.d.ts

@@ -31,4 +31,30 @@ export declare function summarizeInboxEntry(e: MirroredInboxEntry, done: boolean
     text: string | undefined;
     done: boolean;
 };
+/**
+ * The agent's inbox as the bot should see it: the kit's local mirror merged
+ * with the agent's own server inbox.
+ *
+ * Reading the mirror ALONE is a silent-blindness bug. The mirror is only as
+ * fresh as the kit's poller, and when that process dies nothing says so — the
+ * listing simply stops growing. Observed on the Muse pilot: its host rebooted,
+ * the kit supervisor died with it and was never restarted, and `hq agent
+ * inbox` kept answering with the eight messages from before the reboot while
+ * the server had every newer one. No error, no empty result, no stale marker —
+ * just an agent that had gone deaf and could not tell.
+ *
+ * So the server is consulted on every read and anything it knows about that
+ * the mirror lacks is included. When the server cannot be reached the mirror
+ * is still returned, with a `note` naming the degradation: a partial answer
+ * that says it is partial beats a confident wrong one.
+ */
+export interface MergedInbox {
+    entries: MirroredInboxEntry[];
+    /** Set when the server could not be consulted, so the caller can say so. */
+    note?: string;
+}
+export declare function mergeAgentInbox(paths: Pick<AgentKitPaths, "inboxDir">, fetchServerInbox: () => Promise<{
+    status: number;
+    body: unknown;
+}>): Promise<MergedInbox>;
 //# sourceMappingURL=inbox-state.d.ts.map

package/dist/lib/agent-kit/inbox-state.js

@@ -83,4 +83,31 @@ export function summarizeInboxEntry(e, done) {
         done,
     };
 }
+export async function mergeAgentInbox(paths, fetchServerInbox) {
+    const byId = new Map();
+    for (const e of readMirroredInbox(paths))
+        byId.set(e.id, e);
+    let note;
+    try {
+        const res = await fetchServerInbox();
+        if (res.status === 200) {
+            const messages = res.body?.messages;
+            for (const m of Array.isArray(messages) ? messages : []) {
+                if (!m || typeof m !== "object")
+                    continue;
+                const raw = m;
+                const id = typeof raw.id === "string" ? raw.id : typeof raw.messageId === "string" ? raw.messageId : null;
+                if (id && !byId.has(id))
+                    byId.set(id, { ...raw, id });
+            }
+        }
+        else {
+            note = `server inbox answered ${res.status}; showing the local mirror only, which may be stale`;
+        }
+    }
+    catch (err) {
+        note = `server inbox unavailable (${err instanceof Error ? err.message : String(err)}); showing the local mirror only, which may be stale`;
+    }
+    return { entries: [...byId.values()], ...(note ? { note } : {}) };
+}
 //# sourceMappingURL=inbox-state.js.map

package/dist/lib/agent-kit/mcp/tools.js

@@ -17,7 +17,7 @@
  */
 import { CLI_VERSION } from "../../../cli-version.js";
 import { peekIdToken } from "../../../utils/id-token.js";
-import { markInboxDone, readDoneIds, readMirroredInbox, summarizeInboxEntry } from "../inbox-state.js";
+import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../inbox-state.js";
 import { errorResult, McpToolInputError, textResult } from "./jsonrpc.js";
 export const MAX_TOOL_OUTPUT_CHARS = 40_000;
 function str(args, key, opts = {}) {
@@ -252,33 +252,11 @@ export function buildAgentMcpTools(clients) {
                 const limit = int(args, "limit", { min: 1, max: 100, fallback: 20 });
                 const includeDone = args.include_done === true;
                 const done = readDoneIds(clients.paths);
-                // The kit mirror is the source of truth; merge the agent's own server
-                // inbox so items the poller has not mirrored yet are not missed.
-                const byId = new Map();
-                for (const e of readMirroredInbox(clients.paths))
-                    byId.set(e.id, e);
-                let serverNote;
-                try {
+                const { entries, note: serverNote } = await mergeAgentInbox(clients.paths, async () => {
                     const token = await clients.getToken();
-                    const res = await clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`);
-                    if (res.status === 200) {
-                        const messages = res.body?.messages;
-                        for (const m of Array.isArray(messages) ? messages : []) {
-                            if (!m || typeof m !== "object")
-                                continue;
-                            const raw = m;
-                            const id = typeof raw.id === "string" ? raw.id : typeof raw.messageId === "string" ? raw.messageId : null;
-                            if (id && !byId.has(id))
-                                byId.set(id, { ...raw, id });
-                        }
-                    }
-                    else {
-                        serverNote = `server inbox answered ${res.status}: ${describeError(res.body)}; showing the local mirror only`;
-                    }
-                }
-                catch (err) {
-                    serverNote = `server inbox unavailable (${err instanceof Error ? err.message : String(err)}); showing the local mirror only`;
-                }
+                    return clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`);
+                });
+                const byId = new Map(entries.map((e) => [e.id, e]));
                 const rows = [...byId.values()]
                     .filter((e) => includeDone || !done.has(e.id))
                     .slice(0, limit)

package/dist/lib/agent-kit/run/mesh-listener.d.ts

@@ -27,6 +27,29 @@ export declare const DOORBELL_KINDS: readonly ["dm", "work", "sessions", "notifi
 export declare const DOORBELL_DEBOUNCE_MS = 2000;
 export declare const RECONNECT_BASE_MS = 1000;
 export declare const RECONNECT_MAX_MS = 60000;
+/**
+ * Consecutive failed MQTT attempts before the listener stops treating the
+ * doorbell as reachable and runs on the periodic refetch alone.
+ *
+ * The doorbell is an OPTIMISATION, not the source of truth: policy
+ * hq-work-mesh-source-of-truth puts the work mesh behind REST, MQTT only
+ * carries ids, and `schedulePeriodic` already refetches on its own cadence. So
+ * a host that cannot reach AWS IoT is not a broken agent — it is an agent with
+ * a slower doorbell. Some bot sandboxes sit behind an egress proxy that
+ * intercepts the connection and answers with non-TLS bytes (observed on the
+ * Muse pilot: `tls_validate_record_header:wrong version number`, reconnecting
+ * forever while vend, inbox and heartbeat were all healthy). Before this, that
+ * host retried until the process died and reported component-mesh=error the
+ * whole time.
+ */
+export declare const MESH_FALLBACK_AFTER_ATTEMPTS = 5;
+/**
+ * How often polling mode re-tries MQTT. Long, because the usual cause is the
+ * network the host is on, which does not change minute to minute — but it is
+ * retried, so a bot moved to an unrestricted network recovers its instant
+ * doorbell without being reinstalled.
+ */
+export declare const MESH_FALLBACK_RETRY_MS: number;
 export declare function doorbellTopics(actorUid: string): string[];
 /**
  * Doorbell topics this session may subscribe to: the intersection of
@@ -68,7 +91,13 @@ export interface MeshListenerHandle {
     refetchNow: (reason: string) => Promise<void>;
     /** Simulate a doorbell (tests). */
     ring: (topic: string) => void;
-    state: () => "idle" | "connecting" | "subscribed" | "closed";
+    state: () => MeshListenerState;
 }
+/**
+ * `polling` is a healthy state: the doorbell is unreachable, so the cache is
+ * kept current by the periodic refetch alone. Incoming DMs are unaffected —
+ * the inbox poller is a separate service on its own interval.
+ */
+export type MeshListenerState = "idle" | "connecting" | "subscribed" | "polling" | "closed";
 export declare function startMeshListener(deps: MeshListenerDeps): Promise<MeshListenerHandle>;
 //# sourceMappingURL=mesh-listener.d.ts.map

package/dist/lib/agent-kit/run/mesh-listener.js

@@ -28,6 +28,29 @@ export const DOORBELL_KINDS = ["dm", "work", "sessions", "notifications", "inbox
 export const DOORBELL_DEBOUNCE_MS = 2_000;
 export const RECONNECT_BASE_MS = 1_000;
 export const RECONNECT_MAX_MS = 60_000;
+/**
+ * Consecutive failed MQTT attempts before the listener stops treating the
+ * doorbell as reachable and runs on the periodic refetch alone.
+ *
+ * The doorbell is an OPTIMISATION, not the source of truth: policy
+ * hq-work-mesh-source-of-truth puts the work mesh behind REST, MQTT only
+ * carries ids, and `schedulePeriodic` already refetches on its own cadence. So
+ * a host that cannot reach AWS IoT is not a broken agent — it is an agent with
+ * a slower doorbell. Some bot sandboxes sit behind an egress proxy that
+ * intercepts the connection and answers with non-TLS bytes (observed on the
+ * Muse pilot: `tls_validate_record_header:wrong version number`, reconnecting
+ * forever while vend, inbox and heartbeat were all healthy). Before this, that
+ * host retried until the process died and reported component-mesh=error the
+ * whole time.
+ */
+export const MESH_FALLBACK_AFTER_ATTEMPTS = 5;
+/**
+ * How often polling mode re-tries MQTT. Long, because the usual cause is the
+ * network the host is on, which does not change minute to minute — but it is
+ * retried, so a bot moved to an unrestricted network recovers its instant
+ * doorbell without being reinstalled.
+ */
+export const MESH_FALLBACK_RETRY_MS = 30 * 60_000;
 export function doorbellTopics(actorUid) {
     return DOORBELL_KINDS.map((k) => `hq/${actorUid}/${k}`);
 }
@@ -70,6 +93,12 @@ export async function startMeshListener(deps) {
             return createPersonalRealtimeFetcher({ token, baseUrl: deps.apiBaseUrl })();
         });
     let state = "idle";
+    /**
+     * The doorbell is unreachable and the periodic refetch is carrying the
+     * cache. Tracked separately from `state`, which follows the MQTT connection
+     * through every retry attempt.
+     */
+    let polling = false;
     let client = null;
     let stopped = false;
     let attempt = 0;
@@ -87,7 +116,11 @@ export async function startMeshListener(deps) {
             try {
                 const token = await deps.getToken();
                 await refetch(token, deps.agentUid);
-                writeComponentStatus(deps.paths, "mesh", state === "subscribed" ? "ok" : "error");
+                // Polling counts as healthy: the component's job is keeping the cache
+                // current, and in this mode it is doing exactly that, just on the
+                // periodic cadence instead of on a doorbell.
+                const healthy = state === "subscribed" || polling;
+                writeComponentStatus(deps.paths, "mesh", healthy ? "ok" : "error");
                 deps.log("info", `cache refetched (${reason})`);
             }
             catch (err) {
@@ -132,6 +165,25 @@ export async function startMeshListener(deps) {
     const scheduleReconnect = () => {
         if (stopped)
             return;
+        if (attempt >= MESH_FALLBACK_AFTER_ATTEMPTS) {
+            // Stop reporting an unreachable doorbell as a broken component, and stop
+            // hammering a connection this host cannot make. The periodic refetch
+            // carries the cache; MQTT is retried occasionally in case the network
+            // changes.
+            const wasPolling = polling;
+            polling = true;
+            if (!wasPolling) {
+                deps.log("warn", `mqtt unreachable after ${attempt} attempts; falling back to periodic refetch every ${deps.refreshMs}ms. ` +
+                    "Incoming DMs are unaffected (the inbox poller is a separate service). " +
+                    `Retrying mqtt in ${MESH_FALLBACK_RETRY_MS}ms.`);
+                void doRefetch("fallback");
+            }
+            setT(() => {
+                attempt = 0;
+                void connectOnce();
+            }, MESH_FALLBACK_RETRY_MS);
+            return;
+        }
         const delay = backoff(attempt, random);
         attempt += 1;
         deps.log("warn", `mqtt reconnect in ${delay}ms (attempt ${attempt})`);
@@ -149,7 +201,8 @@ export async function startMeshListener(deps) {
             }
         }
         catch (err) {
-            writeComponentStatus(deps.paths, "mesh", "error");
+            if (!polling)
+                writeComponentStatus(deps.paths, "mesh", "error");
             deps.log("error", `credential vend failed: ${err instanceof Error ? err.message : String(err)}`);
             scheduleReconnect();
             return;
@@ -182,6 +235,7 @@ export async function startMeshListener(deps) {
                 }
                 settled = true;
                 attempt = 0;
+                polling = false;
                 state = "subscribed";
                 writeComponentStatus(deps.paths, "mesh", "ok");
                 deps.log("info", `subscribed to ${topics.length} doorbell topics`);
@@ -207,7 +261,11 @@ export async function startMeshListener(deps) {
             client = null;
             const wasSubscribed = state === "subscribed";
             state = stopped ? "closed" : "idle";
-            writeComponentStatus(deps.paths, "mesh", "error");
+            // A close while polling is the periodic MQTT retry failing again; the
+            // periodic refetch is still doing the component's job, so it is not an
+            // error.
+            if (!polling)
+                writeComponentStatus(deps.paths, "mesh", "error");
             if (!settled || !wasSubscribed)
                 deps.log("warn", "mqtt closed before subscribe settled");
             scheduleReconnect();
@@ -232,7 +290,7 @@ export async function startMeshListener(deps) {
         },
         refetchNow: doRefetch,
         ring,
-        state: () => state,
+        state: () => (polling && state !== "subscribed" && state !== "closed" ? "polling" : state),
     };
 }
 //# sourceMappingURL=mesh-listener.js.map

package/dist/lib/billing/plan-lock.d.ts

@@ -41,6 +41,7 @@ export interface PlanLock {
 export interface PlanLockFixOptions {
     removeMembersTo: number;
     disconnectIntegrations: boolean;
+    disconnectIntegrationsTo?: number;
     removeSecretsTo?: number;
     deprovisionAgentsTo?: number;
 }
@@ -64,6 +65,12 @@ export interface PlanLockStatus {
 }
 /** Starter member cap quoted when the server did not send `removeMembersTo`. */
 export declare const STARTER_MEMBER_TARGET = 5;
+/**
+ * Starter integration cap quoted when the server did not send
+ * `disconnectIntegrationsTo`. One: Starter includes a single integration
+ * (US-020 owner decision 11, 2026-09-17 — it was zero before that).
+ */
+export declare const STARTER_INTEGRATION_TARGET = 1;
 /** Starter secret cap quoted when the server did not send `removeSecretsTo`. */
 export declare const STARTER_SECRET_TARGET = 10;
 /** Starter agent cap quoted when the server did not send `deprovisionAgentsTo`. */

package/dist/lib/billing/plan-lock.js

@@ -36,6 +36,12 @@ function isPlanLockReason(value) {
 }
 /** Starter member cap quoted when the server did not send `removeMembersTo`. */
 export const STARTER_MEMBER_TARGET = 5;
+/**
+ * Starter integration cap quoted when the server did not send
+ * `disconnectIntegrationsTo`. One: Starter includes a single integration
+ * (US-020 owner decision 11, 2026-09-17 — it was zero before that).
+ */
+export const STARTER_INTEGRATION_TARGET = 1;
 /** Starter secret cap quoted when the server did not send `removeSecretsTo`. */
 export const STARTER_SECRET_TARGET = 10;
 /** Starter agent cap quoted when the server did not send `deprovisionAgentsTo`. */
@@ -73,6 +79,7 @@ export function parsePlanLock(value) {
     }
     const fix = asRecord(rec.fixOptions);
     const removeMembersTo = finiteNumber(fix?.removeMembersTo) ?? STARTER_MEMBER_TARGET;
+    const disconnectIntegrationsTo = finiteNumber(fix?.disconnectIntegrationsTo);
     const removeSecretsTo = finiteNumber(fix?.removeSecretsTo);
     const deprovisionAgentsTo = finiteNumber(fix?.deprovisionAgentsTo);
     const fixOptions = {
@@ -81,6 +88,9 @@ export function parsePlanLock(value) {
     };
     // Absent stays absent: an omitted remedy target is UNKNOWN, and the renderer
     // quotes the published Starter cap rather than inventing a server answer.
+    if (disconnectIntegrationsTo !== null) {
+        fixOptions.disconnectIntegrationsTo = disconnectIntegrationsTo;
+    }
     if (removeSecretsTo !== null)
         fixOptions.removeSecretsTo = removeSecretsTo;
     if (deprovisionAgentsTo !== null) {
@@ -200,13 +210,16 @@ export function reasonLabel(reason) {
         case "users":
             return "too many members";
         case "integrations":
-            return "integrations are not included on Starter";
+            return "too many integrations";
         case "secrets":
             return "too many secrets";
         case "agents":
             return "agents are not included on Starter";
     }
 }
+function integrationTarget(lock) {
+    return lock.fixOptions.disconnectIntegrationsTo ?? STARTER_INTEGRATION_TARGET;
+}
 function secretTarget(lock) {
     return lock.fixOptions.removeSecretsTo ?? STARTER_SECRET_TARGET;
 }
@@ -219,7 +232,7 @@ function reasonRemedy(reason, lock) {
         case "users":
             return `remove members until you are at ${lock.fixOptions.removeMembersTo} or fewer`;
         case "integrations":
-            return "disconnect the workspace's integrations";
+            return `disconnect integrations until you are at ${integrationTarget(lock)} or fewer`;
         case "secrets":
             return `delete secrets until you are at ${secretTarget(lock)} or fewer`;
         case "agents": {
@@ -241,7 +254,7 @@ function reasonDetail(reason, status) {
                 : `over its ${target}-member limit`;
         }
         case "integrations":
-            return "integrations are not included on Starter";
+            return `over its ${integrationTarget(status.lock)}-integration limit`;
         case "secrets":
             return `over its ${secretTarget(status.lock)}-secret limit`;
         case "agents":
@@ -275,6 +288,9 @@ export function renderPlanLockNotice(status) {
             ? `  Members: ${members.used} of ${target}.`
             : `  Members allowed on Starter: ${target}.`);
     }
+    if (lock.reasons.includes("integrations")) {
+        lines.push(`  Integrations allowed on Starter: ${integrationTarget(lock)}.`);
+    }
     if (lock.reasons.includes("secrets")) {
         lines.push(`  Secrets allowed on Starter: ${secretTarget(lock)}.`);
     }

package/package.json

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