@indigoai-us/hq-cli 5.69.0 → 5.70.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [5.70.0]
+
+### Added
+
+- **Read DMs from the CLI.** `hq dm` gained a receive side, wired to the notify
+  read endpoints that already back the HQ Sync menubar:
+  - `hq dm inbox` — list your incoming direct messages, with `--unread`,
+    `--limit`, `--json`, and `--mark-read`.
+  - `hq dm thread <person>` (alias `read`) — the two-way 1:1 conversation with a
+    person by email, personUid, or agentUid, read oldest-first. Marks their
+    messages read unless `--no-ack`. Reading by email uses the notify thread
+    endpoint's new `withEmail` resolution (requires the matching hq-pro deploy).
+  - `hq dm channel <name|#name|id>` (alias `history`) — channel and group-DM
+    message history, with `--mark-read` to advance your read cursor.
+- **`hq channels` now shows each group DM's channel id**, so unnamed group DMs
+  are addressable for reading with `hq dm channel <id>`.
+
 ## [5.69.0]
 
 ### Added

package/dist/commands/channels.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="891a3265-c9ff-53d8-8a3c-2a964f5a74b6")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fe48059a-56b5-5f50-8ebf-b5fbbe1aa432")}catch(e){}}();
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
@@ -18,7 +18,10 @@ export function describeChannel(c) {
         const who = names.length > 0
             ? names.join(", ")
             : `${c.memberCount ?? "?"}-person group`;
-        return `${who}  ${chalk.dim("(group DM)")}`;
+        // Group DMs are unnamed, so their channel id is the only way to address them
+        // for reading (`hq dm channel <id>`). Surface it so it can be copied.
+        const readHint = chalk.dim(`— hq dm channel ${c.channelId}`);
+        return `${who}  ${chalk.dim("(group DM)")}  ${readHint}`;
     }
     const slug = c.slug ?? (c.name ? channelSlug(c.name) : "");
     const scopeTag = c.scope ? chalk.dim(`(${c.scope})`) : "";
@@ -75,4 +78,4 @@ export function registerChannelsCommand(program) {
     });
 }
 //# sourceMappingURL=channels.js.map
-//# debugId=891a3265-c9ff-53d8-8a3c-2a964f5a74b6
+//# debugId=fe48059a-56b5-5f50-8ebf-b5fbbe1aa432

package/dist/commands/dm.d.ts

@@ -119,5 +119,81 @@ export declare function buildConnectionActionBody(identifier: string, matched: C
 } | {
     withEmail: string;
 };
+/** One incoming DM as returned by GET /v1/notify/inbox. */
+export interface DmInboxEvent {
+    eventId: string;
+    fromPersonUid?: string;
+    fromEmail?: string;
+    fromDisplayName?: string;
+    body: string;
+    createdAt: string;
+    details?: string;
+    prompt?: string;
+    acknowledgedAt?: string;
+}
+/** One message in a 1:1 thread as returned by GET /v1/notify/thread. */
+export interface DmThreadMessage {
+    eventId: string;
+    fromPersonUid?: string;
+    fromEmail?: string;
+    fromDisplayName?: string;
+    body: string;
+    createdAt: string;
+    direction: "in" | "out";
+    details?: string;
+    prompt?: string;
+}
+/** One channel/group message from GET /v1/notify/channels/{id}/messages. */
+export interface ChannelMessageItem {
+    eventId?: string;
+    messageId?: string;
+    fromPersonUid?: string;
+    fromEmail?: string;
+    fromDisplayName?: string;
+    body: string;
+    createdAt: string;
+}
+/**
+ * Human label for a message sender — display name, else email, else uid. Pure →
+ * unit-testable.
+ */
+export declare function senderLabel(m: {
+    fromDisplayName?: string;
+    fromEmail?: string;
+    fromPersonUid?: string;
+}): string;
+/**
+ * Render an ISO timestamp as a compact relative age ("3m ago", "2h ago",
+ * "5d ago"), falling back to a YYYY-MM-DD date for anything older than a week or
+ * an unparseable input. `nowMs` is injected so the formatting is unit-testable.
+ * Pure.
+ */
+export declare function formatRelativeTime(iso: string, nowMs: number): string;
+/** A DM is unread until the recipient acks it. Pure. */
+export declare function isUnread(e: {
+    acknowledgedAt?: string;
+}): boolean;
+/** Event ids of the unread messages in a fetched inbox page. Pure. */
+export declare function unreadEventIds(events: DmInboxEvent[]): string[];
+/** Keep only the unread messages. Pure. */
+export declare function filterUnread(events: DmInboxEvent[]): DmInboxEvent[];
+/**
+ * Collapse a message body to a single trimmed line for list rendering, capped
+ * so one row stays readable. Pure.
+ */
+export declare function firstLine(body: string, max?: number): string;
+/**
+ * Turn a person identifier into the query the thread endpoint expects. An email
+ * rides `withEmail` (server resolves it); a prs_/agt_ uid rides `withPersonUid`.
+ * A bare name is rejected — resolve it first with `hq people resolve`. Pure →
+ * unit-testable. Throws with a user-facing message on an invalid identifier.
+ */
+export declare function buildThreadQuery(identifier: string): Record<string, string>;
+/** Render one inbox row (marker · age · sender · first line of body). */
+export declare function formatInboxEvent(e: DmInboxEvent, nowMs: number): string;
+/** Render one 1:1 thread line, tagged by direction. */
+export declare function formatThreadMessage(m: DmThreadMessage, nowMs: number): string;
+/** Render one channel/group message line. */
+export declare function formatChannelMessage(m: ChannelMessageItem, nowMs: number): string;
 export declare function registerDmCommand(program: Command): void;
 //# sourceMappingURL=dm.d.ts.map

