@indigoai-us/hq-cli 5.115.6 → 5.116.0

package/CHANGELOG.md

@@ -2,20 +2,66 @@
 
 ## [Unreleased]
 
-## [5.115.6] — 2026-09-16
+## [5.116.0] — 2026-09-16
+
+### Added
+
+- External bots as team members (host side). `hq agent enroll <code>`
+  redeems a one-time enrollment code from the console: it generates an
+  Ed25519 host key at `~/.hq-agent/host-key` (0600), POSTs the public half to
+  `POST /v1/agents/enroll`, and writes `~/.hq-agent/machine-creds.json` (0600)
+  with `runtime: "external"`. It refuses to run on a host that already holds a
+  human session file or another machine identity unless `--replace`, and
+  never reads `~/.hq/cognito-tokens.json`. Every contract error (expired,
+  already redeemed, invalid, revoked, plan-gated, throttled, unreachable) maps
+  to a message that names the fix.
+- `hq agent kit install|status|uninstall|run <service>`: user-level services
+  (LaunchAgent on macOS, systemd `--user` on Linux) for the company-vault sync
+  loop, a work-mesh doorbell listener (ids-only MQTT → REST refetch into
+  `~/.hq/work-mesh/cache`), an inbox poller that mirrors new items to
+  `~/.hq-agent/inbox/` (server ack opt-in via `--inbox-ack`), and a 60 s
+  heartbeat posting `{ components: { sync, mesh, inbox } }`. Each unit just
+  runs `hq agent kit run <service>`; logs land in `~/.hq-agent/logs/`. The
+  install also ships `~/.hq-agent/skills/{dm,search,files,secrets-exec,work-mesh-status}/SKILL.md`
+  (agentskills.io format). `docker/hq-agent-kit/` runs the same four
+  processes from a mounted creds volume.
+- `hq agent probe`: whoami → vault sync → mesh presence → DM round trip to
+  self → secrets list, one PASS/FAIL line each, non-zero exit on any failure,
+  a final `heartbeat  <age>` line (the recipe format), and the result POSTed to
+  `POST /v1/agents/{uid}/probe-result` so the console flips to Enrolled.
+- `hq agent mcp`: a stdio MCP server (no SDK dependency; initialize / ping /
+  tools/list / tools/call) backed by the enrolled machine identity, exposing
+  `hq_whoami`, `hq_search`, `hq_files_list`, `hq_files_read`,
+  `hq_secrets_list`, `hq_secrets_exec` (exit code + output only, never
+  values), `hq_dm_send`, `hq_inbox_read`, `hq_work_mesh_status`. Console
+  recipes register it as `command: hq, args: [agent, mcp]`.
+- `hq agents rotate <uid>` (fresh enrollment code, shown once) and
+  `hq agents revoke <uid> [--remove] --yes` for external agents. Both fail
+  closed under `HQ_API_KEY` (JWT-only routes).
+
+### Changed
+
+- `@indigoai-us/hq-cloud` pinned to `~6.16.48`, whose machine mint signs the
+  server's nonce with the host key when creds carry `runtime: "external"`.
 
 ### Fixed
 
-- `hq doctor --fix` can now refresh a company sync journal that is stale or
-  has never synced, when that company still has a folder under `companies/`.
-  It pulls that company only, keeps your local copy if there is a conflict,
-  and does not push. Company journals left over from memberships you do not
-  keep locally are reported as unused rather than broken, so a session-start
-  health check no longer files "could not repair" reports for folders that
-  were never on this machine. Personal journals are unchanged: they still
-  warn when stale, and `--fix` will not pull your personal vault on its own.
-  The repair pass also skips the integrations inventory, which it cannot
-  repair, so a slow connection check cannot stall the fix.
+- When a new agent needs an owner action, `hq agents provision` prints the
+  current Codex sign-in code or a link to finish setting up the Slack app. `hq agents status
+  <slug>` gets the current action again. The `--json` output adds a
+  `pendingActions` array, plus `slackInstallPending` and `slackInstallUrl` for
+  Slack installs.
+
+- `hq secrets` now fails promptly instead of waiting for a browser sign-in
+  that cannot be completed when stdin or stderr is not a terminal, or in CI.
+  Run `hq login` from an interactive shell first if no valid session exists.
+
+- hq gives both visible and quiet version-gated updates 30 minutes to finish.
+  When that limit expires, it tries to terminate the updater's process group
+  on POSIX or process tree on Windows. If the operating system denies that
+  request, hq reports it instead of waiting forever. Set `HQ_UPDATE_TIMEOUT_MS`
+  to another whole number of milliseconds up to 2,147,483,647. hq ignores an
+  invalid value and tells you it is using the 30-minute limit.
 
 - HQ's housekeeping pass now clears out add-on shortcuts that lead nowhere,
   instead of warning about them forever. A pack that stops shipping one of its
