@indigoai-us/hq-cli 5.56.0 → 5.57.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [5.55.1]
+
+### Fixed
+
+- **`hq meetings list` no longer crashes when a meeting has no title.** The list
+  renderer read `title.length` for column sizing and row truncation, assuming
+  every meeting has a string title. The API can return a meeting whose title is
+  null/undefined, so the command printed the `Meetings (N)` header and then died
+  with `Cannot read properties of undefined (reading 'length')`. Missing titles
+  now render as `(untitled)` and the command completes normally. (#164)
+- **`hq meetings get <short-id>` never sends a truncated id to the by-id
+  endpoint.** A short (8-char) id prefix is now resolved to the full meeting id
+  before the lookup, so short-id `get` no longer fails or targets the wrong
+  meeting. (#163)
+- **`hq sync push` no longer reports a false-green success while silently
+  dropping files.** When a push excluded files that fell outside the caller's
+  granted write prefixes (hit by members holding only a company-wide write grant
+  on an older client), the summary now surfaces the scope-excluded files loudly
+  instead of reporting a clean success. (#162)
+
+## [5.55.0]
+
+### Added
+
+- **`hq reindex --from-hook` / `--lock-timeout`** to bound the op-lock wait so a
+  hook-triggered reindex no-waits instead of blocking. (#160)
+
 ## [5.54.0]
 
 ### Added

package/dist/commands/groups.d.ts

@@ -1,3 +1,7 @@
 import { Command } from "commander";
+export declare function detectPrincipalType(principal: string): {
+    granteeType: "email" | "person";
+    granteeId: string;
+} | null;
 export declare function registerGroupsCommand(program: Command): void;
 //# sourceMappingURL=groups.d.ts.map

package/dist/commands/groups.js

@@ -1,18 +1,23 @@
 
-!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]="35b60d26-d8e7-5c10-9ad4-db53285eaaf0")}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]="caec6a8e-2b28-583a-acb3-1e70ab6c390c")}catch(e){}}();
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN } from "./_patterns.js";
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
-function detectPrincipalType(principal) {
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
+const INVALID_PRINCIPAL_HINT = "must be an email address, a personUid (prs_…), or an agentUid (agt_…)";
+export function detectPrincipalType(principal) {
     if (EMAIL_PATTERN.test(principal)) {
         // Server normalizes email again; we normalize here so local validation /
         // cache keys agree with the server-side canonicalization.
         return { granteeType: "email", granteeId: principal.trim().toLowerCase() };
     }
-    if (PERSON_UID_PATTERN.test(principal)) {
+    // Agent uids ride the same personUid wire slot as people — that is the
+    // server contract (group members, DM recipients, and memberships all carry
+    // agt_* in the personUid field; see hq-pro handlers).
+    if (PERSON_UID_PATTERN.test(principal) || AGENT_UID_PATTERN.test(principal)) {
         return { granteeType: "person", granteeId: principal };
     }
     return null;
@@ -124,7 +129,7 @@ export function registerGroupsCommand(program) {
     });
     groups
         .command("add <groupId> <principal>")
-        .description("Add a person to a group (principal: email or personUid)")
+        .description("Add a person or agent to a group (principal: email, personUid, or agentUid)")
         .action(async (groupId, principal) => {
         try {
             if (!GROUP_ID_PATTERN.test(groupId)) {
@@ -133,7 +138,7 @@ export function registerGroupsCommand(program) {
             }
             const detected = detectPrincipalType(principal);
             if (!detected) {
-                console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a personUid matching prs_<alphanumeric>`));
+                console.error(chalk.red(`Invalid principal '${principal}': ${INVALID_PRINCIPAL_HINT}`));
                 process.exit(1);
             }
             const token = await ensureCognitoToken();
@@ -174,7 +179,7 @@ export function registerGroupsCommand(program) {
     });
     groups
         .command("remove <groupId> <principal>")
-        .description("Remove a person from a group (principal: email or personUid)")
+        .description("Remove a person or agent from a group (principal: email, personUid, or agentUid)")
         .action(async (groupId, principal) => {
         try {
             if (!GROUP_ID_PATTERN.test(groupId)) {
@@ -183,7 +188,7 @@ export function registerGroupsCommand(program) {
             }
             const detected = detectPrincipalType(principal);
             if (!detected) {
-                console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a personUid matching prs_<alphanumeric>`));
+                console.error(chalk.red(`Invalid principal '${principal}': ${INVALID_PRINCIPAL_HINT}`));
                 process.exit(1);
             }
             const token = await ensureCognitoToken();
@@ -345,4 +350,4 @@ export function registerGroupsCommand(program) {
     });
 }
 //# sourceMappingURL=groups.js.map
-//# debugId=35b60d26-d8e7-5c10-9ad4-db53285eaaf0
+//# debugId=caec6a8e-2b28-583a-acb3-1e70ab6c390c

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]="2640a391-a3e6-5830-b56f-03b5fab3a4bd")}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]="f2fc6ee0-c7c4-5012-85ce-aea36030aa92")}catch(e){}}();
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
@@ -75,8 +75,12 @@ function printMeetingTable(meetings) {
         console.log(chalk.dim("  No meetings found."));
         return;
     }
