@indigoai-us/hq-cli 5.345.40 → 5.345.41

package/CHANGELOG.md

@@ -2,8 +2,13 @@
 
 ## [Unreleased]
 
+## [5.345.41] — 2026-10-07
+- Short-lived hq commands now use a fresh cached company flag snapshot while the registry refresh is pending.
+- Report failed and quota-interrupted keep-alive lead lanes as stranded in the keep-alive audit and `hq doctor`, with the senior recovery command and quota reset time.
+
 ## [5.345.40] — 2026-10-07
 - Fix published shell parity for rebuild-index company help and Git Bash trigger-facts stdin.
+- Add separate default-off gates: `client-health-show-manual-only` controls CLI remediation output, while `client-health-skip-manual-only-reports` suppresses other manual-only reports and writes a local family diagnostic; `sync.manifest` and `sync.runtime` reports remain filed, and failed automatic fixes remain reportable.
 
 ## [5.345.39] — 2026-10-07
 - Cap each `hq doctor --fix` invocation at two company journal refreshes and persist a rotating cursor so pending journals continue on later runs.

package/dist/lib/doctor/checks/stranded-lanes.d.ts

@@ -0,0 +1,7 @@
+/** Doctor alarm for failed lead lanes that are configured to keep running. */
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+export declare const STRANDED_LANES_FAMILY_ID = "stranded-lanes";
+export declare const STRANDED_LANES_FAMILY_TITLE = "Stranded lanes";
+export declare const strandedLanesFamily: CheckFamily;
+export declare function checkStrandedLanes(context: CheckContext): CheckResult[];
+//# sourceMappingURL=stranded-lanes.d.ts.map

package/dist/lib/doctor/checks/stranded-lanes.js

@@ -0,0 +1,45 @@
+/** Doctor alarm for failed lead lanes that are configured to keep running. */
+import { readAllLanes } from "../../lanes/store.js";
+export const STRANDED_LANES_FAMILY_ID = "stranded-lanes";
+export const STRANDED_LANES_FAMILY_TITLE = "Stranded lanes";
+export const strandedLanesFamily = {
+    id: STRANDED_LANES_FAMILY_ID,
+    title: STRANDED_LANES_FAMILY_TITLE,
+    run: (context) => Promise.resolve(checkStrandedLanes(context)),
+};
+export function checkStrandedLanes(context) {
+    let stranded;
+    try {
+        stranded = readAllLanes(context.hqRoot).filter((lane) => lane.depth === 0 && lane.keep_alive === true && (lane.state === "failed" ||
+            (lane.state === "interrupted" && lane.terminal_reason === "account_quota_exhausted")));
+    }
+    catch (error) {
+        return [{
+                status: "UNKNOWN",
+                checkId: "stranded-lanes.read-error",
+                message: `Could not inspect failed keep-alive lead lanes: ${error instanceof Error ? error.message : String(error)}`,
+            }];
+    }
+    if (stranded.length === 0) {
+        return [{
+                status: "PASS",
+                checkId: "stranded-lanes.none",
+                message: "No failed keep-alive lead lanes.",
+            }];
+    }
+    return stranded.map((lane) => {
+        const quotaExhausted = lane.terminal_reason === "account_quota_exhausted";
+        const state = lane.state;
+        return {
+            status: "FAIL",
+            checkId: `stranded-lanes.${lane.lane_id}`,
+            details: {
+                lane_id: lane.lane_id,
+                ...(lane.terminal_reason ? { terminal_reason: lane.terminal_reason } : {}),
+            },
+            message: `Keep-alive lead lane ${lane.lane_id} is ${state}${quotaExhausted ? " after account quota exhaustion" : ""}.`,
+            remediation: `Ask the senior to recover it with: hq lanes resume ${lane.lane_id} --from-failed --reason "recover stranded keep-alive lane"`,
+        };
+    });
+}
+//# sourceMappingURL=stranded-lanes.js.map

package/dist/lib/doctor/client-health-reason-codes-flag.d.ts

@@ -4,6 +4,10 @@ export declare const CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK = false;
 export declare const CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS = 150;
 export declare const CLIENT_HEALTH_CHECK_STATUS_FLAG = "client-health-sync-check-status";
 export declare const CLIENT_HEALTH_CHECK_STATUS_FLAG_FALLBACK = false;
