@pingroom/cli 0.7.6 → 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`
@@ -641,6 +650,35 @@ shared by ChatGPT and Codex.
 For a fully typed client, use [`@pingroom/sdk`](https://www.npmjs.com/package/@pingroom/sdk).
 See <https://pingroom.io/connect-mcp.md> for the complete MCP and OAuth guide.
 
+## Agent skills
+
+Two ready-to-install [Claude Code skills](https://github.com/pingroom/skills)
+teach an agent when and how to reach a human — `pingroom-mcp` for conversational
+sessions, `pingroom-cli` for shells, CI, and hooks.
+
+```bash
+pingroom skills           # list them and every install route (prints only)
+pingroom skills install   # copy both into ~/.claude/skills (needs git)
+```
+
+`install` refuses to replace a skill that is already there; pass `--force` to
+replace it, or `--dir <path>` to install somewhere other than
+`~/.claude/skills`. Inside Claude Code you can instead use the plugin system,
+which keeps them updated:
+
+```
+/plugin marketplace add pingroom/skills
+/plugin install pingroom-mcp
+```
+
+## Update notifications
+
+When a newer `@pingroom/cli` is published the CLI prints a one-line notice on
+stderr, at most once every 24 hours. It is deliberately invisible to automation:
+the check is skipped entirely unless both stdout and stderr are a TTY, and
+whenever `CI` or `PINGROOM_NO_UPDATE_CHECK=1` is set. A failed or slow check is
+silent and can never change a command's output or exit code.
+
 ## License
 
 MIT

package/bin/pingroom.js

@@ -23,6 +23,7 @@
 //   live     Drive a live progress card (iOS Live Activity / Android live
 //            update) on the room members' lock screen: start / update / end.
 //   mcp      Print the canonical remote MCP endpoint and client setup snippets.
+//   skills   List the published agent skills, or install them for Claude Code.
 //   activate Send one optional test Question with the saved QR-paired credential.
 //   config   Read/write ~/.pingroom/config.json (default_room, api_url).
 //   logout   Forget the credential in ~/.pingroom/credentials.json.
@@ -39,9 +40,11 @@ import { EXIT } from '../lib/constants.js';
 import { fail, stripControlChars } from '../lib/util.js';
 import { VERSION } from '../lib/version.js';
 import { HELP } from '../lib/help.js';
+import { maybeNotifyUpdate } from '../lib/update-check.js';
 import {
   parseArgs, parseConfigArgs, parseHandoffArgs, parseHandoffsArgs, parseHookArgs,
-  parseLiveArgs, parseLogoutArgs, parseManageArgs, parseQArgs,
+  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';
@@ -51,7 +54,8 @@ import { listen } from '../lib/commands/listen.js';
 import { live } from '../lib/commands/live.js';
 import { hook } from '../lib/commands/hook.js';
 import { mcp } from '../lib/commands/mcp.js';
-import { activateStoredInbox, bare } from '../lib/commands/connect.js';
+import { skills } from '../lib/commands/skills.js';
+import { activateStoredInbox, bare, reconnect } from '../lib/commands/connect.js';
 import { config, logout } from '../lib/commands/config.js';
 
 const COMMANDS = {
@@ -66,6 +70,7 @@ const COMMANDS = {
   listen: (rest) => listen(parseQArgs(rest)),
   hook: (rest) => hook(parseHookArgs(rest)),
   mcp,
+  skills: (rest) => skills(parseSkillsArgs(rest)),
   activate: (rest) => activateStoredInbox(parseQArgs(rest)),
   live: (rest) => live(parseLiveArgs(rest)),
   rooms: (rest) => rooms(parseManageArgs(rest)),
@@ -74,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)),
 };
 
@@ -100,7 +106,9 @@ async function main() {
   // 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 bareCode = await bare(parseQArgs(argv));
+    await maybeNotifyUpdate(VERSION);
+    process.exit(bareCode);
   }
 
   const handler = COMMANDS[command];
@@ -109,6 +117,9 @@ async function main() {
   }
 
   const code = await handler(argv.slice(1));
+  // After the command's own output, never before, and never in place of it:
+  // the notice is advisory and must not lead. It cannot alter `code`.
+  await maybeNotifyUpdate(VERSION);
   process.exit(code);
 }
 

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/commands/skills.js

@@ -0,0 +1,178 @@
+// `skills` — the agent skills published at github.com/pingroom/skills.
+//
+// Bare `skills` prints the catalog and every install route, the same
+// output-only contract `mcp` keeps. `skills install` is the one command in this
+// CLI that writes outside ~/.pingroom, so it is explicit, refuses to clobber,
+// and names every path it touched.
+
+import { spawnSync } from 'node:child_process';
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { EXIT } from '../constants.js';
+import { fail } from '../util.js';
+import { commandHelp } from '../help.js';
+
+export const SKILLS_REPO = 'https://github.com/pingroom/skills';
+const SKILLS_CLONE_URL = `${SKILLS_REPO}.git`;
+
+// Path in the repo -> the skill directory name it installs as.
+//
+// The repo is laid out as two Claude Code plugins (`mcp/`, `cli/`), each with a
+// `skills/<name>/` directory whose name already matches the skill's frontmatter
+// `name` — that agreement is what lets the same tree also be installed with
+// `/plugin marketplace add`. So the source path is deep and the install name is
+// simply its last segment; a copy install and a plugin install land the same
+// directory name either way.
+const SKILLS = [
+  {
+    source: ['mcp', 'skills', 'pingroom-mcp'],
+    install: 'pingroom-mcp',
+    summary: 'conversational agents — the hosted MCP connector',
+  },
+  {
+    source: ['cli', 'skills', 'pingroom-cli'],
+    install: 'pingroom-cli',
+    summary: 'shells, CI, and Claude Code hooks',
+  },
+];
+
+export function claudeSkillsDir() {
+  return process.env.CLAUDE_SKILLS_DIR || join(homedir(), '.claude', 'skills');
+}
+
+function catalogLines() {
+  const width = Math.max(...SKILLS.map((s) => s.install.length));
+  return SKILLS.map((s) => `  ${s.install.padEnd(width)}  ${s.summary}`).join('\n');
+}
+
+function printCatalog() {
+  process.stdout.write(
+`PingRoom agent skills — ${SKILLS_REPO}
+
+${catalogLines()}
+
+Install with this CLI (copies into ${claudeSkillsDir()}):
+  pingroom skills install
+
+Install as a Claude Code plugin (auto-updates, no copy):
+  /plugin marketplace add pingroom/skills
+  /plugin install pingroom-mcp
+  /plugin install pingroom-cli
+
+Or by hand:
+  git clone ${SKILLS_CLONE_URL} /tmp/pingroom-skills
+${SKILLS.map((s) => `  cp -r /tmp/pingroom-skills/${s.source.join('/')} ${claudeSkillsDir()}`).join('\n')}
+
+Only "pingroom skills install" writes anything; this listing does not.
+`);
+  return EXIT.OK;
+}
+
+function directoryExists(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clone the skills repo into a fresh temp directory and return its path.
+ *
+ * `git` rather than a tarball fetch: the repo is public and shallow-clones in
+ * one round trip, Node ships no tar reader, and vendoring one would put an
+ * archive parser in the dependency-free path every ping goes through. When git
+ * is missing the manual recipe above is still exact, so this fails with that
+ * rather than half-installing.
+ */
+function cloneSkills() {
+  const probe = spawnSync('git', ['--version'], { stdio: 'ignore' });
+  if (probe.error || probe.status !== 0) {
+    fail(`git is required for "skills install".\nInstall git, or copy the skills by hand:\n  pingroom skills`, EXIT.ERROR);
+  }
+
+  const workspace = mkdtempSync(join(tmpdir(), 'pingroom-skills-'));
+  const clone = spawnSync(
+    'git',
+    ['clone', '--depth', '1', '--quiet', SKILLS_CLONE_URL, workspace],
+    { stdio: ['ignore', 'ignore', 'pipe'], encoding: 'utf8' },
+  );
+
+  if (clone.error || clone.status !== 0) {
+    rmSync(workspace, { recursive: true, force: true });
+    const detail = (clone.stderr || clone.error?.message || 'git clone failed').trim().split('\n')[0];
+    fail(`could not fetch ${SKILLS_REPO}: ${detail}`, EXIT.ERROR);
+  }
+
+  return workspace;
+}
+
+function install(args) {
+  const target = args.dir ? String(args.dir) : claudeSkillsDir();
+  const force = Boolean(args.force);
+
+  // Resolve collisions BEFORE the network call. Cloning first and refusing
+  // afterwards would spend the round trip to tell the operator something that
+  // was knowable from the filesystem alone.
+  if (!force) {
+    const existing = SKILLS.filter((s) => directoryExists(join(target, s.install)));
+    if (existing.length > 0) {
+      const names = existing.map((s) => join(target, s.install)).join('\n  ');
+      fail(
+        `already installed:\n  ${names}\nRe-run with --force to replace ${existing.length === 1 ? 'it' : 'them'}.`,
+        EXIT.USAGE,
+      );
+    }
+  }
+
+  const workspace = cloneSkills();
+  const installed = [];
+  try {
+    for (const skill of SKILLS) {
+      const from = join(workspace, ...skill.source);
+      if (!directoryExists(from)) {
+        fail(`${SKILLS_REPO} has no "${skill.source.join('/')}" directory — the repo layout changed.`, EXIT.ERROR);
+      }
+      const to = join(target, skill.install);
+      mkdirSync(target, { recursive: true });
+      // Replace rather than merge: a stale SKILL.md left beside a new one is a
+      // skill that half-describes two versions, and Claude Code would load it.
+      rmSync(to, { recursive: true, force: true });
+      cpSync(from, to, { recursive: true });
+      installed.push({ name: skill.install, path: to, files: countFiles(to) });
+    }
+  } finally {
+    rmSync(workspace, { recursive: true, force: true });
+  }
+
+  const lines = installed.map((s) => `  ${s.name} -> ${s.path} (${s.files} file${s.files === 1 ? '' : 's'})`);
+  process.stdout.write(
+`Installed ${installed.length} skill${installed.length === 1 ? '' : 's'}:
+${lines.join('\n')}
+
+Restart Claude Code (or start a new session) to load them.
+Connect the MCP server so the pingroom-mcp skill has tools to call:
+  pingroom mcp
+`);
+  return EXIT.OK;
+}
+
+function countFiles(dir) {
+  let total = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    total += entry.isDirectory() ? countFiles(join(dir, entry.name)) : 1;
+  }
+  return total;
+}
+
+export function skills(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('skills')}\n`); return EXIT.OK; }
+
+  const [sub] = args._;
+  if (sub === undefined || sub === 'list') return printCatalog();
+  if (sub === 'install') return install(args);
+
+  fail('usage: pingroom skills [list|install] [--dir <path>] [--force]', EXIT.USAGE);
+}

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

