@indigoai-us/hq-cli 5.117.3 → 5.118.1

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [Unreleased]
 
+## [5.118.1] — 2026-09-17
+
+### Fixed
+
+- The locked-workspace notice now names the real reason. A workspace locked
+  because of secrets or agents no longer reads "over its 5-member limit"; each
+  reason gets its own explanation, its own Starter cap and its own fix, and a
+  lock with no recognised reason says only that the workspace is over the
+  Starter limits. The plan-limit warning also names the dimension it is quoting
+  ("users at 9/10 (90%) (members)").
+
+- You can now remove an HQ Agents v2 agent from the CLI without bypassing its
+  safety check. `hq agents rm` accepts `--confirm-destroy-agents-v2
+  <instance-id>` alongside `--yes` and sends only the instance ID you name; HQ
+  still refuses an ID that does not match the live box.
+
+## [5.118.0] — 2026-09-16
+
+### Added
+
+- External agents can now be woken the moment an HQ message arrives. `hq agent kit wake set-url --stdin` points the kit at a webhook, such as a Grok Bot routine webhook trigger. `hq agent kit wake set-command -- <cmd>` runs a local command for frameworks with a CLI. The kit sends a short notice with no message text when mail is pending, and again every 10 minutes until it is handled. The webhook URL is stored privately and never logged.
+- `hq agent inbox` lists an external agent's pending HQ messages and `hq agent inbox done <id>` marks them handled, so a woken bot never answers the same message twice. The MCP server gains a matching `hq_inbox_done` tool.
+
+### Fixed
+
+- The `hq_inbox_read` MCP tool no longer fails with 403 AGENT_ROUTE_NOT_SUPPORTED. It reads the agent's own inbox instead of the person-only DM inbox, and by default returns only messages not yet handled.
+- The HQ direct-message skill shipped to external agents no longer tells them to use person-only read commands.
+
 ## [5.117.3] — 2026-09-16
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -4023,6 +4023,9 @@ export declare const COMMAND_CATALOG: readonly [{
         }, {
             readonly flags: "--yes";
             readonly description: "Confirm the irreversible teardown (required)";
+        }, {
+            readonly flags: "--confirm-destroy-agents-v2 <instance-id>";
+            readonly description: "Confirm agents-v2 teardown by naming the live EC2 instance ID";
         }];
         readonly subcommands: readonly [];
     }, {
@@ -4218,6 +4221,83 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "Print machine-readable JSON";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "wake";
+            readonly description: "Wake this bot's own framework when HQ messages arrive (webhook URL or local command)";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] [command]";
+            readonly arguments: readonly [];
+            readonly options: readonly [];
+            readonly subcommands: readonly [{
+                readonly name: "set-url";
+                readonly description: "POST a notice to a webhook URL (e.g. a Grok Bot routine webhook) when mail is pending. Prefer --stdin so the URL stays out of shell history";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] [url]";
+                readonly arguments: readonly [{
+                    readonly name: "url";
+                    readonly required: false;
+                    readonly variadic: false;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--stdin";
+                    readonly description: "Read the URL from stdin";
+                }, {
+                    readonly flags: "--retry-minutes <n>";
+                    readonly description: "Re-wake while items stay pending (default 10, minimum 1)";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "set-command";
+                readonly description: "Run a local command (no shell) when mail is pending; the notice JSON arrives on stdin. Use -- before the command";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] <argv...>";
+                readonly arguments: readonly [{
+                    readonly name: "argv";
+                    readonly required: true;
+                    readonly variadic: true;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--timeout-minutes <n>";
+                    readonly description: "Kill a run after this long (default 10)";
+                }, {
+                    readonly flags: "--retry-minutes <n>";
+                    readonly description: "Re-wake while items stay pending (default 10, minimum 1)";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "show";
+                readonly description: "Show the configured wake (the URL is masked)";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options]";
+                readonly arguments: readonly [];
+                readonly options: readonly [{
+                    readonly flags: "--json";
+                    readonly description: "Print machine-readable JSON";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "clear";
+                readonly description: "Remove the wake configuration";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options]";
+                readonly arguments: readonly [];
+                readonly options: readonly [];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "test";
+                readonly description: "Fire the wake once now with the current pending count";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options]";
+                readonly arguments: readonly [];
+                readonly options: readonly [];
+                readonly subcommands: readonly [];
+            }];
         }, {
             readonly name: "run";
             readonly description: "Run one kit service in the foreground (sync|mesh|inbox|heartbeat), or `all` to supervise every service in one process";
@@ -4253,6 +4333,34 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly arguments: readonly [];
         readonly options: readonly [];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "inbox";
+        readonly description: "List this agent's pending HQ messages (mirrored by the kit), or mark them handled";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--all";
+            readonly description: "Include items already marked handled";
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print machine-readable JSON";
+        }];
+        readonly subcommands: readonly [{
+            readonly name: "done";
+            readonly description: "Mark inbox items handled and ack them on the server";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <ids...>";
+            readonly arguments: readonly [{
+                readonly name: "ids";
+                readonly required: true;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }];
     }];
 }, {
     readonly name: "outposts";

package/dist/command-catalog.generated.js

@@ -5205,6 +5205,10 @@ export const COMMAND_CATALOG = [
                     {
                         "flags": "--yes",
                         "description": "Confirm the irreversible teardown (required)"
+                    },
+                    {
+                        "flags": "--confirm-destroy-agents-v2 <instance-id>",
+                        "description": "Confirm agents-v2 teardown by naming the live EC2 instance ID"
                     }
                 ],
                 "subcommands": []
@@ -5457,6 +5461,102 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "wake",
+                        "description": "Wake this bot's own framework when HQ messages arrive (webhook URL or local command)",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] [command]",
+                        "arguments": [],
+                        "options": [],
+                        "subcommands": [
+                            {
+                                "name": "set-url",
+                                "description": "POST a notice to a webhook URL (e.g. a Grok Bot routine webhook) when mail is pending. Prefer --stdin so the URL stays out of shell history",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] [url]",
+                                "arguments": [
+                                    {
+                                        "name": "url",
+                                        "required": false,
+                                        "variadic": false
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--stdin",
+                                        "description": "Read the URL from stdin"
+                                    },
+                                    {
+                                        "flags": "--retry-minutes <n>",
+                                        "description": "Re-wake while items stay pending (default 10, minimum 1)"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "set-command",
+                                "description": "Run a local command (no shell) when mail is pending; the notice JSON arrives on stdin. Use -- before the command",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] <argv...>",
+                                "arguments": [
+                                    {
+                                        "name": "argv",
+                                        "required": true,
+                                        "variadic": true
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--timeout-minutes <n>",
+                                        "description": "Kill a run after this long (default 10)"
+                                    },
+                                    {
+                                        "flags": "--retry-minutes <n>",
+                                        "description": "Re-wake while items stay pending (default 10, minimum 1)"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "show",
+                                "description": "Show the configured wake (the URL is masked)",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options]",
+                                "arguments": [],
+                                "options": [
+                                    {
+                                        "flags": "--json",
+                                        "description": "Print machine-readable JSON"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "clear",
+                                "description": "Remove the wake configuration",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options]",
+                                "arguments": [],
+                                "options": [],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "test",
+                                "description": "Fire the wake once now with the current pending count",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options]",
+                                "arguments": [],
+                                "options": [],
+                                "subcommands": []
+                            }
+                        ]
+                    },
                     {
                         "name": "run",
                         "description": "Run one kit service in the foreground (sync|mesh|inbox|heartbeat), or `all` to supervise every service in one process",
@@ -5499,6 +5599,42 @@ export const COMMAND_CATALOG = [
                 "arguments": [],
                 "options": [],
                 "subcommands": []
+            },
+            {
+                "name": "inbox",
+                "description": "List this agent's pending HQ messages (mirrored by the kit), or mark them handled",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--all",
+                        "description": "Include items already marked handled"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON"
+                    }
+                ],
+                "subcommands": [
+                    {
+                        "name": "done",
+                        "description": "Mark inbox items handled and ack them on the server",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <ids...>",
+                        "arguments": [
+                            {
+                                "name": "ids",
+                                "required": true,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    }
+                ]
             }
         ]
     },

