@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/assets/scaffold/core/scripts/hq-dm-bind.sh

@@ -0,0 +1,585 @@
+#!/usr/bin/env bash
+# hq-dm-bind.sh — bind the current session to one HQ DM channel, post
+# structured updates to it, and listen for replies (feedback / requests).
+#
+# Usage:
+#   core/scripts/hq-dm-bind.sh bind <channel>                 # bind + set the read cursor to "now"
+#   core/scripts/hq-dm-bind.sh status                         # show the binding and cursor
+#   core/scripts/hq-dm-bind.sh post --title <t> [--state <s>] [--line <l>]... [--next <l>]... [--ask <l>]... [--to <name>]... [--topic <t>] [--under <id>] [--new-thread]
+#   core/scripts/hq-dm-bind.sh post --title <t> - < body.md    # body from stdin (already structured)
+#   core/scripts/hq-dm-bind.sh threads                        # list the channel's recent top-level threads (id, replies, author, text)
+#   core/scripts/hq-dm-bind.sh roster                         # print the channel members a post will @-mention
+#   core/scripts/hq-dm-bind.sh poll                           # print new messages since the cursor, advance it
+#   core/scripts/hq-dm-bind.sh listen [--interval 60] [--timeout 1800]
+#                                                             # block until a new message arrives (or timeout)
+#   core/scripts/hq-dm-bind.sh unbind
+#
+# The binding lives in the session's meta.yaml (`dm_channel`) via hq-session.sh;
+# the cursor is `workspace/sessions/<sid>/dm-bind.cursor` (the last seen sort
+# key from `hq dm channel --json`). `listen` is meant to run detached
+# (Bash run_in_background): it exits 0 and prints the new messages the moment
+# one lands, exits 3 on timeout with nothing new.
+#
+# Every post opens with an @-mention of every other member of the channel, so
+# the update reaches people (HQ mentions are structured: the `hq` CLI resolves
+# the `@"Display Name"` tokens against the roster and sends the real mention
+# list; an unresolvable name fails the post rather than posting text that looks
+# addressed but is not). The CLI rewrites a resolved `@"Display Name"` token to
+# `@Display Name`, so the room never shows the quotes.
+#
+# Posts thread by topic. The first post on a topic (`--topic`, else the title)
+# is a top-level root; every later post on the same topic in this session goes
+# out as a reply under it. `--under <id>` replies under an existing thread that
+# someone else (or an earlier session) started — a top-level post is only for a
+# subject the channel has no thread for yet. `--new-thread` starts a fresh root. The topic → root
+# map is `workspace/sessions/<sid>/dm-bind.threads`.
+#
+# A post ALWAYS mentions someone. `--to <name>` (repeatable) narrows the line to
+# the named members, for a reply to one person; without it the line names every
+# other human member (bots are left out unless named with --to, because a tagged
+# bot wakes and replies). There is no way to post unmentioned: an update nobody is
+# notified about does not get read. `post` refuses when the roster cannot be
+# read rather than sending a silent update.
+#
+# Post format (kept deliberately plain — see .claude/skills/dm-bind/SKILL.md):
+#   @"Ada Lovelace" @"Grace Hopper"
+#
+#   <title> — <state>
+#
+#   • line
+#   • line
+#
+#   Next: line
+#   Need from you: line
+set -euo pipefail
+
+HQ_ROOT="${HQ_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+SESSION_SH="$HQ_ROOT/core/scripts/hq-session.sh"
+
+die() { echo "hq-dm-bind: $*" >&2; exit 2; }
+need() { command -v "$1" >/dev/null 2>&1 || die "missing dependency: $1"; }
+need hq; need jq
+
+session_id() { bash "$SESSION_SH" current 2>/dev/null || true; }
+session_dir() {
+  local sid; sid="$(session_id)"
+  [ -n "$sid" ] || die "no current session (hq-session.sh current is empty)"
+  local d="$HQ_ROOT/workspace/sessions/$sid"; mkdir -p "$d"; echo "$d"
+}
+cursor_file() { echo "$(session_dir)/dm-bind.cursor"; }
+channel() { bash "$SESSION_SH" get dm_channel 2>/dev/null | tr -d '"' || true; }
+require_channel() {
+  local ch; ch="$(channel)"
+  [ -n "$ch" ] && [ "$ch" != "null" ] || die "session is not bound — run: core/scripts/hq-dm-bind.sh bind <channel>"
+  echo "$ch"
+}
+
+# Own address, used to skip our own posts when polling. Best effort.
+self_email() {
+  hq whoami 2>/dev/null | grep -oE '[[:alnum:]._+-]+@[[:alnum:].-]+\.[[:alpha:]]+' | head -1 || true
+}
+
+CLI_MIN_VERSION="5.137.0"
+
+# Human sessions have both legacy local Cognito files. Machine-principal
+# sessions use the hq CLI's machine token and do not have those files.
+has_cognito_session() {
+  [ -r "$HOME/.hq/config.json" ] && [ -r "$HOME/.hq/cognito-tokens.json" ]
+}
+
+uses_cli_auth() { ! has_cognito_session; }
+
+cli_version() {
+  local output version
+  if ! output="$(hq --version 2>/dev/null)"; then
+    echo "hq-dm-bind: could not read the installed hq-cli version" >&2
+    return 1
+  fi
+  version="$(printf '%s\n' "$output" | sed -nE 's/^CLI[[:space:]]+([0-9]+(\.[0-9]+){2}).*$/\1/p' | head -1)"
+  if [ -z "$version" ]; then
+    version="$(printf '%s\n' "$output" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true)"
+  fi
+  printf '%s' "$version"
+}
+
+version_at_least() {
+  local actual="$1" required="$2"
+  local a=0 b=0 c=0 ra=0 rb=0 rc=0
+  IFS=. read -r a b c <<< "$actual"
+  IFS=. read -r ra rb rc <<< "$required"
+  [ "${a:-0}" -gt "${ra:-0}" ] || {
+    [ "${a:-0}" -eq "${ra:-0}" ] && {
+      [ "${b:-0}" -gt "${rb:-0}" ] || {
+        [ "${b:-0}" -eq "${rb:-0}" ] && [ "${c:-0}" -ge "${rc:-0}" ]
+      }
+    }
+  }
+}
+
+require_cli_version() {
+  local actual
+  actual="$(cli_version)" || return 2
+  if [ -z "$actual" ] || ! version_at_least "$actual" "$CLI_MIN_VERSION"; then
+    echo "hq-dm-bind: hq-cli >= $CLI_MIN_VERSION is required for machine-principal DM binding (found ${actual:-unknown}); update hq-cli and retry." >&2
+    return 2
+  fi
+}
+
+cli_identity() {
+  local identity
+  if ! identity="$(hq whoami --json 2>/dev/null)"; then
+    echo "hq-dm-bind: could not read the hq-cli identity" >&2
+    return 1
+  fi
+  if ! printf '%s' "$identity" | jq -e 'type == "object"' >/dev/null 2>&1; then
+    echo "hq-dm-bind: hq-cli returned an invalid identity" >&2
+    return 1
+  fi
+  printf '%s' "$identity"
+}
+
+# Normalise `hq dm channel --json` to a JSON array of messages.
+fetch_items() {
+  local ch="$1" limit="${2:-30}"
+  hq dm channel "$ch" --limit "$limit" --json 2>/dev/null \
+    | jq -c 'if type=="array" then . else (.messages // .items // []) end' 2>/dev/null \
+    || echo '[]'
+}
+
+latest_sk() { fetch_items "$1" 5 | jq -r 'last // empty | .sk // empty'; }
+roster_file() { echo "$(session_dir)/dm-bind.roster"; }
+
+# The channel's members other than us, one display name<TAB>uid per line.
+# Machine-principal sessions use the CLI, while human sessions retain the
+# local-file path for compatibility. Fails soft after logging a CLI read error.
+fetch_roster() {
+  local ch="$1" me; me="$(self_email)"
+  if uses_cli_auth; then
+    require_cli_version || return $?
+    if ! hq channels members "$ch"; then
+      echo "hq-dm-bind: could not read the channel roster through hq-cli" >&2
+    fi
+    return 0
+  fi
+  command -v node >/dev/null 2>&1 || return 0
+  node - roster "$ch" "$me" <<'NODE' 2>/dev/null || true
+const fs = require("fs"), os = require("os"), path = require("path");
+const [, ch, me] = process.argv.slice(2);
+const home = os.homedir();
+const slug = (n) => String(n).trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+(async () => {
+  const cfg = JSON.parse(fs.readFileSync(path.join(home, ".hq", "config.json"), "utf8"));
+  const tok = JSON.parse(fs.readFileSync(path.join(home, ".hq", "cognito-tokens.json"), "utf8")).idToken;
+  const base = cfg.vaultApiUrl; const h = { Authorization: "Bearer " + tok };
+  const chans = await (await fetch(base + "/v1/notify/channels", { headers: h })).json();
+  const rows = Array.isArray(chans) ? chans : (chans.channels || []);
+  const hit = rows.find((c) => c.channelId === ch || slug(c.name || "") === slug(ch) || c.slug === slug(ch));
+  if (!hit) return;
+  const mem = await (await fetch(base + "/v1/notify/channels/" + encodeURIComponent(hit.channelId) + "/members", { headers: h })).json();
+  const list = Array.isArray(mem) ? mem : (mem.members || []);
+  for (const m of list) {
+    const email = String(m.email || "").toLowerCase();
+    if (me && email === me.toLowerCase()) continue;
+    const name = String(m.displayName || "").trim();
+    const uid = String(m.personUid || m.participantUid || m.uid || "").trim();
+    if (name) process.stdout.write(name + "\t" + uid + "\n");
+  }
+})().catch(() => {});
+NODE
+}
+
+# Refresh the cached roster; fall back to the cache when the fetch fails.
+roster() {
+  local ch="$1" rf; rf="$(roster_file)"
+  if uses_cli_auth; then require_cli_version || return $?; fi
+  local fresh; fresh="$(fetch_roster "$ch")"
+  if [ -n "$fresh" ]; then printf '%s\n' "$fresh" > "$rf"; fi
+  cut -f1 "$rf" 2>/dev/null || true
+}
+
+# The structured `mentions` array for a newline list of display names, built
+# from the cached roster rows (name<TAB>uid). `agt_*` uids are agents, every
+# other uid is a human — the server 400s when the type and the prefix disagree.
+mentions_json() {
+  local rf; rf="$(roster_file)"
+  jq -Rn --rawfile rows "$rf" '
+    ($rows | split("\n") | map(select(length>0) | split("\t")) | map({key:.[0], value:(.[1] // "")}) | from_entries) as $uid
+    | [inputs | select(length>0) | select(($uid[.] // "") != "")
+       | {participantUid:$uid[.], participantType:(if ($uid[.]|startswith("agt_")) then "agent" else "human" end), displayName:.}]'
+}
+
+threads_file() { echo "$(session_dir)/dm-bind.threads"; }
+topic_slug() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g'; }
+thread_root() { awk -F'\t' -v k="$1" '$1==k{v=$2} END{if(v!="")print v}' "$(threads_file)" 2>/dev/null || true; }
+
+# POST one message to the channel through the legacy notify API. Reads the JSON
+# payload from $1 and prints the new message's eventId. Machine-principal
+# sessions use send_cli_channel below.
+send_channel() {
+  local ch="$1" payload="$2"
+  node - send "$ch" "$payload" <<'NODE'
+const fs = require("fs"), os = require("os"), path = require("path");
+const [, ch, payload] = process.argv.slice(2);
+const home = os.homedir();
+const slug = (n) => String(n).trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+(async () => {
+  const cfg = JSON.parse(fs.readFileSync(path.join(home, ".hq", "config.json"), "utf8"));
+  const tok = JSON.parse(fs.readFileSync(path.join(home, ".hq", "cognito-tokens.json"), "utf8")).idToken;
+  const base = cfg.vaultApiUrl; const h = { Authorization: "Bearer " + tok, "Content-Type": "application/json" };
+  const chans = await (await fetch(base + "/v1/notify/channels", { headers: h })).json();
+  const rows = Array.isArray(chans) ? chans : (chans.channels || []);
+  const hit = rows.find((c) => c.channelId === ch || slug(c.name || "") === slug(ch) || c.slug === slug(ch));
+  if (!hit) throw new Error("channel not found: " + ch);
+  const res = await fetch(base + "/v1/notify/channels/" + encodeURIComponent(hit.channelId) + "/messages", { method: "POST", headers: h, body: payload });
+  const text = await res.text();
+  if (!res.ok) throw new Error("post failed: HTTP " + res.status + " " + text.slice(0, 300));
+  let j = {}; try { j = JSON.parse(text); } catch {}
+  const m = j.message || j.event || j;
+  const id = m.eventId || (typeof m.sk === "string" && m.sk.includes("#") ? m.sk.split("#").pop() : "");
+  process.stdout.write(String(id || ""));
+})().catch((e) => { process.stderr.write("hq-dm-bind: " + e.message + "\n"); process.exit(1); });
+NODE
+}
+
+# The CLI prints a human confirmation rather than the created event id. Read
+# the channel back and use the newest message from this CLI identity so topic
+# replies can keep using the existing thread map.
+latest_cli_event_id() {
+  local ch="$1" identity agent username person email
+  identity="$(cli_identity)" || return 1
+  agent="$(printf '%s' "$identity" | jq -r '.agentUid // empty')"
+  username="$(printf '%s' "$identity" | jq -r '.username // empty')"
+  person="$(printf '%s' "$identity" | jq -r '.personUid // empty')"
+  email="$(printf '%s' "$identity" | jq -r '.email // empty')"
+  fetch_items "$ch" 50 | jq -r \
+    --arg agent "$agent" --arg username "$username" --arg person "$person" --arg email "$email" '
+      [ .[]
+        | select(
+            if ($agent != "" or $username != "") then
+              (((.senderMachineUid // .fromMachineUid // "") == $agent)
+                or ((.senderMachineUid // .fromMachineUid // "") == $username))
+            elif $person != "" then
+              ((.fromPersonUid // "") == $person)
+            elif $email != "" then
+              ((.fromEmail // "" | ascii_downcase) == ($email | ascii_downcase))
+            else false
+            end
+          )
+        | (.eventId // .messageId // "")
+      ] | last // empty'
+}
+
+send_cli_channel() {
+  local ch="$1" body="$2" root="$3"
+  require_cli_version || return $?
+  local -a args=(dm "$ch")
+  if [ -n "$root" ]; then args+=(--thread "$root"); fi
+  args+=("$body")
+  if ! hq "${args[@]}" >/dev/null; then
+    echo "hq-dm-bind: hq dm failed — nothing was sent" >&2
+    return 1
+  fi
+  local event_id
+  event_id="$(latest_cli_event_id "$ch")" || return 1
+  if [ -z "$event_id" ]; then
+    echo "hq-dm-bind: post succeeded but its event id could not be read back" >&2
+    return 1
+  fi
+  printf '%s' "$event_id"
+}
+
+# The @-mention line: one quoted token per member so multi-word names resolve.
+# The quotes are input syntax only — the `hq` CLI strips them once the name
+# resolves, so the room reads `@Ada Lovelace`. With no extra args it names every
+# other member; extra args narrow it to those members, matched case-insensitively
+# against the roster (exact display name first, then a unique partial match).
+# Exit 4: roster unreadable. Exit 5: a --to name matched nobody or several.
+mention_line() {
+  local ch="$1"; shift
+  local names line="" n
+  names="$(roster "$ch")"
+  [ -n "$names" ] || return 4
+  if [ $# -eq 0 ]; then
+    # Default: the people, not the bots. A tagged bot wakes and answers, and a
+    # round of "no response needed" replies under every update is the clutter
+    # threads exist to prevent. Name a bot with --to when the post is for it.
+    local humans; humans="$(awk -F'\t' '$2 !~ /^agt_/ {print $1}' "$(roster_file)" 2>/dev/null || true)"
+    [ -n "$humans" ] || humans="$names"
+    while IFS= read -r n; do [ -n "$n" ] && line="$line @\"$n\""; done <<< "$humans"
+  else
+    local want hit count
+    for want in "$@"; do
+      want="${want#@}"
+      hit="$(printf '%s\n' "$names" | grep -ixF -- "$want" | head -1 || true)"
+      if [ -z "$hit" ]; then
+        count="$(printf '%s\n' "$names" | grep -icF -- "$want" || true)"
+        if [ "$count" = 1 ]; then hit="$(printf '%s\n' "$names" | grep -iF -- "$want")"; fi
+      fi
+      if [ -z "$hit" ]; then
+        echo "hq-dm-bind: --to '$want' does not match exactly one channel member. Members:" >&2
+        printf '%s\n' "$names" | sed 's/^/  /' >&2
+        return 5
+      fi
+      case "$line" in *"@\"$hit\""*) ;; *) line="$line @\"$hit\"" ;; esac
+    done
+  fi
+  printf '%s' "${line# }"
+}
+
+cmd_bind() {
+  local ch="${1:-}"; [ -n "$ch" ] || die "bind needs a channel name (see: hq channels)"
+  ch="${ch#\#}"
+  hq channels 2>/dev/null | grep -q -- "hq dm $ch " || die "no channel named '$ch' (see: hq channels)"
+  bash "$SESSION_SH" set dm_channel "$ch" >/dev/null
+  local sk; sk="$(latest_sk "$ch")"
+  printf '%s\n' "$sk" > "$(cursor_file)"
+  local names; names="$(roster "$ch")"
+  local n; n="$(printf '%s' "$names" | grep -c . || true)"
+  echo "bound session $(session_id) to #$ch (cursor: ${sk:-<empty>}; will @-mention $n member(s))"
+  [ "$n" -gt 0 ] || echo "hq-dm-bind: could not read the channel roster — posts will not @-mention anyone until it is readable" >&2
+}
+
+cmd_roster() {
+  local ch; ch="$(require_channel)"
+  roster "$ch"
+}
+
+# Recent top-level messages (thread roots) in the bound channel, newest last:
+# "<id8>  <replies>  <author>: <first 90 chars>". Read this BEFORE starting a
+# new topic — if a thread for the subject already exists, reply under it.
+recent_roots() { fetch_items "$1" 100 | jq -c 'map(select((.rootEventId // "") == ""))'; }
+cmd_threads() {
+  local ch; ch="$(require_channel)"
+  recent_roots "$ch" | jq -r '.[-25:] | .[] | [(.eventId[0:8]), ((.replyCount // 0)|tostring), ((.fromDisplayName // "?") + ": " + ((.body // "") | gsub("\\s+";" ") | .[0:90]))] | @tsv'
+}
+# Resolve --under: a full event id, or a unique id prefix of a recent root.
+resolve_root() {
+  local ch="$1" want="$2" hits
+  hits="$(recent_roots "$ch" | jq -r --arg w "$want" '.[] | select(.eventId | startswith($w)) | .eventId')"
+  [ -n "$hits" ] || { echo "hq-dm-bind: --under '$want' matches no recent top-level message (see: hq-dm-bind.sh threads)" >&2; return 1; }
+  [ "$(printf '%s\n' "$hits" | wc -l | tr -d ' ')" = 1 ] || { echo "hq-dm-bind: --under '$want' matches several messages — use more of the id" >&2; return 1; }
+  printf '%s' "$hits"
+}
+
+cmd_unbind() {
+  bash "$SESSION_SH" set dm_channel "" >/dev/null
+  rm -f "$(cursor_file)" "$(roster_file)" "$(threads_file)"
+  echo "unbound"
+}
+
+cmd_status() {
+  local ch; ch="$(channel)"
+  echo "session:  $(session_id)"
+  echo "channel:  ${ch:-<none>}"
+  echo "cursor:   $(cat "$(cursor_file)" 2>/dev/null || echo '<none>')"
+}
+
+cmd_post() {
+  local ch; ch="$(require_channel)"
+  local title="" state="" body_from_stdin=0 topic="" new_thread=0 under="" allow_long=0
+  local -a lines=() nexts=() asks=() tos=()
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --topic) topic="$2"; shift 2 ;;
+      --new-thread) new_thread=1; shift ;;
+      --under) [ -n "${2:-}" ] || die "post: --under needs a message id (see: threads)"; under="$2"; shift 2 ;;
+      --to) [ -n "${2:-}" ] || die "post: --to needs a member name"; tos+=("$2"); shift 2 ;;
+      --no-mention) die "post: --no-mention was removed — every post @-mentions someone. Use --to <name> to address specific members." ;;
+      --title) title="$2"; shift 2 ;;
+      --state) state="$2"; shift 2 ;;
+      --line)  lines+=("$2"); shift 2 ;;
+      --next)  nexts+=("$2"); shift 2 ;;
+      --ask)   asks+=("$2"); shift 2 ;;
+      --allow-long) allow_long=1; shift ;;
+      -)       body_from_stdin=1; shift ;;
+      *) die "post: unknown arg $1" ;;
+    esac
+  done
+  [ -n "$title" ] || die "post needs --title"
+
+  # Length guard — refuse before any network call so nothing partial is sent.
+  # Override with --allow-long only when the post genuinely must be longer.
+  if [ "$allow_long" != 1 ] && [ "$body_from_stdin" != 1 ]; then
+    local _guard_fail=0 _len _preview
+    if [ "${#lines[@]}" -gt 6 ]; then
+      echo "hq-dm-bind: too many --line bullets (${#lines[@]}, limit 6). Put extra detail in workspace/reports/<name>.md and link it in one bullet. Use --allow-long to override." >&2
+      _guard_fail=1
+    fi
+    if [ "${#nexts[@]}" -gt 2 ]; then
+      echo "hq-dm-bind: too many --next items (${#nexts[@]}, limit 2). Use --allow-long to override." >&2
+      _guard_fail=1
+    fi
+    if [ "${#asks[@]}" -gt 1 ]; then
+      echo "hq-dm-bind: too many --ask items (${#asks[@]}, limit 1). Use --allow-long to override." >&2
+      _guard_fail=1
+    fi
+    for _l in "${lines[@]}"; do
+      _len="$(printf '%s' "$_l" | wc -c | tr -d ' ')"
+      if [ "$_len" -gt 140 ]; then
+        _preview="$(printf '%s' "$_l" | cut -c1-60)"
+        echo "hq-dm-bind: --line too long ($_len chars, limit 140): \"$_preview\". Put the detail in workspace/reports/<name>.md and reference the path in one line. Use --allow-long to override." >&2
+        _guard_fail=1
+      fi
+    done
+    for _l in "${nexts[@]}"; do
+      _len="$(printf '%s' "$_l" | wc -c | tr -d ' ')"
+      if [ "$_len" -gt 140 ]; then
+        _preview="$(printf '%s' "$_l" | cut -c1-60)"
+        echo "hq-dm-bind: --next too long ($_len chars, limit 140): \"$_preview\". Put the detail in workspace/reports/<name>.md and reference the path in one line. Use --allow-long to override." >&2
+        _guard_fail=1
+      fi
+    done
+    for _l in "${asks[@]}"; do
+      _len="$(printf '%s' "$_l" | wc -c | tr -d ' ')"
+      if [ "$_len" -gt 140 ]; then
+        _preview="$(printf '%s' "$_l" | cut -c1-60)"
+        echo "hq-dm-bind: --ask too long ($_len chars, limit 140): \"$_preview\". Put the detail in workspace/reports/<name>.md and reference the path in one line. Use --allow-long to override." >&2
+        _guard_fail=1
+      fi
+    done
+    [ "$_guard_fail" = 0 ] || exit 2
+  fi
+  local msg="$title"; [ -n "$state" ] && msg="$title — $state"
+  if [ "$body_from_stdin" = 1 ]; then
+    msg="$msg"$'\n\n'"$(cat)"
+  else
+    if [ ${#lines[@]} -gt 0 ]; then
+      msg="$msg"$'\n'
+      for l in "${lines[@]}"; do msg="$msg"$'\n'"• $l"; done
+    fi
+    if [ ${#nexts[@]} -gt 0 ]; then
+      msg="$msg"$'\n'
+      for l in "${nexts[@]}"; do msg="$msg"$'\n'"Next: $l"; done
+    fi
+    if [ ${#asks[@]} -gt 0 ]; then
+      msg="$msg"$'\n'
+      for l in "${asks[@]}"; do msg="$msg"$'\n'"Need from you: $l"; done
+    fi
+  fi
+  local ml rc=0
+  if [ ${#tos[@]} -gt 0 ]; then ml="$(mention_line "$ch" "${tos[@]}")" || rc=$?
+  else ml="$(mention_line "$ch")" || rc=$?; fi
+  [ "$rc" != 5 ] || exit 2
+  [ "$rc" = 0 ] && [ -n "$ml" ] || die "could not read the channel roster — not posting an update that notifies nobody (check \`hq whoami\` and that node is on PATH, then retry)"
+  # The room shows `@Ada Lovelace`; the quotes only ever existed as CLI syntax
+  # for the hq CLI path. Keep the quoted form for CLI mention resolution.
+  local shown names_nl posted_msg cli_msg
+  shown="$(printf '%s' "$ml" | sed -E 's/@"([^"]+)"/@\1/g')"
+  names_nl="$(printf '%s' "$ml" | grep -oE '@"[^"]+"' | sed -E 's/^@"//; s/"$//')"
+  posted_msg="$shown"$'\n\n'"$msg"
+  cli_msg="$ml"$'\n\n'"$msg"
+  msg="$posted_msg"
+
+  # Total body length check (counts what the receipt prints — mention line included).
+  if [ "$allow_long" != 1 ]; then
+    local _total; _total="$(printf '%s' "$msg" | wc -c | tr -d ' ')"
+    if [ "$_total" -gt 600 ]; then
+      echo "hq-dm-bind: post body too long ($_total chars, limit 600). Put the detail in workspace/reports/<name>.md and reference the path in one line. Use --allow-long to override." >&2
+      exit 2
+    fi
+  fi
+
+  # One thread per topic: the first post on a topic is the root, every later
+  # post on it is a reply under that root, so the room stays scannable.
+  local key root=""
+  key="$(topic_slug "${topic:-$title}")"
+  if [ -n "$under" ]; then
+    # Reply under someone else's (or an earlier) thread, and keep this topic there.
+    root="$(resolve_root "$ch" "$under")" || exit 2
+    [ "$(thread_root "$key")" = "$root" ] || printf '%s\t%s\n' "$key" "$root" >> "$(threads_file)"
+  elif [ "$new_thread" != 1 ]; then
+    root="$(thread_root "$key")"
+  fi
+  local eid
+  if uses_cli_auth; then
+    eid="$(send_cli_channel "$ch" "$cli_msg" "$root")" || die "post failed — nothing was sent"
+  else
+    local payload
+    payload="$(printf '%s\n' "$names_nl" | mentions_json | jq -c --arg body "$msg" --arg root "$root" \
+      '{body:$body, mentions:.} + (if $root != "" then {rootEventId:$root} else {} end)')"
+    [ "$(printf '%s' "$payload" | jq '.mentions | length')" -gt 0 ] || die "no mention resolved to a channel member id — not posting an update that notifies nobody"
+    eid="$(send_channel "$ch" "$payload")" || die "post failed — nothing was sent"
+  fi
+  if [ -z "$root" ]; then
+    [ -n "$eid" ] && printf '%s\t%s\n' "$key" "$eid" >> "$(threads_file)"
+    echo "thread: new topic '$key'${eid:+ (root $eid)}"
+  else
+    echo "thread: reply under topic '$key'"
+  fi
+  # Our own post must not come back as "new" on the next poll.
+  latest_sk "$ch" > "$(cursor_file)"
+  echo "posted to #$ch ($(printf '%s' "$msg" | wc -c | tr -d ' ') chars)"
+}
+
+# Prints new messages (not ours) since the cursor as "<time> <name>: <body>",
+# advances the cursor. Exit 0 if any printed, 3 if none.
+cmd_poll() {
+  local ch; ch="$(require_channel)"
+  local cf; cf="$(cursor_file)"
+  local cursor; cursor="$(cat "$cf" 2>/dev/null || true)"
+  local items; items="$(fetch_items "$ch" 50)"
+  local last; last="$(printf '%s' "$items" | jq -r 'last // empty | .sk // empty')"
+  local msgs
+  if uses_cli_auth; then
+    local identity agent username person email
+    identity="$(cli_identity)" || die "could not read the hq-cli identity — not polling"
+    agent="$(printf '%s' "$identity" | jq -r '.agentUid // empty')"
+    username="$(printf '%s' "$identity" | jq -r '.username // empty')"
+    person="$(printf '%s' "$identity" | jq -r '.personUid // empty')"
+    email="$(printf '%s' "$identity" | jq -r '.email // empty')"
+    msgs="$(printf '%s' "$items" | jq -r \
+      --arg cur "$cursor" --arg agent "$agent" --arg username "$username" --arg person "$person" --arg email "$email" '
+        map(select((.sk // "") > $cur and
+          (if ($agent != "" or $username != "") then
+             (((.senderMachineUid // .fromMachineUid // "") != $agent)
+               and ((.senderMachineUid // .fromMachineUid // "") != $username))
+           elif $person != "" then
+             ((.fromPersonUid // "") != $person)
+           elif $email != "" then
+             ((.fromEmail // "" | ascii_downcase) != ($email | ascii_downcase))
+           else true
+           end)))
+        | .[]
+        | ((.sk // "")[0:16] | sub("T"; " ")) + "Z " + (.fromDisplayName // .fromEmail // "?") + ": " + ((.body // "") | gsub("^\\s+|\\s+$"; ""))')"
+  else
+    local me; me="$(self_email)"
+    msgs="$(printf '%s' "$items" | jq -r --arg cur "$cursor" --arg me "$me" '
+      map(select((.sk // "") > $cur and ($me == "" or .fromEmail != $me)))
+      | .[]
+      | ((.sk // "")[0:16] | sub("T"; " ")) + "Z " + (.fromDisplayName // .fromEmail // "?") + ": " + ((.body // "") | gsub("^\\s+|\\s+$"; ""))')"
+  fi
+  [ -n "$last" ] && printf '%s\n' "$last" > "$cf"
+  if [ -n "$(printf '%s' "$msgs" | tr -d '[:space:]')" ]; then printf '%s\n' "$msgs"; return 0; fi
+  return 3
+}
+
+cmd_listen() {
+  local interval=60 timeout=1800
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --interval) interval="$2"; shift 2 ;;
+      --timeout)  timeout="$2"; shift 2 ;;
+      *) die "listen: unknown arg $1" ;;
+    esac
+  done
+  local ch; ch="$(require_channel)"
+  local deadline=$(( $(date +%s) + timeout ))
+  echo "listening on #$ch every ${interval}s (timeout ${timeout}s)"
+  while [ "$(date +%s)" -lt "$deadline" ]; do
+    if cmd_poll; then echo "--- new message(s) on #$ch; handle them, then re-run listen"; return 0; fi
+    sleep "$interval"
+  done
+  echo "no new messages on #$ch within ${timeout}s"; return 3
+}
+
+case "${1:-}" in
+  bind)   shift; cmd_bind "$@" ;;
+  unbind) cmd_unbind ;;
+  status) cmd_status ;;
+  post)   shift; cmd_post "$@" ;;
+  roster) cmd_roster ;;
+  threads) cmd_threads ;;
+  poll)   cmd_poll ;;
+  listen) shift; cmd_listen "$@" ;;
+  *) sed -n '2,25p' "$0"; exit 2 ;;
+esac