@indigoai-us/hq-cli 5.345.58 → 5.345.59

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [5.345.59] — 2026-10-09
+- Keep conduct-mode SessionStart injection out of unattended sessions unless `HQ_AUTO_CONDUCT` explicitly forces it on.
+- Back off the external agent-kit inbox poller from 15 seconds to 30 seconds after repeated empty polls, reset to 15 seconds when a message is mirrored, and stop promptly on SIGTERM or SIGINT with a 10-second deadline for stalled shutdowns. The default-on `agents.inbox-poll-backoff-agent-kit` hq-flags kill switch preserves the regular cadence when disabled; installed services retain a configured `HQ_FLAGS_API_URL`.
+
+- Fix loop-lane recovery: retries receive the fixed per-attempt phase budget; withdrawn and stalled IDs can be reused; `interrupt --story/--phase` targets matching work; and stall answers resume through the controller.
+- `hq db usage --app` says when a deleted app's database was removed, how long its data is kept, and that it is not billed, instead of showing usage and an estimate.
+- `hq db sql --app` and `hq db dump --app` say a deleted app's database was removed, or that the app has no database, instead of "not available yet".
+- `hq billing status` lists database apps: how many are active, the $10 monthly price, overage per app this month, whether the company is exempt, and which subscription carries the charge.
+- Installed Claude and Codex provider wrappers now bypass HQ when the daemon's refreshed runtime flag or person setting is revoked, using a per-user marker under the HQ registry directory.
+- Lane updates preserve completed stories and lead-set states while applying lane progress in order.
+- `hq lanes resume --story` can clear a prior unacknowledged story-switch note.
+
 ## [5.345.58] — 2026-10-09
 - hq access now accepts `--as <member>` to view another member's access, read-only.
 

package/dist/command-catalog.generated.d.ts

@@ -12935,6 +12935,14 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--reason <text>";
             readonly description: "Record the reason in the lane's stop history";
             readonly hidden: false;
+        }, {
+            readonly flags: "--story <id>";
+            readonly description: "Withdraw only this story's queued phases (loop lanes only)";
+            readonly hidden: false;
+        }, {
+            readonly flags: "--phase <name>";
+            readonly description: "Limit --story interruption to one phase";
+            readonly hidden: false;
         }, {
             readonly flags: "--json";
             readonly description: "JSON on stdout (always)";

package/dist/command-catalog.generated.js

@@ -15741,6 +15741,16 @@ export const COMMAND_CATALOG = [
                         "description": "Record the reason in the lane's stop history",
                         "hidden": false
                     },
+                    {
+                        "flags": "--story <id>",
+                        "description": "Withdraw only this story's queued phases (loop lanes only)",
+                        "hidden": false
+                    },
+                    {
+                        "flags": "--phase <name>",
+                        "description": "Limit --story interruption to one phase",
+                        "hidden": false
+                    },
                     {
                         "flags": "--json",
                         "description": "JSON on stdout (always)",

package/dist/commands/agent-kit.js

@@ -30,6 +30,7 @@ import { isKitService, KIT_SERVICES, enabledKitServices, kitServiceSpec, kitServ
 import { writeKitSkills } from "../lib/agent-kit/skills.js";
 import { runHeartbeatLoop } from "../lib/agent-kit/run/heartbeat.js";
 import { runInboxLoop } from "../lib/agent-kit/run/inbox.js";
+import { createKitStopController } from "../lib/agent-kit/run/stop-signals.js";
 import { superviseKitServices } from "../lib/agent-kit/run/supervisor.js";
 import { fallbackStatus, rebootCrontabLine, ensureRebootCrontab, shouldUseFallback, startFallback, stopFallback, } from "../lib/agent-kit/fallback.js";
 import { serviceLogPath } from "../lib/agent-kit/paths.js";
@@ -182,17 +183,26 @@ export async function runKitService(service, rt) {
                 credsSource: rt.credsSource ?? "default",
             });
             return;
-        case "inbox":
-            await runInboxLoop({
-                paths: rt.paths,
-                agentUid: rt.creds.entityUid,
-                apiBaseUrl: rt.creds.apiBaseUrl,
-                pollMs: rt.config.inboxPollMs,
-                ack: rt.config.inboxAck,
-                getToken: rt.getToken,
-                log: rt.log,
-            });
+        case "inbox": {
+            const stop = createKitStopController();
+            try {
+                await runInboxLoop({
+                    paths: rt.paths,
+                    agentUid: rt.creds.entityUid,
+                    apiBaseUrl: rt.creds.apiBaseUrl,
+                    pollMs: rt.config.inboxPollMs,
+                    ack: rt.config.inboxAck,
+                    getToken: rt.getToken,
+                    log: rt.log,
+                    companySlug: rt.creds.companySlug,
+                    signal: stop.signal,
+                });
+            }
+            finally {
+                stop.dispose();
+            }
             return;
+        }
     }
 }
 /** `kit run all`: supervise the kit services as child processes with restart backoff. */

