@pingroom/cli 0.6.2 → 0.7.2

package/bin/pingroom.js

@@ -19,10 +19,11 @@
 //   handoff  Hand a decision to a specific human (ack or question) and, with
 //            --wait, block until they acknowledge / answer.
 //   handoffs List the agent's open handoffs or bounded recent history.
+//   listen   Long-poll for pings arriving in the agent's rooms.
 //   live     Drive a live progress card (iOS Live Activity / Android live
 //            update) on the room members' lock screen: start / update / end.
 //   mcp      Print the canonical remote MCP endpoint and client setup snippets.
-//   activate Retry Agent Inbox activation with the saved QR-paired credential.
+//   activate Send one optional test Question with the saved QR-paired credential.
 //   config   Read/write ~/.pingroom/config.json (default_room, api_url).
 //   logout   Forget the credential in ~/.pingroom/credentials.json.
 //
@@ -40,13 +41,17 @@ import { join } from 'node:path';
 // Kept in lockstep with package.json / package-lock.json. The GitHub Action is
 // pinned independently to the latest version already published on npm; a test
 // makes that release gate explicit. `hook --print-config` emits this candidate.
-const VERSION = '0.6.2';
+const VERSION = '0.7.2';
 
 const BUILTIN_API = 'https://api.pingroom.io';
 const MCP_ENDPOINT = `${BUILTIN_API}/api/agent/mcp`;
 const DEFAULT_API = process.env.PINGROOM_API_URL || BUILTIN_API;
 
-const HELP = `pingroom — send a ping, or ask a human a question, from CI/scripts/agents
+// The help text lives as one section per command plus intro/shared/tail, so
+// `pingroom <command> --help` can print a focused excerpt (see commandHelp).
+// The full HELP below joins them in the historical order — `pingroom --help`
+// output is byte-identical to the pre-split single blob.
+const HELP_INTRO = `pingroom — send a ping, or ask a human a question, from CI/scripts/agents
 
 Usage:
   pingroom <command> [options]
@@ -60,6 +65,7 @@ Commands:
   handoff  Hand a decision (ack or question) to a specific human; with --wait,
            block until they acknowledge or answer
   handoffs List the agent's open handoffs or bounded recent history
+  listen   Block on pings arriving in your rooms and print them as they land
   live     Drive a live progress card on the lock screen (Live Activity)
   hook     Claude Code hook: ping on Stop/Notification, and route tool
            permission prompts to a PingRoom question you answer from your phone
@@ -67,9 +73,9 @@ Commands:
            Claude Desktop
   activate Retry Agent Inbox activation with the saved QR-paired credential
   config   Read/write local settings (config list | get <key> | set <key> <val>)
-  logout   Forget the stored credential
+  logout   Forget the stored credential`;
 
-ping options:
+const HELP_PING = `ping options:
   -m, --message <text>   Ping body text (required)
   -t, --title <text>     Ping title (<= 40 chars)
   -a, --action <1-4>     Quick-action slot to attribute the ping to
@@ -82,9 +88,9 @@ ping options:
                          repeat for up to 4. Requires --token and a Pro account
   -w, --webhook <url>    Room webhook URL (or env PINGROOM_WEBHOOK_URL)
       --token <token>    Agent access token (or env PINGROOM_TOKEN)
-      --room <code>      Room invite code (used with --token)
+      --room <code>      Room invite code (used with --token)`;
 
-ask options (agent token required):
+const HELP_ASK = `ask options (agent token required):
   -p, --prompt <text>    The question a human reads (required)
   -o, --option <v:label[:style]>
                          An answer option (style: primary|danger|default);
@@ -100,12 +106,12 @@ ask options (agent token required):
   -d, --data <json>      Structured data object echoed back on the answer
       --correlation-id <id>  Opaque id echoed on every read of this question
       --reply-to <id>    Id of the ping this question replies to
-      --room <code>      Room invite code (required for ask)
+      --room <code>      Room invite code (required for ask)`;
 
-list options:
-      --state <s>        pending | answered | expired | cancelled | all
+const HELP_LIST = `list options:
+      --state <s>        pending | answered | expired | cancelled | all`;
 
-handoff options (agent token required; consent scope pingroom:handoffs:create):
+const HELP_HANDOFF = `handoff options (agent token required; consent scope pingroom:handoffs:create):
   -m, --message <text>   The prompt a human reads (required)
       --question         Make it a question (else a simple acknowledge). Also
                          implied whenever one or more --option is given.
@@ -119,15 +125,24 @@ handoff options (agent token required; consent scope pingroom:handoffs:create):
   -d, --data <json>      Structured data object echoed on the handoff
       --wait             Block until acked / answered / expired / cancelled
       --timeout <sec>    Per long-poll hold with --wait (0–20, server caps 25)
-      --github-output <path>  Safely append handoff outputs for GitHub Actions
+      --github-output <path>  Safely append handoff outputs for GitHub Actions`;
 
-handoffs options (agent token required; consent scope pingroom:handoffs:create):
-      --state <s>        open | all (default open)
+const HELP_HANDOFFS = `handoffs options (agent token required; consent scope pingroom:handoffs:create):
+      --state <s>        open | all (default open)`;
 
-live <start|update|end|get> options (agent token, or a room webhook):
+const HELP_LISTEN = `listen options (agent token required; consent scope pingroom:notifications:read):
+      --timeout <sec>    Per long-poll hold (0-30, default 25)
+      --limit <n>        Max pings per batch (1-100, default 50)
+      --from <id>        Start after this ping id instead of "now"
+      --once             Print one batch and exit instead of blocking forever
+      --json             One JSON object per line instead of a readable line`;
+
+const HELP_LIVE = `live <start|update|end|get> options (agent token, or a room webhook):
   -c, --correlation-id <id>  The stream key — reuse it for every ping (required)
       --template <name>      start only: status | steps | progress | metrics |
-                             countdown | question | matchup (fixed at creation)
+                             countdown | decision | matchup (fixed at creation;
+                             'decision' is the app's name for the wire id
+                             'question', which is still accepted)
       --category <name>      start only: status | steps | alert. Legacy, but
                              'alert' has no template equivalent and is the only
                              way to start time-sensitive without --require-ack
@@ -138,50 +153,52 @@ live <start|update|end|get> options (agent token, or a room webhook):
       --metric <label:value> Repeatable, up to 3 (metrics template)
       --deadline-at <epoch>  Countdown target (countdown template)
       --eta-at <epoch>       Live ETA (status/progress templates)
-      --prompt <text>        The ask (question template)
-      --option <value:label> Repeatable, up to 4 (question template). A bare
+      --prompt <text>        The ask (decision template)
+      --option <value:label> Repeatable, up to 4 (decision template). A bare
                              token is both value and label
       --left <label:value>   Left side (matchup template)
       --right <label:value>  Right side (matchup template)
       --center <text>        Center score/clock, <= 40 (matchup template)
       --accent-override <#rrggbb>  Semantic accent for this frame
       --failed               end only: finish as failed instead of done