+    // Titles can come back null/undefined from the API even though the type says
+    // string; fall back to a placeholder so width calc + rendering never crash on
+    // `undefined.length`.
+    const displayTitle = (m) => m.title ?? "(untitled)";
     const ID_W = 8;
-    const TITLE_W = Math.min(40, Math.max(10, ...meetings.map((m) => m.title.length)));
+    const TITLE_W = Math.min(40, Math.max(10, ...meetings.map((m) => displayTitle(m).length)));
     const DATE_W = 16;
     const DUR_W = 8;
     const STATUS_W = 12;
@@ -93,7 +97,8 @@ function printMeetingTable(meetings) {
     ].join("  ")));
     for (const m of meetings) {
         const id = m.meetingId.slice(0, 8);
-        const title = m.title.length > TITLE_W ? m.title.slice(0, TITLE_W - 1) + "…" : m.title;
+        const fullTitle = displayTitle(m);
+        const title = fullTitle.length > TITLE_W ? fullTitle.slice(0, TITLE_W - 1) + "…" : fullTitle;
         const date = new Date(m.startTime).toLocaleDateString("en-US", {
             month: "short",
             day: "numeric",
@@ -432,4 +437,4 @@ export function registerMeetingsCommand(program) {
     });
 }
 //# sourceMappingURL=meetings.js.map
-//# debugId=2640a391-a3e6-5830-b56f-03b5fab3a4bd
+//# debugId=f2fc6ee0-c7c4-5012-85ce-aea36030aa92

package/dist/commands/secrets.d.ts

@@ -4,7 +4,7 @@ export type { VaultApiOptions } from "../utils/vault-api.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
 export type SecretTier = "standard" | "sensitive" | "nuclear";
 export type SecretScriptLockMode = "off" | "enforced";
-export type SecretUsageChannel = "run" | "exec" | "env" | "reveal" | "submit-link";
+export type SecretUsageChannel = "run" | "exec" | "env" | "sandbox" | "reveal" | "submit-link";
 export interface SecretScriptUsage {
     scriptId: string;
     path: string;
@@ -36,6 +36,7 @@ export interface SecretLoadResponse {
         message?: string;
     }>;
 }
+export declare function scrubSandboxOutput(text: string, secretNames?: string[]): string;
 export declare function loadRevealedSecrets(token: string, companyUid: string, keys: string[], usage?: SecretUsage): Promise<Map<string, string>>;
 export declare function registerSecretsCommand(program: Command): void;
 //# sourceMappingURL=secrets.d.ts.map

package/dist/commands/secrets.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]="1dfcad18-3626-5c68-8b4c-0c147e896113")}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]="18312d3d-7daf-5faf-ac29-c82ce7bd0b29")}catch(e){}}();
 import chalk from "chalk";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
