@pingroom/cli 0.6.2 → 0.7.0

package/README.md

@@ -6,10 +6,10 @@ from CI, scripts, and agents. Delivered as push straight to your phone.
 One dependency (`qrcode-terminal`, used only to draw the pairing QR). Works
 anywhere Node ≥ 20 runs.
 
-> **Release status:** npm currently serves 0.6.1. The corrected attachment
-> limits are in the tested 0.6.2 release candidate on `main`; the public GitHub
-> Action remains pinned to 0.6.1 until 0.6.2 is published and clean-install
-> verified.
+> **Release status:** 0.7.0 is prepared for publish — the room grant, the
+> `attachments:write` scope `--attach` always needed, and actionable text on the
+> refusals you can fix. The GitHub Action pins 0.7.0, so publish before relying
+> on it.
 
 ## Install and first run
 
@@ -27,8 +27,10 @@ npx --yes @pingroom/cli
 ```
 
 Either command starts the same connection prompt. QR pairing stores the selected
-account, credential, and delivery room in `~/.pingroom`; later commands reuse
+account, credential, and room grant in `~/.pingroom`; later commands reuse
 them, so a local invocation needs neither `PINGROOM_TOKEN` nor `PINGROOM_ROOM`.
+On the phone you grant one room, several, or every room on the account — the
+first room you pick is the delivery room, where Questions and Handoffs land.
 The email fallback stores the credential only. Setting
 `pingroom config set default_room <invite-code>` enables room-addressed commands,
 but private Agent Inbox and Handoff delivery require a connection approved with
@@ -41,16 +43,17 @@ pingroom ping -m "Deploy succeeded ✅"
 
 Commands: `ping` (send), `ask` (ask a human), `watch` (block on an existing
 question), `list`, `cancel`, `handoff` (hand a decision to a specific human),
-`handoffs` (list open or recent Handoffs), `live` (lock-screen progress card),
-`hook` (Claude Code), `mcp` (client setup), `activate` (retry the Agent Inbox
-test), `config`, and `logout`.
+`handoffs` (list open or recent Handoffs), `listen` (hear pings as they land),
+`live` (lock-screen progress card),
+`hook` (Claude Code), `mcp` (client setup), `activate` (send an optional test
+Question), `config`, and `logout`.
 Run `pingroom --help` for the full reference.
 
 ## Connecting
 
 Run `pingroom` (global install) or `npx --yes @pingroom/cli` (no install) with no
-arguments. It prints a QR code — scan it with the PingRoom app and pick both the
-account and the room the agent delivers to — or take the emailed-code fallback.
+arguments. It prints a QR code — scan it with the PingRoom app, pick the account,
+and grant the rooms this agent may reach — or take the emailed-code fallback.
 
 ```
 $ pingroom
@@ -61,43 +64,55 @@ $ pingroom
 
   [QR]
   Or open: https://pingroom.io/app/agents/pair?token=…
-  Waiting for approval… ✓ Connected as @agt_ab12cd34ef → #Project X
-  Sending a test question to PingRoom…
-  Answer “PingRoom connected. Can you answer this?” on your phone.
-✓ Test question answered (Yes). Agent Inbox is ready.
-```
-
-After QR approval, the CLI saves the active credential first, then sends one
-idempotent onboarding Question and observes it through the Handoff wait API.
-Short network and server failures are retried, and `Retry-After` is honored for
-rate limits within the two-minute overall deadline. An answer alone is not
-reported as success: the terminal response must also carry the server's exact
-`activation_completed: true` stamp. On supporting server and mobile builds,
-that stamp means the native phone returned the opaque proof carried in the push
-before the human answer, and this CLI then observed the result. An answered
-response whose stamp is false or missing is incomplete and is not retried as if
-history could be rewritten. If the Question is still pending when the local
-deadline elapses, or activation cannot start, the CLI prints the recovery
-command and exits with the connection still saved and usable. A terminal test
-without the stamp requires a current PingRoom app and a fresh numbered attempt;
-run `pingroom activate` again with the saved connection.
-
-Resume an open idempotent check with the saved QR credential:
+  Waiting for approval… ✓ Connected as @agt_ab12cd34ef → #Project X +2 more
+```
+
+Approving on the phone is the whole ceremony — connecting sends nothing else to
+your phone. The status line reflects the grant: `→ #Project X` for one room,
+`→ #Project X +2 more` for several, `→ all rooms` when you granted every room.
+
+## Proving the round-trip (optional)
 
 ```bash
 pingroom activate
 ```
 
