@indigoai-us/hq-cli 5.36.1 → 5.36.2

package/dist/commands/dm.d.ts

@@ -37,5 +37,38 @@ export declare function buildDmBody(args: {
     inDelay?: string;
     now: number;
 }): DmSendBody;
+/** A pending incoming connection request, as returned by the backend. */
+export interface ConnectionRequest {
+    pairKey: string;
+    fromPersonUid: string;
+    fromDisplayName?: string;
+    fromEmail?: string;
+    message?: string;
+    createdAt?: string;
+}
+/**
+ * Resolve a connection request from a pending-requests list by a caller-supplied
+ * identifier (email, personUid, or pairKey). Pure → unit-testable.
+ *
+ * Matching is case-insensitive for emails. Returns the matched request, or null
+ * if no request matches.
+ */
+export declare function matchRequest(requests: ConnectionRequest[], identifier: string): ConnectionRequest | null;
+/**
+ * Build the POST body for an accept/decline/block action. Prefers a resolved
+ * pairKey (from a matched pending request); otherwise falls back to the
+ * recipient identifier the backend can resolve (`withPersonUid` for a prs_ UID,
+ * `toEmail`-style is not supported by the connections endpoints so we send
+ * `withEmail`). Pure → unit-testable.
+ *
+ * Throws Error with a user-facing message when the identifier can't be resolved.
+ */
+export declare function buildConnectionActionBody(identifier: string, matched: ConnectionRequest | null): {
+    pairKey: string;
+} | {
+    withPersonUid: string;
+} | {
+    withEmail: 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]="69d48194-d5ae-508e-b614-68f2066db6ee")}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]="19c5d8e0-ec0a-5b57-b3dc-e2209b60cf2f")}catch(e){}}();
 import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -89,10 +89,179 @@ function friendlyDmError(status, code, fallback) {
         return `Server error: ${fallback}`;
     return fallback;
 }
