@pingroom/cli 0.2.0 → 0.6.0

package/bin/pingroom.js

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 // @pingroom/cli — pings and human-in-the-loop questions for CI, scripts, agents.
-// Zero dependencies: uses Node's built-in fetch (Node >= 20).
+// Node's built-in fetch (Node >= 20) plus one optional dependency,
+// `qrcode-terminal`, used only to draw the pairing QR. Its absence degrades to
+// printing the pair URL, so every non-interactive path stays dependency-free.
+//
+// Run bare (`pingroom`) it resolves its own auth: connected -> a status line and
+// this help; not connected -> the pairing picker. There is deliberately no
+// `login` subcommand.
 //
 // Commands:
 //   ping     Send a ping to a room. Webhook mode (a room URL carries its own
@@ -10,10 +16,32 @@
 //   watch    Block until a question resolves and print the outcome.
 //   list     List the agent's questions by state.
 //   cancel   Withdraw a pending question.
+//   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.
+//   live     Drive a live progress card (iOS Live Activity / Android live
+//            update) on the room members' lock screen: start / update / end.
+//   config   Read/write ~/.pingroom/config.json (default_room, api_url).
+//   logout   Forget the credential in ~/.pingroom/credentials.json.
 //
-// Exit codes: 0 success/answered · 1 error · 2 bad usage · 3 expired · 4 cancelled.
+// Exit codes: 0 success/answered/acked · 1 error · 2 bad usage · 3 expired ·
+// 4 cancelled/recipient-not-ready.
+
+import { randomBytes } from 'node:crypto';
+import {
+  appendFileSync, chmodSync, closeSync, fchmodSync, mkdirSync, openSync,
+  readFileSync, renameSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 
-const DEFAULT_API = process.env.PINGROOM_API_URL || 'https://api.pingroom.io';
+// Kept in lockstep with package.json / package-lock.json / action.yml (a test
+// asserts the GitHub Action pins this exact version). `hook --print-config`
+// emits an `npx @pingroom/cli@<VERSION>` command, so it must match too.
+const VERSION = '0.6.0';
+
+const BUILTIN_API = 'https://api.pingroom.io';
+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
 
@@ -26,42 +54,145 @@ Commands:
   watch    Block until a question resolves and print the outcome
   list     List the agent's questions by state
   cancel   Withdraw a pending question
+  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
+  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
+  config   Read/write local settings (config list | get <key> | set <key> <val>)
+  logout   Forget the stored credential
 
 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
   -d, --data <json>      Extra JSON data object, e.g. '{"commit":"abc123"}'
+      --url <https-url>  Make the ping a tappable link (absolute http(s) URL)
+      --button-label <t> Link button text (<= 26 chars; requires --url)
+      --require-ack      Keep the ping open until an eligible recipient acknowledges it
+      --ack-timeout <s>  Ack deadline in seconds (requires --require-ack)
   -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)
 
 ask options (agent token required):
   -p, --prompt <text>    The question a human reads (required)
-  -o, --option <v:label> An answer option; repeat for 2–4. Omit for Approve/Deny
+  -o, --option <v:label[:style]>
+                         An answer option (style: primary|danger|default);
+                         repeat for 2–4. Omit for Approve/Deny
   -c, --context <text>   Secondary line, e.g. a build number (<= 40 chars)
       --scope <s>        Who answers: 'direct' (default) or 'room'
       --target <uuid>    For --scope direct: a specific room member
       --ttl <seconds>    Expiry; omit for the server default (1h; 30..86400)
+      --text-input <ph>  Invite a short typed answer; <ph> is the placeholder
+      --text-max <n>     Max typed-answer length (1..60)
       --wait             Block until answered/expired/cancelled
       --timeout <sec>    Per long-poll hold with --wait/watch (0–30, default 25)
   -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)
 
 list options:
       --state <s>        pending | answered | expired | cancelled | all
 
