@indigoai-us/hq-cli 5.103.31 → 5.103.32

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## [5.103.32] — 2026-08-29
+
 ## [5.103.31] — 2026-08-29
 
 ## [5.103.30] — 2026-08-29

package/dist/commands/skill.js

@@ -68,7 +68,13 @@ export function readActiveCompanySlug(hqRoot) {
 export function resolveCompanySlug(flag, hqRoot = DEFAULT_HQ_ROOT) {
     const slug = flag ?? readActiveCompanySlug(hqRoot);
     if (!slug) {
-        throw new Error("No company specified. Pass --company <slug> (or set an active company in .hq/config.json).");
+        // HQ-CLI-13 (Sentry 7695157352): neither `--company` nor an active company
+        // in `.hq/config.json` — ordinary caller state with a self-describing
+        // remedy, not an hq-cli defect. Mark it `expected` (via localSkillError) so
+        // the top-level boundary prints this line and skips Sentry, exactly as the
+        // resolveSkillUid local conditions do (HQ-CLI-10/11). The text is unchanged
+        // and already tells the caller what to do.
+        throw localSkillError("No company specified. Pass --company <slug> (or set an active company in .hq/config.json).");
     }
     return slug;
 }
@@ -354,10 +360,26 @@ export function registerSkillCommand(program, deps = {}) {
                 });
             }
             catch (err) {
-                throw new Error(`Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync failed: ${err instanceof Error ? err.message : String(err)}`);
+                // HQ-CLI-14 (Sentry 7695715459): registration and the local stamp
+                // already SUCCEEDED; only the upload failed. Do NOT flatten the
+                // inner error into a new generic Error — that discarded its class,
+                // `name`, `cause` and any `expected` marker, and spliced the
+                // caller's absolute SKILL.md path into a message Sentry then
+                // fingerprinted per home directory. Keep the partial-success context
+                // on stderr, then rethrow the ORIGINAL error so every classifier the
+                // boundary already has (expected, AuthError, plan-gate, EPIPE,
+                // environmental-fs, sync-state-lock, network-transport) applies to a
+                // sync failure exactly as it does everywhere else, and a genuine
+                // fault is captured under its own type and stack.
+                console.warn(chalk.yellow(`⚠ Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync failed.`));
+                throw err;
             }
             if (syncResult.aborted) {
-                throw new Error(`Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync aborted because the remote file conflicts.`);
+                // A remote-file conflict under hq-cli's own `onConflict: "abort"`
+                // choice is unambiguous caller state with a user-side remedy, not an
+                // hq-cli defect — mark it `expected` so it is printed and skipped for
+                // Sentry rather than filing a crash on its first occurrence.
+                throw localSkillError(`Skill ${registered.skillUid} is stamped locally at '${filePath}', but sync aborted because the remote file conflicts.`);
             }
         }
         console.log(chalk.green(`Skill ready: ${registered.skillUid}`));

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

@@ -128,6 +128,21 @@ function resultForGroup(entries, company) {
             remediation: serverRemediation ?? `hq integrations connect ${first.provider} --token-stdin${company ? ` --company ${company}` : ""}`,
         };
     }