+  -d, --data <json>          Structured data object carried on this frame
   -t, --title <text>         Card title (<= 40 chars)
   -a, --action <1-4>         Quick-action slot supplying the icon and sound
       --require-ack          Add an Acknowledge button
       --ack-timeout <s>      Ack deadline in seconds
       --room <code>          Room invite code (used with --token)
-  -w, --webhook <url>        Room webhook URL instead of a token
+  -w, --webhook <url>        Room webhook URL instead of a token`;
 
-hook options (reads a Claude Code event; defaults to stored credentials/config):
+const HELP_HOOK = `hook options (reads a Claude Code event; defaults to stored credentials/config):
       --room <code>      Room invite code (or env/config/paired room)
       --ttl <seconds>    Approval-question expiry for PreToolUse (default 900)
       --quiet            Suppress the informational stderr lines
-      --print-config     Print a ready-to-paste ~/.claude/settings.json block
+      --print-config     Print a ready-to-paste ~/.claude/settings.json block`;
 
-mcp:
+const HELP_MCP = `mcp:
   pingroom mcp                     Print the endpoint and client setup snippets
   pingroom mcp add claude-code     Print the Claude Code setup command
-                                   (output-only; does not change client config)
+                                   (output-only; does not change client config)`;
 
-activate:
-  pingroom activate                Replay or create the next Agent Inbox test using
-                                   the saved QR-paired credential
+const HELP_ACTIVATE = `activate:
+  pingroom activate                Send one test Question to your phone to prove the
+                                   saved QR-paired credential works (optional —
+                                   connecting no longer does this for you)`;
 
-config options:
+const HELP_CONFIG = `config options:
   pingroom config list              Print the stored settings
   pingroom config get <key>         Print one setting
   pingroom config set <key> <val>   Store a setting (an empty value clears it)
-  Keys: default_room, api_url
+  Keys: default_room, api_url`;
 
-Shared:
+const HELP_SHARED = `Shared:
       --token <token>    Agent access token (or env PINGROOM_TOKEN)
       --api <url>        API base URL (default ${DEFAULT_API}; env PINGROOM_API_URL)
       --json             Print the raw JSON response
   -h, --help             Show this help
-  -v, --version          Show the CLI version
+  -v, --version          Show the CLI version`;
 
-Connecting:
+const HELP_TAIL = `Connecting:
   Install globally, then run with no arguments:
     npm install --global @pingroom/cli
     pingroom
@@ -190,11 +207,10 @@ Connecting:
     npx --yes @pingroom/cli
 
   It prints a QR code you scan with the PingRoom app — you pick the account and
-  delivery room there. Once paired, it saves the credential, sends one test
-  Question, and waits briefly for the server to confirm the completed phone
-  round-trip; an answer alone is not treated as activation, and a setup problem
-  never discards the usable connection. Run "pingroom activate" to retry that
-  test later. The emailed-code fallback stores no server-side delivery room.
+  the rooms it may reach there (one, several, or all of them). Once paired, it
+  saves the credential and you are done; connecting sends nothing to your phone.
+  Run "pingroom activate" if you want to prove the round-trip with one test
+  Question. The emailed-code fallback stores no server-side delivery room.
   "config set default_room" enables room-addressed commands, but private
   Inbox/Handoff delivery requires QR pairing.
   There is no "login" command: being unconnected is a state the tool resolves,