@@ -10,6 +10,7 @@ import { computeSha256 } from "../utils/integrity.js";
 import { SECRET_NAME_PATTERN, GROUP_ID_PATTERN, EMAIL_PATTERN } from "./_patterns.js";
 import { describeSecretsScope, formatSecretSaved, formatSecretsListEmpty, formatSecretsListHeader, } from "./secrets-scope.js";
 import { vaultApiFetch, getCompanyUid, getEntityUid, } from "../utils/vault-api.js";
+import { SandboxRunnerClient, } from "../utils/sandbox-runner-client.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
 function scopeOpts(opts) {
     if (opts.personal && opts.company) {
@@ -183,6 +184,49 @@ async function buildSecretUsage(channel, scriptPath, scriptId, attestationLevel
         },
     };
 }
+function parseSecretNameList(input) {
+    const keys = input.split(",").map((k) => k.trim()).filter(Boolean);
+    if (keys.length === 0) {
+        console.error(chalk.red("Error: --only requires at least one secret name."));
+        process.exit(1);
+    }
+    for (const key of keys) {
+        if (!SECRET_NAME_PATTERN.test(key)) {
+            console.error(chalk.red(`Invalid secret name '${key}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$`));
+            process.exit(1);
+        }
+    }
+    return keys;
+}
+function mergeScopeOpts(parent, child) {
+    return {
+        company: child.company ?? parent.company,
+        personal: child.personal ?? parent.personal,
+    };
+}
+export function scrubSandboxOutput(text, secretNames = []) {
+    let scrubbed = text;
+    for (const name of secretNames) {
+        const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        scrubbed = scrubbed.replace(new RegExp(`\\b(${escaped})\\s*=\\s*([^\\s'"\\n]+|'[^'\\n]*'|"[^"\\n]*")`, "g"), "$1=[REDACTED]");
+        scrubbed = scrubbed.replace(new RegExp(`\\b(${escaped})\\s*:\\s*([^\\s'"\\n]+|'[^'\\n]*'|"[^"\\n]*")`, "g"), "$1: [REDACTED]");
+    }
+    return scrubbed
+        .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "[REDACTED]")
+        .replace(/\bgh[pousr]_[A-Za-z0-9_]{16,}\b/g, "[REDACTED]")
+        .replace(/\b[A-Za-z0-9+/]{40,}={0,2}\b/g, "[REDACTED]");
+}
+function renderSandboxJobResult(job, secretNames) {
+    if (job.stdout) {
+        process.stdout.write(scrubSandboxOutput(job.stdout, secretNames));
+    }
+    if (job.stderr) {
+        process.stderr.write(scrubSandboxOutput(job.stderr, secretNames));
+    }
+    if (job.logsTail) {
+        process.stderr.write(scrubSandboxOutput(job.logsTail, secretNames));
+    }
+}
 function normalizePolicyRecord(secretPath, data) {
     const policy = data.policy ?? { path: secretPath };
     const scripts = Array.isArray(policy.scripts)
@@ -826,6 +870,56 @@ export function registerSecretsCommand(program) {
             process.exit(1);
         }
     });
