@indigoai-us/hq-cli 5.103.23 → 5.103.25

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [5.103.25] — 2026-08-27
+
+### Fixed
+
+- Codex Stop hooks now record their automatic checkpoint out of band after a
+  user-facing reply has already been delivered, avoiding the visible
+  `Hook re-prompted Codex` filler message while preserving the missing-reply
+  safety gate.
+
+## [5.103.24] — 2026-08-27
+
 ## [5.103.23] — 2026-08-26
 
 ### Changed

package/assets/scaffold/core/scripts/checkpoint-stop-gate.sh

@@ -490,6 +490,32 @@ set -uo pipefail
     exit 0
   fi
 
+  # A turn whose user-facing reply is ALREADY delivered cannot be blocked into
+  # silence. Hosts re-prompt an assistant turn that produces no visible text
+  # ("your previous response had no visible output"), so blocking here forces a
+  # trailing filler message — the very double-messaging this gate exists to
+  # prevent. Every wording tried so far only shrank that filler (full
+  # restatement, then a meta-note, then a bare <br>); none removed it, because
+  # the instruction asks for a turn shape the host will not accept.
+  #
+  # So do not ask. Let the turn end and record the checkpoint out-of-band. The
+  # payload carries the transcript, which is what the sibling already reads to
+  # derive files, decisions and learnings, so the record keeps its substance
+  # without an agent-authored summary. Turns that checkpoint BEFORE replying
+  # never reach this branch and keep the full hand-written payload; the
+  # reply-required gate above still runs first, so a turn with no reply at all
+  # is unaffected.
+  if [ "$replied" = 1 ]; then
+    (nohup hq core checkpoint \
+       --session-id "$session_id" \
+       --trigger stop-gate-auto \
+       --transcript "$transcript_path" \
+       --summary "turn ended with its user-facing reply already delivered" \
+       >/dev/null 2>&1 &)
+    rm -f "$block_count_file" 2>/dev/null || true
+    exit 0
+  fi
+
   # Loop guard for the missing-checkpoint demand below: cap consecutive blocks
   # per session, then fail open (see the counter's comment above).
   if [ "$block_count" -ge 3 ]; then
@@ -500,18 +526,12 @@ set -uo pipefail
   # Built with printf rather than concatenation so the session id can appear in
   # both commands without re-splitting the message into fragments.
   #
-  # Two variants, chosen from the transcript rather than left to the agent's
-  # judgment: a single instruction either demanded a full restatement
-  # (double-messaging hosts that render pre-tool text) or forbade
-  # post-checkpoint text (hiding the reply when the agent had not yet written
-  # one). The transcript already tells us which case we are in, so say exactly
-  # one thing.
+  # Only the not-yet-replied case reaches here — a delivered reply took the
+  # out-of-band branch above — so this instruction never has to forbid a
+  # restatement, and the agent's reply lands in final position where every host
+  # renders it in full.
   flags_spec='  hq core checkpoint --session-id %s --trigger stop-gate --summary "<what changed, in one line>" [--file <path>] [--decision "<choice and why>"] [--learning "<reusable rule>"] [--next "<outstanding step>"]\n\nOnly --summary is required, and the repeatable flags are what the sibling uses to enrich the record, distil policies and update the indexes — a bare summary gives it almost nothing to work with. Write them as machine record, not prose for the user, and pass each one that genuinely applies:\n  --file      every path you created or modified this turn\n  --decision  a choice you made that a reader would otherwise have to reverse-engineer\n  --learning  a rule that changes how someone acts next time, not a restatement of what just happened\n  --next      work that is genuinely still outstanding\nOmit a flag rather than padding it: an empty or invented learning is worse than none.\n\nIf this turn only read or inspected things and changed no state, the correct call instead is:\n\n  hq core checkpoint --session-id %s --idle'
