@indigoai-us/hq-cli 5.56.0 → 5.58.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]="12b04dfd-a264-56c7-bfbb-a448c35689b3")}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,43 @@ 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.output) {
+        process.stdout.write(scrubSandboxOutput(job.output, secretNames));
+    }
+}
 function normalizePolicyRecord(secretPath, data) {
     const policy = data.policy ?? { path: secretPath };
     const scripts = Array.isArray(policy.scripts)
@@ -826,6 +864,55 @@ export function registerSecretsCommand(program) {
             process.exit(1);
         }
     });
+    secrets
+        .command("sandbox")
+        .description("Run a command in the hosted sandbox with named secrets injected as env vars; open egress, secrets never touch this machine")
+        .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 to inject (required)")
+        .allowUnknownOption(true)
+        .action(async (opts, cmd) => {
+        try {
+            if (!opts.only || opts.only.trim().length === 0) {
+                console.error(chalk.red("Error: --only is required and must name at least one secret."));
+                process.exit(1);
+            }
+            const rawArgs = cmd.args;
+            const command = rawArgs.join(" ").trim();
+            if (command.length === 0) {
+                console.error(chalk.red("Error: no command specified. Usage: hq secrets sandbox --company <slug> --only KEY1,KEY2 -- <command>"));
+                process.exit(1);
+            }
+            if (command.length > 8192) {
+                console.error(chalk.red("Error: sandbox command exceeds the 8192 character limit."));
+                process.exit(1);
+            }
+            const keys = parseSecretNameList(opts.only);
+            const token = await ensureCognitoToken();
+            const scope = scopeOpts(mergeScopeOpts(secrets.opts(), opts));
+            const companyUid = await getEntityUid(token, scope);
+            const client = new SandboxRunnerClient();
+            const started = await client.startJob(token, {
+                companyUid,
+                secretNames: keys,
+                command,
+            });
+            const job = started.status === "succeeded" || started.status === "failed"
+                ? await client.getJob(token, started.jobId)
+                : await client.pollJob(token, started.jobId);
+            renderSandboxJobResult(job, keys);
+            const exitCode = typeof job.exitCode === "number" ? job.exitCode : undefined;
+            if (job.success === false || (exitCode !== undefined && exitCode !== 0) || job.status === "failed") {
+                const code = exitCode && exitCode !== 0 ? exitCode : 1;
+                console.error(chalk.red(`Sandbox command failed with exit code ${code}.`));
+                process.exit(code);
+            }
+        }
+        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 +934,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 +980,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 +1254,4 @@ export function registerSecretsCommand(program) {
     });
 }
 //# sourceMappingURL=secrets.js.map
-//# debugId=1dfcad18-3626-5c68-8b4c-0c147e896113
+//# debugId=12b04dfd-a264-56c7-bfbb-a448c35689b3

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

@@ -0,0 +1,34 @@
+export type SandboxRunnerState = "queued" | "running" | "succeeded" | "failed";
+export interface SandboxRunnerStartRequest {
+    companyUid: string;
+    secretNames: string[];
+    command: string;
+}
+export interface SandboxRunnerStartResponse {
+    jobId: string;
+    status: SandboxRunnerState;
+}
+export interface SandboxRunnerJob {
+    jobId: string;
+    status: SandboxRunnerState;
+    output?: string;
+    exitCode?: number;
+    success?: boolean;
+}
+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,106 @@
+
+!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]="3cbec729-3b2b-5d53-9e90-5680dd725b7d")}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.");
+    }
+    return {
+        jobId: typeof body.jobId === "string" && body.jobId.length > 0
+            ? body.jobId
+            : jobIdFallback ?? requireString(body, "jobId"),
+        status,
+        output: typeof body.output === "string" ? body.output : undefined,
+        exitCode: typeof body.exitCode === "number" ? body.exitCode : undefined,
+        success: typeof body.success === "boolean" ? body.success : 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=3cbec729-3b2b-5d53-9e90-5680dd725b7d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.56.0",
+  "version": "5.58.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)");
+  });
+});

package/src/commands/meetings.ts

@@ -150,8 +150,13 @@ function printMeetingTable(meetings: MeetingListItem[]): void {
     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: MeetingListItem): string => 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;
