@indigoai-us/hq-cli 5.122.2 → 5.123.1

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 ## [Unreleased]
 
+## [5.123.1] — 2026-09-19
+
+### Fixed
+
+- Work Mesh now preserves an acknowledged company binding through later
+  company-less hook writes, preventing repeated registrations and held events.
+  Held recovery accepts only durable registrations, canonical metadata under a
+  verified HQ root, or manifest-backed repository ownership; conflicting or
+  event-only hints stay unresolved. Its batch cursor rotates across restarts.
+  Both legacy and direct-mode daemons detect an upgraded CLI, and systemd units
+  use `Restart=always` so the installed service reloads the new code.
+
+- Held-session recovery now accepts session metadata only from the daemon's
+  configured HQ root, requires current-session evidence before restoring an
+  acknowledged registration, and retains batch position when held records are
+  compacted. Repeated hook activity no longer re-registers an unchanged binding.
+  CLI updates report installed system units that need their host service manager
+  to restart them. Daemon installs persist verified HQ-root allowlists, inject
+  the primary root into service environments, and rewrite/reload existing user
+  units so upgraded daemons restart reliably.
+
+## [5.123.0] — 2026-09-19
+
+### Fixed
+
+- `hq mesh check --project` lists that project's open threads. The CLI queries
+  `/v1/work-mesh/threads` with `projectId` (and `status=open`) and merges the
+  result with the status listing, because the status index can omit project
+  threads.
+
+- First signed-in interactive run prints a one-line telemetry disclosure on
+  stderr (once per machine). `HQ_TELEMETRY=0` (also `false` or `off`) disables
+  CLI telemetry posts. After the notice has been shown, events send
+  `consentBasis: "disclosed"` instead of `"no-consent"`.
+
+### Added
+
+- Channel messages can now be posted as thread replies: `hq dm <channel>
+  --thread <eventId> "…"` sends `rootEventId` on the POST, and `--thread last`
+  replies to your most recent top-level message in that channel. `hq dm channel
+  <name>` prints each root's eventId and indents replies under their root
+  (`--json` is still the ungrouped oldest-first array). `@name` mentions were
+  already resolved against the roster into the structured `mentions` array;
+  unknown names still fail the send and list the roster (`--no-mentions` posts
+  the text literally).
+
+### Changed
+
+- `hq whoami --company` and the bind notice no longer read `planLock`. They
+  render the Starter over-limit nag from `GET /v1/billing/usage-limits`
+  (including the top-level `freeMonth` CTA). Customer copy does not say
+  "locked" or "read-only".
+
+### Fixed
+
+- Work Mesh board snapshots now read live story status from ProjectView before
+  falling back to the vault board, and `hq mesh daemon doctor` warns when a
+  presence credential omitted companies.
+
 ## [5.122.2] — 2026-09-19
 
 ### Fixed

package/README.md

@@ -0,0 +1,46 @@
+# hq-cli
+
+HQ management CLI — modules, packages, and cloud sync.
+
+```bash
+npm install -g @indigoai-us/hq-cli
+hq --help
+```
+
+## Telemetry
+
+When you are signed in, `hq` may POST one `cli_session_started` event to
+`/v1/telemetry/events`. The event body is:
+
+- `eventName`: `cli_session_started`
+- `app`: `hq-cli`
+- `source`: `cli`
+- `occurredAt`: ISO timestamp
+- `consentBasis`: `disclosed` after the first-run notice, otherwise `no-consent`
+- `schemaVersion`: `1`
+- `properties.version`: the CLI version
+
+The request is authenticated with your cached session token so the control
+plane can accept the event. The body does not include command names, arguments,
+timings, file contents, or secrets.
+
+The first signed-in interactive run (stdout is a TTY, and the command is not
+`--json`) prints this line once on stderr and records that it was shown under
+`~/.hq/cli-telemetry-disclosed`:
+
+```
+HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.
+```
+
+Turn telemetry off:
+
+```bash
+export HQ_TELEMETRY=0
+```
+
+`false` and `off` are accepted as well (case-insensitive). That disables every
+CLI POST to `/v1/telemetry/events`. `HQ_TELEMETRY_TIMEOUT_MS` is a separate
+timeout knob and is unchanged.
+
+The same kill switch and event shape should be documented on hqforwork.com
+when that site's telemetry page is added (indigo-marketing; not this repo).

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