@@ -30,6 +30,7 @@ Commands:
            permission prompts to a PingRoom question you answer from your phone
   mcp      Print the remote MCP endpoint and setup for Claude Code, Cursor, and
            Claude Desktop
+  skills   List the PingRoom agent skills, or install them for Claude Code
   activate Retry Agent Inbox activation with the saved QR-paired credential
   rooms    List, inspect, create, or join rooms (rooms list|get|create|join)
   webhooks Manage a room's incoming webhooks (webhooks list|create|update|delete)
@@ -37,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:
@@ -156,6 +158,13 @@ export const HELP_MCP = `mcp:
   pingroom mcp add claude-code     Print the Claude Code setup command
                                    (output-only; does not change client config)`;
 
+export const HELP_SKILLS = `skills:
+  pingroom skills                  List the published agent skills and every
+                                   install route (output-only)
+  pingroom skills install          Copy them into ~/.claude/skills (needs git)
+      --dir <path>       Install somewhere other than ~/.claude/skills
+      --force            Replace skills that are already installed`;
+
 export const HELP_ACTIVATE = `activate:
   pingroom activate                Send one test Question to your phone to prove the
                                    saved QR-paired credential works (optional —
@@ -278,7 +287,7 @@ human decision is not an infrastructure failure.`;
 
 export const HELP = [
   HELP_INTRO, HELP_PING, HELP_ASK, HELP_LIST, HELP_HANDOFF, HELP_HANDOFFS,
-  HELP_LISTEN, HELP_LIVE, HELP_HOOK, HELP_MCP, HELP_ACTIVATE, HELP_CONFIG,
+  HELP_LISTEN, HELP_LIVE, HELP_HOOK, HELP_MCP, HELP_SKILLS, HELP_ACTIVATE, HELP_CONFIG,
   HELP_SHARED, HELP_TAIL,
 ].join('\n\n');
 