+    secrets
+        .command("sandbox")
+        .description("Run a skill in the hosted sandbox with secrets injected server-side")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--personal", "Operate on the caller's personal vault (no sharing)")
+        .option("--only <keys>", "Comma-separated list of secret names the skill may use")
+        .option("--script <path>", "Attach local script identity for script-locked secrets")
+        .allowUnknownOption(true)
+        .action(async (opts, cmd) => {
+        try {
+            const dashIndex = process.argv.indexOf("--");
+            const rawArgs = dashIndex !== -1 ? process.argv.slice(dashIndex + 1) : cmd.args;
+            if (rawArgs.length === 0) {
+                console.error(chalk.red("Error: no skill specified. Usage: hq secrets sandbox [--company X] [--only KEY1,KEY2] -- <skill> [args...]"));
+                process.exit(1);
+            }
+            const [skillId, ...skillArgs] = rawArgs;
+            const keys = opts.only ? parseSecretNameList(opts.only) : [];
+            const token = await ensureCognitoToken();
+            const scope = scopeOpts(mergeScopeOpts(secrets.opts(), opts));
+            const companyUid = await getEntityUid(token, scope);
+            const usage = await buildSecretUsage("sandbox", opts.script);
+            const client = new SandboxRunnerClient();
+            const started = await client.startJob(token, {
+                skillId,
+                companyUid,
+                args: skillArgs.length > 0 ? { argv: skillArgs } : undefined,
+                companySlug: scope.companySlug,
+                only: keys.length > 0 ? keys : undefined,
+                usage,
+            });
+            const job = started.status === "succeeded" || started.status === "failed"
+                ? await client.getJob(token, started.jobId)
+                : await client.pollJob(token, started.jobId);
+            renderSandboxJobResult(job, keys);
+            if (job.status === "failed") {
+                if (job.error) {
+                    console.error(chalk.red("Sandbox job failed:"), scrubSandboxOutput(job.error, keys));
+                }
+                process.exit(job.exitCode && job.exitCode > 0 ? job.exitCode : 1);
+            }
+            if (job.exitCode && job.exitCode !== 0) {
+                process.exit(job.exitCode);
+            }
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? scrubSandboxOutput(err.message) : scrubSandboxOutput(String(err)));
+            process.exit(1);
+        }
+    });
     secrets
         .command("exec")
         .description("Run a command with secrets injected as env vars")
@@ -847,17 +941,7 @@ export function registerSecretsCommand(program) {
                 console.error(chalk.red("Error: no command specified. Usage: hq secrets exec --only KEY1,KEY2 -- <command>"));
                 process.exit(1);
             }
-            const keys = _opts.only.split(",").map((k) => k.trim()).filter(Boolean);
-            if (keys.length === 0) {
-                console.error(chalk.red("Error: --only requires at least one secret name."));
-                process.exit(1);
-            }
-            for (const key of keys) {
-                if (!SECRET_NAME_PATTERN.test(key)) {
-                    console.error(chalk.red(`Invalid secret name '${key}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$`));
-                    process.exit(1);
-                }
-            }
+            const keys = parseSecretNameList(_opts.only);
             const token = await ensureCognitoToken();
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const revealed = await loadRevealedSecrets(token, companyUid, keys, await buildSecretUsage("exec", _opts.script));
@@ -903,17 +987,7 @@ export function registerSecretsCommand(program) {
             if (redact) {
                 console.error(chalk.yellow("stdout is a terminal — values redacted. Use: source <(hq secrets env --only KEY1,KEY2)"));
             }
-            const keys = opts.only.split(",").map((k) => k.trim()).filter(Boolean);
-            if (keys.length === 0) {
-                console.error(chalk.red("Error: --only requires at least one secret name."));
-                process.exit(1);
-            }
-            for (const key of keys) {
-                if (!SECRET_NAME_PATTERN.test(key)) {
-                    console.error(chalk.red(`Invalid secret name '${key}': must match ^[A-Z][A-Z0-9_]*(/[A-Z][A-Z0-9_]+)*$`));
-                    process.exit(1);
-                }
-            }
+            const keys = parseSecretNameList(opts.only);
             const token = await ensureCognitoToken();
             const companyUid = await getEntityUid(token, scopeOpts(secrets.opts()));
             const revealed = await loadRevealedSecrets(token, companyUid, keys, await buildSecretUsage("env", opts.script));
@@ -1187,4 +1261,4 @@ export function registerSecretsCommand(program) {
     });
 }
 //# sourceMappingURL=secrets.js.map
-//# debugId=1dfcad18-3626-5c68-8b4c-0c147e896113
+//# debugId=18312d3d-7daf-5faf-ac29-c82ce7bd0b29

