@pingroom/cli 0.4.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
@@ -13,19 +19,29 @@
 //   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/acked · 1 error · 2 bad usage · 3 expired ·
 // 4 cancelled/recipient-not-ready.
 
 import { randomBytes } from 'node:crypto';
-import { appendFileSync, readFileSync } from 'node:fs';
+import {
+  appendFileSync, chmodSync, closeSync, fchmodSync, mkdirSync, openSync,
+  readFileSync, renameSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 
 // 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.4.0';
+const VERSION = '0.6.0';
 
-const DEFAULT_API = process.env.PINGROOM_API_URL || 'https://api.pingroom.io';
+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
 
@@ -41,14 +57,19 @@ 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
+  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)
@@ -57,15 +78,20 @@ ping options:
 
 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:
@@ -90,22 +116,83 @@ 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)
 
+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
@@ -128,6 +215,16 @@ Examples:
 
   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
 
@@ -150,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) {
@@ -160,6 +400,8 @@ 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',
@@ -172,7 +414,11 @@ function parseArgs(argv) {
 
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i];
-    const key = alias[token];
+    // 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) {
@@ -203,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',
@@ -217,7 +466,8 @@ 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) {
@@ -267,7 +517,8 @@ function parseHandoffArgs(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) {
@@ -318,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, {
@@ -331,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 */ }
 
@@ -367,9 +630,35 @@ async function ping(args) {
     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;
 
@@ -386,12 +675,12 @@ async function ping(args) {
     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);
@@ -400,7 +689,7 @@ async function ping(args) {
     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;
@@ -420,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
@@ -438,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 };
   });
 }
 
@@ -511,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`;
@@ -825,7 +1398,8 @@ function parseHookArgs(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) {
@@ -1105,9 +1679,11 @@ async function hook(args) {
   if (raw) { try { event = JSON.parse(raw); } catch { event = {}; } }
   const name = event.hook_event_name || '';
 
-  const token = args.token || process.env.PINGROOM_TOKEN;
-  const room = args.room || process.env.PINGROOM_ROOM;
-  const apiBase = (args.api || DEFAULT_API).replace(/\/$/, '');
+  // 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 });
@@ -1115,6 +1691,529 @@ async function hook(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)),
@@ -1125,6 +2224,9 @@ const COMMANDS = {
   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) {
@@ -1135,11 +2237,19 @@ async function main() {
   const argv = process.argv.slice(2);
   const command = argv[0];
 
-  if (!command || command === '-h' || command === '--help' || command === 'help') {
+  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];
   if (!handler) {
     fail(`unknown command: ${command}\nRun "pingroom --help".`, EXIT.USAGE);