@indigoai-us/hq-cli 5.77.12 → 5.77.14

package/src/commands/packs-update-api-key.test.ts

@@ -0,0 +1,105 @@
+// @vitest-environment node
+/**
+ * Regression (Codex P1 follow-up on hq-cli#273): `hq packs update` un-wires a
+ * pack's existing contributions BEFORE calling `installPack()` to re-wire
+ * them. The Cognito-only `HQ_API_KEY` fail-closed gate added for `hq install`
+ * must live ONLY at that top-level CLI route (pkg-install.ts) — NOT inside
+ * the shared `installPack()` primitive `hq packs update` also calls. If it
+ * lived inside `installPack()`, a vault-key session would un-wire a pack and
+ * then throw before re-installing it, leaving the pack unwired with no
+ * symlinks and no rollback.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as os from 'os';
+import { Command } from 'commander';
+
+const { listInstalledPacks, unwirePack, installPack, resolveLatest } = vi.hoisted(() => ({
+  listInstalledPacks: vi.fn(),
+  unwirePack: vi.fn(() => ({ unlinked: [], skipped: [] })),
+  installPack: vi.fn(async () => {}),
+  resolveLatest: vi.fn(async () => ({
+    transport: 'git',
+    current: 'aaa',
+    latest: 'bbb',
+    updateAvailable: true,
+  })),
+}));
+
+vi.mock('./pack-install.js', () => ({
+  classify: vi.fn(() => 'git'),
+  resolveLatest,
+  resolveLatestMarketplace: vi.fn(),
+  runScanPackages: vi.fn(),
+  installPack,
+}));
+
+vi.mock('../utils/pack-contributions.js', () => ({
+  contributionLinks: vi.fn(() => []),
+  linkStatus: vi.fn(() => 'live'),
+  listInstalledPacks,
+  findDependentPacks: vi.fn(() => []),
+  readPackManifest: vi.fn(() => ({ manifest: null })),
+  unwirePack,
+  unwirePackMcp: vi.fn(),
+  readHqVersion: vi.fn(() => '15.0.0'),
+  readRecommendedPackages: vi.fn(() => []),
+  packagesDir: vi.fn((root: string) => `${root}/core/packages`),
+}));
+
+// resolveRoot() falls back to findHqRoot() when --hq-root isn't passed; stub
+// it to a real, existing directory so packs.ts never chdir()s into one.
+vi.mock('../utils/manifest.js', () => ({
+  findHqRoot: vi.fn(() => os.tmpdir()),
+}));
+
+import { registerPacksCommand } from './packs.js';
+
+async function runUpdateCli(...args: string[]): Promise<void> {
+  const program = new Command();
+  program.exitOverride();
+  registerPacksCommand(program);
+  await program.parseAsync(['packs', 'update', ...args], { from: 'user' });
+}
+
+describe('hq packs update leaves no pack unwired under HQ_API_KEY', () => {
+  beforeEach(() => {
+    listInstalledPacks.mockReturnValue([
+      {
+        name: 'hq-pack-demo',
+        dir: '/tmp/hq/core/packages/hq-pack-demo',
+        manifest: {
+          name: 'hq-pack-demo',
+          version: '1.0.0',
+          source: 'https://example.com/demo.git#aaa',
+          contributes: { skills: ['demo'] },
+        },
+      },
+    ]);
+    unwirePack.mockClear();
+    installPack.mockClear();
+  });
+
+  afterEach(() => {
+    delete process.env.HQ_API_KEY;
+  });
+
+  it('still calls installPack after unwirePack when HQ_API_KEY is set', async () => {
+    process.env.HQ_API_KEY = 'hqk_probe';
+    await runUpdateCli('hq-pack-demo', '--json');
+
+    expect(unwirePack).toHaveBeenCalledTimes(1);
+    // The regression: installPack must run to completion right after
+    // unwirePack -- it must NOT throw due to a Cognito-only gate, which would
+    // leave the pack unwired with nothing re-installed in its place.
+    expect(installPack).toHaveBeenCalledTimes(1);
+    const unwireOrder = unwirePack.mock.invocationCallOrder[0];
+    const installOrder = installPack.mock.invocationCallOrder[0];
+    expect(unwireOrder).toBeLessThan(installOrder);
+  });
+
+  it('still updates without HQ_API_KEY set (baseline, unchanged behavior)', async () => {
+    await runUpdateCli('hq-pack-demo', '--json');
+    expect(unwirePack).toHaveBeenCalledTimes(1);
+    expect(installPack).toHaveBeenCalledTimes(1);
+  });
+});

package/src/commands/pkg-install.dispatch.test.ts

@@ -4,7 +4,7 @@
  * listings transport (the live install path), not the legacy Cognito-gated
  * registry flow whose backend (/packages, /entitlements) was never deployed.
  */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { Command } from 'commander';
 
 // vi.mock is hoisted above imports/consts, so build the mocks via vi.hoisted()