package/dist/utils/sandbox-runner-client.d.ts

@@ -0,0 +1,39 @@
+export type SandboxRunnerState = "queued" | "running" | "succeeded" | "failed";
+export interface SandboxRunnerStartRequest {
+    skillId: string;
+    companyUid: string;
+    args?: Record<string, unknown>;
+    companySlug?: string;
+    only?: string[];
+    usage?: unknown;
+}
+export interface SandboxRunnerStartResponse {
+    jobId: string;
+    status: SandboxRunnerState;
+}
+export interface SandboxRunnerJob {
+    jobId: string;
+    status: SandboxRunnerState;
+    stdout?: string;
+    stderr?: string;
+    logsTail?: string;
+    exitCode?: number;
+    error?: string;
+}
+export interface SandboxRunnerClientOptions {
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export interface SandboxRunnerPollOptions {
+    intervalMs?: number;
+    maxPolls?: number;
+}
+export declare class SandboxRunnerClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: SandboxRunnerClientOptions);
+    startJob(token: string, request: SandboxRunnerStartRequest): Promise<SandboxRunnerStartResponse>;
+    getJob(token: string, jobId: string): Promise<SandboxRunnerJob>;
+    pollJob(token: string, jobId: string, options?: SandboxRunnerPollOptions): Promise<SandboxRunnerJob>;
+}
+//# sourceMappingURL=sandbox-runner-client.d.ts.map

package/dist/utils/sandbox-runner-client.js