package/dist/commands/dm.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e95f345b-0e15-52b3-a851-fc97da935a99")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8ba6c13e-f0d4-58c7-a62e-eede4fb7873f")}catch(e){}}();
 import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -497,10 +497,294 @@ async function runDmRequests() {
         process.exit(1);
     }
 }
+/**
+ * Human label for a message sender — display name, else email, else uid. Pure →
+ * unit-testable.
+ */
+export function senderLabel(m) {
+    return (m.fromDisplayName?.trim() ||
+        m.fromEmail?.trim() ||
+        m.fromPersonUid?.trim() ||
+        "unknown");
+}
+/**
+ * Render an ISO timestamp as a compact relative age ("3m ago", "2h ago",
+ * "5d ago"), falling back to a YYYY-MM-DD date for anything older than a week or
+ * an unparseable input. `nowMs` is injected so the formatting is unit-testable.
+ * Pure.
+ */
+export function formatRelativeTime(iso, nowMs) {
+    const t = new Date(iso).getTime();
+    if (isNaN(t))
+        return iso;
+    const diff = nowMs - t;
+    if (diff < 60_000)
+        return "just now";
+    const mins = Math.floor(diff / 60_000);
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 7)
+        return `${days}d ago`;
+    return new Date(t).toISOString().slice(0, 10);
+}
+/** A DM is unread until the recipient acks it. Pure. */
+export function isUnread(e) {
+    return !e.acknowledgedAt;
+}
+/** Event ids of the unread messages in a fetched inbox page. Pure. */
+export function unreadEventIds(events) {
+    return events
+        .filter(isUnread)
+        .map((e) => e.eventId)
+        .filter((id) => typeof id === "string" && id.length > 0);
+}
+/** Keep only the unread messages. Pure. */
+export function filterUnread(events) {
+    return events.filter(isUnread);
+}
+/**
+ * Collapse a message body to a single trimmed line for list rendering, capped
+ * so one row stays readable. Pure.
+ */
+export function firstLine(body, max = 240) {
+    const oneLine = (body ?? "").replace(/\s+/g, " ").trim();
+    if (oneLine.length <= max)
+        return oneLine;
+    return oneLine.slice(0, max - 1) + "…";
+}
+/**
+ * Turn a person identifier into the query the thread endpoint expects. An email
+ * rides `withEmail` (server resolves it); a prs_/agt_ uid rides `withPersonUid`.
+ * A bare name is rejected — resolve it first with `hq people resolve`. Pure →
+ * unit-testable. Throws with a user-facing message on an invalid identifier.
+ */
+export function buildThreadQuery(identifier) {
+    const rcpt = detectRecipient(identifier);
+    if (!rcpt) {
+        throw new Error(`Invalid person '${identifier}': pass an email or a personUid/agentUid (prs_… / agt_…). Resolve a name first with \`hq people resolve\`.`);
+    }
+    if (rcpt.toEmail)
+        return { withEmail: rcpt.toEmail };
+    return { withPersonUid: rcpt.toPersonUid };
+}
+/** Render one inbox row (marker · age · sender · first line of body). */
+export function formatInboxEvent(e, nowMs) {
+    const marker = isUnread(e) ? chalk.cyan("●") : " ";
+    const when = chalk.dim(formatRelativeTime(e.createdAt, nowMs));
+    const who = chalk.bold(senderLabel(e));
+    const email = e.fromEmail && e.fromDisplayName ? chalk.dim(` <${e.fromEmail}>`) : "";
+    return `${marker} ${when}  ${who}${email}\n    ${firstLine(e.body)}`;
+}
+/** Render one 1:1 thread line, tagged by direction. */
+export function formatThreadMessage(m, nowMs) {
+    const arrow = m.direction === "out" ? chalk.dim("→") : chalk.cyan("←");
+    const who = m.direction === "out" ? "you" : senderLabel(m);
+    const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
+    return `${arrow} ${chalk.bold(who)} ${when}\n    ${firstLine(m.body)}`;
+}
+/** Render one channel/group message line. */
+export function formatChannelMessage(m, nowMs) {
+    const who = chalk.bold(senderLabel(m));
+    const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
+    return `${who} ${when}\n    ${firstLine(m.body)}`;
+}
+/** POST /v1/notify/inbox/ack — idempotently mark messages read. */
+async function ackEvents(token, eventIds) {
+    if (eventIds.length === 0)
+        return;
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/notify/inbox/ack",
+        method: "POST",
+        body: { eventIds },
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        throw new Error(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText));
+    }
+}
+async function runDmInbox(opts) {
+    try {
+        const token = await ensureCognitoToken();
+        const query = {};
+        if (opts.limit)
+            query.limit = opts.limit;
+        const res = await vaultApiFetch({ token, path: "/v1/notify/inbox", query });
+        if (!res.ok) {
+            const err = (await res.json().catch(() => ({})));
+            console.error(chalk.red(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText)));
+            process.exit(1);
+        }
+        const data = (await res.json());
+        const all = data.events ?? [];
+        const shown = opts.unread ? filterUnread(all) : all;
+        if (opts.json) {
+            console.log(JSON.stringify(shown, null, 2));
+        }
+        else if (shown.length === 0) {
+            console.log(chalk.dim(opts.unread ? "No unread messages." : "No messages yet."));
+        }
+        else {
+            const unreadCount = filterUnread(all).length;
+            const suffix = unreadCount > 0 ? ` (${unreadCount} unread)` : "";
+            console.log(chalk.green(`${shown.length} message${shown.length === 1 ? "" : "s"}${suffix}:`));
+            const now = Date.now();
+            for (const e of shown)
+                console.log(`\n${formatInboxEvent(e, now)}`);
+            if (data.nextCursor) {
+                console.log(chalk.dim("\nMore messages available — raise --limit to see them."));
+            }
+        }
+        // Ack every unread message on the fetched page (not just the filtered view).
+        if (opts.markRead) {
+            const ids = unreadEventIds(all);
+            await ackEvents(token, ids);
+            if (!opts.json && ids.length > 0) {
+                console.log(chalk.dim(`\nMarked ${ids.length} read.`));
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+async function runDmThread(identifier, opts) {
+    try {
+        const query = buildThreadQuery(identifier);
+        if (opts.limit)
+            query.limit = opts.limit;
+        const token = await ensureCognitoToken();
+        const res = await vaultApiFetch({
+            token,
+            path: "/v1/notify/thread",
+            query,
+        });
+        if (!res.ok) {
+            const err = (await res.json().catch(() => ({})));
+            console.error(chalk.red(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText)));
+            process.exit(1);
+        }
+        const data = (await res.json());
+        const messages = data.messages ?? [];
+        // The server returns newest-first; read a conversation oldest-first.
+        const ordered = [...messages].reverse();
+        if (opts.json) {
+            console.log(JSON.stringify(ordered, null, 2));
+        }
+        else if (ordered.length === 0) {
+            console.log(chalk.dim(`No messages with ${identifier} yet.`));
+        }
+        else {
+            console.log(chalk.green(`${ordered.length} message${ordered.length === 1 ? "" : "s"} with ${identifier}:`));
+            const now = Date.now();
+            for (const m of ordered)
+                console.log(`\n${formatThreadMessage(m, now)}`);
+        }
+        // Mark the incoming messages read unless the caller opted out. Best-effort:
+        // a read is a side effect, not the point of the command, so an ack failure
+        // is surfaced but does not fail the read.
+        if (opts.ack !== false) {
+            const inIds = messages
+                .filter((m) => m.direction === "in")
+                .map((m) => m.eventId)
+                .filter((id) => typeof id === "string" && id.length > 0);
+            try {
+                await ackEvents(token, inIds);
+            }
+            catch (ackErr) {
+                console.error(chalk.dim(`(could not mark read: ${ackErr instanceof Error ? ackErr.message : String(ackErr)})`));
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+/**
+ * Resolve a `hq dm channel <target>` argument to a channelId. Accepts a channel
+ * name (bare or `#name`) resolved against the caller's channels, or a raw
+ * channelId (the only way to address an unnamed group DM — copy it from
+ * `hq channels`). Throws a user-facing message when nothing matches or a name is
+ * ambiguous.
+ */
+async function resolveChannelId(token, target) {
+    const raw = target.trim().replace(/^#/, "");
+    if (!raw)
+        throw new Error("A channel name or id is required.");
+    const channels = await fetchChannels(token);
+    const named = matchChannelsByName(channels, raw);
+    if (named.length === 1)
+        return named[0].channelId;
+    if (named.length > 1) {
+        throw new Error(`'${raw}' matches ${named.length} channels — pass the channel id instead (see \`hq channels\`).`);
+    }
+    const byId = channels.find((c) => c.channelId === raw);
+    if (byId)
+        return byId.channelId;
+    throw new Error(`No channel named or with id '${raw}' — run \`hq channels\` to see yours.`);
+}
+async function runDmChannel(target, opts) {
+    try {
+        const token = await ensureCognitoToken();
+        const channelId = await resolveChannelId(token, target);
+        const query = {};
+        if (opts.limit)
+            query.limit = opts.limit;
+        const res = await vaultApiFetch({
+            token,
+            path: `/v1/notify/channels/${encodeURIComponent(channelId)}/messages`,
+            query,
+        });
+        if (!res.ok) {
+            const err = (await res.json().catch(() => ({})));
+            console.error(chalk.red(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText)));
+            process.exit(1);
+        }
+        const data = (await res.json());
+        const messages = data.messages ?? [];
+        const ordered = [...messages].reverse(); // oldest-first for reading
+        if (opts.json) {
+            console.log(JSON.stringify(ordered, null, 2));
+        }
+        else if (ordered.length === 0) {
+            console.log(chalk.dim("No messages in this channel yet."));
+        }
+        else {
+            console.log(chalk.green(`${ordered.length} message${ordered.length === 1 ? "" : "s"}:`));
+            const now = Date.now();
+            for (const m of ordered)
+                console.log(`\n${formatChannelMessage(m, now)}`);
+        }
+        if (opts.markRead) {
+            // messages are newest-first from the server; advance the read cursor to
+            // the newest one we saw.
+            const newest = messages[0]?.createdAt;
+            const readRes = await vaultApiFetch({
+                token,
+                path: `/v1/notify/channels/${encodeURIComponent(channelId)}/read`,
+                method: "POST",
+                body: newest ? { lastReadAt: newest } : {},
+            });
+            if (!opts.json && readRes.ok) {
+                console.log(chalk.dim("\nMarked read."));
+            }
+        }
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
 export function registerDmCommand(program) {
     const dm = program
         .command("dm")
-        .description("Send a direct message and manage connection requests.");
+        .description("Send and read direct messages, and manage connection requests.");
     dm
         .command("send [recipient] [message]", { isDefault: true, hidden: true })
         .description('Send a direct message. RECIPIENT can be a person (email, personUid, or agentUid), a GROUP DM (comma-separated: "a@x.com,b@y.com"), or one of your DM CHANNELS by name — bare (hq dm vyg-dev "hi"), hash form (hq dm "#vyg-dev" "hi"), or via --channel (hq dm --channel vyg-dev "hi"). A person receives a DM as an HQ Sync notification; an agent receives it in its durable box inbox. If you aren\'t connected yet, it sends a connection request that holds your message. See your channels with `hq channels`.')
@@ -514,6 +798,36 @@ export function registerDmCommand(program) {
         .action(async (recipient, message, opts) => {
         await runDmSend(recipient, message, opts);
     });
+    dm
+        .command("inbox")
+        .description("List your recent incoming direct messages.")
+        .option("--limit <n>", "Max messages to fetch (server-capped)")
+        .option("--unread", "Show only unread messages")
+        .option("--mark-read", "Mark the fetched messages as read after listing")
+        .option("--json", "Output raw JSON instead of a list")
+        .action(async (opts) => {
+        await runDmInbox(opts);
+    });
+    dm
+        .command("thread <person>")
+        .alias("read")
+        .description("Show your two-way conversation with a person (email, personUid, or agentUid). Reads oldest-first and marks their messages read unless --no-ack.")
+        .option("--limit <n>", "Max messages to fetch (server-capped)")
+        .option("--no-ack", "Do not mark the incoming messages as read")
+        .option("--json", "Output raw JSON instead of a transcript")
+        .action(async (person, opts) => {
+        await runDmThread(person, opts);
+    });
+    dm
+        .command("channel <target>")
+        .alias("history")
+        .description("Show recent messages in a DM channel or group DM — by name, #name, or a channel id from `hq channels`.")
+        .option("--limit <n>", "Max messages to fetch (server-capped)")
+        .option("--mark-read", "Advance your read marker to the newest message")
+        .option("--json", "Output raw JSON instead of a transcript")
+        .action(async (target, opts) => {
+        await runDmChannel(target, opts);
+    });
     dm
         .command("requests")
         .description("List your pending incoming connection requests.")
@@ -540,4 +854,4 @@ export function registerDmCommand(program) {
     });
 }
 //# sourceMappingURL=dm.js.map
-//# debugId=e95f345b-0e15-52b3-a851-fc97da935a99
+//# debugId=8ba6c13e-f0d4-58c7-a62e-eede4fb7873f

package/package.json

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

package/src/commands/channels.ts

@@ -19,7 +19,10 @@ export function describeChannel(c: ChannelSummary): string {
       names.length > 0
         ? names.join(", ")
         : `${c.memberCount ?? "?"}-person group`;
-    return `${who}  ${chalk.dim("(group DM)")}`;
+    // Group DMs are unnamed, so their channel id is the only way to address them
+    // for reading (`hq dm channel <id>`). Surface it so it can be copied.
+    const readHint = chalk.dim(`— hq dm channel ${c.channelId}`);
+    return `${who}  ${chalk.dim("(group DM)")}  ${readHint}`;
   }
   const slug = c.slug ?? (c.name ? channelSlug(c.name) : "");
   const scopeTag = c.scope ? chalk.dim(`(${c.scope})`) : "";

package/src/commands/dm.test.ts

@@ -18,6 +18,7 @@ vi.mock("../utils/cognito-session.js", async (importOriginal) => {
 });
 
 import { Command } from "commander";
+import chalk from "chalk";
 import {
   detectRecipient,
   parseDuration,
@@ -29,8 +30,18 @@ import {
   channelSlug,
   parseChannelName,
   matchChannelsByName,
+  senderLabel,
+  formatRelativeTime,
+  isUnread,
+  unreadEventIds,
+  filterUnread,
+  firstLine,
+  buildThreadQuery,
+  formatInboxEvent,
+  formatThreadMessage,
   type ConnectionRequest,
   type ChannelSummary,
+  type DmInboxEvent,
 } from "./dm.js";
 
 describe("parseGroupRecipients", () => {
@@ -262,6 +273,127 @@ describe("buildConnectionActionBody", () => {
 // Action handlers (HTTP/auth mocked)
 // ---------------------------------------------------------------------------
 
+describe("senderLabel", () => {
+  it("prefers display name, then email, then uid", () => {
+    expect(
+      senderLabel({ fromDisplayName: "Jonathan", fromEmail: "j@x.com", fromPersonUid: "prs_1" }),
+    ).toBe("Jonathan");
+    expect(senderLabel({ fromEmail: "j@x.com", fromPersonUid: "prs_1" })).toBe("j@x.com");
+    expect(senderLabel({ fromPersonUid: "prs_1" })).toBe("prs_1");
+    expect(senderLabel({})).toBe("unknown");
+  });
+});
+
+describe("formatRelativeTime", () => {
+  const now = Date.parse("2026-07-16T12:00:00.000Z");
+  it("renders sub-minute as 'just now'", () => {
+    expect(formatRelativeTime("2026-07-16T11:59:30.000Z", now)).toBe("just now");
+  });
+  it("renders minutes, hours, and days", () => {
+    expect(formatRelativeTime("2026-07-16T11:57:00.000Z", now)).toBe("3m ago");
+    expect(formatRelativeTime("2026-07-16T10:00:00.000Z", now)).toBe("2h ago");
+    expect(formatRelativeTime("2026-07-11T12:00:00.000Z", now)).toBe("5d ago");
+  });
+  it("falls back to a date for anything older than a week", () => {
+    expect(formatRelativeTime("2026-06-01T09:00:00.000Z", now)).toBe("2026-06-01");
+  });
+  it("echoes an unparseable input", () => {
+    expect(formatRelativeTime("not-a-date", now)).toBe("not-a-date");
+  });
+});
+
+describe("isUnread / unreadEventIds / filterUnread", () => {
+  const events: DmInboxEvent[] = [
+    { eventId: "a", body: "x", createdAt: "2026-07-16T11:00:00.000Z" },
+    {
+      eventId: "b",
+      body: "y",
+      createdAt: "2026-07-16T11:30:00.000Z",
+      acknowledgedAt: "2026-07-16T11:31:00.000Z",
+    },
+  ];
+  it("treats a message with no acknowledgedAt as unread", () => {
+    expect(isUnread(events[0])).toBe(true);
+    expect(isUnread(events[1])).toBe(false);
+  });
+  it("collects unread event ids", () => {
+    expect(unreadEventIds(events)).toEqual(["a"]);
+  });
+  it("filters to unread only", () => {
+    expect(filterUnread(events).map((e) => e.eventId)).toEqual(["a"]);
+  });
+});
+
+describe("firstLine", () => {
+  it("collapses whitespace to a single trimmed line", () => {
+    expect(firstLine("  hello\n  world  \t there ")).toBe("hello world there");
+  });
+  it("truncates with an ellipsis past the cap", () => {
+    const out = firstLine("abcdefghij", 5);
+    expect(out).toBe("abcd…");
+    expect(out.length).toBe(5);
+  });
+});
+
+describe("buildThreadQuery", () => {
+  it("routes an email through withEmail (lowercased)", () => {
+    expect(buildThreadQuery("Jonathan@GetIndigo.ai")).toEqual({
+      withEmail: "jonathan@getindigo.ai",
+    });
+  });
+  it("routes a personUid / agentUid through withPersonUid", () => {
+    expect(buildThreadQuery("prs_123")).toEqual({ withPersonUid: "prs_123" });
+    expect(buildThreadQuery("agt_123")).toEqual({ withPersonUid: "agt_123" });
+  });
+  it("rejects a bare name", () => {
+    expect(() => buildThreadQuery("Jonathan")).toThrow(/Resolve a name first/);
+  });
+});
+
+describe("format helpers (rendering)", () => {
+  beforeEach(() => {
+    chalk.level = 0; // plain text so assertions read the rendered content
+  });
+  const now = Date.parse("2026-07-16T12:00:00.000Z");
+  it("marks an unread inbox row with a bullet and shows the sender + body", () => {
+    const row = formatInboxEvent(
+      {
+        eventId: "e1",
+        fromDisplayName: "Jonathan Bach",
+        fromEmail: "jonathan@getindigo.ai",
+        body: "grp_jb_agent is created",
+        createdAt: "2026-07-16T11:57:00.000Z",
+      },
+      now,
+    );
+    expect(row).toContain("●");
+    expect(row).toContain("Jonathan Bach");
+    expect(row).toContain("<jonathan@getindigo.ai>");
+    expect(row).toContain("3m ago");
+    expect(row).toContain("grp_jb_agent is created");
+  });
+  it("tags thread direction: outgoing as 'you', incoming by sender", () => {
+    const out = formatThreadMessage(
+      { eventId: "o", body: "hey", createdAt: "2026-07-16T11:00:00.000Z", direction: "out" },
+      now,
+    );
+    expect(out).toContain("→");
+    expect(out).toContain("you");
+    const inbound = formatThreadMessage(
+      {
+        eventId: "i",
+        fromDisplayName: "Jonathan",
+        body: "thanks",
+        createdAt: "2026-07-16T11:30:00.000Z",
+        direction: "in",
+      },
+      now,
+    );
+    expect(inbound).toContain("←");
+    expect(inbound).toContain("Jonathan");
+  });
+});
+
 function jsonResponse(status: number, body: unknown): Response {
   return new Response(JSON.stringify(body), {
     status,
@@ -480,4 +612,137 @@ describe("dm command actions", () => {
     expect(body).toEqual({ withEmail: "spammer@example.com" });
     expect(logged()).toMatch(/Blocked — spammer@example\.com\./);
   });
+
+  // ---- receive side: inbox / thread / channel ----
+
+  it("inbox: lists incoming messages from GET /v1/notify/inbox", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        events: [
+          {
+            eventId: "e1",
+            fromDisplayName: "Jonathan Bach",
+            fromEmail: "jonathan@getindigo.ai",
+            body: "grp_jb_agent is created",
+            createdAt: "2026-07-16T11:57:00.000Z",
+          },
+        ],
+      }),
+    );
+    await program.parseAsync(["dm", "inbox"], { from: "user" });
+    expect(String(fetchSpy.mock.calls[0][0])).toContain("/v1/notify/inbox");
+    expect(logged()).toContain("Jonathan Bach");
+    expect(logged()).toContain("grp_jb_agent is created");
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("inbox --unread --mark-read: acks only the unread ids", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          events: [
+            { eventId: "u1", body: "new", createdAt: "2026-07-16T11:00:00.000Z" },
+            {
+              eventId: "r1",
+              body: "old",
+              createdAt: "2026-07-16T10:00:00.000Z",
+              acknowledgedAt: "2026-07-16T10:01:00.000Z",
+            },
+          ],
+        }),
+      )
+      .mockResolvedValueOnce(jsonResponse(200, { acknowledged: 1 }));
+    await program.parseAsync(["dm", "inbox", "--unread", "--mark-read"], {
+      from: "user",
+    });
+    const ackCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/v1/notify/inbox/ack"),
+    );
+    expect(ackCall).toBeTruthy();
+    expect(JSON.parse((ackCall![1]?.body as string) ?? "{}")).toEqual({
+      eventIds: ["u1"],
+    });
+  });
+
+  it("thread <email>: reads via withEmail and acks incoming messages", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          messages: [
+            {
+              eventId: "in1",
+              fromDisplayName: "Jonathan",
+              body: "thanks!",
+              createdAt: "2026-07-16T11:30:00.000Z",
+              direction: "in",
+            },
+            {
+              eventId: "out1",
+              body: "done",
+              createdAt: "2026-07-16T11:00:00.000Z",
+              direction: "out",
+            },
+          ],
+        }),
+      )
+      .mockResolvedValueOnce(jsonResponse(200, { acknowledged: 1 }));
+    await program.parseAsync(["dm", "thread", "jonathan@getindigo.ai"], {
+      from: "user",
+    });
+    expect(String(fetchSpy.mock.calls[0][0])).toContain("/v1/notify/thread");
+    expect(String(fetchSpy.mock.calls[0][0])).toContain("withEmail=");
+    const ackCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/v1/notify/inbox/ack"),
+    );
+    expect(ackCall).toBeTruthy();
+    expect(JSON.parse((ackCall![1]?.body as string) ?? "{}")).toEqual({
+      eventIds: ["in1"],
+    });
+    expect(logged()).toContain("thanks!");
+  });
+
+  it("thread --no-ack: reads without marking anything read", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        messages: [
+          {
+            eventId: "in1",
+            body: "hi",
+            createdAt: "2026-07-16T11:30:00.000Z",
+            direction: "in",
+          },
+        ],
+      }),
+    );
+    await program.parseAsync(["dm", "thread", "prs_x", "--no-ack"], {
+      from: "user",
+    });
+    expect(
+      fetchSpy.mock.calls.some((c) => String(c[0]).includes("/inbox/ack")),
+    ).toBe(false);
+    expect(String(fetchSpy.mock.calls[0][0])).toContain("withPersonUid=prs_x");
+  });
+
+  it("channel <name>: resolves the channel then reads its messages", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(200, channelsPayload))
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          messages: [
+            {
+              eventId: "m1",
+              fromDisplayName: "Stefan",
+              body: "ship it",
+              createdAt: "2026-07-16T11:00:00.000Z",
+            },
+          ],
+        }),
+      );
+    await program.parseAsync(["dm", "channel", "vyg-dev"], { from: "user" });
+    expect(String(fetchSpy.mock.calls[0][0])).toContain("/v1/notify/channels");
+    expect(String(fetchSpy.mock.calls[1][0])).toContain(
+      "/v1/notify/channels/chn_v/messages",
+    );
+    expect(logged()).toContain("ship it");
+  });
 });

