@pingroom/cli 0.7.5 → 0.8.0

package/README.md

@@ -243,6 +243,36 @@ on the Lock Screen (iOS Live Activity / Dynamic Island, Android live update, and
 a full inline card in the app). `start` opens it with one alert, `update` moves
 it **silently**, `end` closes it with one completion alert.
 
+## Managing rooms, webhooks, and quick actions
+
+The management nouns cover the rest of the agent surface (agent token required;
+`--room` where noted):
+
+```bash
+pingroom rooms list                       # rooms this account belongs to
+pingroom rooms get GZNFB6BZGJIH
+pingroom rooms create -n "Deploys" --icon bell --color "#e33122"
+pingroom rooms create -n "Status" --icon globe --color "#0391fe" --public --handle status
+pingroom rooms join GZNFB6BZGJIH
+
+pingroom webhooks list --room GZNFB6BZGJIH
+pingroom webhooks create --room GZNFB6BZGJIH --name "CI" --action 2   # prints the secret URL once
+pingroom webhooks update <id> --room GZNFB6BZGJIH --enabled false
+pingroom webhooks delete <id> --room GZNFB6BZGJIH
+
+pingroom actions list --room GZNFB6BZGJIH
+pingroom actions set 3 --room GZNFB6BZGJIH --label "Deploy done" --icon 🚀
+pingroom actions trigger 3 --room GZNFB6BZGJIH
+
+pingroom approval -p "Ship v2 to production?" --wait   # exit 0 approved · 4 denied · 3 expired
+
+pingroom attachment get <id> --out report.md
+pingroom attachment delete <id>
+```
+
+Creating webhooks and uploading attachments require a Pro account; public-room
+creation runs under its own consent scope (`pingroom:rooms:publish`).
+
 ## Hearing replies
 
 Everything else here talks; `listen` is how an agent hears — replies to its own
@@ -506,6 +536,9 @@ Options are `value:label` pairs (repeat `-o` for 2–4). Omit them for the binar
 Approve/Deny default — two options is the lock-screen fast path. `--ttl` sets the
 expiry in seconds (default 1h; 30–86400). `--scope room` lets any eligible member
 answer (first tap wins); the default `direct` asks your bound user.
+`--idempotency-key <key>` sends a printable 1–255 character `Idempotency-Key`
+header. Retrying the same key with the same request returns the original
+Question; reusing it with a changed request returns `409 idempotency_conflict`.
 
 ## Handoffs (agent → human)
 
@@ -590,22 +623,53 @@ tune the approval-question expiry with `--ttl <seconds>` (default 900).
 
 ## MCP client setup
 
-Print the canonical remote endpoint, a copy-ready Claude Code command, Cursor
-JSON, and the Claude Desktop custom-connector steps:
+Print the canonical remote endpoint, copy-ready Codex and Claude Code commands,
+Cursor JSON, Claude custom-connector steps, and the public OpenAI directory:
 
 ```bash
 pingroom mcp
 # no global install: npx --yes @pingroom/cli mcp
 ```
 
-`pingroom mcp add claude-code` prints the exact `claude mcp add` command but does
-not execute it or modify client configuration. After adding the server, use the
-client's MCP controls to authenticate in the browser; no PingRoom API key is
-pasted into its config.
+`pingroom mcp add codex` and `pingroom mcp add claude-code` print the exact setup
+commands but do not execute them or modify client configuration. After adding
+the server, use the client's MCP controls to authenticate in the browser; no
+PingRoom API key is pasted into its config. Once PingRoom's public listing is
+approved, the same plugin will also be discoverable in the Plugins Directory
+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,10 +40,12 @@ 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, parseQArgs,
+  parseLiveArgs, parseLogoutArgs, parseManageArgs, parseQArgs, parseSkillsArgs,
 } from '../lib/parser.js';
+import { actions, approval, attachment, rooms, webhooks } from '../lib/commands/manage.js';
 import { ping } from '../lib/commands/ping.js';
 import { ask, cancel, list, watch } from '../lib/commands/ask.js';
 import { handoff, listHandoffs } from '../lib/commands/handoff.js';