-  if [ "$replied" = 1 ]; then
-    reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint before it can end.\n\nYour user-facing reply is ALREADY delivered — the message you just wrote is visible to the user. Do NOT send it again, in full or summarized: repeating it double-messages the user, which is exactly the bug this gate guards against.\n\nTHE SIBLING (a background maintenance agent) reads only the checkpoint payload, never your chat reply — anything it needs must go into the flags.\n\nRun the checkpoint now as the FINAL action of the turn and end the turn immediately after it, adding no further text:\n\n'"$flags_spec" "$session_id" "$session_id")"
-  else
-    reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. You have not sent one yet this turn — everything you owe them (results, links, answers, status, decisions) must go into it. The checkpoint is invisible to them and does NOT count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nORDER: run the checkpoint FIRST, then deliver your complete user-facing reply as the FINAL text of the turn — final-position text is the one placement every host renders in full. Every link, URL, instruction, command, and decision the user needs must appear in that final message. The gate enforces this: a turn that ends without a user-facing reply is blocked until the reply is delivered.\n\n'"$flags_spec" "$session_id" "$session_id")"
-  fi
+  reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. You have not sent one yet this turn — everything you owe them (results, links, answers, status, decisions) must go into it. The checkpoint is invisible to them and does NOT count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nORDER: run the checkpoint FIRST, then deliver your complete user-facing reply as the FINAL text of the turn — final-position text is the one placement every host renders in full. Every link, URL, instruction, command, and decision the user needs must appear in that final message. The gate enforces this: a turn that ends without a user-facing reply is blocked until the reply is delivered.\n\n'"$flags_spec" "$session_id" "$session_id")"
 
   # Codex surfaces a blocked Stop reason as a synthetic user prompt. Preserve
   # the actionable instruction out-of-band, then use the stable marker covered

package/dist/commands/doctor.d.ts

@@ -7,10 +7,9 @@
  *     to every check.
  *   - Running outside any HQ tree exits non-zero with a message naming exactly
  *     what it looked for — never a throw, never a false PASS.