@@ -174,7 +179,8 @@ function printMeetingTable(meetings: MeetingListItem[]): void {
 
   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",

package/src/commands/secrets.test.ts

@@ -56,10 +56,16 @@ vi.mock("node:child_process", () => ({
 }));
 
 import { Command } from "commander";
-import { registerSecretsCommand, loadRevealedSecrets } from "./secrets.js";
+import {
+  registerSecretsCommand,
+  loadRevealedSecrets,
+  type SecretUsageChannel,
+} from "./secrets.js";
 import { spawn } from "node:child_process";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { getEntityUid, vaultApiFetch } from "../utils/vault-api.js";
 import { readCache, writeCache } from "../utils/secrets-cache.js";
+import { SandboxRunnerClient } from "../utils/sandbox-runner-client.js";
 
 let logSpy: MockInstance<typeof console.log>;
 let errSpy: MockInstance<typeof console.error>;
@@ -95,6 +101,199 @@ function jsonRes(body: unknown, status = 200): Response {
   });
 }
 
+describe("secrets sandbox", () => {
+  let stdoutSpy: MockInstance<typeof process.stdout.write>;
+  let stderrSpy: MockInstance<typeof process.stderr.write>;
+  let exitSpy: MockInstance<typeof process.exit>;
+  let startJobSpy: MockInstance<SandboxRunnerClient["startJob"]>;
+  let pollJobSpy: MockInstance<SandboxRunnerClient["pollJob"]>;
+  let getJobSpy: MockInstance<SandboxRunnerClient["getJob"]>;
+
+  beforeEach(() => {
+    stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    startJobSpy = vi
+      .spyOn(SandboxRunnerClient.prototype, "startJob")
+      .mockResolvedValue({ jobId: "job_123", status: "queued" });
+    pollJobSpy = vi
+      .spyOn(SandboxRunnerClient.prototype, "pollJob")
+      .mockResolvedValue({
+        jobId: "job_123",
+        status: "succeeded",
+        output: "done\n",
+        exitCode: 0,
+        success: true,
+      });
+    getJobSpy = vi.spyOn(SandboxRunnerClient.prototype, "getJob");
+    exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("__exit__");
+    }) as never);
+  });
+
+  it("registers the sandbox channel value", () => {
+    const channel: SecretUsageChannel = "sandbox";
+    expect(channel).toBe("sandbox");
+  });
+
+  it("parses --company, --only, and joins args after -- into a command", async () => {
+    const program = buildProgram();
+    await program.parseAsync([
+      "node",
+      "hq",
+      "secrets",
+      "sandbox",
+      "--company",
+      "acme",
+      "--only",
+      "API_KEY,OTHER_KEY",
+      "--",
+      "node",
+      "-e",
+      "console.log('hi')",
+      "--days",
+      "7",
+    ]);
+
+    expect(startJobSpy).toHaveBeenCalledWith("test-token", {
+      companyUid: "prs_alice",
+      secretNames: ["API_KEY", "OTHER_KEY"],
+      command: "node -e console.log('hi') --days 7",
+    });
+    expect(stdoutSpy).toHaveBeenCalledWith("done\n");
+  });
+
+  it("requires --only", async () => {
+    const program = buildProgram();
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "hq",
+        "secrets",
+        "sandbox",
+        "--",
+        "env",
+      ]),
+    ).rejects.toThrow("__exit__");
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(errSpy.mock.calls.flat().join(" ")).toMatch(/--only is required/i);
+    expect(startJobSpy).not.toHaveBeenCalled();
+  });
+
+  it("requires a command after --", async () => {
+    const program = buildProgram();
+
+    await expect(
+      program.parseAsync([
+        "node",
+        "hq",
+        "secrets",
+        "sandbox",
+        "--only",
+        "API_KEY",
+      ]),
+    ).rejects.toThrow("__exit__");
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(errSpy.mock.calls.flat().join(" ")).toMatch(/no command specified/i);
+    expect(startJobSpy).not.toHaveBeenCalled();
+  });
+
+  it("resolves identity before posting the runner job", async () => {
+    const program = buildProgram();
+    await program.parseAsync([
+      "node",
+      "hq",
+      "secrets",
+      "--company",
+      "parent-co",
+      "sandbox",
+      "--only",
+      "API_KEY",
+      "--",
+      "env",
+    ]);
+
+    expect(ensureCognitoToken).toHaveBeenCalled();
+    expect(getEntityUid).toHaveBeenCalledWith("test-token", {
+      personal: false,
+      companySlug: "parent-co",
+    });
+    expect(startJobSpy).toHaveBeenCalledWith("test-token", {
+      companyUid: "prs_alice",
+      secretNames: ["API_KEY"],
+      command: "env",
+    });
+  });
+
+  it("prints server-scrubbed output and never batch-loads secrets locally", async () => {
+    pollJobSpy.mockResolvedValueOnce({
+      jobId: "job_123",
+      status: "succeeded",
+      output: "token [REDACTED]\nAPI_KEY=[REDACTED]\n",
+      exitCode: 0,
+      success: true,
+    });
+
+    const program = buildProgram();
+    await program.parseAsync([
+      "node",
+      "hq",
+      "secrets",
+      "sandbox",
+      "--only",
+      "API_KEY",
+      "--",
+      "my-skill",
+    ]);
+
+    expect(vaultApiFetch).not.toHaveBeenCalledWith(
+      expect.objectContaining({ path: expect.stringContaining("/load") }),
+    );
+    expect(vaultApiFetch).not.toHaveBeenCalledWith(
+      expect.objectContaining({ path: expect.stringContaining("/name/") }),
+    );
+    const rendered = [
+      ...stdoutSpy.mock.calls.flat().map(String),
+      ...stderrSpy.mock.calls.flat().map(String),
+      ...logSpy.mock.calls.flat().map(String),
+      ...errSpy.mock.calls.flat().map(String),
+    ].join("\n");
+    expect(rendered).toContain("[REDACTED]");
+    expect(stdoutSpy).toHaveBeenCalledWith("token [REDACTED]\nAPI_KEY=[REDACTED]\n");
+  });
+
+  it("exits non-zero when the sandbox command fails", async () => {
+    pollJobSpy.mockResolvedValueOnce({
+      jobId: "job_123",
+      status: "failed",
+      output: "boom\n",
+      exitCode: 7,
+      success: false,
+    });
+
+    const program = buildProgram();
+    await expect(
+      program.parseAsync([
+        "node",
+        "hq",
+        "secrets",
+        "sandbox",
+        "--only",
+        "API_KEY",
+        "--",
+        "my-skill",
+      ]),
+    ).rejects.toThrow("__exit__");
+
+    expect(stdoutSpy).toHaveBeenCalledWith("boom\n");
+    expect(errSpy.mock.calls.flat().join(" ")).toMatch(/exit code 7/i);
+    expect(exitSpy).toHaveBeenCalledWith(7);
+    expect(getJobSpy).not.toHaveBeenCalled();
+  });
+});
+
 // HQ-4H: `hq secrets exists` — HEAD existence probe with shell-chaining exit
 // codes (0=present, 1=absent, 2=error). process.exit is spied so the command's
 // terminal exit doesn't kill the runner; we assert the code it requested.