@@ -37,6 +83,21 @@
   that leads to real content. Repairing a tree this way fixed a batch of
   long-broken pack shortcuts in one pass.
 
+## [5.115.6] — 2026-09-16
+
+### Fixed
+
+- `hq doctor --fix` can now refresh a company sync journal that is stale or
+  has never synced, when that company still has a folder under `companies/`.
+  It pulls that company only, keeps your local copy if there is a conflict,
+  and does not push. Company journals left over from memberships you do not
+  keep locally are reported as unused rather than broken, so a session-start
+  health check no longer files "could not repair" reports for folders that
+  were never on this machine. Personal journals are unchanged: they still
+  warn when stale, and `--fix` will not pull your personal vault on its own.
+  The repair pass also skips the integrations inventory, which it cannot
+  repair, so a slow connection check cannot stall the fix.
+
 ## [5.115.5] — 2026-09-15
 
 ### Fixed

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

@@ -3853,9 +3853,9 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly description: "Show an agent's setup state and runtime detail";
         readonly aliases: readonly [];
         readonly hidden: false;
-        readonly usage: "[options] <agentUid>";
+        readonly usage: "[options] <agent>";
         readonly arguments: readonly [{
-            readonly name: "agentUid";
+            readonly name: "agent";
             readonly required: true;
             readonly variadic: false;
         }];
@@ -4022,6 +4022,47 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Confirm the irreversible teardown (required)";
         }];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "rotate";
+        readonly description: "Issue a fresh enrollment code for an external agent (old secret + host key stop minting)";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] <agentUid>";
+        readonly arguments: readonly [{
+            readonly name: "agentUid";
+            readonly required: true;
+            readonly variadic: false;
+        }];
+        readonly options: readonly [{
+            readonly flags: "--company <slug>";
+            readonly description: "Company slug (resolves to companyUid)";
+        }, {
+            readonly flags: "--json";
+            readonly description: "Emit raw JSON (code included — pipe carefully)";
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "revoke";
+        readonly description: "Revoke an external agent: disable its login and drop it from the team";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] <agentUid>";
+        readonly arguments: readonly [{
+            readonly name: "agentUid";
+            readonly required: true;
+            readonly variadic: false;
+        }];
+        readonly options: readonly [{
+            readonly flags: "--company <slug>";
+            readonly description: "Company slug (resolves to companyUid)";
+        }, {
+            readonly flags: "--remove";
+            readonly description: "Also delete the agent entity (it disappears from the roster)";
+        }, {
+            readonly flags: "--yes";
+            readonly description: "Confirm the revoke (required)";
+        }];
+        readonly subcommands: readonly [];
     }, {
         readonly name: "jobs";
         readonly description: "List, pause, or cancel an agent's scheduled jobs";
@@ -4091,6 +4132,125 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly subcommands: readonly [];
         }];
     }];