@@ -280,6 +296,54 @@ or the recipient was not ready (409 recipient_not_ready). A question answered
 with ANY value — including a negative one like 'hold' or 'deny' — exits 0: a
 human decision is not an infrastructure failure.`;
 
+const HELP = [
+  HELP_INTRO, HELP_PING, HELP_ASK, HELP_LIST, HELP_HANDOFF, HELP_HANDOFFS,
+  HELP_LISTEN, HELP_LIVE, HELP_HOOK, HELP_MCP, HELP_ACTIVATE, HELP_CONFIG,
+  HELP_SHARED, HELP_TAIL,
+].join('\n\n');
+
+// Sections for `pingroom <command> --help`. watch/cancel/logout have no block
+// of their own in the full help, so they get a minimal one here.
+const COMMAND_HELP_SECTIONS = {
+  ping: HELP_PING,
+  ask: HELP_ASK,
+  watch: `watch:
+  pingroom watch <question-id>      Block until the question resolves and
+                                    print the outcome
+      --timeout <sec>    Per long-poll hold (0–30, default 25)`,
+  cancel: `cancel:
+  pingroom cancel <question-id>     Withdraw a pending question`,
+  list: HELP_LIST,
+  handoff: HELP_HANDOFF,
+  handoffs: HELP_HANDOFFS,
+  listen: HELP_LISTEN,
+  live: HELP_LIVE,
+  hook: HELP_HOOK,
+  activate: HELP_ACTIVATE,
+  config: HELP_CONFIG,
+  logout: `logout:
+  pingroom logout                   Forget the stored credential (PINGROOM_TOKEN
+                                    in the environment is unaffected)`,
+};
+
+// config and logout are local-only commands that reject --token/--api (and,
+// for logout, --json), so their help gets a footer that only lists what they
+// actually accept instead of the full shared block.
+const COMMAND_HELP_FOOTERS = {
+  config: `Shared:
+      --json             Print the raw JSON response
+  -h, --help             Show this help`,
+  logout: `Shared:
+  -h, --help             Show this help`,
+};
+
+// `<command> --help`: that command's section plus the shared flags, instead of
+// the full reference `pingroom --help` / `pingroom help` still print.
+function commandHelp(name) {
+  const section = COMMAND_HELP_SECTIONS[name];
+  return section ? `${section}\n\n${COMMAND_HELP_FOOTERS[name] ?? HELP_SHARED}` : HELP;
+}
+
 const EXIT = { OK: 0, ERROR: 1, USAGE: 2, EXPIRED: 3, CANCELLED: 4 };
 
 function fail(message, code = EXIT.ERROR) {
@@ -287,6 +351,35 @@ function fail(message, code = EXIT.ERROR) {
   process.exit(code);
 }
 
+/**
+ * The fixes that live on THIS side of the wire. The server's message always
+ * leads; these are appended only for the codes where the operator would
+ * otherwise have no way to know what to do next, and where the answer is a
+ * local action rather than "try again".
+ */
+const API_HINTS = {
+  room_not_granted:
+    'That room is outside the grant this agent was given. Add it under Connected Agents in the PingRoom app, or run "pingroom" to reconnect and pick it.',
+  insufficient_scope:
+    'This credential was approved before the command needed that permission. Run "pingroom" to reconnect and re-approve.',
+  no_room_configured:
+    'This agent has no delivery room. Pick one under Connected Agents in the PingRoom app.',
+};
+
+/**
+ * What to print when an API call fails: the server's own wording, plus the one
+ * thing that would fix it when we know one.
+ */
+function apiDetail(res, json) {
+  // The server's wording is untrusted text headed for the terminal — strip
+  // escapes so a hostile API can't smuggle ANSI (same threat model as pair_url).
+  const base = stripControlChars(
+    (json && (json.message || json.error || json.code)) || `HTTP ${res ? res.status : 'error'}`,
+  );
+  const hint = json && typeof json.code === 'string' ? API_HINTS[json.code] : undefined;
+  return hint ? `${base}\n  ${hint}` : base;
+}
+
 // --- local state (~/.pingroom) ---------------------------------------------
 //
 // Two files, both under a 0700 directory:
@@ -462,16 +555,86 @@ function sleep(ms) {
 // Drop C0/C1 control characters before echoing server-supplied text to the
 // terminal. Without this an attacker-controlled API base can smuggle ANSI
 // escapes into the output and repaint, erase or overwrite the lines around them.
+/**
+ * Reject an over-long field here rather than letting it become a 422.
+ *
+ * Every bound mirrors a Laravel rule (StoreNotificationRequest,
+ * StoreQuestionRequest, LiveStatusRules) and is documented in --help, so a value
+ * past it was always going to be refused — locally it reads as the usage error
+ * it is, with the limit and the actual length named.
+ */
+function requireMaxLength(value, max, flag) {
+  if (typeof value === 'string' && value.length > max) {
+    fail(`${flag} must be at most ${max} characters (got ${value.length})`, EXIT.USAGE);
+  }
+}
+
+/**
+ * Validate --timeout and resolve the per-poll hold. Called by ask/handoff
+ * BEFORE the create POST: the old in-wait check ran only after the question or
+ * handoff already existed, so `--timeout -5` put a live question on someone's
+ * phone and then exited 2, orphaning it until its TTL.
+ */
+function resolveWaitHold(args, { def, cap }) {
+  if (args.timeout === undefined) return Math.min(def, cap);
+  const hold = Number(args.timeout);
+  if (!Number.isFinite(hold) || hold < 0) fail('--timeout must be a non-negative integer', EXIT.USAGE);
+  return Math.min(hold, cap);
+}
+
 function stripControlChars(value) {
   // eslint-disable-next-line no-control-regex
   return String(value).replace(/[\u0000-\u001F\u007F-\u009F]/g, '');
 }
 
+// --- argument parsing -------------------------------------------------------
+
+/**
+ * Build an argv parser from a flag table. Every command parser runs the same
+ * loop; only the tables differ:
+ *   aliases              flag or alias -> canonical args key
+ *   booleans             keys that take no value
+ *   repeatable           keys collected into an array (the flag may repeat)
+ *   bareDashIsPositional whether a lone `-` collects into `_` (the question-
+ *                        style parsers) or fails as an unknown option (ping,
+ *                        live)
+ * Unknown flags always fail as a usage error; bare words collect into `_`.
+ */
+function makeParser({ aliases, booleans, repeatable = [], bareDashIsPositional = false }) {
+  const booleanKeys = new Set(booleans);
+  const repeatableKeys = new Set(repeatable);
+  return function parse(argv) {
+    const args = { _: [] };
+    for (let i = 0; i < argv.length; i++) {
+      const token = argv[i];
+      // Object.hasOwn, not aliases[token]: a bare lookup walks the prototype
+      // chain, so `constructor` / `toString` / `__proto__` in flag position
+      // resolve to a truthy inherited value, get treated as an option, and
+      // swallow the next argument instead of failing as an unknown flag.
+      const key = Object.hasOwn(aliases, token) ? aliases[token] : undefined;
+      if (key && booleanKeys.has(key)) {
+        args[key] = true;
+      } else if (key) {
+        const value = argv[++i];
+        if (value === undefined) {
+          fail(`option ${token} needs a value`, EXIT.USAGE);
+        }
+        if (repeatableKeys.has(key)) (args[key] ||= []).push(value);
+        else args[key] = value;
+      } else if (token.startsWith('-') && !(bareDashIsPositional && token === '-')) {
+        fail(`Unknown option: ${token}`, EXIT.USAGE);
+      } else {
+        args._.push(token);
+      }
+    }
+    return args;
+  };
+}
+
 // --- ping (unchanged wire behaviour) ---------------------------------------
 
-function parseArgs(argv) {
-  const args = { _: [] };
-  const alias = {
+const parseArgs = makeParser({
+  aliases: {
     '-m': 'message', '--message': 'message',
     '-t': 'title', '--title': 'title',
     '-a': 'action', '--action': 'action',
@@ -487,40 +650,15 @@ function parseArgs(argv) {
     '--api': 'api',
     '--json': 'json',
     '-h': 'help', '--help': 'help',
-  };
-  const booleans = new Set(['require_ack', 'json', 'help']);
-  const repeatable = new Set(['attach']);
-
-  for (let i = 0; i < argv.length; i++) {
-    const token = argv[i];
-    // Object.hasOwn, not alias[token]: a bare lookup walks the prototype chain,
-    // so `constructor` / `toString` / `__proto__` in flag position resolve to a
-    // truthy inherited value, get treated as an option, and swallow the next
-    // argument instead of failing as an unknown flag.
-    const key = Object.hasOwn(alias, token) ? alias[token] : undefined;
-    if (key && booleans.has(key)) {
-      args[key] = true;
-    } else if (key) {
-      const value = argv[++i];
-      if (value === undefined) {
-        fail(`option ${token} needs a value`, EXIT.USAGE);
-      }
-      if (repeatable.has(key)) (args[key] ||= []).push(value);
-      else args[key] = value;
-    } else if (token.startsWith('-')) {
-      fail(`Unknown option: ${token}`, EXIT.USAGE);
-    } else {
-      args._.push(token);
-    }
-  }
-  return args;
-}
+  },
+  booleans: ['require_ack', 'json', 'help'],
+  repeatable: ['attach'],
+});
 
 // Parser for the question commands: supports repeatable --option and a trailing
 // positional (a question id). Unknown flags fail like the ping parser.
-function parseQArgs(argv) {
-  const args = { _: [] };
-  const alias = {
+const parseQArgs = makeParser({
+  aliases: {
     '-p': 'prompt', '--prompt': 'prompt',
     '-o': 'option', '--option': 'option',
     '-c': 'context', '--context': 'context',
@@ -534,46 +672,25 @@ function parseQArgs(argv) {
     '--text-max': 'text_max',
     '--timeout': 'timeout',
     '--state': 'state',
+    '--limit': 'limit',
+    '--from': 'from',
+    '--once': 'once',
     '--token': 'token',
     '--room': 'room',
     '--api': 'api',
     '--wait': 'wait',
     '--json': 'json',
     '-h': 'help', '--help': 'help',
-  };
-  const booleans = new Set(['wait', 'json', 'help']);
-  const multi = new Set(['option']);
-
-  for (let i = 0; i < argv.length; i++) {
-    const token = argv[i];
-    // hasOwn, not a bare lookup — see parseArgs: an inherited key would swallow args.
-    const key = Object.hasOwn(alias, token) ? alias[token] : undefined;
-    if (key && booleans.has(key)) {
-      args[key] = true;
-    } else if (key) {
-      const value = argv[++i];
-      if (value === undefined) {
-        fail(`option ${token} needs a value`, EXIT.USAGE);
-      }
-      if (multi.has(key)) {
-        (args[key] ||= []).push(value);
-      } else {
-        args[key] = value;
-      }
-    } else if (token.startsWith('-') && token !== '-') {
-      fail(`Unknown option: ${token}`, EXIT.USAGE);
-    } else {
-      args._.push(token);
-    }
-  }
-  return args;
-}
+  },
+  booleans: ['wait', 'json', 'help', 'once'],
+  repeatable: ['option'],
+  bareDashIsPositional: true,
+});
 
 // Parser for `handoff`: --message plus repeatable --option, boolean --question,
 // and the handoff-specific flags. Unknown flags fail like the other parsers.
-function parseHandoffArgs(argv) {
-  const args = { _: [] };
-  const alias = {
+const parseHandoffArgs = makeParser({
+  aliases: {
     '-m': 'message', '--message': 'message',
     '--question': 'question',
     '-o': 'option', '--option': 'option',
@@ -591,34 +708,11 @@ function parseHandoffArgs(argv) {
     '--wait': 'wait',
     '--json': 'json',
     '-h': 'help', '--help': 'help',
-  };
-  const booleans = new Set(['question', 'wait', 'json', 'help']);
-  const multi = new Set(['option']);
-
-  for (let i = 0; i < argv.length; i++) {
-    const token = argv[i];
-    // hasOwn, not a bare lookup — see parseArgs: an inherited key would swallow args.
-    const key = Object.hasOwn(alias, token) ? alias[token] : undefined;
-    if (key && booleans.has(key)) {
-      args[key] = true;
-    } else if (key) {
-      const value = argv[++i];
-      if (value === undefined) {
-        fail(`option ${token} needs a value`, EXIT.USAGE);
-      }
-      if (multi.has(key)) {
-        (args[key] ||= []).push(value);
-      } else {
-        args[key] = value;
-      }
-    } else if (token.startsWith('-') && token !== '-') {
-      fail(`Unknown option: ${token}`, EXIT.USAGE);
-    } else {
-      args._.push(token);
-    }
-  }
-  return args;
-}
+  },
+  booleans: ['question', 'wait', 'json', 'help'],
+  repeatable: ['option'],
+  bareDashIsPositional: true,
+});
 
 // True when a URL is safe to attach a bearer token or webhook secret to: https,
 // or http on loopback so local dev against http://localhost still works.
@@ -772,7 +866,7 @@ async function uploadAttachments(paths, apiBase, token) {
       fail(`--attach ${name}: ping attachments are a Pro feature`, EXIT.USAGE);
     }
     if (!res.ok || !json?.attachment?.id) {
-      const detail = json?.message || json?.error || `HTTP ${res.status}`;
+      const detail = apiDetail(res, json);
       fail(`upload failed for ${name}: ${detail}`);
     }
 
@@ -783,10 +877,12 @@ async function uploadAttachments(paths, apiBase, token) {
 }
 
 async function ping(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('ping')}\n`); return EXIT.OK; }
 
   const message = args.message;
   if (!message) fail('a --message is required', EXIT.USAGE);