package/src/commands/secrets.ts

@@ -24,6 +24,10 @@ import {
   getCompanyUid,
   getEntityUid,
 } from "../utils/vault-api.js";
+import {
+  SandboxRunnerClient,
+  type SandboxRunnerJob,
+} from "../utils/sandbox-runner-client.js";
 export type { VaultApiOptions } from "../utils/vault-api.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
 
@@ -172,6 +176,7 @@ export type SecretUsageChannel =
   | "run"
   | "exec"
   | "env"
+  | "sandbox"
   | "reveal"
   | "submit-link";
 
@@ -318,6 +323,56 @@ async function buildSecretUsage(
   };
 }
 
+function parseSecretNameList(input: string): string[] {
+  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: SecretsScopeOpts,
+  child: SecretsScopeOpts,
+): SecretsScopeOpts {
+  return {
+    company: child.company ?? parent.company,
+    personal: child.personal ?? parent.personal,
+  };
+}
+
+export function scrubSandboxOutput(text: string, secretNames: string[] = []): string {
+  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: SandboxRunnerJob, secretNames: string[]): void {
+  if (job.output) {
+    process.stdout.write(scrubSandboxOutput(job.output, secretNames));
+  }
+}
+
 function normalizePolicyRecord(
   secretPath: string,
   data: SecretPolicyResponse,
@@ -1186,6 +1241,65 @@ export function registerSecretsCommand(program: Command): void {
       }
     });
 
