@indigoai-us/hq-cli 5.117.0 → 5.117.1

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [Unreleased]
 
+## [5.117.1] — 2026-09-16
+
+### Fixed
+
+- `hq agent probe` works for external agents. The work-mesh check no longer
+  reads the owner-only company roster (which answered "Not found" to an agent);
+  it passes when the realtime credential vend names the agent, the agent's own
+  inbox answers, and this host's heartbeat and mesh listener are live. The DM
+  check reads the probe message back from the agent's inbox instead of the
+  human-only thread view that refused agents. Output format is unchanged.
+- The agent kit's mesh listener stays connected. It now asks for the personal
+  realtime credentials that cover the agent's own doorbell topics (the company
+  presence credentials it used made the connection drop before subscribing),
+  subscribes only to topics those credentials grant, and polls the inbox
+  immediately when an inbox doorbell rings.
+- Inbox poll failures are diagnosable: the log names the method, full URL,
+  status and the first 300 characters of the response, and the inbox URL keeps
+  any base path from `apiBaseUrl` without doubling `/v1`.
+- `hq dm inbox` works for agent identities by reading the agent inbox;
+  `hq dm thread` tells agents to use `hq dm inbox` instead of failing with a
+  server refusal.
+- `hq agent kit install` works on hosts with no systemd user session or
+  launchd: it starts the services under one background `hq agent kit run all`
+  supervisor (restarting any service that exits), records its pid in
+  `~/.hq-agent/kit.pid`, and prints the `@reboot` crontab line that keeps it
+  running after a restart. `kit status` and `kit uninstall` understand this
+  mode.
+
 ## [5.117.0] — 2026-09-16
 
 ### Added

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