@@ -0,0 +1,113 @@
+
+!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]="8203259b-d3ae-5c9b-845e-f4c1470c30f3")}catch(e){}}();
+const DEFAULT_SANDBOX_RUNNER_URL = "https://hqapi.getindigo.ai/sandbox";
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}
+function getSandboxRunnerBaseUrl() {
+    return normalizeBaseUrl(process.env.HQ_SANDBOX_RUNNER_URL ?? DEFAULT_SANDBOX_RUNNER_URL);
+}
+function isSandboxRunnerState(value) {
+    return value === "queued" || value === "running" || value === "succeeded" || value === "failed";
+}
+async function parseJsonResponse(res) {
+    return (await res.json().catch(() => ({})));
+}
+function requireString(body, key) {
+    const value = body[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Sandbox Runner returned an invalid '${key}'.`);
+    }
+    return value;
+}
+function normalizeJob(body, jobIdFallback) {
+    const status = body.status;
+    if (!isSandboxRunnerState(status)) {
+        throw new Error("Sandbox Runner returned an invalid job status.");
+    }
+    const output = typeof body.stdout === "string"
+        ? body.stdout
+        : typeof body.output === "string"
+            ? body.output
+            : undefined;
+    return {
+        jobId: typeof body.jobId === "string" && body.jobId.length > 0
+            ? body.jobId
+            : jobIdFallback ?? requireString(body, "jobId"),
+        status,
+        stdout: output,
+        stderr: typeof body.stderr === "string" ? body.stderr : undefined,
+        logsTail: typeof body.logsTail === "string" ? body.logsTail : undefined,
+        exitCode: typeof body.exitCode === "number" ? body.exitCode : undefined,
+        error: typeof body.error === "string" ? body.error : undefined,
+    };
+}
+function delay(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export class SandboxRunnerClient {
+    baseUrl;
+    fetchImpl;
+    constructor(options = {}) {
+        this.baseUrl = normalizeBaseUrl(options.baseUrl ?? getSandboxRunnerBaseUrl());
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async startJob(token, request) {
+        const res = await this.fetchImpl(`${this.baseUrl}/jobs`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(request),
+        });
+        const body = await parseJsonResponse(res);
+        if (!res.ok) {
+            const message = typeof body.message === "string"
+                ? body.message
+                : typeof body.error === "string"
+                    ? body.error
+                    : res.statusText;
+            throw new Error(`Sandbox Runner rejected job: ${message}`);
+        }
+        const status = body.status;
+        if (!isSandboxRunnerState(status)) {
+            throw new Error("Sandbox Runner returned an invalid start status.");
+        }
+        return {
+            jobId: requireString(body, "jobId"),
+            status,
+        };
+    }
+    async getJob(token, jobId) {
+        const res = await this.fetchImpl(`${this.baseUrl}/jobs/${encodeURIComponent(jobId)}`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        const body = await parseJsonResponse(res);
+        if (!res.ok) {
+            const message = typeof body.message === "string"
+                ? body.message
+                : typeof body.error === "string"
+                    ? body.error
+                    : res.statusText;
+            throw new Error(`Sandbox Runner job lookup failed: ${message}`);
+        }
+        return normalizeJob(body, jobId);
+    }
+    async pollJob(token, jobId, options = {}) {
+        const intervalMs = options.intervalMs ?? 1000;
+        const maxPolls = options.maxPolls ?? 300;
+        for (let attempt = 0; attempt < maxPolls; attempt += 1) {
+            const job = await this.getJob(token, jobId);
+            if (job.status === "succeeded" || job.status === "failed") {
+                return job;
+            }
+            await delay(intervalMs);
+        }
+        throw new Error(`Sandbox Runner job '${jobId}' did not finish before the poll limit.`);
+    }
+}
+//# sourceMappingURL=sandbox-runner-client.js.map
+//# debugId=8203259b-d3ae-5c9b-845e-f4c1470c30f3

package/package.json

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

package/src/commands/groups.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Unit tests for `hq groups` principal detection (groups.ts).
+ *
+ * Regression coverage for feedback_edb1796a-24be-4b9f-bc60-a06f39d1c9f2:
+ * `hq groups add` rejected agent identities (agt_<ULID>), forcing per-agent
+ * secret shares instead of group-carried ACLs. Agent uids ride the same
+ * personUid wire slot as people (server contract — the group-members handler
+ * accepts granteeType "person" with an agt_* granteeId, and every ACL
+ * evaluation keys off caller.personUid, which for agent JWTs IS the agt_ uid).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { detectPrincipalType } from "./groups.js";
+
+describe("detectPrincipalType", () => {
+  it("detects an email principal and normalizes it", () => {
+    expect(detectPrincipalType("Jane@Example.COM")).toEqual({
+      granteeType: "email",
+      granteeId: "jane@example.com",
+    });
+  });
+
+  it("detects a personUid principal", () => {
+    expect(detectPrincipalType("prs_01ABCDEF")).toEqual({
+      granteeType: "person",
+      granteeId: "prs_01ABCDEF",
+    });
+  });
+
+  it("detects an agentUid principal and sends it in the person slot (regression)", () => {
+    expect(detectPrincipalType("agt_01KWFVWZYX8H1DN57ZPNZNKM6C")).toEqual({
+      granteeType: "person",
+      granteeId: "agt_01KWFVWZYX8H1DN57ZPNZNKM6C",
+    });
+  });
+
+  it("rejects malformed principals", () => {
+    expect(detectPrincipalType("agt_")).toBeNull();
+    expect(detectPrincipalType("prs_")).toBeNull();
+    expect(detectPrincipalType("grp_finance")).toBeNull();
+    expect(detectPrincipalType("not a principal")).toBeNull();
+  });
+});

package/src/commands/groups.ts

@@ -6,8 +6,12 @@ import { GROUP_ID_PATTERN } from "./_patterns.js";
 
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
 
-function detectPrincipalType(
+const INVALID_PRINCIPAL_HINT =
+  "must be an email address, a personUid (prs_…), or an agentUid (agt_…)";
+
+export function detectPrincipalType(
   principal: string,
 ): { granteeType: "email" | "person"; granteeId: string } | null {
   if (EMAIL_PATTERN.test(principal)) {
@@ -15,7 +19,10 @@ function detectPrincipalType(
     // cache keys agree with the server-side canonicalization.
     return { granteeType: "email", granteeId: principal.trim().toLowerCase() };
   }
-  if (PERSON_UID_PATTERN.test(principal)) {
+  // Agent uids ride the same personUid wire slot as people — that is the
+  // server contract (group members, DM recipients, and memberships all carry
+  // agt_* in the personUid field; see hq-pro handlers).
+  if (PERSON_UID_PATTERN.test(principal) || AGENT_UID_PATTERN.test(principal)) {
     return { granteeType: "person", granteeId: principal };
   }
   return null;
@@ -130,7 +137,7 @@ export function registerGroupsCommand(program: Command): void {
 
   groups
     .command("add <groupId> <principal>")
-    .description("Add a person to a group (principal: email or personUid)")
+    .description("Add a person or agent to a group (principal: email, personUid, or agentUid)")
     .action(async (groupId: string, principal: string) => {
       try {
         if (!GROUP_ID_PATTERN.test(groupId)) {
@@ -140,7 +147,7 @@ export function registerGroupsCommand(program: Command): void {
 
         const detected = detectPrincipalType(principal);
         if (!detected) {
-          console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a personUid matching prs_<alphanumeric>`));
+          console.error(chalk.red(`Invalid principal '${principal}': ${INVALID_PRINCIPAL_HINT}`));
           process.exit(1);
         }
 