+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.
+  -o, --option <v:label> A question option; repeat for 2–4. Requires --question.
+      --target <id>      Recipient: 'me' (default) or a specific user uuid
+      --expires-in <s>   Expiry in seconds (120..86400, default 900)
+      --urgency <u>      'active' (default) or 'passive'
+      --idempotency-key <key>  Dedupe key; retries reuse it (Idempotency-Key)
+      --correlation-id <id>    Opaque id echoed on every read of this handoff
+      --reply-to <id>    Opaque reply-to id echoed back
+  -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
+
+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):
+  -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)
+      --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
+      --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
+      --step <n>             Current step index (steps template)
+      --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
+                             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
+  -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
+
+hook options (agent token required; reads a Claude Code hook event on stdin):
+      --room <code>      Room invite code (or env PINGROOM_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
+
+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
+
 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
 
+Connecting:
+  Run "pingroom" with no arguments to connect. It prints a QR code you scan with
+  the PingRoom app — you pick the account and the delivery room there — or you
+  can choose the emailed-code fallback. There is no "login" command: being
+  unconnected is a state the tool resolves, not one you have to discover.
+
+  The credential is written to ~/.pingroom/credentials.json (mode 0600, in a
+  0700 directory). PINGROOM_HOME overrides that directory. PINGROOM_TOKEN in the
+  environment ALWAYS wins over the stored credential, so CI is unaffected.
+  "pingroom logout" forgets it.
+
+  Settings precedence, highest first:
+    explicit flag  >  env var  >  ~/.pingroom/config.json  >  the paired
+    credential  >  built-in default
+  So --room beats PINGROOM_ROOM beats "config set default_room", and --api beats
+  PINGROOM_API_URL beats "config set api_url" beats the host you paired against,
+  beats ${BUILTIN_API}. The credential layer is why a token minted by a
+  self-hosted server is never presented to ${BUILTIN_API}.
+
+  Non-interactive shells (CI, pipes) never prompt and never draw a QR: set
+  PINGROOM_TOKEN there instead.
+
 Examples:
   pingroom ping -w "$PINGROOM_WEBHOOK_URL" -m "Deploy succeeded ✅"
   pingroom ping --token "$PINGROOM_TOKEN" --room ab12cd -m "Release shipped"
 
+  # Link ping — a tappable button that opens a URL:
+  pingroom ping -w "$PINGROOM_WEBHOOK_URL" -m "Build 512 ready" \\
+    --url https://ci.example.com/builds/512 --button-label "Open build"
+
   # Gate a deploy on a human tap — the chosen value prints to stdout:
   if [ "$(pingroom ask --token "$T" --room ab12cd --wait \\
         -p 'Deploy 1.4.0 to production?')" = approve ]; then ./deploy.sh; fi
@@ -74,14 +205,40 @@ Examples:
   pingroom watch --token "$T" q_01H...   # block on an existing question
   pingroom cancel --token "$T" q_01H...
 
+  # Hand a deploy decision to yourself and block on the acknowledgement:
+  pingroom handoff --token "$T" -m "Prod deploy 1.4.0 — ack to proceed" --wait
+
+  # A blocking question handed to a specific human; branch in CI on exit code:
+  pingroom handoff --token "$T" -m "Ship 1.4.0?" --question \\
+    -o deploy:Deploy -o hold:Hold --wait
+  # -> exit 0 (answered, any value incl. 'hold'); 3 expired; 4 recipient-not-ready
+
+  pingroom handoffs --token "$T" --state all   # recent history (up to 200/kind)
+
+  # A live deploy card on everyone's lock screen — one stream, three calls:
+  pingroom live start --token "$T" --room ab12cd -c "deploy-$GITHUB_RUN_ID" \\
+    --template steps --steps "Build,Test,Stage,Ship" -t "Deploy 2.1.0"
+  pingroom live update --token "$T" --room ab12cd -c "deploy-$GITHUB_RUN_ID" \\
+    --step 2 -m "Smoke tests green"
+  pingroom live end --token "$T" --room ab12cd -c "deploy-$GITHUB_RUN_ID" \\
+    -m "Live on production"
+  # ...or end it as a failure, which still delivers one completion alert:
+  #   pingroom live end ... --failed -m "Rollback triggered"
+
+  # Connect Claude Code to your phone (prints the settings.json to paste):
+  pingroom hook --print-config
+
 Security:
   Prefer the env vars (PINGROOM_WEBHOOK_URL / PINGROOM_TOKEN) over passing
   secrets as --webhook / --token flags: argv is visible to other users via the
   process table (ps) and may be captured in shell history. URLs must use https
   (loopback http is allowed for local dev).
 
-Exit codes: 0 on success (answered), 1 on error, 2 on bad usage,
-3 when a question expired, 4 when it was cancelled.`;
+Exit codes: 0 on success (answered / acked), 1 on error (network/auth/5xx),
+2 on bad usage, 3 when a handoff or question expired, 4 when it was cancelled
+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 EXIT = { OK: 0, ERROR: 1, USAGE: 2, EXPIRED: 3, CANCELLED: 4 };
 
@@ -90,6 +247,149 @@ function fail(message, code = EXIT.ERROR) {
   process.exit(code);
 }
 
+// --- local state (~/.pingroom) ---------------------------------------------
+//
+// Two files, both under a 0700 directory:
+//   credentials.json  the agent credential this machine paired (mode 0600)
+//   config.json       user settings: default_room, api_url
+//
+// PINGROOM_HOME relocates the directory (tests, sandboxes, multi-account
+// shells). Every lookup is layered: explicit flag > env var > config file >
+// the paired credential > built-in default. PINGROOM_TOKEN is the one env var
+// that also outranks the stored credential, which is what keeps CI working
+// untouched.
+
+function pingroomHome() {
+  return process.env.PINGROOM_HOME || join(homedir(), '.pingroom');
+}
+
+function credentialsPath() { return join(pingroomHome(), 'credentials.json'); }
+function configPath() { return join(pingroomHome(), 'config.json'); }
+
+// Read a JSON object, or null for anything unreadable/corrupt. Local state must
+// never be able to crash a ping: a hand-edited file degrades to "not set".
+function readJsonFile(path) {
+  let raw;
+  try { raw = readFileSync(path, 'utf8'); } catch { return null; }
+  let value;
+  try { value = JSON.parse(raw); } catch { return null; }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  return value;
+}
+
+// Write JSON with restrictive permissions, atomically.
+//
+// Writing in place truncates first, so a crash or a full disk between truncate
+// and write leaves a half-written file — and readJsonFile() degrades anything
+// unparseable to {}, so the *next* `config set` would silently drop every other
+// setting. Writing a sibling temp file and renaming over the target means a
+// reader only ever sees the old file or the new one, never a torn one.
+//
+// The temp file is opened 'wx' with mode 0600 and fchmod'd before a single byte
+// is written: `mode` on an existing file is ignored and a post-write chmod
+// leaves a window where the credential is world-readable. rename() carries the
+// 0600 over the target, so a pre-existing loose file is tightened too.
+//
+// mkdirSync(recursive) returns the first path it created, or undefined when the
+// directory already existed. chmod'ing only on the former keeps this from
+// narrowing a directory the user deliberately created at 0755.
+function writeJsonFile(path, value) {
+  const dir = pingroomHome();
+  const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  let fd;
+  try {
+    const created = mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (created !== undefined) chmodSync(dir, 0o700);
+
+    fd = openSync(tmp, 'wx', 0o600);
+    fchmodSync(fd, 0o600); // defeat a permissive umask masking the open mode
+    writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+    closeSync(fd);
+    fd = undefined;
+    renameSync(tmp, path);
+  } catch (err) {
+    if (fd !== undefined) { try { closeSync(fd); } catch { /* already gone */ } }
+    try { unlinkSync(tmp); } catch { /* never created */ }
+    fail(`could not write ${path}: ${err.message}`);
+  }
+}
+
+function readStoredCredential() {
+  const cred = readJsonFile(credentialsPath());
+  if (!cred || typeof cred.token !== 'string' || cred.token === '') return null;
+  return cred;
+}
+
+function readConfigFile() {
+  return readJsonFile(configPath()) || {};
+}
+
+/** Agent token: --token > PINGROOM_TOKEN > the paired credential. */
+function resolveToken(args) {
+  return args.token || process.env.PINGROOM_TOKEN || readStoredCredential()?.token || undefined;
+}
+
+/**
+ * API base: --api > PINGROOM_API_URL > config.api_url > the host the credential
+ * was paired against > built-in, no trailing slash.
+ *
+ * The credential layer is not optional. saveCredential() records `api_url`, and
+ * a token minted by a self-hosted / staging server is only valid there; without
+ * this layer the next command would present that bearer to api.pingroom.io —
+ * leaking it to a host it was never issued for. resolveRoom() already consults
+ * the credential last, so the two layerings now agree.
+ */
+function resolveApiBase(args) {
+  const raw = args.api
+    || process.env.PINGROOM_API_URL
+    || readConfigFile().api_url
+    || readStoredCredential()?.api_url
+    || BUILTIN_API;
+  return String(raw).replace(/\/$/, '');
+}
+
+/**
+ * Room invite code: --room > PINGROOM_ROOM > config.default_room > the room the
+ * credential was paired to. The paired room is last because it is the weakest
+ * signal — it is where the agent was told to deliver, not necessarily where
+ * this invocation means to.
+ */
+function resolveRoom(args) {
+  return args.room
+    || process.env.PINGROOM_ROOM
+    || readConfigFile().default_room
+    || readStoredCredential()?.room?.invite_code
+    || undefined;
+}
+
+/**
+ * True when it is safe to prompt / draw a QR. Both streams must be a TTY: a
+ * piped stdin cannot answer a prompt and a piped stdout would capture the QR as
+ * garbage.
+ *
+ * The override is deliberately double-locked (internal-looking name AND
+ * NODE_ENV=test) and not documented in --help. A single well-known env var
+ * shipping in the published binary is one stray `export` away from making a CI
+ * job prompt into the void and poll for the full 15-minute pairing window
+ * instead of failing in a second.
+ */
+function isInteractive() {
+  if (process.env.PINGROOM_INTERNAL_TEST_TTY === '1' && process.env.NODE_ENV === 'test') return true;
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => { setTimeout(resolve, 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.
+function stripControlChars(value) {
+  // eslint-disable-next-line no-control-regex
+  return String(value).replace(/[\u0000-\u001F\u007F-\u009F]/g, '');
+}
+
 // --- ping (unchanged wire behaviour) ---------------------------------------
 
 function parseArgs(argv) {
@@ -100,22 +400,33 @@ function parseArgs(argv) {
     '-a': 'action', '--action': 'action',
     '-d': 'data', '--data': 'data',
     '-w': 'webhook', '--webhook': 'webhook',
+    '--url': 'url',
+    '--button-label': 'button_label',
+    '--require-ack': 'require_ack',
+    '--ack-timeout': 'ack_timeout',
     '--token': 'token',
     '--room': 'room',
     '--api': 'api',
     '--json': 'json',
     '-h': 'help', '--help': 'help',
   };
+  const booleans = new Set(['require_ack', 'json', 'help']);
 
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i];
-    if (token === '--json' || token === '-h' || token === '--help') {
-      args[alias[token]] = true;
-      continue;
-    }
-    const key = alias[token];
-    if (key) {
-      args[key] = 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);
+      }
+      args[key] = value;
     } else if (token.startsWith('-')) {
       fail(`Unknown option: ${token}`, EXIT.USAGE);
     } else {
@@ -138,6 +449,9 @@ function parseQArgs(argv) {
     '--ttl': 'ttl',
     '-d': 'data', '--data': 'data',
     '--correlation-id': 'correlation_id',
+    '--reply-to': 'reply_to',
+    '--text-input': 'text_input',
+    '--text-max': 'text_max',
     '--timeout': 'timeout',
     '--state': 'state',
     '--token': 'token',
@@ -152,7 +466,59 @@ function parseQArgs(argv) {
 
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i];
-    const key = alias[token];
+    // 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;
+}
+
+// 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 = {
+    '-m': 'message', '--message': 'message',
+    '--question': 'question',
+    '-o': 'option', '--option': 'option',
+    '--target': 'target',
+    '--expires-in': 'expires_in',
+    '--urgency': 'urgency',
+    '--idempotency-key': 'idempotency_key',
+    '--correlation-id': 'correlation_id',
+    '--reply-to': 'reply_to',
+    '-d': 'data', '--data': 'data',
+    '--timeout': 'timeout',
+    '--github-output': 'github_output',
+    '--token': 'token',
+    '--api': 'api',
+    '--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) {
@@ -203,7 +569,11 @@ function parseDataObject(raw) {
   return data;
 }
 
-async function httpJson(method, url, { body, headers = {} } = {}) {
+// `soft: true` returns { error } instead of exiting on a transport failure. Only
+// the pairing poll passes it: there, a single DNS blip or dropped connection
+// would otherwise kill a 15-minute wait the human is still walking towards their
+// phone for. Every other caller keeps the hard exit.
+async function httpJson(method, url, { body, headers = {}, soft = false } = {}) {
   let res;
   try {
     res = await fetch(url, {
@@ -216,10 +586,18 @@ async function httpJson(method, url, { body, headers = {} } = {}) {
       ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
     });
   } catch (err) {
+    if (soft) return { res: null, text: '', json: null, error: err };
     fail(`network error: ${err.message}`);
   }
 
-  const text = await res.text();
+  let text;
+  try {
+    text = await res.text();
+  } catch (err) {
+    // A connection dropped mid-body throws here, not at fetch().
+    if (soft) return { res: null, text: '', json: null, error: err };
+    fail(`network error: ${err.message}`);
+  }
   let json = null;
   try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
 
@@ -236,35 +614,82 @@ async function ping(args) {
     fail('--action must be an integer 1–4', EXIT.USAGE);
   }
 
+  let ackTimeout;
+  if (args.ack_timeout !== undefined) {
+    if (!args.require_ack) {
+      fail('--ack-timeout requires --require-ack', EXIT.USAGE);
+    }
+    if (!/^\d+$/.test(String(args.ack_timeout))) {
+      fail('--ack-timeout must be an integer number of seconds', EXIT.USAGE);
+    }
+    ackTimeout = Number(args.ack_timeout);
+  }
+
   let data;
   if (args.data !== undefined) {
     data = parseDataObject(args.data);
   }
 
+  // Link ping: --url/--button-label fold into the structured data object
+  // (server contract: data.url = absolute http(s) <= 2048, data.button_label <= 26).
+  if (args.button_label !== undefined && args.url === undefined) {
+    fail('--button-label requires --url', EXIT.USAGE);
+  }
+  if (args.url !== undefined) {
+    let linkUrl;
+    try {
+      linkUrl = new URL(args.url);
+    } catch {
+      fail('--url is not a valid URL', EXIT.USAGE);
+    }
+    if (linkUrl.protocol !== 'https:' && linkUrl.protocol !== 'http:') {
+      fail('--url must be an absolute http(s) URL', EXIT.USAGE);
+    }
+    if (args.url.length > 2048) {
+      fail('--url must be at most 2048 characters', EXIT.USAGE);
+    }
+    if (args.button_label !== undefined && args.button_label.length > 26) {
+      fail('--button-label must be at most 26 characters', EXIT.USAGE);
+    }
+    data = { ...(data || {}), url: args.url };
+    if (args.button_label !== undefined) data.button_label = args.button_label;
+  }
+
   const webhook = args.webhook || process.env.PINGROOM_WEBHOOK_URL;
-  const token = args.token || process.env.PINGROOM_TOKEN;
-  const apiBase = (args.api || DEFAULT_API).replace(/\/$/, '');
+  const token = resolveToken(args);
+  const apiBase = resolveApiBase(args);
+  const room = resolveRoom(args);
 
   let result;
 
   if (webhook) {
+    if (ackTimeout !== undefined && (ackTimeout < 1 || ackTimeout > 86_400)) {
+      fail('--ack-timeout must be between 1 and 86400 seconds for a webhook ping', EXIT.USAGE);
+    }
     requireSafeUrl('--webhook', webhook);
     const body = { message };
     if (args.title) body.title = args.title;
     if (args.action !== undefined) body.action = Number(args.action);
     if (data) body.data = data;
+    if (args.require_ack) body.requires_ack = true;
+    if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
     result = await httpJson('POST', webhook, { body });
   } else if (token) {
-    if (!args.room) fail('--room is required when using --token', EXIT.USAGE);
+    if (!room) fail('--room is required when using --token (or set one with "pingroom config set default_room <code>")', EXIT.USAGE);
+    if (ackTimeout !== undefined && (ackTimeout < 60 || ackTimeout > 86_400)) {
+      fail('--ack-timeout must be between 60 and 86400 seconds for an agent room ping', EXIT.USAGE);
+    }
     requireSafeUrl('--api', apiBase);
-    const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(args.room)}/notifications`;
+    const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/notifications`;
     const body = { message };
     if (args.title) body.title = args.title;
     if (args.action !== undefined) body.action_number = Number(args.action);
     if (data) body.data = data;
+    if (args.require_ack) body.requires_ack = true;
+    if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
     result = await httpJson('POST', url, { body, headers: { Authorization: `Bearer ${token}` } });
   } else {
-    fail('provide a webhook (--webhook / PINGROOM_WEBHOOK_URL) or an agent token (--token / PINGROOM_TOKEN)', EXIT.USAGE);
+    fail('provide a webhook (--webhook / PINGROOM_WEBHOOK_URL) or an agent token (--token / PINGROOM_TOKEN, or run "pingroom" to connect)', EXIT.USAGE);
   }
 
   const { res, text, json } = result;
@@ -284,15 +709,275 @@ async function ping(args) {
   return EXIT.OK;
 }
 
+// --- live status -----------------------------------------------------------
+
+// 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 = {
+    '-c': 'correlation_id', '--correlation-id': 'correlation_id',
+    '-t': 'title', '--title': 'title',
+    '-m': 'message', '--message': 'message',
+    '--template': 'template',
+    '--category': 'category',
+    '--progress': 'progress',
+    '--step': 'step',
+    '--steps': 'steps',
+    '--metric': 'metric',
+    '--deadline-at': 'deadline_at',
+    '--eta-at': 'eta_at',
+    '--prompt': 'prompt',
+    '--option': 'option',
+    '--left': 'left',
+    '--right': 'right',
+    '--center': 'center',
+    '--accent-override': 'accent_override',
+    '--failed': 'failed',
+    '-a': 'action', '--action': 'action',
+    '-d': 'data', '--data': 'data',
+    '--require-ack': 'require_ack',
+    '--ack-timeout': 'ack_timeout',
+    '-w': 'webhook', '--webhook': 'webhook',
+    '--token': 'token',
+    '--room': 'room',
+    '--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;
+}
+
+// "label:value" -> {label, value}. Only the first colon splits.
+function buildMetrics(list) {
+  if (!list || list.length === 0) return undefined;
+  return list.map((spec) => {
+    const idx = spec.indexOf(':');
+    if (idx <= 0) fail(`--metric must be "label:value" (got "${spec}")`, EXIT.USAGE);
+    return { label: spec.slice(0, idx), value: spec.slice(idx + 1) };
+  });
+}
+
+// "value:label" -> {value, label}; a bare token is both. Matches the `ask`
+// command's option syntax minus `style`, which live_status options don't carry.
+function buildLiveOptions(list) {
+  if (!list || list.length === 0) return undefined;
+  return list.map((spec) => {
+    const idx = spec.indexOf(':');
+    if (idx < 0) return { value: spec, label: spec };
+    if (idx === 0) fail(`--option needs a value before the colon (got "${spec}")`, EXIT.USAGE);
+    return { value: spec.slice(0, idx), label: spec.slice(idx + 1) };
+  });
+}
+
+// "label:value" -> {label, value}, for --left / --right on the matchup template.
+function buildSide(spec, flag) {
+  if (spec === undefined) return undefined;
+  const idx = spec.indexOf(':');
+  if (idx <= 0) fail(`${flag} must be "label:value" (got "${spec}")`, EXIT.USAGE);
+  return { label: spec.slice(0, idx), value: spec.slice(idx + 1) };
+}
+
+// The server accepts #rrggbb with or without the leading #; normalize to one
+// form so a shell that ate the # (unquoted) still produces a valid payload.
+function normalizeAccent(raw) {
+  if (raw === undefined) return undefined;
+  const hex = raw.trim().replace(/^#/, '');
+  if (!/^[0-9A-Fa-f]{6}$/.test(hex)) {
+    fail(`--accent-override must be a 6-digit hex color (got "${raw}")`, EXIT.USAGE);
+  }
+  return `#${hex.toLowerCase()}`;
+}
+
+function numberOption(raw, flag, { min, max, integer = false } = {}) {
+  if (raw === undefined) return undefined;
+  const value = Number(raw);
+  if (!Number.isFinite(value)) fail(`${flag} must be a number`, EXIT.USAGE);
+  if (integer && !Number.isInteger(value)) fail(`${flag} must be an integer`, EXIT.USAGE);
+  if (min !== undefined && value < min) fail(`${flag} must be at least ${min}`, EXIT.USAGE);
+  if (max !== undefined && value > max) fail(`${flag} must be at most ${max}`, EXIT.USAGE);
+  return value;
+}
+
+/**
+ * Drive a live progress card on the room members' lock screen.
+ *
+ * One correlation id = one stream: `start` opens it (one alert), `update` moves
+ * it silently, `end` closes it with one completion alert. Works with either an
+ * agent token (--token, needs pingroom:live:write) or a room's incoming webhook
+ * (--webhook), which speak the same `live_status` contract.
+ */
+async function live(args) {
+  const sub = args._[0];
+  const known = ['start', 'update', 'end', 'get'];
+  if (!sub || !known.includes(sub)) {
+    fail(`live needs a subcommand: ${known.join(' | ')}`, EXIT.USAGE);
+  }
+
+  const correlationId = args.correlation_id;
+  if (!correlationId) fail('--correlation-id is required', EXIT.USAGE);
+
+  const webhook = args.webhook || process.env.PINGROOM_WEBHOOK_URL;
+  const token = resolveToken(args);
+  const apiBase = resolveApiBase(args);
+  const room = resolveRoom(args);
+
+  if (sub === 'get') {
+    if (!token) fail('live get requires an agent token (--token or PINGROOM_TOKEN)', EXIT.USAGE);
+    if (!room) fail('--room is required', EXIT.USAGE);
+    requireSafeUrl('--api', apiBase);
+    const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/live/${encodeURIComponent(correlationId)}`;
+    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}`}`);
+    }
+    if (!args.json) process.stdout.write(`${(json && json.state) || 'unknown'}\n`);
+    return EXIT.OK;
+  }
+
+  const liveStatus = {
+    state: sub === 'end' ? (args.failed ? 'failed' : 'done') : 'running',
+  };
+
+  if (args.message !== undefined) liveStatus.message = args.message;
+  if (args.prompt !== undefined) liveStatus.prompt = args.prompt;
+
+  const progress = numberOption(args.progress, '--progress', { min: 0, max: 1 });
+  if (progress !== undefined) liveStatus.progress = progress;
+
+  const step = numberOption(args.step, '--step', { min: 0, max: 8, integer: true });
+  if (step !== undefined) liveStatus.current_step = step;
+
+  const deadlineAt = numberOption(args.deadline_at, '--deadline-at', { min: 0, integer: true });
+  if (deadlineAt !== undefined) liveStatus.deadline_at = deadlineAt;
+
+  const etaAt = numberOption(args.eta_at, '--eta-at', { min: 0, integer: true });
+  if (etaAt !== undefined) liveStatus.eta_at = etaAt;
+
+  const metrics = buildMetrics(args.metric);
+  if (metrics) liveStatus.metrics = metrics;
+
+  const options = buildLiveOptions(args.option);
+  if (options) {
+    if (options.length > 4) fail('--option accepts at most 4 choices', EXIT.USAGE);
+    liveStatus.options = options;
+  }
+
+  const left = buildSide(args.left, '--left');
+  if (left) liveStatus.left = left;
+  const right = buildSide(args.right, '--right');
+  if (right) liveStatus.right = right;
+  if (args.center !== undefined) liveStatus.center = args.center;
+
+  const accent = normalizeAccent(args.accent_override);
+  if (accent) liveStatus.accent_override = accent;
+
+  // Template, category and step labels are fixed when the stream is created;
+  // sending them on an update is a no-op server-side, so only `start` takes them.
+  if (sub === 'start') {
+    if (args.template) liveStatus.template = args.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.
+    if (args.category) {
+      if (!['status', 'steps', 'alert'].includes(args.category)) {
+        fail('--category must be status, steps or alert', EXIT.USAGE);
+      }
+      liveStatus.category = args.category;
+    }
+    if (args.steps) {
+      const labels = args.steps.split(',').map((s) => s.trim()).filter(Boolean);
+      if (labels.length < 2 || labels.length > 8) {
+        fail('--steps needs between 2 and 8 comma-separated labels', EXIT.USAGE);
+      }
+      liveStatus.steps = labels;
+    }
+  } else if (args.template || args.steps || args.category) {
+    fail('--template, --category and --steps are fixed at stream creation; pass them to "live start"', EXIT.USAGE);
+  }
+
+  const body = { correlation_id: correlationId, live_status: liveStatus };
+  if (args.title) body.title = args.title;
+  if (args.action !== undefined) body.action = Number(args.action);
+  // Same object-shape guard ping/ask/handoff use. A bare JSON.parse also accepts
+  // an array, which the server then rejects — a wasted round trip for what is a
+  // local usage error.
+  // `!== undefined`, not truthiness: `-d ''` is a malformed value, and a
+  // truthiness test drops it on the floor and ships the ping without the data
+  // the caller believed they attached. ping/ask/handoff all reject it loudly.
+  if (args.data !== undefined) body.data = parseDataObject(args.data);
+  if (args.require_ack) body.requires_ack = true;
+  const ackTimeout = numberOption(args.ack_timeout, '--ack-timeout', { min: 1, max: 86_400, integer: true });
+  if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
+
+  let result;
+  if (webhook) {
+    requireSafeUrl('--webhook', webhook);
+    result = await httpJson('POST', webhook, { body });
+  } else if (token) {
+    if (!room) fail('--room is required when using --token (or set one with "pingroom config set default_room <code>")', EXIT.USAGE);
+    requireSafeUrl('--api', apiBase);
+    const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/live`;
+    result = await httpJson('POST', url, { body, headers: { Authorization: `Bearer ${token}` } });
+  } else {
+    fail('provide a webhook (--webhook / PINGROOM_WEBHOOK_URL) or an agent token (--token / PINGROOM_TOKEN, or run "pingroom" to connect)', EXIT.USAGE);
+  }
+
+  const { res, text, json } = result;
+  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}`;
+    fail(`live ${sub} failed: ${detail}`);
+  }
+
+  if (!args.json) {
+    const state = (json && (json.state || (json.live_status && json.live_status.state))) || sub;
+    process.stdout.write(`live ${sub} → ${state} ✅\n`);
+  }
+  return EXIT.OK;
+}
+
 // --- questions -------------------------------------------------------------
 
+// Resolve the credential + endpoint a token-only command needs. When nothing is
+// available this is a usage error pointing at PINGROOM_TOKEN — never a prompt,
+// so a CI job fails in a second instead of hanging on an invisible question.
 function agentContext(args, { needRoom = false } = {}) {
-  const token = args.token || process.env.PINGROOM_TOKEN;
-  if (!token) fail('an agent token is required (--token or PINGROOM_TOKEN)', EXIT.USAGE);
-  const apiBase = (args.api || DEFAULT_API).replace(/\/$/, '');
+  const token = resolveToken(args);
+  if (!token) {
+    fail(
+      'an agent token is required (--token or PINGROOM_TOKEN). Run "pingroom" in an interactive terminal to connect this machine; in CI set PINGROOM_TOKEN.',
+      EXIT.USAGE,
+    );
+  }
+  const apiBase = resolveApiBase(args);
   requireSafeUrl('--api', apiBase);
-  if (needRoom && !args.room) fail('--room is required', EXIT.USAGE);
-  return { token, apiBase, room: args.room };
+  const room = resolveRoom(args);
+  if (needRoom && !room) {
+    fail('--room is required (or set one with "pingroom config set default_room <code>")', EXIT.USAGE);
+  }
+  return { token, apiBase, room };
 }
 
 // value:label -> {value, label}. Labels may contain colons (only the first
@@ -302,9 +987,20 @@ function buildOptions(list) {
   return list.map((spec) => {
     const idx = spec.indexOf(':');
     const value = idx === -1 ? spec : spec.slice(0, idx);
-    const label = idx === -1 ? spec : spec.slice(idx + 1);
-    if (!value) fail(`--option must be "value" or "value:label" (got "${spec}")`, EXIT.USAGE);
-    return { value, label };
+    let label = idx === -1 ? spec : spec.slice(idx + 1);
+    if (!value) fail(`--option must be "value", "value:label" or "value:label:style" (got "${spec}")`, EXIT.USAGE);
+    // A trailing :primary|:danger|:default segment styles the button; any other
+    // trailing segment stays part of the label (labels may contain colons).
+    let style;
+    const lastColon = label.lastIndexOf(':');
+    if (lastColon !== -1) {
+      const candidate = label.slice(lastColon + 1);
+      if (candidate === 'primary' || candidate === 'danger' || candidate === 'default') {
+        style = candidate;
+        label = label.slice(0, lastColon);
+      }
+    }
+    return style ? { value, label, style } : { value, label };
   });
 }
 
@@ -375,6 +1071,19 @@ async function ask(args) {
     body.ttl = Number(args.ttl);
   }
   if (args.correlation_id !== undefined) body.correlation_id = args.correlation_id;
+  if (args.reply_to !== undefined) body.reply_to = args.reply_to;
+  if (args.text_input !== undefined || args.text_max !== undefined) {
+    const textInput = {};
+    if (args.text_input) textInput.placeholder = String(args.text_input).slice(0, 60);
+    if (args.text_max !== undefined) {
+      const n = Number(args.text_max);
+      if (!/^\d+$/.test(String(args.text_max)) || n < 1 || n > 60) {
+        fail('--text-max must be an integer between 1 and 60', EXIT.USAGE);
+      }
+      textInput.max_length = n;
+    }
+    body.text_input = textInput;
+  }
   if (args.data !== undefined) body.data = parseDataObject(args.data);
 
   const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/questions`;