+  requireMaxLength(message, 500, '--message');
+  requireMaxLength(args.title, 40, '--title');
 
   if (args.action !== undefined && !/^[1-4]$/.test(String(args.action))) {
     fail('--action must be an integer 1–4', EXIT.USAGE);
@@ -890,7 +986,7 @@ async function ping(args) {
   const ok = res.ok && !(json && json.success === false);
 
   if (!ok) {
-    const detail = (json && (json.message || json.error)) || `HTTP ${res.status}`;
+    const detail = apiDetail(res, json);
     fail(`delivery failed: ${detail}`);
   }
 
@@ -905,11 +1001,30 @@ async function ping(args) {
 // --template line in HELP and with LIVE_ACTIVITY_TEMPLATES.md.
 const LIVE_TEMPLATES = ['status', 'steps', 'progress', 'metrics', 'countdown', 'question', 'matchup'];
 
+/**
+ * Names the API does not take, folded onto the wire id it does.
+ *
+ * The `question` template is labelled **Decision** everywhere a person sees it,
+ * so it is never confused with PingRoom's first-class Question protocol — that
+ * one is answered through `pingroom ask`, carries a real Question id, and this
+ * template does not. The wire id stayed `question`, so someone who reads
+ * "Decision" in the app and types it would otherwise get a usage error for
+ * using the only name they have been shown.
+ */
+const LIVE_TEMPLATE_ALIASES = { decision: 'question' };
+
+/** The wire id for a template name a human typed, or the name unchanged. */
+function canonicalTemplate(name) {
+  return LIVE_TEMPLATE_ALIASES[name] ?? name;
+}
+
+/** What we offer in help and errors: the alias leads, since it is what the app shows. */
+const LIVE_TEMPLATE_NAMES = ['status', 'steps', 'progress', 'metrics', 'countdown', 'decision', 'matchup'];
+
 // Parser for `live`: a leading subcommand (start|update|end|get) plus the
 // live-status flags. Unknown flags fail like the other parsers.
-function parseLiveArgs(argv) {
-  const args = { _: [] };
-  const alias = {
+const parseLiveArgs = makeParser({
+  aliases: {
     '-c': 'correlation_id', '--correlation-id': 'correlation_id',
     '-t': 'title', '--title': 'title',
     '-m': 'message', '--message': 'message',
@@ -938,29 +1053,10 @@ function parseLiveArgs(argv) {
     '--api': 'api',
     '--json': 'json',
     '-h': 'help', '--help': 'help',
-  };
-  const booleans = new Set(['require_ack', 'json', 'help', 'failed']);
-  const repeatable = new Set(['metric', 'option']);
-
-  for (let i = 0; i < argv.length; i++) {
-    const token = argv[i];
-    // hasOwn, not a bare lookup — see parseArgs: an inherited key would swallow args.
-    const key = Object.hasOwn(alias, token) ? alias[token] : undefined;
-    if (key && booleans.has(key)) {
-      args[key] = true;
-    } else if (key) {
-      const value = argv[++i];
-      if (value === undefined) fail(`option ${token} needs a value`, EXIT.USAGE);
-      if (repeatable.has(key)) (args[key] ||= []).push(value);
-      else args[key] = value;
-    } else if (token.startsWith('-')) {
-      fail(`Unknown option: ${token}`, EXIT.USAGE);
-    } else {
-      args._.push(token);
-    }
-  }
-  return args;
-}
+  },
+  booleans: ['require_ack', 'json', 'help', 'failed'],
+  repeatable: ['metric', 'option'],
+});
 
 // "label:value" -> {label, value}. Only the first colon splits.
 function buildMetrics(list) {
@@ -1022,6 +1118,7 @@ function numberOption(raw, flag, { min, max, integer = false } = {}) {
  * (--webhook), which speak the same `live_status` contract.
  */
 async function live(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('live')}\n`); return EXIT.OK; }
   const sub = args._[0];
   const known = ['start', 'update', 'end', 'get'];
   if (!sub || !known.includes(sub)) {
@@ -1045,7 +1142,7 @@ async function live(args) {
     const { res, text, json } = await httpJson('GET', url, { headers: { Authorization: `Bearer ${token}` } });
     if (args.json) process.stdout.write(`${text || '{}'}\n`);
     if (!res.ok) {
-      fail(`read failed: ${(json && (json.message || json.code)) || `HTTP ${res.status}`}`);
+      fail(`read failed: ${apiDetail(res, json)}`);
     }
     if (!args.json) process.stdout.write(`${(json && json.state) || 'unknown'}\n`);
     return EXIT.OK;
@@ -1055,6 +1152,11 @@ async function live(args) {
     state: sub === 'end' ? (args.failed ? 'failed' : 'done') : 'running',
   };
 
+  // 256, not the 500 a ping body gets: this is the card's one live line.
+  requireMaxLength(args.message, 256, '--message');
+  requireMaxLength(args.title, 40, '--title');
+  requireMaxLength(args.prompt, 256, '--prompt');
+  requireMaxLength(args.center, 40, '--center');
   if (args.message !== undefined) liveStatus.message = args.message;
   if (args.prompt !== undefined) liveStatus.prompt = args.prompt;
 
@@ -1095,10 +1197,11 @@ async function live(args) {
     // usage error, and letting it reach the server turns it into a 422 round
     // trip that reads like an outage.
     if (args.template) {
-      if (!LIVE_TEMPLATES.includes(args.template)) {
-        fail(`--template must be one of: ${LIVE_TEMPLATES.join(', ')}`, EXIT.USAGE);
+      const template = canonicalTemplate(args.template);
+      if (!LIVE_TEMPLATES.includes(template)) {
+        fail(`--template must be one of: ${LIVE_TEMPLATE_NAMES.join(', ')}`, EXIT.USAGE);
       }
-      liveStatus.template = args.template;
+      liveStatus.template = template;
     }
     // `alert` has no template equivalent and is the only way to start a stream
     // time-sensitive (breaking through Focus) without also demanding an ack.
@@ -1151,7 +1254,7 @@ async function live(args) {
   if (args.json) process.stdout.write(`${text || '{}'}\n`);
 
   if (!res.ok || (json && json.success === false)) {
-    const detail = (json && (json.message || json.error || json.code)) || `HTTP ${res.status}`;
+    const detail = apiDetail(res, json);
     fail(`live ${sub} failed: ${detail}`);
   }
 
@@ -1234,15 +1337,14 @@ function printResolution(q) {
 // and return the state's exit code. The server expires it at its ttl, so this
 // always terminates.
 async function waitForResolution(id, args, { token, apiBase }) {
-  let hold = args.timeout !== undefined ? Number(args.timeout) : 25;
-  if (!Number.isFinite(hold) || hold < 0) fail('--timeout must be a non-negative integer', EXIT.USAGE);
-  hold = Math.min(hold, 30);
+  const hold = resolveWaitHold(args, { def: 25, cap: 30 });
 
   for (;;) {
+    const started = Date.now();
     const url = `${apiBase}/api/agent/questions/${encodeURIComponent(id)}/wait?timeout=${hold}`;
     const { res, text, json } = await httpJson('GET', url, { headers: { Authorization: `Bearer ${token}` } });
     if (!res.ok) {
-      const detail = (json && (json.message || json.code)) || `HTTP ${res.status}`;
+      const detail = apiDetail(res, json);
       fail(`wait failed: ${detail}`);
     }
     if (json && json.state && json.state !== 'pending') {
@@ -1250,15 +1352,21 @@ async function waitForResolution(id, args, { token, apiBase }) {
       else printResolution(json);
       return exitForState(json.state);
     }
-    // Still pending at the hold timeout — poll again.
+    // Still pending at the hold timeout — poll again, but never hot-loop: a
+    // misbehaving server that answers `pending` instantly (ignoring the hold)
+    // would otherwise be hammered at full speed.
+    const elapsed = Date.now() - started;
+    if (elapsed < 1000) await sleep(1000 - elapsed);
   }
 }
 
 async function ask(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('ask')}\n`); return EXIT.OK; }
 
   const prompt = args.prompt;
   if (!prompt) fail('a --prompt is required', EXIT.USAGE);
+  requireMaxLength(prompt, 500, '--prompt');
+  requireMaxLength(args.context, 40, '--context');
 
   const { token, apiBase, room } = agentContext(args, { needRoom: true });
 
@@ -1291,10 +1399,13 @@ async function ask(args) {
   }
   if (args.data !== undefined) body.data = parseDataObject(args.data);
 
+  // Pre-flight: reject a bad --timeout before the question exists.
+  if (args.wait) resolveWaitHold(args, { def: 25, cap: 30 });
+
   const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/questions`;
   const { res, text, json } = await httpJson('POST', url, { body, headers: { Authorization: `Bearer ${token}` } });
   if (!res.ok) {
-    const detail = (json && (json.message || json.code)) || `HTTP ${res.status}`;
+    const detail = apiDetail(res, json);
     fail(`ask failed: ${detail}`);
   }
 
@@ -1308,7 +1419,7 @@ async function ask(args) {
 }
 
 async function watch(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('watch')}\n`); return EXIT.OK; }
   const id = args._[0];
   if (!id) fail('a question id is required (pingroom watch <id>)', EXIT.USAGE);
   const { token, apiBase } = agentContext(args);
@@ -1316,14 +1427,14 @@ async function watch(args) {
 }
 
 async function cancel(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('cancel')}\n`); return EXIT.OK; }
   const id = args._[0];
   if (!id) fail('a question id is required (pingroom cancel <id>)', EXIT.USAGE);
   const { token, apiBase } = agentContext(args);
   const url = `${apiBase}/api/agent/questions/${encodeURIComponent(id)}/cancel`;
   const { res, text, json } = await httpJson('POST', url, { body: {}, headers: { Authorization: `Bearer ${token}` } });
   if (!res.ok) {
-    const detail = (json && (json.message || json.code)) || `HTTP ${res.status}`;
+    const detail = apiDetail(res, json);
     fail(`cancel failed: ${detail}`);
   }
   if (args.json) process.stdout.write(`${text}\n`);
@@ -1332,13 +1443,13 @@ async function cancel(args) {
 }
 
 async function list(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('list')}\n`); return EXIT.OK; }
   const { token, apiBase } = agentContext(args);
   const qs = args.state ? `?state=${encodeURIComponent(args.state)}` : '';
   const url = `${apiBase}/api/agent/questions${qs}`;
   const { res, text, json } = await httpJson('GET', url, { headers: { Authorization: `Bearer ${token}` } });
   if (!res.ok) {
-    const detail = (json && (json.message || json.code)) || `HTTP ${res.status}`;
+    const detail = apiDetail(res, json);
     fail(`list failed: ${detail}`);
   }
   if (args.json) { process.stdout.write(`${text}\n`); return EXIT.OK; }
