@indigoai-us/hq-cli 5.249.1 → 5.250.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 ## [Unreleased]
 
+## [5.250.0] — 2026-09-27
+
+### Fixed
+
+- An enrolled agent that sets `HQ_AGENT_DIR` now acts as that agent in every
+  command, not only under `hq agent`. `hq dm` and `hq secrets` used to look
+  for a person's session instead, find none, and open a browser sign-in. On
+  the Runneth pilot that hung the first reply for four minutes. Only the
+  explicit variable counts, so a bot living beside its owner on the owner's
+  computer never takes over the owner's commands.
+- On an agent host (Linux, no terminal, no display), a missing session now
+  fails at once with the fix instead of opening a browser sign-in that
+  nobody can complete.
+- `hq agent enroll --name` no longer overrides `HQ_AGENT_DIR`. A bot that
+  pointed its identity at persistent storage had it written under `$HOME`
+  instead, where a rebuild erases it, with a message claiming a person was
+  signed in when nobody was.
+- `wake.log` no longer records the wake command's standard output. A wake
+  command's normal output (a routine record, an echoed prompt) is not
+  diagnostic, and on a share without permissions the log is readable by
+  anything with access to the share. Errors are still logged.
+- Bots now reply in the group or channel a message came from. Their inbox
+  shows the channel id, `hq dm <channelId>` and the `hq_dm_send` tool post by
+  that id (including unnamed group DMs), and the wake and inbox instructions
+  say to answer there. Before, a bot answered a group message with a private
+  DM to the sender, so the group never heard back. The instructions also tell
+  bots not to answer another bot's greetings or sign-offs, so two bots stop
+  acknowledging each other in a loop.
+- An agent whose identity files were moved or copied no longer goes silent an
+  hour later. The credentials file records where the host key lives; when that
+  path is gone and the key sits beside the credentials file, the CLI now points
+  at it before running any agent command. `hq agent probe` also fails when the
+  host key is missing, instead of passing on a cached token and leaving the
+  agent to fail at its next refresh.
+
+
 ## [5.249.1] — 2026-09-27
 
 ## [5.249.0] — 2026-09-27

package/dist/commands/agent-enroll.js

