@indigoai-us/hq-cli 5.48.0 → 5.50.0

package/.github/workflows/ci.yml

@@ -24,6 +24,23 @@ jobs:
       pnpm-version: "10"
       node-version: ${{ matrix.node-version }}
       run-build: true
-      run-lint: false
+      run-lint: true
       run-coverage: true
     secrets: inherit
+
+  e2e:
+    name: e2e (node 22)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: "10"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm test:e2e

package/dist/commands/meetings.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f1986062-db39-5448-a8fa-3bb6be32c58b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ae9ed929-9821-5f8b-bbbe-8f7b6105f5ad")}catch(e){}}();
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
@@ -246,8 +246,15 @@ export function registerMeetingsCommand(program) {
             }
             const where = companyId === "unknown" ? "unattributed (personal)" : companyId;
             console.log(chalk.green(`\n✓ Meeting ${chalk.cyan(meetingId)} attributed to ${chalk.bold(where)}.`));
-            if (data && data.appliedToSeries)
+            if (typeof data.occurrencesUpdated === "number" && data.occurrencesUpdated > 1) {
+                console.log(chalk.dim(`  Applied to ${data.occurrencesUpdated} meetings in this recurring series (including past occurrences).`));
+            }
+            else if (data.appliedToSeries) {
                 console.log(chalk.dim("  Future occurrences of this recurring series will inherit this attribution."));
+            }
+            if (typeof data.refiledCount === "number" && data.refiledCount > 0) {
+                console.log(chalk.dim(`  Refiled ${data.refiledCount} transcript${data.refiledCount === 1 ? "" : "s"} into the new company vault.`));
+            }
             console.log();
         }
         catch (err) {
@@ -419,4 +426,4 @@ export function registerMeetingsCommand(program) {
     });
 }
 //# sourceMappingURL=meetings.js.map
-//# debugId=f1986062-db39-5448-a8fa-3bb6be32c58b
+//# debugId=ae9ed929-9821-5f8b-bbbe-8f7b6105f5ad

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="aeb143c7-7e19-5999-b6cb-790fc79034cc")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d57c1cc3-6dd3-5c7f-8eef-c7692d41b836")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -45,6 +45,7 @@ import { registerSignalsCommand } from "./commands/signals.js";
 import { registerReindexCommand } from "./commands/reindex.js";
 import { registerRescueCommand } from "./commands/rescue.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
+import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import { maybeWarnNewVersion, refreshVersionCache, } from "./utils/version-check.js";
 import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { CLI_VERSION } from "./cli-version.js";
@@ -176,12 +177,25 @@ registerRescueCommand(program);
         await program.parseAsync();
     }
     catch (err) {
-        Sentry.captureException(err);
+        // A full disk / exhausted quota / read-only filesystem is the user's
+        // machine, not an HQ code defect. Surface a clear, actionable message and
+        // skip Sentry capture so one full disk doesn't flood the tracker with
+        // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
+        // to Sentry and still exit 1.
+        const envMsg = environmentalFsErrorMessage(err);
+        if (envMsg) {
+            process.stderr.write(`hq: ${envMsg}\n`);
+        }
+        else {
+            Sentry.captureException(err);
+        }
         process.exitCode = 1;
     }
     finally {
+        // Release health: finalize the per-run session before the flush.
+        Sentry.endSession();
         await Promise.allSettled([refreshVersionCache(), Sentry.flush(2000)]);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=aeb143c7-7e19-5999-b6cb-790fc79034cc
+//# debugId=d57c1cc3-6dd3-5c7f-8eef-c7692d41b836

package/dist/sentry.js

@@ -1,10 +1,11 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="80ca2b2d-c649-5e88-9bc6-69a20fa4aa51")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a260ea42-f6d8-52d0-90c6-6e586de5efd6")}catch(e){}}();
 import * as Sentry from "@sentry/node";
 import { BUNDLED_DSN } from "./sentry-dsn.generated.js";
 import { beforeSend } from "./sentry-before-send.js";
 import { beforeBreadcrumb } from "./utils/breadcrumb-buffer.js";
 import { CLI_VERSION } from "./cli-version.js";