@@ -299,6 +308,7 @@ export const COMMAND_HELP_SECTIONS = {
   listen: HELP_LISTEN,
   live: HELP_LIVE,
   hook: HELP_HOOK,
+  skills: HELP_SKILLS,
   activate: HELP_ACTIVATE,
   rooms: `rooms (agent token required):
   pingroom rooms list               List the rooms this account belongs to
@@ -323,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,
@@ -346,6 +372,14 @@ 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:
+  -h, --help             Show this help`,
 };
 
 // `<command> --help`: that command's section plus the shared flags, instead of

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'],
@@ -214,6 +223,18 @@ export const parseLogoutArgs = makeParser({
 // Parser for the management nouns (rooms / webhooks / actions / approval /
 // attachment). One shared vocabulary: each sub-command reads the flags it
 // needs and the rest are usage errors at the command layer, same as everywhere.
+// `skills` takes no credential and touches no API: only where to install and
+// whether to replace what is already there. A dedicated vocabulary keeps
+// --force from leaking into the parsers whose commands send real pings.
+export const parseSkillsArgs = makeParser({
+  aliases: {
+    '--dir': 'dir',
+    '--force': 'force',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['force', 'help'],
+});
+
 export const parseManageArgs = makeParser({
   aliases: {
     '-n': 'name', '--name': 'name',
@@ -235,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/update-check.js

@@ -0,0 +1,153 @@
+// "A newer @pingroom/cli is available" — the one piece of output this tool
+// prints that nobody asked for. Everything here exists to make that safe.
+//
+// The hard rule: this must never change what a command does. Not its exit code,
+// not its stdout, not whether it succeeds. A version notice that breaks a
+// deploy pipeline is worse than never shipping the notice at all, so every
+// failure path below is a silent return.
+
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+
+import { pingroomHome, readJsonFile } from './config.js';
+
+const REGISTRY_URL = 'https://registry.npmjs.org/@pingroom/cli/latest';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+// Awaited before exit, so this is a real ceiling on how long a successful
+// command can be delayed by a check nobody asked for. Measured round trips to
+// the registry ran 0.63-1.19s warm, so a tighter budget (1.2s was tried) times
+// out often enough to look like "there is never an update".
+const TIMEOUT_MS = 2500;
+
+export function updateCachePath() { return join(pingroomHome(), 'update-check.json'); }
+
+/**
+ * Write the cache, or give up without a word.
+ *
+ * Deliberately NOT config.js's writeJsonFile: that one calls fail() on an
+ * unwritable path, and fail() calls process.exit() — which no try/catch can
+ * intercept. Borrowing it here would mean a read-only or full ~/.pingroom turns
+ * an advisory version check into the thing that kills the operator's ping. The
+ * write is still atomic (temp file + rename) so a crash mid-write cannot leave
+ * a torn file for the next run to parse.
+ */
+function writeCacheQuietly(path, value) {
+  const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  try {
+    mkdirSync(pingroomHome(), { recursive: true, mode: 0o700 });
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch {
+    try { unlinkSync(tmp); } catch { /* never created */ }
+  }
+}
+
+/**
+ * Why an env var AND a TTY test:
+ *
+ * `CI` covers the graders that set it (GitHub Actions, GitLab, CircleCI). The
+ * TTY test covers everything else — cron, systemd units, Docker builds, a
+ * pipeline that forgot to set CI, and `pingroom ... | jq`. Neither alone is
+ * enough, and the notice is worthless to a machine either way.
+ */
+function suppressed() {
+  if (process.env.PINGROOM_NO_UPDATE_CHECK === '1') return true;
+  if (process.env.CI) return true;
+  if (process.env.NODE_ENV === 'test') return true;
+  return !process.stdout.isTTY || !process.stderr.isTTY;
+}
+
+/**
+ * Compare two dotted release numbers. Returns true when `candidate` is strictly
+ * newer than `current`.
+ *
+ * Anything carrying a prerelease or build suffix (`-beta.1`, `+sha`) is refused
+ * outright rather than guessed at: npm's `latest` tag should never point at one,
+ * and a wrong guess here nags every single run. Only the numeric release line is
+ * compared, and only when both sides parse.
+ */
+export function isNewer(candidate, current) {
+  const parse = (value) => {
+    if (typeof value !== 'string') return null;
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value.trim());
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+  };
+  const a = parse(candidate);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return true;
+    if (a[i] < b[i]) return false;
+  }
+  return false;
+}
+
+/**
+ * Fetch the published `latest` version, or null for any failure at all — no
+ * network, DNS refusal, a 5xx, a proxy returning HTML, a body without a version
+ * string. The caller cannot distinguish these and should not try to.
+ */
+async function fetchLatest() {
+  try {
+    // Plain application/json, NOT npm's abbreviated-metadata type: that one is
+    // only accepted on the full packument, and asking for it here gets a 406
+    // that this function would swallow into a permanent "no update available".
+    // The single-version document is ~1.5 KB, smaller than the packument the
+    // abbreviated type would have saved us from.
+    const res = await fetch(REGISTRY_URL, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    return typeof json?.version === 'string' ? json.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check at most once every 24h and print a notice when a newer release exists.
+ *
+ * The cache timestamp is written on every completed check, including one that
+ * found nothing and one whose fetch failed. Writing it only on success would
+ * turn an offline machine into a machine that retries the registry on every
+ * single invocation.
+ *
+ * Note this is awaited by the caller rather than detached: the CLI ends in an
+ * explicit process.exit(), which would kill a floating promise mid-flight and
+ * leave the cache unwritten — so a detached check would re-fetch forever while
+ * appearing to cost nothing.
+ */
+export async function maybeNotifyUpdate(currentVersion) {
+  try {
+    if (suppressed()) return;
+
+    const path = updateCachePath();
+    const cached = readJsonFile(path);
+    const checkedAt = Number(cached?.checked_at);
+    const fresh = Number.isFinite(checkedAt) && Date.now() - checkedAt < CHECK_INTERVAL_MS;
+
+    // Inside the window, still report what the last check found: the notice
+    // should persist until the operator actually upgrades, not appear once a day
+    // and vanish.
+    const latest = fresh ? cached?.latest : await fetchLatest();
+    if (!fresh) {
+      writeCacheQuietly(path, { checked_at: Date.now(), latest: latest ?? null });
+    }
+
+    if (typeof latest !== 'string' || !isNewer(latest, currentVersion)) return;
+
+    process.stderr.write(
+      `\nnote: @pingroom/cli ${latest} is available (you have ${currentVersion})\n`
+      + '      npm i -g @pingroom/cli\n'
+      + '      set PINGROOM_NO_UPDATE_CHECK=1 to silence this\n',
+    );
+  } catch {
+    // Unreachable by design — every step above already swallows its own
+    // failures. This is the backstop that guarantees the promise this function
+    // returns can never reject into the caller's exit path.
+  }
+}

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.7.6",
+  "version": "0.8.1",
   "description": "Send PingRoom Pings and wait for human decisions from CI, scripts, and agents.",
   "type": "module",
   "bin": {