-An incomplete explicit retry exits `1`; it never deletes or replaces the saved
-credential. The command does not fall back to `PINGROOM_TOKEN`, an email-only
-credential, or a credential without `pingroom:handoffs:create` and a
-QR-selected delivery room. Email-code and other non-interactive credential
-flows do not run the phone-response loop automatically.
+`activate` sends one idempotent onboarding Question and observes it through the
+Handoff wait API. Short network and server failures are retried, and
+`Retry-After` is honored for rate limits within the two-minute overall deadline.
+An answer alone is not reported as success: the terminal response must also
+carry the server's exact `activation_completed: true` stamp. On supporting
+server and mobile builds, that stamp means the native phone returned the opaque
+proof carried in the push before the human answer, and this CLI then observed
+the result. An answered response whose stamp is false or missing is incomplete
+and is not retried as if history could be rewritten.
+
+An incomplete run exits `1`; it never deletes or replaces the saved credential.
+The command does not fall back to `PINGROOM_TOKEN`, an email-only credential, or
+a credential without `pingroom:handoffs:create` and a delivery room. A grant of
+all rooms pins no delivery room — pick one under Connected Agents in the app
+first.
 
 There is deliberately no `login` command: being unconnected is a state the tool
 resolves, not one you have to discover. Once connected, bare `pingroom` prints
 that status line followed by the usual help.
 
+### What the approval grants
+
+Approving on the phone grants two separate things, and both are enforced:
+
+- **Permissions** — the scopes this CLI asks for: `rooms:read`,
+  `broadcast:send`, `attachments:write`, `notifications:read`, `questions:ask`,
+  `handoffs:create`, `live:write`. Nothing widens them later; a command needing
+  one you did not approve returns `403 insufficient_scope`.
+- **Rooms** — one room, several, or all of them. A room outside that grant
+  returns `403 room_not_granted` on any write, including pings, questions and
+  live streams. Widen it under Connected Agents in the app.
+
+Both refusals print the fix, not just the code. A credential paired by an older
+CLI carries the scope set that version asked for — reconnect to re-approve if a
+command starts reporting `insufficient_scope`.
+
 The credential lands in `~/.pingroom/credentials.json` (mode `0600`, inside a
 `0700` directory). `PINGROOM_HOME` moves that directory; `pingroom logout`
 clears it.
@@ -206,12 +221,41 @@ on the Lock Screen (iOS Live Activity / Dynamic Island, Android live update, and
 a full inline card in the app). `start` opens it with one alert, `update` moves
 it **silently**, `end` closes it with one completion alert.
 