package/src/commands/dm.ts

@@ -702,11 +702,422 @@ async function runDmRequests(): Promise<void> {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Receive side — reading DMs (inbox, 1:1 thread, channel/group history).
+// The backend read endpoints (GET /v1/notify/inbox, GET /v1/notify/thread,
+// GET /v1/notify/channels/{id}/messages) already back the HQ Sync menubar; the
+// commands below expose the same reads from the CLI.
+// ---------------------------------------------------------------------------
+
+/** One incoming DM as returned by GET /v1/notify/inbox. */
+export interface DmInboxEvent {
+  eventId: string;
+  fromPersonUid?: string;
+  fromEmail?: string;
+  fromDisplayName?: string;
+  body: string;
+  createdAt: string;
+  details?: string;
+  prompt?: string;
+  acknowledgedAt?: string;
+}
+
+/** One message in a 1:1 thread as returned by GET /v1/notify/thread. */
+export interface DmThreadMessage {
+  eventId: string;
+  fromPersonUid?: string;
+  fromEmail?: string;
+  fromDisplayName?: string;
+  body: string;
+  createdAt: string;
+  direction: "in" | "out";
+  details?: string;
+  prompt?: string;
+}
+
+/** One channel/group message from GET /v1/notify/channels/{id}/messages. */
+export interface ChannelMessageItem {
+  eventId?: string;
+  messageId?: string;
+  fromPersonUid?: string;
+  fromEmail?: string;
+  fromDisplayName?: string;
+  body: string;
+  createdAt: string;
+}
+
+/**
+ * Human label for a message sender — display name, else email, else uid. Pure →
+ * unit-testable.
+ */
+export function senderLabel(m: {
+  fromDisplayName?: string;
+  fromEmail?: string;
+  fromPersonUid?: string;
+}): string {
+  return (
+    m.fromDisplayName?.trim() ||
+    m.fromEmail?.trim() ||
+    m.fromPersonUid?.trim() ||
+    "unknown"
+  );
+}
+
+/**
+ * Render an ISO timestamp as a compact relative age ("3m ago", "2h ago",
+ * "5d ago"), falling back to a YYYY-MM-DD date for anything older than a week or
+ * an unparseable input. `nowMs` is injected so the formatting is unit-testable.
+ * Pure.
+ */
+export function formatRelativeTime(iso: string, nowMs: number): string {
+  const t = new Date(iso).getTime();
+  if (isNaN(t)) return iso;
+  const diff = nowMs - t;
+  if (diff < 60_000) return "just now";
+  const mins = Math.floor(diff / 60_000);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  return new Date(t).toISOString().slice(0, 10);
+}
+
+/** A DM is unread until the recipient acks it. Pure. */
+export function isUnread(e: { acknowledgedAt?: string }): boolean {
+  return !e.acknowledgedAt;
+}
+
+/** Event ids of the unread messages in a fetched inbox page. Pure. */
+export function unreadEventIds(events: DmInboxEvent[]): string[] {
+  return events
+    .filter(isUnread)
+    .map((e) => e.eventId)
+    .filter((id): id is string => typeof id === "string" && id.length > 0);
+}
+
+/** Keep only the unread messages. Pure. */
+export function filterUnread(events: DmInboxEvent[]): DmInboxEvent[] {
+  return events.filter(isUnread);
+}
+
+/**
+ * Collapse a message body to a single trimmed line for list rendering, capped
+ * so one row stays readable. Pure.
+ */
+export function firstLine(body: string, max = 240): string {
+  const oneLine = (body ?? "").replace(/\s+/g, " ").trim();
+  if (oneLine.length <= max) return oneLine;
+  return oneLine.slice(0, max - 1) + "…";
+}
+
+/**
+ * Turn a person identifier into the query the thread endpoint expects. An email
+ * rides `withEmail` (server resolves it); a prs_/agt_ uid rides `withPersonUid`.
+ * A bare name is rejected — resolve it first with `hq people resolve`. Pure →
+ * unit-testable. Throws with a user-facing message on an invalid identifier.
+ */
+export function buildThreadQuery(identifier: string): Record<string, string> {
+  const rcpt = detectRecipient(identifier);
+  if (!rcpt) {
+    throw new Error(
+      `Invalid person '${identifier}': pass an email or a personUid/agentUid (prs_… / agt_…). Resolve a name first with \`hq people resolve\`.`,
+    );
+  }
+  if (rcpt.toEmail) return { withEmail: rcpt.toEmail };
+  return { withPersonUid: rcpt.toPersonUid! };
+}
+
+/** Render one inbox row (marker · age · sender · first line of body). */
+export function formatInboxEvent(e: DmInboxEvent, nowMs: number): string {
+  const marker = isUnread(e) ? chalk.cyan("●") : " ";
+  const when = chalk.dim(formatRelativeTime(e.createdAt, nowMs));
+  const who = chalk.bold(senderLabel(e));
+  const email =
+    e.fromEmail && e.fromDisplayName ? chalk.dim(` <${e.fromEmail}>`) : "";
+  return `${marker} ${when}  ${who}${email}\n    ${firstLine(e.body)}`;
+}
+
+/** Render one 1:1 thread line, tagged by direction. */
+export function formatThreadMessage(m: DmThreadMessage, nowMs: number): string {
+  const arrow = m.direction === "out" ? chalk.dim("→") : chalk.cyan("←");
+  const who = m.direction === "out" ? "you" : senderLabel(m);
+  const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
+  return `${arrow} ${chalk.bold(who)} ${when}\n    ${firstLine(m.body)}`;
+}
+
+/** Render one channel/group message line. */
+export function formatChannelMessage(
+  m: ChannelMessageItem,
+  nowMs: number,
+): string {
+  const who = chalk.bold(senderLabel(m));
+  const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
+  return `${who} ${when}\n    ${firstLine(m.body)}`;
+}
+
+/** POST /v1/notify/inbox/ack — idempotently mark messages read. */
+async function ackEvents(token: string, eventIds: string[]): Promise<void> {
+  if (eventIds.length === 0) return;
+  const res = await vaultApiFetch({
+    token,
+    path: "/v1/notify/inbox/ack",
+    method: "POST",
+    body: { eventIds },
+  });
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throw new Error(
+      friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
+    );
+  }
+}
+
+interface DmInboxOpts {
+  limit?: string;
+  unread?: boolean;
+  markRead?: boolean;
+  json?: boolean;
+}
+
+async function runDmInbox(opts: DmInboxOpts): Promise<void> {
+  try {
+    const token = await ensureCognitoToken();
+    const query: Record<string, string> = {};
+    if (opts.limit) query.limit = opts.limit;
+    const res = await vaultApiFetch({ token, path: "/v1/notify/inbox", query });
+    if (!res.ok) {
+      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+      console.error(
+        chalk.red(
+          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
+        ),
+      );
+      process.exit(1);
+    }
+    const data = (await res.json()) as {
+      events?: DmInboxEvent[];
+      nextCursor?: string;
+    };
+    const all = data.events ?? [];
+    const shown = opts.unread ? filterUnread(all) : all;
+
+    if (opts.json) {
+      console.log(JSON.stringify(shown, null, 2));
+    } else if (shown.length === 0) {
+      console.log(
+        chalk.dim(opts.unread ? "No unread messages." : "No messages yet."),
+      );
+    } else {
+      const unreadCount = filterUnread(all).length;
+      const suffix = unreadCount > 0 ? ` (${unreadCount} unread)` : "";
+      console.log(
+        chalk.green(
+          `${shown.length} message${shown.length === 1 ? "" : "s"}${suffix}:`,
+        ),
+      );
+      const now = Date.now();
+      for (const e of shown) console.log(`\n${formatInboxEvent(e, now)}`);
+      if (data.nextCursor) {
+        console.log(
+          chalk.dim("\nMore messages available — raise --limit to see them."),
+        );
+      }
+    }
+
+    // Ack every unread message on the fetched page (not just the filtered view).
+    if (opts.markRead) {
+      const ids = unreadEventIds(all);
+      await ackEvents(token, ids);
+      if (!opts.json && ids.length > 0) {
+        console.log(chalk.dim(`\nMarked ${ids.length} read.`));
+      }
+    }
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
+interface DmThreadOpts {
+  limit?: string;
+  ack?: boolean;
+  json?: boolean;
+}
+
+async function runDmThread(
+  identifier: string,
+  opts: DmThreadOpts,
+): Promise<void> {
+  try {
+    const query = buildThreadQuery(identifier);
+    if (opts.limit) query.limit = opts.limit;
+    const token = await ensureCognitoToken();
+    const res = await vaultApiFetch({
+      token,
+      path: "/v1/notify/thread",
+      query,
+    });
+    if (!res.ok) {
+      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+      console.error(
+        chalk.red(
+          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
+        ),
+      );
+      process.exit(1);
+    }
+    const data = (await res.json()) as { messages?: DmThreadMessage[] };
+    const messages = data.messages ?? [];
+    // The server returns newest-first; read a conversation oldest-first.
+    const ordered = [...messages].reverse();
+
+    if (opts.json) {
+      console.log(JSON.stringify(ordered, null, 2));
+    } else if (ordered.length === 0) {
+      console.log(chalk.dim(`No messages with ${identifier} yet.`));
+    } else {
+      console.log(
+        chalk.green(
+          `${ordered.length} message${ordered.length === 1 ? "" : "s"} with ${identifier}:`,
+        ),
+      );
+      const now = Date.now();
+      for (const m of ordered) console.log(`\n${formatThreadMessage(m, now)}`);
+    }
+
+    // Mark the incoming messages read unless the caller opted out. Best-effort:
+    // a read is a side effect, not the point of the command, so an ack failure
+    // is surfaced but does not fail the read.
+    if (opts.ack !== false) {
+      const inIds = messages
+        .filter((m) => m.direction === "in")
+        .map((m) => m.eventId)
+        .filter((id): id is string => typeof id === "string" && id.length > 0);
+      try {
+        await ackEvents(token, inIds);
+      } catch (ackErr) {
+        console.error(
+          chalk.dim(
+            `(could not mark read: ${
+              ackErr instanceof Error ? ackErr.message : String(ackErr)
+            })`,
+          ),
+        );
+      }
+    }
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * Resolve a `hq dm channel <target>` argument to a channelId. Accepts a channel
+ * name (bare or `#name`) resolved against the caller's channels, or a raw
+ * channelId (the only way to address an unnamed group DM — copy it from
+ * `hq channels`). Throws a user-facing message when nothing matches or a name is
+ * ambiguous.
+ */
+async function resolveChannelId(token: string, target: string): Promise<string> {
+  const raw = target.trim().replace(/^#/, "");
+  if (!raw) throw new Error("A channel name or id is required.");
+  const channels = await fetchChannels(token);
+  const named = matchChannelsByName(channels, raw);
+  if (named.length === 1) return named[0].channelId;
+  if (named.length > 1) {
+    throw new Error(
+      `'${raw}' matches ${named.length} channels — pass the channel id instead (see \`hq channels\`).`,
+    );
+  }
+  const byId = channels.find((c) => c.channelId === raw);
+  if (byId) return byId.channelId;
+  throw new Error(
+    `No channel named or with id '${raw}' — run \`hq channels\` to see yours.`,
+  );
+}
+
+interface DmChannelOpts {
+  limit?: string;
+  markRead?: boolean;
+  json?: boolean;
+}
+
+async function runDmChannel(
+  target: string,
+  opts: DmChannelOpts,
+): Promise<void> {
+  try {
+    const token = await ensureCognitoToken();
+    const channelId = await resolveChannelId(token, target);
+    const query: Record<string, string> = {};
+    if (opts.limit) query.limit = opts.limit;
+    const res = await vaultApiFetch({
+      token,
+      path: `/v1/notify/channels/${encodeURIComponent(channelId)}/messages`,
+      query,
+    });
+    if (!res.ok) {
+      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
+      console.error(
+        chalk.red(
+          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
+        ),
+      );
+      process.exit(1);
+    }
+    const data = (await res.json()) as { messages?: ChannelMessageItem[] };
+    const messages = data.messages ?? [];
+    const ordered = [...messages].reverse(); // oldest-first for reading
+
+    if (opts.json) {
+      console.log(JSON.stringify(ordered, null, 2));
+    } else if (ordered.length === 0) {
+      console.log(chalk.dim("No messages in this channel yet."));
+    } else {
+      console.log(
+        chalk.green(
+          `${ordered.length} message${ordered.length === 1 ? "" : "s"}:`,
+        ),
+      );
+      const now = Date.now();
+      for (const m of ordered) console.log(`\n${formatChannelMessage(m, now)}`);
+    }
+
+    if (opts.markRead) {
+      // messages are newest-first from the server; advance the read cursor to
+      // the newest one we saw.
+      const newest = messages[0]?.createdAt;
+      const readRes = await vaultApiFetch({
+        token,
+        path: `/v1/notify/channels/${encodeURIComponent(channelId)}/read`,
+        method: "POST",
+        body: newest ? { lastReadAt: newest } : {},
+      });
+      if (!opts.json && readRes.ok) {
+        console.log(chalk.dim("\nMarked read."));
+      }
+    }
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
 export function registerDmCommand(program: Command): void {
   const dm = program
     .command("dm")
     .description(
-      "Send a direct message and manage connection requests.",
+      "Send and read direct messages, and manage connection requests.",
     );
 
   dm
@@ -746,6 +1157,43 @@ export function registerDmCommand(program: Command): void {
       },
     );
 
+  dm
+    .command("inbox")
+    .description("List your recent incoming direct messages.")
+    .option("--limit <n>", "Max messages to fetch (server-capped)")
+    .option("--unread", "Show only unread messages")
+    .option("--mark-read", "Mark the fetched messages as read after listing")
+    .option("--json", "Output raw JSON instead of a list")
+    .action(async (opts: DmInboxOpts) => {
+      await runDmInbox(opts);
+    });
+
+  dm
+    .command("thread <person>")
+    .alias("read")
+    .description(
+      "Show your two-way conversation with a person (email, personUid, or agentUid). Reads oldest-first and marks their messages read unless --no-ack.",
+    )
+    .option("--limit <n>", "Max messages to fetch (server-capped)")
+    .option("--no-ack", "Do not mark the incoming messages as read")
+    .option("--json", "Output raw JSON instead of a transcript")
+    .action(async (person: string, opts: DmThreadOpts) => {
+      await runDmThread(person, opts);
+    });
+
+  dm
+    .command("channel <target>")
+    .alias("history")
+    .description(
+      "Show recent messages in a DM channel or group DM — by name, #name, or a channel id from `hq channels`.",
+    )
+    .option("--limit <n>", "Max messages to fetch (server-capped)")
+    .option("--mark-read", "Advance your read marker to the newest message")
+    .option("--json", "Output raw JSON instead of a transcript")
+    .action(async (target: string, opts: DmChannelOpts) => {
+      await runDmChannel(target, opts);
+    });
+
   dm
     .command("requests")
     .description("List your pending incoming connection requests.")