@pingroom/cli 0.8.0 → 0.8.1

package/README.md

@@ -85,8 +85,9 @@ and is not retried as if history could be rewritten.
 An incomplete run exits `1`; it never deletes or replaces the saved credential.
 The command does not fall back to `PINGROOM_TOKEN`, an email-only credential, or
 a credential without `pingroom:handoffs:create` and a delivery room. A grant of
-all rooms pins no delivery room — pick one under Connected Agents in the app
-first.
+all rooms pins no delivery room up front — pick one under Connected Agents in
+the app, or run `pingroom rooms create`, which adopts the new room as the
+delivery room when the agent was granted every room.
 
 There is deliberately no `login` command: being unconnected is a state the tool
 resolves, not one you have to discover. Once connected, bare `pingroom` prints
@@ -96,18 +97,26 @@ that status line followed by the usual help.
 
 Approving on the phone grants two separate things, and both are enforced:
 
-- **Permissions** — the scopes this CLI asks for: `rooms:read`,
-  `broadcast:send`, `attachments:write`, `notifications:read`, `questions:ask`,
-  `handoffs:create`, `live:write`. Nothing widens them later; a command needing
-  one you did not approve returns `403 insufficient_scope`.
+- **Permissions** — one approval covers every command this CLI ships, so it
+  asks for all 16 scopes its commands can need (`lib/scopes.js` is the list):
+  send pings, upload attachments, read pings, ask questions, request approvals,
+  create handoffs, drive live status; read/create/publish/join rooms and
+  set/trigger quick actions; and read/create/delete incoming webhooks. It does
+  **not** ask for `profile:write` (no command uses it) or the retired
+  `agents:ping`. Nothing widens them later — consent is an intersection, so a
+  scope the pairing did not request can never be granted afterwards; a command
+  needing one you did not approve returns `403 insufficient_scope`.
 - **Rooms** — one room, several, or all of them. A room outside that grant
   returns `403 room_not_granted` on every room-scoped call — writes such as
   pings, questions and live streams, and reads such as listing a room's quick
   actions or webhooks. Widen it under Connected Agents in the app.
 
 Both refusals print the fix, not just the code. A credential paired by an older
-CLI carries the scope set that version asked for — reconnect to re-approve if a
-command starts reporting `insufficient_scope`.
+CLI carries the scope set that version asked for — CLIs before 0.8.1 asked for
+only seven — so run `pingroom reconnect` if a command starts reporting
+`insufficient_scope`. That re-approves with the current set, keeps the existing
+connection working until you approve the new one, and revokes the old one only
+afterwards, so cancelling changes nothing.
 
 The credential lands in `~/.pingroom/credentials.json` (mode `0600`, inside a
 `0700` directory). `PINGROOM_HOME` moves that directory; `pingroom logout`

package/bin/pingroom.js

@@ -43,7 +43,8 @@ import { HELP } from '../lib/help.js';
 import { maybeNotifyUpdate } from '../lib/update-check.js';
 import {
   parseArgs, parseConfigArgs, parseHandoffArgs, parseHandoffsArgs, parseHookArgs,
-  parseLiveArgs, parseLogoutArgs, parseManageArgs, parseQArgs, parseSkillsArgs,
+  parseLiveArgs, parseLogoutArgs, parseManageArgs, parseQArgs, parseReconnectArgs,
+  parseSkillsArgs,
 } from '../lib/parser.js';
 import { actions, approval, attachment, rooms, webhooks } from '../lib/commands/manage.js';
 import { ping } from '../lib/commands/ping.js';
@@ -54,7 +55,7 @@ import { live } from '../lib/commands/live.js';
 import { hook } from '../lib/commands/hook.js';
 import { mcp } from '../lib/commands/mcp.js';
 import { skills } from '../lib/commands/skills.js';