@@ -50,6 +53,7 @@ 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 { skills } from '../lib/commands/skills.js';
 import { activateStoredInbox, bare } from '../lib/commands/connect.js';
 import { config, logout } from '../lib/commands/config.js';
 
@@ -65,8 +69,14 @@ 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)),
+  webhooks: (rest) => webhooks(parseManageArgs(rest)),
+  actions: (rest) => actions(parseManageArgs(rest)),
+  approval: (rest) => approval(parseManageArgs(rest)),
+  attachment: (rest) => attachment(parseManageArgs(rest)),
   config: (rest) => config(parseConfigArgs(rest)),
   logout: (rest) => logout(parseLogoutArgs(rest)),
 };
@@ -94,7 +104,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];
@@ -103,6 +115,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

@@ -76,11 +76,24 @@ 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;
+  }
+
   // Pre-flight: reject a bad --timeout before the question exists.
   if (args.wait) resolveWaitHold(args, { def: 25, cap: 30 });
 
   const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/questions`;
-  const { res, text, json } = await httpJson('POST', url, { body, headers: { Authorization: `Bearer ${token}` } });
+  const { res, text, json } = await httpJson('POST', url, { body, headers });
   if (!res.ok) {
     const detail = apiDetail(res, json);
     fail(`ask failed: ${detail}`);

package/lib/commands/manage.js

@@ -0,0 +1,260 @@
+// Room, webhook, quick-action, approval, and attachment management — the
+// agent REST surface that previously had no CLI verbs. One module, one
+// sub-command dispatch per noun, JSON-first output (--json prints the raw
+// response; the default prints a compact human line per record).
+
+import { EXIT } from '../constants.js';
+import { fail } from '../util.js';
+import { commandHelp } from '../help.js';
+import { apiDetail, httpJson } from '../http.js';
+import { agentContext } from '../config.js';
+
+function sub(args, allowed, noun) {
+  const name = args._[0];
+  if (!name || !allowed.includes(name)) {
+    fail(`usage: pingroom ${noun} <${allowed.join('|')}>\nRun "pingroom ${noun} --help".`, EXIT.USAGE);
+  }
+  return name;
+}
+
+function auth(token) {
+  return { Authorization: `Bearer ${token}` };
+}
+
+async function requireOk(promise, what) {
+  const { res, text, json } = await promise;
+  if (!res.ok) fail(`${what} failed: ${apiDetail(res, json)}`);
+  return { text, json };
+}
+
+function printJsonOr(args, text, lines) {
+  if (args.json) process.stdout.write(`${text}\n`);
+  else process.stdout.write(`${lines}\n`);
+}
+
+// ---------------------------------------------------------------- rooms
+
+export async function rooms(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('rooms')}\n`); return EXIT.OK; }
+  const action = sub(args, ['list', 'get', 'create', 'join'], 'rooms');
+  const { token, apiBase } = agentContext(args);
+
+  if (action === 'list') {
+    const { text, json } = await requireOk(
+      httpJson('GET', `${apiBase}/api/agent/rooms`, { headers: auth(token) }),
+      'rooms list',
+    );
+    const items = Array.isArray(json) ? json : (json.rooms ?? json.data ?? []);
+    printJsonOr(args, text, items.map((r) => `${r.invite_code}  ${r.name}${r.is_public ? '  (public)' : ''}`).join('\n') || '(no rooms)');
+    return EXIT.OK;
+  }
+
+  if (action === 'get') {
+    const code = args._[1];
+    if (!code) fail('usage: pingroom rooms get <invite-code>', EXIT.USAGE);
+    const { text } = await requireOk(
+      httpJson('GET', `${apiBase}/api/agent/rooms/${encodeURIComponent(code)}`, { headers: auth(token) }),
+      'rooms get',
+    );
+    process.stdout.write(`${text}\n`);
+    return EXIT.OK;
+  }
+
+  if (action === 'join') {
+    const code = args._[1];
+    if (!code) fail('usage: pingroom rooms join <invite-code>', EXIT.USAGE);
+    const { text, json } = await requireOk(
+      httpJson('POST', `${apiBase}/api/agent/rooms/join`, { headers: auth(token), body: { invite_code: code } }),
+      'rooms join',
+    );
+    printJsonOr(args, text, `joined ${json.room?.name ?? code}`);
+    return EXIT.OK;
+  }
+
+  // create — private by default; --public requires --handle and uses the
+  // dedicated consent scope on the server.
+  if (!args.name) fail('rooms create needs --name', EXIT.USAGE);
+  if (!args.icon || !args.color) fail('rooms create needs --icon and --color (see "pingroom rooms list-icons" via the app, e.g. --icon bell --color "#e33122")', EXIT.USAGE);
+
+  const body = { name: args.name, icon: args.icon, color: args.color };
+  if (args.description) body.description = args.description;
+
+  let url = `${apiBase}/api/agent/rooms`;
+  if (args.public) {
+    if (!args.handle) fail('a public room needs --handle', EXIT.USAGE);
+    body.handle = args.handle;
+    url = `${apiBase}/api/agent/rooms/public`;
+  }
+
+  const { text, json } = await requireOk(httpJson('POST', url, { headers: auth(token), body }), 'rooms create');
+  printJsonOr(args, text, `created ${json.room?.invite_code ?? json.invite_code ?? ''} ${args.name}`.trim());
+  return EXIT.OK;
+}
+
+// ------------------------------------------------------------- webhooks
+
+export async function webhooks(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('webhooks')}\n`); return EXIT.OK; }
+  const action = sub(args, ['list', 'create', 'update', 'delete'], 'webhooks');
+  const { token, apiBase, room } = agentContext(args, { needRoom: true });
+  const base = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/webhooks`;
+
+  if (action === 'list') {
+    const { text, json } = await requireOk(httpJson('GET', base, { headers: auth(token) }), 'webhooks list');
+    const items = Array.isArray(json) ? json : (json.webhooks ?? json.data ?? []);
+    printJsonOr(args, text, items.map((w) => `${w.id}  ${w.name}${w.enabled === false ? '  (disabled)' : ''}`).join('\n') || '(no webhooks)');
+    return EXIT.OK;
+  }
+
+  if (action === 'delete') {
+    const id = args._[1];
+    if (!id) fail('usage: pingroom webhooks delete <id> --room <code>', EXIT.USAGE);
+    await requireOk(httpJson('DELETE', `${base}/${encodeURIComponent(id)}`, { headers: auth(token) }), 'webhooks delete');
+    process.stdout.write('deleted\n');
+    return EXIT.OK;
+  }
+
+  const body = {};
+  for (const key of ['name', 'title', 'message', 'icon', 'color', 'sound']) {
+    if (args[key] !== undefined) body[key] = args[key];
+  }
+  if (args.action !== undefined) body.action_number = Number(args.action);
+  if (args.cooldown !== undefined) body.cooldown_seconds = Number(args.cooldown);
+  if (args.enabled !== undefined) body.enabled = args.enabled !== 'false';
+
+  if (action === 'create') {
+    if (!body.name) fail('webhooks create needs --name', EXIT.USAGE);
+    const { text, json } = await requireOk(httpJson('POST', base, { headers: auth(token), body }), 'webhooks create');
+    // The trigger URL carries the webhook secret — print it once, like the app.
+    printJsonOr(args, text, `created ${json.webhook?.id ?? ''}\n${json.webhook?.url ?? json.url ?? ''}`.trim());
+    return EXIT.OK;
+  }
+
+  const id = args._[1];
+  if (!id) fail('usage: pingroom webhooks update <id> --room <code> [fields]', EXIT.USAGE);
+  const { text } = await requireOk(
+    httpJson('PUT', `${base}/${encodeURIComponent(id)}`, { headers: auth(token), body }),
+    'webhooks update',
+  );
+  process.stdout.write(`${text}\n`);
+  return EXIT.OK;
+}
+
+// -------------------------------------------------------------- actions
+
+export async function actions(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('actions')}\n`); return EXIT.OK; }
+  const action = sub(args, ['list', 'set', 'trigger'], 'actions');
+  const { token, apiBase, room } = agentContext(args, { needRoom: true });
+  const base = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/actions`;
+
+  if (action === 'list') {
+    const { text, json } = await requireOk(httpJson('GET', base, { headers: auth(token) }), 'actions list');
+    const items = Array.isArray(json) ? json : (json.actions ?? json.quick_actions ?? json.data ?? []);
+    printJsonOr(args, text, items.map((a) => `${a.action_number}  ${a.icon ?? ''} ${a.label ?? '(unset)'}`).join('\n') || '(no actions)');
+    return EXIT.OK;
+  }
+
+  const slot = args._[1];
+  if (!/^[1-4]$/.test(String(slot))) fail(`usage: pingroom actions ${action} <1-4> --room <code>`, EXIT.USAGE);
+
+  if (action === 'trigger') {
+    const { text } = await requireOk(
+      httpJson('POST', `${base}/${slot}/trigger`, { headers: auth(token), body: {} }),
+      'actions trigger',
+    );
+    process.stdout.write(`${text}\n`);
+    return EXIT.OK;
+  }
+
+  if (!args.label || !args.icon) fail('actions set needs --label and --icon', EXIT.USAGE);
+  const body = { label: args.label, icon: args.icon };
+  if (args.sound !== undefined) body.sound = args.sound;
+  if (args.require_ack) body.requires_ack = true;
+
+  const { text } = await requireOk(
+    httpJson('PUT', `${base}/${slot}`, { headers: auth(token), body }),
+    'actions set',
+  );
+  process.stdout.write(`${text}\n`);
+  return EXIT.OK;
+}
+
+// ------------------------------------------------------------- approval
+
+const APPROVAL_EXIT = { approved: EXIT.OK, denied: EXIT.CANCELLED, expired: EXIT.EXPIRED };
+
+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);
+  const { token, apiBase, room } = agentContext(args, { needRoom: true });
+
+  const body = { prompt: args.prompt };
+  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 { text, json } = await requireOk(
+    httpJson('POST', `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/approvals`, { headers: auth(token), body }),
+    'approval',
+  );
+
+  if (!args.wait) {
+    process.stdout.write(`${text}\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;
+    }
+  }
+}
+
+// ----------------------------------------------------------- attachment
+
+export async function attachment(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('attachment')}\n`); return EXIT.OK; }
+  const action = sub(args, ['get', 'delete'], 'attachment');
+  const id = args._[1];
+  if (!id) fail(`usage: pingroom attachment ${action} <id>`, EXIT.USAGE);
+  const { token, apiBase } = agentContext(args);
+
+  if (action === 'delete') {
+    await requireOk(
+      httpJson('DELETE', `${apiBase}/api/agent/attachments/${encodeURIComponent(id)}`, { headers: auth(token) }),
+      'attachment delete',
+    );
+    process.stdout.write('deleted\n');
+    return EXIT.OK;
+  }
+
+  // Binary download: raw fetch, not httpJson. Bytes go to --out or stdout.
+  const res = await fetch(`${apiBase}/api/agent/attachments/${encodeURIComponent(id)}/content`, {
+    headers: auth(token),
+  });
+  if (!res.ok) {
+    let json = null;
+    try { json = await res.json(); } catch { /* binary error bodies stay generic */ }
+    fail(`attachment get failed: ${apiDetail(res, json)}`);
+  }
+  const bytes = Buffer.from(await res.arrayBuffer());
+  if (args.out) {
+    const { writeFileSync } = await import('node:fs');
+    writeFileSync(args.out, bytes);
+    process.stdout.write(`${args.out}  ${bytes.length} bytes\n`);
+  } else {
+    process.stdout.write(bytes);
+  }
+  return EXIT.OK;
+}