+  secrets
+    .command("sandbox")
+    .description("Run a command in the hosted sandbox with named secrets injected as env vars; open egress, secrets never touch this machine")
+    .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 to inject (required)")
+    .allowUnknownOption(true)
+    .action(async (opts: { company?: string; personal?: boolean; only?: string }, cmd: Command) => {
+      try {
+        if (!opts.only || opts.only.trim().length === 0) {
+          console.error(chalk.red("Error: --only is required and must name at least one secret."));
+          process.exit(1);
+        }
+
+        const rawArgs = cmd.args;
+        const command = rawArgs.join(" ").trim();
+        if (command.length === 0) {
+          console.error(chalk.red("Error: no command specified. Usage: hq secrets sandbox --company <slug> --only KEY1,KEY2 -- <command>"));
+          process.exit(1);
+        }
+        if (command.length > 8192) {
+          console.error(chalk.red("Error: sandbox command exceeds the 8192 character limit."));
+          process.exit(1);
+        }
+
+        const keys = parseSecretNameList(opts.only);
+        const token = await ensureCognitoToken();
+        const scope = scopeOpts(mergeScopeOpts(secrets.opts(), opts));
+        const companyUid = await getEntityUid(token, scope);
+        const client = new SandboxRunnerClient();
+        const started = await client.startJob(token, {
+          companyUid,
+          secretNames: keys,
+          command,
+        });
+        const job =
+          started.status === "succeeded" || started.status === "failed"
+            ? await client.getJob(token, started.jobId)
+            : await client.pollJob(token, started.jobId);
+
+        renderSandboxJobResult(job, keys);
+        const exitCode = typeof job.exitCode === "number" ? job.exitCode : undefined;
+        if (job.success === false || (exitCode !== undefined && exitCode !== 0) || job.status === "failed") {
+          const code = exitCode && exitCode !== 0 ? exitCode : 1;
+          console.error(chalk.red(`Sandbox command failed with exit code ${code}.`));
+          process.exit(code);
+        }
+      } 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")
@@ -1208,18 +1322,7 @@ export function registerSecretsCommand(program: Command): void {
           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(
@@ -1287,18 +1390,7 @@ export function registerSecretsCommand(program: Command): void {
           );
         }
 
-        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(

package/src/utils/sandbox-runner-client.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it, vi } from "vitest";
+import { SandboxRunnerClient } from "./sandbox-runner-client.js";
+
+function jsonRes(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("SandboxRunnerClient", () => {
+  it("posts jobs to the configured runner URL with the caller JWT", async () => {
+    const fetchImpl = vi.fn<typeof fetch>(async () =>
+      jsonRes({ jobId: "job_1", status: "queued" }),
+    );
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example/",
+      fetchImpl,
+    });
+
+    const result = await client.startJob("jwt-token", {
+      companyUid: "cmp_123",
+      secretNames: ["API_KEY"],
+      command: "node script.js --x",
+    });
+
+    expect(result).toEqual({ jobId: "job_1", status: "queued" });
+    expect(fetchImpl).toHaveBeenCalledWith("https://runner.example/jobs", {
+      method: "POST",
+      headers: {
+        Authorization: "Bearer jwt-token",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        companyUid: "cmp_123",
+        secretNames: ["API_KEY"],
+        command: "node script.js --x",
+      }),
+    });
+  });
+
+  it("polls queued and running states until succeeded", async () => {
+    const fetchImpl = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "queued" }))
+      .mockResolvedValueOnce(jsonRes({ jobId: "job_1", status: "running" }))
+      .mockResolvedValueOnce(
+        jsonRes({
+          jobId: "job_1",
+          status: "succeeded",
+          output: "ok\n",
+          exitCode: 0,
+          success: true,
+        }),
+      );
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+    });
+
+    const result = await client.pollJob("jwt-token", "job_1", {
+      intervalMs: 0,
+    });
+
+    expect(result).toEqual({
+      jobId: "job_1",
+      status: "succeeded",
+      output: "ok\n",
+      exitCode: 0,
+      success: true,
+    });
+    expect(fetchImpl).toHaveBeenCalledTimes(3);
+    expect(fetchImpl).toHaveBeenNthCalledWith(
+      1,
+      "https://runner.example/jobs/job_1",
+      { headers: { Authorization: "Bearer jwt-token" } },
+    );
+  });
+
+  it("returns failed terminal jobs with error details", async () => {
+    const fetchImpl = vi.fn<typeof fetch>(async () =>
+      jsonRes({
+        jobId: "job_1",
+        status: "failed",
+        output: "boom\n",
+        exitCode: 2,
+        success: false,
+      }),
+    );
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+    });
+
+    await expect(
+      client.pollJob("jwt-token", "job_1", { intervalMs: 0 }),
+    ).resolves.toMatchObject({
+      jobId: "job_1",
+      status: "failed",
+      output: "boom\n",
+      exitCode: 2,
+      success: false,
+    });
+  });
+
+  it("uses the requested job id when the live status response omits it", async () => {
+    const fetchImpl = vi.fn<typeof fetch>(async () =>
+      jsonRes({ status: "succeeded", output: "ok\n" }),
+    );
+    const client = new SandboxRunnerClient({
+      baseUrl: "https://runner.example",
+      fetchImpl,
+    });
+
+    await expect(client.getJob("jwt-token", "job_live")).resolves.toEqual({
+      jobId: "job_live",
+      status: "succeeded",
+      output: "ok\n",
+      exitCode: undefined,
+      success: undefined,
+    });
+  });
+});

