@indigoai-us/hq-cli 5.123.1 → 5.123.2

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.123.2] — 2026-09-19
+
+### Fixed
+
+- Company slug lookup no longer prints `Failed to resolve company slug '…':`
+  with nothing after the colon. Transient failures (timeouts, 429, 5xx) are
+  retried once, and the error names the HTTP status and says it is a temporary
+  lookup failure rather than a missing company.
+
 ## [5.123.1] — 2026-09-19
 
 ### Fixed

package/dist/utils/vault-api.js

@@ -320,16 +320,37 @@ async function resolveCompanyByUid(token, uid) {
     if (!res.ok) {
         raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
-        throw new Error(`Failed to resolve company '${uid}': ${body.error ?? res.statusText}`);
+        throw new Error(`Failed to resolve company '${uid}': ${formatSlugLookupReason(res, body)}`);
     }
     const data = (await res.json());
     return data.entity.uid;
 }
+/**
+ * Node's fetch (undici) often leaves `statusText` empty, and some vault
+ * error bodies send `error: ""` or omit it. `??` does not treat "" as missing,
+ * so `body.error ?? res.statusText` produced
+ * `Failed to resolve company slug '…':` with nothing after the colon
+ * (Shepherd #2306). Never return an empty reason: prefer a non-blank body
+ * error, then statusText, then `HTTP <status>`.
+ */
+function formatSlugLookupReason(res, body) {
+    const fromBody = typeof body.error === "string" ? body.error.trim() : "";
+    if (fromBody)
+        return fromBody;
+    const fromStatus = (res.statusText ?? "").trim();
+    if (fromStatus)
+        return fromStatus;
+    return `HTTP ${res.status}`;
+}
+function isTransientSlugLookupStatus(status) {
+    return status === 408 || status === 425 || status === 429 || status >= 500;
+}
 /**
  * Resolve a company slug WITHIN THE CALLER'S NAMESPACE via the server's
  * caller-scoped `/entity/check-slug/me` endpoint. Returns the caller's own
- * company uid for that slug, or `null` when the caller owns / actively belongs
- * to no company with that slug.
+ * company uid for that slug, `miss` when the caller owns / actively belongs
+ * to no company with that slug, or `transient` when the lookup itself failed
+ * (timeout, 429, 5xx) after one retry.
  *
  * This is the load-bearing fix for DEV-1742. Under hq-pro's per-user-namespace
  * model two unrelated tenants may each hold "acme", so the legacy GLOBAL
@@ -344,25 +365,63 @@ async function resolveCompanyByUid(token, uid) {
  * the same primitive hq-cloud's `context.ts` already resolves slugs through.
  */
 async function resolveSlugInCallerNamespace(token, slug) {
-    const res = await vaultApiFetch({
+    const attempt = async () => {
+        const res = await vaultApiFetch({
+            token,
+            path: "/entity/check-slug/me",
+            query: { type: "company", slug },
+            signal: AbortSignal.timeout(identityLookupTimeoutMs()),
+        });
+        if (!res.ok) {
+            raiseIfUnauthorized(res);
+            // Namespace lookup unavailable (e.g. membership table not configured →
+            // 503, or the caller has no person entity). A 401 short-circuits above
+            // because the token is bad and the global fallback would only 401 again.
+            // Transient statuses are retried once below; other non-2xx still mean
+            // "couldn't resolve here" and fall back to the global lookup.
+            // vaultApiFetch already recorded the non-2xx as a Sentry breadcrumb.
+            if (isTransientSlugLookupStatus(res.status)) {
+                return { kind: "transient" };
+            }
+            return { kind: "miss" };
+        }
+        const data = (await res.json());
+        // `available: false` carries the caller's own company holding the slug.
+        const uid = data.conflictingCompanyUid;
+        return uid ? { kind: "hit", uid } : { kind: "miss" };
+    };
+    const run = async () => {
+        try {
+            return await attempt();
+        }
+        catch (err) {
+            if (networkTransportErrorCode(err) === null)
+                throw err;
+            return { kind: "transient" };
+        }
+    };
+    const first = await run();
+    if (first.kind !== "transient")
+        return first;
+    return run();
+}
+async function fetchGlobalCompanyBySlug(token, ref) {
+    const attempt = () => vaultApiFetch({
         token,
-        path: '/entity/check-slug/me',
-        query: { type: 'company', slug },
+        path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
         signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
-    if (!res.ok) {
-        raiseIfUnauthorized(res);
-        // Namespace lookup unavailable (e.g. membership table not configured →
-        // 503, or the caller has no person entity). A 401 short-circuits above
-        // because the token is bad and the global fallback would only 401 again;
-        // other non-2xx statuses signal "couldn't resolve here" and let the caller
-        // fall back to the global lookup. vaultApiFetch already recorded the
-        // non-2xx as a Sentry breadcrumb, so this is not a silent swallow.
-        return null;
+    try {
+        const res = await attempt();
+        if (res.ok || !isTransientSlugLookupStatus(res.status))
+            return res;
     }
-    const data = (await res.json());
-    // `available: false` carries the caller's own company holding the slug.
-    return data.conflictingCompanyUid ?? null;
+    catch (err) {
+        if (networkTransportErrorCode(err) === null)
+            throw err;
+        return attempt();
+    }
+    return attempt();
 }
 async function resolveCompanyUid(token, ref) {
     // Silent escape hatch: a `cmp_` ref is a uid, not a slug — resolve directly.
@@ -379,39 +438,25 @@ async function resolveCompanyUid(token, ref) {
     // caller's OWN company (unique within their namespace by the invariant
     // above), making a stranger's same-slug company invisible.
     //
-    // A non-2xx already degrades to the global fallback below (via `return null`).
-    // A TRANSPORT failure must degrade the SAME way, not abort the command:
-    // `resolveSlugInCallerNamespace`'s fetch is bounded by AbortSignal.timeout, so
-    // a vault gateway that accepts the connection but never answers rejects with a
-    // DOMException named `TimeoutError`. Before this catch, that rejection threw
-    // straight out of `resolveCompanyUid`, skipped the global by-slug lookup, and
-    // — being unclassified by main.ts — filed a Sentry crash report instead of an
-    // actionable connectivity message (Sentry HQ-CLI-1P / issue 7716090679).
-    // Degrade ONLY on a recognized transport failure; re-throw everything else
-    // unchanged, so a genuine hq-cli defect stays fatal and the 401 AuthError that
-    // `raiseIfUnauthorized` throws still short-circuits before any fallback.
-    let mine;
-    try {
-        mine = await resolveSlugInCallerNamespace(token, ref);
+    // A non-2xx already degrades to the global fallback below (`miss` /
+    // `transient`). A TRANSPORT failure must degrade the SAME way, not abort
+    // the command: `resolveSlugInCallerNamespace`'s fetch is bounded by
+    // AbortSignal.timeout, so a vault gateway that accepts the connection but
+    // never answers rejects with a DOMException named `TimeoutError`. That is
+    // classified as `transient` (and retried once) inside the helper; a genuine
+    // hq-cli defect still throws, and the 401 AuthError that
+    // `raiseIfUnauthorized` throws still short-circuits before any fallback
+    // (Sentry HQ-CLI-1P / issue 7716090679).
+    const mine = await resolveSlugInCallerNamespace(token, ref);
+    if (mine.kind === "hit") {
+        return mine.uid;
     }
-    catch (err) {
-        if (networkTransportErrorCode(err) === null) {
-            throw err;
-        }
-        mine = null;
-    }
-    if (mine) {
-        return mine;
-    }
-    // The caller owns / belongs to no company with this slug. Fall back to the
-    // GLOBAL by-slug lookup for the cross-company / admin resolutions that
-    // intentionally target a company the caller isn't a member of (e.g. a
-    // group-grant target). A single global match resolves cleanly.
-    const res = await vaultApiFetch({
-        token,
-        path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
-        signal: AbortSignal.timeout(identityLookupTimeoutMs()),
-    });
+    // The caller owns / belongs to no company with this slug, or the namespace
+    // lookup itself failed. Fall back to the GLOBAL by-slug lookup for the
+    // cross-company / admin resolutions that intentionally target a company the
+    // caller isn't a member of (e.g. a group-grant target). A single global
+    // match resolves cleanly.
+    const res = await fetchGlobalCompanyBySlug(token, ref);
     if (!res.ok) {
         raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
@@ -425,10 +470,19 @@ async function resolveCompanyUid(token, ref) {
                 `is in your namespace. Re-run with --company <uid> to pick one:\n` +
                 body.uids.map((u) => `  --company ${u}`).join('\n'));
         }
-        if (res.status === 404 && body.error === "Entity not found") {
+        // Only a clean namespace miss plus a global 404 is "this slug does not
+        // exist". A transient namespace failure followed by 404 is still a lookup
+        // failure — treating it as not-found sent owners to check a slug that
+        // was fine (Shepherd #2306).
+        if (res.status === 404 && mine.kind === "miss") {
             throw Object.assign(new Error(`Company slug '${ref}' was not found. Check the slug or run \`hq companies list\`.`), { expected: true });
         }
-        throw new Error(`Failed to resolve company slug '${ref}': ${body.error ?? res.statusText}`);
+        const reason = formatSlugLookupReason(res, body);
+        const retryable = mine.kind === "transient" || isTransientSlugLookupStatus(res.status);
+        const hint = retryable
+            ? " This is a temporary lookup failure, not a missing company. Retry the command."
+            : "";
+        throw new Error(`Failed to resolve company slug '${ref}': ${reason}.${hint}`);
     }
     const data = (await res.json());
     return data.entity.uid;

package/package.json

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