@@ -4217,7 +4217,7 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly subcommands: readonly [];
         }, {
             readonly name: "run";
-            readonly description: "Run one kit service in the foreground (sync|mesh|inbox|heartbeat)";
+            readonly description: "Run one kit service in the foreground (sync|mesh|inbox|heartbeat), or `all` to supervise every service in one process";
             readonly aliases: readonly [];
             readonly hidden: false;
             readonly usage: "[options] <service>";

package/dist/command-catalog.generated.js

@@ -5455,7 +5455,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "name": "run",
-                        "description": "Run one kit service in the foreground (sync|mesh|inbox|heartbeat)",
+                        "description": "Run one kit service in the foreground (sync|mesh|inbox|heartbeat), or `all` to supervise every service in one process",
                         "aliases": [],
                         "hidden": false,
                         "usage": "[options] <service>",

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

@@ -10,7 +10,10 @@
  * `install` renders one user-level unit per service (LaunchAgent on macOS,
  * systemd --user on Linux), each of which just runs
  * `node hq agent kit run <service>`; the Docker image runs the same four
- * commands. Logs: ~/.hq-agent/logs/<service>.log. Skills:
+ * commands. Hosts where the service manager is unusable (no systemd user
+ * session bus, permission refused, launchd unavailable) fall back to one
+ * detached `hq agent kit run all` supervisor (pid in ~/.hq-agent/kit.pid,
+ * output in ~/.hq-agent/logs/kit.log). Logs: ~/.hq-agent/logs/<service>.log. Skills:
  * ~/.hq-agent/skills/<name>/SKILL.md.
  */
 import { Command } from "commander";
@@ -19,6 +22,7 @@ import { type KitConfig } from "../lib/agent-kit/kit-config.js";
 import { type KitLogger } from "../lib/agent-kit/log.js";
 import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
 import { type KitService } from "../lib/agent-kit/services.js";
+import { type DetachedSpawn, type KillFn } from "../lib/agent-kit/fallback.js";
 import { type ServiceHostPaths, type ServiceManagerDeps, type ServiceSetResult } from "../lib/service-manager/index.js";
 export declare class KitError extends Error {
     constructor(message: string);
@@ -32,12 +36,25 @@ export interface KitInstallOptions {
     inboxAck?: boolean;
     activate?: boolean;
 }
+export interface KitFallbackInfo {
+    mode: "fallback";
+    pid: number;
+    pidFile: string;
+    logPath: string;
+    /** Add to `crontab -e` so the supervisor survives a reboot. */
+    crontab: string;
+}
 export interface KitInstallResult {
     config: KitConfig;
     skills: string[];
     services: ServiceSetResult;
+    fallback?: KitFallbackInfo;
+}
+export interface KitFallbackDeps {
+    spawn?: DetachedSpawn;
+    kill?: KillFn;
 }
-export declare function installKit(paths: AgentKitPaths, opts: KitInstallOptions, host: ServiceHostPaths, deps?: ServiceManagerDeps): KitInstallResult;
+export declare function installKit(paths: AgentKitPaths, opts: KitInstallOptions, host: ServiceHostPaths, deps?: ServiceManagerDeps, fallbackDeps?: KitFallbackDeps): KitInstallResult;
 export declare function formatServiceSet(result: ServiceSetResult): string[];
 /** Shared runtime for `kit run <service>`. */
 export interface KitRuntime {
@@ -47,7 +64,10 @@ export interface KitRuntime {
     getToken: () => Promise<string>;
     log: KitLogger;
 }
-export declare function buildKitRuntime(service: KitService): KitRuntime;
+export declare function buildKitRuntime(service: KitService | "all"): KitRuntime;
 export declare function runKitService(service: KitService, rt: KitRuntime): Promise<void>;
+/** `kit run all`: supervise the four services as child processes with restart backoff. */
+export declare function runAllKitServices(rt: KitRuntime, host: ServiceHostPaths): Promise<void>;
+export declare function formatFallbackStatus(paths: AgentKitPaths, kill?: KillFn): string[] | null;
 export declare function registerAgentKitCommand(agent: Command): void;
 //# sourceMappingURL=agent-kit.d.ts.map

package/dist/commands/agent-kit.js

@@ -10,7 +10,10 @@
  * `install` renders one user-level unit per service (LaunchAgent on macOS,
  * systemd --user on Linux), each of which just runs
  * `node hq agent kit run <service>`; the Docker image runs the same four
- * commands. Logs: ~/.hq-agent/logs/<service>.log. Skills:
+ * commands. Hosts where the service manager is unusable (no systemd user
+ * session bus, permission refused, launchd unavailable) fall back to one
+ * detached `hq agent kit run all` supervisor (pid in ~/.hq-agent/kit.pid,
+ * output in ~/.hq-agent/logs/kit.log). Logs: ~/.hq-agent/logs/<service>.log. Skills:
  * ~/.hq-agent/skills/<name>/SKILL.md.
  */
 import chalk from "chalk";
@@ -25,7 +28,11 @@ import { agentKitPaths } from "../lib/agent-kit/paths.js";
 import { isKitService, KIT_SERVICES, kitServiceSpecs, } from "../lib/agent-kit/services.js";
 import { writeKitSkills } from "../lib/agent-kit/skills.js";
 import { runHeartbeatLoop } from "../lib/agent-kit/run/heartbeat.js";
-import { runInboxLoop } from "../lib/agent-kit/run/inbox.js";
+import { pollInboxOnce, runInboxLoop } from "../lib/agent-kit/run/inbox.js";
+import { superviseKitServices } from "../lib/agent-kit/run/supervisor.js";
+import { fallbackStatus, rebootCrontabLine, shouldUseFallback, startFallback, stopFallback, } from "../lib/agent-kit/fallback.js";
+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 { runSyncLoop } from "../lib/agent-kit/run/sync.js";
 import { resolveHqBinary, resolveNodeBinary, } from "../lib/mesh/live/daemon/install.js";
@@ -57,7 +64,7 @@ export function resolveServiceHost(paths) {
         hqBinary: resolveHqBinary(),
     };
 }
-export function installKit(paths, opts, host, deps = {}) {
+export function installKit(paths, opts, host, deps = {}, fallbackDeps = {}) {
     requireExternalCreds(paths);
     ensureKitDirs(paths);
     const existing = fs.existsSync(paths.kitConfigPath)
@@ -72,10 +79,20 @@ export function installKit(paths, opts, host, deps = {}) {
     fs.mkdirSync(config.hqRoot, { recursive: true, mode: 0o700 });
     writeKitConfig(paths, config);
     const skills = writeKitSkills(paths);
+    const activate = opts.activate ?? deps.activate ?? true;
     const services = installServices(kitServiceSpecs(paths), host, {
         ...deps,
-        activate: opts.activate ?? deps.activate ?? true,
+        activate,
     });
+    if (shouldUseFallback(services, activate)) {
+        const started = startFallback(paths, host, fallbackDeps);
+        return {
+            config,
+            skills,
+            services,
+            fallback: { mode: "fallback", ...started, crontab: rebootCrontabLine(paths, host) },
+        };
+    }
     return { config, skills, services };
 }
 export function formatServiceSet(result) {
@@ -151,6 +168,16 @@ export async function runKitService(service, rt) {
                 refreshMs: rt.config.meshRefreshMs,
                 getToken: rt.getToken,
                 log: rt.log,
+                // An inbox doorbell means "poll now" rather than waiting for the loop.
+                onInboxDoorbell: () => pollInboxOnce({
+                    paths: rt.paths,
+                    agentUid: rt.creds.entityUid,
+                    apiBaseUrl: rt.creds.apiBaseUrl,
+                    pollMs: rt.config.inboxPollMs,
+                    ack: rt.config.inboxAck,
+                    getToken: rt.getToken,
+                    log: rt.log,
+                }),
             });
             const stop = () => {
                 void handle.stop().then(() => process.exit(0));
@@ -164,6 +191,45 @@ export async function runKitService(service, rt) {
         }
     }
 }
+/** `kit run all`: supervise the four services as child processes with restart backoff. */
+export async function runAllKitServices(rt, host) {
+    rt.log("info", `supervisor starting ${KIT_SERVICES.join(",")} agent=${rt.creds.entityUid} cli=${CLI_VERSION}`);
+    const handle = superviseKitServices({
+        services: KIT_SERVICES,
+        log: rt.log,
+        spawnService: (service) => {
+            const fd = fs.openSync(serviceLogPath(rt.paths, service), "a", 0o600);
+            try {
+                return spawn(host.nodeBinary, [host.hqBinary, "agent", "kit", "run", service], {
+                    stdio: ["ignore", fd, fd],
+                    env: process.env,
+                    cwd: rt.paths.agentDir,
+                });
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        },
+    });
+    await new Promise((resolve) => {
+        const stop = (signal) => {
+            rt.log("info", `supervisor stopping (${signal})`);
+            handle.stop("SIGTERM");
+            resolve();
+        };
+        process.once("SIGTERM", () => stop("SIGTERM"));
+        process.once("SIGINT", () => stop("SIGINT"));
+    });
+}
+export function formatFallbackStatus(paths, kill) {
+    const st = fallbackStatus(paths, kill);
+    if (!st)
+        return null;
+    const state = st.running
+        ? chalk.green(`running (pid ${st.pid})`)
+        : 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 fail(err) {
     console.error(chalk.red(err instanceof Error ? err.message : String(err)));
     process.exit(1);
@@ -191,9 +257,19 @@ export function registerAgentKitCommand(agent) {
             console.log(`  hq root:   ${result.config.hqRoot}`);
             console.log(`  logs:      ${paths.logsDir}`);
             console.log(`  skills:    ${paths.skillsDir} (${result.skills.length} skills)`);
-            console.log("  services:");
-            for (const line of formatServiceSet(result.services))
-                console.log(line);
+            if (result.fallback) {
+                console.log(chalk.yellow("  services: service manager unavailable — running in fallback mode " +
+                    `(hq agent kit run all, pid ${result.fallback.pid})`));
+                console.log(`  pidfile:   ${result.fallback.pidFile}`);
+                console.log(`  kit log:   ${result.fallback.logPath}`);
+                console.log("  To restart it after a reboot, add this line with `crontab -e`:");
+                console.log(`    ${result.fallback.crontab}`);
+            }
+            else {
+                console.log("  services:");
+                for (const line of formatServiceSet(result.services))
+                    console.log(line);
+            }
             console.log("");
             console.log("Next: hq agent probe");
         }
@@ -208,13 +284,19 @@ export function registerAgentKitCommand(agent) {
         .action((opts) => {
         try {
             const paths = agentKitPaths(os.homedir(), process.env);
+            const fallback = fallbackStatus(paths);
             const result = servicesStatus(kitServiceSpecs(paths), resolveServiceHost(paths));
             if (opts.json) {
-                console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+                console.log(JSON.stringify({ ok: true, ...result, ...(fallback ? { fallback } : {}) }, null, 2));
                 return;
             }
-            for (const line of formatServiceSet(result))
-                console.log(line);
+            const fallbackLines = formatFallbackStatus(paths);
+            if (fallbackLines)
+                for (const line of fallbackLines)
+                    console.log(line);
+            else
+                for (const line of formatServiceSet(result))
+                    console.log(line);
         }
         catch (err) {
             fail(err);
@@ -227,11 +309,15 @@ export function registerAgentKitCommand(agent) {
         .action((opts) => {
         try {
             const paths = agentKitPaths(os.homedir(), process.env);
+            const fallback = stopFallback(paths);
             const result = uninstallServices(kitServiceSpecs(paths), resolveServiceHost(paths));
             if (opts.json) {
-                console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+                console.log(JSON.stringify({ ok: true, ...result, fallback }, null, 2));
                 return;
             }
+            if (fallback.pid !== null) {
+                console.log(`  fallback supervisor pid ${fallback.pid} ${fallback.killed ? "stopped" : "was not running"}; pidfile removed`);
+            }
             console.log(chalk.green("HQ agent kit services removed."));
             for (const line of formatServiceSet(result))
                 console.log(line);
@@ -242,10 +328,21 @@ export function registerAgentKitCommand(agent) {
     });
     kit
         .command("run <service>")
-        .description(`Run one kit service in the foreground (${KIT_SERVICES.join("|")})`)
+        .description(`Run one kit service in the foreground (${KIT_SERVICES.join("|")}), or \`all\` to supervise every service in one process`)
         .action(async (service) => {
+        if (service === "all") {
+            try {
+                const paths = agentKitPaths(os.homedir(), process.env);
+                const rt = buildKitRuntime("all");
+                await runAllKitServices(rt, resolveServiceHost(paths));
+                process.exit(0);
+            }
+            catch (err) {
+                fail(err);
+            }
+        }
         if (!isKitService(service)) {
-            console.error(chalk.red(`Unknown kit service "${service}". Expected one of: ${KIT_SERVICES.join(", ")}`));
+            console.error(chalk.red(`Unknown kit service "${service}". Expected one of: all, ${KIT_SERVICES.join(", ")}`));
             process.exit(1);
         }
         try {

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

@@ -4,9 +4,14 @@
  *
  *   whoami       mint as the machine identity; token names this agent
  *   team-sync    `hq sync pull --all` succeeds and the company folder exists
- *   work-mesh    realtime credentials vend for this agent and the roster row
- *                shows presence online/stale (heartbeat landed)
- *   dm           send a DM to self via the notify surface and read it back
+ *   work-mesh    the personal (contract-2) realtime vend names this agent, the
+ *                agent-authorized inbox route answers 200, and this host's own
+ *                presence is live: a fresh last-heartbeat.json plus an ok
+ *                component-mesh stamp from the doorbell listener. (The company
+ *                roster route is owner/admin-only and 404s for agt_ callers.)
+ *   dm           send a DM to self via POST /v1/notify/dm and read it back
+ *                through GET /v1/agents/{uid}/inbox (the agent read surface;
+ *                /v1/notify/thread is intentionally closed to agents)
  *   secrets      `GET /secrets/{companyUid}` answers 200
  *
  * Output is the exact shape the console recipes promise: one
@@ -18,6 +23,7 @@
  * the kit's last heartbeat.
  */
 import { Command } from "commander";
+import { type InboxFetchResult } from "../lib/agent-kit/run/inbox.js";
 import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
 import type { ExternalMachineCreds } from "../lib/agent-kit/creds.js";
 export interface ProbeCheck {
@@ -34,6 +40,8 @@ export interface ProbeResult {
 }
 export declare const DM_ROUNDTRIP_TIMEOUT_MS = 20000;
 export declare const DM_ROUNDTRIP_POLL_MS = 2000;
+/** A heartbeat older than this does not count as live presence (3 missed 60 s beats). */
+export declare const PRESENCE_FRESH_SECONDS = 180;
 export interface ProbeDeps {
     paths: AgentKitPaths;
     creds: ExternalMachineCreds;
@@ -44,11 +52,9 @@ export interface ProbeDeps {
     vendRealtime: (token: string) => Promise<{
         actorUid: string;
     }>;
-    listRoster: (token: string, companyUid: string) => Promise<Array<Record<string, unknown>>>;
+    /** GET /v1/agents/{self}/inbox — agent-authorized, self-scoped. */
+    readInbox: (token: string) => Promise<InboxFetchResult>;
     sendDm: (token: string, toUid: string, body: string) => Promise<void>;
-    readThread: (token: string, withUid: string) => Promise<Array<{
-        body: string;
-    }>>;
     listSecrets: (token: string, companyUid: string) => Promise<number>;
     postResult: (token: string, result: ProbeResult) => Promise<number>;
     now?: () => Date;
@@ -58,6 +64,8 @@ export interface ProbeDeps {
 }
 export declare function heartbeatAgeSeconds(paths: Pick<AgentKitPaths, "lastHeartbeatPath">, now?: () => Date): number | null;
 export declare function runProbe(deps: ProbeDeps): Promise<ProbeResult>;
+/** True when any inbox item (whatever its channel shape) carries the nonce. */
+export declare function inboxContainsNonce(body: unknown, nonce: string): boolean;
 export declare function formatHeartbeatAge(age: number | null): string;
 /**
  * Recipe contract: `PASS  <check>  <detail>` / `FAIL  <check>  <detail>` per

package/dist/commands/agent-probe.js

@@ -4,9 +4,14 @@
  *
  *   whoami       mint as the machine identity; token names this agent
  *   team-sync    `hq sync pull --all` succeeds and the company folder exists
- *   work-mesh    realtime credentials vend for this agent and the roster row
- *                shows presence online/stale (heartbeat landed)
- *   dm           send a DM to self via the notify surface and read it back
+ *   work-mesh    the personal (contract-2) realtime vend names this agent, the
+ *                agent-authorized inbox route answers 200, and this host's own
+ *                presence is live: a fresh last-heartbeat.json plus an ok
+ *                component-mesh stamp from the doorbell listener. (The company
+ *                roster route is owner/admin-only and 404s for agt_ callers.)
+ *   dm           send a DM to self via POST /v1/notify/dm and read it back
+ *                through GET /v1/agents/{uid}/inbox (the agent read surface;
+ *                /v1/notify/thread is intentionally closed to agents)
  *   secrets      `GET /secrets/{companyUid}` answers 200
  *
  * Output is the exact shape the console recipes promise: one
@@ -26,8 +31,11 @@ import { CLI_VERSION } from "../cli-version.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { peekIdToken } from "../utils/id-token.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-import { listAgents, readAgentThread, sendAgentDm } from "./agents.js";
-import { createContract3Fetcher } from "../lib/mesh/live/daemon/credentials.js";
+import { sendAgentDm } from "./agents.js";
+import { createPersonalRealtimeFetcher } from "../lib/mesh/live/daemon/credentials.js";
+import { readComponentStatus } from "../lib/agent-kit/creds.js";
+import { COMPONENT_STALE_AFTER_MS } from "../lib/agent-kit/run/heartbeat.js";
+import { defaultFetchInbox } from "../lib/agent-kit/run/inbox.js";
 import { agentKitPaths } from "../lib/agent-kit/paths.js";
 import { readKitConfig } from "../lib/agent-kit/kit-config.js";
 import { readLastHeartbeat } from "../lib/agent-kit/run/heartbeat.js";
@@ -35,6 +43,8 @@ import { defaultRunPull, syncPullArgs } from "../lib/agent-kit/run/sync.js";
 import { requireExternalCreds } from "./agent-kit.js";
 export const DM_ROUNDTRIP_TIMEOUT_MS = 20_000;
 export const DM_ROUNDTRIP_POLL_MS = 2_000;
+/** A heartbeat older than this does not count as live presence (3 missed 60 s beats). */
+export const PRESENCE_FRESH_SECONDS = 180;
 function errText(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -108,7 +118,7 @@ export async function runProbe(deps) {
     else {
         checks.push({ name: "team-sync", ok: false, detail: "skipped: no token" });
     }
-    // 3. mesh-presence
+    // 3. work-mesh: vend + agent-authorized reachability + self presence
     if (token && companyUid) {
         try {
             const vend = await deps.vendRealtime(token);
@@ -116,17 +126,23 @@ export async function runProbe(deps) {
                 checks.push({ name: "work-mesh", ok: false, detail: `realtime vend is for ${vend.actorUid}` });
             }
             else {
-                const roster = await deps.listRoster(token, companyUid);
-                const row = roster.find((r) => r.uid === self);
-                const presence = typeof row?.presence === "string" ? row.presence : "unknown";
-                const last = typeof row?.lastHeartbeatAt === "string" ? row.lastHeartbeatAt : "never";
-                const ok = presence === "online" || presence === "stale";
+                const inbox = await deps.readInbox(token);
+                const age = heartbeatAgeSeconds(deps.paths, now);
+                const mesh = readComponentStatus(deps.paths, "mesh", COMPONENT_STALE_AFTER_MS.mesh, now);
+                const reachable = inbox.status === 200;
+                const fresh = age !== null && age <= PRESENCE_FRESH_SECONDS;
+                const meshOk = mesh.status === "ok";
+                const ok = reachable && fresh && meshOk;
+                const parts = [
+                    "realtime vend ok",
+                    `inbox GET → ${inbox.status}`,
+                    `heartbeat ${age === null ? "never" : `${age}s ago`}`,
+                    `mesh listener ${mesh.status}${mesh.at ? ` @${mesh.at.toISOString()}` : ""}`,
+                ];
                 checks.push({
                     name: "work-mesh",
                     ok,
-                    detail: row
-                        ? `realtime vend ok; presence=${presence} lastHeartbeatAt=${last}${ok ? "" : " — is `hq agent kit` installed and running?"}`
-                        : "realtime vend ok but this agent is not on the company roster",
+                    detail: `${parts.join("; ")}${ok ? "" : " — is `hq agent kit` installed and running? see ~/.hq-agent/logs/mesh.log"}`,
                 });
             }
         }
@@ -137,27 +153,37 @@ export async function runProbe(deps) {
     else {
         checks.push({ name: "work-mesh", ok: false, detail: "skipped: no token/company" });
     }
-    // 4. dm-roundtrip
+    // 4. dm round-trip: send via notify, read back via the agent inbox
     if (token) {
         try {
             const body = `hq agent probe ${nonce}`;
             await deps.sendDm(token, self, body);
             const deadline = now().getTime() + (deps.dmTimeoutMs ?? DM_ROUNDTRIP_TIMEOUT_MS);
             let found = false;
+            let lastStatus = 0;
             for (;;) {
-                const msgs = await deps.readThread(token, self);
-                if (msgs.some((m) => typeof m.body === "string" && m.body.includes(nonce))) {
+                const res = await deps.readInbox(token);
+                lastStatus = res.status;
+                if (res.status === 200 && inboxContainsNonce(res.body, nonce)) {
                     found = true;
                     break;
                 }
+                // A 4xx will not heal by polling (auth/route refusal): stop now.
+                if (res.status >= 400 && res.status < 500)
+                    break;
                 if (now().getTime() >= deadline)
                     break;
                 await sleep(DM_ROUNDTRIP_POLL_MS);
             }
+            const secs = Math.round((deps.dmTimeoutMs ?? DM_ROUNDTRIP_TIMEOUT_MS) / 1000);
             checks.push({
                 name: "dm",
                 ok: found,
-                detail: found ? "sent to self via /v1/notify/dm and read back" : `sent but not visible in thread after ${Math.round((deps.dmTimeoutMs ?? DM_ROUNDTRIP_TIMEOUT_MS) / 1000)}s`,
+                detail: found
+                    ? "sent to self via /v1/notify/dm and read back from /v1/agents/{uid}/inbox"
+                    : lastStatus === 200
+                        ? `sent but not visible in /v1/agents/{uid}/inbox after ${secs}s`
+                        : `sent but /v1/agents/{uid}/inbox answered ${lastStatus}`,
             });
         }
         catch (err) {
@@ -205,6 +231,19 @@ export async function runProbe(deps) {
     }
     return result;
 }
+/** True when any inbox item (whatever its channel shape) carries the nonce. */
+export function inboxContainsNonce(body, nonce) {
+    const rec = body && typeof body === "object" ? body : {};
+    const messages = Array.isArray(rec.messages) ? rec.messages : [];
+    return messages.some((m) => {
+        try {
+            return JSON.stringify(m).includes(nonce);
+        }
+        catch {
+            return false;
+        }
+    });
+}
 export function formatHeartbeatAge(age) {
     if (age === null)
         return "never (kit heartbeat has not posted yet)";
@@ -241,12 +280,11 @@ export function defaultProbeDeps(paths, creds) {
         resolveCompanyUid: (token, slug) => getCompanyUid(token, slug),
         runPull: defaultRunPull(process.execPath, process.argv[1], process.env),
         vendRealtime: async (token) => {
-            const bundle = await createContract3Fetcher({ token, baseUrl: base })();
+            const bundle = await createPersonalRealtimeFetcher({ token, baseUrl: base })();
             return { actorUid: bundle.actorUid };
         },
-        listRoster: async (token, companyUid) => (await listAgents(token, companyUid)),
+        readInbox: (token) => defaultFetchInbox(creds.entityUid, base)(token),
         sendDm: (token, to, body) => sendAgentDm(token, to, body),
-        readThread: async (token, withUid) => readAgentThread(token, withUid, 20),
         listSecrets: async (token, companyUid) => {
             const res = await vaultApiFetch({
                 token,

package/dist/commands/dm.d.ts

@@ -259,5 +259,15 @@ export declare function formatInboxEvent(e: DmInboxEvent, nowMs: number): string
 export declare function formatThreadMessage(m: DmThreadMessage, nowMs: number): string;
 /** Render one channel/group message line. */
 export declare function formatChannelMessage(m: ChannelMessageItem, nowMs: number): string;
+/**
+ * The agent uid when the caller is an agent (machine) identity, else null.
+ * Agents may not read /v1/notify/inbox or /v1/notify/thread (the server
+ * allow-list is intentionally human-only); their read surface is
+ * GET /v1/agents/{uid}/inbox.
+ */
+export declare function agentCallerUid(token: string, machine?: () => boolean): string | null;
+export declare const AGENT_THREAD_UNAVAILABLE: string;
+/** One-line summary of an agent inbox item (DM, email, … — shapes vary by channel). Pure. */
+export declare function formatAgentInboxItem(item: Record<string, unknown>): string;
 export declare function registerDmCommand(program: Command): void;
 //# sourceMappingURL=dm.d.ts.map

package/dist/commands/dm.js

@@ -2,6 +2,8 @@ import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { isMachineIdentity } from "@indigoai-us/hq-cloud";
+import { peekIdToken } from "../utils/id-token.js";
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 // People (prs_) and agents (agt_) are both first-class DM participants; the
 // server applies the same membership-overlap gate to either and delivers
@@ -789,9 +791,83 @@ async function ackEvents(token, eventIds) {
         throw new Error(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText));
     }
 }
+/**
+ * The agent uid when the caller is an agent (machine) identity, else null.
+ * Agents may not read /v1/notify/inbox or /v1/notify/thread (the server
+ * allow-list is intentionally human-only); their read surface is
+ * GET /v1/agents/{uid}/inbox.
+ */
+export function agentCallerUid(token, machine = isMachineIdentity) {
+    const claims = peekIdToken(token);
+    const uid = claims["custom:entityUid"];
+    if (typeof uid !== "string" || !uid.startsWith("agt_"))
+        return null;
+    if (claims["custom:entityType"] === "agent")
+        return uid;
+    try {
+        return machine() ? uid : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const AGENT_THREAD_UNAVAILABLE = "`hq dm thread` reads /v1/notify/thread, which is not available to agent identities. " +
+    "Use `hq dm inbox` — for agents it reads GET /v1/agents/{uid}/inbox.";
+/** One-line summary of an agent inbox item (DM, email, … — shapes vary by channel). Pure. */
+export function formatAgentInboxItem(item) {
+    const str = (k) => (typeof item[k] === "string" ? item[k] : "");
+    const id = str("messageId") || str("id") || "?";
+    const channel = str("channel") || "inbox";
+    const from = str("fromDisplayName") || str("fromEmail") || str("from") || str("fromPersonUid") || "unknown";
+    const when = str("createdAt") || str("receivedAt");
+    const text = str("text") || str("body") || str("subject");
+    return `${chalk.bold(from)} ${chalk.dim(`[${channel}] ${id}${when ? ` ${when}` : ""}`)}\n  ${firstLine(text)}`;
+}
+async function runAgentInbox(token, agentUid, opts) {
+    const route = `/v1/agents/${encodeURIComponent(agentUid)}/inbox`;
+    const res = await vaultApiFetch({ token, path: route });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(chalk.red(`GET ${route} → ${res.status}${text ? `: ${text.slice(0, 300)}` : ""}`));
+        process.exit(1);
+    }
+    const data = (await res.json().catch(() => ({})));
+    let items = Array.isArray(data.messages) ? data.messages : [];
+    if (opts.limit && Number(opts.limit) > 0)
+        items = items.slice(0, Number(opts.limit));
+    if (opts.json) {
+        console.log(JSON.stringify(items, null, 2));
+    }
+    else if (items.length === 0) {
+        console.log(chalk.dim("No pending inbox items."));
+    }
+    else {
+        console.log(chalk.green(`${items.length} pending inbox item${items.length === 1 ? "" : "s"}:`));
+        for (const item of items)
+            console.log(`\n${formatAgentInboxItem(item)}`);
+    }
+    if (opts.markRead) {
+        let acked = 0;
+        for (const item of items) {
+            const id = typeof item.messageId === "string" ? item.messageId : typeof item.id === "string" ? item.id : null;
+            if (!id)
+                continue;
+            const ack = await vaultApiFetch({ token, path: `${route}/${encodeURIComponent(id)}/ack`, method: "POST" });
+            if (ack.ok)
+                acked += 1;
+        }
+        if (!opts.json && acked > 0)
+            console.log(chalk.dim(`\nAcked ${acked}.`));
+    }
+}
 async function runDmInbox(opts) {
     try {
         const token = await ensureCognitoToken();
+        const agentUid = agentCallerUid(token);
+        if (agentUid) {
+            await runAgentInbox(token, agentUid, opts);
+            return;
+        }
         const query = {};
         if (opts.limit)
             query.limit = opts.limit;
@@ -841,6 +917,10 @@ async function runDmThread(identifier, opts) {
         if (opts.limit)
             query.limit = opts.limit;
         const token = await ensureCognitoToken();
+        if (agentCallerUid(token)) {
+            console.error(chalk.yellow(AGENT_THREAD_UNAVAILABLE));
+            process.exit(1);
+        }
         const res = await vaultApiFetch({
             token,
             path: "/v1/notify/thread",