+/**
+ * Resolve a connection request from a pending-requests list by a caller-supplied
+ * identifier (email, personUid, or pairKey). Pure → unit-testable.
+ *
+ * Matching is case-insensitive for emails. Returns the matched request, or null
+ * if no request matches.
+ */
+export function matchRequest(requests, identifier) {
+    const id = identifier.trim();
+    const idLower = id.toLowerCase();
+    for (const r of requests) {
+        if (r.pairKey === id)
+            return r;
+        if (r.fromPersonUid === id)
+            return r;
+        if (r.fromEmail && r.fromEmail.toLowerCase() === idLower)
+            return r;
+    }
+    return null;
+}
+/**
+ * Build the POST body for an accept/decline/block action. Prefers a resolved
+ * pairKey (from a matched pending request); otherwise falls back to the
+ * recipient identifier the backend can resolve (`withPersonUid` for a prs_ UID,
+ * `toEmail`-style is not supported by the connections endpoints so we send
+ * `withEmail`). Pure → unit-testable.
+ *
+ * Throws Error with a user-facing message when the identifier can't be resolved.
+ */
+export function buildConnectionActionBody(identifier, matched) {
+    if (matched) {
+        return { pairKey: matched.pairKey };
+    }
+    const r = identifier.trim();
+    const rcpt = detectRecipient(r);
+    if (rcpt?.toPersonUid)
+        return { withPersonUid: rcpt.toPersonUid };
+    if (rcpt?.toEmail)
+        return { withEmail: rcpt.toEmail };
+    throw new Error(`Could not resolve '${identifier}' to a pending request — pass the requester's email, personUid, or the pairKey from \`hq dm requests\`.`);
+}
+const CONNECTION_ACTIONS = {
+    accept: { path: "accept", done: "Connection accepted" },
+    decline: { path: "decline", done: "Request declined" },
+    block: { path: "block", done: "Blocked" },
+};
+/** Fetch the caller's pending incoming connection requests. */
+async function fetchRequests(token) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/notify/connections/requests",
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        throw new Error(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText));
+    }
+    const data = (await res.json());
+    return data.requests ?? [];
+}
+async function runConnectionAction(action, identifier) {
+    try {
+        const token = await ensureCognitoToken();
+        // Resolve the pairKey from the caller's pending requests when possible so
+        // accept/decline/block work against a friendly email or personUid.
+        const requests = await fetchRequests(token).catch(() => []);
+        const matched = matchRequest(requests, identifier);
+        const body = buildConnectionActionBody(identifier, matched);
+        const res = await vaultApiFetch({
+            token,
+            path: `/v1/notify/connections/${CONNECTION_ACTIONS[action].path}`,
+            method: "POST",
+            body: body,
+        });
+        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 who = matched?.fromDisplayName ?? matched?.fromEmail ?? identifier;
+        console.log(chalk.green(`${CONNECTION_ACTIONS[action].done} — ${who}.`));
+        if (action === "accept" && matched?.message) {
+            console.log(chalk.dim("Their held message will now be delivered."));
+        }
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+async function runDmSend(recipient, message, opts) {
+    try {
+        // Resolve prompt/details from inline text or a file.
+        let prompt = opts.prompt;
+        if (opts.promptFile)
+            prompt = readFileSync(opts.promptFile, "utf8");
+        let details = opts.details;
+        if (opts.detailsFile)
+            details = readFileSync(opts.detailsFile, "utf8");
+        const reqBody = buildDmBody({
+            recipient,
+            message: message ?? "",
+            prompt,
+            details,
+            at: opts.at,
+            inDelay: opts.in,
+            now: Date.now(),
+        });
+        const token = await ensureCognitoToken();
+        const res = await vaultApiFetch({
+            token,
+            path: "/v1/notify/dm",
+            method: "POST",
+            body: reqBody,
+        });
+        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);
+        }
+        // 202 connection_requested: the recipient isn't connected yet, so the DM is
+        // held as a connection request rather than delivered. This is a success, not
+        // an error — surface it quietly.
+        const data = (await res.json());
+        if (res.status === 202 || data.state === "connection_requested") {
+            console.log(chalk.green(`Request sent — pending ${recipient}'s acceptance.`));
+            console.log(chalk.dim("Your message is held and delivers automatically once they accept."));
+            return;
+        }
+        if (data.scheduled) {
+            console.log(chalk.green(`Scheduled DM to ${recipient} for ${data.deliverAt} (eventId ${data.eventId}).`));
+            console.log(chalk.dim("It delivers within ~60s of that time, even if you're offline."));
+        }
+        else {
+            console.log(chalk.green(`DM sent to ${recipient} (eventId ${data.eventId}).`));
+        }
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+async function runDmRequests() {
+    try {
+        const token = await ensureCognitoToken();
+        const requests = await fetchRequests(token);
+        if (requests.length === 0) {
+            console.log(chalk.dim("No pending connection requests."));
+            return;
+        }
+        console.log(chalk.green(`${requests.length} pending connection request${requests.length === 1 ? "" : "s"}:`));
+        for (const r of requests) {
+            const name = r.fromDisplayName ?? r.fromEmail ?? r.fromPersonUid;
+            const emailPart = r.fromEmail ? chalk.dim(` <${r.fromEmail}>`) : "";
+            console.log(`\n  ${chalk.bold(name)}${emailPart}`);
+            if (r.message) {
+                console.log(`    ${chalk.dim('"' + r.message + '"')}`);
+            }
+            const idHint = r.fromEmail ?? r.fromPersonUid ?? r.pairKey;
+            console.log(chalk.dim(`    Accept: hq dm accept ${idHint}   ·   Decline: hq dm decline ${idHint}`));
+        }
+    }
+    catch (err) {
+        console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
 export function registerDmCommand(program) {
-    program
-        .command("dm <recipient> [message]")
-        .description("Send a direct message to a teammate (email or personUid). They receive it as an HQ Sync notification.")
+    const dm = program
+        .command("dm")
+        .description("Send a direct message and manage connection requests.");
+    dm
+        .command("send <recipient> [message]", { isDefault: true, hidden: true })
+        .description("Send a direct message to someone (email or personUid). They receive it as an HQ Sync notification. If you aren't connected yet, it sends a connection request that holds your message.")
         .option("--prompt <text>", "Agent-context prompt the recipient can one-click copy into their agent")
         .option("--prompt-file <path>", "Read the agent prompt from a file")
         .option("--details <text>", "Longer detail shown in the recipient's DM detail window")
@@ -100,49 +269,32 @@ export function registerDmCommand(program) {
         .option("--at <iso>", "Schedule delivery at an ISO8601 time (store-and-forward; delivered within ~60s of the time)")
         .option("--in <duration>", "Schedule delivery after a relative delay: 30s, 10m, 2h, 1d")
         .action(async (recipient, message, opts) => {
-        try {
-            // Resolve prompt/details from inline text or a file.
-            let prompt = opts.prompt;
-            if (opts.promptFile)
-                prompt = readFileSync(opts.promptFile, "utf8");
-            let details = opts.details;
-            if (opts.detailsFile)
-                details = readFileSync(opts.detailsFile, "utf8");
-            const reqBody = buildDmBody({
-                recipient,
-                message: message ?? "",
-                prompt,
-                details,
-                at: opts.at,
-                inDelay: opts.in,
-                now: Date.now(),
-            });
-            const token = await ensureCognitoToken();
-            const res = await vaultApiFetch({
-                token,
-                path: "/v1/notify/dm",
-                method: "POST",
-                body: reqBody,
-            });
-            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());
-            if (data.scheduled) {
-                console.log(chalk.green(`Scheduled DM to ${recipient} for ${data.deliverAt} (eventId ${data.eventId}).`));
-                console.log(chalk.dim("It delivers within ~60s of that time, even if you're offline."));
-            }
-            else {
-                console.log(chalk.green(`DM sent to ${recipient} (eventId ${data.eventId}).`));
-            }
-        }
-        catch (err) {
-            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
-            process.exit(1);
-        }
+        await runDmSend(recipient, message, opts);
+    });
+    dm
+        .command("requests")
+        .description("List your pending incoming connection requests.")
+        .action(async () => {
+        await runDmRequests();
+    });
+    dm
+        .command("accept <person>")
+        .description("Accept a pending connection request (by email, personUid, or pairKey). Their held message is then delivered.")
+        .action(async (person) => {
+        await runConnectionAction("accept", person);
+    });
+    dm
+        .command("decline <person>")
+        .description("Decline a pending connection request (by email, personUid, or pairKey).")
+        .action(async (person) => {
+        await runConnectionAction("decline", person);
+    });
+    dm
+        .command("block <person>")
+        .description("Block a person so they can't send you further requests (by email, personUid, or pairKey).")
+        .action(async (person) => {
+        await runConnectionAction("block", person);
     });
 }
 //# sourceMappingURL=dm.js.map
-//# debugId=69d48194-d5ae-508e-b614-68f2066db6ee
+//# debugId=19c5d8e0-ec0a-5b57-b3dc-e2209b60cf2f

package/package.json

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

package/src/commands/dm.test.ts

@@ -1,5 +1,32 @@
-import { describe, it, expect } from "vitest";
-import { detectRecipient, parseDuration, buildDmBody } from "./dm.js";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from "vitest";
+
+// Stub ensureCognitoToken so the action handlers run without keychain/disk I/O.
+vi.mock("../utils/cognito-session.js", async (importOriginal) => {
+  const original = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...original,
+    ensureCognitoToken: vi.fn(async () => "test-token"),
+  };
+});
+
+import { Command } from "commander";
+import {
+  detectRecipient,
+  parseDuration,
+  buildDmBody,
+  matchRequest,
+  buildConnectionActionBody,
+  registerDmCommand,
+  type ConnectionRequest,
+} from "./dm.js";
 
 describe("detectRecipient", () => {
   it("classifies an email", () => {
@@ -86,3 +113,185 @@ describe("buildDmBody", () => {
     expect(() => buildDmBody({ recipient: "a@b.com", message: "m", inDelay: "soon", now })).toThrow(/Invalid --in/);
   });
 });
+
+// ---------------------------------------------------------------------------
+// matchRequest (pure)
+// ---------------------------------------------------------------------------
+
+const SAMPLE_REQUESTS: ConnectionRequest[] = [
+  {
+    pairKey: "pair_abc",
+    fromPersonUid: "prs_alice",
+    fromDisplayName: "Alice",
+    fromEmail: "alice@example.com",
+    message: "hey, lets connect",
+    createdAt: "2026-06-01T00:00:00.000Z",
+  },
+  {
+    pairKey: "pair_def",
+    fromPersonUid: "prs_bob",
+    fromDisplayName: "Bob",
+    fromEmail: "Bob@Example.com",
+  },
+];
+
+describe("matchRequest", () => {
+  it("matches by email case-insensitively", () => {
+    expect(matchRequest(SAMPLE_REQUESTS, "ALICE@example.com")?.pairKey).toBe("pair_abc");
+    expect(matchRequest(SAMPLE_REQUESTS, "bob@example.com")?.pairKey).toBe("pair_def");
+  });
+  it("matches by personUid", () => {
+    expect(matchRequest(SAMPLE_REQUESTS, "prs_bob")?.pairKey).toBe("pair_def");
+  });
+  it("matches by pairKey", () => {
+    expect(matchRequest(SAMPLE_REQUESTS, "pair_abc")?.fromPersonUid).toBe("prs_alice");
+  });
+  it("returns null when nothing matches", () => {
+    expect(matchRequest(SAMPLE_REQUESTS, "nobody@example.com")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildConnectionActionBody (pure)
+// ---------------------------------------------------------------------------
+
+describe("buildConnectionActionBody", () => {
+  it("prefers the matched request's pairKey", () => {
+    expect(buildConnectionActionBody("alice@example.com", SAMPLE_REQUESTS[0])).toEqual({
+      pairKey: "pair_abc",
+    });
+  });
+  it("falls back to withPersonUid for an unmatched prs_ id", () => {
+    expect(buildConnectionActionBody("prs_zed", null)).toEqual({ withPersonUid: "prs_zed" });
+  });
+  it("falls back to withEmail for an unmatched email", () => {
+    expect(buildConnectionActionBody("Stranger@Example.com", null)).toEqual({
+      withEmail: "stranger@example.com",
+    });
+  });
+  it("throws on an unresolvable identifier", () => {
+    expect(() => buildConnectionActionBody("not-an-id", null)).toThrow(/Could not resolve/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Action handlers (HTTP/auth mocked)
+// ---------------------------------------------------------------------------
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+describe("dm command actions", () => {
+  let fetchSpy: MockInstance<typeof fetch>;
+  let exitSpy: MockInstance<typeof process.exit>;
+  let logSpy: MockInstance<typeof console.log>;
+  let errSpy: MockInstance<typeof console.error>;
+  let program: Command;
+
+  beforeEach(() => {
+    fetchSpy = vi.spyOn(globalThis, "fetch");
+    exitSpy = vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+      throw new Error(`__EXIT__:${code ?? 0}`);
+    }) as never);
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+    errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    program = new Command();
+    registerDmCommand(program);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  function logged(): string {
+    return logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+  }
+
+  it("send: prints delivered on 200", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { eventId: "evt_1" }));
+    await program.parseAsync(["dm", "alice@example.com", "hi there"], { from: "user" });
+    const url = String(fetchSpy.mock.calls[0][0]);
+    expect(url).toContain("/v1/notify/dm");
+    expect(logged()).toMatch(/DM sent to alice@example.com/);
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("send: prints pending request on 202 connection_requested (not an error)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(202, { state: "connection_requested" }),
+    );
+    await program.parseAsync(["dm", "stranger@example.com", "hello"], { from: "user" });
+    expect(logged()).toMatch(/Request sent — pending stranger@example\.com's acceptance\./);
+    // 202 is a success, not an error path.
+    expect(exitSpy).not.toHaveBeenCalled();
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("requests: lists pending incoming requests with identifiers", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { requests: SAMPLE_REQUESTS }),
+    );
+    await program.parseAsync(["dm", "requests"], { from: "user" });
+    const url = String(fetchSpy.mock.calls[0][0]);
+    expect(url).toContain("/v1/notify/connections/requests");
+    const out = logged();
+    expect(out).toMatch(/2 pending connection requests/);
+    expect(out).toContain("Alice");
+    expect(out).toContain("alice@example.com");
+    expect(out).toContain('"hey, lets connect"');
+  });
+
+  it("requests: handles an empty list quietly", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { requests: [] }));
+    await program.parseAsync(["dm", "requests"], { from: "user" });
+    expect(logged()).toMatch(/No pending connection requests/);
+  });
+
+  it("accept: resolves email to pairKey and hits the accept endpoint", async () => {
+    // 1st call: fetch requests; 2nd call: accept.
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(200, { requests: SAMPLE_REQUESTS }))
+      .mockResolvedValueOnce(jsonResponse(200, { state: "active" }));
+    await program.parseAsync(["dm", "accept", "alice@example.com"], { from: "user" });
+    const acceptCall = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/v1/notify/connections/accept"),
+    );
+    expect(acceptCall).toBeTruthy();
+    const body = JSON.parse((acceptCall![1]?.body as string) ?? "{}");
+    expect(body).toEqual({ pairKey: "pair_abc" });
+    expect(logged()).toMatch(/Connection accepted — Alice\./);
+  });
+
+  it("decline: hits the decline endpoint", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(200, { requests: SAMPLE_REQUESTS }))
+      .mockResolvedValueOnce(jsonResponse(200, { state: "declined" }));
+    await program.parseAsync(["dm", "decline", "prs_bob"], { from: "user" });
+    const call = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/v1/notify/connections/decline"),
+    );
+    expect(call).toBeTruthy();
+    const body = JSON.parse((call![1]?.body as string) ?? "{}");
+    expect(body).toEqual({ pairKey: "pair_def" });
+    expect(logged()).toMatch(/Request declined — Bob\./);
+  });
+
+  it("block: hits the block endpoint, falling back to withEmail for a stranger", async () => {
+    // No matching request → falls back to withEmail.
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(200, { requests: [] }))
+      .mockResolvedValueOnce(jsonResponse(200, { state: "blocked" }));
+    await program.parseAsync(["dm", "block", "spammer@example.com"], { from: "user" });
+    const call = fetchSpy.mock.calls.find((c) =>
+      String(c[0]).includes("/v1/notify/connections/block"),
+    );
+    expect(call).toBeTruthy();
+    const body = JSON.parse((call![1]?.body as string) ?? "{}");
+    expect(body).toEqual({ withEmail: "spammer@example.com" });
+    expect(logged()).toMatch(/Blocked — spammer@example\.com\./);
+  });
+});

package/src/commands/dm.ts

@@ -117,11 +117,266 @@ function friendlyDmError(status: number, code: string | undefined, fallback: str
   return fallback;
 }
 
+/** A pending incoming connection request, as returned by the backend. */
+export interface ConnectionRequest {
+  pairKey: string;
+  fromPersonUid: string;
+  fromDisplayName?: string;
+  fromEmail?: string;
+  message?: string;
+  createdAt?: string;
+}
+
+/**
+ * Resolve a connection request from a pending-requests list by a caller-supplied
+ * identifier (email, personUid, or pairKey). Pure → unit-testable.
+ *
+ * Matching is case-insensitive for emails. Returns the matched request, or null
+ * if no request matches.
+ */
+export function matchRequest(
+  requests: ConnectionRequest[],
+  identifier: string,
+): ConnectionRequest | null {
+  const id = identifier.trim();
+  const idLower = id.toLowerCase();
+  for (const r of requests) {
+    if (r.pairKey === id) return r;
+    if (r.fromPersonUid === id) return r;
+    if (r.fromEmail && r.fromEmail.toLowerCase() === idLower) return r;
+  }
+  return null;
+}
+
+/**
+ * Build the POST body for an accept/decline/block action. Prefers a resolved
+ * pairKey (from a matched pending request); otherwise falls back to the
+ * recipient identifier the backend can resolve (`withPersonUid` for a prs_ UID,
+ * `toEmail`-style is not supported by the connections endpoints so we send
+ * `withEmail`). Pure → unit-testable.
+ *
+ * Throws Error with a user-facing message when the identifier can't be resolved.
+ */
+export function buildConnectionActionBody(
+  identifier: string,
+  matched: ConnectionRequest | null,
+): { pairKey: string } | { withPersonUid: string } | { withEmail: string } {
+  if (matched) {
+    return { pairKey: matched.pairKey };
+  }
+  const r = identifier.trim();
+  const rcpt = detectRecipient(r);
+  if (rcpt?.toPersonUid) return { withPersonUid: rcpt.toPersonUid };
+  if (rcpt?.toEmail) return { withEmail: rcpt.toEmail };
+  throw new Error(
+    `Could not resolve '${identifier}' to a pending request — pass the requester's email, personUid, or the pairKey from \`hq dm requests\`.`,
+  );
+}
+
+const CONNECTION_ACTIONS = {
+  accept: { path: "accept", done: "Connection accepted" },
+  decline: { path: "decline", done: "Request declined" },
+  block: { path: "block", done: "Blocked" },
+} as const;
+
+type ConnectionAction = keyof typeof CONNECTION_ACTIONS;
+
+/** Fetch the caller's pending incoming connection requests. */
+async function fetchRequests(token: string): Promise<ConnectionRequest[]> {
+  const res = await vaultApiFetch({
+    token,
+    path: "/v1/notify/connections/requests",
+  });
+  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),
+    );
+  }
+  const data = (await res.json()) as { requests?: ConnectionRequest[] };
+  return data.requests ?? [];
+}
+
+async function runConnectionAction(
+  action: ConnectionAction,
+  identifier: string,
+): Promise<void> {
+  try {
+    const token = await ensureCognitoToken();
+    // Resolve the pairKey from the caller's pending requests when possible so
+    // accept/decline/block work against a friendly email or personUid.
+    const requests = await fetchRequests(token).catch(() => [] as ConnectionRequest[]);
+    const matched = matchRequest(requests, identifier);
+    const body = buildConnectionActionBody(identifier, matched);
+
+    const res = await vaultApiFetch({
+      token,
+      path: `/v1/notify/connections/${CONNECTION_ACTIONS[action].path}`,
+      method: "POST",
+      body: body as unknown as Record<string, unknown>,
+    });
+    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 who = matched?.fromDisplayName ?? matched?.fromEmail ?? identifier;
+    console.log(chalk.green(`${CONNECTION_ACTIONS[action].done} — ${who}.`));
+    if (action === "accept" && matched?.message) {
+      console.log(chalk.dim("Their held message will now be delivered."));
+    }
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
+interface DmSendOpts {
+  prompt?: string;
+  promptFile?: string;
+  details?: string;
+  detailsFile?: string;
+  at?: string;
+  in?: string;
+}
+
+async function runDmSend(
+  recipient: string,
+  message: string | undefined,
+  opts: DmSendOpts,
+): Promise<void> {
+  try {
+    // Resolve prompt/details from inline text or a file.
+    let prompt = opts.prompt;
+    if (opts.promptFile) prompt = readFileSync(opts.promptFile, "utf8");
+    let details = opts.details;
+    if (opts.detailsFile) details = readFileSync(opts.detailsFile, "utf8");
+
+    const reqBody = buildDmBody({
+      recipient,
+      message: message ?? "",
+      prompt,
+      details,
+      at: opts.at,
+      inDelay: opts.in,
+      now: Date.now(),
+    });
+
+    const token = await ensureCognitoToken();
+    const res = await vaultApiFetch({
+      token,
+      path: "/v1/notify/dm",
+      method: "POST",
+      body: reqBody as unknown as Record<string, unknown>,
+    });
+
+    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);
+    }
+
+    // 202 connection_requested: the recipient isn't connected yet, so the DM is
+    // held as a connection request rather than delivered. This is a success, not
+    // an error — surface it quietly.
+    const data = (await res.json()) as {
+      eventId?: string;
+      createdAt?: string;
+      scheduled?: boolean;
+      deliverAt?: string;
+      state?: string;
+    };
+
+    if (res.status === 202 || data.state === "connection_requested") {
+      console.log(
+        chalk.green(`Request sent — pending ${recipient}'s acceptance.`),
+      );
+      console.log(
+        chalk.dim("Your message is held and delivers automatically once they accept."),
+      );
+      return;
+    }
+
+    if (data.scheduled) {
+      console.log(
+        chalk.green(
+          `Scheduled DM to ${recipient} for ${data.deliverAt} (eventId ${data.eventId}).`,
+        ),
+      );
+      console.log(
+        chalk.dim("It delivers within ~60s of that time, even if you're offline."),
+      );
+    } else {
+      console.log(
+        chalk.green(`DM sent to ${recipient} (eventId ${data.eventId}).`),
+      );
+    }
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
+async function runDmRequests(): Promise<void> {
+  try {
+    const token = await ensureCognitoToken();
+    const requests = await fetchRequests(token);
+    if (requests.length === 0) {
+      console.log(chalk.dim("No pending connection requests."));
+      return;
+    }
+    console.log(
+      chalk.green(
+        `${requests.length} pending connection request${requests.length === 1 ? "" : "s"}:`,
+      ),
+    );
+    for (const r of requests) {
+      const name = r.fromDisplayName ?? r.fromEmail ?? r.fromPersonUid;
+      const emailPart = r.fromEmail ? chalk.dim(` <${r.fromEmail}>`) : "";
+      console.log(`\n  ${chalk.bold(name)}${emailPart}`);
+      if (r.message) {
+        console.log(`    ${chalk.dim('"' + r.message + '"')}`);
+      }
+      const idHint = r.fromEmail ?? r.fromPersonUid ?? r.pairKey;
+      console.log(
+        chalk.dim(`    Accept: hq dm accept ${idHint}   ·   Decline: hq dm decline ${idHint}`),
+      );
+    }
+  } catch (err) {
+    console.error(
+      chalk.red("Error:"),
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(1);
+  }
+}
+
 export function registerDmCommand(program: Command): void {
-  program
-    .command("dm <recipient> [message]")
+  const dm = program
+    .command("dm")
     .description(
-      "Send a direct message to a teammate (email or personUid). They receive it as an HQ Sync notification.",
+      "Send a direct message and manage connection requests.",
+    );
+
+  dm
+    .command("send <recipient> [message]", { isDefault: true, hidden: true })
+    .description(
+      "Send a direct message to someone (email or personUid). They receive it as an HQ Sync notification. If you aren't connected yet, it sends a connection request that holds your message.",
     )
     .option(
       "--prompt <text>",
@@ -145,78 +400,39 @@ export function registerDmCommand(program: Command): void {
       async (
         recipient: string,
         message: string | undefined,
-        opts: {
-          prompt?: string;
-          promptFile?: string;
-          details?: string;
-          detailsFile?: string;
-          at?: string;
-          in?: string;
-        },
+        opts: DmSendOpts,
       ) => {
-        try {
-          // Resolve prompt/details from inline text or a file.
-          let prompt = opts.prompt;
-          if (opts.promptFile) prompt = readFileSync(opts.promptFile, "utf8");
-          let details = opts.details;
-          if (opts.detailsFile) details = readFileSync(opts.detailsFile, "utf8");
-
-          const reqBody = buildDmBody({
-            recipient,
-            message: message ?? "",
-            prompt,
-            details,
-            at: opts.at,
-            inDelay: opts.in,
-            now: Date.now(),
-          });
-
-          const token = await ensureCognitoToken();
-          const res = await vaultApiFetch({
-            token,
-            path: "/v1/notify/dm",
-            method: "POST",
-            body: reqBody as unknown as Record<string, unknown>,
-          });
-
-          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 {
-            eventId?: string;
-            createdAt?: string;
-            scheduled?: boolean;
-            deliverAt?: string;
-          };
-
-          if (data.scheduled) {
-            console.log(
-              chalk.green(
-                `Scheduled DM to ${recipient} for ${data.deliverAt} (eventId ${data.eventId}).`,
-              ),
-            );
-            console.log(
-              chalk.dim("It delivers within ~60s of that time, even if you're offline."),
-            );
-          } else {
-            console.log(
-              chalk.green(`DM sent to ${recipient} (eventId ${data.eventId}).`),
-            );
-          }
-        } catch (err) {
-          console.error(
-            chalk.red("Error:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
+        await runDmSend(recipient, message, opts);
       },
     );
+
+  dm
+    .command("requests")
+    .description("List your pending incoming connection requests.")
+    .action(async () => {
+      await runDmRequests();
+    });
+
+  dm
+    .command("accept <person>")
+    .description(
+      "Accept a pending connection request (by email, personUid, or pairKey). Their held message is then delivered.",
+    )
+    .action(async (person: string) => {
+      await runConnectionAction("accept", person);
+    });
+
+  dm
+    .command("decline <person>")
+    .description("Decline a pending connection request (by email, personUid, or pairKey).")
+    .action(async (person: string) => {
+      await runConnectionAction("decline", person);
+    });
+
+  dm
+    .command("block <person>")
+    .description("Block a person so they can't send you further requests (by email, personUid, or pairKey).")
+    .action(async (person: string) => {
+      await runConnectionAction("block", person);
+    });
 }