+    if (first.kind === "re-add-with-auth") {
+        // Deliberately NOT the `re-add` branch. That one's default remediation is
+        // the API-key flow (`--token-stdin`), and this fault is the opposite case:
+        // an install that was created with no credential at all and needs a
+        // browser sign-in. Falling through to the reconnect default would be worse
+        // still, since there is no stored credential to refresh.
+        return {
+            status: "FAIL",
+            checkId: `${INTEGRATIONS_PREFIX}.re-add-with-auth.${first.provider}`,
+            target: namedConnections,
+            message: `${first.provider}: ${count} ${plural} ${first.message}.`,
+            remediation: serverRemediation
+                ?? `Remove the integration and add it again, signing in this time: hq integrations connect ${first.provider}${company ? ` --company ${company}` : ""}`,
+        };
+    }
     if (first.kind === "contact-admin") {
         return {
             status: "FAIL",

package/dist/lib/integrations/health.d.ts

@@ -39,8 +39,18 @@ export interface IntegrationConnection extends AdminConnection {
  *
  * A server that DID say `fix_kind: "reconnect"` still classifies as
  * `reconnect`: that is a diagnosis, not an absence of one.
+ *
+ * `re-add-with-auth` is NOT a synonym for `re-add`. `re-add` means an API key
+ * has to be typed in again; this one means the install was created with no
+ * credential at all and needs a browser sign-in. Collapsing the two would print
+ * the API-key command against a connection that never had a key.
+ *
+ * This union is kept identical to the console's twin (`_connection-health.ts`
+ * `FixKind`) on purpose: a person who reads one surface and then the other must
+ * not find the same failure sorted into two different buckets. Any member added
+ * here has to be added there in the same change.
  */
-export type FindingKind = "reconnect" | "re-add" | "contact-admin" | "wait" | "provider-blocked" | "retryable" | "hq-configuration" | "undiagnosed";
+export type FindingKind = "reconnect" | "re-add" | "re-add-with-auth" | "contact-admin" | "wait" | "provider-blocked" | "retryable" | "hq-configuration" | "undiagnosed";
 export interface Finding {
     provider: string;
     connectionId: string;

package/dist/lib/integrations/health.js

@@ -19,6 +19,12 @@ import { bareProvider } from "./provider-slug.js";
 const RECONNECT_REASON_CODES = new Set([
     "oauth_refresh_invalid_grant",
     "oauth_refresh_unavailable",
+    // The stored grant carries no refresh token, so nothing can be renewed
+    // without the person signing in again. The legacy text heuristic below
+    // happens to match this string through its `refresh[\s_-]*token` branch, but
+    // that is coincidence rather than contract: it is listed here so the
+    // classification survives a rename of the heuristic.
+    "oauth_refresh_missing_refresh_token",
     "token_refresh_failed",
     "credentials_rejected",
 ]);
@@ -26,7 +32,27 @@ const RETRYABLE_REASON_CODES = new Set([
     "oauth_refresh_transient",
     "oauth_refresh_write_conflict",
 ]);
-const HQ_CONFIGURATION_REASON_CODE = "oauth_client_secret_unavailable";
+/**
+ * Faults that sit on HQ's side of the boundary.
+ *
+ * Neither is repairable by anyone at the customer: `oauth_client_secret_unavailable`
+ * means HQ could not read its own client secret, and `oauth_refresh_missing_client`
+ * means HQ has no OAuth client configured for the provider at all. Sending a
+ * person round a reconnect for either costs them a working credential and
+ * cannot succeed, which is why hq-pro answers both with `contact-support`
+ * ahead of its own role gate — a member sees the same instruction an owner does.
+ */
+const HQ_CONFIGURATION_REASON_CODES = new Set([
+    "oauth_client_secret_unavailable",
+    "oauth_refresh_missing_client",
+]);
+/**
+ * The install exists but was created without credentials, and the provider
+ * refused it. The repair is to add the integration again and sign in — NOT the
+ * `re-add` API-key flow, and not a reconnect of a credential that was never
+ * stored.
+ */
+const RE_ADD_WITH_AUTH_REASON_CODE = "unauthenticated_install_rejected";
 const UNSPECIFIED_REASON_CODE = "unspecified";
 /** Classify without echoing untrusted provider text, which may contain secrets. */
 export function classifyConnection(connection) {
@@ -45,10 +71,11 @@ export function classifyConnection(connection) {
     if (knownReasonCode && knownReasonCode !== UNSPECIFIED_REASON_CODE) {
         const finding = findingForKnownReasonCode(connection, provider, knownReasonCode);
         // Retryable and HQ-configuration reason codes diagnose conditions that a
-        // caller-specific remediation cannot change. Reconnect-class codes defer
-        // to the server's credential/role-aware remediation classification, so an
-        // install in progress is never interrupted by a reconnect.
-        return [withServerRemediation(connection, RECONNECT_REASON_CODES.has(knownReasonCode)
+        // caller-specific remediation cannot change. Role-dependent codes defer to
+        // the server's credential/role-aware remediation classification, so an
+        // install in progress is never interrupted by a reconnect and a member is
+        // never told to perform a repair only an owner or admin can carry out.
+        return [withServerRemediation(connection, defersToServerFixKind(knownReasonCode)
                 ? findingForServerFixKind(finding, connection.fix_kind)
                 : finding)];
     }
@@ -161,6 +188,32 @@ function findingForServerFixKind(fallback, fixKind) {
                 kind: "wait",
                 message: "is waiting for the Factory installation to complete",
             };
+        case "re-add-with-auth":
+            return {
+                ...fallback,
+                kind: "re-add-with-auth",
+                message: "was added without a sign-in, and the provider refused it",
+            };
+        case "contact-support":
+            // hq-pro answers `contact-support` only for a gap in HQ's own OAuth
+            // configuration, which is the same class `hq-configuration` already
+            // names. It gets that kind rather than a member of its own so both paths
+            // into the class carry the same VERDICT — an HQ administrator has to fix
+            // it and reconnecting will not — instead of one cause reaching a person
+            // under two different remediations.
+            //
+            // The message stays distinct, and `hq doctor` groups on the message, so a
+            // provider with both faults prints two lines under the one class. That is
+            // deliberate and matches every other class here (two `reconnect` rows with
+            // different causes already print separately). Collapsing them would mean
+            // stamping a row that arrived with NO reason code with the specific
+            // wording of one that did — a confident wrong answer, which is the exact
+            // failure this vocabulary exists to stop.
+            return {
+                ...fallback,
+                kind: "hq-configuration",
+                message: "is blocked by an HQ-side configuration gap",
+            };
         case "reconnect":
         default:
             return fallback;
@@ -181,13 +234,30 @@ function withServerRemediation(connection, finding) {
  * the legacy text heuristics, which remain below for old and unknown rows.
  */
 function knownReasonCodeFor(connection) {
-    const values = [connection.errorReason, connection.needsReauthReason, connection.degradedReason];
-    if (values.includes(HQ_CONFIGURATION_REASON_CODE))
-        return HQ_CONFIGURATION_REASON_CODE;
-    return values.find((value) => (typeof value === "string" &&
-        (RECONNECT_REASON_CODES.has(value) ||
-            RETRYABLE_REASON_CODES.has(value) ||
-            value === UNSPECIFIED_REASON_CODE)));
+    const values = [connection.errorReason, connection.needsReauthReason, connection.degradedReason]
+        .filter((value) => typeof value === "string");
+    // An HQ-side configuration fault outranks anything else recorded on the row:
+    // no customer-side repair can clear it, so a co-recorded reconnect code must
+    // not send someone to re-enter a credential that was never the problem.
+    const hqFault = values.find((value) => HQ_CONFIGURATION_REASON_CODES.has(value));
+    if (hqFault)
+        return hqFault;
+    return values.find((value) => (RECONNECT_REASON_CODES.has(value) ||
+        RETRYABLE_REASON_CODES.has(value) ||
+        value === RE_ADD_WITH_AUTH_REASON_CODE ||
+        value === UNSPECIFIED_REASON_CODE));
+}
+/**
+ * Whether the server's role- and credential-aware `fix_kind` should override
+ * the reason code's own classification.
+ *
+ * True for faults the customer CAN repair, because who repairs them depends on
+ * the caller's role — hq-pro answers a member with `contact-admin` where it
+ * answers an owner with the repair itself. False for HQ-side and retryable
+ * faults, whose remediation is the same for everyone.
+ */
+function defersToServerFixKind(code) {
+    return RECONNECT_REASON_CODES.has(code) || code === RE_ADD_WITH_AUTH_REASON_CODE;
 }
 function findingForKnownReasonCode(connection, provider, code) {
     if (RECONNECT_REASON_CODES.has(code)) {
@@ -208,11 +278,21 @@ function findingForKnownReasonCode(connection, provider, code) {
                 : "token refresh is temporarily unavailable; the stored credential remains intact",
         };
     }
+    if (code === RE_ADD_WITH_AUTH_REASON_CODE) {
+        return {
+            provider,
+            connectionId: connection.id,
+            kind: "re-add-with-auth",
+            message: "was added without a sign-in, and the provider refused it",
+        };
+    }
     return {
         provider,
         connectionId: connection.id,
         kind: "hq-configuration",
-        message: "the HQ OAuth client secret is unavailable",
+        message: code === "oauth_refresh_missing_client"
+            ? "cannot be refreshed because HQ has no OAuth client configured for this provider"
+            : "the HQ OAuth client secret is unavailable",
     };
 }
 function recordedReason(connection) {

package/dist/main.js

@@ -64,6 +64,7 @@ import { registerDoctorCommand } from "./commands/doctor.js";
 import { registerMeshCommand } from "./commands/mesh.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
+import { syncStateLockMessage } from "./utils/sync-state-lock-error.js";
 import { networkTransportErrorMessage } from "./utils/network-transport-error.js";
 import { qmdNativeBindingErrorMessage } from "./utils/qmd-native-binding-error.js";
 import { qmdMissingCollectionMessage } from "./utils/qmd-collection-missing-error.js";
@@ -523,6 +524,23 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         const envMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg
             ? null
             : environmentalFsErrorMessage(err);
+        // A LOCAL sync-state lock failure (@indigoai-us/hq-cloud's
+        // `StateStoreLockError`: another HQ process on this machine holds the
+        // sync-state journal lock) is the caller's concurrency state, not an
+        // hq-cli defect — hq-cloud's own watcher/sync-runner treat lock contention
+        // as transient. Before HQ-CLI-14 the `hq skill create` sync step flattened
+        // it into a generic, path-bearing Error that reached the capture below and
+        // minted a new fingerprint per home directory. Print the input-free remedy,
+        // exit 1, and skip Sentry. The signatures do not overlap the neighbouring
+        // branches: a StateStoreLockError carries no `.code` (so
+        // environmentalFsErrorMessage returned null) and is not a fetch TypeError
+        // (so it is not a transport failure), and this ordering — after the
+        // environmental-fs check, before network-transport — is pinned by tests.
+        // The `in-process-async-holder` reason is deliberately NOT suppressed here
+        // (see sync-state-lock-error.ts); it stays captured.
+        const lockMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || envMsg
+            ? null
+            : syncStateLockMessage(err);
         // A raw network transport failure (undici's `TypeError: fetch failed`
         // with a ConnectTimeoutError / ECONNREFUSED / ENOTFOUND cause) is the
         // caller's connectivity, not an hq-cli defect. Before this branch it fell
@@ -533,7 +551,7 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         // message that names the unreachable host, exit 1, and skip Sentry.
         // Ordered after the environmental check so a full disk keeps its exact
         // existing message.
-        const transportMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || envMsg
+        const transportMsg = qmdMsg || collectionMsg || terminatedMsg || llmDisabledMsg || moduleMissingMsg || envMsg || lockMsg
             ? null
             : networkTransportErrorMessage(err);
         if (qmdMsg) {
@@ -554,6 +572,9 @@ export async function handleTopLevelError(err, deps = defaultTopLevelErrorDepend
         else if (envMsg) {
             deps.stderr.write(`hq: ${envMsg}\n`);
         }
+        else if (lockMsg) {
+            deps.stderr.write(`hq: ${lockMsg}\n`);
+        }
         else if (transportMsg) {
             deps.stderr.write(`hq: ${transportMsg}\n`);
         }

package/dist/utils/sync-state-lock-error.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The `name` @indigoai-us/hq-cloud stamps on a state-store lock failure, and the
+ * prefix it puts on every such message (`super(\`state-store lock: ${message}\`)`).
+ * EITHER signal identifies the class. A unit test pins BOTH against the installed
+ * dependency so a future rename fails loudly in CI here rather than silently
+ * resuming Sentry noise.
+ */
+export declare const SYNC_STATE_LOCK_ERROR_NAME = "StateStoreLockError";
+export declare const SYNC_STATE_LOCK_MESSAGE_PREFIX = "state-store lock: ";
+/**
+ * If `err` is a LOCAL sync-state lock failure, return a short, input-free,
+ * actionable user-facing message; otherwise return `null`.
+ *
+ * A non-null result means the caller should PRINT the message, exit non-zero,
+ * and SKIP Sentry capture — the condition is another HQ process holding this
+ * machine's sync-state lock, not a bug HQ can fix. A null result means "handle
+ * this as usual (capture to Sentry)". The `in-process-async-holder` reason is
+ * deliberately excluded and still captures.
+ *
+ * The returned message never echoes the lock path or any other caller input, so
+ * the whole class groups as ONE Sentry-free condition instead of minting a new
+ * fingerprint per home directory. It is a fixed, bounded string, so no redaction
+ * or length cap is required.
+ */
+export declare function syncStateLockMessage(err: unknown): string | null;
+//# sourceMappingURL=sync-state-lock-error.d.ts.map

package/dist/utils/sync-state-lock-error.js

@@ -0,0 +1,78 @@
+// src/utils/sync-state-lock-error.ts
+//
+// Classify a LOCAL sync-state lock failure — another HQ process on THIS machine
+// already holds the sync-state journal lock — as the caller's machine/
+// concurrency state rather than an hq-cli code defect. Sibling of
+// `environmental-error.ts` (HQ-CLI-2, full disk / read-only fs) and
+// `network-transport-error.ts` (HQ-CLI-G, connectivity): a failure that is not
+// an hq-cli defect is surfaced to the user with an actionable message and
+// skipped for Sentry capture.
+//
+// HQ-CLI-14 (Sentry 7695715459): `hq skill create` registered and stamped the
+// skill, then its sync step called @indigoai-us/hq-cloud's `share()`, which
+// surfaced a `StateStoreLockError: state-store lock: cannot acquire
+// <HOME>/.hq/sync-state-v3/<digest>/append.lock`. hq-cloud's OWN consumers treat
+// lock contention as transient — its watcher reschedules on it and its
+// sync-runner defers only the `in-process-async-holder` reason — so a local
+// lock failure is concurrency state the user resolves by waiting for (or
+// quitting) the other HQ sync, not a reportable hq-cli crash. Before this the
+// caller flattened every sync failure into a generic, path-bearing Error, so the
+// lock class fell through the top-level boundary's closed allowlist and filed a
+// crash whose message minted a new Sentry fingerprint per home directory.
+//
+// Matching is STRUCTURAL, never `instanceof`: `StateStoreLockError` is not
+// re-exported from `@indigoai-us/hq-cloud`'s package entry (only `.`,
+// `./outposts*` and `./package.json` are exported), so a consumer cannot name
+// the class. Both signals below are computed from the value itself, mirroring
+// the style `environmental-error.ts` and `network-transport-error.ts` already
+// use.
+/**
+ * The `name` @indigoai-us/hq-cloud stamps on a state-store lock failure, and the
+ * prefix it puts on every such message (`super(\`state-store lock: ${message}\`)`).
+ * EITHER signal identifies the class. A unit test pins BOTH against the installed
+ * dependency so a future rename fails loudly in CI here rather than silently
+ * resuming Sentry noise.
+ */
+export const SYNC_STATE_LOCK_ERROR_NAME = "StateStoreLockError";
+export const SYNC_STATE_LOCK_MESSAGE_PREFIX = "state-store lock: ";
+/**
+ * The one `reason` hq-cloud treats as a DISTINCT internal condition rather than
+ * ordinary foreign contention: this process already holds the async scope lock,
+ * so a synchronous contender cannot spin without deadlocking the holder
+ * (state-store.ts's `in-process async holder for …`). That is same-process
+ * reentrancy — a condition HQ could actually fix — so it is NOT suppressed and
+ * stays on the captured path, exactly as hq-cloud's own sync-runner special-cases
+ * it.
+ */
+const IN_PROCESS_ASYNC_HOLDER_REASON = "in-process-async-holder";
+function isStateStoreLockError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return (err.name === SYNC_STATE_LOCK_ERROR_NAME ||
+        err.message.startsWith(SYNC_STATE_LOCK_MESSAGE_PREFIX));
+}
+/**
+ * If `err` is a LOCAL sync-state lock failure, return a short, input-free,
+ * actionable user-facing message; otherwise return `null`.
+ *
+ * A non-null result means the caller should PRINT the message, exit non-zero,
+ * and SKIP Sentry capture — the condition is another HQ process holding this
+ * machine's sync-state lock, not a bug HQ can fix. A null result means "handle
+ * this as usual (capture to Sentry)". The `in-process-async-holder` reason is
+ * deliberately excluded and still captures.
+ *
+ * The returned message never echoes the lock path or any other caller input, so
+ * the whole class groups as ONE Sentry-free condition instead of minting a new
+ * fingerprint per home directory. It is a fixed, bounded string, so no redaction
+ * or length cap is required.
+ */
+export function syncStateLockMessage(err) {
+    if (!isStateStoreLockError(err))
+        return null;
+    if (err.reason === IN_PROCESS_ASYNC_HOLDER_REASON)
+        return null;
+    return ("Another HQ process on this machine is holding the local sync state, so HQ " +
+        "could not update it. Wait for the other HQ sync to finish (or quit it), " +
+        "then run `hq sync` to finish syncing.");
+}
+//# sourceMappingURL=sync-state-lock-error.js.map

package/package.json

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