package/src/utils/sandbox-runner-client.ts

@@ -0,0 +1,162 @@
+export type SandboxRunnerState = "queued" | "running" | "succeeded" | "failed";
+
+export interface SandboxRunnerStartRequest {
+  companyUid: string;
+  secretNames: string[];
+  command: string;
+}
+
+export interface SandboxRunnerStartResponse {
+  jobId: string;
+  status: SandboxRunnerState;
+}
+
+export interface SandboxRunnerJob {
+  jobId: string;
+  status: SandboxRunnerState;
+  output?: string;
+  exitCode?: number;
+  success?: boolean;
+}
+
+export interface SandboxRunnerClientOptions {
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+}
+
+export interface SandboxRunnerPollOptions {
+  intervalMs?: number;
+  maxPolls?: number;
+}
+
+const DEFAULT_SANDBOX_RUNNER_URL = "https://hqapi.getindigo.ai/sandbox";
+
+function normalizeBaseUrl(baseUrl: string): string {
+  return baseUrl.replace(/\/+$/, "");
+}
+
+function getSandboxRunnerBaseUrl(): string {
+  return normalizeBaseUrl(
+    process.env.HQ_SANDBOX_RUNNER_URL ?? DEFAULT_SANDBOX_RUNNER_URL,
+  );
+}
+
+function isSandboxRunnerState(value: unknown): value is SandboxRunnerState {
+  return value === "queued" || value === "running" || value === "succeeded" || value === "failed";
+}
+
+async function parseJsonResponse(res: Response): Promise<Record<string, unknown>> {
+  return (await res.json().catch(() => ({}))) as Record<string, unknown>;
+}
+
+function requireString(body: Record<string, unknown>, key: string): string {
+  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: Record<string, unknown>,
+  jobIdFallback?: string,
+): SandboxRunnerJob {
+  const status = body.status;
+  if (!isSandboxRunnerState(status)) {
+    throw new Error("Sandbox Runner returned an invalid job status.");
+  }
+  return {
+    jobId:
+      typeof body.jobId === "string" && body.jobId.length > 0
+        ? body.jobId
+        : jobIdFallback ?? requireString(body, "jobId"),
+    status,
+    output: typeof body.output === "string" ? body.output : undefined,
+    exitCode: typeof body.exitCode === "number" ? body.exitCode : undefined,
+    success: typeof body.success === "boolean" ? body.success : undefined,
+  };
+}
+
+function delay(ms: number): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class SandboxRunnerClient {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: SandboxRunnerClientOptions = {}) {
+    this.baseUrl = normalizeBaseUrl(options.baseUrl ?? getSandboxRunnerBaseUrl());
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+
+  async startJob(
+    token: string,
+    request: SandboxRunnerStartRequest,
+  ): Promise<SandboxRunnerStartResponse> {
+    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: string, jobId: string): Promise<SandboxRunnerJob> {
+    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: string,
+    jobId: string,
+    options: SandboxRunnerPollOptions = {},
+  ): Promise<SandboxRunnerJob> {
+    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.`);
+  }
+}