@indigoai-us/hq-cli 5.77.0 → 5.77.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [5.77.1]
+
+### Fixed
+
+- Missing company-slug responses are classified as expected user errors, so the
+  CLI no longer sends this expected absence to Sentry.
+
 ## [5.71.0]
 
 ### Added

package/dist/commands/cloud.d.ts

@@ -22,6 +22,13 @@ import { type BannerLevel } from "../lib/narrow-hint-banner.js";
  * succeed when files were dropped" guarantee unit-testable.
  */
 export declare function scopeExcludedWarning(count: number): string | null;
+/**
+ * Bound foreground waits for a watcher/manual sync that currently owns the
+ * per-root operation lock. The cloud engine reads this environment value on
+ * every lock acquisition. A command-line value wins; otherwise preserve a
+ * valid explicit caller environment value and supply a finite CLI default.
+ */
+export declare function configureSyncLockTimeout(raw: string | undefined): void;
 export interface PullAllVaultClient {
     listMyMemberships(): Promise<Array<{
         companyUid: string;

package/dist/commands/cloud.js

@@ -59,6 +59,21 @@ function resolveDeletePolicy() {
     }
     return "currency-gated";
 }
+const DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS = 300;
+/**
+ * Bound foreground waits for a watcher/manual sync that currently owns the
+ * per-root operation lock. The cloud engine reads this environment value on
+ * every lock acquisition. A command-line value wins; otherwise preserve a
+ * valid explicit caller environment value and supply a finite CLI default.
+ */
+export function configureSyncLockTimeout(raw) {
+    const value = raw ?? process.env.HQ_OP_LOCK_TIMEOUT ?? String(DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS);
+    const seconds = Number(value);
+    if (!Number.isInteger(seconds) || seconds < 0) {
+        throw new Error("--lock-timeout must be a non-negative integer number of seconds");
+    }
+    process.env.HQ_OP_LOCK_TIMEOUT = String(seconds);
+}
 // Oldest-first by createdAt, ties broken by uid lexicographic — matches
 // `pickCanonicalPersonEntity` in @indigoai-us/hq-cloud so the CLI lands on
 // the same person bucket that `hq-sync-runner` picks.
@@ -478,6 +493,7 @@ export function registerCloudCommands(program) {
         .argument("[paths...]", "Paths to push (defaults to current directory)")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .option("--company <slug>", "Company slug or UID (defaults to active company in .hq/config.json)")
+        .option("--lock-timeout <seconds>", "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)")
         .option("--message <msg>", "Optional message attached to journal entries for these uploads")
         .option("--on-conflict <strategy>", "Conflict strategy: overwrite | keep | abort (omit for interactive)")
         .option("--creds-from-stdin", "Read a pre-vended EntityContext as JSON from stdin instead of vending " +
@@ -509,6 +525,7 @@ export function registerCloudCommands(program) {
         "`--all`.")
         .action(async (paths, options) => {
         try {
+            configureSyncLockTimeout(options.lockTimeout);
             assertSingleSelector(options, "push");
         }
         catch (err) {
@@ -688,6 +705,7 @@ export function registerCloudCommands(program) {
         .description("Pull permitted files from the company vault to local HQ")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .option("--company <slug>", "Company slug or UID (defaults to active company in .hq/config.json)")
+        .option("--lock-timeout <seconds>", "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)")
         .option("--on-conflict <strategy>", "Conflict strategy: overwrite | keep | abort (omit for interactive)")
         .option("--all", "Pull every company you are a member of plus your personal vault " +
         "into <hq-root>. Companies land at <hq-root>/companies/<slug>; " +
@@ -711,6 +729,7 @@ export function registerCloudCommands(program) {
         "quarantined under .hq/scope-quarantine/ (recoverable).")
         .action(async (options) => {
         try {
+            configureSyncLockTimeout(options.lockTimeout);
             assertSingleSelector(options, "pull");
         }
         catch (err) {
@@ -882,6 +901,7 @@ export function registerCloudCommands(program) {
         "(mirrors AppBar HQ Sync's \"Sync Now\" button)")
         .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
         .option("--company <slug>", "Company slug or UID (defaults to active company in .hq/config.json)")
+        .option("--lock-timeout <seconds>", "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)")
         .option("--message <msg>", "Optional message attached to journal entries for the push leg")
         .option("--on-conflict <strategy>", "Conflict strategy: overwrite | keep | abort (omit for interactive)")
         .option("--all", "Sync every company you are a member of plus your personal vault " +
@@ -901,6 +921,7 @@ export function registerCloudCommands(program) {
         "out-of-scope files are quarantined under .hq/scope-quarantine/.")
         .action(async (options) => {
         try {
+            configureSyncLockTimeout(options.lockTimeout);
             assertSingleSelector(options, "now");
             if (options.all) {
                 // `options.personal === false` is Commander's auto-negation

package/dist/main.js

@@ -67,6 +67,9 @@ import { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
+import { settleWithin } from "./utils/settle-with-timeout.js";
+/** Hard upper bound for non-user-visible release-health finalization. */
+const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
 // the pipe early. This covers the ASYNC path — an 'error' event emitted on the
 // stream. The SYNCHRONOUS path (a `write EPIPE` thrown straight out of
@@ -306,7 +309,11 @@ export async function runCli() {
     finally {
         // Release health: finalize the per-run session before the flush.
         Sentry.endSession();
-        await Promise.allSettled([refreshVersionCache(), Sentry.flush(2000)]);
+        // Neither task may turn a successful command into Node's
+        // `unsettled top-level await` exit. They are observability-only after the
+        // command has completed, so a bounded best-effort wait is the terminal
+        // lifecycle boundary for this invocation.
+        await settleWithin([refreshVersionCache(), Sentry.flush(2000)], RELEASE_HEALTH_SETTLE_TIMEOUT_MS);
     }
 }
 //# sourceMappingURL=main.js.map

package/dist/utils/settle-with-timeout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Await finalization work without allowing a best-effort promise to leave a
+ * CLI's top-level await pending forever. The timer intentionally stays
+ * referenced: Node must remain alive long enough to settle this race.
+ */
+export declare function settleWithin(promises: readonly Promise<unknown>[], timeoutMs: number): Promise<"settled" | "timed_out">;
+//# sourceMappingURL=settle-with-timeout.d.ts.map

package/dist/utils/settle-with-timeout.js

@@ -0,0 +1,22 @@
+/**
+ * Await finalization work without allowing a best-effort promise to leave a
+ * CLI's top-level await pending forever. The timer intentionally stays
+ * referenced: Node must remain alive long enough to settle this race.
+ */
+export async function settleWithin(promises, timeoutMs) {
+    let timer;
+    const timedOut = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("timed_out"), timeoutMs);
+    });
+    try {
+        return await Promise.race([
+            Promise.allSettled(promises).then(() => "settled"),
+            timedOut,
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=settle-with-timeout.js.map

package/dist/utils/vault-api.js

@@ -176,6 +176,9 @@ 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") {
+            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 data = (await res.json());

package/package.json

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

package/src/commands/cloud.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { configureSyncLockTimeout } from "./cloud.js";
+
+const originalLockTimeout = process.env.HQ_OP_LOCK_TIMEOUT;
+
+afterEach(() => {
+  if (originalLockTimeout === undefined) {
+    delete process.env.HQ_OP_LOCK_TIMEOUT;
+  } else {
+    process.env.HQ_OP_LOCK_TIMEOUT = originalLockTimeout;
+  }
+});
+
+describe("configureSyncLockTimeout", () => {
+  it("supplies a finite foreground wait when the caller has not configured one", () => {
+    delete process.env.HQ_OP_LOCK_TIMEOUT;
+    configureSyncLockTimeout(undefined);
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBe("300");
+  });
+
+  it("honors an explicit zero-second refusal", () => {
+    configureSyncLockTimeout("0");
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBe("0");
+  });
+
+  it("honors a valid inherited lock timeout", () => {
+    process.env.HQ_OP_LOCK_TIMEOUT = "17";
+    configureSyncLockTimeout(undefined);
+    expect(process.env.HQ_OP_LOCK_TIMEOUT).toBe("17");
+  });
+
+  it("rejects an invalid timeout instead of silently waiting forever", () => {
+    expect(() => configureSyncLockTimeout("forever")).toThrow("--lock-timeout");
+  });
+
+  it("rejects an invalid inherited timeout instead of restoring an infinite wait", () => {
+    process.env.HQ_OP_LOCK_TIMEOUT = "forever";
+    expect(() => configureSyncLockTimeout(undefined)).toThrow("--lock-timeout");
+  });
+});

package/src/commands/cloud.ts

@@ -97,6 +97,24 @@ function resolveDeletePolicy(): "owned-only" | "currency-gated" | "all" {
 interface CommonSyncOptions {
   hqRoot: string;
   company?: string;
+  lockTimeout?: string;
+}
+
+const DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS = 300;
+
+/**
+ * Bound foreground waits for a watcher/manual sync that currently owns the
+ * per-root operation lock. The cloud engine reads this environment value on
+ * every lock acquisition. A command-line value wins; otherwise preserve a
+ * valid explicit caller environment value and supply a finite CLI default.
+ */
+export function configureSyncLockTimeout(raw: string | undefined): void {
+  const value = raw ?? process.env.HQ_OP_LOCK_TIMEOUT ?? String(DEFAULT_SYNC_LOCK_TIMEOUT_SECONDS);
+  const seconds = Number(value);
+  if (!Number.isInteger(seconds) || seconds < 0) {
+    throw new Error("--lock-timeout must be a non-negative integer number of seconds");
+  }
+  process.env.HQ_OP_LOCK_TIMEOUT = String(seconds);
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -821,6 +839,10 @@ export function registerCloudCommands(program: Command): void {
       "--company <slug>",
       "Company slug or UID (defaults to active company in .hq/config.json)",
     )
+    .option(
+      "--lock-timeout <seconds>",
+      "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)",
+    )
     .option(
       "--message <msg>",
       "Optional message attached to journal entries for these uploads",
@@ -884,6 +906,7 @@ export function registerCloudCommands(program: Command): void {
         },
       ) => {
         try {
+          configureSyncLockTimeout(options.lockTimeout);
           assertSingleSelector(options, "push");
         } catch (err) {
           console.error(
@@ -1118,6 +1141,10 @@ export function registerCloudCommands(program: Command): void {
       "--company <slug>",
       "Company slug or UID (defaults to active company in .hq/config.json)",
     )
+    .option(
+      "--lock-timeout <seconds>",
+      "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)",
+    )
     .option(
       "--on-conflict <strategy>",
       "Conflict strategy: overwrite | keep | abort (omit for interactive)",
@@ -1168,6 +1195,7 @@ export function registerCloudCommands(program: Command): void {
         },
       ) => {
         try {
+          configureSyncLockTimeout(options.lockTimeout);
           assertSingleSelector(options, "pull");
         } catch (err) {
           console.error(
@@ -1410,6 +1438,10 @@ export function registerCloudCommands(program: Command): void {
       "--company <slug>",
       "Company slug or UID (defaults to active company in .hq/config.json)",
     )
+    .option(
+      "--lock-timeout <seconds>",
+      "Maximum wait for another active HQ operation (default: 300; 0 = refuse immediately)",
+    )
     .option(
       "--message <msg>",
       "Optional message attached to journal entries for the push leg",
@@ -1460,6 +1492,7 @@ export function registerCloudCommands(program: Command): void {
         },
       ) => {
         try {
+          configureSyncLockTimeout(options.lockTimeout);
           assertSingleSelector(options, "now");
           if (options.all) {
             // `options.personal === false` is Commander's auto-negation

package/src/main.ts

@@ -75,6 +75,10 @@ import {
 } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
+import { settleWithin } from "./utils/settle-with-timeout.js";
+
+/** Hard upper bound for non-user-visible release-health finalization. */
+const RELEASE_HEALTH_SETTLE_TIMEOUT_MS = 3_000;
 
 // Swallow EPIPE when a downstream reader (e.g. `source <(…)`, `| head`) closes
 // the pipe early. This covers the ASYNC path — an 'error' event emitted on the
@@ -351,6 +355,13 @@ export async function runCli(): Promise<void> {
   } finally {
     // Release health: finalize the per-run session before the flush.
     Sentry.endSession();
-    await Promise.allSettled([refreshVersionCache(), Sentry.flush(2000)]);
+    // Neither task may turn a successful command into Node's
+    // `unsettled top-level await` exit. They are observability-only after the
+    // command has completed, so a bounded best-effort wait is the terminal
+    // lifecycle boundary for this invocation.
+    await settleWithin(
+      [refreshVersionCache(), Sentry.flush(2000)],
+      RELEASE_HEALTH_SETTLE_TIMEOUT_MS,
+    );
   }
 }

package/src/utils/settle-with-timeout.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { settleWithin } from "./settle-with-timeout.js";
+
+describe("settleWithin", () => {
+  it("settles normally when all finalizers finish", async () => {
+    await expect(settleWithin([Promise.resolve(), Promise.reject(new Error("ignored"))], 100))
+      .resolves.toBe("settled");
+  });
+
+  it("settles the caller when a best-effort finalizer never resolves", async () => {
+    vi.useFakeTimers();
+    try {
+      const result = settleWithin([new Promise<void>(() => {})], 1_000);
+      await vi.advanceTimersByTimeAsync(1_000);
+      await expect(result).resolves.toBe("timed_out");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/utils/settle-with-timeout.ts

@@ -0,0 +1,22 @@
+/**
+ * Await finalization work without allowing a best-effort promise to leave a
+ * CLI's top-level await pending forever. The timer intentionally stays
+ * referenced: Node must remain alive long enough to settle this race.
+ */
+export async function settleWithin(
+  promises: readonly Promise<unknown>[],
+  timeoutMs: number,
+): Promise<"settled" | "timed_out"> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<"timed_out">((resolve) => {
+    timer = setTimeout(() => resolve("timed_out"), timeoutMs);
+  });
+  try {
+    return await Promise.race([
+      Promise.allSettled(promises).then(() => "settled" as const),
+      timedOut,
+    ]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}

package/src/utils/vault-api.test.ts

@@ -8,6 +8,7 @@ import { Sentry } from '../sentry.js';
 import { getCompanyUid, getEntityUid, resolveCallerPersonUid, vaultApiFetch } from './vault-api.js';
 import { isAuthError } from './auth-error.js';
 import { isCompanySelectionError } from './company-selection-error.js';
+import { isExpectedUserError } from './expected-cli-error.js';
 
 const fetchMock = vi.fn();
 const originalFetch = globalThis.fetch;
@@ -142,6 +143,19 @@ describe('getEntityUid', () => {
     expect(fetchMock.mock.calls[1][0]).toMatch(/\/entity\/by-slug\/company\/acme/);
   });
 
+  it('classifies a global by-slug entity miss as an expected user error (HQ-CLI-8)', async () => {
+    fetchMock
+      .mockResolvedValueOnce(mockResponse(200, { available: true }))
+      .mockResolvedValueOnce(mockResponse(404, { error: 'Entity not found' }));
+
+    const err = await getEntityUid('tok', { companySlug: 'missing-co' }).catch(
+      (e: unknown) => e,
+    );
+
+    expect(isExpectedUserError(err)).toBe(true);
+    expect((err as Error).message).toMatch(/Company slug 'missing-co' was not found/);
+  });
+
   it('on residual global ambiguity (not in namespace) gives actionable --company <uid> guidance', async () => {
     // Caller belongs to no "acme"; the slug matches multiple strangers'
     // companies. The server 409s with the colliding uids and the CLI must tell

package/src/utils/vault-api.ts

@@ -217,6 +217,14 @@ async function resolveCompanyUid(token: string, ref: string): Promise<string> {
           body.uids.map((u) => `  --company ${u}`).join('\n'),
       );
     }
+    if (res.status === 404 && body.error === "Entity not found") {
+      throw Object.assign(
+        new Error(
+          `Company slug '${ref}' was not found. Check the slug or run \`hq companies list\`.`,
+        ),
+        { expected: true as const },
+      );
+    }
     throw new Error(
       `Failed to resolve company slug '${ref}': ${body.error ?? res.statusText}`,
     );