+import { getCachedSentryUser } from "./utils/sentry-identity.js";
 export function initSentry() {
     const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
     if (!dsn)
@@ -22,7 +23,16 @@ export function initSentry() {
         beforeSend,
         beforeBreadcrumb,
     });
+    // Attribute events to the logged-in HQ identity (best-effort; null when not
+    // logged in). A CLI process is one user, so global setUser is correct here.
+    const user = getCachedSentryUser();
+    if (user)
+        Sentry.setUser(user);
+    // Release health: one session per CLI run. Ended + flushed in index.ts's
+    // finally (covers every exit path). A captured error auto-marks the session
+    // "errored", so crash-free numbers per release stay accurate.
+    Sentry.startSession();
 }
 export { Sentry };
 //# sourceMappingURL=sentry.js.map
-//# debugId=80ca2b2d-c649-5e88-9bc6-69a20fa4aa51
+//# debugId=a260ea42-f6d8-52d0-90c6-6e586de5efd6

package/dist/utils/environmental-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * If `err` is an environmental disk/quota/read-only filesystem error, return a
+ * short, user-facing message explaining it; otherwise return `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture — the condition is the user's machine, not a bug HQ can fix. A null
+ * result means "this is a normal error; handle it as usual (capture to Sentry)".
+ */
+export declare function environmentalFsErrorMessage(err: unknown): string | null;
+//# sourceMappingURL=environmental-error.d.ts.map

package/dist/utils/environmental-error.js

@@ -0,0 +1,40 @@
+// src/utils/environmental-error.ts
+//
+// Classify errors that stem from the user's machine/filesystem state rather
+// than an HQ code defect. These are unactionable from our side: a full disk, an
+// exhausted quota, or a read-only filesystem. The CLI surfaces a clear,
+// actionable message and does NOT report them to Sentry — otherwise a single
+// full disk floods the issue tracker with identical, unfixable crash reports.
+//
+// HQ-CLI-2: `hq reindex` hit ENOSPC in the operation-lock temp-file write
+// (`fs.openSync` → "ENOSPC: no space left on device, open") and the raw error
+// propagated uncaught to the CLI's top-level handler, which captured it to
+// Sentry and exited silently — 5 stack-trace crashes in 6 seconds, with no
+// message telling the user their disk was full.
+/**
+ * Node errno codes for "the filesystem cannot accept this write" — purely
+ * environmental, never a code bug. Mapped to the message shown to the user.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="03976a9c-d4c3-57dc-bd1d-40c9d025193d")}catch(e){}}();
+const ENVIRONMENTAL_FS_CODES = {
+    ENOSPC: "No space left on device. Free up disk space and try again.",
+    EDQUOT: "Disk quota exceeded. Free up space (or raise your quota) and try again.",
+    EROFS: "The filesystem is read-only, so HQ can't write here. Check the mount/permissions and try again.",
+};
+/**
+ * If `err` is an environmental disk/quota/read-only filesystem error, return a
+ * short, user-facing message explaining it; otherwise return `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture — the condition is the user's machine, not a bug HQ can fix. A null
+ * result means "this is a normal error; handle it as usual (capture to Sentry)".
+ */
+export function environmentalFsErrorMessage(err) {
+    const code = err?.code;
+    if (typeof code !== "string")
+        return null;
+    return ENVIRONMENTAL_FS_CODES[code] ?? null;
+}
+//# sourceMappingURL=environmental-error.js.map
+//# debugId=03976a9c-d4c3-57dc-bd1d-40c9d025193d

package/dist/utils/sentry-identity.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Best-effort Sentry user from the cached HQ session, so CLI events are
+ * attributed to a user ("users affected" + per-user triage). Returns null when
+ * not logged in. A CLI process is single-user, so this is set once at init.
+ */
+export declare function getCachedSentryUser(): {
+    id?: string;
+    email?: string;
+    username?: string;
+} | null;
+//# sourceMappingURL=sentry-identity.d.ts.map

package/dist/utils/sentry-identity.js