@@ -1352,8 +1463,100 @@ async function list(args) {
   return EXIT.OK;
 }
 
+// --- listen ----------------------------------------------------------------
+//
+// The inbound half. Everything else here talks; this is how an agent hears —
+// replies to its own structured pings, a human's ping in a room it belongs to,
+// anything landing while it works.
+//
+// The server holds each request open until something arrives or the timeout
+// elapses, so this is a long-poll, not a poll loop: an idle hour costs ~144
+// requests, not one per second.
+
+/** Cursor bookkeeping is the whole protocol: `after` in, `cursor` back. */
+async function listen(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('listen')}\n`); return EXIT.OK; }
+
+  const { token, apiBase } = agentContext(args);
+  const headers = { Authorization: `Bearer ${token}` };
+
+  const timeout = numberOption(args.timeout, '--timeout', { min: 0, max: 30, integer: true }) ?? 25;
+  const limit = numberOption(args.limit, '--limit', { min: 1, max: 100, integer: true }) ?? 50;
+
+  // No cursor means "from now": the server answers an empty `after` with the
+  // head id and no rows, so starting up never replays history the agent has
+  // already seen. `--from` opts into catching up from a known id instead.
+  let cursor = args.from;
+  if (!cursor) {
+    const { res, json } = await httpJson('GET', `${apiBase}/api/agent/notifications/wait`, {
+      headers,
+      soft: true,
+    });
+    if (!res?.ok) fail(`listen failed: ${apiDetail(res, json)}`);
+    cursor = json && json.cursor;
+    if (!cursor) {
+      // A brand-new account with no pings at all has no head id. Nothing is
+      // wrong; there is simply nothing to be after yet.
+      cursor = '';
+    }
+  }
+
+  let transientRun = 0;
+
+  for (;;) {
+    const query = new URLSearchParams({ timeout: String(timeout), limit: String(limit) });
+    if (cursor) query.set('after', cursor);
+
+    const { res, json, error } = await httpJson(
+      'GET',
+      `${apiBase}/api/agent/notifications/wait?${query}`,
+      // The hold plus headroom: aborting at exactly the server's deadline would
+      // race it and turn every quiet window into a client-side error.
+      { headers, soft: true, signal: AbortSignal.timeout((timeout + 10) * 1000) },
+    );
+
+    if (error || res.status === 429 || res.status >= 500) {
+      transientRun += 1;
+      const retryAfter = res?.status === 429 ? retryAfterMs(res) : null;
+      // Geometric backoff so a real outage is not also a thundering herd. The
+      // loop is unbounded by design — `listen` is a daemon, not a request.
+      const backoff = Math.min(1000 * 2 ** Math.max(0, transientRun - 1), 30_000);
+      await sleep(Math.max(0, retryAfter ?? backoff));
+      continue;
+    }
+
+    if (!res.ok) fail(`listen failed: ${apiDetail(res, json)}`);
+    transientRun = 0;
+
+    const batch = Array.isArray(json?.notifications) ? json.notifications : [];
+    for (const item of batch) {
+      process.stdout.write(args.json ? `${JSON.stringify(item)}\n` : `${formatIncoming(item)}\n`);
+    }
+    // Advance only on a cursor the server actually returned, or a batch could be
+    // replayed forever against a stale `after`.
+    if (json && typeof json.cursor === 'string' && json.cursor) cursor = json.cursor;
+
+    if (args.once) return EXIT.OK;
+  }
+}
+
+/** One readable line per incoming ping. */
+function formatIncoming(item) {
+  const room = item?.room?.name || item?.room?.code || '?';
+  const body = stripControlChars(item?.message ?? '');
+  const marks = [];
+  if (item?.correlation_id) marks.push(`corr=${stripControlChars(item.correlation_id)}`);
+  if (item?.reply_to) marks.push(`reply_to=${stripControlChars(item.reply_to)}`);
+  if (item?.question) marks.push('question');
+  if (Array.isArray(item?.attachments) && item.attachments.length) {
+    marks.push(`${item.attachments.length} attachment${item.attachments.length === 1 ? '' : 's'}`);
+  }
+  const suffix = marks.length ? `  (${marks.join(' · ')})` : '';
+  return `[${stripControlChars(room)}] ${body}${suffix}`;
+}
+
 async function listHandoffs(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('handoffs')}\n`); return EXIT.OK; }
   const { token, apiBase } = agentContext(args);
   const state = args.state || 'open';
   if (state !== 'open' && state !== 'all') {
@@ -1363,7 +1566,7 @@ async function listHandoffs(args) {
   const url = `${apiBase}/api/agent/handoffs?state=${encodeURIComponent(state)}`;
   const { res, text, json } = await httpJson('GET', url, { headers: { Authorization: `Bearer ${token}` } });
   if (!res.ok) {
-    const detail = (json && (json.message || json.code)) || `HTTP ${res.status}`;
+    const detail = apiDetail(res, json);
     fail(`handoffs list failed: ${detail}`);
   }
   if (args.json) { process.stdout.write(`${text}\n`); return EXIT.OK; }
@@ -1471,15 +1674,14 @@ function writeGitHubHandoffOutputs(path, h) {
 // Long-poll GET /handoffs/{id}/wait until the handoff leaves open/pending, then
 // print it and return the state's exit code. Reuses the shared bounded hold.
 async function waitForHandoff(id, args, { token, apiBase }, initialDeliveryState) {
-  let hold = args.timeout !== undefined ? Number(args.timeout) : 20;
-  if (!Number.isFinite(hold) || hold < 0) fail('--timeout must be a non-negative integer', EXIT.USAGE);
-  hold = Math.min(hold, 25);
+  const hold = resolveWaitHold(args, { def: 20, cap: 25 });
 
   for (;;) {
+    const started = Date.now();
     const url = `${apiBase}/api/agent/handoffs/${encodeURIComponent(id)}/wait?timeout=${hold}`;
     const { res, text, json } = await httpJson('GET', url, { headers: { Authorization: `Bearer ${token}` } });
     if (!res.ok) {
-      const detail = (json && (json.message || json.code)) || `HTTP ${res.status}`;
+      const detail = apiDetail(res, json);
       fail(`wait failed: ${detail}`);
     }
     if (json && json.state && !HANDOFF_PENDING.has(json.state)) {
@@ -1494,15 +1696,19 @@ async function waitForHandoff(id, args, { token, apiBase }, initialDeliveryState
       else printHandoff(resolved);
       return exitForHandoffState(resolved.state);
     }
-    // Still open/pending at the hold timeout — poll again.
+    // Still open/pending at the hold timeout — poll again, with the same
+    // hot-loop floor as waitForResolution.
+    const elapsed = Date.now() - started;
+    if (elapsed < 1000) await sleep(1000 - elapsed);
   }
 }
 
 async function handoff(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('handoff')}\n`); return EXIT.OK; }
 
   const message = args.message;
   if (!message) fail('a --message is required', EXIT.USAGE);
+  requireMaxLength(message, 500, '--message');
 
   const { token, apiBase } = agentContext(args);
 
@@ -1548,11 +1754,14 @@ async function handoff(args) {
     headers['Idempotency-Key'] = args.idempotency_key;
   }
 
+  // Pre-flight: reject a bad --timeout before the handoff exists.
+  if (args.wait) resolveWaitHold(args, { def: 20, cap: 25 });
+
   const url = `${apiBase}/api/agent/handoffs`;
   const { res, text, json } = await httpJson('POST', url, { body, headers });
   if (!res.ok) {
     const code = json && json.code;
-    const detail = (json && (json.message || code)) || `HTTP ${res.status}`;
+    const detail = apiDetail(res, json);
     // A recipient who isn't reachable yet is a distinct, retriable outcome (4),
     // not a generic error — CI may want to wait and retry rather than fail hard.
     if (res.status === 409 && code === 'recipient_not_ready') {
@@ -1587,9 +1796,8 @@ async function handoff(args) {
 // normal local prompt (PreToolUse -> permissionDecision "ask") and exits 0. It
 // must not call fail() (a non-zero exit — 2 especially — would break the run).
 
-function parseHookArgs(argv) {
-  const args = { _: [] };
-  const alias = {
+const parseHookArgs = makeParser({
+  aliases: {
     '--room': 'room',
     '--ttl': 'ttl',
     '--quiet': 'quiet',
@@ -1598,27 +1806,10 @@ function parseHookArgs(argv) {
     '--api': 'api',
     '--json': 'json',
     '-h': 'help', '--help': 'help',
-  };
-  const booleans = new Set(['quiet', 'print_config', 'json', 'help']);
-
-  for (let i = 0; i < argv.length; i++) {
-    const token = argv[i];
-    // hasOwn, not a bare lookup — see parseArgs: an inherited key would swallow args.
-    const key = Object.hasOwn(alias, token) ? alias[token] : undefined;
-    if (key && booleans.has(key)) {
-      args[key] = true;
-    } else if (key) {
-      const value = argv[++i];
-      if (value === undefined) fail(`option ${token} needs a value`, EXIT.USAGE);
-      args[key] = value;
-    } else if (token.startsWith('-') && token !== '-') {
-      fail(`Unknown option: ${token}`, EXIT.USAGE);
-    } else {
-      args._.push(token);
-    }
-  }
-  return args;
-}
+  },
+  booleans: ['quiet', 'print_config', 'json', 'help'],
+  bareDashIsPositional: true,
+});
 
 // Read all of stdin as a string. Resolves '' when nothing is piped (TTY), so a
 // stray `pingroom hook` in a terminal is a silent no-op rather than a hang.
@@ -1655,7 +1846,7 @@ async function hookFetch(method, url, { body, token } = {}) {
   let json = null;
   try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
   if (!res.ok) {
-    throw new Error((json && (json.message || json.code)) || `HTTP ${res.status}`);
+    throw new Error(apiDetail(res, json));
   }
   return json;
 }
@@ -1880,7 +2071,7 @@ ${JSON.stringify(config, null, 2)}
 }
 
 async function hook(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('hook')}\n`); return EXIT.OK; }
   if (args.print_config) { printHookConfig(); return EXIT.OK; }
 
   let event = {};
@@ -1984,12 +2175,16 @@ This command only prints setup instructions and does not modify client config.
 const CLI_SCOPES = [
   'pingroom:rooms:read',        // resolve/display the connected room
   'pingroom:broadcast:send',    // ping
+  'pingroom:attachments:write', // ping --attach (the upload leg)
+  'pingroom:notifications:read',// listen
   'pingroom:questions:ask',     // ask / watch / cancel / list, and the hook
   'pingroom:handoffs:create',   // handoff / handoffs
   'pingroom:live:write',        // live start/update/end/get
 ];
 
-const AGENT_LABEL = 'pingroom-cli';
+// What the human reads on the approval screen. A product name, not a package
+// id: the phone shows it verbatim ("PingRoom CLI wants to connect").
+const AGENT_LABEL = 'PingRoom CLI';
 // A connect command should prove the phone round-trip, but it must not hold a
 // terminal for the onboarding Question's full 24-hour server TTL. The Question
 // remains answerable after this local deadline and the credential is already
@@ -2117,19 +2312,24 @@ async function registerAnonymous(apiBase) {
     body: { type: 'anonymous', agent_label: AGENT_LABEL, scopes: CLI_SCOPES },
   });
   if (!res.ok || !json || typeof json.credential !== 'string') {
-    const detail = (json && (json.message || json.error || json.code)) || `HTTP ${res.status}`;
+    const detail = apiDetail(res, json);
     fail(`could not start a connection: ${detail}`);
   }
   return json.credential;
 }
 
 /** Persist the active credential plus the bits the status line prints. */