@@ -181,7 +188,7 @@ export function registerGroupsCommand(program: Command): void {
 
   groups
     .command("remove <groupId> <principal>")
-    .description("Remove a person from a group (principal: email or personUid)")
+    .description("Remove a person or agent from a group (principal: email, personUid, or agentUid)")
     .action(async (groupId: string, principal: string) => {
       try {
         if (!GROUP_ID_PATTERN.test(groupId)) {
@@ -191,7 +198,7 @@ export function registerGroupsCommand(program: Command): void {
 
         const detected = detectPrincipalType(principal);
         if (!detected) {
-          console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a personUid matching prs_<alphanumeric>`));
+          console.error(chalk.red(`Invalid principal '${principal}': ${INVALID_PRINCIPAL_HINT}`));
           process.exit(1);
         }
 

package/src/commands/meetings.test.ts

@@ -304,3 +304,49 @@ describe("meetings set-company", () => {
     expect(output).not.toContain("Future occurrences of this recurring series will inherit this attribution.");
   });
 });
+
+describe("meetings list — null-safe rendering", () => {
+  it("does not crash when a meeting has an undefined or null title", async () => {
+    // The API can return meetings with a missing/null title even though the
+    // type says string. This list previously crashed with
+    // "Cannot read properties of undefined (reading 'length')" after printing
+    // the header. Assert the command completes and renders a placeholder.
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonRes({
+        meetings: [
+          {
+            meetingId: "589bfd78-aaaa-bbbb-cccc-1234567890ab",
+            // title intentionally omitted (undefined)
+            status: "ready",
+            startTime: "2026-01-01T00:00:00Z",
+            endTime: "2026-01-01T00:30:00Z",
+            duration: 1800,
+            participantCount: 3,
+            hasTranscript: true,
+            hasNotes: false,
+          },
+          {
+            meetingId: "689bfd78-aaaa-bbbb-cccc-1234567890ab",
+            title: null,
+            status: "ready",
+            startTime: "2026-01-02T00:00:00Z",
+            endTime: "2026-01-02T00:30:00Z",
+            duration: 1800,
+            participantCount: 1,
+            hasTranscript: false,
+            hasNotes: true,
+          },
+        ],
+      }),
+    );
+
+    const program = buildProgram();
+    await expect(
+      program.parseAsync(["node", "hq", "meetings", "list", "--company", "indigo"]),
+    ).resolves.toBeDefined();
+
+    const printed = logSpy.mock.calls.map(([line]) => String(line)).join("\n");
+    expect(printed).toContain("Meetings (2)");
+    expect(printed).toContain("(untitled)");
+  });
+});