@@ -0,0 +1,43 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1ca7cb4e-47e2-5cd0-a400-bbdaafa2b0d5")}catch(e){}}();
+import { loadCachedTokens, isMachineIdentity, loadMachineCreds, } from "@indigoai-us/hq-cloud";
+/** Decode the (untrusted) id-token payload — for attribution/display only. */
+function peekIdToken(idToken) {
+    try {
+        const payload = idToken.split(".")[1];
+        if (!payload)
+            return {};
+        const pad = payload.length % 4 === 0 ? "" : "=".repeat(4 - (payload.length % 4));
+        const normalized = payload.replace(/-/g, "+").replace(/_/g, "/") + pad;
+        const decoded = JSON.parse(Buffer.from(normalized, "base64").toString("utf-8"));
+        return { email: decoded.email, sub: decoded.sub };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Best-effort Sentry user from the cached HQ session, so CLI events are
+ * attributed to a user ("users affected" + per-user triage). Returns null when
+ * not logged in. A CLI process is single-user, so this is set once at init.
+ */
+export function getCachedSentryUser() {
+    try {
+        if (isMachineIdentity()) {
+            const username = loadMachineCreds()?.username;
+            return username ? { id: username, username } : null;
+        }
+        const cached = loadCachedTokens();
+        if (!cached)
+            return null;
+        const { email, sub } = peekIdToken(cached.idToken);
+        if (!sub && !email)
+            return null;
+        return { id: sub, email };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=sentry-identity.js.map
+//# debugId=1ca7cb4e-47e2-5cd0-a400-bbdaafa2b0d5

package/e2e/cli.test.ts

@@ -0,0 +1,93 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { afterEach, describe, expect, it } from "vitest";
+import { version } from "../package.json";
+
+const cliEntry = path.resolve("dist/index.js");
+const tempDirs: string[] = [];
+
+interface CliResult {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+function runHq(args: string[], options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}) {
+  return new Promise<CliResult>((resolve, reject) => {
+    const child = spawn(process.execPath, [cliEntry, ...args], {
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        HQ_NO_UPDATE_CHECK: "1",
+        ...options.env,
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+async function makeTempDir(prefix: string) {
+  const dir = await mkdtemp(path.join(tmpdir(), prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+describe("built hq CLI", () => {
+  it("prints help from the built entrypoint", async () => {
+    const result = await runHq(["--help"]);
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe("");
+    expect(result.stdout).toContain("Usage: hq [options] [command]");
+    expect(result.stdout).toContain("HQ management CLI");
+    expect(result.stdout).toContain("whoami");
+  });
+
+  it("prints the package version from the built entrypoint", async () => {
+    const result = await runHq(["--version"]);
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe("");
+    expect(result.stdout.trim()).toBe(version);
+  });
+
+  it("reports logged-out state without network or credentials", async () => {
+    const home = await makeTempDir("hq-cli-e2e-home-");
+    const cwd = await makeTempDir("hq-cli-e2e-cwd-");
+
+    const result = await runHq(["whoami"], {
+      cwd,
+      env: {
+        HOME: home,
+        USERPROFILE: home,
+        XDG_CONFIG_HOME: path.join(home, ".config"),
+        XDG_CACHE_HOME: path.join(home, ".cache"),
+        HQ_MACHINE_IDENTITY: undefined,
+        HQ_MACHINE_CREDS: undefined,
+      },
+    });
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe("");
+    expect(result.stdout.trim()).toBe("Not logged in. Run 'hq login' to authenticate.");
+  });
+});

package/eslint.config.js

@@ -0,0 +1,37 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+const sourceFiles = ["src/**/*.ts"];
+const recommended = tseslint
+  .config(js.configs.recommended, ...tseslint.configs.recommended)
+  .map((config) => ({
+    ...config,
+    files: sourceFiles,
+  }));
+
+export default [
+  {
+    ignores: ["dist/**", "generated/**", "node_modules/**"],
+  },
+  ...recommended,
+  {
+    files: sourceFiles,
+    rules: {
+      "no-undef": "off",
+      "no-useless-assignment": "warn",
+      "no-useless-escape": "warn",
+      "prefer-const": "warn",
+      "preserve-caught-error": "off",
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/no-require-imports": "warn",
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          argsIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+        },
+      ],
+    },
+  },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.48.0",
+  "version": "5.50.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -10,13 +10,15 @@
   "scripts": {
     "build": "node scripts/generate-dsn.mjs && tsc",
     "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
     "test": "vitest run",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary",
     "vitest": "vitest",
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^6.11.14",
+    "@indigoai-us/hq-cloud": "^6.12.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",
@@ -29,11 +31,14 @@
   },
   "devDependencies": {
     "@aws-sdk/client-s3": "^3.1049.0",
+    "@eslint/js": "^10.0.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "@types/semver": "^7.5.8",
     "@vitest/coverage-v8": "4.1.6",
+    "eslint": "^10.5.0",
     "typescript": "^5.7.0",
+    "typescript-eslint": "^8.61.1",
     "vitest": "^4.1.2"
   },
   "repository": {

package/src/commands/meetings.test.ts

@@ -160,4 +160,68 @@ describe("meetings set-company", () => {
 
     expect(logSpy).toHaveBeenCalledWith(JSON.stringify(body, null, 2));
   });
+
+  it("prints recurring series and refiled transcript counts from the response", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonRes({
+        ok: true,
+        meetingId: "meeting-123456",
+        companyId: "cmp_acme",
+        seriesKey: "series-123",
+        appliedToSeries: true,
+        occurrencesUpdated: 3,
+        refiled: true,
+        refiledCount: 2,
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync([
+      "node",
+      "hq",
+      "meetings",
+      "set-company",
+      "meeting-123456",
+      "--company",
+      "acme",
+    ]);
+
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Applied to 3 meetings in this recurring series"),
+    );
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Refiled 2 transcripts into the new company vault."),
+    );
+  });
+
+  it("does not print multi-meeting or refile copy for a single occurrence without refiles", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonRes({
+        ok: true,
+        meetingId: "meeting-123456",
+        companyId: "cmp_acme",
+        seriesKey: null,
+        appliedToSeries: false,
+        occurrencesUpdated: 1,
+        refiled: false,
+        refiledCount: 0,
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync([
+      "node",
+      "hq",
+      "meetings",
+      "set-company",
+      "meeting-123456",
+      "--company",
+      "acme",
+    ]);
+
+    const output = logSpy.mock.calls.map(([line]) => String(line)).join("\n");
+    expect(output).not.toContain("Applied to 1 meetings");
+    expect(output).not.toContain("Refiled 0 transcripts");
+    expect(output).not.toContain("Future occurrences of this recurring series will inherit this attribution.");
+  });
 });

package/src/commands/meetings.ts

@@ -341,6 +341,9 @@ export function registerMeetingsCommand(program: Command): void {
         if (!res.ok) await handleApiError(res);
         const data = (await res.json()) as {
           appliedToSeries?: boolean;
+          occurrencesUpdated?: number;
+          refiled?: boolean;
+          refiledCount?: number;
           [key: string]: unknown;
         };
 
@@ -351,7 +354,14 @@ export function registerMeetingsCommand(program: Command): void {
 
         const where = companyId === "unknown" ? "unattributed (personal)" : companyId;
         console.log(chalk.green(`\n✓ Meeting ${chalk.cyan(meetingId)} attributed to ${chalk.bold(where)}.`));
-        if (data && data.appliedToSeries) console.log(chalk.dim("  Future occurrences of this recurring series will inherit this attribution."));
+        if (typeof data.occurrencesUpdated === "number" && data.occurrencesUpdated > 1) {
+          console.log(chalk.dim(`  Applied to ${data.occurrencesUpdated} meetings in this recurring series (including past occurrences).`));
+        } else if (data.appliedToSeries) {
+          console.log(chalk.dim("  Future occurrences of this recurring series will inherit this attribution."));
+        }
+        if (typeof data.refiledCount === "number" && data.refiledCount > 0) {
+          console.log(chalk.dim(`  Refiled ${data.refiledCount} transcript${data.refiledCount === 1 ? "" : "s"} into the new company vault.`));
+        }
         console.log();
       } catch (err) {
         console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));

package/src/index.ts

@@ -45,6 +45,7 @@ import { registerSignalsCommand } from "./commands/signals.js";
 import { registerReindexCommand } from "./commands/reindex.js";
 import { registerRescueCommand } from "./commands/rescue.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
+import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
 import {
   maybeWarnNewVersion,
   refreshVersionCache,
@@ -215,9 +216,21 @@ registerRescueCommand(program);
     }
     await program.parseAsync();
   } catch (err) {
-    Sentry.captureException(err);
+    // A full disk / exhausted quota / read-only filesystem is the user's
+    // machine, not an HQ code defect. Surface a clear, actionable message and
+    // skip Sentry capture so one full disk doesn't flood the tracker with
+    // identical, unfixable crash reports (HQ-CLI-2). Genuine errors still go
+    // to Sentry and still exit 1.
+    const envMsg = environmentalFsErrorMessage(err);
+    if (envMsg) {
+      process.stderr.write(`hq: ${envMsg}\n`);
+    } else {
+      Sentry.captureException(err);
+    }
     process.exitCode = 1;
   } finally {
+    // Release health: finalize the per-run session before the flush.
+    Sentry.endSession();
     await Promise.allSettled([refreshVersionCache(), Sentry.flush(2000)]);
   }
 })();

package/src/sentry.ts

@@ -3,6 +3,7 @@ import { BUNDLED_DSN } from "./sentry-dsn.generated.js";
 import { beforeSend } from "./sentry-before-send.js";
 import { beforeBreadcrumb } from "./utils/breadcrumb-buffer.js";
 import { CLI_VERSION } from "./cli-version.js";
+import { getCachedSentryUser } from "./utils/sentry-identity.js";
 
 export function initSentry(): void {
   const dsn = BUNDLED_DSN || process.env.SENTRY_DSN;
@@ -20,6 +21,14 @@ export function initSentry(): void {
     beforeSend,
     beforeBreadcrumb,
   });
+  // Attribute events to the logged-in HQ identity (best-effort; null when not
+  // logged in). A CLI process is one user, so global setUser is correct here.
+  const user = getCachedSentryUser();
+  if (user) Sentry.setUser(user);
+  // Release health: one session per CLI run. Ended + flushed in index.ts's
+  // finally (covers every exit path). A captured error auto-marks the session
+  // "errored", so crash-free numbers per release stay accurate.
+  Sentry.startSession();
 }
 
 export { Sentry };

package/src/utils/environmental-error.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { environmentalFsErrorMessage } from "./environmental-error.js";
+
+/** Build a Node-style errno error with a `.code`, as fs.*Sync throws. */
+function errnoError(code: string, message: string): NodeJS.ErrnoException {
+  const err = new Error(message) as NodeJS.ErrnoException;
+  err.code = code;
+  return err;
+}
+
+describe("environmentalFsErrorMessage", () => {
+  // HQ-CLI-2: the exact error that crashed `hq reindex` and flooded Sentry.
+  it("classifies ENOSPC (no space left on device) as environmental", () => {
+    const err = errnoError("ENOSPC", "ENOSPC: no space left on device, open '/x'");
+    const msg = environmentalFsErrorMessage(err);
+    expect(msg).not.toBeNull();
+    expect(msg).toMatch(/no space left on device/i);
+  });
+
+  it("classifies EDQUOT (quota exceeded) as environmental", () => {
+    const msg = environmentalFsErrorMessage(errnoError("EDQUOT", "EDQUOT: disk quota exceeded"));
+    expect(msg).toMatch(/quota/i);
+  });
+
+  it("classifies EROFS (read-only filesystem) as environmental", () => {
+    const msg = environmentalFsErrorMessage(errnoError("EROFS", "EROFS: read-only file system"));
+    expect(msg).toMatch(/read-only/i);
+  });
+
+  // A genuine code bug must still reach Sentry — only the disk-class codes are
+  // diverted, so we never silently swallow real defects.
+  it("returns null for a code-bug error (ENOENT) so it is still captured", () => {
+    expect(environmentalFsErrorMessage(errnoError("ENOENT", "ENOENT: not found"))).toBeNull();
+  });
+
+  it("returns null for a plain Error with no code", () => {
+    expect(environmentalFsErrorMessage(new Error("boom"))).toBeNull();
+  });
+
+  it("returns null for non-error values (null/undefined/string)", () => {
+    expect(environmentalFsErrorMessage(null)).toBeNull();
+    expect(environmentalFsErrorMessage(undefined)).toBeNull();
+    expect(environmentalFsErrorMessage("ENOSPC")).toBeNull();
+  });
+});

package/src/utils/environmental-error.ts

@@ -0,0 +1,39 @@
+// src/utils/environmental-error.ts
+//
+// Classify errors that stem from the user's machine/filesystem state rather
+// than an HQ code defect. These are unactionable from our side: a full disk, an
+// exhausted quota, or a read-only filesystem. The CLI surfaces a clear,
+// actionable message and does NOT report them to Sentry — otherwise a single
+// full disk floods the issue tracker with identical, unfixable crash reports.
+//
+// HQ-CLI-2: `hq reindex` hit ENOSPC in the operation-lock temp-file write
+// (`fs.openSync` → "ENOSPC: no space left on device, open") and the raw error
+// propagated uncaught to the CLI's top-level handler, which captured it to
+// Sentry and exited silently — 5 stack-trace crashes in 6 seconds, with no
+// message telling the user their disk was full.
+
+/**
+ * Node errno codes for "the filesystem cannot accept this write" — purely
+ * environmental, never a code bug. Mapped to the message shown to the user.
+ */
+const ENVIRONMENTAL_FS_CODES: Record<string, string> = {
+  ENOSPC: "No space left on device. Free up disk space and try again.",
+  EDQUOT:
+    "Disk quota exceeded. Free up space (or raise your quota) and try again.",
+  EROFS:
+    "The filesystem is read-only, so HQ can't write here. Check the mount/permissions and try again.",
+};
+
+/**
+ * If `err` is an environmental disk/quota/read-only filesystem error, return a
+ * short, user-facing message explaining it; otherwise return `null`.
+ *
+ * A non-null result means the caller should print the message and SKIP Sentry
+ * capture — the condition is the user's machine, not a bug HQ can fix. A null
+ * result means "this is a normal error; handle it as usual (capture to Sentry)".
+ */
+export function environmentalFsErrorMessage(err: unknown): string | null {
+  const code = (err as NodeJS.ErrnoException | null | undefined)?.code;
+  if (typeof code !== "string") return null;
+  return ENVIRONMENTAL_FS_CODES[code] ?? null;
+}

package/src/utils/sentry-identity.ts

@@ -0,0 +1,45 @@
+import {
+  loadCachedTokens,
+  isMachineIdentity,
+  loadMachineCreds,
+} from "@indigoai-us/hq-cloud";
+
+/** Decode the (untrusted) id-token payload — for attribution/display only. */
+function peekIdToken(idToken: string): { email?: string; sub?: string } {
+  try {
+    const payload = idToken.split(".")[1];
+    if (!payload) return {};
+    const pad =
+      payload.length % 4 === 0 ? "" : "=".repeat(4 - (payload.length % 4));
+    const normalized = payload.replace(/-/g, "+").replace(/_/g, "/") + pad;
+    const decoded = JSON.parse(
+      Buffer.from(normalized, "base64").toString("utf-8"),
+    ) as { email?: string; sub?: string };
+    return { email: decoded.email, sub: decoded.sub };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Best-effort Sentry user from the cached HQ session, so CLI events are
+ * attributed to a user ("users affected" + per-user triage). Returns null when
+ * not logged in. A CLI process is single-user, so this is set once at init.
+ */
+export function getCachedSentryUser():
+  | { id?: string; email?: string; username?: string }
+  | null {
+  try {
+    if (isMachineIdentity()) {
+      const username = loadMachineCreds()?.username;
+      return username ? { id: username, username } : null;
+    }
+    const cached = loadCachedTokens();
+    if (!cached) return null;
+    const { email, sub } = peekIdToken(cached.idToken);
+    if (!sub && !email) return null;
+    return { id: sub, email };
+  } catch {
+    return null;
+  }
+}

package/vitest.e2e.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["e2e/**/*.test.ts"],
+  },
+});