@@ -48,6 +48,10 @@ describe('hq install dispatch — bare slug routes to marketplace', () => {
     sourceMatchesPackPattern.mockClear();
   });
 
+  afterEach(() => {
+    delete process.env.HQ_API_KEY;
+  });
+
   it('routes a bare slug through the marketplace transport', async () => {
     await runInstall('email-assistant');
     expect(installPack).toHaveBeenCalledTimes(1);
@@ -69,3 +73,31 @@ describe('hq install dispatch — bare slug routes to marketplace', () => {
     expect(installPack.mock.calls[0][0]).toBe('@indigoai-us/hq-pack-demo');
   });
 });
+
+describe('hq install dispatch — HQ_API_KEY fail-closed gate', () => {
+  beforeEach(() => {
+    installPack.mockClear();
+    sourceMatchesPackPattern.mockClear();
+  });
+
+  afterEach(() => {
+    delete process.env.HQ_API_KEY;
+  });
+
+  it('rejects at the CLI entrypoint before calling installPack when HQ_API_KEY is set', async () => {
+    process.env.HQ_API_KEY = 'hqk_probe';
+    const exitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation((code?: number | string | null) => {
+        throw new Error(`process.exit(${code})`);
+      });
+    try {
+      await expect(runInstall('@indigoai-us/hq-pack-demo')).rejects.toThrow('process.exit(1)');
+      // The gate must fire BEFORE installPack -- a vault-key session must
+      // never reach the pack-fetch/wire path via `hq install`.
+      expect(installPack).not.toHaveBeenCalled();
+    } finally {
+      exitSpy.mockRestore();
+    }
+  });
+});

package/src/commands/pkg-install.ts

@@ -28,6 +28,7 @@ import {
 } from '../utils/registry-client.js';
 import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
 import { addToRegistry } from '../utils/registry.js';