+}, {
+    readonly name: "agent";
+    readonly description: "Enroll and run this host as an external HQ agent";
+    readonly aliases: readonly [];
+    readonly hidden: false;
+    readonly usage: "[options] [command]";
+    readonly arguments: readonly [];
+    readonly options: readonly [];
+    readonly subcommands: readonly [{
+        readonly name: "enroll";
+        readonly description: "Enroll this host as an external HQ agent using a one-time code";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] <code>";
+        readonly arguments: readonly [{
+            readonly name: "code";
+            readonly required: true;
+            readonly variadic: false;
+        }];
+        readonly options: readonly [{
+            readonly flags: "--company <slug>";
+            readonly description: "Expected company slug (warns when the code belongs elsewhere)";
+        }, {
+            readonly flags: "--replace";
+            readonly description: "Overwrite an existing machine identity on this host";
+        }, {
+            readonly flags: "--api-base-url <url>";
+            readonly description: "hq-pro control plane (default: HQ_VAULT_API_URL or production)";
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "kit";
+        readonly description: "Install, inspect, or run the external-agent background services";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [{
+            readonly name: "install";
+            readonly description: "Install sync, work-mesh, inbox and heartbeat services plus the skills directory";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options]";
+            readonly arguments: readonly [];
+            readonly options: readonly [{
+                readonly flags: "--hq-root <path>";
+                readonly description: "Local HQ tree to sync the company vault into (default: ~/.hq-agent/hq)";
+            }, {
+                readonly flags: "--inbox-ack";
+                readonly description: "Ack mirrored inbox items on the server (default: leave acking to the bot)";
+            }, {
+                readonly flags: "--no-activate";
+                readonly description: "Write unit files but do not load them";
+            }, {
+                readonly flags: "--json";
+                readonly description: "Print machine-readable JSON";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "status";
+            readonly description: "Show whether each kit service is installed and running";
+            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: "uninstall";
+            readonly description: "Stop and remove the kit services (credentials and skills are kept)";
+            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: "run";
+            readonly description: "Run one kit service in the foreground (sync|mesh|inbox|heartbeat)";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <service>";
+            readonly arguments: readonly [{
+                readonly name: "service";
+                readonly required: true;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }];
+    }, {
+        readonly name: "probe";
+        readonly description: "Verify identity, vault sync, work-mesh presence, DMs and secrets; report to the console";
+        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: "mcp";
+        readonly description: "Serve HQ as a stdio MCP server for the bot framework (whoami, search, files, secrets-exec, dm, inbox, work-mesh)";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [];
+    }];
 }, {
     readonly name: "outposts";
     readonly description: "Manage your personal HQ Outposts (EC2 boxes)";

package/dist/command-catalog.generated.js

@@ -4979,10 +4979,10 @@ export const COMMAND_CATALOG = [
                 "description": "Show an agent's setup state and runtime detail",
                 "aliases": [],
                 "hidden": false,
-                "usage": "[options] <agentUid>",
+                "usage": "[options] <agent>",
                 "arguments": [
                     {
-                        "name": "agentUid",
+                        "name": "agent",
                         "required": true,
                         "variadic": false
                     }
@@ -5205,6 +5205,60 @@ export const COMMAND_CATALOG = [
                 ],
                 "subcommands": []
             },
+            {
+                "name": "rotate",
+                "description": "Issue a fresh enrollment code for an external agent (old secret + host key stop minting)",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] <agentUid>",
+                "arguments": [
+                    {
+                        "name": "agentUid",
+                        "required": true,
+                        "variadic": false
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Company slug (resolves to companyUid)"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Emit raw JSON (code included — pipe carefully)"
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "revoke",
+                "description": "Revoke an external agent: disable its login and drop it from the team",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] <agentUid>",
+                "arguments": [
+                    {
+                        "name": "agentUid",
+                        "required": true,
+                        "variadic": false
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Company slug (resolves to companyUid)"
+                    },
+                    {
+                        "flags": "--remove",
+                        "description": "Also delete the agent entity (it disappears from the roster)"
+                    },
+                    {
+                        "flags": "--yes",
+                        "description": "Confirm the revoke (required)"
+                    }
+                ],
+                "subcommands": []
+            },
             {
                 "name": "jobs",
                 "description": "List, pause, or cancel an agent's scheduled jobs",
@@ -5295,6 +5349,155 @@ export const COMMAND_CATALOG = [
             }
         ]
     },
+    {
+        "name": "agent",
+        "description": "Enroll and run this host as an external HQ agent",
+        "aliases": [],
+        "hidden": false,
+        "usage": "[options] [command]",
+        "arguments": [],
+        "options": [],
+        "subcommands": [
+            {
+                "name": "enroll",
+                "description": "Enroll this host as an external HQ agent using a one-time code",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] <code>",
+                "arguments": [
+                    {
+                        "name": "code",
+                        "required": true,
+                        "variadic": false
+                    }
+                ],
+                "options": [
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Expected company slug (warns when the code belongs elsewhere)"
+                    },
+                    {
+                        "flags": "--replace",
+                        "description": "Overwrite an existing machine identity on this host"
+                    },
+                    {
+                        "flags": "--api-base-url <url>",
+                        "description": "hq-pro control plane (default: HQ_VAULT_API_URL or production)"
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "kit",
+                "description": "Install, inspect, or run the external-agent background services",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "install",
+                        "description": "Install sync, work-mesh, inbox and heartbeat services plus the skills directory",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--hq-root <path>",
+                                "description": "Local HQ tree to sync the company vault into (default: ~/.hq-agent/hq)"
+                            },
+                            {
+                                "flags": "--inbox-ack",
+                                "description": "Ack mirrored inbox items on the server (default: leave acking to the bot)"
+                            },
+                            {
+                                "flags": "--no-activate",
+                                "description": "Write unit files but do not load them"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "status",
+                        "description": "Show whether each kit service is installed and running",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "uninstall",
+                        "description": "Stop and remove the kit services (credentials and skills are kept)",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options]",
+                        "arguments": [],
+                        "options": [
+                            {
+                                "flags": "--json",
+                                "description": "Print machine-readable JSON"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "run",
+                        "description": "Run one kit service in the foreground (sync|mesh|inbox|heartbeat)",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <service>",
+                        "arguments": [
+                            {
+                                "name": "service",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    }
+                ]
+            },
+            {
+                "name": "probe",
+                "description": "Verify identity, vault sync, work-mesh presence, DMs and secrets; report to the console",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON"
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "mcp",
+                "description": "Serve HQ as a stdio MCP server for the bot framework (whoami, search, files, secrets-exec, dm, inbox, work-mesh)",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [],
+                "subcommands": []
+            }
+        ]
+    },
     {
         "name": "outposts",
         "description": "Manage your personal HQ Outposts (EC2 boxes)",

package/dist/command-registration-plan.d.ts

@@ -340,6 +340,12 @@ export declare const REGISTRATION_PLAN: readonly [{
     readonly parent: "program";
     readonly module: "./commands/agents.js";
     readonly exportName: "registerAgentsCommand";
+}, {
+    readonly type: "registrar";
+    readonly root: "agent";
+    readonly parent: "program";
+    readonly module: "./commands/agent.js";
+    readonly exportName: "registerAgentCommand";
 }, {
     readonly type: "registrar";
     readonly root: "outposts";

package/dist/command-registration-plan.js

@@ -59,6 +59,7 @@ export const REGISTRATION_PLAN = [
     { type: "registrar", root: "crm", parent: "program", module: "./commands/crm.js", exportName: "registerCrmCommand" },
     { type: "registrar", root: "company", parent: "program", module: "./commands/company.js", exportName: "registerCompanyCommand" },
     { type: "registrar", root: "agents", parent: "program", module: "./commands/agents.js", exportName: "registerAgentsCommand" },
+    { type: "registrar", root: "agent", parent: "program", module: "./commands/agent.js", exportName: "registerAgentCommand" },
     { type: "registrar", root: "outposts", parent: "program", module: "./commands/outposts.js", exportName: "registerOutpostsCommand" },
     { type: "registrar", root: "billing", parent: "program", module: "./commands/billing.js", exportName: "registerBillingCommand" },
     { type: "registrar", root: "core", parent: "program", module: "./commands/core.js", exportName: "registerCoreCommands" },

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

@@ -0,0 +1,105 @@
+/**
+ * `hq agent enroll <code>` — turn this host into an external HQ agent.
+ *
+ * Flow (api-contract v1, POST /v1/agents/enroll):
+ *   1. refuse if this host already carries an identity (human session file or
+ *      a machine-creds file) unless --replace
+ *   2. generate an Ed25519 key pair at ~/.hq-agent/host-key{,.pub} (0600)
+ *   3. POST { code, hostPublicKey, hostInfo } — unauthenticated, one-shot
+ *   4. write ~/.hq-agent/machine-creds.json (0600) with runtime "external",
+ *      hostKeyPath, companySlug and apiBaseUrl
+ *
+ * The code is single-use and expires 15 minutes after an admin creates it,
+ * so every failure names the fix. The human session file is only checked
+ * for EXISTENCE — its contents are never read (policy
+ * never-extract-stored-session-tokens-to-forge-privileged-calls).
+ */
+import { Command } from "commander";
+import { generateHostKeyPair } from "../lib/agent-kit/creds.js";
+import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
+export declare const ENROLL_PATH = "/v1/agents/enroll";
+/** Canonical code: un-grouped, uppercase (server hashes exactly this). */
+export declare function normalizeEnrollmentCode(raw: string): string;
+/** 24 chars of Crockford base32 (no I, L, O, U). */
+export declare function isWellFormedEnrollmentCode(code: string): boolean;
+export interface HostInfo {
+    os: string;
+    arch: string;
+    hostname: string;
+    cliVersion: string;
+}
+export declare function collectHostInfo(): HostInfo;
+export type ExistingIdentity = {
+    kind: "none";
+} | {
+    kind: "human";
+    file: string;
+} | {
+    kind: "machine";
+    file: string;
+    agentUid?: string;
+};
+/**
+ * What identity already lives on this host. Existence checks only: the
+ * human token file is never opened.
+ */
+export declare function detectExistingIdentity(paths: Pick<AgentKitPaths, "machineCredsPath" | "home">, env?: NodeJS.ProcessEnv): ExistingIdentity;
+export declare function refusalMessage(existing: ExistingIdentity): string | null;
+export declare class EnrollError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined);
+}
+/** Map a non-2xx enroll response to an actionable message (contract codes). */
+export declare function mapEnrollFailure(status: number, body: {
+    code?: unknown;
+    error?: unknown;
+    message?: unknown;
+    attemptsRemaining?: unknown;
+}, headers?: {
+    retryAfter?: string | null;
+}): EnrollError;
+export declare function mapEnrollTransportError(err: unknown, apiBaseUrl: string): EnrollError;
+export interface EnrollResponse {
+    agentUid: string;
+    companyUid: string;
+    companySlug: string;
+    credentials: {
+        username: string;
+        secret: string;
+        userPoolId?: string;
+        clientId: string;
+        region: string;
+        entityType: "agent";
+        entityUid: string;
+        runtime: "external";
+    };
+    hostFingerprint: string;
+}
+export interface EnrollDeps {
+    fetch?: typeof fetch;
+    paths?: AgentKitPaths;
+    env?: NodeJS.ProcessEnv;
+    hostInfo?: HostInfo;
+    generateKeyPair?: typeof generateHostKeyPair;
+}
+export interface EnrollOptions {
+    code: string;
+    company?: string;
+    replace?: boolean;
+    apiBaseUrl?: string;
+}
+export interface EnrollResult {
+    agentUid: string;
+    companySlug: string;
+    companyUid: string;
+    hostFingerprint: string;
+    credsPath: string;
+    hostKeyPath: string;
+    /** Set when --company disagreed with the server's company. */
+    companyMismatch?: string;
+}
+/** Pure-ish orchestration so tests can drive it without a TTY or network. */
+export declare function enrollHost(opts: EnrollOptions, deps?: EnrollDeps): Promise<EnrollResult>;
+export declare function registerAgentEnrollCommand(agent: Command): void;
+//# sourceMappingURL=agent-enroll.d.ts.map