+export declare const CLIENT_HEALTH_SHOW_MANUAL_ONLY_FLAG = "client-health-show-manual-only";
+export declare const CLIENT_HEALTH_SHOW_MANUAL_ONLY_FLAG_FALLBACK = false;
+export declare const CLIENT_HEALTH_SKIP_MANUAL_ONLY_REPORTS_FLAG = "client-health-skip-manual-only-reports";
+export declare const CLIENT_HEALTH_SKIP_MANUAL_ONLY_REPORTS_FLAG_FALLBACK = false;
 type ClientHealthFlagClient = Pick<FlagClient, "ready" | "isEnabled" | "close">;
 export interface ClientHealthReasonCodesFlagDependencies {
     env?: NodeJS.ProcessEnv;
@@ -25,6 +29,10 @@ export interface ClientHealthReasonCodesCompany {
 export declare function clientHealthReasonCodesEnabled(dependencies?: ClientHealthReasonCodesFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
 /** Resolve the separate status-report gate for the active company. */
 export declare function clientHealthCheckStatusEnabled(dependencies?: ClientHealthReasonCodesFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
+/** Resolve the default-off gate for showing manual-only doctor output. */
+export declare function clientHealthShowManualOnlyEnabled(dependencies?: ClientHealthReasonCodesFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
+/** Resolve the separate default-off gate for skipping manual-only reports. */
+export declare function clientHealthSkipManualOnlyReportsEnabled(dependencies?: ClientHealthReasonCodesFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
 /** Resolve the same default-off gate for one explicitly identified company. */
 export declare function clientHealthReasonCodesEnabledForCompany(company: ClientHealthReasonCodesCompany, dependencies?: ClientHealthReasonCodesFlagDependencies, callerSignal?: AbortSignal): Promise<boolean>;
 /** Resolve the separate default-off check-status gate for one company. */

package/dist/lib/doctor/client-health-reason-codes-flag.js

@@ -6,6 +6,10 @@ export const CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK = false;
 export const CLIENT_HEALTH_REASON_CODES_FLAG_TIMEOUT_MS = 150;
 export const CLIENT_HEALTH_CHECK_STATUS_FLAG = "client-health-sync-check-status";
 export const CLIENT_HEALTH_CHECK_STATUS_FLAG_FALLBACK = false;
+export const CLIENT_HEALTH_SHOW_MANUAL_ONLY_FLAG = "client-health-show-manual-only";
+export const CLIENT_HEALTH_SHOW_MANUAL_ONLY_FLAG_FALLBACK = false;
+export const CLIENT_HEALTH_SKIP_MANUAL_ONLY_REPORTS_FLAG = "client-health-skip-manual-only-reports";
+export const CLIENT_HEALTH_SKIP_MANUAL_ONLY_REPORTS_FLAG_FALLBACK = false;
 function safeErrorClass(error) {
     const name = error instanceof Error ? error.name : "UnknownError";
     return /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(name) ? name : "UnknownError";
@@ -44,6 +48,24 @@ export async function clientHealthCheckStatusEnabled(dependencies = {}, callerSi
         companySlug: env.HQ_COMPANY_SLUG?.trim() || undefined,
     }, dependencies, callerSignal);
 }
+/** Resolve the default-off gate for showing manual-only doctor output. */
+export async function clientHealthShowManualOnlyEnabled(dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const companyUid = env.HQ_COMPANY_UID?.trim() || "";
+    if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return CLIENT_HEALTH_SHOW_MANUAL_ONLY_FLAG_FALLBACK;
+    }
+    return clientHealthFlagEnabledForCompany(CLIENT_HEALTH_SHOW_MANUAL_ONLY_FLAG, CLIENT_HEALTH_SHOW_MANUAL_ONLY_FLAG_FALLBACK, { companyUid, companySlug: env.HQ_COMPANY_SLUG?.trim() || undefined }, dependencies, callerSignal);
+}
+/** Resolve the separate default-off gate for skipping manual-only reports. */
+export async function clientHealthSkipManualOnlyReportsEnabled(dependencies = {}, callerSignal) {
+    const env = dependencies.env ?? process.env;
+    const companyUid = env.HQ_COMPANY_UID?.trim() || "";
+    if (!/^cmp_[A-Za-z0-9]{3,128}$/.test(companyUid)) {
+        return CLIENT_HEALTH_SKIP_MANUAL_ONLY_REPORTS_FLAG_FALLBACK;
+    }
+    return clientHealthFlagEnabledForCompany(CLIENT_HEALTH_SKIP_MANUAL_ONLY_REPORTS_FLAG, CLIENT_HEALTH_SKIP_MANUAL_ONLY_REPORTS_FLAG_FALLBACK, { companyUid, companySlug: env.HQ_COMPANY_SLUG?.trim() || undefined }, dependencies, callerSignal);
+}
 /** Resolve the same default-off gate for one explicitly identified company. */
 export async function clientHealthReasonCodesEnabledForCompany(company, dependencies = {}, callerSignal) {
     return clientHealthFlagEnabledForCompany(CLIENT_HEALTH_REASON_CODES_FLAG, CLIENT_HEALTH_REASON_CODES_FLAG_FALLBACK, company, dependencies, callerSignal);

package/dist/lib/doctor/fix/apply.js

@@ -41,6 +41,7 @@ import { botDir } from "../../bot/paths.js";
 import { readBotConfig } from "../../bot/config.js";
 import { buildBotDaemonPaths, rewriteBotDaemonNodePath } from "../../bot/daemon.js";
 import { classifyRefreshSyncOutcome, } from "./refresh-sync-outcome.js";
+import { clientHealthShowManualOnlyEnabled } from "../client-health-reason-codes-flag.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export const HOOK_CONFIG_DIRS = [".claude", ".codex", ".grok"];
 /** Per-company bound for the default `hq sync pull` repair. */
@@ -117,6 +118,17 @@ export async function applyFixes(options) {
             return empty({ exitCode: 1, refused: "dirty-tree" });
         }
     }
+    // Resolve the customer-visible manual-only output gate once per fix run.
+    // Keep it behind the dirty-tree guard, and fail open to the pre-change
+    // output if the identity is absent or the registry lookup fails.
+    let showManualOnlyRemediations = false;
+    try {
+        showManualOnlyRemediations =
+            await clientHealthShowManualOnlyEnabled();
+    }
+    catch {
+        writeErr("HQ client-health manual-only flag lookup failed; keeping manual-only instructions hidden.\n");
+    }
     const collect = options.runChecks ?? defaultRunChecks;
     const refreshSync = options.refreshSync ?? defaultRefreshSync;
     const rewriteBotNodePath = options.rewriteBotNodePath ?? defaultRewriteBotNodePath;
@@ -174,6 +186,8 @@ export async function applyFixes(options) {
                 refused = "declined";
                 if (planned.length === 0) {
                     write("Aborted — no changes written.\n");
+                    if (showManualOnlyRemediations)
+                        writeManualOnlyRemediations(findings, write);
                     return empty({ refused, fixableCount });
                 }
                 write(`Pass ${pass} declined — no further changes written.\n`);
@@ -214,6 +228,8 @@ export async function applyFixes(options) {
     }
     if (planned.length === 0) {
         write("hq doctor --fix: nothing to repair — no auto-fixable findings.\n");
+        if (showManualOnlyRemediations)
+            writeManualOnlyRemediations(findings, write);
         return empty({ refused, fixableCount });
     }
     // Show each repair's final post-fix status, including work from earlier passes.
@@ -243,6 +259,8 @@ export async function applyFixes(options) {
     if (planned.at(-1)?.pass === MAX_FIX_PASSES && buildPlans(findings).length > 0) {
         write(`Stopped after ${MAX_FIX_PASSES} repair passes; new auto-fixable findings remain.\n`);
     }
+    if (showManualOnlyRemediations)
+        writeManualOnlyRemediations(findings, write);
     return {
         exitCode: 0,
         wrote: true,
@@ -254,6 +272,24 @@ export async function applyFixes(options) {
         applied,
     };
 }
+/** Print the available user action for findings that `--fix` deliberately skips. */
+function writeManualOnlyRemediations(findings, write) {
+    const manual = findings.flatMap((result) => {
+        const remediation = deriveRemediation(result);
+        return remediation && !remediation.autoFixable
+            ? [{ result, remediation }]
+            : [];
+    });
+    if (manual.length === 0)
+        return;
+    write("\nManual-only findings — complete these actions yourself:\n");
+    for (const { result, remediation } of manual) {
+        write(`  ${result.checkId}: ${remediation.action}\n`);
+        if (remediation.command.trim()) {
+            write(`    Command: ${remediation.command}\n`);
+        }
+    }
+}
 /** Run the default (read-only) check registry and flatten to a result list. */
 async function defaultRunChecks(hqRoot) {
     // `--fix` never repairs the integrations family (networked inventory), so

package/dist/lib/doctor/registry.js

@@ -25,6 +25,7 @@ import { workContextFamily } from "./checks/work-context.js";
 import { botsFamily } from "./checks/bots.js";
 import { anywhereFamily } from "./checks/anywhere.js";
 import { scaffoldCliFloorFamily } from "./checks/scaffold-cli-floor.js";
+import { strandedLanesFamily } from "./checks/stranded-lanes.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -266,6 +267,9 @@ export function createDefaultRegistry() {
     // HQ anywhere (US-012): pointer, registry, hqd service/socket/version,
     // heartbeat, MCP registrations and skill links. NA when not installed.
     registry.register(anywhereFamily);
+    // Failed keep-alive lead lanes cannot recover themselves; make them visible
+    // in the standard local doctor report with the senior recovery command.
+    registry.register(strandedLanesFamily);
     return registry;
 }
 //# sourceMappingURL=registry.js.map

package/dist/lib/flag-registry.js

@@ -142,6 +142,16 @@ export function kickFlagRegistryReadiness(dependencies = {}) {
     const sentry = dependencies.sentry;
     const companyUid = company.companyUid;
     const companyIdentifiers = [companyUid, company.companySlug].filter((value) => Boolean(value));
+    // Short-lived commands can reach a synchronous gate before the background
+    // worker receives the registry response. Hydrate only the validated,
+    // company-scoped persisted snapshot so those gates can use the last fresh
+    // decision immediately; the worker refresh below replaces it when available.
+    const persistedSnapshot = companyUid
+        ? readFlagSnapshotFile(companyUid, { env: companyEnv })
+        : null;
+    if (persistedSnapshot) {
+        heldSnapshot = { version: 0, flags: persistedSnapshot.flags };
+    }
     refreshCompletion = Promise.resolve();
     completeRefresh = null;
     refreshWorker = null;

package/dist/lib/lanes/keep-alive-audit.d.ts

@@ -1,4 +1,4 @@
-type KeepAliveAuditVerdict = "on_time" | "late" | "early_wake" | "message_wake" | "work_triggered" | "self_wake" | "early_by_keep_alive" | "restarted_untimed" | "not_restarted" | "keep_alive_off" | "waiting";
+type KeepAliveAuditVerdict = "on_time" | "late" | "early_wake" | "message_wake" | "work_triggered" | "self_wake" | "early_by_keep_alive" | "restarted_untimed" | "not_restarted" | "stranded" | "keep_alive_off" | "waiting";
 interface KeepAliveAuditRestart {
     at: string | null;
     trigger: string;
@@ -12,15 +12,18 @@ interface KeepAliveAuditRow {
     stopped_at: string;
     next_check_at: string | null;
     due_at: string;
-    due_reason: "next_check_at" | "backoff";
+    due_reason: "next_check_at" | "backoff" | "quota_reset_at";
     restart: KeepAliveAuditRestart | null;
     blocked_outcome?: "woken" | "skipped";
     blocked_outcome_reason?: string;
     verdict: KeepAliveAuditVerdict;
+    remediation?: string;
+    terminal_reason?: string;
 }
 interface KeepAliveAuditSummary {
     by_verdict: Record<KeepAliveAuditVerdict, number>;
     not_restarted: number;
+    stranded: number;
     restarted_untimed: number;
     late_restarts_after_window: number;
     late_over_10m: number;

package/dist/lib/lanes/keep-alive-audit.js

@@ -4,7 +4,7 @@ import { LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS, LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_M
 import { LanesError } from "./errors.js";
 import { laneRunDir } from "./spawn.js";
 import { compareEnvelopeNames } from "./envelope-sequence.js";
-import { listQuestionIds, readAllLanes, tryReadQuestion } from "./store.js";
+import { laneRecordPath, listQuestionIds, readAllLanes, tryReadQuestion } from "./store.js";
 import { isIsoDateTime } from "./types.js";
 function readTerminalClassifications(hqRoot, laneId) {
     const root = fs.realpathSync(hqRoot);
@@ -62,6 +62,7 @@ const VERDICTS = [
     "restarted_untimed",
     "keep_alive_off",
     "not_restarted",
+    "stranded",
     "waiting",
 ];
 function parseTime(value) {
@@ -70,6 +71,17 @@ function parseTime(value) {
     const parsed = Date.parse(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
+function isStrandedKeepAliveLead(lane) {
+    return lane.depth === 0 && lane.keep_alive === true && (lane.state === "failed" ||
+        (lane.state === "interrupted" && lane.terminal_reason === "account_quota_exhausted"));
+}
+function strandedTerminalTime(lane) {
+    if (lane.state === "interrupted")
+        return parseTime(lane.interrupted_at);
+    if (lane.state === "failed")
+        return parseTime(lane.terminal_details?.failed_at);
+    return undefined;
+}
 function readLaneWorkerResumeEvents(hqRoot, laneId) {
     const root = fs.realpathSync(hqRoot);
     const eventsPath = path.join(laneRunDir(root, laneId), "watcher", "events.jsonl");
@@ -491,9 +503,45 @@ export function buildKeepAliveAudit(input) {
         .filter((entry) => entry !== null)
         .sort((a, b) => a.lane.localeCompare(b.lane));
     const lanes = allLanes.filter((lane) => (input.laneId === undefined || lane.lane_id === input.laneId) &&
-        typeof lane.hire_grant === "number" && Number.isFinite(lane.hire_grant) && lane.hire_grant > 0);
+        (isStrandedKeepAliveLead(lane) || (typeof lane.hire_grant === "number" && Number.isFinite(lane.hire_grant) && lane.hire_grant > 0)));
     const rows = [];
     const errors = [];
+    for (const lane of lanes) {
+        if (!isStrandedKeepAliveLead(lane))
+            continue;
+        const terminalAt = strandedTerminalTime(lane);
+        if (terminalAt === undefined) {
+            errors.push({
+                lane: lane.lane_id,
+                error: "keep_alive_audit_terminal_time_missing",
+                path: laneRecordPath(input.hqRoot, lane.lane_id),
+                message: `Cannot determine terminal transition time for stranded keep-alive lead ${lane.lane_id}.`,
+            });
+            continue;
+        }
+        if (terminalAt < sinceMs || terminalAt > nowMs)
+            continue;
+        const dueCandidates = [
+            { at: parseTime(lane.last_envelope?.next_check_at), reason: "next_check_at" },
+            { at: parseTime(lane.keep_alive_next_eligible_at), reason: "backoff" },
+            { at: parseTime(lane.terminal_details?.quota_reset_at) ?? parseTime(lane.quota_reset_at), reason: "quota_reset_at" },
+        ].filter((candidate) => candidate.at !== undefined);
+        dueCandidates.sort((a, b) => b.at - a.at);
+        const due = dueCandidates[0] ?? { at: terminalAt, reason: "backoff" };
+        rows.push({
+            lane: lane.lane_id,
+            project: lane.project_id,
+            profile: lane.worker_profile ?? lane.worker ?? null,
+            stopped_at: iso(terminalAt),
+            next_check_at: lane.last_envelope?.next_check_at ?? null,
+            due_at: iso(due.at),
+            due_reason: due.reason,
+            restart: null,
+            verdict: "stranded",
+            ...(lane.terminal_reason === undefined ? {} : { terminal_reason: lane.terminal_reason }),
+            remediation: `Ask the senior to run: hq lanes resume ${lane.lane_id} --from-failed --reason "recover stranded keep-alive lane"`,
+        });
+    }
     for (const lane of lanes) {
         try {
             const { allMtimes, stops } = readStopEnvelopes(input.hqRoot, lane.lane_id);
@@ -561,6 +609,7 @@ export function buildKeepAliveAudit(input) {
         summary: {
             by_verdict: byVerdict,
             not_restarted: byVerdict.not_restarted,
+            stranded: byVerdict.stranded,
             restarted_untimed: byVerdict.restarted_untimed,
             late_restarts_after_window: lateRestartsAfterWindow,
             late_over_10m: lateOverTenMinutes,
@@ -592,8 +641,9 @@ export function formatKeepAliveAuditText(result) {
         ...values.map(tableLine),
         "",
         `Since ${result.since}; ${counts}`,
-        `not_restarted=${result.summary.not_restarted}, late_restarts_after_window=${result.summary.late_restarts_after_window}, late_over_10m=${result.summary.late_over_10m}, early_wake_by_others=${result.summary.early_wake_by_others}, self_wake=${result.summary.self_wake}`,
+        `not_restarted=${result.summary.not_restarted}, stranded=${result.summary.stranded}, late_restarts_after_window=${result.summary.late_restarts_after_window}, late_over_10m=${result.summary.late_over_10m}, early_wake_by_others=${result.summary.early_wake_by_others}, self_wake=${result.summary.self_wake}`,
         `Stopped and not restarted on their own: ${result.summary.stopped_and_not_restarted_on_their_own}`,
+        ...result.rows.filter((row) => row.remediation).map((row) => `Stranded ${row.lane}: ${row.remediation}`),
         ...result.companyless_lead_lanes.map((lane) => `Company-less lead ${lane.lane} (${lane.project}): ${lane.reason}; repair with hq lanes repair-company ${lane.lane} --company <slug>`),
         ...result.errors.map((error) => `Error ${error.lane} (${error.error}) at ${error.path}: ${error.message}`),
     ].join("\n");

package/dist/lib/lanes/spawn.js

@@ -1511,7 +1511,7 @@ export function markSpawnFailure(hqRoot, laneId, reasonRaw, details, options = {
             queued_at: undefined,
             admission_reserved_at: undefined,
             terminal_reason: reason,
-            terminal_details: details,
+            terminal_details: resumableQuotaHold ? details : { ...details, failed_at: new Date().toISOString() },
             ...(resumableQuotaHold
                 ? {
                     ...(options.pendingResume !== undefined

package/dist/sentry-init.d.ts

@@ -2,6 +2,7 @@ import type { NodeOptions } from "@sentry/node";
 type SentryModule = typeof import("@sentry/node");
 type SentryBreadcrumb = Parameters<SentryModule["addBreadcrumb"]>[0];
 /** Shared Sentry SDK setup for the command graph and isolated fast handlers. */
+export declare function createFlaggedBeforeSend(beforeSend: NodeOptions["beforeSend"], skipManualOnlyReportsEnabled?: () => Promise<boolean>): NonNullable<NodeOptions["beforeSend"]>;
 export declare function initSentryRuntime(beforeSend: NodeOptions["beforeSend"], overrides?: Partial<Pick<NodeOptions, "transport">>, pendingBreadcrumbs?: readonly SentryBreadcrumb[]): SentryModule | undefined;
 export declare function finishSentryRuntimeSession(): void;
 export declare function addSentryRuntimeBreadcrumb(breadcrumb: SentryBreadcrumb): void;

package/dist/sentry-init.js

@@ -3,13 +3,116 @@ import { BUNDLED_DSN } from "./sentry-dsn.generated.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { beforeBreadcrumb } from "./utils/breadcrumb-buffer.js";
 import { getCachedSentryUser } from "./utils/sentry-identity.js";
-const requireSentry = createRequire(import.meta.url);
+const requireRuntime = createRequire(import.meta.url);
 let sentryModule;
 function loadSentryModule() {
-    sentryModule ??= requireSentry("@sentry/node");
+    sentryModule ??= requireRuntime("@sentry/node");
     return sentryModule;
 }
 /** Shared Sentry SDK setup for the command graph and isolated fast handlers. */
+export function createFlaggedBeforeSend(beforeSend, skipManualOnlyReportsEnabled = resolveManualOnlyReportSkip) {
+    return async (event, hint) => {
+        if (event.tags?.sentry_event_type === "client_health" &&
+            event.tags.fix_outcome === "not_auto_fixable") {
+            const checkIds = clientHealthCheckIds(event);
+            // Sync-family reports detect an open sync P0. Keep filing them until
+            // the operator declares that P0 closed.
+            if (checkIds.length === 0 ||
+                checkIds.some((id) => MANUAL_ONLY_DROP_FAMILY_PREFIXES.some((prefix) => matchesCheckFamily(id, prefix)))) {
+                return beforeSend ? beforeSend(event, hint) : event;
+            }
+            let skipManualOnlyReport = false;
+            try {
+                skipManualOnlyReport = await skipManualOnlyReportsEnabled();
+            }
+            catch {
+                // The default-off gate fails open to the prior reporting behavior.
+                process.stderr.write("HQ client-health manual-only report flag lookup failed; keeping current reporting behavior.\n");
+            }
+            if (skipManualOnlyReport) {
+                recordSkippedManualOnlyReport(checkIds);
+                return null;
+            }
+        }
+        return beforeSend ? beforeSend(event, hint) : event;
+    };
+}
+const MANUAL_ONLY_DROP_FAMILY_PREFIXES = [
+    "sync.manifest",
+    "sync.runtime",
+    "sync.journal",
+];
+function clientHealthCheckIds(event) {
+    try {
+        const tags = event.tags;
+        const extra = event.extra;
+        const rawValues = [
+            tags?.check_ids,
+            tags?.check_id,
+            tags?.checkIds,
+            tags?.checkId,
+            tags?.check_class,
+            extra?.check_ids,
+            extra?.check_id,
+            extra?.checkIds,
+            extra?.checkId,
+        ];
+        const ids = new Set();
+        let hasUnparseableValue = false;
+        for (const raw of rawValues) {
+            if (raw === undefined || raw === null)
+                continue;
+            const candidates = Array.isArray(raw)
+                ? raw
+                : typeof raw === "string"
+                    ? raw.split(/[\s,]+/).filter(Boolean)
+                    : [];
+            if (candidates.length === 0) {
+                hasUnparseableValue = true;
+                continue;
+            }
+            for (const candidate of candidates) {
+                if (typeof candidate === "string" &&
+                    /^[A-Za-z0-9][A-Za-z0-9_-]*(?:\.[A-Za-z0-9][A-Za-z0-9_-]*)+$/.test(candidate)) {
+                    ids.add(candidate);
+                }
+                else {
+                    hasUnparseableValue = true;
+                }
+            }
+        }
+        return hasUnparseableValue ? [] : [...ids];
+    }
+    catch {
+        return [];
+    }
+}
+function matchesCheckFamily(checkId, prefix) {
+    return checkId === prefix || checkId.startsWith(`${prefix}.`);
+}
+function recordSkippedManualOnlyReport(checkIds) {
+    try {
+        const families = new Set();
+        for (const checkId of checkIds) {
+            for (const prefix of MANUAL_ONLY_DROP_FAMILY_PREFIXES) {
+                if (matchesCheckFamily(checkId, prefix)) {
+                    families.add(prefix);
+                }
+            }
+        }
+        const familyList = [...families].sort().join(", ") || "unknown";
+        process.stderr.write(`HQ client-health manual-only report skipped; check families: ${familyList}.\n`);
+    }
+    catch {
+        // A local diagnostic must not change the decision to drop this event.
+    }
+}
+async function resolveManualOnlyReportSkip() {
+    // Keep this runtime lookup out of native fast-entry bundles. A static or
+    // dynamic import pulls the flag client and its fetch usage into the closure.
+    const flagModule = requireRuntime("./lib/doctor/client-health-reason-codes-flag.js");
+    return flagModule.clientHealthSkipManualOnlyReportsEnabled();
+}
 export function initSentryRuntime(beforeSend, overrides = {}, pendingBreadcrumbs = []) {
     const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
     if (!dsn)
@@ -23,7 +126,7 @@ export function initSentryRuntime(beforeSend, overrides = {}, pendingBreadcrumbs
         release: `hq-cli@${CLI_VERSION}`,
         environment: process.env.HQ_CLI_ENV ?? "production",
         initialScope: { tags: { repo: "hq-cli" } },
-        beforeSend,
+        beforeSend: createFlaggedBeforeSend(beforeSend),
         beforeBreadcrumb,
         integrations: (defaults) => defaults.filter((integration) => integration.name !== "ProcessSession"),
         ...overrides,

package/dist/utils/resident-package-preload.js

@@ -1,8 +1,8 @@
 import { releaseCurrentPackageUseLease, releasePackageUseLeaseAfterResidentPreload, } from "./package-use-lease.js";
 /** Runtime modules that resident commands may need after a wait starts. */
 export const RESIDENT_PACKAGE_MODULES = {
-    "agent-kit": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
-    "agent-mcp": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "../commands/access.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "../utils/local-files-overview.js", "@indigoai-us/hq-cloud"],
+    "agent-kit": ["../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "agent-mcp": ["../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "../commands/access.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "../utils/local-files-overview.js", "@indigoai-us/hq-cloud"],
     login: [
         "../lib/mesh/api.js",
         "../lib/work-context/config.js",
@@ -10,7 +10,7 @@ export const RESIDENT_PACKAGE_MODULES = {
         "../lib/work-context/paths.js",
         "../lib/plan-limit-nag.js",
         "../utils/plan-gate-error.js",
-        "../sentry.js",
+        "../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client",
         "open",
         "../utils/cognito-session.js",
         "../lib/first-sync-next-step.js",
@@ -21,16 +21,16 @@ export const RESIDENT_PACKAGE_MODULES = {
         "../lib/daemon/mcp-oauth.js",
         "../lib/plan-limit-nag.js",
         "../utils/plan-gate-error.js",
-        "../sentry.js",
+        "../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client",
         "open",
         "../utils/cognito-session.js",
         "@indigoai-us/hq-cloud",
     ],
-    "agents-terminal": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "agents-terminal": ["../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
     bot: [
         "../lib/flag-registry.js",
         "../commands/access.js",
-        "../sentry.js",
+        "../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client",
         "../lib/plan-limit-nag.js",
         "../utils/plan-gate-error.js",
         "open",
@@ -40,12 +40,12 @@ export const RESIDENT_PACKAGE_MODULES = {
         "@indigoai-us/hq-cloud",
     ],
     "bot-logs-follow": [],
-    mcp: ["../lib/mcp/tools.js", "../lib/mcp/prompts.js", "../utils/cognito-session.js", "@indigoai-us/hq-cloud", "../sentry.js"],
+    mcp: ["../lib/mcp/tools.js", "../lib/mcp/prompts.js", "../utils/cognito-session.js", "@indigoai-us/hq-cloud", "../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client"],
     childWrapper: ["../main.js"],
     coreJobRun: ["../lib/flag-registry.js"],
     "daemon-call": ["../lib/daemon/protocol.js"],
     daemon: [
-        "../sentry.js",
+        "../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client",
         "../utils/cognito-session.js",
         "../lib/plan-limit-nag.js",
         "../utils/plan-gate-error.js",
@@ -58,17 +58,17 @@ export const RESIDENT_PACKAGE_MODULES = {
         "@indigoai-us/hq-cloud",
     ],
     "daemon-logs-follow": [],
-    "mesh-daemon": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
-    "lanes-watch": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
-    "monitor-wait": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
-    "monitor-run": ["../commands/lanes.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "../sentry.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
-    "agents-message-wait": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
-    "integrations-oauth-wait": ["../sentry.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
-    "outpost-wait": ["../commands/lanes.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "../sentry.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "mesh-daemon": ["../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "lanes-watch": ["../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "monitor-wait": ["../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "monitor-run": ["../commands/lanes.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "agents-message-wait": ["../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "integrations-oauth-wait": ["../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
+    "outpost-wait": ["../commands/lanes.js", "../lib/plan-limit-nag.js", "../utils/plan-gate-error.js", "../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "open", "../utils/cognito-session.js", "../lib/first-sync-next-step.js", "@indigoai-us/hq-cloud"],
     "secrets-sandbox": [],
-    "pkg-update": ["../sentry.js", "../utils/cognito-session.js", "@indigoai-us/hq-cloud"],
+    "pkg-update": ["../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client", "../utils/cognito-session.js", "@indigoai-us/hq-cloud"],
     "pack-install": [
-        "../sentry.js",
+        "../sentry.js", "../lib/doctor/client-health-reason-codes-flag.js", "@indigoai-us/hq-flags-client",
         "../lib/plan-limit-nag.js",
         "../utils/plan-gate-error.js",
         "open",
@@ -87,6 +87,8 @@ const LOADERS = {
     "agent-kit": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../lib/plan-limit-nag.js"),
@@ -99,6 +101,8 @@ const LOADERS = {
     "agent-mcp": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../lib/plan-limit-nag.js"),
@@ -119,6 +123,8 @@ const LOADERS = {
         () => import("../utils/plan-gate-error.js"),
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("open"),
@@ -133,6 +139,8 @@ const LOADERS = {
         () => import("../utils/plan-gate-error.js"),
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("open"),
@@ -142,6 +150,8 @@ const LOADERS = {
     "agents-terminal": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../lib/plan-limit-nag.js"),
@@ -156,6 +166,8 @@ const LOADERS = {
         () => import("../commands/access.js"),
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../lib/plan-limit-nag.js"),
@@ -174,6 +186,8 @@ const LOADERS = {
         () => import("@indigoai-us/hq-cloud"),
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
     ],
@@ -189,6 +203,8 @@ const LOADERS = {
     daemon: [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../utils/cognito-session.js"),
@@ -206,6 +222,8 @@ const LOADERS = {
     "mesh-daemon": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../lib/plan-limit-nag.js"),
@@ -218,6 +236,8 @@ const LOADERS = {
     "lanes-watch": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../lib/plan-limit-nag.js"),
@@ -230,6 +250,8 @@ const LOADERS = {
     "monitor-wait": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../lib/plan-limit-nag.js"),
@@ -245,6 +267,8 @@ const LOADERS = {
         () => import("../utils/plan-gate-error.js"),
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("open"),
@@ -255,6 +279,8 @@ const LOADERS = {
     "agents-message-wait": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../lib/plan-limit-nag.js"),
@@ -267,6 +293,8 @@ const LOADERS = {
     "integrations-oauth-wait": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../lib/plan-limit-nag.js"),
@@ -282,6 +310,8 @@ const LOADERS = {
         () => import("../utils/plan-gate-error.js"),
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("open"),
@@ -293,6 +323,8 @@ const LOADERS = {
     "pkg-update": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../utils/cognito-session.js"),
@@ -301,6 +333,8 @@ const LOADERS = {
     "pack-install": [
         async () => {
             const { preloadSentrySdk } = await import("../sentry.js");
+            await import("../lib/doctor/client-health-reason-codes-flag.js");
+            await import("@indigoai-us/hq-flags-client");
             preloadSentrySdk();
         },
         () => import("../lib/plan-limit-nag.js"),

package/package.json

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