+import { assertCognitoOnlyCommand } from '../utils/resolve-vault-credential.js';
 import {
   MARKETPLACE_PREFIX,
   installPack,
@@ -51,6 +52,11 @@ export function registerPackageInstallCommand(parent: Command): void {
         opts: { company?: string; allowHooks?: boolean; allowMcp?: boolean; branch?: boolean }
       ) => {
         try {
+          // Gate the top-level `hq install` entrypoint only — `installPack`
+          // itself is also called by `hq packs update` (packs.ts), which must
+          // stay able to fail closed at its OWN call site (before it un-wires
+          // an existing pack) rather than mid-flight inside installPack.
+          assertCognitoOnlyCommand('hq install');
           if (sourceMatchesPackPattern(source)) {
             await installPack(source, {
               company: opts.company,

package/src/commands/run.ts

@@ -4,6 +4,7 @@ import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { internal } from 'varlock';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { peekHqApiKey } from '../utils/resolve-vault-credential.js';
 import { computeSha256 } from '../utils/integrity.js';
 import { vaultApiFetch, getCompanyUid } from '../utils/vault-api.js';
 import { discoverSchemas } from '../run/discover-schemas.js';
@@ -52,6 +53,11 @@ export function registerRunCommand(program: Command): void {
       check?: boolean;
     }) => {
       try {
+        if (peekHqApiKey() !== undefined) {
+          throw new Error(
+            'HQ_API_KEY is set; `hq run` requires a Cognito session. Unset HQ_API_KEY or use `hq secrets exec`.',
+          );
+        }
         const dashIndex = process.argv.indexOf('--');
         const childArgs = dashIndex !== -1 ? process.argv.slice(dashIndex + 1) : [];
 

package/src/commands/secrets.test.ts

@@ -1945,6 +1945,19 @@ describe("HQ_API_KEY consume path", () => {
     expect(errText).toMatch(/must start with 'hqk_'/);
   });
 
+  it("rejects secrets get without --reveal when HQ_API_KEY is set", async () => {
+    process.env.HQ_API_KEY = "hqk_valid_key";
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["node", "hq", "secrets", "get", "FOO"]),
+    ).rejects.toThrow(/__EXIT__:1/);
+    expect(vaultApiFetch).not.toHaveBeenCalled();
+    const errText = errSpy.mock.calls
+      .map((call) => call.map(String).join(" "))
+      .join("\n");
+    expect(errText).toMatch(/without --reveal is not supported/);
+  });
+
   it("gets a secret via /v1/keys/secrets/fetch when HQ_API_KEY is set", async () => {
     process.env.HQ_API_KEY = "hqk_valid_key";
     vi.mocked(vaultApiFetch).mockResolvedValueOnce(

package/src/commands/secrets.ts

@@ -1055,6 +1055,15 @@ export function registerSecretsCommand(program: Command): void {
         const cred = await resolveVaultCredential();
 
         if (cred.kind === "api-key") {
+          if (!opts.reveal) {
+            console.error(
+              chalk.red(
+                "HQ_API_KEY is set; `hq secrets get` without --reveal is not supported for API keys. " +
+                  "Use --reveal to fetch the value, or unset HQ_API_KEY for metadata-only reads.",
+              ),
+            );
+            process.exit(1);
+          }
           const res = await vaultApiFetch({
             token: cred.token,
             path: "/v1/keys/secrets/fetch",

package/src/outpost/session-heartbeat-bounds.test.ts

@@ -0,0 +1,195 @@
+/**
+ * Payload bounding for the Outpost session heartbeat.
+ *
+ * ## Why this exists
+ *
+ * The heartbeat enumerates every Claude transcript and Codex rollout on the
+ * box. On a long-lived Outpost that is an archive, not a status: the box this
+ * was first run against had **8,258 Claude transcripts and 1,082 Codex
+ * rollouts — 9,340 sessions — of which 15 had any activity in the last 15
+ * minutes.** Publishing all of them produced a payload of roughly 1.9 MB.
+ *
+ * AWS IoT Core rejects anything over 128 KB, so the very first real publish
+ * failed with `payload larger than 131072 bytes`. Every subsequent one would
+ * have too. The heartbeat is a liveness signal; it must carry what is live.
+ *
+ * Two rules, both tested here:
+ *   1. `ended` sessions are not published — they are history, and re-sending
+ *      thousands of them every five seconds is the bug.
+ *   2. Whatever survives that filter is still bounded by BYTES, because a busy
+ *      box could exceed the limit on live sessions alone. When the bound bites
+ *      it is reported, never silent — a truncated payload that looks complete
+ *      is how you get a wrong dashboard instead of a missing one.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_LIVENESS_THRESHOLDS,
+  IOT_PAYLOAD_BUDGET_BYTES,
+  collectSessions,
+  type DirEntry,
+  type FileStat,
+  type FileSystemPort,
+} from "./session-heartbeat.js";
+
+const NOW = new Date("2026-07-29T12:00:00.000Z");
+const NOW_MS = NOW.getTime();
+
+/**
+ * A fake Claude tree with `count` transcripts, each aged `ageSecondsFor(i)`.
+ * Codex enumeration sees an empty tree.
+ */
+function claudeTreeFs(
+  count: number,
+  ageSecondsFor: (i: number) => number,
+): FileSystemPort {
+  const names = Array.from(
+    { length: count },
+    (_, i) =>
+      `${i.toString(16).padStart(8, "0")}-aaaa-bbbb-cccc-dddddddddddd.jsonl`,
+  );
+  const ageOf = new Map<string, number>();
+  names.forEach((n, i) => ageOf.set(n, ageSecondsFor(i)));
+
+  return {
+    async readDir(path: string): Promise<DirEntry[]> {
+      if (path.endsWith("/.claude/projects")) {
+        return [{ name: "-home-ec2-user-hq", isDirectory: true, isFile: false }];
+      }
+      if (path.endsWith("/.claude/projects/-home-ec2-user-hq")) {
+        return names.map((name) => ({
+          name,
+          isDirectory: false,
+          isFile: true,
+        }));
+      }
+      return [];
+    },
+    async stat(path: string): Promise<FileStat> {
+      const name = path.split("/").pop() ?? "";
+      const age = ageOf.get(name) ?? 0;
+      const mtimeMs = NOW_MS - age * 1000;
+      return { mtimeMs, birthtimeMs: mtimeMs, size: 1024 };
+    },
+    async readTextFile() {
+      return "";
+    },
+    async readBounded() {
+      // A realistic cwd/model sniff, so each record is a realistic size.
+      return JSON.stringify({
+        cwd: "/home/ec2-user/hq/repos/private/some-longish-repo-name",
+        model: "claude-opus-4-8",
+      });
+    },
+  };
+}
+
+const config = { personUid: "prs_01TEST", home: "/home/ec2-user", now: () => NOW };
+
+describe("payload bounding", () => {
+  it("publishes live sessions and drops the ended archive", async () => {
+    // 500 sessions: the first 5 active, the rest ancient — the real shape of
+    // a box that has been running for weeks.
+    const fs = claudeTreeFs(500, (i) => (i < 5 ? 2 : 60 * 60 * 24 * 30));
+
+    const payload = await collectSessions(config, { fs });
+
+    expect(payload.sessions).toHaveLength(5);
+    expect(payload.sessions.every((s) => s.status !== "ended")).toBe(true);
+  });
+
+  it("reports how many sessions exist, not just how many it sent", async () => {
+    const fs = claudeTreeFs(500, (i) => (i < 5 ? 2 : 60 * 60 * 24 * 30));
+
+    const payload = await collectSessions(config, { fs });
+
+    // Silent filtering reads as "this box has 5 sessions". It has 500.
+    expect(payload.totalSessions).toBe(500);
+    expect(payload.sessions.length).toBeLessThan(payload.totalSessions);
+  });
+
+  it("keeps idle sessions — only `ended` is archive", async () => {
+    // 2s → running, 5min → idle, 30d → ended.
+    const fs = claudeTreeFs(3, (i) => [2, 300, 60 * 60 * 24 * 30][i]!);
+
+    const payload = await collectSessions(config, { fs });
+
+    const statuses = payload.sessions.map((s) => s.status).sort();
+    expect(statuses).toEqual(["idle", "running"]);
+  });
+
+  it("stays under the IoT limit even when every session is live", async () => {
+    // 5,000 sessions all active — the size bound, not the status filter, is
+    // what has to hold here.
+    const fs = claudeTreeFs(5000, () => 2);
+
+    const payload = await collectSessions(config, { fs });
+    const bytes = Buffer.byteLength(JSON.stringify(payload), "utf8");
+
+    expect(bytes).toBeLessThanOrEqual(IOT_PAYLOAD_BUDGET_BYTES);
+    // The real AWS IoT Core ceiling. The budget must leave headroom under it.
+    expect(bytes).toBeLessThan(131072);
+  });
+
+  it("flags truncation rather than quietly shortening the list", async () => {
+    const fs = claudeTreeFs(5000, () => 2);
+
+    const payload = await collectSessions(config, { fs });
+
+    expect(payload.truncated).toBe(true);
+    expect(payload.totalSessions).toBe(5000);
+    expect(payload.sessions.length).toBeLessThan(5000);
+  });
+
+  it("does not flag truncation when everything fits", async () => {
+    const fs = claudeTreeFs(3, () => 2);
+
+    const payload = await collectSessions(config, { fs });
+
+    expect(payload.truncated).toBe(false);
+    expect(payload.sessions).toHaveLength(3);
+    expect(payload.totalSessions).toBe(3);
+  });
+
+  it("reads transcript bodies ONLY for sessions it will publish", async () => {
+    // The enumerator statted every file AND did a 16 KiB bounded read on each,
+    // before anything was filtered. On the first real box that was 9,340 reads
+    // per tick, every 5 seconds — ~150 MB of disk for 15 useful records, on
+    // the exact resource that had already taken the machine down once.
+    const reads: string[] = [];
+    const base = claudeTreeFs(500, (i) => (i < 5 ? 2 : 60 * 60 * 24 * 30));
+    const fs: FileSystemPort = {
+      ...base,
+      async readBounded(path, maxBytes, from) {
+        reads.push(path);
+        return base.readBounded(path, maxBytes, from);
+      },
+    };
+
+    const payload = await collectSessions(config, { fs });
+
+    expect(payload.sessions).toHaveLength(5);
+    // Five live sessions ⇒ five reads, not five hundred.
+    expect(reads).toHaveLength(5);
+  });
+
+  it("keeps the MOST RECENTLY ACTIVE sessions when it has to choose", async () => {
+    // Index 0 is freshest, index N oldest — all still within `idle`.
+    const fs = claudeTreeFs(5000, (i) => 1 + i * (1 / 10));
+
+    const payload = await collectSessions(config, { fs });
+
+    expect(payload.truncated).toBe(true);
+    // Dropping the newest and keeping stale ones would make the live view
+    // wrong in the one way that matters.
+    const kept = payload.sessions
+      .map((s) => Date.parse(s.lastActivityAt!))
+      .sort((a, b) => a - b);
+    const oldestKept = kept[0]!;
+    const cutoff =
+      NOW_MS - DEFAULT_LIVENESS_THRESHOLDS.idleWithinSeconds * 1000;
+    expect(oldestKept).toBeGreaterThan(cutoff);
+    // The single freshest session must always survive.
+    expect(Math.max(...kept)).toBe(NOW_MS - 1000);
+  });
+});

package/src/outpost/session-heartbeat-guard.test.ts

@@ -0,0 +1,105 @@
+/**
+ * The no-secrets guard must catch credentials WITHOUT catching ordinary paths.
+ *
+ * Both halves matter equally, and the second is easy to get wrong. The guard
+ * throws, and a throw fails the whole tick — so a pattern that matches a
+ * legitimate directory name silently disables reporting for the entire box
+ * until that session ages out.
+ *
+ * The original marker list held `sk-` and `asia` as bare substrings. `sk-`
+ * matches `task-runner`, `flask-app`, `disk-usage`, `risk-model`. Anyone who
+ * created a repo with one of those names would have taken the heartbeat down
+ * across the box, with the service still reporting active — the exact failure
+ * shape this whole change exists to remove.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  assertNoSecretsInPayload,
+  type AgentSession,
+  type SessionsHeartbeatPayload,
+} from "./session-heartbeat.js";
+
+function payloadWith(over: Partial<AgentSession>): SessionsHeartbeatPayload {
+  const session: AgentSession = {
+    id: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    tool: "claude",
+    origin: "outpost",
+    cwd: "/home/ec2-user/hq",
+    project: "hq",
+    company: null,
+    model: "claude-opus-4-8",
+    status: "running",
+    startedAt: "2026-07-29T12:00:00.000Z",
+    lastActivityAt: "2026-07-29T12:00:00.000Z",
+    source: "/home/ec2-user/.claude/projects/-home-ec2-user-hq/x.jsonl",
+    ...over,
+  };
+  return {
+    type: "sessions",
+    origin: "outpost",
+    emittedAt: "2026-07-29T12:00:00.000Z",
+    sessions: [session],
+  };
+}
+
+describe("ordinary paths must never trip the guard", () => {
+  // Every one of these contains `sk-` or `asia` and would have thrown before.
+  const innocentPaths = [
+    "/home/ec2-user/hq/repos/private/task-runner",
+    "/home/ec2-user/hq/repos/public/flask-app",
+    "/home/ec2-user/hq/tools/disk-usage",
+    "/home/ec2-user/hq/models/risk-model",
+    "/home/ec2-user/hq/regions/asia-pacific",
+    "/home/ec2-user/hq/repos/private/password-manager",
+    "/home/ec2-user/hq/kiosk-display",
+  ];
+
+  for (const cwd of innocentPaths) {
+    it(`allows ${cwd.split("/").pop()}`, () => {
+      const project = cwd.split("/").pop()!;
+      expect(() =>
+        assertNoSecretsInPayload(payloadWith({ cwd, project, source: `${cwd}/s.jsonl` })),
+      ).not.toThrow();
+    });
+  }
+
+  it("allows a model id that merely starts with the letters sk", () => {
+    expect(() =>
+      assertNoSecretsInPayload(payloadWith({ model: "sk-lite-preview" })),
+    ).not.toThrow();
+  });
+});
+
+describe("real credentials must still be caught", () => {
+  const leaks: [string, Partial<AgentSession>][] = [
+    ["an Anthropic key", { model: "sk-ant-api03-AbCdEfGhIjKlMnOpQrStUv" }],
+    ["an OpenAI-style key", { model: "sk-AbCdEfGhIjKlMnOpQrStUvWxYz012345" }],
+    ["a long-lived AWS key id", { project: "AKIAIOSFODNN7EXAMPLE" }],
+    ["an STS temp key id", { project: "ASIAIOSFODNN7EXAMPLE" }],
+    ["a PEM private key", { cwd: "-----BEGIN RSA PRIVATE KEY-----" }],
+    ["an authorization header", { model: "authorization: xyz" }],
+    ["a bearer token", { model: "Bearer abcdefghijklmnop0123" }],
+    ["an instance token header", { project: "x-outpost-instance-token" }],
+    ["a refresh token field", { model: 'refresh_token="abc"' }],
+    ["a password field", { model: "password=hunter2" }],
+    ["a secret access key", { project: "secretaccesskey" }],
+    ["a session token", { project: "sessiontoken" }],
+  ];
+
+  for (const [what, over] of leaks) {
+    it(`rejects ${what}`, () => {
+      expect(() => assertNoSecretsInPayload(payloadWith(over))).toThrow(
+        /refusing to publish/,
+      );
+    });
+  }
+});
+
+describe("non-whitelisted fields are still rejected", () => {
+  it("refuses a payload carrying an extra field", () => {
+    const p = payloadWith({});
+    (p.sessions[0] as unknown as Record<string, unknown>).transcript = "secret";
+    expect(() => assertNoSecretsInPayload(p)).toThrow(/non-whitelisted/);
+  });
+});