package/dist/commands/agent-inbox.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `hq agent inbox` — what a woken bot runs to see and clear its HQ mail.
+ *
+ *   hq agent inbox [--all] [--json]   pending items (oldest first), or all
+ *   hq agent inbox done <id...>       mark handled locally and ack on the server
+ */
+import { Command } from "commander";
+export declare function registerAgentInboxCommand(agent: Command): void;
+//# sourceMappingURL=agent-inbox.d.ts.map

package/dist/commands/agent-inbox.js

@@ -0,0 +1,81 @@
+/**
+ * `hq agent inbox` — what a woken bot runs to see and clear its HQ mail.
+ *
+ *   hq agent inbox [--all] [--json]   pending items (oldest first), or all
+ *   hq agent inbox done <id...>       mark handled locally and ack on the server
+ */
+import chalk from "chalk";
+import * as os from "node:os";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { markInboxDone, readDoneIds, readMirroredInbox, summarizeInboxEntry } from "../lib/agent-kit/inbox-state.js";
+import { agentKitPaths } from "../lib/agent-kit/paths.js";
+import { requireExternalCreds } from "./agent-kit.js";
+const ID_RE = /^[A-Za-z0-9._:-]{1,200}$/;
+export function registerAgentInboxCommand(agent) {
+    const inbox = agent
+        .command("inbox")
+        .description("List this agent's pending HQ messages (mirrored by the kit), or mark them handled")
+        .option("--all", "Include items already marked handled")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => {
+        const paths = agentKitPaths(os.homedir(), process.env);
+        const done = readDoneIds(paths);
+        const rows = readMirroredInbox(paths)
+            .filter((e) => opts.all || !done.has(e.id))
+            .map((e) => summarizeInboxEntry(e, done.has(e.id)));
+        if (opts.json) {
+            console.log(JSON.stringify({ count: rows.length, messages: rows }, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log(opts.all ? "Inbox is empty." : "No pending messages.");
+            return;
+        }
+        for (const r of rows) {
+            const state = r.done ? chalk.dim(" (done)") : "";
+            console.log(`${chalk.bold(r.id)}${state}  ${r.channel ?? "?"}  from ${r.from}${r.fromUid ? ` <${r.fromUid}>` : ""}  ${r.at ?? ""}`);
+            if (r.text)
+                console.log(`  ${r.text.replace(/\n/g, "\n  ")}`);
+        }
+        if (!opts.all)
+            console.log(chalk.dim(`\nReply with hq dm <uid> "…", then: hq agent inbox done <id>`));
+    });
+    inbox
+        .command("done <ids...>")
+        .description("Mark inbox items handled and ack them on the server")
+        .action(async (ids) => {
+        const bad = ids.filter((id) => !ID_RE.test(id));
+        if (bad.length) {
+            console.error(chalk.red(`Invalid id(s): ${bad.join(", ")}`));
+            process.exit(1);
+        }
+        const paths = agentKitPaths(os.homedir(), process.env);
+        const creds = requireExternalCreds(paths);
+        const added = markInboxDone(paths, ids);
+        process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
+        process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
+        process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
+        let acked = 0;
+        try {
+            const token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
+            for (const id of ids) {
+                const res = await vaultApiFetch({
+                    token,
+                    baseUrl: creds.apiBaseUrl,
+                    path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox/${encodeURIComponent(id)}/ack`,
+                    method: "POST",
+                });
+                if (res.ok)
+                    acked += 1;
+                else
+                    console.error(chalk.yellow(`server ack ${id} → ${res.status}`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.yellow(`server ack skipped: ${err instanceof Error ? err.message : String(err)}`));
+        }
+        console.log(`Marked ${added.length} handled (${ids.length - added.length} already done); server acked ${acked}.`);
+    });
+}
+//# sourceMappingURL=agent-inbox.js.map

package/dist/commands/agent-kit.js

@@ -34,6 +34,8 @@ import { fallbackStatus, rebootCrontabLine, shouldUseFallback, startFallback, st
 import { serviceLogPath } from "../lib/agent-kit/paths.js";
 import { spawn } from "node:child_process";
 import { startMeshListener } from "../lib/agent-kit/run/mesh-listener.js";
+import { pendingInbox } from "../lib/agent-kit/inbox-state.js";
+import { buildWakeNotice, clearWakeConfig, currentWakeState, DEFAULT_WAKE_RETRY_MS, describeWake, fireWake, readWakeConfig, validateWakeUrl, writeWakeConfig, } from "../lib/agent-kit/wake.js";
 import { runSyncLoop } from "../lib/agent-kit/run/sync.js";
 import { resolveHqBinary, resolveNodeBinary, } from "../lib/mesh/live/daemon/install.js";
 import { installServices, servicesStatus, uninstallServices, } from "../lib/service-manager/index.js";
@@ -245,6 +247,14 @@ export function formatFallbackStatus(paths, kill) {
         : chalk.yellow(st.pid === null ? "pidfile unreadable" : `not running (stale pid ${st.pid})`);
     return [`  mode: fallback supervisor (hq agent kit run all) ${state}${chalk.dim(`  ${st.pidFile}`)}`];
 }
+function retryMsFrom(raw) {
+    if (raw === undefined)
+        return DEFAULT_WAKE_RETRY_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1)
+        throw new Error("--retry-minutes must be at least 1");
+    return n * 60_000;
+}
 function fail(err) {
     console.error(chalk.red(err instanceof Error ? err.message : String(err)));
     process.exit(1);
@@ -341,6 +351,101 @@ export function registerAgentKitCommand(agent) {
             fail(err);
         }
     });
+    const wake = kit
+        .command("wake")
+        .description("Wake this bot's own framework when HQ messages arrive (webhook URL or local command)");
+    wake
+        .command("set-url [url]")
+        .description("POST a notice to a webhook URL (e.g. a Grok Bot routine webhook) when mail is pending. Prefer --stdin so the URL stays out of shell history")
+        .option("--stdin", "Read the URL from stdin")
+        .option("--retry-minutes <n>", "Re-wake while items stay pending (default 10, minimum 1)")
+        .action(async (url, opts) => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            requireExternalCreds(paths);
+            let raw = url;
+            if (opts.stdin) {
+                const chunks = [];
+                for await (const c of process.stdin)
+                    chunks.push(c);
+                raw = Buffer.concat(chunks).toString("utf8").trim();
+            }
+            if (!raw)
+                throw new Error("Provide the URL as an argument or with --stdin");
+            const config = { kind: "url", url: validateWakeUrl(raw), retryMs: retryMsFrom(opts.retryMinutes) };
+            writeWakeConfig(paths, config);
+            console.log(chalk.green(`Wake set: ${describeWake(config)}`));
+            console.log("Test it: hq agent kit wake test");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    wake
+        .command("set-command <argv...>")
+        .description("Run a local command (no shell) when mail is pending; the notice JSON arrives on stdin. Use -- before the command")
+        .option("--timeout-minutes <n>", "Kill a run after this long (default 10)")
+        .option("--retry-minutes <n>", "Re-wake while items stay pending (default 10, minimum 1)")
+        .action((argv, opts) => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            requireExternalCreds(paths);
+            const minutes = opts.timeoutMinutes ? Number(opts.timeoutMinutes) : 10;
+            if (!Number.isFinite(minutes) || minutes <= 0)
+                throw new Error("--timeout-minutes must be a positive number");
+            const config = { kind: "command", command: argv, timeoutMs: minutes * 60_000, retryMs: retryMsFrom(opts.retryMinutes) };
+            writeWakeConfig(paths, config);
+            console.log(chalk.green(`Wake set: ${describeWake(config)}`));
+            console.log("Test it: hq agent kit wake test");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    wake
+        .command("show")
+        .description("Show the configured wake (the URL is masked)")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => {
+        const paths = agentKitPaths(os.homedir(), process.env);
+        const config = readWakeConfig(paths);
+        const state = currentWakeState(paths);
+        if (opts.json) {
+            console.log(JSON.stringify({ configured: !!config, wake: describeWake(config), lastWakeAt: state.lastWakeAt ?? null }, null, 2));
+            return;
+        }
+        console.log(`  wake:      ${describeWake(config)}`);
+        console.log(`  last wake: ${state.lastWakeAt ?? "never"}`);
+    });
+    wake
+        .command("clear")
+        .description("Remove the wake configuration")
+        .action(() => {
+        const paths = agentKitPaths(os.homedir(), process.env);
+        console.log(clearWakeConfig(paths) ? "Wake cleared." : "No wake was configured.");
+    });
+    wake
+        .command("test")
+        .description("Fire the wake once now with the current pending count")
+        .action(async () => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            const creds = requireExternalCreds(paths);
+            ensureKitDirs(paths);
+            const config = readWakeConfig(paths);
+            if (!config)
+                throw new Error("No wake configured. Run hq agent kit wake set-url --stdin (or set-command).");
+            const log = createKitLogger(paths, "wake", { echo: false });
+            const ids = pendingInbox(paths).map((e) => e.id);
+            const result = await fireWake(config, buildWakeNotice(creds.entityUid, "test", ids, new Date()), { paths, agentUid: creds.entityUid, log });
+            console.log(result.ok ? chalk.green(result.detail) : chalk.red(result.detail));
+            if (!result.ok)
+                process.exit(1);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     kit
         .command("run <service>")
         .description(`Run one kit service in the foreground (${KIT_SERVICES.join("|")}), or \`all\` to supervise every service in one process`)

package/dist/commands/agent-mcp.d.ts

@@ -11,12 +11,13 @@
 import { Command } from "commander";
 import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
 import { type HqRunResult, type McpToolClients } from "../lib/agent-kit/mcp/tools.js";
+import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
 import type { ExternalMachineCreds } from "../lib/agent-kit/creds.js";
 export declare const AGENT_MCP_SERVER_NAME = "hq-agent";
 export declare const AGENT_MCP_INSTRUCTIONS: string;
 export declare const HQ_SUBPROCESS_TIMEOUT_MS = 120000;
 export declare function defaultRunHq(nodeBinary: string, hqBinary: string, env: NodeJS.ProcessEnv): (args: string[]) => Promise<HqRunResult>;
-export declare function defaultMcpClients(creds: ExternalMachineCreds, credsPath: string): McpToolClients;
+export declare function defaultMcpClients(creds: ExternalMachineCreds, credsPath: string, paths?: Pick<AgentKitPaths, "inboxDir">): McpToolClients;
 export declare function createAgentMcpServer(clients: McpToolClients): McpServer;
 export declare function registerAgentMcpCommand(agent: Command): void;
 //# sourceMappingURL=agent-mcp.d.ts.map

package/dist/commands/agent-mcp.js

@@ -21,7 +21,7 @@ export const AGENT_MCP_SERVER_NAME = "hq-agent";
 export const AGENT_MCP_INSTRUCTIONS = "You are acting inside HQ as an enrolled external agent. Tools run as that machine identity: " +
     "hq_whoami (identity), hq_search / hq_files_list / hq_files_read (company vault), " +
     "hq_secrets_list / hq_secrets_exec (secrets by NAME only — values are never returned), " +
-    "hq_dm_send / hq_inbox_read (direct messages), hq_work_mesh_status (what the team is doing). " +
+    "hq_inbox_read / hq_dm_send / hq_inbox_done (read pending HQ messages, reply, then mark each handled), hq_work_mesh_status (what the team is doing). " +
     "Never ask a user for a token or secret value; if a secret is missing, name it and ask an admin to add it.";
 export const HQ_SUBPROCESS_TIMEOUT_MS = 120_000;
 export function defaultRunHq(nodeBinary, hqBinary, env) {
@@ -45,7 +45,7 @@ export function defaultRunHq(nodeBinary, hqBinary, env) {
         });
     });
 }
-export function defaultMcpClients(creds, credsPath) {
+export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.homedir(), process.env)) {
     const env = {
         ...process.env,
         HQ_MACHINE_CREDS_FILE: credsPath,
@@ -55,6 +55,7 @@ export function defaultMcpClients(creds, credsPath) {
     };
     return {
         creds,
+        paths,
         runHq: defaultRunHq(process.execPath, process.argv[1], env),
         getToken: () => ensureCognitoToken({ tokenSource: "machine", interactive: false }),
         apiJson: async (token, path, init) => {
@@ -96,7 +97,7 @@ export function registerAgentMcpCommand(agent) {
         process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
         process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
         process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
-        const server = createAgentMcpServer(defaultMcpClients(creds, paths.machineCredsPath));
+        const server = createAgentMcpServer(defaultMcpClients(creds, paths.machineCredsPath, paths));
         process.stderr.write(`hq agent mcp: serving as ${creds.entityUid} (${creds.companySlug})\n`);
         await server.serve(process.stdin, process.stdout);
     });

package/dist/commands/agent.d.ts

@@ -6,6 +6,7 @@
  *   hq agent kit install|status|uninstall|run <service>
  *   hq agent probe                end-to-end membership check
  *   hq agent mcp                  stdio MCP server for the bot framework
+ *   hq agent inbox [done <id…>]   pending HQ messages / mark handled
  */
 import { Command } from "commander";
 export declare function registerAgentCommand(program: Command): void;

package/dist/commands/agent.js

@@ -6,8 +6,10 @@
  *   hq agent kit install|status|uninstall|run <service>
  *   hq agent probe                end-to-end membership check
  *   hq agent mcp                  stdio MCP server for the bot framework
+ *   hq agent inbox [done <id…>]   pending HQ messages / mark handled
  */
 import { registerAgentEnrollCommand } from "./agent-enroll.js";
+import { registerAgentInboxCommand } from "./agent-inbox.js";
 import { registerAgentKitCommand } from "./agent-kit.js";
 import { registerAgentMcpCommand } from "./agent-mcp.js";
 import { registerAgentProbeCommand } from "./agent-probe.js";
@@ -19,5 +21,6 @@ export function registerAgentCommand(program) {
     registerAgentKitCommand(agent);
     registerAgentProbeCommand(agent);
     registerAgentMcpCommand(agent);
+    registerAgentInboxCommand(agent);
 }
 //# sourceMappingURL=agent.js.map

package/dist/commands/agents.d.ts

@@ -258,7 +258,7 @@ export type AgentTerminalResponse = ({
 };
 export declare function openAgentTerminal(token: string, agentUid: string, body: Record<string, unknown>): Promise<AgentTerminalResponse>;
 export declare function retryAgent(token: string, agentUid: string): Promise<Record<string, unknown>>;
-export declare function deprovisionAgent(token: string, agentUid: string): Promise<{
+export declare function deprovisionAgent(token: string, agentUid: string, confirmDestroyAgentsV2?: string): Promise<{
     uid: string;
     setupState?: string;
     terminal?: boolean;

package/dist/commands/agents.js

@@ -564,11 +564,14 @@ export async function retryAgent(token, agentUid) {
         method: "POST",
     });
 }
-export async function deprovisionAgent(token, agentUid) {
+export async function deprovisionAgent(token, agentUid, confirmDestroyAgentsV2) {
     return agentsRequest({
         token,
         path: `/v1/agents/${encodeURIComponent(agentUid)}`,
         method: "DELETE",
+        body: confirmDestroyAgentsV2 === undefined
+            ? undefined
+            : { confirmDestroyAgentsV2 },
     });
 }
 export async function listAgentJobs(token, agentUid) {
@@ -1477,6 +1480,7 @@ export function registerAgentsCommand(program) {
         .description("Deprovision (permanently tear down) an agent")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--yes", "Confirm the irreversible teardown (required)")
+        .option("--confirm-destroy-agents-v2 <instance-id>", "Confirm agents-v2 teardown by naming the live EC2 instance ID")
         .action(async function (agentUid, opts) {
         if (!opts.yes) {
             console.error(chalk.yellow(`This will permanently deprovision agent ${agentUid} and tear down its ` +
@@ -1486,7 +1490,7 @@ export function registerAgentsCommand(program) {
         }
         try {
             const token = (await resolveVaultCredential()).token;
-            const result = await deprovisionAgent(token, agentUid);
+            const result = await deprovisionAgent(token, agentUid, opts.confirmDestroyAgentsV2);
             if (result.terminal === false) {
                 console.log(chalk.yellow(`Deprovision in progress for agent ${agentUid} (not yet fully torn down — re-run to continue).`));
             }