-import { activateStoredInbox, bare } from '../lib/commands/connect.js';
+import { activateStoredInbox, bare, reconnect } from '../lib/commands/connect.js';
 import { config, logout } from '../lib/commands/config.js';
 
 const COMMANDS = {
@@ -78,6 +79,7 @@ const COMMANDS = {
   approval: (rest) => approval(parseManageArgs(rest)),
   attachment: (rest) => attachment(parseManageArgs(rest)),
   config: (rest) => config(parseConfigArgs(rest)),
+  reconnect: (rest) => reconnect(parseReconnectArgs(rest)),
   logout: (rest) => logout(parseLogoutArgs(rest)),
 };
 

package/lib/commands/ask.js

@@ -2,41 +2,14 @@
 // existing one), `cancel`, and `list`.
 
 import { EXIT } from '../constants.js';
-import { fail, parseDataObject, requireMaxLength, resolveWaitHold, sleep } from '../util.js';
+import { applyIdempotencyKey, fail, parseDataObject, requireMaxLength, resolveWaitHold } from '../util.js';
 import { commandHelp } from '../help.js';
 import { apiDetail, httpJson } from '../http.js';
 import { agentContext } from '../config.js';
-import { buildOptions, exitForState, printResolution } from '../render.js';
+import { buildOptions } from '../render.js';
+import { waitForResolution } from '../question-wait.js';
 import { writeGitHubQuestionOutputs } from '../github-output.js';
 
-// Long-poll the wait endpoint until the question leaves `pending`, then print
-// and return the state's exit code. The server expires it at its ttl, so this
-// always terminates.
-async function waitForResolution(id, args, { token, apiBase }) {
-  const hold = resolveWaitHold(args, { def: 25, cap: 30 });
-
-  for (;;) {
-    const started = Date.now();
-    const url = `${apiBase}/api/agent/questions/${encodeURIComponent(id)}/wait?timeout=${hold}`;
-    const { res, text, json } = await httpJson('GET', url, { headers: { Authorization: `Bearer ${token}` } });
-    if (!res.ok) {
-      const detail = apiDetail(res, json);
-      fail(`wait failed: ${detail}`);
-    }
-    if (json && json.state && json.state !== 'pending') {
-      if (args.github_output !== undefined) writeGitHubQuestionOutputs(args.github_output, json);
-      if (args.json) process.stdout.write(`${text}\n`);
-      else printResolution(json);
-      return exitForState(json.state);
-    }
-    // Still pending at the hold timeout — poll again, but never hot-loop: a
-    // misbehaving server that answers `pending` instantly (ignoring the hold)
-    // would otherwise be hammered at full speed.
-    const elapsed = Date.now() - started;
-    if (elapsed < 1000) await sleep(1000 - elapsed);
-  }
-}
-
 export async function ask(args) {
   if (args.help) { process.stdout.write(`${commandHelp('ask')}\n`); return EXIT.OK; }
 
@@ -76,18 +49,7 @@ export async function ask(args) {
   }
   if (args.data !== undefined) body.data = parseDataObject(args.data);
 
-  const headers = { Authorization: `Bearer ${token}` };
-  // Question creation is the durable human gate for workflows. A printable,
-  // bounded key lets a caller safely replay the exact same create request
-  // after an ambiguous transport failure; the server returns 409 if the key is
-  // ever reused for a different payload.
-  if (args.idempotency_key !== undefined) {
-    const key = String(args.idempotency_key);
-    if (!/^[\x21-\x7E]{1,255}$/.test(key)) {
-      fail('--idempotency-key must be 1–255 printable ASCII characters without spaces', EXIT.USAGE);
-    }
-    headers['Idempotency-Key'] = key;
-  }
+  const headers = applyIdempotencyKey(args, { Authorization: `Bearer ${token}` });
 
   // Pre-flight: reject a bad --timeout before the question exists.
   if (args.wait) resolveWaitHold(args, { def: 25, cap: 30 });

package/lib/commands/connect.js

@@ -9,8 +9,10 @@ import {
 import { HELP, commandHelp } from '../help.js';
 import { apiDetail, httpJson, requireSafeUrl, retryAfterMs } from '../http.js';
 import {
-  credentialsPath, readStoredCredential, resolveApiBase, resolveRoom, saveCredential,
+  credentialsPath, readStoredCredential, requireStoredCredentialOrigin, resolveApiBase,
+  resolveRoom, saveCredential,
 } from '../config.js';
+import { CLI_SCOPES } from '../scopes.js';
 
 // --- connecting (pairing + email fallback) ---------------------------------
 //
@@ -19,20 +21,6 @@ import {
 // 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:attachments:write', // ping --attach (the upload leg)
-  'pingroom:notifications:read',// listen
-  'pingroom:questions:ask',     // ask / watch / cancel / list, and the hook
-  'pingroom:handoffs:create',   // handoff / handoffs
-  'pingroom:live:write',        // live start/update/end/get
-];
-
 // What the human reads on the approval screen. A product name, not a package
 // id: the phone shows it verbatim ("PingRoom CLI wants to connect").
 const AGENT_LABEL = 'PingRoom CLI';
@@ -724,3 +712,97 @@ export async function bare(args) {
 
   return connect(args);
 }
+
+// --- reconnect --------------------------------------------------------------
+
+/**
+ * Re-pair an existing connection so it carries the scopes this CLI version
+ * needs. Ordered so that any failure is a no-op:
+ *
+ *   1. the old credential stays in place and keeps working throughout;
+ *   2. the human approves a NEW pairing — a separate registration, since the
+ *      server puts no uniqueness on user_id, so both are live at once;
+ *   3. the new credential is written atomically (temp file + rename);
+ *   4. only THEN is the old one revoked.
+ *
+ * Cancelling, Ctrl-C, or any error before step 3 leaves the machine exactly as
+ * it was. Revocation is last and best-effort on purpose: a crash between the
+ * rename and the revoke leaves a stale-but-harmless registration the human can
+ * remove from Connected Agents, whereas the reverse order would leave a working
+ * credentials file holding a dead token.
+ *
+ * This is NOT `logout && pingroom`. `logout` only unlinks the local file; the
+ * server-side credential stays active forever, so that sequence leaks a live
+ * credential every time.
+ */
+export async function reconnect(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('reconnect')}\n`); return EXIT.OK; }
+
+  // An env token is not ours to replace: it was pasted here from somewhere else
+  // (a CI secret, a password manager), the same registration is probably in use
+  // on other machines, and revoking it would break all of them from a terminal
+  // whose owner may not even know. Refuse rather than guess.
+  if (process.env.PINGROOM_TOKEN) {
+    fail(
+      'PINGROOM_TOKEN is set, and reconnect would revoke whatever credential it names.\n'
+      + '  Unset it and run "pingroom reconnect" against the stored credential, or re-pair\n'
+      + '  from scratch with "pingroom" and update the token where it is configured.',
+      EXIT.USAGE,
+    );
+  }
+
+  const stored = readStoredCredential();
+  if (!stored) {
+    fail(`not connected — there is no credential in ${credentialsPath()} to replace. Run "pingroom" to pair.`, EXIT.USAGE);
+  }
+
+  if (!isInteractive()) {
+    fail('reconnect needs an interactive terminal to show the QR code.', EXIT.USAGE);
+  }
+
+  const apiBase = resolveApiBase(args);
+  requireSafeUrl('--api', apiBase);
+  // The stored credential is about to be sent to `apiBase` in the revoke below,
+  // so it is bound by the same origin rule every other stored-bearer command
+  // obeys. Without this, `--api` (or a stale config.json api_url) redirects a
+  // live production credential to an arbitrary host.
+  requireStoredCredentialOrigin(args, apiBase);
+
+  process.stdout.write('  Reconnecting updates the permissions this CLI holds.\n');
+  process.stdout.write('  Your current connection keeps working until the new one is approved,\n');
+  process.stdout.write('  and is then revoked — any other machine or CI job using that same\n');
+  process.stdout.write('  credential will stop working.\n\n');
+
+  const prompter = createPrompter();
+  const ask = (question) => prompter.ask(question);
+  let cred;
+  try {
+    cred = await connectByPairing(apiBase, ask);
+  } finally {
+    prompter.close();
+  }
+
+  // Declined, expired, or the user closed stdin: nothing was written, so the old
+  // credential is still the one on disk and still valid.
+  if (!cred) {
+    process.stdout.write('  Kept your current connection.\n');
+    return EXIT.EXPIRED;
+  }
+
+  // The new credential is already durable (connectByPairing saved it). From
+  // here on, failing to revoke is untidy, not dangerous.
+  const { res, json, error } = await httpJson('POST', `${apiBase}/api/agent/auth/revoke`, {
+    headers: { Authorization: `Bearer ${stored.token}` },
+    body: {},
+    soft: true,
+  });
+  if (error || !res || !res.ok) {
+    const detail = error ? error.message : apiDetail(res, json);
+    process.stdout.write(`  Note: the previous connection could not be revoked (${detail}).\n`);
+    process.stdout.write('  Remove it from PingRoom → Settings → Connected Agents when convenient.\n');
+    return EXIT.OK;
+  }
+
+  process.stdout.write('  Previous connection revoked.\n');
+  return EXIT.OK;
+}

package/lib/commands/hook.js

@@ -5,6 +5,7 @@ import { truncate } from '../util.js';
 import { commandHelp } from '../help.js';
 import { hookFetch, isSafeUrl } from '../http.js';
 import { resolveApiBase, resolveRoom, resolveToken, storedCredentialOriginError } from '../config.js';
+import { forgetContinuation, recordContinuation } from '../continuations.js';
 import { VERSION } from '../version.js';
 
 // --- hook (Claude Code integration) ----------------------------------------
@@ -139,8 +140,11 @@ async function hookPreToolUse(event, { token, room, apiBase, args }) {
   process.on('SIGTERM', onSignal);
 
   try {
+    // `data` is echoed into every room member's push AND into the room's
+    // outgoing webhook, so it carries only what a recipient should see. The
+    // working directory is a local filesystem path: it goes to
+    // ~/.pingroom/continuations.json below, never on the wire.
     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: {
@@ -161,7 +165,16 @@ async function hookPreToolUse(event, { token, room, apiBase, args }) {
       return EXIT.OK;
     }
 
+    // Where this session would need to resume from, kept locally. Best-effort:
+    // a failure here must not change the tool decision.
+    recordContinuation(questionId, {
+      sessionId: event.session_id,
+      cwd: event.cwd,
+      transcriptPath: event.transcript_path,
+    });
+
     const resolved = await hookWaitForAnswer(questionId, { token, apiBase });
+    forgetContinuation(questionId);
     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; }
@@ -210,9 +223,11 @@ async function hookNotify(event, name, { token, room, apiBase, args }) {
     return EXIT.OK; // unknown event — stay silent rather than send noise
   }
 
+  // Same rule as the question path: nothing here is private to this machine.
+  // `session_id` is already the ping's correlation_id, so it is on the wire by
+  // design; `cwd` is a local path and stays local.
   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`, {

package/lib/commands/manage.js

@@ -4,10 +4,12 @@
 // response; the default prints a compact human line per record).
 
 import { EXIT } from '../constants.js';
-import { fail } from '../util.js';
+import { applyIdempotencyKey, fail, requireMaxLength, resolveWaitHold } from '../util.js';
 import { commandHelp } from '../help.js';
 import { apiDetail, httpJson } from '../http.js';
 import { agentContext } from '../config.js';
+import { APPROVAL_OPTIONS, exitForApproval, printApproval } from '../render.js';
+import { waitForResolution } from '../question-wait.js';
 
 function sub(args, allowed, noun) {
   const name = args._[0];
@@ -182,43 +184,48 @@ export async function actions(args) {
 
 // ------------------------------------------------------------- approval
 
-const APPROVAL_EXIT = { approved: EXIT.OK, denied: EXIT.CANCELLED, expired: EXIT.EXPIRED };
-
+/**
+ * The deploy gate. An approval is the canonical two-option Question, so this
+ * creates one rather than using the older `/approvals` endpoint: only Questions
+ * reach the phone with real Approve/Deny buttons on the lock screen, and only
+ * Questions get idempotency, the expiry sweep and the resolution webhook.
+ */
 export async function approval(args) {
   if (args.help) { process.stdout.write(`${commandHelp('approval')}\n`); return EXIT.OK; }
 
   if (!args.prompt) fail('an approval needs --prompt', EXIT.USAGE);
+  requireMaxLength(args.prompt, 500, '--prompt');
+  requireMaxLength(args.context, 40, '--context');
+
   const { token, apiBase, room } = agentContext(args, { needRoom: true });
 
-  const body = { prompt: args.prompt };
+  const body = { prompt: args.prompt, options: APPROVAL_OPTIONS };
   if (args.context) body.context = args.context;
   if (args.ttl !== undefined) {
     if (!/^\d+$/.test(String(args.ttl))) fail('--ttl must be an integer number of seconds', EXIT.USAGE);
     body.ttl = Number(args.ttl);
   }
 
+  const headers = applyIdempotencyKey(args, auth(token));
+
+  // Pre-flight: reject a bad --timeout before the approval is on someone's phone.
+  if (args.wait) resolveWaitHold(args, { def: 25, cap: 30 });
+
   const { text, json } = await requireOk(
-    httpJson('POST', `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/approvals`, { headers: auth(token), body }),
+    httpJson('POST', `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/questions`, { headers, body }),
     'approval',
   );
 
   if (!args.wait) {
-    process.stdout.write(`${text}\n`);
+    if (args.json) process.stdout.write(`${text}\n`);
+    else process.stdout.write(`${json.id}\n`);
     return EXIT.OK;
   }
 
-  for (;;) {
-    const { res, text: waitText, json: state } = await httpJson(
-      'GET',
-      `${apiBase}/api/agent/approvals/${encodeURIComponent(json.id)}/wait?timeout=25`,
-      { headers: auth(token) },
-    );
-    if (!res.ok) fail(`approval wait failed: ${apiDetail(res, state)}`);
-    if (state && state.state && state.state !== 'pending') {
-      process.stdout.write(`${args.json ? waitText : state.state}\n`);
-      return APPROVAL_EXIT[state.state] ?? EXIT.OK;
-    }
-  }
+  return waitForResolution(json.id, args, { token, apiBase }, {
+    exitFor: exitForApproval,
+    print: printApproval,
+  });
 }
 
 // ----------------------------------------------------------- attachment

package/lib/continuations.js

@@ -0,0 +1,106 @@
+// Where a blocked agent left off, kept on THIS machine only.
+//
+// When a hook turns a tool-permission prompt into a PingRoom question, the
+// thing that will eventually need to resume — the Claude Code session, its
+// working directory, its transcript — is local. The server never needs to know
+// any of it: the question already carries `correlation_id = session_id`, which
+// is enough to match an answer back to a row here.
+//
+// That is deliberate, not incidental. A question's `data` object is echoed into
+// every room member's push payload AND into the room's outgoing webhook, so a
+// `cwd` put there would publish a local filesystem path to everyone in the room
+// and to whatever URL the room forwards to. Keeping the record local leaks
+// nothing and needs no wire contract.
+//
+// Nothing consumes this yet. It exists so that resuming an ended session is a
+// matter of writing the consumer, not of changing the protocol — and until that
+// consumer exists, PingRoom only claims to block an agent that is still running.
+
+import { randomBytes } from 'node:crypto';
+import { chmodSync, closeSync, fchmodSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { pingroomHome, readJsonFile } from './config.js';
+
+/** Enough for any plausible backlog of open questions on one machine. */
+const MAX_ENTRIES = 100;
+/** A question cannot outlive its TTL by this much; anything older is dead. */
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function continuationsPath() { return join(pingroomHome(), 'continuations.json'); }
+
+/**
+ * Atomic write that REPORTS failure instead of exiting.
+ *
+ * config.js's writeJsonFile calls fail() — correct when a human ran `config
+ * set` and needs to know it didn't take, fatal here: this is called from the
+ * hook, which must never break the agent it is advising. A full disk loses a
+ * resume hint; it must not kill the session.
+ */
+function writeQuietly(path, value) {
+  const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  let fd;
+  try {
+    const created = mkdirSync(pingroomHome(), { recursive: true, mode: 0o700 });
+    if (created !== undefined) chmodSync(pingroomHome(), 0o700);
+    fd = openSync(tmp, 'wx', 0o600);
+    fchmodSync(fd, 0o600);
+    writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+    closeSync(fd);
+    fd = undefined;
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    if (fd !== undefined) { try { closeSync(fd); } catch { /* already gone */ } }
+    try { unlinkSync(tmp); } catch { /* never created */ }
+    return false;
+  }
+}
+
+function load() {
+  const stored = readJsonFile(continuationsPath());
+  const entries = stored && typeof stored.entries === 'object' && !Array.isArray(stored.entries)
+    ? stored.entries
+    : {};
+  return entries;
+}
+
+/** Drop expired rows, then the oldest ones, so the file cannot grow forever. */
+function bound(entries, now) {
+  const live = Object.entries(entries).filter(([, e]) => {
+    const at = Date.parse(e && e.recorded_at);
+    return Number.isFinite(at) && now - at < MAX_AGE_MS;
+  });
+  live.sort((a, b) => Date.parse(a[1].recorded_at) - Date.parse(b[1].recorded_at));
+  return Object.fromEntries(live.slice(-MAX_ENTRIES));
+}
+
+/**
+ * Remember where to come back to for one question. Best-effort by design: the
+ * caller is a hook that has already decided the agent proceeds either way.
+ */
+export function recordContinuation(questionId, { sessionId, cwd, transcriptPath } = {}) {
+  if (!questionId || typeof questionId !== 'string') return false;
+  const now = Date.now();
+  const entries = bound(load(), now);
+  entries[questionId] = {
+    recorded_at: new Date(now).toISOString(),
+    ...(sessionId ? { session_id: String(sessionId) } : {}),
+    ...(cwd ? { cwd: String(cwd) } : {}),
+    ...(transcriptPath ? { transcript_path: String(transcriptPath) } : {}),
+  };
+  return writeQuietly(continuationsPath(), { version: 1, entries: bound(entries, now) });
+}
+
+/** The record for one question, or null. */
+export function readContinuation(questionId) {
+  return load()[questionId] ?? null;
+}
+
+/** Forget one question once it has resolved — the hint has done its job. */
+export function forgetContinuation(questionId) {
+  const entries = load();
+  if (!(questionId in entries)) return false;
+  delete entries[questionId];
+  return writeQuietly(continuationsPath(), { version: 1, entries: bound(entries, Date.now()) });
+}

package/lib/help.js

@@ -38,6 +38,7 @@ Commands:
   approval Send an approve/deny request; with --wait, block on the decision
   attachment Download or delete an attachment by id (attachment get|delete)
   config   Read/write local settings (config list | get <key> | set <key> <val>)
+  reconnect Re-approve this CLI so it holds every permission it needs
   logout   Forget the stored credential`;
 
 export const HELP_PING = `ping options:
@@ -332,18 +333,34 @@ export const COMMAND_HELP_SECTIONS = {
   pingroom actions trigger <1-4> --room <code>`,
   approval: `approval (agent token + --room required):
   pingroom approval -p <prompt>     Send an approve/deny request
+                                    Prints the id; --wait prints the decision
       -c, --context <text>   Secondary line (<= 40 chars)
       --ttl <seconds>        Expiry; omit for the server default
-      --wait                 Block until approved/denied/expired
-                             (exit 0 approved · 4 denied · 3 expired)`,
+      --idempotency-key <k>  Safe replay of the create after a network failure
+      --wait                 Block until the human decides
+                             (exit 0 approve · 4 deny/cancelled · 3 expired)
+      --timeout <0-30>       Seconds per long-poll while waiting (default 25)`,
   attachment: `attachment (agent token required):
   pingroom attachment get <id> [--out <path>]
                                     Download; bytes go to --out or stdout
   pingroom attachment delete <id>   Delete an unclaimed upload`,
   config: HELP_CONFIG,
+  reconnect: `reconnect:
+  pingroom reconnect                Re-approve this CLI with the permissions the
+                                    current version needs, then revoke the old
+                                    connection. Your existing connection keeps
+                                    working until you approve the new one, and
+                                    cancelling changes nothing.
+                                    Any other machine or CI job sharing the same
+                                    credential will stop working once it is revoked.
+      --api <url>            API base URL (default https://api.pingroom.io)`,
   logout: `logout:
   pingroom logout                   Forget the stored credential (PINGROOM_TOKEN
-                                    in the environment is unaffected)`,
+                                    in the environment is unaffected).
+                                    This is LOCAL ONLY — the connection stays
+                                    active on the server. To replace it, use
+                                    "pingroom reconnect"; to end it, revoke it in
+                                    PingRoom -> Settings -> Connected Agents.`,
 };
 
 // config and logout are local-only commands that reject --token/--api (and,
@@ -355,6 +372,10 @@ export const COMMAND_HELP_FOOTERS = {
   -h, --help             Show this help`,
   logout: `Shared:
   -h, --help             Show this help`,
+  // reconnect drives the QR pairing flow; a --token would have nothing to do
+  // with the credential it is about to replace.
+  reconnect: `Shared:
+  -h, --help             Show this help`,
   // `skills` reaches GitHub, never the PingRoom API, so the shared credential
   // and --json flags would all be lies here.
   skills: `Shared:

package/lib/http.js

@@ -13,11 +13,16 @@ import { readStrictJsonResponse } from './strict-json.js';
  */
 const API_HINTS = {
   room_not_granted:
-    'That room is outside the grant this agent was given. Add it under Connected Agents in the PingRoom app, or run "pingroom" to reconnect and pick it.',
+    'That room is outside the grant this agent was given. Add it under Connected Agents in the PingRoom app, or run "pingroom reconnect" to re-approve and pick it.',
+  // The remedy has to be `reconnect`, not `pingroom`: on a machine that is
+  // already connected, bare `pingroom` just prints the status line and the help,
+  // so it reads as a fix and does nothing. Consent is an intersection
+  // server-side, so a scope the old pairing never requested can only be gained
+  // by approving a new one.
   insufficient_scope:
-    'This credential was approved before the command needed that permission. Run "pingroom" to reconnect and re-approve.',
+    'This credential was approved before the CLI needed that permission. Run "pingroom reconnect" to re-approve with the current permissions — your existing connection keeps working until you approve the new one.',
   no_room_configured:
-    'This agent has no delivery room. Pick one under Connected Agents in the PingRoom app.',
+    'This agent has no delivery room. Pick one under Connected Agents in the PingRoom app, or — if it was granted every room — let it create one with "pingroom rooms create".',
 };
 
 /**

package/lib/parser.js

@@ -205,6 +205,15 @@ export const parseConfigArgs = makeParser({
   bareDashIsPositional: true,
 });
 
+// reconnect re-runs the pairing flow against the stored credential. It takes no
+// --token deliberately: the credential it replaces is the one on disk, and an
+// env token is refused outright by the command.
+export const parseReconnectArgs = makeParser({
+  aliases: { '--api': 'api', '-h': 'help', '--help': 'help' },
+  booleans: ['help'],
+  bareDashIsPositional: true,
+});
+
 export const parseLogoutArgs = makeParser({
   aliases: { '-h': 'help', '--help': 'help' },
   booleans: ['help'],
@@ -247,6 +256,8 @@ export const parseManageArgs = makeParser({
     '--require-ack': 'require_ack',
     '--out': 'out',
     '--wait': 'wait',
+    '--timeout': 'timeout',
+    '--idempotency-key': 'idempotency_key',
     '--token': 'token',
     '--room': 'room',
     '--expected-room-sha256': 'expected_room_sha256',

package/lib/question-wait.js

@@ -0,0 +1,45 @@
+// The one long-poll loop behind every command that blocks on a human: `ask`,
+// `watch`, and `approval`. It lives here rather than in ask.js so the hot-loop
+// floor and the terminal-state handling cannot drift apart — `approval` shipped
+// its own copy of this loop once, and that copy read a field the server never
+// sends, so it spun forever after the human had already decided.
+
+import { fail, resolveWaitHold, sleep } from './util.js';
+import { apiDetail, httpJson } from './http.js';
+import { exitForState, printResolution } from './render.js';
+import { writeGitHubQuestionOutputs } from './github-output.js';
+
+/**
+ * Long-poll until the question leaves `pending`, then print and return its exit
+ * code. The server expires it at its ttl, so this always terminates.
+ *
+ * `exitFor` and `print` take the whole resolved question, not just its state:
+ * a deploy gate has to read the chosen *value* to tell approve from deny, which
+ * the state alone ("answered") cannot express.
+ */
+export async function waitForResolution(id, args, { token, apiBase }, opts = {}) {
+  const exitFor = opts.exitFor ?? ((q) => exitForState(q.state));
+  const print = opts.print ?? printResolution;
+  const hold = resolveWaitHold(args, { def: 25, cap: 30 });
+
+  for (;;) {
+    const started = Date.now();
+    const url = `${apiBase}/api/agent/questions/${encodeURIComponent(id)}/wait?timeout=${hold}`;
+    const { res, text, json } = await httpJson('GET', url, { headers: { Authorization: `Bearer ${token}` } });
+    if (!res.ok) {
+      const detail = apiDetail(res, json);
+      fail(`wait failed: ${detail}`);
+    }
+    if (json && json.state && json.state !== 'pending') {
+      if (args.github_output !== undefined) writeGitHubQuestionOutputs(args.github_output, json);
+      if (args.json) process.stdout.write(`${text}\n`);
+      else print(json);
+      return exitFor(json);
+    }
+    // Still pending at the hold timeout — poll again, but never hot-loop: a
+    // misbehaving server that answers `pending` instantly (ignoring the hold)
+    // would otherwise be hammered at full speed.
+    const elapsed = Date.now() - started;
+    if (elapsed < 1000) await sleep(1000 - elapsed);
+  }
+}

package/lib/render.js

@@ -116,6 +116,45 @@ export function printResolution(q) {
   }
 }
 
+/**
+ * The two options behind `pingroom approval`. An approval IS a two-option
+ * Question — same wire shape, same lock-screen buttons, same first-answer-wins
+ * — so the command builds one rather than reaching for the older Approvals API,
+ * which delivers no answer actions to the phone at all.
+ */
+export const APPROVAL_OPTIONS = Object.freeze([
+  Object.freeze({ value: 'approve', label: 'Approve', style: 'primary' }),
+  Object.freeze({ value: 'deny', label: 'Deny', style: 'danger' }),
+]);
+
+/**
+ * A deploy gate reads the chosen VALUE, not just the state.
+ *
+ * `exitForState` maps every answer to 0, which is right for `ask` (a human
+ * answering "hold" is not an infra failure) and catastrophic for a gate:
+ * `if pingroom approval --wait; then deploy; fi` must refuse on a denial.
+ * So `approve` is 0 and anything else answered is 4, and only the non-answered
+ * states fall through to the shared mapping.
+ */
+export function exitForApproval(q) {
+  if (q.state === 'answered') {
+    const value = (q.answer && (q.answer.value ?? q.answer.text)) || '';
+    return value === 'approve' ? EXIT.OK : EXIT.CANCELLED;
+  }
+  return exitForState(q.state);
+}
+
+// Same split as printResolution: the decision goes to stdout so `$(...)` can
+// capture it, every other outcome reports to stderr and leaves stdout empty.
+export function printApproval(q) {
+  if (q.state === 'answered') {
+    const value = (q.answer && (q.answer.value ?? q.answer.text)) || '';
+    process.stdout.write(`${value}\n`);
+  } else {
+    process.stderr.write(`pingroom: approval ${q.state}\n`);
+  }
+}
+
 /** One readable line per incoming ping. */
 export function formatIncoming(item) {
   const room = item?.room?.name || item?.room?.code || '?';

package/lib/scopes.js

@@ -0,0 +1,95 @@
+// What the official CLI asks for, and what each command actually needs.
+//
+// One pairing approval enables every command PingRoom ships. That is a
+// deliberate reading of OAuth's minimum-required principle (RFC 9700 §2.3): the
+// unit being authorized here is the complete official CLI, not the server's
+// whole capability surface. Consent is an intersection server-side
+// (AgentAuthController::pairingClaim), so this list is a hard CEILING — a scope
+// missing here can never be granted, and the only remedy is a fresh pairing.
+// That is why the set is not trimmed to "what you happen to run today".
+//
+// Two catalog scopes are deliberately absent:
+//   pingroom:profile:write — no CLI command sets the agent avatar or handle.
+//   pingroom:agents:ping   — retired; the route answers 410.
+//
+// Ordered by the group the consent screen shows, so the approval reads as three
+// coherent sections even on a client that has not shipped the grouping yet.
+export const CLI_SCOPES = [
+  // Communication and human decisions
+  'pingroom:broadcast:send',    // ping
+  'pingroom:attachments:write', // ping --attach (upload), attachment delete
+  'pingroom:notifications:read',// listen, attachment get
+  'pingroom:questions:ask',     // ask / watch / cancel / list, approval, the hook
+  'pingroom:approvals:request', // the legacy approvals surface (SDK/MCP parity)
+  'pingroom:handoffs:create',   // handoff / handoffs / activate
+  'pingroom:live:write',        // live start/update/end/get
+  // Rooms and quick actions
+  'pingroom:rooms:read',        // rooms list/get, actions list, room icons
+  'pingroom:rooms:write',       // rooms create
+  'pingroom:rooms:publish',     // rooms create --public
+  'pingroom:rooms:join',        // rooms join
+  'pingroom:actions:trigger',   // actions trigger
+  'pingroom:actions:write',     // actions set
+  // Webhooks
+  'pingroom:webhooks:read',     // webhooks list
+  'pingroom:webhooks:write',    // webhooks create/update
+  'pingroom:webhooks:delete',   // webhooks delete
+];
+
+/**
+ * Command -> every scope any of its verbs can need, taken from the route
+ * middleware in laravel/routes/api.php.
+ *
+ * This exists to be TESTED, not consulted at runtime for authorization: the
+ * server is the authority. `test/cli.test.mjs` asserts both directions — every
+ * dispatched command appears here, and every scope named here is in
+ * CLI_SCOPES — so a new command whose scope nobody requested cannot ship. That
+ * check is the thing that would have caught `approval` 403ing on a fresh
+ * pairing for as long as it did.
+ *
+ * An empty array means the command touches no agent-authenticated route.
+ */
+export const COMMAND_SCOPES = {
+  ping: ['pingroom:broadcast:send', 'pingroom:attachments:write'],
+  ask: ['pingroom:questions:ask'],
+  watch: ['pingroom:questions:ask'],
+  await: ['pingroom:questions:ask'],
+  cancel: ['pingroom:questions:ask'],
+  list: ['pingroom:questions:ask'],
+  approval: ['pingroom:questions:ask'],
+  handoff: ['pingroom:handoffs:create'],
+  handoffs: ['pingroom:handoffs:create'],
+  activate: ['pingroom:handoffs:create'],
+  listen: ['pingroom:notifications:read'],
+  hook: ['pingroom:questions:ask', 'pingroom:broadcast:send'],
+  live: ['pingroom:live:write'],
+  rooms: [
+    'pingroom:rooms:read', 'pingroom:rooms:write',
+    'pingroom:rooms:publish', 'pingroom:rooms:join',
+  ],
+  actions: ['pingroom:rooms:read', 'pingroom:actions:write', 'pingroom:actions:trigger'],
+  webhooks: ['pingroom:webhooks:read', 'pingroom:webhooks:write', 'pingroom:webhooks:delete'],
+  attachment: ['pingroom:notifications:read', 'pingroom:attachments:write'],
+  // Local-only: no agent-authenticated route, so nothing to request.
+  mcp: [],
+  skills: [],
+  config: [],
+  logout: [],
+  reconnect: [],
+};
+
+/**
+ * Scopes a command needs that this credential was never granted.
+ *
+ * Returns [] whenever the answer is not knowable — no stored scope list at all
+ * (a PINGROOM_TOKEN in CI has none), or an unrecognized command. That is the
+ * whole contract: this is a courtesy that turns a 403 into a sentence naming
+ * the fix, never a gate. Refusing on unknown scopes would break every CI job
+ * holding a perfectly good token.
+ */
+export function missingScopesFor(command, grantedScopes) {
+  if (!Array.isArray(grantedScopes) || grantedScopes.length === 0) return [];
+  const needed = COMMAND_SCOPES[command];
+  if (!needed || needed.length === 0) return [];
+  return needed.filter((scope) => !grantedScopes.includes(scope));
+}

package/lib/util.js

@@ -73,6 +73,24 @@ export function resolveWaitHold(args, { def, cap }) {
   return Math.min(hold, cap);
 }
 
+/**
+ * Validate --idempotency-key and stamp it on the outgoing headers.
+ *
+ * Creating a human gate is the one CLI write a caller genuinely wants to replay
+ * after an ambiguous transport failure, so the key must survive a shell round
+ * trip intact: printable ASCII, no spaces. The server returns 409 if the same
+ * key is ever reused for a different payload.
+ */
+export function applyIdempotencyKey(args, headers) {
+  if (args.idempotency_key === undefined) return headers;
+  const key = String(args.idempotency_key);
+  if (!/^[\x21-\x7E]{1,255}$/.test(key)) {
+    fail('--idempotency-key must be 1–255 printable ASCII characters without spaces', EXIT.USAGE);
+  }
+  headers['Idempotency-Key'] = key;
+  return headers;
+}
+
 export function numberOption(raw, flag, { min, max, integer = false } = {}) {
   if (raw === undefined) return undefined;
   const value = Number(raw);

package/package.json

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