@@ -204,14 +204,18 @@ function parseEnrollResponse(raw) {
  */
 export function resolveEnrollTarget(opts, env = process.env, home = os.homedir()) {
     const pinned = Boolean(env.HQ_AGENT_DIR?.trim() || env.HQ_MACHINE_CREDS_FILE?.trim());
+    // A pinned tree is the environment's explicit choice and wins over --name:
+    // a bot that set HQ_AGENT_DIR to its persistent storage must never be
+    // redirected to a directory under $HOME, which may be erased on rebuild.
+    if (pinned)
+        return { paths: agentKitPaths(home, env), local: false };
     if (opts.name) {
         const dir = localAgentDir(validateLocalAgentName(opts.name), home);
         return { paths: agentKitPaths(home, { ...env, HQ_AGENT_DIR: dir }), local: true };
     }
     const base = agentKitPaths(home, env);
-    // A pinned tree is the caller's explicit choice; --replace is an explicit
-    // choice too. Neither gets silently redirected.
-    if (pinned || opts.replace)
+    // --replace is an explicit choice too; it is not silently redirected.
+    if (opts.replace)
         return { paths: base, local: false };
     if (detectExistingIdentity(base, env).kind !== "human") {
         return { paths: base, local: false };

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

@@ -54,6 +54,8 @@ export interface ProbeDeps {
     listSecrets: (token: string, companyUid: string) => Promise<number>;
     postResult: (token: string, result: ProbeResult) => Promise<number>;
     now?: () => Date;
+    /** Test seam; defaults to fs.existsSync. */
+    hostKeyExists?: (p: string) => boolean;
     sleep?: (ms: number) => Promise<void>;
     nonce?: () => string;
     dmTimeoutMs?: number;

package/dist/commands/agent-probe.js

@@ -63,7 +63,17 @@ export async function runProbe(deps) {
         const claims = peekIdToken(token);
         const uid = claims["custom:entityUid"];
         const type = claims["custom:entityType"];
-        if (type === "agent" && uid === self) {
+        if (type === "agent" && uid === self && !(deps.hostKeyExists ?? fs.existsSync)(deps.creds.hostKeyPath)) {
+            // A cached token hides a missing host key for up to an hour: the probe
+            // used to pass and the agent then went silent at its next refresh.
+            checks.push({
+                name: "whoami",
+                ok: false,
+                detail: `token minted from cache, but there is no host key at ${deps.creds.hostKeyPath}, so the next refresh will fail. Keep host-key beside machine-creds.json, or re-enroll`,
+            });
+            token = null;
+        }
+        else if (type === "agent" && uid === self) {
             checks.push({ name: "whoami", ok: true, detail: `${self} (external, ${deps.creds.companySlug})` });
         }
         else {

package/dist/commands/dm.js

@@ -84,6 +84,13 @@ export function parseChannelName(recipient) {
  * unit-testable.
  */
 export function matchChannelsByName(channels, name) {
+    // A channel id is exact and names nothing else, so it may target any scope,
+    // including an unnamed group DM. Bots reply this way: their inbox carries
+    // the id of the conversation a message arrived in, not its name.
+    const trimmed = name.trim().replace(/^#/, "");
+    if (/^chn_[A-Za-z0-9]+$/.test(trimmed)) {
+        return channels.filter((c) => c.channelId === trimmed);
+    }
     const targetSlug = channelSlug(name);
     const targetName = name.trim().toLowerCase();
     if (!targetSlug && !targetName)

package/dist/lib/agent-kit/adopt-identity.js

@@ -18,6 +18,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { ensureHostKeyPath } from "./creds.js";
 export const MACHINE_CREDS_FILE_ENV = "HQ_MACHINE_CREDS_FILE";
 export const MACHINE_TOKEN_STATE_DIR_ENV = "HQ_MACHINE_TOKEN_STATE_DIR";
 /**
@@ -37,6 +38,14 @@ export function adoptAgentIdentityEnv(paths, env = process.env) {
     catch {
         return applied;
     }
+    // A moved or copied identity keeps a stale host-key path until the next
+    // token refresh fails; repoint it at the key beside the creds file first.
+    try {
+        ensureHostKeyPath(paths);
+    }
+    catch {
+        /* never block a command on the repair; probe reports a missing key */
+    }
     applied[MACHINE_CREDS_FILE_ENV] = paths.machineCredsPath;
     env[MACHINE_CREDS_FILE_ENV] = paths.machineCredsPath;
     // Per-agent token cache. Two identities on one computer must never share a

package/dist/lib/agent-kit/creds.d.ts

@@ -75,4 +75,32 @@ export interface ComponentReading {
  * older than `staleAfterMs` reads as `error` — silence is never health.
  */
 export declare function readComponentStatus(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent, staleAfterMs: number, now?: () => Date): ComponentReading;
+export type HostKeyPathCheck = {
+    status: "ok";
+    hostKeyPath: string;
+} | {
+    status: "healed";
+    hostKeyPath: string;
+    previous: string;
+} | {
+    status: "missing";
+    hostKeyPath: string;
+} | {
+    status: "no-creds";
+};
+/**
+ * Make the recorded host-key path point at a key that exists.
+ *
+ * The creds file records the key's absolute path, and hq-cloud signs every
+ * token mint with the key at that path. When the identity is moved or copied —
+ * the Runneth pilot copied its files from a disposable $HOME to persistent
+ * storage — the recorded path goes stale, and nothing fails until the cached
+ * token expires up to an hour later. Then every mint fails and the agent goes
+ * silent until someone re-enrolls it.
+ *
+ * The key always travels with the creds file, so when the recorded path is
+ * gone and a key sits beside the creds file, point at that one. The key
+ * itself is never read or copied here; only the recorded path changes.
+ */
+export declare function ensureHostKeyPath(paths: Pick<AgentKitPaths, "machineCredsPath">): HostKeyPathCheck;
 //# sourceMappingURL=creds.d.ts.map

package/dist/lib/agent-kit/creds.js

@@ -26,7 +26,8 @@
  */
 import { createHash, createPublicKey, generateKeyPairSync } from "node:crypto";
 import * as fs from "node:fs";
-import { componentStatePath } from "./paths.js";
+import * as path from "node:path";
+import { componentStatePath, HOST_KEY_NAME } from "./paths.js";
 import { writePrivateFile, } from "./private-file.js";
 /** Contract fingerprint: sha256(DER SPKI public key) hex, first 16 chars. */
 export function hostFingerprint(publicPem) {
@@ -130,4 +131,33 @@ export function readComponentStatus(paths, component, staleAfterMs, now = () =>
     }
     return { status: "ok", at };
 }
+/**
+ * Make the recorded host-key path point at a key that exists.
+ *
+ * The creds file records the key's absolute path, and hq-cloud signs every
+ * token mint with the key at that path. When the identity is moved or copied —
+ * the Runneth pilot copied its files from a disposable $HOME to persistent
+ * storage — the recorded path goes stale, and nothing fails until the cached
+ * token expires up to an hour later. Then every mint fails and the agent goes
+ * silent until someone re-enrolls it.
+ *
+ * The key always travels with the creds file, so when the recorded path is
+ * gone and a key sits beside the creds file, point at that one. The key
+ * itself is never read or copied here; only the recorded path changes.
+ */
+export function ensureHostKeyPath(paths) {
+    const creds = readExternalMachineCreds(paths);
+    if (!creds)
+        return { status: "no-creds" };
+    if (fs.existsSync(creds.hostKeyPath))
+        return { status: "ok", hostKeyPath: creds.hostKeyPath };
+    const sibling = path.join(path.dirname(paths.machineCredsPath), HOST_KEY_NAME);
+    if (sibling === creds.hostKeyPath || !fs.existsSync(sibling)) {
+        return { status: "missing", hostKeyPath: creds.hostKeyPath };
+    }
+    const raw = JSON.parse(fs.readFileSync(paths.machineCredsPath, "utf8"));
+    raw.hostKeyPath = sibling;
+    writePrivateFile(paths.machineCredsPath, `${JSON.stringify(raw, null, 2)}\n`, 0o600);
+    return { status: "healed", hostKeyPath: sibling, previous: creds.hostKeyPath };
+}
 //# sourceMappingURL=creds.js.map

package/dist/lib/agent-kit/inbox-state.d.ts

@@ -50,6 +50,7 @@ export declare function summarizeInboxEntry(e: MirroredInboxEntry, done: boolean
     attachments?: InboxAttachment[] | undefined;
     id: string;
     channel: string | undefined;
+    channelId: string | undefined;
     from: string;
     fromUid: string | undefined;
     at: string | undefined;

package/dist/lib/agent-kit/inbox-state.js

@@ -118,6 +118,9 @@ export function summarizeInboxEntry(e, done) {
     return {
         id: e.id,
         channel: pick("channel"),
+        // Set when the message arrived in a channel or group DM. Reply there
+        // (`hq dm <channelId> "…"`), not to the sender privately.
+        channelId: pick("channelId"),
         from: pick("fromDisplayName", "fromEmail", "fromPersonUid") ?? "unknown",
         fromUid: pick("fromPersonUid"),
         at: pick("receivedAt", "createdAt", "mirroredAt"),

package/dist/lib/agent-kit/mcp/tools.js

@@ -213,11 +213,11 @@ export function buildAgentMcpTools(clients) {
         },
         {
             name: "hq_dm_send",
-            description: "Send an HQ direct message as this agent to a person (email or prs_…) or agent (agt_…). Use audience='agent' for progress/status messages that only agents need to see; audience='human' for messages a person must read; audience='both' when unsure.",
+            description: "Send an HQ message as this agent to a person (email or prs_…), an agent (agt_…), or a channel or group DM (chn_…). When replying to an inbox item that has a channelId, pass that channelId as `to` so the answer lands in the conversation it came from. Use audience='agent' for progress/status messages that only agents need to see; audience='human' for messages a person must read; audience='both' when unsure.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    to: { type: "string", description: "Email, prs_… or agt_… uid" },
+                    to: { type: "string", description: "Email, prs_… or agt_… uid, or a chn_… channel id" },
                     message: { type: "string" },
                     audience: { type: "string", enum: ["human", "agent", "both"], description: "Who this message is for (default: human)" },
                 },
@@ -231,12 +231,25 @@ export function buildAgentMcpTools(clients) {
                 if (audience !== undefined && !["human", "agent", "both"].includes(audience)) {
                     throw new McpToolInputError('"audience" must be human, agent, or both');
                 }
+                if (/^chn_[A-Za-z0-9]+$/.test(to)) {
+                    // A channel or group DM: post into it, so a reply lands where the
+                    // message arrived instead of in a private DM to the sender.
+                    const token = await clients.getToken();
+                    const res = await clients.apiJson(token, `/v1/notify/channels/${encodeURIComponent(to)}/messages`, {
+                        method: "POST",
+                        body: { body: message },
+                    });
+                    if (res.status < 200 || res.status >= 300) {
+                        return errorResult(`Channel send failed (${res.status}): ${describeError(res.body)}`);
+                    }
+                    return textResult(`posted in ${to}`);
+                }
                 const body = /^[^\s]+@[^\s]+$/.test(to)
                     ? { toEmail: to.toLowerCase(), body: message }
                     : isRecipientUid(to)
                         ? { toPersonUid: to, body: message }
                         : (() => {
-                            throw new McpToolInputError('"to" must be an email, prs_… or agt_… uid');
+                            throw new McpToolInputError('"to" must be an email, prs_… or agt_… uid, or a chn_… channel id');
                         })();
                 if (audience)
                     body.audience = audience;
@@ -252,7 +265,7 @@ export function buildAgentMcpTools(clients) {
             name: "hq_inbox_read",
             description: "Read this agent's HQ inbox (DMs, channel mentions, jobs), oldest first. By default only items not yet " +
                 "marked handled. Items with `attachments` carry files: download each with hq_attachment_fetch (pass its vaultPath " +
-                "and companyUid) when its vaultPath is under chat/attachments/ before answering. Reply with hq_dm_send, then mark each one handled with hq_inbox_done so it is never answered twice.",
+                "and companyUid) when its vaultPath is under chat/attachments/ before answering. Reply with hq_dm_send, passing the item's channelId as `to` when it has one so the reply lands in that channel or group; do not reply to another bot's greeting or sign-off that asks for nothing. Then mark each one handled with hq_inbox_done so it is never answered twice.",
             inputSchema: {
                 type: "object",
                 properties: {

package/dist/lib/agent-kit/skills.js

@@ -31,11 +31,17 @@ The kit's inbox poller mirrors every message addressed to you (DMs, channel
 mentions, jobs). Work through them like this:
 
 \`\`\`bash
-hq agent inbox                  # pending messages, oldest first (id, sender uid, text)
-hq dm <sender-uid> "reply"      # answer each one
+hq agent inbox                  # pending messages, oldest first (id, sender uid, channelId, text)
+hq dm <channelId> "reply"       # message came from a channel or group: answer in it
+hq dm <sender-uid> "reply"      # otherwise: answer the sender privately
 hq agent inbox done <id> [id…]  # mark handled so it is never answered twice
 \`\`\`
 
+Reply where the message arrived. A message with a \`channelId\` was posted in a
+channel or group DM, and the answer belongs there, not in a private DM to the
+sender. Do not reply to another bot's greeting, thanks or sign-off that asks
+for nothing: two bots acknowledging each other never stop.
+
 The MCP equivalents are \`hq_inbox_read\`, \`hq_dm_send\` and \`hq_inbox_done\`.
 If the kit has a wake configured (\`hq agent kit wake show\`), HQ pokes your
 framework whenever something is pending, so always drain the whole list and

package/dist/lib/agent-kit/wake.js

@@ -27,8 +27,10 @@ export const WAKE_STATE_NAME = "wake-state.json";
 export const DEFAULT_WAKE_RETRY_MS = 10 * 60_000;
 export const WAKE_URL_TIMEOUT_MS = 15_000;
 export const DEFAULT_WAKE_COMMAND_TIMEOUT_MS = 10 * 60_000;
-export const WAKE_INSTRUCTIONS = "New HQ messages are waiting. Run `hq agent inbox` (or the hq_inbox_read tool), reply to each " +
-    "with `hq dm <sender-uid> \"…\"` (or hq_dm_send), then mark each handled with `hq agent inbox done <id>` (or hq_inbox_done).";
+export const WAKE_INSTRUCTIONS = "New HQ messages are waiting. Run `hq agent inbox` (or the hq_inbox_read tool). Reply where each message " +
+    "arrived: if it has a channelId, post in that channel with `hq dm <channelId> \"…\"`; otherwise reply to the " +
+    "sender with `hq dm <sender-uid> \"…\"` (or hq_dm_send). Do not reply to another bot's greeting, thanks or " +
+    "sign-off that asks for nothing. Then mark each handled with `hq agent inbox done <id>` (or hq_inbox_done).";
 export function wakePath(paths) {
     return path.join(paths.agentDir, WAKE_FILE_NAME);
 }
@@ -197,7 +199,11 @@ export async function fireWake(config, notice, deps) {
     let child;
     try {
         child = doSpawn(config.command[0], config.command.slice(1), {
-            stdio: ["pipe", logFd, logFd],
+            // stdout is discarded: a wake command's normal output (a routine record,
+            // a prompt echo) has no diagnostic value and would land in a log that is
+            // world-readable on a share without permissions. stderr is kept so a
+            // failing wake can still be diagnosed.
+            stdio: ["pipe", "ignore", logFd],
             env: {
                 ...process.env,
                 HQ_WAKE_EVENT: notice.event,

package/dist/main.js

@@ -54,6 +54,9 @@ import { installTreeTornCaptureContext, installTreeTornStderrLine, isInstallTree
 import { isVaultAccessDeniedError, vaultAccessDeniedMessage, } from "./utils/vault-access-denied-error.js";
 import { fallbackOperatorMessage, unexpectedCliErrorMessage } from "./utils/unexpected-cli-error.js";
 import { runGlobalNetworkLifecycle } from "./utils/cli-network-lifecycle.js";
+import * as os from "node:os";
+import { adoptAgentIdentityEnv } from "./lib/agent-kit/adopt-identity.js";
+import { agentKitPaths } from "./lib/agent-kit/paths.js";
 /**
  * Total time one CLI invocation may await foreground network work. This spans
  * the hard version decision, pre-action observability, and release-health
@@ -160,6 +163,16 @@ program
     .description("HQ management CLI — modules, packages, and cloud sync")
     .version(CLI_VERSION);
 program.hook("preAction", async () => {
+    // A host that pinned HQ_AGENT_DIR has declared that it IS that agent, so
+    // every command — `hq dm`, `hq secrets`, not only `hq agent …` — must
+    // mint as the agent. Without this, those commands looked for a person
+    // session, found none, and opened a browser sign-in that a headless bot can
+    // never complete. Only the explicit variable counts: a bot that merely lives
+    // beside its owner on the owner's computer must not take over the owner's
+    // commands.
+    if (process.env.HQ_AGENT_DIR?.trim()) {
+        adoptAgentIdentityEnv(agentKitPaths(os.homedir(), process.env), process.env);
+    }
     // Both are best-effort and fully swallowed: neither can change the command's
     // result or exit code. They receive only the shared pre-finalization
     // allowance (up to 1.2s), and that bound is a TIMER, so it only preempts

package/dist/utils/cognito-session.d.ts

@@ -290,4 +290,16 @@ export declare function refreshCachedSession(options?: Pick<EnsureCognitoTokenOp
     refreshed: boolean;
     reason?: string;
 }>;
+/**
+ * True on a Linux host with no terminal and no display — a container or
+ * server, where a browser sign-in can never be completed. macOS and Windows
+ * always have a way to open a browser, and a terminal means a person is there.
+ */
+export declare function isHeadlessHost(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, tty?: boolean): boolean;
+/**
+ * True when the environment explicitly names an HQ agent identity. Only the
+ * explicit variables count: guessing from the filesystem is unreliable, and a
+ * wrong guess would take an ordinary headless run off its sign-in path.
+ */
+export declare function hostRunsAnAgent(env?: NodeJS.ProcessEnv): boolean;
 //# sourceMappingURL=cognito-session.d.ts.map

package/dist/utils/cognito-session.js

@@ -943,6 +943,15 @@ async function ensureCognitoTokenUnserialized(options) {
     if (!interactive) {
         throw new Error("No valid HQ session and interactive login is disabled. Run `hq login` first.");
     }
+    if (isHeadlessHost() && hostRunsAnAgent()) {
+        // An agent host with no display has no one to complete a browser sign-in,
+        // which then blocks until something kills the process. Fail with the fix
+        // instead. Scoped to agent hosts so an ordinary headless run keeps the
+        // existing sign-in and its remedies.
+        throw new Error("No valid HQ session, and this host has no display for a browser sign-in. " +
+            "If this is an enrolled agent, set HQ_AGENT_DIR to its agent directory " +
+            "(or HQ_MACHINE_CREDS_FILE to its machine-creds.json). Otherwise run `hq login` on a computer with a browser.");
+    }
     console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
     const tokens = await browserLogin(DEFAULT_COGNITO);
     return tokens.accessToken;
@@ -1010,6 +1019,13 @@ async function ensureCognitoIdTokenUnserialized(options) {
     if (!interactive) {
         throw new Error("No valid HQ session and interactive login is disabled. Run `hq login` first.");
     }
+    if (isHeadlessHost() && hostRunsAnAgent()) {
+        // A browser sign-in on a server has no one to complete it and blocks
+        // until something kills the process. Fail with the fix instead.
+        throw new Error("No valid HQ session, and this host has no display for a browser sign-in. " +
+            "If this is an enrolled agent, set HQ_AGENT_DIR to its agent directory " +
+            "(or HQ_MACHINE_CREDS_FILE to its machine-creds.json). Otherwise run `hq login` on a computer with a browser.");
+    }
     console.error(chalk.cyan("  No cached HQ session — launching browser sign-in..."));
     const tokens = await browserLogin(DEFAULT_COGNITO);
     return tokens.idToken;
@@ -1121,4 +1137,24 @@ async function refreshCachedSessionUnserialized(options) {
         };
     }
 }
+/**
+ * True on a Linux host with no terminal and no display — a container or
+ * server, where a browser sign-in can never be completed. macOS and Windows
+ * always have a way to open a browser, and a terminal means a person is there.
+ */
+export function isHeadlessHost(env = process.env, platform = process.platform, tty = Boolean(process.stdin.isTTY || process.stdout.isTTY || process.stderr.isTTY)) {
+    if (platform !== "linux")
+        return false;
+    if (tty)
+        return false;
+    return !env.DISPLAY?.trim() && !env.WAYLAND_DISPLAY?.trim();
+}
+/**
+ * True when the environment explicitly names an HQ agent identity. Only the
+ * explicit variables count: guessing from the filesystem is unreliable, and a
+ * wrong guess would take an ordinary headless run off its sign-in path.
+ */
+export function hostRunsAnAgent(env = process.env) {
+    return Boolean(env.HQ_AGENT_DIR?.trim() || env.HQ_MACHINE_CREDS_FILE?.trim());
+}
 //# sourceMappingURL=cognito-session.js.map

package/package.json

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