package/lib/commands/mcp.js

@@ -6,6 +6,8 @@ import { fail } from '../util.js';
 
 export function mcp(rest) {
   const claudeCommand = `claude mcp add --transport http pingroom ${MCP_ENDPOINT}`;
+  const codexAddCommand = `codex mcp add pingroom --url ${MCP_ENDPOINT}`;
+  const codexLoginCommand = 'codex mcp login pingroom';
 
   if (rest.length === 0 || (rest.length === 1 && (rest[0] === '-h' || rest[0] === '--help'))) {
     const config = {
@@ -20,6 +22,13 @@ export function mcp(rest) {
 Claude Code:
   ${claudeCommand}
 
+Codex CLI:
+  ${codexAddCommand}
+  ${codexLoginCommand}
+
+OpenAI Plugins Directory (ChatGPT and Codex):
+  Search for PingRoom after its public listing is approved.
+
 Cursor JSON (~/.cursor/mcp.json):
 ${JSON.stringify(config, null, 2)}
 
@@ -43,5 +52,14 @@ This command only prints setup instructions and does not modify client config.
     return EXIT.OK;
   }
 
-  fail('usage: pingroom mcp [add claude-code]', EXIT.USAGE);
+  if (rest.length === 2 && rest[0] === 'add' && rest[1] === 'codex') {
+    process.stdout.write(
+`No client configuration was changed. Copy and run:
+  ${codexAddCommand}
+  ${codexLoginCommand}
+`);
+    return EXIT.OK;
+  }
+
+  fail('usage: pingroom mcp [add claude-code|codex]', EXIT.USAGE);
 }

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/config.js

@@ -1,7 +1,7 @@
 // Local state (~/.pingroom) and the layered resolution every command shares:
 // explicit flag > env var > config file > the paired credential > built-in.
 
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import {
   chmodSync, closeSync, fchmodSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync,
   writeFileSync,
@@ -12,6 +12,7 @@ import { join } from 'node:path';
 import { BUILTIN_API, EXIT } from './constants.js';
 import { fail } from './util.js';
 import { requireSafeUrl } from './http.js';
+import { parseJsonStrict } from './strict-json.js';
 
 // --- local state (~/.pingroom) ---------------------------------------------
 //
@@ -36,9 +37,9 @@ export function configPath() { return join(pingroomHome(), 'config.json'); }
 // never be able to crash a ping: a hand-edited file degrades to "not set".
 export function readJsonFile(path) {
   let raw;
-  try { raw = readFileSync(path, 'utf8'); } catch { return null; }
+  try { raw = new TextDecoder('utf-8', { fatal: true }).decode(readFileSync(path)); } catch { return null; }
   let value;
-  try { value = JSON.parse(raw); } catch { return null; }
+  try { value = parseJsonStrict(raw, path); } catch { return null; }
   if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
   return value;
 }
@@ -183,6 +184,13 @@ export function agentContext(args, { needRoom = false } = {}) {
   if (needRoom && !room) {
     fail('--room is required (or set one with "pingroom config set default_room <code>")', EXIT.USAGE);
   }
+  if (args.expected_room_sha256 !== undefined) {
+    const expected = String(args.expected_room_sha256);
+    if (!/^[a-f0-9]{64}$/.test(expected)) fail('--expected-room-sha256 must be 64 lowercase hexadecimal characters', EXIT.USAGE);
+    if (!room) fail('--expected-room-sha256 requires a resolved room', EXIT.USAGE);
+    const actual = createHash('sha256').update(String(room), 'utf8').digest('hex');
+    if (actual !== expected) fail('resolved room does not match --expected-room-sha256', EXIT.USAGE);
+  }
   return { token, apiBase, room };
 }
 

package/lib/help.js

@@ -30,7 +30,13 @@ 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)
+  actions  List, configure, or trigger a room's quick actions (actions list|set|trigger)
+  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>)
   logout   Forget the stored credential`;
 
@@ -65,6 +71,7 @@ export const HELP_ASK = `ask options (agent token required):
       --scope <s>        Who answers: 'direct' (default) or 'room'
       --target <uuid>    For --scope direct: a specific room member
       --ttl <seconds>    Expiry; omit for the server default (1h; 30..86400)
+      --idempotency-key <key>  Dedupe this exact create request across retries
       --text-input <ph>  Invite a short typed answer; <ph> is the placeholder
       --text-max <n>     Max typed-answer length (1..60)
       --wait             Block until answered/expired/cancelled
@@ -73,6 +80,8 @@ export const HELP_ASK = `ask options (agent token required):
       --correlation-id <id>  Opaque id echoed on every read of this question
       --reply-to <id>    Id of the ping this question replies to
       --room <code>      Room invite code (required for ask)
+      --expected-room-sha256 <hex>
+                         Fail unless the resolved room matches this SHA-256
       --github-output <path>  Safely append question outputs for GitHub Actions`;
 
 export const HELP_LIST = `list options:
@@ -148,6 +157,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 —
@@ -270,7 +286,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');
 
@@ -291,7 +307,39 @@ 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
+  pingroom rooms get <code>         Show one room
+  pingroom rooms create -n <name> --icon <id> --color <hex>
+                                    Create a private room (add --description);
+                                    --public --handle <handle> creates a public
+                                    room under its own consent scope
+  pingroom rooms join <code>        Join a room by invite code`,
+  webhooks: `webhooks (agent token + --room required):
+  pingroom webhooks list --room <code>
+  pingroom webhooks create --room <code> --name <n>
+                                    Optional: --title --message --icon --color
+                                    --sound --action <1-4> --cooldown <sec>
+                                    Prints the secret trigger URL once
+  pingroom webhooks update <id> --room <code> [same fields, plus --enabled true|false]
+  pingroom webhooks delete <id> --room <code>`,
+  actions: `actions (agent token + --room required):
+  pingroom actions list --room <code>
+  pingroom actions set <1-4> --room <code> --label <text> --icon <emoji>
+                                    Optional: --sound, --require-ack
+  pingroom actions trigger <1-4> --room <code>`,
+  approval: `approval (agent token + --room required):
+  pingroom approval -p <prompt>     Send an approve/deny request
+      -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)`,
+  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,
   logout: `logout:
   pingroom logout                   Forget the stored credential (PINGROOM_TOKEN
@@ -307,6 +355,10 @@ export const COMMAND_HELP_FOOTERS = {
   -h, --help             Show this help`,
   logout: `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

@@ -3,6 +3,7 @@
 
 import { EXIT } from './constants.js';
 import { fail, stripControlChars } from './util.js';
+import { readStrictJsonResponse } from './strict-json.js';
 
 /**
  * The fixes that live on THIS side of the wire. The server's message always
@@ -85,15 +86,13 @@ export async function httpJson(method, url, { body, headers = {}, soft = false,
   }
 
   let text;
+  let json;
   try {
-    text = await res.text();
+    ({ text, json } = await readStrictJsonResponse(res, 'PingRoom API response'));
   } catch (err) {
-    // A connection dropped mid-body throws here, not at fetch().
     if (soft) return { res: null, text: '', json: null, error: err };
-    fail(`network error: ${err.message}`);
+    fail(`untrusted JSON response: ${err.message}`);
   }
-  let json = null;
-  try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
 
   return { res, text, json };
 }
@@ -165,9 +164,10 @@ export async function uploadAttachments(paths, apiBase, token) {
       fail(`network error uploading ${name}: ${err.message}`);
     }
 
-    const text = await res.text().catch(() => '');
     let json = null;
-    try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
+    try { ({ json } = await readStrictJsonResponse(res, 'attachment API response')); } catch (error) {
+      fail(`untrusted JSON response uploading ${name}: ${error.message}`);
+    }
 
     if (res.status === 402) {
       fail(`--attach ${name}: ping attachments are a Pro feature`, EXIT.USAGE);
@@ -196,9 +196,7 @@ export async function hookFetch(method, url, { body, token } = {}) {
     },
     ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
   });
-  const text = await res.text();
-  let json = null;
-  try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
+  const { json } = await readStrictJsonResponse(res, 'hook response');
   if (!res.ok) {
     throw new Error(apiDetail(res, json));
   }

package/lib/parser.js

@@ -70,6 +70,7 @@ export const parseArgs = makeParser({
     '--attach': 'attach',
     '--token': 'token',
     '--room': 'room',
+    '--expected-room-sha256': 'expected_room_sha256',
     '--api': 'api',
     '--json': 'json',
     '-h': 'help', '--help': 'help',
@@ -88,6 +89,7 @@ export const parseQArgs = makeParser({
     '--scope': 'scope',
     '--target': 'target',
     '--ttl': 'ttl',
+    '--idempotency-key': 'idempotency_key',
     '-d': 'data', '--data': 'data',
     '--correlation-id': 'correlation_id',
     '--reply-to': 'reply_to',
@@ -101,6 +103,7 @@ export const parseQArgs = makeParser({
     '--github-output': 'github_output',
     '--token': 'token',
     '--room': 'room',
+    '--expected-room-sha256': 'expected_room_sha256',
     '--api': 'api',
     '--wait': 'wait',
     '--json': 'json',
@@ -208,6 +211,52 @@ export const parseLogoutArgs = makeParser({
   bareDashIsPositional: true,
 });
 
+// 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',
+    '--description': 'description',
+    '--icon': 'icon',
+    '--color': 'color',
+    '--sound': 'sound',
+    '--label': 'label',
+    '-t': 'title', '--title': 'title',
+    '-m': 'message', '--message': 'message',
+    '-p': 'prompt', '--prompt': 'prompt',
+    '-c': 'context', '--context': 'context',
+    '--ttl': 'ttl',
+    '--public': 'public',
+    '--handle': 'handle',
+    '-a': 'action', '--action': 'action',
+    '--cooldown': 'cooldown',
+    '--enabled': 'enabled',
+    '--require-ack': 'require_ack',
+    '--out': 'out',
+    '--wait': 'wait',
+    '--token': 'token',
+    '--room': 'room',
+    '--expected-room-sha256': 'expected_room_sha256',
+    '--api': 'api',
+    '--json': 'json',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['public', 'require_ack', 'wait', 'json', 'help'],
+});
+
 export const parseHandoffsArgs = makeParser({
   aliases: {
     '--state': 'state',

package/lib/strict-json.js

@@ -0,0 +1,93 @@
+const MAX_JSON_BYTES = 1024 * 1024;
+
+export function parseJsonStrict(raw, label = 'JSON') {
+  if (typeof raw !== 'string') throw new Error(`${label} must be UTF-8 JSON`);
+  rejectDuplicateKeys(raw, label);
+  return JSON.parse(raw);
+}
+
+export async function readStrictJsonResponse(response, label = 'response') {
+  const chunks = [];
+  let size = 0;
+  if (response.body) {
+    const reader = response.body.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > MAX_JSON_BYTES) {
+        await reader.cancel().catch(() => {});
+        throw new Error(`${label} exceeded ${MAX_JSON_BYTES} bytes`);
+      }
+      chunks.push(Buffer.from(value));
+    }
+  }
+  const bytes = Buffer.concat(chunks);
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { throw new Error(`${label} was not valid UTF-8`); }
+  return { text, json: text ? parseJsonStrict(text, label) : null };
+}
+
+function rejectDuplicateKeys(raw, label) {
+  let index = 0;
+  const invalid = () => { throw new Error(`${label} is not valid JSON`); };
+  const whitespace = () => { while (/\s/u.test(raw[index] ?? '')) index += 1; };
+  const string = () => {
+    if (raw[index] !== '"') invalid();
+    const start = index++;
+    while (index < raw.length) {
+      if (raw[index] === '\\') { index += 2; continue; }
+      if (raw[index] === '"') {
+        index += 1;
+        try { return JSON.parse(raw.slice(start, index)); } catch { invalid(); }
+      }
+      index += 1;
+    }
+    invalid();
+  };
+  const value = () => {
+    whitespace();
+    if (raw[index] === '{') return object();
+    if (raw[index] === '[') return array();
+    if (raw[index] === '"') { string(); return; }
+    const start = index;
+    while (index < raw.length && !/[\s,\]}]/u.test(raw[index])) index += 1;
+    if (index === start) invalid();
+  };
+  const object = () => {
+    index += 1;
+    whitespace();
+    const keys = new Set();
+    if (raw[index] === '}') { index += 1; return; }
+    for (;;) {
+      whitespace();
+      const key = string();
+      if (keys.has(key)) throw new Error(`${label} contains a duplicate object key`);
+      keys.add(key);
+      whitespace();
+      if (raw[index] !== ':') invalid();
+      index += 1;
+      value();
+      whitespace();
+      if (raw[index] === '}') { index += 1; return; }
+      if (raw[index] !== ',') invalid();
+      index += 1;
+    }
+  };
+  const array = () => {
+    index += 1;
+    whitespace();
+    if (raw[index] === ']') { index += 1; return; }
+    for (;;) {
+      value();
+      whitespace();
+      if (raw[index] === ']') { index += 1; return; }
+      if (raw[index] !== ',') invalid();
+      index += 1;
+    }
+  };
+  whitespace();
+  value();
+  whitespace();
+  if (index !== raw.length) invalid();
+}

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/package.json

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