@@ -833,7 +833,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly description: "Output identity metadata as JSON (never tokens)";
     }, {
         readonly flags: "--company <slug>";
-        readonly description: "Also report this company's workspace plan state (Starter lock)";
+        readonly description: "Also report this company's workspace plan state (Starter nag)";
     }];
     readonly subcommands: readonly [];
 }, {
@@ -2209,7 +2209,7 @@ export declare const COMMAND_CATALOG: readonly [{
     readonly options: readonly [];
     readonly subcommands: readonly [{
         readonly name: "send";
-        readonly 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`.\n\nCHANNEL MENTIONS: HQ mentions are structured — the server never reads `@name` out of your text, so a channel message has to carry the participants alongside the body. When you write `@name` in a channel message, this command looks the name up in the channel roster (case-insensitive on display name and slug/handle; quote multi-word names as @\"Jacob Posel\") and sends it as a real mention, which notifies people and wakes agents. If a name is unknown or matches more than one member, the send FAILS with the candidates instead of posting something that mentions nobody. A bare \"@\" or an email address in your prose is never treated as a mention. Pass --no-mentions to post the text literally.";
+        readonly 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`.\n\nCHANNEL MENTIONS: HQ mentions are structured — the server never reads `@name` out of your text, so a channel message has to carry the participants alongside the body. When you write `@name` in a channel message, this command looks the name up in the channel roster (case-insensitive on display name and slug/handle; quote multi-word names as @\"Jacob Posel\") and sends it as a real mention, which notifies people and wakes agents. If a name is unknown or matches more than one member, the send FAILS with the candidates instead of posting something that mentions nobody. A bare \"@\" or an email address in your prose is never treated as a mention. Pass --no-mentions to post the text literally.\n\nCHANNEL THREADS: `hq dm <channel> --thread <eventId> \"…\"` replies under an existing root (the request carries rootEventId). `--thread last` replies to your most recent top-level message in that channel. Copy a root eventId from `hq dm channel <name>`, which prints each root's id and indents replies underneath.";
         readonly aliases: readonly [];
         readonly hidden: true;
         readonly usage: "[options] [recipient] [message]";
@@ -2228,6 +2228,9 @@ export declare const COMMAND_CATALOG: readonly [{
         }, {
             readonly flags: "--no-mentions";
             readonly description: "Do not resolve `@name` in a channel message into structured mentions — post the text literally";
+        }, {
+            readonly flags: "--thread <eventId>";
+            readonly description: "Reply in a channel thread. Pass a root eventId from `hq dm channel`, or `last` for your most recent top-level message in that channel";
         }, {
             readonly flags: "--prompt <text>";
             readonly description: "Agent-context prompt the recipient can one-click copy into their agent (1:1 DMs only)";
@@ -2293,7 +2296,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "channel";
-        readonly description: "Show recent messages in a DM channel or group DM — by name, #name, or a channel id from `hq channels`.";
+        readonly description: "Show recent messages in a DM channel or group DM — by name, #name, or a channel id from `hq channels`. Roots print their eventId; replies indent under their root. --json is the raw oldest-first array (ungrouped).";
         readonly aliases: readonly ["history"];
         readonly hidden: false;
         readonly usage: "[options] <target>";

package/dist/command-catalog.generated.js

@@ -1064,7 +1064,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "flags": "--company <slug>",
-                "description": "Also report this company's workspace plan state (Starter lock)"
+                "description": "Also report this company's workspace plan state (Starter nag)"
             }
         ],
         "subcommands": []
@@ -2836,7 +2836,7 @@ export const COMMAND_CATALOG = [
         "subcommands": [
             {
                 "name": "send",
-                "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`.\n\nCHANNEL MENTIONS: HQ mentions are structured — the server never reads `@name` out of your text, so a channel message has to carry the participants alongside the body. When you write `@name` in a channel message, this command looks the name up in the channel roster (case-insensitive on display name and slug/handle; quote multi-word names as @\"Jacob Posel\") and sends it as a real mention, which notifies people and wakes agents. If a name is unknown or matches more than one member, the send FAILS with the candidates instead of posting something that mentions nobody. A bare \"@\" or an email address in your prose is never treated as a mention. Pass --no-mentions to post the text literally.",
+                "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`.\n\nCHANNEL MENTIONS: HQ mentions are structured — the server never reads `@name` out of your text, so a channel message has to carry the participants alongside the body. When you write `@name` in a channel message, this command looks the name up in the channel roster (case-insensitive on display name and slug/handle; quote multi-word names as @\"Jacob Posel\") and sends it as a real mention, which notifies people and wakes agents. If a name is unknown or matches more than one member, the send FAILS with the candidates instead of posting something that mentions nobody. A bare \"@\" or an email address in your prose is never treated as a mention. Pass --no-mentions to post the text literally.\n\nCHANNEL THREADS: `hq dm <channel> --thread <eventId> \"…\"` replies under an existing root (the request carries rootEventId). `--thread last` replies to your most recent top-level message in that channel. Copy a root eventId from `hq dm channel <name>`, which prints each root's id and indents replies underneath.",
                 "aliases": [],
                 "hidden": true,
                 "usage": "[options] [recipient] [message]",
@@ -2861,6 +2861,10 @@ export const COMMAND_CATALOG = [
                         "flags": "--no-mentions",
                         "description": "Do not resolve `@name` in a channel message into structured mentions — post the text literally"
                     },
+                    {
+                        "flags": "--thread <eventId>",
+                        "description": "Reply in a channel thread. Pass a root eventId from `hq dm channel`, or `last` for your most recent top-level message in that channel"
+                    },
                     {
                         "flags": "--prompt <text>",
                         "description": "Agent-context prompt the recipient can one-click copy into their agent (1:1 DMs only)"
@@ -2948,7 +2952,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "channel",
-                "description": "Show recent messages in a DM channel or group DM — by name, #name, or a channel id from `hq channels`.",
+                "description": "Show recent messages in a DM channel or group DM — by name, #name, or a channel id from `hq channels`. Roots print their eventId; replies indent under their root. --json is the raw oldest-first array (ungrouped).",
                 "aliases": [
                     "history"
                 ],

package/dist/commands/dm.d.ts

@@ -228,6 +228,8 @@ export interface ChannelMessageItem {
     fromDisplayName?: string;
     body: string;
     createdAt: string;
+    /** Present on a reply; absent on a top-level (root) message. */
+    rootEventId?: string;
     attachments?: DmAttachment[];
     attachment?: DmAttachment;
 }
@@ -296,7 +298,58 @@ 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 formatChannelMessage(m: ChannelMessageItem, nowMs: number, opts?: {
+    indent?: string;
+    showEventId?: boolean;
+}): string;
+/** Identity we can match against a channel message's from* fields. Pure. */
+export interface CallerIdentity {
+    personUid?: string;
+    email?: string;
+}
+/**
+ * Read the caller's person/agent uid and email from a JWT we already hold.
+ * Used to resolve `--thread last` (most recent top-level message *by us*).
+ * Pure → unit-testable.
+ */
+export declare function callerFromToken(token: string): CallerIdentity;
+export declare function isCallerMessage(m: ChannelMessageItem, me: CallerIdentity): boolean;
+/**
+ * Newest-first channel history → the caller's most recent top-level eventId.
+ * Replies (those with rootEventId) are skipped. Pure → unit-testable.
+ */
+export declare function lastCallerRootEventId(messagesNewestFirst: ChannelMessageItem[], me: CallerIdentity): string | undefined;
+export type ThreadFlagResolution = {
+    ok: true;
+    rootEventId?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve `--thread <eventId|last>` against a newest-first message page.
+ * An explicit eventId is passed through; `last` picks our most recent
+ * top-level message. Pure → unit-testable (the fetch is the caller's job).
+ */
+export declare function resolveThreadFlag(thread: string | undefined, messagesNewestFirst: ChannelMessageItem[], me: CallerIdentity): ThreadFlagResolution;
+export interface ChannelThread {
+    root: ChannelMessageItem;
+    replies: ChannelMessageItem[];
+    /** True when the root is not in this page — replies hang off a placeholder. */
+    missingRoot?: boolean;
+}
+/**
+ * Group a channel history page into roots with their replies underneath.
+ * Orphan replies (root not in this page) hang off a placeholder carrying the
+ * missing root's eventId. Pure → unit-testable.
+ */
+export declare function groupChannelMessages(messages: ChannelMessageItem[]): ChannelThread[];
+/**
+ * Human channel history: each root prints its eventId so `--thread` can copy
+ * it; replies render indented under their root. `--json` does not use this.
+ * Pure → unit-testable.
+ */
+export declare function formatChannelTranscript(messages: 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

package/dist/commands/dm.js

@@ -515,6 +515,20 @@ async function fetchChannelMembers(token, channelId) {
     const data = (await res.json());
     return data.members ?? [];
 }
+/** Fetch a channel history page (GET /v1/notify/channels/{id}/messages). Newest-first. */
+async function fetchChannelMessages(token, channelId, query = {}) {
+    const res = await vaultApiFetch({
+        token,
+        path: `/v1/notify/channels/${encodeURIComponent(channelId)}/messages`,
+        query,
+    });
+    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.messages ?? [];
+}
 /**
  * Channel DM path: `hq dm vyg-dev "msg"`, `hq dm '#vyg-dev' "msg"`, or
  * `hq dm --channel vyg-dev "msg"`. Resolves the caller's channel by name via
@@ -552,6 +566,20 @@ async function runChannelSend(channelName, message, opts) {
             process.exit(1);
         }
         const channel = matches[0];
+        let rootEventId;
+        if (opts.thread !== undefined) {
+            let recent = [];
+            if (opts.thread.trim().toLowerCase() === "last") {
+                recent = await fetchChannelMessages(token, channel.channelId);
+            }
+            const resolved = resolveThreadFlag(opts.thread, recent, callerFromToken(token));
+            if (!resolved.ok) {
+                console.error(chalk.red(resolved.error));
+                process.exit(1);
+                return;
+            }
+            rootEventId = resolved.rootEventId;
+        }
         // Mentions are structured-only server-side: resolve `@name` against the
         // roster and send the array, or fail before posting. --no-mentions opts out
         // and posts the text literally.
@@ -572,11 +600,16 @@ async function runChannelSend(channelName, message, opts) {
         // Send the human-readable form: the quotes only existed for parsing.
         if (mentions.length > 0)
             body = stripMentionQuotes(body);
+        const payload = { body };
+        if (mentions.length > 0)
+            payload.mentions = mentions;
+        if (rootEventId)
+            payload.rootEventId = rootEventId;
         const sendRes = await vaultApiFetch({
             token,
             path: `/v1/notify/channels/${encodeURIComponent(channel.channelId)}/messages`,
             method: "POST",
-            body: mentions.length > 0 ? { body, mentions } : { body },
+            body: payload,
         });
         if (!sendRes.ok) {
             const err = (await sendRes.json().catch(() => ({})));
@@ -586,7 +619,8 @@ async function runChannelSend(channelName, message, opts) {
         const mentionSuffix = mentions.length > 0
             ? ` Mentioned ${mentions.map((m) => m.displayName).join(", ")}.`
             : "";
-        console.log(chalk.green(`Message posted to #${channel.name ?? channelName}.${mentionSuffix}`));
+        const threadSuffix = rootEventId ? ` Reply in thread ${rootEventId}.` : "";
+        console.log(chalk.green(`Message posted to #${channel.name ?? channelName}.${mentionSuffix}${threadSuffix}`));
     }
     catch (err) {
         console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -608,6 +642,11 @@ async function runDmSend(recipient, message, opts) {
     // A comma in the recipient means a group DM — fan into the channel path.
     const group = parseGroupRecipients(recipient);
     if (group) {
+        if (opts.thread !== undefined) {
+            console.error(chalk.red("--thread is only supported for named channel messages (hq dm <channel> --thread <eventId|last> \"…\")."));
+            process.exit(1);
+            return;
+        }
         await runGroupSend(group, message);
         return;
     }
@@ -617,6 +656,11 @@ async function runDmSend(recipient, message, opts) {
         await runChannelSend(channelName, message, opts);
         return;
     }
+    if (opts.thread !== undefined) {
+        console.error(chalk.red("--thread is only supported for channel messages (hq dm <channel> --thread <eventId|last> \"…\")."));
+        process.exit(1);
+        return;
+    }
     try {
         // Resolve prompt/details from inline text or a file.
         let prompt = opts.prompt;
@@ -804,10 +848,162 @@ export function formatThreadMessage(m, nowMs) {
     return `${arrow} ${chalk.bold(who)} ${when}\n    ${firstLine(m.body)}${formatAttachments(m)}`;
 }
 /** Render one channel/group message line. */
-export function formatChannelMessage(m, nowMs) {
+export function formatChannelMessage(m, nowMs, opts = {}) {
+    const indent = opts.indent ?? "";
     const who = chalk.bold(senderLabel(m));
     const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
-    return `${who} ${when}\n    ${firstLine(m.body)}${formatAttachments(m)}`;
+    const id = opts.showEventId ? (m.eventId ?? m.messageId) : undefined;
+    const idPart = id ? `  ${chalk.dim(id)}` : "";
+    const bodyIndent = `${indent}    `;
+    return `${indent}${who} ${when}${idPart}\n${bodyIndent}${firstLine(m.body)}${formatAttachments(m, bodyIndent)}`;
+}
+/**
+ * Read the caller's person/agent uid and email from a JWT we already hold.
+ * Used to resolve `--thread last` (most recent top-level message *by us*).
+ * Pure → unit-testable.
+ */
+export function callerFromToken(token) {
+    const claims = peekIdToken(token);
+    const uid = claims["custom:entityUid"];
+    const email = claims.email;
+    const personUid = typeof uid === "string" && uid.trim() ? uid.trim() : undefined;
+    const emailNorm = typeof email === "string" && email.trim()
+        ? email.trim().toLowerCase()
+        : undefined;
+    return {
+        ...(personUid ? { personUid } : {}),
+        ...(emailNorm ? { email: emailNorm } : {}),
+    };
+}
+export function isCallerMessage(m, me) {
+    if (me.personUid && m.fromPersonUid === me.personUid)
+        return true;
+    if (me.email && (m.fromEmail ?? "").trim().toLowerCase() === me.email) {
+        return true;
+    }
+    return false;
+}
+function messageEventId(m) {
+    const id = (m.eventId ?? m.messageId ?? "").trim();
+    return id || undefined;
+}
+/**
+ * Newest-first channel history → the caller's most recent top-level eventId.
+ * Replies (those with rootEventId) are skipped. Pure → unit-testable.
+ */
+export function lastCallerRootEventId(messagesNewestFirst, me) {
+    for (const m of messagesNewestFirst) {
+        if ((m.rootEventId ?? "").trim())
+            continue;
+        if (!isCallerMessage(m, me))
+            continue;
+        const id = messageEventId(m);
+        if (id)
+            return id;
+    }
+    return undefined;
+}
+/**
+ * Resolve `--thread <eventId|last>` against a newest-first message page.
+ * An explicit eventId is passed through; `last` picks our most recent
+ * top-level message. Pure → unit-testable (the fetch is the caller's job).
+ */
+export function resolveThreadFlag(thread, messagesNewestFirst, me) {
+    if (thread === undefined)
+        return { ok: true };
+    const value = thread.trim();
+    if (!value) {
+        return { ok: false, error: "--thread requires an eventId or 'last'." };
+    }
+    if (value.toLowerCase() !== "last") {
+        return { ok: true, rootEventId: value };
+    }
+    if (!me.personUid && !me.email) {
+        return {
+            ok: false,
+            error: "Cannot resolve --thread last: the session token has no person uid or email. Pass --thread <eventId> from `hq dm channel`.",
+        };
+    }
+    const id = lastCallerRootEventId(messagesNewestFirst, me);
+    if (!id) {
+        return {
+            ok: false,
+            error: "No top-level message from you in this channel's recent history. Pass --thread <eventId> (copy it from `hq dm channel <name>`).",
+        };
+    }
+    return { ok: true, rootEventId: id };
+}
+function sortByCreatedAt(a, b) {
+    return (a.createdAt ?? "").localeCompare(b.createdAt ?? "");
+}
+/**
+ * Group a channel history page into roots with their replies underneath.
+ * Orphan replies (root not in this page) hang off a placeholder carrying the
+ * missing root's eventId. Pure → unit-testable.
+ */
+export function groupChannelMessages(messages) {
+    const roots = [];
+    const repliesByRoot = new Map();
+    for (const m of messages) {
+        const rootId = (m.rootEventId ?? "").trim();
+        if (!rootId) {
+            roots.push(m);
+            continue;
+        }
+        const bucket = repliesByRoot.get(rootId) ?? [];
+        bucket.push(m);
+        repliesByRoot.set(rootId, bucket);
+    }
+    const used = new Set();
+    const threads = [];
+    roots.sort(sortByCreatedAt);
+    for (const root of roots) {
+        const id = messageEventId(root) ?? "";
+        if (id)
+            used.add(id);
+        threads.push({
+            root,
+            replies: (repliesByRoot.get(id) ?? []).slice().sort(sortByCreatedAt),
+        });
+    }
+    for (const [rootId, replies] of repliesByRoot) {
+        if (used.has(rootId))
+            continue;
+        const sorted = replies.slice().sort(sortByCreatedAt);
+        threads.push({
+            root: {
+                eventId: rootId,
+                body: "",
+                createdAt: sorted[0]?.createdAt ?? "",
+            },
+            replies: sorted,
+            missingRoot: true,
+        });
+    }
+    return threads;
+}
+/**
+ * Human channel history: each root prints its eventId so `--thread` can copy
+ * it; replies render indented under their root. `--json` does not use this.
+ * Pure → unit-testable.
+ */
+export function formatChannelTranscript(messages, nowMs) {
+    const threads = groupChannelMessages(messages);
+    const blocks = [];
+    for (const t of threads) {
+        const parts = [];
+        if (t.missingRoot) {
+            parts.push(chalk.dim(`… ${t.root.eventId ?? ""} (root not in this page)`));
+        }
+        else {
+            parts.push(formatChannelMessage(t.root, nowMs, { showEventId: true }));
+        }
+        for (const reply of t.replies) {
+            parts.push(formatChannelMessage(reply, nowMs, { indent: "  " }));
+        }
+        blocks.push(parts.join("\n"));
+    }
+    return blocks.join("\n\n");
 }
 /** POST /v1/notify/inbox/ack — idempotently mark messages read. */
 async function ackEvents(token, eventIds) {
@@ -1053,8 +1249,7 @@ async function runDmChannel(target, opts) {
         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)}`);
+            console.log(`\n${formatChannelTranscript(ordered, now)}`);
         }
         if (opts.markRead) {
             // messages are newest-first from the server; advance the read cursor to
@@ -1082,9 +1277,10 @@ export function registerDmCommand(program) {
         .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`.\n\nCHANNEL MENTIONS: HQ mentions are structured — the server never reads `@name` out of your text, so a channel message has to carry the participants alongside the body. When you write `@name` in a channel message, this command looks the name up in the channel roster (case-insensitive on display name and slug/handle; quote multi-word names as @"Jacob Posel") and sends it as a real mention, which notifies people and wakes agents. If a name is unknown or matches more than one member, the send FAILS with the candidates instead of posting something that mentions nobody. A bare "@" or an email address in your prose is never treated as a mention. Pass --no-mentions to post the text literally.')
+        .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`.\n\nCHANNEL MENTIONS: HQ mentions are structured — the server never reads `@name` out of your text, so a channel message has to carry the participants alongside the body. When you write `@name` in a channel message, this command looks the name up in the channel roster (case-insensitive on display name and slug/handle; quote multi-word names as @"Jacob Posel") and sends it as a real mention, which notifies people and wakes agents. If a name is unknown or matches more than one member, the send FAILS with the candidates instead of posting something that mentions nobody. A bare "@" or an email address in your prose is never treated as a mention. Pass --no-mentions to post the text literally.\n\nCHANNEL THREADS: `hq dm <channel> --thread <eventId> "…"` replies under an existing root (the request carries rootEventId). `--thread last` replies to your most recent top-level message in that channel. Copy a root eventId from `hq dm channel <name>`, which prints each root\'s id and indents replies underneath.')
         .option("--channel <name>", "Post the message to one of your DM channels by name (e.g. --channel vyg-dev)")
         .option("--no-mentions", "Do not resolve `@name` in a channel message into structured mentions — post the text literally")
+        .option("--thread <eventId>", 'Reply in a channel thread. Pass a root eventId from `hq dm channel`, or `last` for your most recent top-level message in that channel')
         .option("--prompt <text>", "Agent-context prompt the recipient can one-click copy into their agent (1:1 DMs only)")
         .option("--prompt-file <path>", "Read the agent prompt from a file (1:1 DMs only)")
         .option("--details <text>", "Longer detail shown in the recipient's DM detail window (1:1 DMs only)")
@@ -1117,7 +1313,7 @@ export function registerDmCommand(program) {
     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`.")
+        .description("Show recent messages in a DM channel or group DM — by name, #name, or a channel id from `hq channels`. Roots print their eventId; replies indent under their root. --json is the raw oldest-first array (ungrouped).")
         .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")

package/dist/commands/mesh.js

@@ -6,6 +6,7 @@
  * Distinct from `hq doctor` (hook guardrails).
  */
 import * as os from "node:os";
+import { findHqRoot } from "../utils/manifest.js";
 import chalk from "chalk";
 import { loadCachedTokens, isMachineIdentity } from "../utils/cognito-session.js";
 import * as readline from "node:readline/promises";
@@ -324,6 +325,7 @@ async function runContextBackfillHeld(opts) {
     const result = await backfillHeldSessions({
         workMeshRoot: meshRoot,
         workContextRoot: root,
+        hqRoot: process.env.HQ_ROOT?.trim() || findHqRoot(),
         dryRun,
         limit,
         // Mirror the reconcile closure's non-forcing hint in the dry-run predictor
@@ -1181,7 +1183,10 @@ async function runDaemonRun() {
 async function runDaemonInstall(opts) {
     const result = installDaemonService({
         platform: detectPlatform(),
-        paths: buildInstallPaths({ systemUser: opts.systemUser }),
+        paths: buildInstallPaths({
+            systemUser: opts.systemUser,
+            hqRoot: process.env.HQ_ROOT?.trim() || findHqRoot(),
+        }),
         systemUser: opts.systemUser,
     });
     if (opts.json) {
@@ -1242,7 +1247,7 @@ async function runDaemonStatus(opts) {
     }
 }
 async function runDaemonDoctorCmd(opts) {
-    const report = collectDaemonDoctor();
+    const report = collectDaemonDoctor({ hqRoot: process.env.HQ_ROOT?.trim() || findHqRoot() });
     if (opts.json) {
         console.log(JSON.stringify({ ok: !report.unhealthy, ...report }, null, 2));
         return;

package/dist/commands/update.js

@@ -5,6 +5,7 @@
 import * as path from 'path';
 import { findHqRoot, readManifest, readLock, writeLock, getModulesDir } from '../utils/manifest.js';
 import { fetchRepo, pullRepo, getCurrentCommit, isRepo } from '../utils/git.js';
+import { restartDaemonServiceIfInstalled } from "../lib/mesh/live/daemon/install.js";
 export function registerUpdateCommand(program) {
     program
         .command('update [module-name]')
@@ -49,6 +50,11 @@ export function registerUpdateCommand(program) {
                 }
             }
             writeLock(hqRoot, lock);
+            // An installed daemon is a separate Node process. Refresh it
+            // best-effort after a successful update without making the update fail.
+            const restart = restartDaemonServiceIfInstalled();
+            if (restart.message)
+                console.log(restart.message);
             console.log('\nLock file updated.');
         }
         catch (error) {

package/dist/commands/whoami.d.ts

@@ -2,7 +2,7 @@
  * hq whoami — displays current user or 'not logged in'
  */
 import { Command } from 'commander';
-import { type PlanLockStatus } from "../lib/billing/plan-lock.js";
+import { type PlanLimitStatus } from "../lib/billing/plan-lock.js";
 export interface WhoamiTokenIdentity {
     email?: string;
     sub?: string;
@@ -25,6 +25,6 @@ export declare function resolveWhoamiIdentity(identity: WhoamiTokenIdentity): Wh
  * workspace is over its Starter limits, the one-line `Plan: Starter — …`
  * orientation when it is Starter and healthy, and nothing at all otherwise.
  */
-export declare function renderWhoamiPlanBlock(status: PlanLockStatus): string | null;
+export declare function renderWhoamiPlanBlock(status: PlanLimitStatus): string | null;
 export declare function registerWhoamiCommand(program: Command): void;
 //# sourceMappingURL=whoami.d.ts.map