- *   - The command performs no network calls and needs no authentication; it is
- *     purely a function of the on-disk shape of the tree. `--live-runtimes` is
- *     the one opt-in exception: it probes the installed AI CLIs (claude, codex,
- *     grok) with a version read and a one-line prompt.
+ *   - Most families inspect the local tree. The integrations family makes one
+ *     control-plane inventory read for the active company, without invoking a
+ *     provider tool. `--live-runtimes` is the opt-in AI CLI probe.
  *
  * US-015 adds reporting, `--json`, and the exit-code contract: the exit code is
  * 0 unless some result is FAIL or UNKNOWN (WARN/UNTESTED/NA/KNOWN-DEFECT never
@@ -86,6 +85,10 @@ export interface RunDoctorOptions {
      * family reports UNTESTED rather than spawning anything.
      */
     liveRuntimes?: boolean;
+    /** Company slug for the integrations family; omitted uses active membership. */
+    company?: string;
+    /** Internal test seam; production CLI always runs integrations checks. */
+    integrations?: boolean;
 }
 /** The outcome of a doctor run, returned rather than thrown so it is testable. */
 export interface RunDoctorResult {
@@ -98,7 +101,8 @@ export interface RunDoctorResult {
 }
 /**
  * Resolve the HQ root, run every registered check family against it, and render
- * a plain-text summary. Makes no network calls and needs no authentication.
+ * a plain-text summary. The integrations family makes one bounded inventory
+ * read; all other default tiers remain local unless explicitly opted in.
  */
 export declare function runDoctor(options?: RunDoctorOptions): Promise<RunDoctorResult>;
 /** Register the top-level `hq doctor` command so it appears in `hq --help`. */

package/dist/commands/doctor.js

@@ -7,10 +7,9 @@
  *     to every check.
  *   - Running outside any HQ tree exits non-zero with a message naming exactly
  *     what it looked for — never a throw, never a false PASS.
- *   - The command performs no network calls and needs no authentication; it is
- *     purely a function of the on-disk shape of the tree. `--live-runtimes` is
- *     the one opt-in exception: it probes the installed AI CLIs (claude, codex,
- *     grok) with a version read and a one-line prompt.
+ *   - Most families inspect the local tree. The integrations family makes one
+ *     control-plane inventory read for the active company, without invoking a
+ *     provider tool. `--live-runtimes` is the opt-in AI CLI probe.
  *
  * US-015 adds reporting, `--json`, and the exit-code contract: the exit code is
  * 0 unless some result is FAIL or UNKNOWN (WARN/UNTESTED/NA/KNOWN-DEFECT never
@@ -79,7 +78,8 @@ function isHqRoot(dir) {
 }
 /**
  * Resolve the HQ root, run every registered check family against it, and render
- * a plain-text summary. Makes no network calls and needs no authentication.
+ * a plain-text summary. The integrations family makes one bounded inventory
+ * read; all other default tiers remain local unless explicitly opted in.
  */
 export async function runDoctor(options = {}) {
     const write = options.stdout ?? ((chunk) => void process.stdout.write(chunk));
@@ -102,6 +102,8 @@ export async function runDoctor(options = {}) {
         platform: { id: platform.id, evidence: platform.evidence },
         sessionId: options.sessionId,
         liveRuntimes: options.liveRuntimes === true,
+        company: options.company,
+        integrations: options.integrations !== false,
     };
     const families = await registry.run(context);
     // `--deep-test` (US-008): after the read-only tiers, actually fire pure-guard
@@ -150,13 +152,14 @@ export async function runDoctor(options = {}) {
 export function registerDoctorCommand(program) {
     program
         .command("doctor")
-        .description("Verify HQ hook guardrails are wired and firing (read-only, offline; --live-runtimes adds networked AI CLI probes).")
+        .description("Verify HQ hook wiring, runtimes, and connection health (read-only; integrations uses one control-plane inventory read).")
         .option("--json", "Emit the machine-readable JSON document (no colour).")
         .option("--verbose", "Also print every PASS result in text output.")
         .option("--no-color", "Disable ANSI colour even on a TTY.")
         .option("--session-id <id>", "Scope the runtime probe's ledger check to this exact session.")
         .option("--deep-test", "Also fire pure-guard hooks through the real gate under all three profiles (sandboxed).")
         .option("--live-runtimes", "Also probe each installed AI CLI (claude, codex, grok) with a one-line prompt to verify login and subscription (networked; uses your subscriptions).")
+        .option("--company <slug>", "Company slug for integrations checks (otherwise resolves your single active company).")
         .option("--fix", "Apply the allowlisted safe repairs (backs up first; read-only without this flag).")
         .option("--yes", "Skip the interactive --fix confirmation (non-interactive use).")
         .option("--force", "Let --fix run despite uncommitted changes under .claude/, .codex/, or .grok/.")
@@ -204,6 +207,7 @@ export function registerDoctorCommand(program) {
             sessionId: opts.sessionId,
             deepTest: opts.deepTest === true,
             liveRuntimes: opts.liveRuntimes === true,
+            company: opts.company,
         });
         // Set the exit code rather than calling process.exit, so the CLI's
         // normal shutdown (telemetry flush) still runs. Non-zero means either an

package/dist/lib/doctor/checks/integrations.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Company integration health for `hq doctor`.
+ *
+ * This family makes one authenticated read of HQ's connection inventory. It
+ * never calls an integration gateway or provider tool, so it cannot mutate
+ * data, spend provider quota, or trigger provider rate limits. It classifies
+ * stored health signals only: a recorded rejection overrides a misleading
+ * `connected` status, but a clean connected row is not live-provider proof.
+ */
+import { type AdminConnection } from "../../../commands/integrations-core.js";
+import type { CheckContext, CheckFamily, CheckResult } from "../types.js";
+export declare const INTEGRATIONS_FAMILY_ID = "integrations";
+export declare const INTEGRATIONS_PREFIX = "integrations";
+/** Additive health fields returned by newer control planes. */
+export interface IntegrationConnection extends AdminConnection {
+    errorReason?: string;
+    degradedReason?: string;
+    needsReauthReason?: string;
+    /** Server-derived remediation flow; optional for older control planes. */
+    fix_path?: string;
+}
+export interface IntegrationsDoctorDeps {
+    ensureToken?: () => Promise<string>;
+    resolveCompany?: (token: string, company: string | undefined) => Promise<string>;
+    listConnections?: (token: string, companyUid: string) => Promise<IntegrationConnection[]>;
+}
+type FindingKind = "reconnect" | "re-add" | "provider-blocked";
+interface Finding {
+    provider: string;
+    connectionId: string;
+    kind: FindingKind;
+    message: string;
+}
+/**
+ * Expected session/company prerequisites degrade to NA instead of crashing or
+ * becoming a false connection failure. An unreadable inventory remains UNKNOWN.
+ */
+export declare function checkIntegrations(context: CheckContext, deps?: IntegrationsDoctorDeps): Promise<CheckResult[]>;
+/** Classify without echoing untrusted provider text, which may contain secrets. */
+export declare function classifyConnection(connection: IntegrationConnection): Finding[];
+export declare const integrationsFamily: CheckFamily;
+export {};
+//# sourceMappingURL=integrations.d.ts.map

package/dist/lib/doctor/checks/integrations.js

@@ -0,0 +1,237 @@
+/**
+ * Company integration health for `hq doctor`.
+ *
+ * This family makes one authenticated read of HQ's connection inventory. It
+ * never calls an integration gateway or provider tool, so it cannot mutate
+ * data, spend provider quota, or trigger provider rate limits. It classifies
+ * stored health signals only: a recorded rejection overrides a misleading
+ * `connected` status, but a clean connected row is not live-provider proof.
+ */
+import { ensureCognitoIdToken } from "../../../utils/cognito-session.js";
+import { isAuthError } from "../../../utils/auth-error.js";
+import { isCompanySelectionError } from "../../../utils/company-selection-error.js";
+import { getCompanyUid } from "../../../utils/vault-api.js";
+import { bareProvider, fetchConnections, IntegrationsCliError, } from "../../../commands/integrations-core.js";
+export const INTEGRATIONS_FAMILY_ID = "integrations";
+export const INTEGRATIONS_PREFIX = "integrations";
+/**
+ * Expected session/company prerequisites degrade to NA instead of crashing or
+ * becoming a false connection failure. An unreadable inventory remains UNKNOWN.
+ */
+export async function checkIntegrations(context, deps = {}) {
+    if (context.integrations === false) {
+        return [{
+                status: "NA",
+                checkId: `${INTEGRATIONS_PREFIX}.skipped`,
+                message: "Integration checks were not requested for this run.",
+            }];
+    }
+    const ensureToken = deps.ensureToken ?? (() => ensureCognitoIdToken({ interactive: false }));
+    const resolveCompany = deps.resolveCompany ?? getCompanyUid;
+    const listConnections = deps.listConnections ?? ((token, companyUid) => fetchConnections(token, companyUid));
+    let token;
+    try {
+        token = await ensureToken();
+    }
+    catch {
+        return skippedForSession();
+    }
+    let companyUid;
+    try {
+        companyUid = await resolveCompany(token, context.company);
+    }
+    catch (error) {
+        if (isAuthError(error))
+            return skippedForSession();
+        if (isCompanySelectionError(error)) {
+            return skippedForCompany(error instanceof Error ? error : new Error("Company selection failed."));
+        }
+        return unknown("The active company could not be resolved; retry after checking HQ connectivity.");
+    }
+    let connections;
+    try {
+        connections = await listConnections(token, companyUid);
+    }
+    catch (error) {
+        if (isAuthError(error))
+            return skippedForSession();
+        if (error instanceof IntegrationsCliError && error.expected) {
+            return [{
+                    status: "NA",
+                    checkId: `${INTEGRATIONS_PREFIX}.unavailable`,
+                    message: "Integration inventory is unavailable to this account, so no connection health was assessed.",
+                }];
+        }
+        return unknown("The integration connection inventory could not be read; retry after checking HQ connectivity.");
+    }
+    const active = connections.filter((connection) => connection.status !== "revoked");
+    if (active.length === 0) {
+        return [{
+                status: "NA",
+                checkId: `${INTEGRATIONS_PREFIX}.connections`,
+                message: "No active integration connections to assess. Revoked connection tombstones are ignored.",
+            }];
+    }
+    const findings = active.flatMap(classifyConnection);
+    if (findings.length === 0) {
+        return [{
+                status: "PASS",
+                checkId: `${INTEGRATIONS_PREFIX}.connections`,
+                message: `${active.length} active integration connection${active.length === 1 ? "" : "s"} reported healthy; only the control-plane inventory was read (no provider calls).`,
+            }];
+    }
+    return groupFindings(findings, context.company);
+}
+/** Classify without echoing untrusted provider text, which may contain secrets. */
+export function classifyConnection(connection) {
+    if (connection.status === "revoked")
+        return [];
+    const provider = bareProvider(connection.provider);
+    const reason = recordedReason(connection);
+    const connectedWithRecordedFailure = connection.status === "connected" && reason !== "";
+    if (isProviderBlocked(reason) || connection.status === "degraded") {
+        return [{
+                provider,
+                connectionId: connection.id,
+                kind: "provider-blocked",
+                message: connectedWithRecordedFailure
+                    ? "reports connected, but recorded provider health says access is blocked upstream"
+                    : "provider-side access is blocked or unavailable",
+            }];
+    }
+    if (isTokenRefreshFailure(reason) || isCredentialFailure(reason)) {
+        const problem = isTokenRefreshFailure(reason)
+            ? "token refresh failed"
+            : connectedWithRecordedFailure
+                ? "reports connected, but the provider rejected the stored credentials"
+                : "the provider rejected the stored credentials";
+        return [{ provider, connectionId: connection.id, kind: "reconnect", message: problem }];
+    }
+    if (connection.status !== "connected" && connection.fix_path === "blocked-upstream") {
+        return [{
+                provider,
+                connectionId: connection.id,
+                kind: "provider-blocked",
+                message: "provider-side access is blocked or unavailable",
+            }];
+    }
+    // The server is authoritative about an API-key credential that must be
+    // re-entered. Do not apply a stale fix path to a clean connected row, but do
+    // preserve this useful branch logic for a non-healthy row.
+    if (connection.status !== "connected" && connection.fix_path === "re-add") {
+        return [{
+                provider,
+                connectionId: connection.id,
+                kind: "re-add",
+                message: "needs its API key re-entered",
+            }];
+    }
+    if (connection.status === "needs-reauth" || connection.status === "error") {
+        return [{
+                provider,
+                connectionId: connection.id,
+                kind: "reconnect",
+                message: connection.status === "needs-reauth" ? "needs re-authentication" : "is in an error state",
+            }];
+    }
+    if (connection.status !== "connected") {
+        return [{
+                provider,
+                connectionId: connection.id,
+                kind: "reconnect",
+                message: `reports an unrecognized non-healthy status (${connection.status})`,
+            }];
+    }
+    return [];
+}
+function groupFindings(findings, company) {
+    const groups = new Map();
+    for (const finding of findings) {
+        const key = `${finding.kind}\u0000${finding.provider}\u0000${finding.message}`;
+        const entries = groups.get(key) ?? [];
+        entries.push(finding);
+        groups.set(key, entries);
+    }
+    return [...groups.values()]
+        .sort((a, b) => a[0].provider.localeCompare(b[0].provider))
+        .map((entries) => resultForGroup(entries, company));
+}
+function resultForGroup(entries, company) {
+    const first = entries[0];
+    const count = entries.length;
+    const ids = entries.map((entry) => entry.connectionId);
+    const preview = ids.slice(0, 6);
+    const overflow = ids.length - preview.length;
+    const namedConnections = preview.join(", ") + (overflow > 0 ? ` (+${overflow} more)` : "");
+    const plural = count === 1 ? "connection" : "connections";
+    if (first.kind === "provider-blocked") {
+        return {
+            status: "FAIL",
+            checkId: `${INTEGRATIONS_PREFIX}.provider-blocked.${first.provider}`,
+            target: namedConnections,
+            message: `${first.provider}: ${count} ${plural} ${first.message}. This is not reported as a local credential repair.`,
+        };
+    }
+    if (first.kind === "re-add") {
+        return {
+            status: "FAIL",
+            checkId: `${INTEGRATIONS_PREFIX}.re-add.${first.provider}`,
+            target: namedConnections,
+            message: `${first.provider}: ${count} ${plural} ${first.message}.`,
+            remediation: `hq integrations connect ${first.provider} --token-stdin${company ? ` --company ${company}` : ""}`,
+        };
+    }
+    const companyArg = company ? ` --company ${company}` : "";
+    const remediation = preview
+        .map((id) => `hq integrations reconnect --connection ${id}${companyArg}`)
+        .join("; ");
+    return {
+        status: "FAIL",
+        checkId: `${INTEGRATIONS_PREFIX}.reconnect.${first.provider}`,
+        target: namedConnections,
+        message: `${first.provider}: ${count} ${plural} ${first.message}.`,
+        remediation: overflow > 0
+            ? `Reconnect the listed connections, then repeat for the remaining ${overflow}: ${remediation}`
+            : remediation,
+    };
+}
+function recordedReason(connection) {
+    return [connection.errorReason, connection.needsReauthReason, connection.degradedReason]
+        .filter((value) => typeof value === "string")
+        .join(" ")
+        .toLowerCase();
+}
+function isTokenRefreshFailure(reason) {
+    return /token[\s_-]*refresh|refresh[\s_-]*token|invalid_grant/.test(reason);
+}
+function isCredentialFailure(reason) {
+    return /rejected[\s_-]*(the[\s_-]*)?stored[\s_-]*credentials|credentials[\s_-]*rejected|unauthori[sz]ed|invalid[\s_-]*(token|credentials)/.test(reason);
+}
+function isProviderBlocked(reason) {
+    return /\b403\b|access[\s_-]*denied|upstream[\s_-]*(block|blocked)|provider[\s_-]*(block|blocked|unavailable)|service[\s_-]*unavailable/.test(reason);
+}
+function skippedForSession() {
+    return [{
+            status: "NA",
+            checkId: `${INTEGRATIONS_PREFIX}.session`,
+            message: "Integration checks skipped: no usable HQ session is available.",
+            remediation: "Run `hq login`, then rerun `hq doctor`.",
+        }];
+}
+function skippedForCompany(error) {
+    return [{
+            status: "NA",
+            checkId: `${INTEGRATIONS_PREFIX}.company`,
+            message: "Integration checks skipped: no single active company could be selected.",
+            remediation: `Rerun \`hq doctor --company <slug>\`. (${error.message})`,
+        }];
+}
+function unknown(message) {
+    return [{ status: "UNKNOWN", checkId: `${INTEGRATIONS_PREFIX}.inventory`, message }];
+}
+export const integrationsFamily = {
+    id: INTEGRATIONS_FAMILY_ID,
+    title: "Integration connection health",
+    run: (context) => checkIntegrations(context),
+};
+//# sourceMappingURL=integrations.js.map

package/dist/lib/doctor/registry.js

@@ -19,6 +19,7 @@ import { checkCodexWiring } from "./checks/codex-wiring.js";
 import { checkGrokWiring } from "./checks/grok-wiring.js";
 import { checkRuntimeProbe } from "./checks/runtime-probe.js";
 import { runtimeHealthFamily } from "./checks/runtime-health.js";
+import { integrationsFamily } from "./checks/integrations.js";
 import { fixtureCoverageFamily } from "./fixtures/discover.js";
 import { checkClaudeWiring } from "./checks/claude-wiring.js";
 /**
@@ -177,6 +178,9 @@ export function createDefaultRegistry() {
     // runtime is logged out or broken; this family closes that blind spot. Its
     // default tier is a pure PATH scan, preserving the offline contract.
     registry.register(runtimeHealthFamily);
+    // The engine remains family-agnostic: integrations is one bounded,
+    // read-only inventory family, registered alongside all other checks.
+    registry.register(integrationsFamily);
     return registry;
 }
 //# sourceMappingURL=registry.js.map

package/dist/lib/doctor/types.d.ts

@@ -66,6 +66,10 @@ export interface CheckContext {
      * executing anything.
      */
     liveRuntimes?: boolean;
+    /** Company slug for company-scoped families; absent uses active membership. */
+    company?: string;
+    /** Internal test seam; production `hq doctor` always enables integrations. */
+    integrations?: boolean;
 }
 /**
  * A check family: an id, a human title, and an async `run` returning per-item

package/dist/main.js

@@ -72,6 +72,7 @@ import { isExpectedUserError } from "./utils/expected-cli-error.js";
 import { isEpipe } from "./utils/epipe.js";
 import { isInterceptedProcessExit } from "./utils/intercepted-process-exit.js";
 import { isAuthError } from "./utils/auth-error.js";
+import { browserLoginAbandonedMessage } from "./utils/browser-login-abandoned.js";
 import { isCompanySelectionError } from "./utils/company-selection-error.js";
 import { canOfferTeamUpgrade, formatPlanGateError, isPlanGateError, offerTeamUpgrade, } from "./utils/plan-gate-error.js";
 import { upgradeToTeam } from "./utils/team-upgrade.js";
@@ -394,6 +395,21 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         deps.stderr.write(`hq: ${err.message}\n`);
         deps.setExitCode(1);
     }
+    else if (browserLoginAbandonedMessage(err)) {
+        // HQ-CLI-V: the caller triggered the implicit browser sign-in fallback
+        // (an expiring/absent HQ session) and then never completed it —
+        // @indigoai-us/hq-cloud's browserLogin rejected either at its 15-minute
+        // deadline or because the user declined at the IdP (access_denied). A
+        // human walking away from an OAuth prompt is expected auth state the user
+        // fixes with `hq login`, not an hq-cli defect. Print the fixed actionable
+        // remedy and skip Sentry so one abandoned login doesn't file a permanent
+        // high-priority "crash". Placed with the auth carve-out (both mean "your
+        // HQ session isn't usable; run hq login"); every genuine browser-login or
+        // token-exchange fault stays outside the closed allowlist and still
+        // captures below.
+        deps.stderr.write(`hq: ${browserLoginAbandonedMessage(err)}\n`);
+        deps.setExitCode(1);
+    }
     else if (isPlanGateError(err)) {
         // hq-pro's plan denials are expected product limits, never a CLI crash.
         // The shared vault client has already decoded and typed the small safe

package/dist/utils/browser-login-abandoned.d.ts

@@ -0,0 +1,12 @@
+/**
+ * If `err` is an abandoned implicit browser sign-in, return a short, fixed
+ * user-facing remedy; otherwise return `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture — a user who walked away from an OAuth prompt is not an hq-cli defect.
+ * A null result means "handle as usual (capture to Sentry)". CognitoRefreshError
+ * is a refresh fault, never an abandonment, so it is excluded structurally even
+ * though it extends CognitoAuthError.
+ */
+export declare function browserLoginAbandonedMessage(err: unknown): string | null;
+//# sourceMappingURL=browser-login-abandoned.d.ts.map

package/dist/utils/browser-login-abandoned.js

@@ -0,0 +1,70 @@
+// src/utils/browser-login-abandoned.ts
+//
+// Classify an ABANDONED implicit browser sign-in — the caller triggered the
+// fallback OAuth flow (an expiring/absent HQ session on any of the ~100
+// ensureCognitoToken/ensureCognitoIdToken call sites) and then never completed
+// it. @indigoai-us/hq-cloud's browserLogin arms a 15-minute deadline and also
+// rejects when the identity provider reports the user declined; both mint a
+// bare CognitoAuthError. A human walking away from an OAuth prompt is expected
+// auth state the user fixes with `hq login`, NOT an hq-cli defect — so the
+// top-level handler prints an actionable line and exits non-zero but SKIPS
+// Sentry capture, mirroring the auth (HQ-CLI-8), company-selection (HQ-CLI-7),
+// expected-user-error (HQ-CLI-6), and environmental-FS (HQ-CLI-2) carve-outs.
+//
+// HQ-CLI-V (Sentry indigo-d0/hq-cli 7685055900): `hq integrations list
+// --company <slug> --json` tried to refresh an expiring session, the refresh
+// 400'd (invalid_grant), and it fell back to browserLogin(). Nobody finished
+// the sign-in, so exactly 15 minutes later browserLogin rejected with
+// `CognitoAuthError("Login timed out after 15 minutes")`. That error carries no
+// `code`, no `expected` flag, and is not an AuthError/CompanySelectionError/…,
+// so every predicate in handleTopLevelError returned false and the abandoned
+// login was captured as a high-priority, unfixable "crash".
+//
+// The allowlist is CLOSED at the two upstream-minted human-abandonment
+// signatures and defaults to null (capture). Every other CognitoAuthError — a
+// state-parameter mismatch (possible CSRF), a missing callback code, a
+// non-access_denied IdP error, a token-exchange failure — and every
+// CognitoRefreshError (a refresh fault, not an abandonment) still reaches
+// Sentry.
+import { CognitoAuthError, CognitoRefreshError } from "@indigoai-us/hq-cloud";
+/**
+ * Fixed, actionable remedy. Deliberately interpolates NO upstream error text,
+ * so this carve-out can never widen disclosure and needs no redaction pass.
+ */
+const BROWSER_LOGIN_ABANDONED_MESSAGE = "Browser sign-in was not completed. Run `hq login`, finish the sign-in in " +
+    "your browser, then re-run your command.";
+/**
+ * The 15-minute login-deadline signature (@indigoai-us/hq-cloud cognito-auth
+ * `waitForAuthCode`). The minute count is tolerated (`\d+`) so an upstream
+ * retune of the deadline turns the contract test red rather than silently
+ * restoring the Sentry noise.
+ */
+const LOGIN_TIMED_OUT = /^Login timed out after \d+ minutes?$/;
+/**
+ * The user declined at the identity provider. Matched EXACTLY — other
+ * `Cognito returned error: <x>` values (server_error, …) are not abandonment
+ * and stay reportable.
+ */
+const ACCESS_DENIED = "Cognito returned error: access_denied";
+/**
+ * If `err` is an abandoned implicit browser sign-in, return a short, fixed
+ * user-facing remedy; otherwise return `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture — a user who walked away from an OAuth prompt is not an hq-cli defect.
+ * A null result means "handle as usual (capture to Sentry)". CognitoRefreshError
+ * is a refresh fault, never an abandonment, so it is excluded structurally even
+ * though it extends CognitoAuthError.
+ */
+export function browserLoginAbandonedMessage(err) {
+    if (!(err instanceof CognitoAuthError))
+        return null;
+    if (err instanceof CognitoRefreshError)
+        return null;
+    const { message } = err;
+    if (LOGIN_TIMED_OUT.test(message) || message === ACCESS_DENIED) {
+        return BROWSER_LOGIN_ABANDONED_MESSAGE;
+    }
+    return null;
+}
+//# sourceMappingURL=browser-login-abandoned.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.103.23",
+  "version": "5.103.25",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.15.71",
+    "@indigoai-us/hq-cloud": "~6.15.79",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",