package/dist/commands/billing.d.ts

@@ -16,5 +16,18 @@
  *                                                         answer such a request
  */
 import { Command } from "commander";
+interface DatabaseBilling {
+    period: string;
+    activeApps: number;
+    pricePerAppCents: number;
+    exempt: boolean;
+    chargedOn: "team" | "dedicated" | "existing" | null;
+    apps: Array<{
+        appId: string;
+        overageCents: number;
+    }>;
+}
+export declare function formatDatabaseBilling(db: DatabaseBilling | null | undefined): string[];
 export declare function registerBillingCommand(program: Command): void;
+export {};
 //# sourceMappingURL=billing.d.ts.map

package/dist/commands/billing.js

@@ -21,6 +21,35 @@ import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 import { mintPaymentLink } from "../utils/billing-gate.js";
 import { upgradeToTeam } from "../utils/team-upgrade.js";
 import { registerBillingSponsorCommands } from "./billing-sponsor.js";
+const CHARGED_ON = {
+    team: "the Team subscription",
+    dedicated: "the separate HQ database apps subscription",
+    existing: "the company's existing subscription",
+};
+function dollars(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}
+export function formatDatabaseBilling(db) {
+    if (db === undefined)
+        return [];
+    if (db === null)
+        return [`${chalk.bold("Database apps")}: could not be read right now`];
+    const lines = [
+        `${chalk.bold("Database apps")}: ${db.activeApps} active, ${dollars(db.pricePerAppCents)} a month each`,
+    ];
+    if (db.exempt) {
+        lines.push("  Not billed: this company is exempt from database app charges.");
+    }
+    else if (db.activeApps > 0) {
+        lines.push(db.chargedOn
+            ? `  Charged on ${CHARGED_ON[db.chargedOn]}.`
+            : "  Not on a subscription yet. The charge is added on the next billing sync.");
+    }
+    for (const app of db.apps) {
+        lines.push(`  ${app.appId}: ${dollars(app.overageCents)} overage so far in ${db.period}`);
+    }
+    return lines;
+}
 function fail(err) {
     console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
     process.exit(1);
@@ -69,6 +98,8 @@ export function registerBillingCommand(program) {
                 console.log(`${chalk.bold("Card")}: ${chalk.yellow("no card on file")} — ` +
                     `run \`hq billing checkout\` to add one before provisioning paid resources.`);
             }
+            for (const line of formatDatabaseBilling(summary.databases))
+                console.log(line);
         }
         catch (err) {
             fail(err);

package/dist/commands/db-dump.js

@@ -8,8 +8,8 @@ import { dumpRemoteSchema, openRemoteAppConnection } from "../lib/db/remote-engi
 import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { defaultRemoteDeps, describeRemoteError, remoteEngineDeps, resolveAppId, } from "./db-remote-deps.js";
 export function describeSessionGap(error) {
-    const status = error.status;
-    if (status === 404 || status === 405) {
+    const { status, code } = error;
+    if ((status === 404 || status === 405) && !code) {
         return "Remote database access for apps is not available yet. The HQ API has no database session route.";
     }
     return null;

package/dist/commands/db-remote-deps.js

@@ -71,6 +71,12 @@ export function describeRemoteError(error) {
     if (status === 404 && code === "DB_USAGE_NOT_PROVISIONED") {
         return "This company has no remote database yet. Run hq db provision first.";
     }
+    if (status === 404 && code === "DB_APP_REMOVED") {
+        return "This app's database was removed, so it can't be opened. Run hq db usage --app <app> to see how long its data is kept.";
+    }
+    if (status === 404 && code === "DB_APP_NOT_FOUND") {
+        return "This app has no database in this company. Check the app name, or deploy it with database enabled.";
+    }
     if (status === 404 && code === "DB_USAGE_APP_NOT_FOUND") {
         return "No database found for that app in this company. Check the app name, or deploy it with database enabled.";
     }

package/dist/commands/lanes-loop.js

@@ -176,12 +176,13 @@ export async function runLaneLoopController(ctx, laneId, deps) {
                     signal.removeEventListener("abort", abortPhase);
                 }
             },
-            raiseQuestion: ({ envelope, envelopeId, attempt, error }) => {
+            raiseQuestion: ({ envelope, envelopeId, attempt, error, questionId }) => {
                 const current = readLane(hqRoot, laneId);
                 const data = envelope;
                 raiseLaneQuestion({
                     hqRoot,
                     lane: current,
+                    questionId,
                     raisedVia: "cli",
                     at: ctx.now().toISOString(),
                     body: {
@@ -189,6 +190,7 @@ export async function runLaneLoopController(ctx, laneId, deps) {
                         context: `${error}\nThe phase is parked; later envelopes remain queued. Stall attempt: ${attempt}.`,
                         options: ["Retry with a longer deadline", "Reroute to another worker", "Drop this phase and block the story"],
                         recommended: "Retry with a longer deadline",
+                        loop_stall: { lane_id: laneId, envelope_id: envelopeId, attempt },
                     },
                 });
             },

package/dist/commands/lanes-questions.js

@@ -1,9 +1,11 @@
+import * as path from "node:path";
 import { buildOutpostQuestionAnswerCommand, buildOutpostQuestionCancelCommand, buildOutpostQuestionShowCommand, dispatchErrorMessage } from "../lib/lanes/outpost-dispatch.js";
 import { assertNoSecretText } from "../lib/lanes/text-scan.js";
 import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
 import { appendCappedHistory, createQuestion, isLanesError, listSessionLiveness, parseLivenessState, parseQuestionRecord, parseQuestionStatus, readDaemonPresenceConnected, readLane, readQuestion, wakeAnsweredLaneNow, sessionLiveness, appendDropboxMessage, answerDropboxMessage, laneAcceptsDropboxDelivery, laneIdForAnswerDelivery, writeQuestionBody } from "../lib/lanes/index.js";
 import { resolveQuestionCompanyWithFallback } from "../lib/lanes/questions.js";
 import { LanesError } from "../lib/lanes/errors.js";
+import { applyLoopStallAnswer } from "../lib/lanes/loop.js";
 export function resolveAnswerChoice(choice, options, freeform) {
     const trimmed = choice.trim();
     if (/^[0-9]+$/.test(trimmed)) {
@@ -854,6 +856,20 @@ export function createLaneQuestionsHandlers(deps) {
                 },
             };
         });
+        if (body.loop_stall?.lane_id === askingLane.lane_id && askingLane.loop_mode === true) {
+            const resolved = applyLoopStallAnswer({
+                runDir: path.join(hqRoot, "workspace", "lanes-runs", askingLane.lane_id),
+                questionId,
+                choice,
+                ...(opts.notes ? { notes: opts.notes } : {}),
+                at,
+            });
+            if (!resolved)
+                throw new LanesError("loop_stall_result_missing", `Loop stall result for question ${questionId} is missing`, { question_id: questionId, lane_id: askingLane.lane_id });
+            const controllerPid = await deps.restartLoopController(ctx, askingLane.lane_id);
+            printJson({ ok: true, action: "questions.answer", lane_id: askingLane.lane_id, question: updated, loop_action: resolved.action, controller_pid: controllerPid });
+            return;
+        }
         const latestAskingLane = readLane(hqRoot, askingLane.lane_id);
         if (latestAskingLane.state === "awaiting_input") {
             let wake;

package/dist/commands/lanes-session-start.js

@@ -16,6 +16,18 @@ function enabledFromSettings(root) {
     const value = /^\s+default_enabled:\s*["']?(true|false|yes|no|on|off|1|0)["']?\s*(?:#.*)?$/mi.exec(block)?.[1]?.toLowerCase();
     return value === "true" || value === "yes" || value === "on" || value === "1";
 }
+function isUnattended(env) {
+    const flags = `${env.HQ_UNATTENDED ?? ""}${env.HQ_SESSION_UNATTENDED ?? ""}${env.CLAUDE_HEADLESS ?? ""}`;
+    if (["1", "true", "TRUE", "yes", "YES", "on", "ON"].some((marker) => flags.includes(marker)))
+        return true;
+    return [
+        env.HQ_BOT_AGENT_UID,
+        env.HQ_MACHINE_CREDS_FILE,
+        env.HQ_AGENT_CLAUDE_TASKFILE,
+        env.HQ_AGENT_COMPANY_DIR,
+        env.HQ_AGENT_STATUS_FILE,
+    ].some((marker) => Boolean(marker));
+}
 function sessionWasDisabled(root, env, payloadSessionId) {
     const sessionId = payloadSessionId || env.HQ_SESSION_ID;
     if (!sessionId || !/^[A-Za-z0-9_-]+$/.test(sessionId))
@@ -169,11 +181,15 @@ export async function runLaneSessionStart(options = {}) {
         (options.startSweep ?? ((r, e) => startSessionStartOrphanSweep(r, e, spawn)))(root, env);
         if (sessionWasDisabled(root, env, payloadSessionId))
             return;
+        const autoConduct = env.HQ_AUTO_CONDUCT ?? "";
+        const forceOn = /^(1|true|on|yes)$/i.test(autoConduct);
+        if (/^(0|false|off|no)$/i.test(autoConduct))
+            return;
+        if (!forceOn && isUnattended(env))
+            return;
         let enabled = enabledFromSettings(root);
-        if (/^(1|true|on|yes)$/i.test(env.HQ_AUTO_CONDUCT ?? ""))
+        if (forceOn)
             enabled = true;
-        else if (/^(0|false|off|no)$/i.test(env.HQ_AUTO_CONDUCT ?? ""))
-            enabled = false;
         if (!enabled)
             return;
         const core = path.join(root, ".claude", "skills", "conduct", "conductor-core.md");

package/dist/commands/lanes-shared.d.ts

@@ -474,6 +474,7 @@ export interface LaneQuestionsHandlerDeps {
     printJson(value: unknown): void;
     readSessionMeta(hqRoot: string, sessionId: string, ctx: Ctx): Record<string, unknown> | null;
     reconcileHostFromCtx(ctx: Ctx): ReconcileHost;
+    restartLoopController(ctx: Ctx, laneId: string): Promise<number>;
     resolveActiveQuestionCompany(ctx: Ctx, message?: string): Promise<LaneCompanyRef>;
     resolveAudience(hqRoot: string, question: QuestionRecord, ctx: Ctx): SeniorRef;
     sameQuestionAnswer(left: QuestionAnswer | undefined, right: QuestionAnswer): boolean;

package/dist/commands/lanes.d.ts

@@ -7,7 +7,7 @@
  */
 import { Command } from "commander";
 import type { MonitorLaneMessagePayload, MonitorLaneMessageResult } from "./lanes-message.js";
-import { type LanesMesh, type OutpostRouteIdentity, type SpawnLoginResult } from "./lanes-shared.js";
+import { type Ctx, type LanesMesh, type OutpostRouteIdentity, type SpawnLoginResult } from "./lanes-shared.js";
 export type { LanesMesh, SpawnLoginResult } from "./lanes-shared.js";
 export { CLAUDE_ACCOUNT_BALANCE_SIGNALS_FLAG, LANE_OUTPOST_LOAD_BALANCING_FLAG } from "./lanes-shared.js";
 export { resolveAnswerChoice } from "./lanes-questions.js";
@@ -36,6 +36,8 @@ export interface LanesCommandDeps {
     onLaneWorkerStarted?: (laneId: string, command: "message" | "resume") => void;
     /** Test seam for failures after a message is durably queued. */
     onLaneMessageQueued?: (laneId: string, path: "admission" | "account_move" | "quota_hold") => void;
+    /** Test seam for routing loop stall answers back through their controller. */
+    restartLoopController?: (ctx: Ctx, laneId: string) => Promise<number>;
     hqRoot?: () => string;
     /** Start HQ-root walk here instead of process.cwd(). Tests only. */
     cwd?: () => string;

package/dist/commands/lanes.js

@@ -43,7 +43,7 @@ import { appendProjectFocusOverride, readProjectStoryFocusData, removeProjectFoc
 import { appendLaneFocusOverride, assertFocusGuardAllows, makeFocusOverride } from "../lib/lanes/focus-guard.js";
 import { LANE_FOCUS_GUARD_FLAG, LANE_FOCUS_DASHBOARD_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, LANE_PROFILE_PIN_EXHAUSTED_FALLBACK_FLAG, LANE_STATUS_ROW_FIELDS_FLAG, LANE_REAP_STOP_FLAG, LANE_REUSE_REFRESHES_PROFILE_FLAG, LANE_WORKER_CONTINUITY_FLAG, LANE_CONDUCT_LOOP_FLAG, } from "../lib/lanes/flag-keys.js";
 import { findWorkerContinuityLane, sameLaneHost, workerContinuityPrompt } from "../lib/lanes/worker-continuity.js";
-import { enqueueLoopEnvelope, interruptLoopQueue, loopControllerIsAlive, loopStatus, validateLoopEnvelope } from "../lib/lanes/loop.js";
+import { enqueueLoopEnvelope, interruptLoopQueue, interruptLoopQueueForStory, loopControllerIsAlive, loopStatus, validateLoopEnvelope } from "../lib/lanes/loop.js";
 import { runLaneLoopController, startLaneLoopController } from "./lanes-loop.js";
 import { configuredCodexRolloutHomes, retainCodexRollouts } from "../lib/lanes/disk-guard.js";
 import { isControllerAliasOutpostId } from "../lib/lanes/admission-host.js";
@@ -580,6 +580,13 @@ export function parseQuestionBody(raw) {
         return null;
     if (obj.notes !== undefined && typeof obj.notes !== "string")
         return null;
+    if (obj.loop_stall !== undefined && (typeof obj.loop_stall !== "object" || obj.loop_stall === null || Array.isArray(obj.loop_stall) ||
+        typeof obj.loop_stall.lane_id !== "string" ||
+        typeof obj.loop_stall.envelope_id !== "string" ||
+        typeof obj.loop_stall.attempt !== "number" ||
+        !Number.isSafeInteger(obj.loop_stall.attempt) ||
+        obj.loop_stall.attempt < 1))
+        return null;
     const options = obj.options.filter((item) => typeof item === "string");
     const body = {
         question: obj.question,
@@ -590,6 +597,8 @@ export function parseQuestionBody(raw) {
         body.recommended = obj.recommended;
     if (typeof obj.notes === "string")
         body.notes = obj.notes;
+    if (obj.loop_stall !== undefined)
+        body.loop_stall = obj.loop_stall;
     return body;
 }
 function readQuestionBodyFile(hqRoot, question) {
@@ -8614,6 +8623,29 @@ async function runInterrupt(ctx, laneId, reason, options = {}) {
         throw new LanesError("interrupt_remote_unsupported", `Lane ${laneId} runs on Outpost ${lane.host.id}; run hq lanes interrupt on that Outpost`, { lane_id: laneId, outpost_id: lane.host.id });
     }
     assertLaneRunsHereForOperatorMutation(ctx, lane, "interrupt");
+    if (options.story !== undefined && lane.loop_mode !== true) {
+        throw new LanesError("usage_error", "--story is only supported for loop lanes", { lane_id: laneId });
+    }
+    if (options.phase !== undefined && options.story === undefined) {
+        throw new LanesError("usage_error", "--phase requires --story", { lane_id: laneId });
+    }
+    if (lane.loop_mode === true && options.story !== undefined) {
+        const scoped = interruptLoopQueueForStory(runDir(hqRoot, lane.lane_id), options.story, options.phase);
+        if (scoped.already_picked_up.length === 0 || lane.state !== "running") {
+            if (!options.quiet)
+                printJson({ ok: true, action: "interrupt", lane_id: lane.lane_id, terminal: false, resumable: true, ...scoped });
+            return;
+        }
+        options = { ...options, preserveLoopQueue: true };
+        // The matching active phase uses the same provider interruption path as a deadline abort.
+        if (!reason)
+            reason = "story-scoped loop phase interrupt";
+        const remaining = scoped;
+        await runInterrupt(ctx, laneId, reason, { preserveLoopQueue: true, quiet: true });
+        if (!options.quiet)
+            printJson({ ok: true, action: "interrupt", lane_id: lane.lane_id, terminal: false, resumable: true, ...remaining });
+        return;
+    }
     const queueInterrupt = lane.loop_mode === true && options.preserveLoopQueue !== true
         ? interruptLoopQueue(runDir(hqRoot, lane.lane_id))
         : undefined;
@@ -9390,6 +9422,22 @@ export function registerLanesCommand(parent, deps = {}) {
         printJson,
         readSessionMeta,
         reconcileHostFromCtx,
+        restartLoopController: async (handlerCtx, laneId) => {
+            if (deps.restartLoopController)
+                return deps.restartLoopController(handlerCtx, laneId);
+            const current = readLane(handlerCtx.hqRoot(), laneId);
+            if (current.state === "running") {
+                await runInterrupt(handlerCtx, laneId, "loop stall question answered; restarting controller", { preserveLoopQueue: true, quiet: true });
+            }
+            const runDirPath = runDir(handlerCtx.hqRoot(), laneId);
+            if (loopControllerIsAlive(runDirPath)) {
+                const pid = loopStatus(runDirPath, laneId).pid;
+                if (pid === undefined)
+                    throw new LanesError("loop_controller_pid_missing", `Loop controller for ${laneId} is alive without a recorded pid`, { lane_id: laneId });
+                return pid;
+            }
+            return startLaneLoopController(handlerCtx, laneId);
+        },
         resolveActiveQuestionCompany,
         resolveAudience,
         sameQuestionAnswer,
@@ -10034,8 +10082,10 @@ export function registerLanesCommand(parent, deps = {}) {
         .description("Stop a running lane's turn and keep it resumable with hq lanes resume")
         .argument("<lane-id>", "Lane id")
         .option("--reason <text>", "Record the reason in the lane's stop history")
+        .option("--story <id>", "Withdraw only this story's queued phases (loop lanes only)")
+        .option("--phase <name>", "Limit --story interruption to one phase")
         .action(wrap(async (laneId, options) => {
-        await runInterrupt(ctx, laneId, options.reason);
+        await runInterrupt(ctx, laneId, options.reason, options);
     }));
     lanes
         .command("approve")

package/dist/lib/agent-kit/inbox-poll-backoff-flag.d.ts

@@ -0,0 +1,19 @@
+import { type FlagClient, type FlagClientOptions } from "@indigoai-us/hq-flags-client";
+export declare const AGENT_KIT_INBOX_BACKOFF_FLAG = "agents.inbox-poll-backoff-agent-kit";
+export declare const AGENT_KIT_INBOX_BACKOFF_DEFAULT = true;
+export declare const AGENT_KIT_INBOX_BACKOFF_CACHE_MS: number;
+export declare const AGENT_KIT_INBOX_BACKOFF_TIMEOUT_MS = 2000;
+type InboxBackoffFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
+export interface AgentKitInboxBackoffFlagDependencies {
+    companySlug?: string;
+    getToken: FlagClientOptions["getToken"];
+    createClient?: (options: FlagClientOptions) => InboxBackoffFlagClient;
+    endpoint?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+    reportFailure?: (error: unknown) => void;
+}
+/** Read the default-on kill switch; registry outages preserve idle backoff. */
+export declare function createAgentKitInboxBackoffFlagReader(dependencies: AgentKitInboxBackoffFlagDependencies): () => Promise<boolean>;
+export {};
+//# sourceMappingURL=inbox-poll-backoff-flag.d.ts.map

package/dist/lib/agent-kit/inbox-poll-backoff-flag.js

@@ -0,0 +1,70 @@
+import { createFlagClient, } from "@indigoai-us/hq-flags-client";
+import { resolveFlagGate } from "../flag-registry.js";
+import { resolveFlagRegistryEndpoint } from "../flag-registry-endpoint.js";
+export const AGENT_KIT_INBOX_BACKOFF_FLAG = "agents.inbox-poll-backoff-agent-kit";
+export const AGENT_KIT_INBOX_BACKOFF_DEFAULT = true;
+export const AGENT_KIT_INBOX_BACKOFF_CACHE_MS = 3 * 60_000;
+export const AGENT_KIT_INBOX_BACKOFF_TIMEOUT_MS = 2_000;
+/** Read the default-on kill switch; registry outages preserve idle backoff. */
+export function createAgentKitInboxBackoffFlagReader(dependencies) {
+    const createClient = dependencies.createClient ?? createFlagClient;
+    const now = dependencies.now ?? Date.now;
+    const report = dependencies.reportFailure ?? ((error) => {
+        const name = error instanceof Error ? error.name : "UnknownError";
+        process.stderr.write(`HQ agent-kit inbox backoff flag lookup failed (${name}); keeping the default-on behavior.\n`);
+    });
+    let cachedValue = AGENT_KIT_INBOX_BACKOFF_DEFAULT;
+    let lastReadAt = Number.NEGATIVE_INFINITY;
+    let pending = null;
+    const read = async () => {
+        let client;
+        let failed = false;
+        const reportOnce = (error) => {
+            if (failed)
+                return;
+            failed = true;
+            report(error);
+        };
+        try {
+            client = createClient({
+                endpoint: resolveFlagRegistryEndpoint(dependencies.endpoint),
+                ...(dependencies.companySlug ? { companyIdentifiers: [dependencies.companySlug] } : {}),
+                env: {},
+                getToken: dependencies.getToken,
+                ...(dependencies.fetch ? { fetch: dependencies.fetch } : {}),
+                refreshIntervalMs: 0,
+                requestTimeoutMs: AGENT_KIT_INBOX_BACKOFF_TIMEOUT_MS,
+                onError: reportOnce,
+            });
+            await client.ready();
+            cachedValue = failed
+                ? AGENT_KIT_INBOX_BACKOFF_DEFAULT
+                : resolveFlagGate(client, AGENT_KIT_INBOX_BACKOFF_FLAG, { fallback: AGENT_KIT_INBOX_BACKOFF_DEFAULT }, () => AGENT_KIT_INBOX_BACKOFF_DEFAULT);
+        }
+        catch (error) {
+            reportOnce(error);
+            cachedValue = AGENT_KIT_INBOX_BACKOFF_DEFAULT;
+        }
+        finally {
+            try {
+                client?.close();
+            }
+            catch (error) {
+                reportOnce(error);
+                cachedValue = AGENT_KIT_INBOX_BACKOFF_DEFAULT;
+            }
+        }
+        return cachedValue;
+    };
+    return () => {
+        const currentTime = now();
+        if (pending)
+            return pending;
+        if (currentTime - lastReadAt < AGENT_KIT_INBOX_BACKOFF_CACHE_MS)
+            return Promise.resolve(cachedValue);
+        lastReadAt = currentTime;
+        pending = read().finally(() => { pending = null; });
+        return pending;
+    };
+}
+//# sourceMappingURL=inbox-poll-backoff-flag.js.map

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

@@ -21,6 +21,7 @@ import { type WakeConfig, type WakeDeps, type WakeNotice, type WakeResult } from
 export declare const SEEN_IDS_NAME = "seen-ids.json";
 export declare const INBOX_JSONL_NAME = "inbox.jsonl";
 export declare const MAX_SEEN_IDS = 5000;
+export declare const INBOX_POLL_BACKOFF_MAX_MS = 30000;
 export interface InboxItem {
     id: string;
     raw: Record<string, unknown>;
@@ -38,10 +39,13 @@ export interface InboxDeps {
     ack: boolean;
     getToken: () => Promise<string>;
     log: KitLogger;
-    fetchInbox?: (token: string) => Promise<InboxFetchResult>;
+    fetchInbox?: (token: string, signal?: AbortSignal) => Promise<InboxFetchResult>;
     ackItem?: (token: string, id: string) => Promise<number>;
     warmCache?: (token: string, agentUid: string) => Promise<unknown>;
-    sleep?: (ms: number) => Promise<void>;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    readInboxBackoffEnabled?: () => Promise<boolean>;
+    signal?: AbortSignal;
+    companySlug?: string;
     maxPolls?: number;
     /** Override wake config lookup (tests). `null` disables the wake. */
     wakeConfig?: WakeConfig | null;
@@ -66,7 +70,7 @@ export interface InboxFetchResult {
 export declare function agentApiUrl(apiBaseUrl: string, route: string): string;
 export declare function agentInboxUrl(apiBaseUrl: string, agentUid: string): string;
 export declare function truncateBody(text: string, max?: number): string;
-export declare function defaultFetchInbox(agentUid: string, apiBaseUrl: string): (token: string) => Promise<InboxFetchResult>;
+export declare function defaultFetchInbox(agentUid: string, apiBaseUrl: string): (token: string, signal?: AbortSignal) => Promise<InboxFetchResult>;
 export declare function defaultAckItem(agentUid: string, apiBaseUrl: string): (token: string, id: string) => Promise<number>;
 export declare function pollInboxOnce(deps: InboxDeps): Promise<{
     ok: boolean;

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

@@ -21,10 +21,12 @@ import { vaultApiFetch } from "../../../utils/vault-api.js";
 import { writeComponentStatus } from "../creds.js";
 import { pendingInbox } from "../inbox-state.js";
 import { writePrivateFile } from "./../private-file.js";
+import { createAgentKitInboxBackoffFlagReader } from "../inbox-poll-backoff-flag.js";
 import { buildWakeNotice, currentWakeState, fireWake, readWakeConfig, shouldWake, } from "../wake.js";
 export const SEEN_IDS_NAME = "seen-ids.json";
 export const INBOX_JSONL_NAME = "inbox.jsonl";
 export const MAX_SEEN_IDS = 5000;
+export const INBOX_POLL_BACKOFF_MAX_MS = 30_000;
 /** Pull `{id}` out of each server item; items without a string id are dropped. */
 export function extractInboxItems(body) {
     const rec = body && typeof body === "object" ? body : {};
@@ -107,12 +109,13 @@ export function truncateBody(text, max = INBOX_ERROR_BODY_MAX) {
     return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
 }
 export function defaultFetchInbox(agentUid, apiBaseUrl) {
-    return async (token) => {
+    return async (token, signal) => {
         const url = new URL(agentInboxUrl(apiBaseUrl, agentUid));
         const res = await vaultApiFetch({
             token,
             baseUrl: url.origin,
             path: url.pathname,
+            ...(signal ? { signal } : {}),
         });
         const text = await res.text().catch(() => "");
         let body;
@@ -137,6 +140,8 @@ export function defaultAckItem(agentUid, apiBaseUrl) {
     };
 }
 export async function pollInboxOnce(deps) {
+    if (deps.signal?.aborted)
+        return { ok: false, mirrored: 0 };
     const fetchInbox = deps.fetchInbox ?? defaultFetchInbox(deps.agentUid, deps.apiBaseUrl);
     const ackItem = deps.ackItem ?? defaultAckItem(deps.agentUid, deps.apiBaseUrl);
     // No default cache warm: the human conversation routes 403 for agent callers.
@@ -152,9 +157,11 @@ export async function pollInboxOnce(deps) {
     }
     let res;
     try {
-        res = await fetchInbox(token);
+        res = await fetchInbox(token, deps.signal);
     }
     catch (err) {
+        if (deps.signal?.aborted)
+            return { ok: false, mirrored: 0 };
         writeComponentStatus(deps.paths, "inbox", "error");
         deps.log("error", `inbox fetch failed: GET ${agentInboxUrl(deps.apiBaseUrl, deps.agentUid)}: ${err instanceof Error ? err.message : String(err)}`);
         return { ok: false, mirrored: 0 };
@@ -218,14 +225,46 @@ async function maybeWake(deps, freshCount) {
     }
 }
 export async function runInboxLoop(deps) {
-    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const sleep = deps.sleep ?? ((ms, signal) => new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const timer = setTimeout(done, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            done();
+        };
+        function done() {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }
+        signal?.addEventListener("abort", abort, { once: true });
+    }));
+    const readBackoffEnabled = deps.readInboxBackoffEnabled ?? createAgentKitInboxBackoffFlagReader({
+        companySlug: deps.companySlug,
+        getToken: deps.getToken,
+    });
     let polls = 0;
-    for (;;) {
-        await pollInboxOnce(deps);
+    let consecutiveEmptyPolls = 0;
+    while (!deps.signal?.aborted) {
+        const result = await pollInboxOnce(deps);
         polls += 1;
         if (deps.maxPolls !== undefined && polls >= deps.maxPolls)
             return;
-        await sleep(deps.pollMs);
+        if (deps.signal?.aborted)
+            return;
+        if (!result.ok || result.mirrored > 0)
+            consecutiveEmptyPolls = 0;
+        const enabled = await readBackoffEnabled();
+        const delay = enabled && result.ok && result.mirrored === 0 && consecutiveEmptyPolls > 0
+            ? Math.min(deps.pollMs * 2 ** consecutiveEmptyPolls, Math.max(deps.pollMs, INBOX_POLL_BACKOFF_MAX_MS))
+            : deps.pollMs;
+        if (enabled && result.ok && result.mirrored === 0)
+            consecutiveEmptyPolls += 1;
+        else
+            consecutiveEmptyPolls = 0;
+        if (deps.signal?.aborted)
+            return;
+        await sleep(delay, deps.signal);
     }
 }
 //# sourceMappingURL=inbox.js.map