+## Hearing replies
+
+Everything else here talks; `listen` 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.
+
+```bash
+pingroom listen                      # block, printing each ping as it lands
+pingroom listen --once --json        # one batch as JSON, then exit
+pingroom listen --from "$LAST_ID"    # catch up from a known ping id
+```
+
+```
+      --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
+```
+
+The server holds each request open until something arrives, so this is a
+long-poll rather than a poll loop: an idle hour costs about 144 requests, not
+one per second. With no `--from` it starts from *now* — the first call takes the
+head cursor and returns nothing, so starting up never replays history. Transient
+failures (429, 5xx, network) back off geometrically and keep listening;
+`--once` is the form to use in a script.
+
 ```
 pingroom live <start|update|end|get> [options]
 
   -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)
       --steps <a,b,c>        start only: 2-8 comma-separated step labels
   -m, --message <text>       The card's live message line
       --progress <0..1>      Progress bar / Dynamic Island gauge
@@ -219,13 +263,14 @@ pingroom live <start|update|end|get> [options]
       --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)
+      --prompt <text>        The ask (decision template)
+      --option <value:label> Repeatable, up to 4 (decision template)
       --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

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,7 +41,7 @@ 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.0';
 
 const BUILTIN_API = 'https://api.pingroom.io';
 const MCP_ENDPOINT = `${BUILTIN_API}/api/agent/mcp`;
@@ -60,6 +61,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
@@ -124,10 +126,19 @@ handoff options (agent token required; consent scope pingroom:handoffs:create):
 handoffs options (agent token required; consent scope pingroom:handoffs:create):
       --state <s>        open | all (default open)
 
+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
+
 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,14 +149,15 @@ 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
@@ -165,8 +177,9 @@ mcp:
                                    (output-only; does not change client config)
 
 activate:
-  pingroom activate                Replay or create the next Agent Inbox test using
-                                   the saved QR-paired credential
+  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:
   pingroom config list              Print the stored settings
@@ -190,11 +203,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,
@@ -287,6 +299,32 @@ 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) {
+  const base =
+    (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,6 +500,20 @@ 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);
+  }
+}
+
 function stripControlChars(value) {
   // eslint-disable-next-line no-control-regex
   return String(value).replace(/[\u0000-\u001F\u007F-\u009F]/g, '');
@@ -534,6 +586,9 @@ function parseQArgs(argv) {
     '--text-max': 'text_max',
     '--timeout': 'timeout',
     '--state': 'state',
+    '--limit': 'limit',
+    '--from': 'from',
+    '--once': 'once',
     '--token': 'token',
     '--room': 'room',
     '--api': 'api',
@@ -541,7 +596,7 @@ function parseQArgs(argv) {
     '--json': 'json',
     '-h': 'help', '--help': 'help',
   };
-  const booleans = new Set(['wait', 'json', 'help']);
+  const booleans = new Set(['wait', 'json', 'help', 'once']);
   const multi = new Set(['option']);
 
   for (let i = 0; i < argv.length; i++) {
@@ -772,7 +827,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}`);
     }
 
@@ -787,6 +842,8 @@ async function ping(args) {
 
   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 +947,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,6 +962,26 @@ 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) {
@@ -1045,7 +1122,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 +1132,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 +1177,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 +1234,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}`);
   }
 
@@ -1242,7 +1325,7 @@ async function waitForResolution(id, args, { token, apiBase }) {
     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') {
@@ -1259,6 +1342,8 @@ async function ask(args) {
 
   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 });
 
@@ -1294,7 +1379,7 @@ async function ask(args) {
   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}`);
   }
 
@@ -1323,7 +1408,7 @@ async function cancel(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`);
@@ -1338,7 +1423,7 @@ async function list(args) {
   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,6 +1437,98 @@ 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(`${HELP}\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; }
   const { token, apiBase } = agentContext(args);
@@ -1363,7 +1540,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; }
@@ -1479,7 +1656,7 @@ async function waitForHandoff(id, args, { token, apiBase }, initialDeliveryState
     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)) {
@@ -1503,6 +1680,7 @@ async function handoff(args) {
 
   const message = args.message;
   if (!message) fail('a --message is required', EXIT.USAGE);
+  requireMaxLength(message, 500, '--message');
 
   const { token, apiBase } = agentContext(args);
 
@@ -1552,7 +1730,7 @@ async function handoff(args) {
   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') {
@@ -1655,7 +1833,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;
 }
@@ -1984,12 +2162,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 +2299,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 +2324,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) {
@@ -2391,7 +2589,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 +2705,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 +2722,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;
@@ -2804,6 +3016,7 @@ const COMMANDS = {
   list: (rest) => list(parseQArgs(rest)),
   handoff: (rest) => handoff(parseHandoffArgs(rest)),
   handoffs: (rest) => listHandoffs(parseQArgs(rest)),
+  listen: (rest) => listen(parseQArgs(rest)),
   hook: (rest) => hook(parseHookArgs(rest)),
   mcp,
   activate: (rest) => activateStoredInbox(parseQArgs(rest)),
@@ -2847,4 +3060,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))}`);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingroom/cli",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Send PingRoom Pings and wait for human decisions from CI, scripts, and agents.",
   "type": "module",
   "bin": {