-function saveCredential({ token, handle, room, account, scopes, apiBase }) {
+function saveCredential({ token, handle, room, rooms, roomAccess, account, scopes, apiBase }) {
   writeJsonFile(credentialsPath(), {
     version: 1,
     token,
     handle: handle || null,
+    // `room` is the delivery room — where handoffs and questions land. `rooms`
+    // is the whole grant, which can be wider; `room_access: "all"` means the
+    // human granted every room they are in, listing none.
     room: room || null,
+    rooms: Array.isArray(rooms) ? rooms : [],
+    room_access: roomAccess || null,
     account: account || null,
     scopes: scopes || [],
     api_url: apiBase,
@@ -2137,11 +2337,22 @@ function saveCredential({ token, handle, room, account, scopes, apiBase }) {
   });
 }
 
-/** "✓ Connected as @agt_ab12 → #Project X" — the room half is omitted if unknown. */
+/**
+ * "✓ Connected as @agt_ab12 → #Project X" — the room half is omitted if unknown,
+ * and widened to "→ all rooms" / "→ #Project X +2 more" when the human granted
+ * this agent more than the one delivery room.
+ */
 function connectedLine(cred) {
   const who = cred.handle ? `@${cred.handle}` : 'this machine';
   const room = cred.room && (cred.room.name || cred.room.invite_code);
-  return `✓ Connected as ${who}${room ? ` → #${room}` : ''}`;
+  const access = cred.room_access ?? cred.roomAccess;
+
+  if (access === 'all') return `✓ Connected as ${who} → all rooms`;
+
+  if (!room) return `✓ Connected as ${who}`;
+
+  const extra = Math.max(0, (Array.isArray(cred.rooms) ? cred.rooms.length : 0) - 1);
+  return `✓ Connected as ${who} → #${room}${extra > 0 ? ` +${extra} more` : ''}`;
 }
 
 function activationFailureDetail(result) {
@@ -2376,7 +2587,7 @@ async function activateInboxAfterPairing(cred) {
 
 /** Retry activation only for the durable credential created by QR pairing. */
 async function activateStoredInbox(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('activate')}\n`); return EXIT.OK; }
   if (args._.length > 0) fail('usage: pingroom activate', EXIT.USAGE);
   if (args.token !== undefined) {
     fail('pingroom activate uses the saved QR-paired credential; remove --token', EXIT.USAGE);
@@ -2391,7 +2602,15 @@ async function activateStoredInbox(args) {
     fail('no saved QR-paired credential; run "pingroom" in an interactive terminal first', EXIT.USAGE);
   }
   if (!credential.room || !isNonEmptyString(credential.room.invite_code)) {
-    fail('the saved credential has no QR-selected delivery room; reconnect with QR pairing before running "pingroom activate"', EXIT.USAGE);
+    // Granting every room is a valid answer that pins no destination, so the
+    // fix there is picking one — not pairing again, which would only offer the
+    // same choice back.
+    fail(
+      credential.room_access === 'all'
+        ? 'this agent was granted all rooms but no delivery room; pick one in the PingRoom app under Connected Agents, then run "pingroom activate" again'
+        : 'the saved credential has no QR-selected delivery room; reconnect with QR pairing before running "pingroom activate"',
+      EXIT.USAGE,
+    );
   }
   if (!Array.isArray(credential.scopes) || !credential.scopes.includes('pingroom:handoffs:create')) {
     fail('the saved credential lacks pingroom:handoffs:create; reconnect with QR pairing before running "pingroom activate"', EXIT.USAGE);
@@ -2499,7 +2718,7 @@ async function connectByPairing(apiBase, ask) {
 
       if (!res.ok) {
         process.stdout.write('\n');
-        const detail = (json && (json.message || json.error || json.code)) || `HTTP ${res.status}`;
+        const detail = apiDetail(res, json);
         fail(`pairing failed: ${detail}`);
       }
       const status = json && json.status;
@@ -2516,13 +2735,19 @@ async function connectByPairing(apiBase, ask) {
           token: json.credential,
           handle: json.handle,
           room: json.room,
+          rooms: Array.isArray(json.rooms) ? json.rooms : [],
+          roomAccess: typeof json.room_access === 'string' ? json.room_access : null,
           account: json.account,
           scopes: json.scopes,
           apiBase,
         };
         saveCredential(cred);
         process.stdout.write(`${connectedLine(cred)}\n`);
-        await activateInboxAfterPairing(cred);
+        // Connecting deliberately sends nothing to the human's phone. The
+        // approval they just tapped IS the round-trip; a test Question on top of
+        // it was one more thing to answer before the tool could be used, and it
+        // made a healthy connection look broken whenever the answer was slow.
+        // `pingroom activate` still sends one for anyone who wants the proof.
         return cred;
       }
       if (status === 'expired') break;
@@ -2715,7 +2940,7 @@ const CONFIG_KEYS = {
 };
 
 async function config(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('config')}\n`); return EXIT.OK; }
 
   const sub = args._[0];
   const known = ['list', 'get', 'set'];
@@ -2773,7 +2998,7 @@ async function config(args) {
 // --- logout ----------------------------------------------------------------
 
 async function logout(args) {
-  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.help) { process.stdout.write(`${commandHelp('logout')}\n`); return EXIT.OK; }
 
   const path = credentialsPath();
   const stored = readStoredCredential();
@@ -2795,6 +3020,33 @@ async function logout(args) {
   return EXIT.OK;
 }
 
+// config/logout/handoffs used to share parseQArgs, which silently accepted and
+// ignored flags those commands never read (`logout --wait --prompt x`). Minimal
+// tables instead, so an irrelevant flag is a usage error like everywhere else.
+const parseConfigArgs = makeParser({
+  aliases: { '--json': 'json', '-h': 'help', '--help': 'help' },
+  booleans: ['json', 'help'],
+  bareDashIsPositional: true,
+});
+
+const parseLogoutArgs = makeParser({
+  aliases: { '-h': 'help', '--help': 'help' },
+  booleans: ['help'],
+  bareDashIsPositional: true,
+});
+
+const parseHandoffsArgs = makeParser({
+  aliases: {
+    '--state': 'state',
+    '--token': 'token',
+    '--api': 'api',
+    '--json': 'json',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['json', 'help'],
+  bareDashIsPositional: true,
+});
+
 const COMMANDS = {
   ping: (rest) => ping(parseArgs(rest)),
   ask: (rest) => ask(parseQArgs(rest)),
@@ -2803,13 +3055,14 @@ const COMMANDS = {
   cancel: (rest) => cancel(parseQArgs(rest)),
   list: (rest) => list(parseQArgs(rest)),
   handoff: (rest) => handoff(parseHandoffArgs(rest)),
-  handoffs: (rest) => listHandoffs(parseQArgs(rest)),
+  handoffs: (rest) => listHandoffs(parseHandoffsArgs(rest)),
+  listen: (rest) => listen(parseQArgs(rest)),
   hook: (rest) => hook(parseHookArgs(rest)),
   mcp,
   activate: (rest) => activateStoredInbox(parseQArgs(rest)),
   live: (rest) => live(parseLiveArgs(rest)),
-  config: (rest) => config(parseQArgs(rest)),
-  logout: (rest) => logout(parseQArgs(rest)),
+  config: (rest) => config(parseConfigArgs(rest)),
+  logout: (rest) => logout(parseLogoutArgs(rest)),
 };
 
 function waitFrom(handler, rest) {
@@ -2847,4 +3100,13 @@ async function main() {
   process.exit(code);
 }
 
-main();
+// Anything that escapes a handler is a bug in this tool, not a usage error, but
+// the operator still gets one clean line instead of a Node stack trace — and the
+// same exit 1 every other failure uses, so scripts branching on the code are
+// unaffected. PINGROOM_DEBUG keeps the stack for whoever is fixing it.
+main().catch((error) => {
+  if (process.env.PINGROOM_DEBUG) {
+    process.stderr.write(`${error?.stack ?? error}\n`);
+  }
+  fail(`unexpected error: ${stripControlChars(error?.message ?? String(error))}`);
+});