@indigoai-us/hq-cli 5.313.0 → 5.314.0

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

@@ -1,585 +0,0 @@
-#!/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