@@ -438,26 +1147,1107 @@ async function list(args) {
   return EXIT.OK;
 }
 
-const COMMANDS = {
-  ping: (rest) => ping(parseArgs(rest)),
-  ask: (rest) => ask(parseQArgs(rest)),
-  watch: (rest) => waitFrom(watch, rest),
-  await: (rest) => waitFrom(watch, rest),
-  cancel: (rest) => cancel(parseQArgs(rest)),
-  list: (rest) => list(parseQArgs(rest)),
-};
+async function listHandoffs(args) {
+  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  const { token, apiBase } = agentContext(args);
+  const state = args.state || 'open';
+  if (state !== 'open' && state !== 'all') {
+    fail("--state must be 'open' or 'all' for handoffs", EXIT.USAGE);
+  }
 
-function waitFrom(handler, rest) {
-  return handler(parseQArgs(rest));
+  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}`;
+    fail(`handoffs list failed: ${detail}`);
+  }
+  if (args.json) { process.stdout.write(`${text}\n`); return EXIT.OK; }
+
+  const handoffs = (json && json.handoffs) || [];
+  if (handoffs.length === 0) { process.stdout.write('no handoffs\n'); return EXIT.OK; }
+  for (const h of handoffs) {
+    const answer = h.answer && (h.answer.value ?? h.answer.text);
+    const outcome = answer !== undefined && answer !== null ? ` → ${answer}` : '';
+    process.stdout.write(
+      `${h.id}  ${String(h.kind || '').padEnd(8)}  ${String(h.state || '').padEnd(9)}  ${h.prompt || ''}${outcome}\n`,
+    );
+  }
+  return EXIT.OK;
 }
 
-async function main() {
-  const argv = process.argv.slice(2);
-  const command = argv[0];
+// --- handoff ---------------------------------------------------------------
 
-  if (!command || command === '-h' || command === '--help' || command === 'help') {
-    process.stdout.write(`${HELP}\n`);
-    process.exit(EXIT.OK);
+// Terminal wire states across both kinds. ack: open→acked|expired.
+// question: pending→answered|expired|cancelled. `open`/`pending` are the only
+// non-terminal states, so a wait loop against these always terminates.
+const HANDOFF_PENDING = new Set(['open', 'pending']);
+
+// Map a terminal handoff state to an exit code. A `question` answered with ANY
+// value is a success (0) — a negative human decision ('hold'/'deny') is NOT an
+// infra failure. `acked` is likewise 0. `expired` is a distinct 3 so CI can
+// branch; `cancelled` shares 4 with recipient_not_ready.
+function exitForHandoffState(state) {
+  switch (state) {
+    case 'acked': return EXIT.OK;
+    case 'answered': return EXIT.OK;
+    case 'expired': return EXIT.EXPIRED;
+    case 'cancelled': return EXIT.CANCELLED;
+    default: return EXIT.ERROR;
+  }
+}
+
+// Print a machine-readable summary of a handoff: id, state, delivery-state, and
+// the answer value / acked-by when present, one `key=value` per line to stdout.
+function printHandoff(h) {
+  const lines = [`id=${h.id ?? ''}`, `state=${h.state ?? ''}`];
+  if (h.delivery_state != null) lines.push(`delivery-state=${h.delivery_state}`);
+  if (h.correlation_id) lines.push(`correlation-id=${h.correlation_id}`);
+  if (h.state === 'answered') {
+    const value = h.answer && (h.answer.value ?? h.answer.text) || '';
+    lines.push(`answer=${value}`);
+  }
+  if (h.state === 'acked') {
+    // The Handoff API returns a privacy-aware actor object. Only expose its id
+    // in the machine-readable CLI/GitHub Action output; a redacted actor yields
+    // an empty value instead of the unhelpful "[object Object]" string.
+    const ackerId = h.acked_by && typeof h.acked_by === 'object'
+      ? h.acked_by.id
+      : h.acked_by;
+    lines.push(`acked-by=${ackerId ?? ''}`);
+    if (h.acked_at) lines.push(`acked-at=${h.acked_at}`);
+  }
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+/**
+ * Append the composite Action's declared outputs without interpreting stdout.
+ * Values use GitHub's multiline protocol with a fresh random delimiter. Output
+ * names are a fixed allowlist; untrusted answer text can never create a key.
+ */
+function writeGitHubHandoffOutputs(path, h) {
+  if (typeof path !== 'string' || path.length === 0) {
+    fail('--github-output must be a non-empty path', EXIT.USAGE);
+  }
+
+  const ackerId = h.acked_by && typeof h.acked_by === 'object'
+    ? h.acked_by.id
+    : h.acked_by;
+  const fields = [
+    ['handoff-id', h.id ?? ''],
+    ['state', h.state ?? ''],
+  ];
+  if (h.delivery_state != null) fields.push(['delivery-state', h.delivery_state]);
+  if (h.state === 'answered') {
+    fields.push(['answer', h.answer && (h.answer.value ?? h.answer.text) || '']);
+  }
+  if (h.state === 'acked') fields.push(['acknowledged-by', ackerId ?? '']);
+
+  const blocks = fields.map(([name, rawValue]) => {
+    const value = String(rawValue ?? '');
+    let delimiter;
+    do {
+      delimiter = `pingroom_${randomBytes(24).toString('hex')}`;
+    } while (value.includes(delimiter));
+    // Keep the collision check next to serialization: a delimiter must never
+    // occur in an untrusted value, even though a 192-bit collision is remote.
+    if (value.includes(delimiter)) {
+      fail('could not create a safe GitHub output delimiter');
+    }
+    return `${name}<<${delimiter}\n${value}\n${delimiter}\n`;
+  });
+
+  try {
+    appendFileSync(path, blocks.join(''), { encoding: 'utf8' });
+  } catch {
+    fail('could not write GitHub outputs');
+  }
+}
+
+// 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);
+
+  for (;;) {
+    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}`;
+      fail(`wait failed: ${detail}`);
+    }
+    if (json && json.state && !HANDOFF_PENDING.has(json.state)) {
+      // Read/wait responses intentionally carry delivery_state=null. Preserve
+      // the create response's durable delivery result so --wait callers and
+      // the GitHub Action do not lose it at the terminal read boundary.
+      const resolved = json.delivery_state == null && initialDeliveryState != null
+        ? { ...json, delivery_state: initialDeliveryState }
+        : json;
+      if (args.github_output !== undefined) writeGitHubHandoffOutputs(args.github_output, resolved);
+      if (args.json) process.stdout.write(`${text}\n`);
+      else printHandoff(resolved);
+      return exitForHandoffState(resolved.state);
+    }
+    // Still open/pending at the hold timeout — poll again.
+  }
+}
+
+async function handoff(args) {
+  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+
+  const message = args.message;
+  if (!message) fail('a --message is required', EXIT.USAGE);
+
+  const { token, apiBase } = agentContext(args);
+
+  const options = buildOptions(args.option);
+  // Any --option (or an explicit --question) makes this a question handoff.
+  const isQuestion = Boolean(args.question) || Boolean(options);
+  if (isQuestion && (!options || options.length < 2)) {
+    fail('a question handoff needs at least 2 --option values', EXIT.USAGE);
+  }
+  if (isQuestion && options && options.length > 4) {
+    fail('a question handoff accepts at most 4 --option values', EXIT.USAGE);
+  }
+  if (!isQuestion && options) {
+    fail('--option requires --question', EXIT.USAGE);
+  }
+
+  const body = { kind: isQuestion ? 'question' : 'ack', prompt: message };
+
+  const target = args.target || 'me';
+  body.audience = { type: 'direct', user_id: target };
+
+  if (options) body.options = options;
+
+  if (args.expires_in !== undefined) {
+    if (!/^\d+$/.test(String(args.expires_in))) fail('--expires-in must be an integer number of seconds', EXIT.USAGE);
+    const secs = Number(args.expires_in);
+    if (secs < 120 || secs > 86_400) fail('--expires-in must be between 120 and 86400 seconds', EXIT.USAGE);
+    body.expires_in = secs;
+  }
+  if (args.urgency !== undefined) {
+    if (args.urgency !== 'active' && args.urgency !== 'passive') fail("--urgency must be 'active' or 'passive'", EXIT.USAGE);
+    body.urgency = args.urgency;
+  }
+  if (args.correlation_id !== undefined) body.correlation_id = args.correlation_id;
+  if (args.reply_to !== undefined) body.reply_to = args.reply_to;
+  if (args.data !== undefined) body.data = parseDataObject(args.data);
+
+  const headers = { Authorization: `Bearer ${token}` };
+  // A stable Idempotency-Key lets network retries collapse to one resource; the
+  // server returns the same handoff for a matching key+hash (409 on conflict).
+  if (args.idempotency_key !== undefined) {
+    if (!args.idempotency_key) fail('--idempotency-key must be non-empty', EXIT.USAGE);
+    headers['Idempotency-Key'] = args.idempotency_key;
+  }
+
+  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}`;
+    // 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') {
+      if (args.json) process.stdout.write(`${text}\n`);
+      else process.stderr.write(`pingroom: recipient not ready\n`);
+      return EXIT.CANCELLED;
+    }
+    fail(`handoff failed: ${detail}`);
+  }
+
+  if (!args.wait) {
+    if (args.github_output !== undefined) writeGitHubHandoffOutputs(args.github_output, json);
+    if (args.json) process.stdout.write(`${text}\n`);
+    else printHandoff(json);
+    return EXIT.OK;
+  }
+
+  return waitForHandoff(json.id, args, { token, apiBase }, json.delivery_state);
+}
+
+// --- hook (Claude Code integration) ----------------------------------------
+//
+// A single command wired into several Claude Code hook events. It reads the
+// hook's JSON payload on stdin and switches on `hook_event_name`:
+//   Stop / SubagentStop / SessionEnd  -> ping the room ("Claude finished")
+//   Notification                      -> ping the room (idle / needs-input)
+//   PreToolUse                        -> ask a PingRoom question and gate the
+//                                        tool call on the phone's Approve/Deny.
+//
+// Safety: the hook FAILS OPEN. It never blocks the agent and never
+// auto-approves. Any missing config / network error / non-answer defers to the
+// 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 = {
+    '--room': 'room',
+    '--ttl': 'ttl',
+    '--quiet': 'quiet',
+    '--print-config': 'print_config',
+    '--token': 'token',
+    '--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;
+}
+
+// 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.
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) { resolve(''); return; }
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', () => resolve(data));
+  });
+}
+
+function truncate(value, max) {
+  const str = String(value ?? '');
+  return str.length <= max ? str : `${str.slice(0, max - 1)}…`;
+}
+
+// A minimal HTTP helper for the hook path that THROWS instead of calling fail(),
+// so every failure funnels into a fail-open decision. Mirrors httpJson's header
+// handling but leaves control flow to the caller.
+async function hookFetch(method, url, { body, token } = {}) {
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Accept: 'application/json',
+      ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  const text = await res.text();
+  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}`);
+  }
+  return json;
+}
+
+// Pull the readable text out of a Claude transcript message's content, which is
+// either a plain string or an array of typed blocks.
+function extractAssistantText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+      .map((b) => b.text)
+      .join(' ');
+  }
+  return '';
+}
+
+// Tail a Claude Code transcript (JSONL) and return the last assistant message as
+// a single truncated line. Best-effort: any read/parse failure yields ''.
+function summarizeTranscript(path) {
+  if (!path || typeof path !== 'string') return '';
+  let content;
+  try { content = readFileSync(path, 'utf8'); } catch { return ''; }
+  const lines = content.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    const msg = entry && entry.message;
+    if (!msg || msg.role !== 'assistant') continue;
+    const text = extractAssistantText(msg.content).replace(/\s+/g, ' ').trim();
+    if (text) return truncate(text, 500);
+  }
+  return '';
+}
+
+// A short, single-line description of the tool call for the question prompt.
+// Never emits more than a truncated line, and strips whitespace/newlines so an
+// untrusted command can't reshape the message.
+function summarizeToolInput(input) {
+  if (!input || typeof input !== 'object') return '';
+  let raw = '';
+  if (typeof input.command === 'string') raw = input.command;          // Bash
+  else if (typeof input.file_path === 'string') raw = input.file_path; // Read/Write/Edit
+  else if (typeof input.path === 'string') raw = input.path;
+  else if (typeof input.url === 'string') raw = input.url;             // WebFetch
+  else if (typeof input.pattern === 'string') raw = input.pattern;     // Grep/Glob
+  else { try { raw = JSON.stringify(input); } catch { raw = ''; } }
+  return truncate(String(raw).replace(/\s+/g, ' ').trim(), 160);
+}
+
+function emitPreToolUseDecision(decision, reason) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: decision,
+      permissionDecisionReason: reason,
+    },
+  })}\n`);
+}
+
+// Long-poll the wait endpoint until the question leaves `pending`. The server
+// expires it at its ttl, so this always terminates; a mid-poll throw propagates
+// to the caller's fail-open handler.
+async function hookWaitForAnswer(id, { token, apiBase }) {
+  for (;;) {
+    const url = `${apiBase}/api/agent/questions/${encodeURIComponent(id)}/wait?timeout=25`;
+    const json = await hookFetch('GET', url, { token });
+    if (json && json.state && json.state !== 'pending') return json;
+  }
+}
+
+async function hookPreToolUse(event, { token, room, apiBase, args }) {
+  if (!token || !room) {
+    emitPreToolUseDecision('ask', 'PingRoom not configured (set PINGROOM_TOKEN and PINGROOM_ROOM)');
+    return EXIT.OK;
+  }
+
+  const toolName = event.tool_name || 'a tool';
+  const summary = summarizeToolInput(event.tool_input);
+  const prompt = truncate(`Run ${toolName}${summary ? `: ${summary}` : ''}?`, 500);
+
+  let ttl = 900;
+  if (args.ttl !== undefined && /^\d+$/.test(String(args.ttl))) ttl = Number(args.ttl);
+
+  let questionId;
+  let cancelled = false;
+  const cancelQuestion = async () => {
+    if (!questionId || cancelled) return;
+    cancelled = true;
+    try {
+      await hookFetch('POST', `${apiBase}/api/agent/questions/${encodeURIComponent(questionId)}/cancel`, { body: {}, token });
+    } catch { /* best-effort — a leftover question expires on its own ttl */ }
+  };
+  // If the agent aborts the tool call, withdraw the question so it doesn't linger
+  // on the phone. Exit 0 so the abort itself isn't reported as a hook failure.
+  const onSignal = () => { cancelQuestion().finally(() => process.exit(EXIT.OK)); };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+
+  try {
+    const data = { tool_name: String(toolName) };
+    if (event.cwd) data.cwd = String(event.cwd);
+    const created = await hookFetch('POST', `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/questions`, {
+      token,
+      body: {
+        prompt,
+        context: 'Claude Code',
+        options: [
+          { value: 'allow', label: 'Approve', style: 'primary' },
+          { value: 'deny', label: 'Deny', style: 'danger' },
+        ],
+        ttl,
+        data,
+        ...(event.session_id ? { correlation_id: String(event.session_id) } : {}),
+      },
+    });
+    questionId = created && created.id;
+    if (!questionId) {
+      emitPreToolUseDecision('ask', 'PingRoom did not return a question — deferring to local prompt');
+      return EXIT.OK;
+    }
+
+    const resolved = await hookWaitForAnswer(questionId, { token, apiBase });
+    if (resolved.state === 'answered') {
+      const value = resolved.answer && (resolved.answer.value || resolved.answer.text);
+      if (value === 'allow') { emitPreToolUseDecision('allow', 'Approved via PingRoom'); return EXIT.OK; }
+      if (value === 'deny') { emitPreToolUseDecision('deny', 'Denied via PingRoom'); return EXIT.OK; }
+      emitPreToolUseDecision('ask', `PingRoom answer "${value}" — deferring to local prompt`);
+      return EXIT.OK;
+    }
+    emitPreToolUseDecision('ask', `PingRoom question ${resolved.state} — deferring to local prompt`);
+    return EXIT.OK;
+  } catch (err) {
+    emitPreToolUseDecision('ask', `PingRoom unavailable (${err.message}) — deferring to local prompt`);
+    return EXIT.OK;
+  } finally {
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  }
+}
+
+async function hookNotify(event, name, { token, room, apiBase, args }) {
+  if (!token || !room) {
+    if (!args.quiet) process.stderr.write('pingroom: hook skipped (set PINGROOM_TOKEN and PINGROOM_ROOM)\n');
+    return EXIT.OK;
+  }
+
+  let title;
+  let message;
+  if (name === 'Stop' || name === 'SubagentStop') {
+    title = 'Claude finished';
+    message = summarizeTranscript(event.transcript_path) || 'Session finished — waiting for you.';
+  } else if (name === 'Notification') {
+    message = truncate(event.message || 'Claude is waiting for your input.', 500);
+    // A PreToolUse hook already turns permission prompts into a question; skip
+    // the duplicate "needs your permission" Notification so you aren't paged twice.
+    if (/permission/i.test(message)) return EXIT.OK;
+    title = 'Claude needs you';
+  } else if (name === 'SessionEnd') {
+    if (event.reason === 'clear') return EXIT.OK; // /clear isn't worth a ping
+    title = 'Session ended';
+    message = `Claude Code session ended (${event.reason || 'unknown'}).`;
+  } else {
+    return EXIT.OK; // unknown event — stay silent rather than send noise
+  }
+
+  const data = { event: name };
+  if (event.session_id) data.session_id = String(event.session_id);
+  if (event.cwd) data.cwd = String(event.cwd);
+
+  try {
+    await hookFetch('POST', `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/notifications`, {
+      token,
+      body: {
+        message,
+        title,
+        data,
+        ...(event.session_id ? { correlation_id: String(event.session_id) } : {}),
+      },
+    });
+    if (!args.quiet) process.stderr.write('pingroom: pinged ✅\n');
+  } catch (err) {
+    // A broken ping must never break the agent — report to stderr and exit 0.
+    if (!args.quiet) process.stderr.write(`pingroom: hook ping failed (${err.message})\n`);
+  }
+  return EXIT.OK;
+}
+
+function printHookConfig() {
+  const command = `npx --yes @pingroom/cli@${VERSION} hook`;
+  const config = {
+    hooks: {
+      Stop: [{ hooks: [{ type: 'command', command }] }],
+      Notification: [{ hooks: [{ type: 'command', command }] }],
+      PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command, timeout: 960 }] }],
+    },
+  };
+  process.stdout.write(
+`# PingRoom × Claude Code — merge this into ~/.claude/settings.json
+#
+# 1. Set your credentials in the environment (e.g. in your shell profile):
+#      export PINGROOM_TOKEN="<your agent token>"
+#      export PINGROOM_ROOM="<room invite code>"
+#
+# 2. Merge the "hooks" block below into ~/.claude/settings.json.
+#      Stop / Notification  -> ping your phone.
+#      PreToolUse (Bash)     -> ask a question you Approve/Deny from the lock
+#                               screen before the command runs. Add or change the
+#                               matcher to gate other tools.
+#
+# If PingRoom is unreachable the hook defers to the normal local prompt — it
+# never auto-approves and never blocks the agent.
+
+${JSON.stringify(config, null, 2)}
+`);
+}
+
+async function hook(args) {
+  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+  if (args.print_config) { printHookConfig(); return EXIT.OK; }
+
+  let event = {};
+  const raw = await readStdin();
+  if (raw) { try { event = JSON.parse(raw); } catch { event = {}; } }
+  const name = event.hook_event_name || '';
+
+  // The hook fails open, so it reads the same layered config as everything else
+  // but never complains about a missing piece — it just defers.
+  const token = resolveToken(args);
+  const room = resolveRoom(args);
+  const apiBase = resolveApiBase(args);
+
+  if (name === 'PreToolUse') {
+    return hookPreToolUse(event, { token, room, apiBase, args });
+  }
+  return hookNotify(event, name, { token, room, apiBase, args });
+}
+
+// --- connecting (pairing + email fallback) ---------------------------------
+//
+// Wire contract: AGENT_PAIRING_SPEC.md. The shape is deliberately one gesture —
+// scanning the QR is where the human picks BOTH the account and the delivery
+// room, so an agent can never end up connected with nobody's say-so about where
+// it pings. There is no `login` subcommand: `pingroom` resolves the state.
+
+// The scopes this CLI can actually use, one per command surface. Requested at
+// registration so the approval screen shows exactly what it is granting; the
+// server intersects, so asking for less is always safe and asking for more than
+// the human approves is impossible.
+const CLI_SCOPES = [
+  'pingroom:rooms:read',        // resolve/display the connected room
+  'pingroom:broadcast:send',    // ping
+  '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';
+
+// Widest QR we render (compact half-block form of a ~110-char pair URL is 39
+// columns). Anything narrower would wrap and become unscannable, so we print
+// the URL alone instead of a broken QR.
+const QR_MIN_COLUMNS = 41;
+
+/**
+ * Draw the pair URL as a scannable QR. Returns false when it could not — a too
+ * narrow terminal, or the optional dependency being absent (someone vendored
+ * just bin/) — and the caller falls back to the printed URL, which always works.
+ */
+async function renderQr(url) {
+  // A real terminal reports its width on the stream; COLUMNS covers the rest.
+  // Unknown width is treated as wide enough — the URL is printed either way.
+  const columns = Number(process.stdout.columns || process.env.COLUMNS || 0);
+  if (columns > 0 && columns < QR_MIN_COLUMNS) return false;
+
+  let qr;
+  try {
+    const mod = await import('qrcode-terminal');
+    qr = mod.default || mod;
+  } catch { return false; }
+  if (!qr || typeof qr.generate !== 'function') return false;
+
+  try {
+    let art = '';
+    // Call it as a method: qrcode-terminal reads its error-correction level off
+    // `this`, so a detached `generate` reference silently builds a version-1
+    // code and throws on anything longer than a few characters.
+    // `small` is the half-block form: two module rows per text row, so the code
+    // stays square-ish and fits an 80-column terminal.
+    qr.generate(url, { small: true }, (rendered) => { art = rendered; });
+    if (!art) return false;
+    process.stdout.write(`\n${art}\n`);
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * A line-at-a-time reader over stdin.
+ *
+ * Deliberately not node:readline: its Interface keeps consuming while we are
+ * awaiting an HTTP round trip between two questions and drops the lines nobody
+ * is listening for, which silently loses piped answers. This queues every line
+ * instead, so the answers can arrive in one blob or one keystroke at a time.
+ *
+ * ask() resolves `null` — never a string — once the input is closed, so it can
+ * never be confused with a real empty line. That distinction is load-bearing:
+ * callers treat an empty line as "take the default", and a caller that reads EOF
+ * as an empty line will take that default again on the next question, and the
+ * next, forever, because nothing will ever arrive to change its mind. Callers
+ * that genuinely want the empty-line behaviour opt in with `?? ''`.
+ */
+function createPrompter() {
+  const queued = [];
+  const waiting = [];
+  let buffer = '';
+  let closed = false;
+
+  const deliver = (line) => {
+    const waiter = waiting.shift();
+    if (waiter) waiter(line);
+    else queued.push(line);
+  };
+  const onData = (chunk) => {
+    buffer += chunk;
+    let idx;
+    while ((idx = buffer.indexOf('\n')) !== -1) {
+      deliver(buffer.slice(0, idx).replace(/\r$/, ''));
+      buffer = buffer.slice(idx + 1);
+    }
+  };
+  const onEnd = () => {
+    if (closed) return;
+    closed = true;
+    if (buffer) { deliver(buffer); buffer = ''; }
+    while (waiting.length) waiting.shift()(null);
+  };
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', onData);
+  process.stdin.once('end', onEnd);
+  process.stdin.resume();
+
+  return {
+    ask(question) {
+      process.stdout.write(question);
+      if (queued.length > 0) return Promise.resolve(queued.shift());
+      if (closed) return Promise.resolve(null);
+      return new Promise((resolve) => { waiting.push(resolve); });
+    },
+    close() {
+      process.stdin.off('data', onData);
+      process.stdin.off('end', onEnd);
+      process.stdin.pause();
+    },
+  };
+}
+
+/** POST /api/agent/auth — anonymous registration, yields the pre-claim credential. */
+async function registerAnonymous(apiBase) {
+  const { res, json } = await httpJson('POST', `${apiBase}/api/agent/auth`, {
+    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}`;
+    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 }) {
+  writeJsonFile(credentialsPath(), {
+    version: 1,
+    token,
+    handle: handle || null,
+    room: room || null,
+    account: account || null,
+    scopes: scopes || [],
+    api_url: apiBase,
+    created_at: new Date().toISOString(),
+  });
+}
+
+/** "✓ Connected as @agt_ab12 → #Project X" — the room half is omitted if unknown. */
+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}` : ''}`;
+}
+
+/**
+ * The QR path. Mints a pre-claim credential, asks the server for a pairing
+ * token, renders it, then polls until the human approves. Returns a credential
+ * object, or null when the pairing lapsed and the user declined a fresh one.
+ */
+async function connectByPairing(apiBase, ask) {
+  for (;;) {
+    const preClaim = await registerAnonymous(apiBase);
+    const headers = { Authorization: `Bearer ${preClaim}` };
+
+    const start = await httpJson('POST', `${apiBase}/api/agent/auth/pair/start`, {
+      body: { scopes: CLI_SCOPES },
+      headers,
+    });
+    if (!start.res.ok || !start.json || typeof start.json.pair_url !== 'string') {
+      const detail = (start.json && (start.json.message || start.json.error || start.json.code))
+        || `HTTP ${start.res.status}`;
+      fail(`could not start pairing: ${detail}`);
+    }
+
+    // The URL is server-controlled and goes straight to the terminal, so strip
+    // C0/C1 controls: an --api / config api_url pointing at a hostile host could
+    // otherwise emit ANSI escapes that repaint or hide the line the user is
+    // about to trust with their account.
+    const pairUrl = stripControlChars(start.json.pair_url);
+    // 900s is the server's pre-claim lifetime; never poll past it, and clamp the
+    // server's suggested interval so a bad value can't busy-loop or stall.
+    // The 1000ms floor is not cosmetic: AGENT_PAIRING_SPEC.md throttles
+    // pair/status at `60,1`, so a faster floor spends the pairing window
+    // collecting 429s instead of the approval.
+    const lifetimeMs = Math.max(1, Number(start.json.expires_in) || 900) * 1000;
+    const intervalMs = Math.min(Math.max(Number(start.json.poll_interval_ms) || 1500, 1000), 10_000);
+    const deadline = Date.now() + lifetimeMs;
+
+    const drew = await renderQr(pairUrl);
+    process.stdout.write(`${drew ? '  Or open' : '  Open'}: ${pairUrl}\n`);
+    process.stdout.write('  Waiting for approval… ');
+
+    // A transient failure must not end a wait the human is mid-way through.
+    // Network errors, 5xx and 429 are the load balancer / rate limiter talking,
+    // not the pairing being over; hard-failing on the first one throws away the
+    // whole 15 minutes over a single blip. 401/403/404 still exit immediately —
+    // those say the pre-claim is gone, and retrying can only spin.
+    // The `Date.now() < deadline` bound is what keeps a *persistent* outage from
+    // retrying forever: it ends at the same moment a clean poll would have.
+    let transientRun = 0;
+    let lastTransient = null;
+    let warnedTransient = false;
+
+    while (Date.now() < deadline) {
+      const { res, json, error } = await httpJson(
+        'GET', `${apiBase}/api/agent/auth/pair/status`, { headers, soft: true },
+      );
+
+      if (error || res.status >= 500 || res.status === 429) {
+        transientRun += 1;
+        lastTransient = error
+          ? error.message
+          : `HTTP ${res.status}`;
+        // Say something rather than sitting mute: a user watching a QR with no
+        // output cannot tell a slow approval from a broken endpoint.
+        if (transientRun === 3 && !warnedTransient) {
+          warnedTransient = true;
+          process.stdout.write(`\n  (still trying — ${lastTransient}) `);
+        }
+        // Ride out a short blip at the normal cadence, then back off
+        // geometrically so a real outage is not also a thundering herd. Never
+        // sleep past the deadline this loop is bounded by.
+        const backoff = Math.min(intervalMs * 2 ** Math.max(0, transientRun - 3), 30_000);
+        await sleep(Math.max(0, Math.min(backoff, deadline - Date.now())));
+        continue;
+      }
+
+      transientRun = 0;
+
+      if (!res.ok) {
+        process.stdout.write('\n');
+        const detail = (json && (json.message || json.error || json.code)) || `HTTP ${res.status}`;
+        fail(`pairing failed: ${detail}`);
+      }
+      const status = json && json.status;
+      if (status === 'active') {
+        // A server that says "active" with no credential has not paired us.
+        // Without this, `token: undefined` is written to credentials.json and
+        // every later command reads a credential file that exists but cannot
+        // authenticate — a far more confusing failure than stopping here.
+        if (typeof json.credential !== 'string' || json.credential === '') {
+          process.stdout.write('\n');
+          fail('pairing succeeded but the server returned no credential');
+        }
+        const cred = {
+          token: json.credential,
+          handle: json.handle,
+          room: json.room,
+          account: json.account,
+          scopes: json.scopes,
+          apiBase,
+        };
+        saveCredential(cred);
+        process.stdout.write(`${connectedLine(cred)}\n`);
+        return cred;
+      }
+      if (status === 'expired') break;
+      // `pending` (or anything unrecognized) — keep waiting.
+      await sleep(intervalMs);
+    }
+
+    if (transientRun > 0) {
+      process.stdout.write(`\n  Gave up waiting — the server kept failing (last: ${lastTransient}).\n`);
+    } else {
+      process.stdout.write(`\n  That code expired.\n`);
+    }
+
+    // `null` means the input is closed, and that is the whole point of this
+    // guard. Reading EOF as "" would fall through the y/yes test below (empty
+    // means "take the default: yes"), restart the for(;;), mint another
+    // anonymous registration, and do it again — a Ctrl-D or a piped stdin turns
+    // a single pairing attempt into thousands of registrations against the API.
+    const again = await ask('  Show a fresh QR code? [Y/n]: ');
+    if (again === null) { process.stdout.write('\n'); return null; }
+    const answer = again.trim().toLowerCase();
+    if (answer && answer !== 'y' && answer !== 'yes') return null;
+  }
+}
+
+/**
+ * The email fallback, over the unchanged claim/* endpoints: the server mails a
+ * link, the web page shows a 6-digit code, the user reads it back here.
+ */
+async function connectByEmail(apiBase, ask) {
+  const preClaim = await registerAnonymous(apiBase);
+  const headers = { Authorization: `Bearer ${preClaim}` };
+
+  // `?? ''` preserves the old EOF behaviour deliberately: ask() now returns null
+  // at EOF, and without the coalesce this would throw a TypeError on `.trim()`
+  // instead of reaching the "this is required" error the user should see.
+  const email = (await ask('  Your PingRoom email: ') ?? '').trim();
+  if (!email) fail('an email address is required', EXIT.USAGE);
+
+  const start = await httpJson('POST', `${apiBase}/api/agent/auth/claim/start`, {
+    body: { email },
+    headers,
+  });
+  if (!start.res.ok) {
+    const detail = (start.json && (start.json.message || start.json.error || start.json.code))
+      || `HTTP ${start.res.status}`;
+    fail(`could not send the email: ${detail}`);
+  }
+
+  process.stdout.write('  Sent. Open the link in that email — the page shows a 6-digit code.\n');
+
+  // A mistyped code is the common case, so allow a few tries before giving up.
+  // The server locks the registration out after its own attempt cap anyway.
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    // Same reason as the email prompt: EOF stays an empty answer, which the
+    // server rejects, rather than a TypeError on null.
+    const otp = (await ask('  Code: ') ?? '').trim();
+    const done = await httpJson('POST', `${apiBase}/api/agent/auth/claim/complete`, {
+      body: { email, otp },
+      headers,
+    });
+    if (done.res.ok && done.json && typeof done.json.credential === 'string') {
+      const cred = {
+        token: done.json.credential,
+        handle: done.json.handle,
+        // claim/complete carries no room — the email flow does not choose one.
+        room: done.json.room,
+        account: done.json.account,
+        scopes: done.json.scopes,
+        apiBase,
+      };
+      saveCredential(cred);
+      process.stdout.write(`${connectedLine(cred)}\n`);
+      if (!cred.room) {
+        process.stdout.write('  Pick a delivery room with: pingroom config set default_room <invite code>\n');
+      }
+      return cred;
+    }
+    const detail = (done.json && (done.json.message || done.json.error || done.json.code))
+      || `HTTP ${done.res.status}`;
+    if (attempt === 3) fail(`could not connect: ${detail}`);
+    process.stderr.write(`pingroom: ${detail}\n`);
+  }
+  return null;
+}
+
+/**
+ * Resolve the unconnected state interactively. Refuses outright when there is no
+ * TTY — a hung prompt in CI is worse than a clean failure, and the fix there is
+ * PINGROOM_TOKEN, not a QR nobody can scan.
+ */
+async function connect(args) {
+  if (!isInteractive()) {
+    fail(
+      'not connected, and this is not an interactive terminal. Set PINGROOM_TOKEN (CI, pipes), or run "pingroom" from a terminal to pair.',
+      EXIT.USAGE,
+    );
+  }
+
+  const apiBase = resolveApiBase(args);
+  requireSafeUrl('--api', apiBase);
+
+  const prompter = createPrompter();
+  const ask = (question) => prompter.ask(question);
+  try {
+    process.stdout.write('  Not connected. How do you want to connect?\n');
+    process.stdout.write('    1) Scan a QR code with the PingRoom app\n');
+    process.stdout.write('    2) Email me a code\n');
+    // EOF here means "no answer", which is what the default already covers, so
+    // coalesce rather than crash on null — the pairing branch below is the one
+    // that must distinguish EOF, and it does.
+    const choice = (await ask('  Choose [1]: ') ?? '').trim();
+    if (choice && choice !== '1' && choice !== '2') {
+      process.stderr.write('pingroom: choose 1 or 2\n');
+      return EXIT.USAGE;
+    }
+
+    const cred = choice === '2'
+      ? await connectByEmail(apiBase, ask)
+      : await connectByPairing(apiBase, ask);
+
+    return cred ? EXIT.OK : EXIT.EXPIRED;
+  } finally {
+    prompter.close();
+  }
+}
+
+// --- status / bare invocation ----------------------------------------------
+
+/**
+ * `pingroom` with no arguments. Connected -> one status line then the usual
+ * help. Not connected -> pair (interactive) or, in a pipe/CI, say so on stderr
+ * and still print the help rather than prompting into the void.
+ */
+async function bare(args) {
+  const envToken = process.env.PINGROOM_TOKEN;
+  const stored = readStoredCredential();
+
+  if (envToken) {
+    process.stdout.write('Using the agent token from PINGROOM_TOKEN.\n');
+    if (stored) process.stdout.write(`(the stored credential in ${credentialsPath()} is ignored while it is set)\n`);
+    const room = resolveRoom(args);
+    if (room) process.stdout.write(`Default room: ${room}\n`);
+    process.stdout.write(`\n${HELP}\n`);
+    return EXIT.OK;
+  }
+
+  if (stored) {
+    process.stdout.write(`${connectedLine(stored)}\n`);
+    const room = resolveRoom(args);
+    if (room) process.stdout.write(`Default room: ${room}\n`);
+    process.stdout.write(`\n${HELP}\n`);
+    return EXIT.OK;
+  }
+
+  if (!isInteractive()) {
+    process.stderr.write('pingroom: not connected. Set PINGROOM_TOKEN, or run "pingroom" from an interactive terminal to pair.\n');
+    process.stdout.write(`${HELP}\n`);
+    return EXIT.OK;
+  }
+
+  return connect(args);
+}
+
+// --- config ----------------------------------------------------------------
+
+// Only these keys are storable. An unknown key is a usage error rather than a
+// silently-ignored setting the user then blames the tool for not honouring.
+const CONFIG_KEYS = {
+  default_room: {
+    describe: 'Room invite code used when --room / PINGROOM_ROOM is absent',
+    validate: (value) => {
+      if (/\s/.test(value) || value.length > 64) return 'default_room must be an invite code (no spaces, <= 64 chars)';
+      return null;
+    },
+  },
+  api_url: {
+    describe: `API base URL (default ${BUILTIN_API})`,
+    validate: (value) => {
+      let u;
+      try { u = new URL(value); } catch { return 'api_url must be a valid URL'; }
+      const loopback = u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '[::1]';
+      if (u.protocol !== 'https:' && !(u.protocol === 'http:' && loopback)) {
+        return 'api_url must use https (refusing to send credentials over cleartext)';
+      }
+      return null;
+    },
+  },
+};
+
+async function config(args) {
+  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+
+  const sub = args._[0];
+  const known = ['list', 'get', 'set'];
+  if (!sub || !known.includes(sub)) {
+    fail(`config needs a subcommand: ${known.join(' | ')}`, EXIT.USAGE);
+  }
+
+  const stored = readConfigFile();
+
+  if (sub === 'list') {
+    if (args.json) { process.stdout.write(`${JSON.stringify(stored)}\n`); return EXIT.OK; }
+    const keys = Object.keys(CONFIG_KEYS).filter((k) => stored[k] !== undefined && stored[k] !== '');
+    if (keys.length === 0) {
+      process.stdout.write(`no settings stored in ${configPath()}\n`);
+      return EXIT.OK;
+    }
+    for (const key of keys) process.stdout.write(`${key}=${stored[key]}\n`);
+    return EXIT.OK;
+  }
+
+  const key = args._[1];
+  if (!key) fail(`config ${sub} needs a key (${Object.keys(CONFIG_KEYS).join(', ')})`, EXIT.USAGE);
+  if (!Object.hasOwn(CONFIG_KEYS, key)) {
+    fail(`unknown config key: ${key} (known keys: ${Object.keys(CONFIG_KEYS).join(', ')})`, EXIT.USAGE);
+  }
+
+  if (sub === 'get') {
+    const value = stored[key];
+    if (value === undefined || value === '') return EXIT.OK; // unset: print nothing, exit 0
+    process.stdout.write(`${value}\n`);
+    return EXIT.OK;
+  }
+
+  // set
+  const raw = args._[2];
+  if (raw === undefined) fail(`config set needs a value (pass "" to clear ${key})`, EXIT.USAGE);
+  const value = String(raw).trim();
+
+  if (value === '') {
+    delete stored[key];
+    writeJsonFile(configPath(), stored);
+    process.stdout.write(`${key} cleared\n`);
+    return EXIT.OK;
+  }
+
+  const problem = CONFIG_KEYS[key].validate(value);
+  if (problem) fail(problem, EXIT.USAGE);
+
+  stored[key] = value;
+  writeJsonFile(configPath(), stored);
+  process.stdout.write(`${key}=${value}\n`);
+  return EXIT.OK;
+}
+
+// --- logout ----------------------------------------------------------------
+
+async function logout(args) {
+  if (args.help) { process.stdout.write(`${HELP}\n`); return EXIT.OK; }
+
+  const path = credentialsPath();
+  const stored = readStoredCredential();
+  try {
+    unlinkSync(path);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      process.stdout.write('not connected — there was no stored credential to clear\n');
+      return EXIT.OK;
+    }
+    fail(`could not clear ${path}: ${err.message}`);
+  }
+
+  const who = stored && stored.handle ? ` (@${stored.handle})` : '';
+  process.stdout.write(`logged out${who} — cleared ${path}\n`);
+  if (process.env.PINGROOM_TOKEN) {
+    process.stdout.write('note: PINGROOM_TOKEN is still set in this environment and will keep being used\n');
+  }
+  return EXIT.OK;
+}
+
+const COMMANDS = {
+  ping: (rest) => ping(parseArgs(rest)),
+  ask: (rest) => ask(parseQArgs(rest)),
+  watch: (rest) => waitFrom(watch, rest),
+  await: (rest) => waitFrom(watch, rest),
+  cancel: (rest) => cancel(parseQArgs(rest)),
+  list: (rest) => list(parseQArgs(rest)),
+  handoff: (rest) => handoff(parseHandoffArgs(rest)),
+  handoffs: (rest) => listHandoffs(parseQArgs(rest)),
+  hook: (rest) => hook(parseHookArgs(rest)),
+  live: (rest) => live(parseLiveArgs(rest)),
+  config: (rest) => config(parseQArgs(rest)),
+  logout: (rest) => logout(parseQArgs(rest)),
+};
+
+function waitFrom(handler, rest) {
+  return handler(parseQArgs(rest));
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+
+  if (command === '-h' || command === '--help' || command === 'help') {
+    process.stdout.write(`${HELP}\n`);
+    process.exit(EXIT.OK);
+  }
+
+  // Bare `pingroom` resolves the auth state instead of only printing help:
+  // connected -> status + help; not connected -> pair (interactive only).
+  // A leading flag with no subcommand (`pingroom --api …`) counts as bare — it
+  // configures the connect attempt rather than naming a command.
+  if (!command || command.startsWith('-')) {
+    process.exit(await bare(parseQArgs(argv)));
   }
 
   const handler = COMMANDS[command];