pidge-cli 0.6.1 → 0.8.0

package/README.md

@@ -11,6 +11,48 @@ then gets the answer as JSON — no webhook, no polling loop to write.
 > current spec (fields, profiles, guarantees). This CLI is a thin pipe over it — any
 > new server field works without a CLI update via `--param key=value`.
 
+## Setup in one command (v0.8.0 — the claim flow)
+
+```bash
+# The human copies a setup prompt from the Pidge app (Canais → the channel) —
+# it carries a SINGLE-USE claim code (15 min TTL), never the key:
+npx pidge-cli setup --claim <code> --url https://pidge.sh
+# → exchanges the code for the real key, stores it (chmod 600), runs `pidge doctor`.
+#   The secret never appears on screen or in any chat (the CLI writes it).
+
+npx pidge-cli doctor   # validate anytime: env source, server, key, "canal X · N devices"
+npx pidge-cli whoami   # which channel does this key speak for (JSON)
+```
+
+### Many agents on one machine — isolate them (read this)
+
+`~/.config/pidge/env` is **one slot per machine-user**: every agent without its
+own identity reads the same key, so one agent's `setup` makes another agent send
+as the wrong channel (this bit us for real — a cron got hijacked). Each agent
+must have its **own** identity. Cheapest correct setups, in order:
+
+```bash
+# A. per-agent env var — the cleanest; the human sets it at the agent's launch
+#    (systemd unit / launcher / profile). Env var always wins over any file.
+export PIDGE_TOKEN=hld_…        # this agent only
+
+# B. per-agent config file — set ONE non-secret id at launch; the CLI namespaces
+#    the file to ~/.config/pidge/agents/<id>/env and still writes the key for you
+#    (no secret in the agent's chat). setup/doctor/everything follow it.
+export PIDGE_AGENT=javier
+npx pidge-cli setup --claim <code>
+
+# C. you're at YOUR terminal and want the env var hygienically from a claim:
+npx pidge-cli setup --claim <code> --print   # prints `export …`; writes nothing
+#    paste the two lines into THAT agent's launcher. NEVER run --print as an agent
+#    (the key would land in its context) — that's what A/B are for.
+```
+
+The bare `~/.config/pidge/env` (no `PIDGE_AGENT`) is fine for a **single** agent;
+`pidge doctor` warns loudly when you're on that shared file. Lost the local key?
+Just re-claim — `POST /claim` returns the channel's **same** key, so re-running
+setup restores the exact identity.
+
 ## Use it (no install — via npx)
 
 ```bash
@@ -55,6 +97,10 @@ npx pidge-cli notify --title "Relatório" --file ./relatorio.xlsx
 | `cancel <correlation_id>` | Cancel a **still-scheduled** notification before it fires (idempotent; 409 once it reached the phone). |
 | `inbox` | What you sent: list, `--pending` slice, or `--summary` (counts + answer latency). |
 | `listen` | Block until the human **messages you** from the app; prints the messages, ACKs them, exits `0`. One-shot — loop it. |
+| `setup --claim <code>` | One-shot onboarding (v0.7.0): exchange the single-use code for the key, store it in `~/.config/pidge/env` (600), run doctor. |
+| `doctor` | Validate the setup **without exposing secrets**: env source, server reachable, key valid, channel + device count. Exit 0/2. |
+| `whoami` | Which channel does this key speak for (JSON). |
+| `skill install` | Write `.claude/skills/pidge/SKILL.md` generated from the live manifest — persistent Pidge knowledge for Claude Code agents; re-run to update. |
 
 ## Realtime (v0.6.0)
 

package/bin/pidge.js

@@ -41,13 +41,28 @@ const path = require('node:path');
 const os = require('node:os');
 const crypto = require('node:crypto');
 
-// #57 token hygiene: when the env vars are unset, fall back to
-// ~/.config/pidge/env (KEY=VALUE lines the HUMAN writes once in THEIR terminal)
-// so the raw hld_… key never has to ride the agent's chat/context. Explicit env
-// vars always win; `export ` prefixes, quotes and #comments are tolerated.
+// Per-agent isolation (incident 2026-06-13): ~/.config/pidge/env is one slot
+// per machine-user, so N agents sharing a HOME share an identity — one agent's
+// setup hijacked another's cron. The fix is a NON-secret namespacing var the
+// human sets ONCE at each agent's launch: PIDGE_AGENT=<id> → the config lives
+// at ~/.config/pidge/agents/<id>/env, isolated by construction. The CLI still
+// WRITES the key (the agent never sees it — #57 hygiene intact), it's just
+// per-agent now. No PIDGE_AGENT ⇒ the legacy shared file (single-agent only).
+// (An explicit PIDGE_TOKEN env var still wins over any file — the purest
+// per-agent path.)
+const AGENT_ID = (process.env.PIDGE_AGENT || '').trim().replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 64);
+function pidgeConfigDir() {
+  const base = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'pidge');
+  return AGENT_ID ? path.join(base, 'agents', AGENT_ID) : base;
+}
+
+// #57 token hygiene: when the env vars are unset, fall back to the config file
+// (KEY=VALUE the CLI writes during setup, or the HUMAN writes once) so the raw
+// hld_… key never rides the agent's chat/context. Explicit env vars always win;
+// `export ` prefixes, quotes and #comments are tolerated.
 function configEnv() {
   try {
-    const file = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'pidge', 'env');
+    const file = path.join(pidgeConfigDir(), 'env');
     const out = {};
     for (let line of fs.readFileSync(file, 'utf8').split('\n')) {
       line = line.trim().replace(/^export\s+/, '');
@@ -90,6 +105,7 @@ const OPTIONS = {
   'reply-to': { type: 'string' },
   'correlation-id': { type: 'string' },
   thread: { type: 'string' },                  // conversation handle (#49) — same id ⇒ one strand on the phone
+  after: { type: 'string' },                   // decision queue (#157): held until this cid resolves
   'collapse-key': { type: 'string' },
   param: { type: 'string', multiple: true },   // key=value escape hatch → raw /notify field
   timeout: { type: 'string' },
@@ -102,17 +118,42 @@ const OPTIONS = {
   // realtime (#118): WS by default when the runtime has a WebSocket (Node ≥22)
   realtime: { type: 'boolean' },               // force WS (warn+fallback if unavailable)
   'no-realtime': { type: 'boolean' },          // polling only
+  // onboarding v2 (#110)
+  claim: { type: 'string' },                   // setup --claim <single-use code>
+  // #157 P2: listen keeps going after a batch (supervisor loop, one process)
+  follow: { type: 'boolean' },
+  force: { type: 'boolean' },                  // setup: overwrite a config owned by ANOTHER channel
+  print: { type: 'boolean' },                  // setup: print export lines instead of writing a file (per-agent, human runs it)
 };
 
 const USAGE = `pidge — send an iPhone notification to a human and block until they answer.
 
 USAGE
+  pidge setup --claim CODE [--url BASE]   one-shot onboarding (#110): exchange the single-use
+                                          code for the channel key, store it, run doctor.
+                                          MULTI-AGENT: set PIDGE_AGENT=<id> at each agent's launch
+                                          → isolated config ~/.config/pidge/agents/<id>/env.
+                                          --print  emit 'export PIDGE_TOKEN=…' instead of a file
+                                                   (you run it in YOUR terminal; paste into the
+                                                   agent's launcher — never run --print as an agent)
+                                          --force  overwrite a shared file owned by another channel
+  pidge doctor                            validate the setup WITHOUT exposing secrets:
+                                          env source, server, key, "canal X · N devices"
+  pidge whoami                            which channel does this key speak for (JSON)
   pidge ask    [options]                  send AND wait for the answer (prints chosen_action JSON)
   pidge notify [options]                  send only (prints the 201 JSON)
   pidge wait   <correlation_id> [options] block on an already-sent notification
   pidge cancel <correlation_id>           cancel a still-scheduled notification (#56)
   pidge inbox  [--pending|--summary|--all|--limit N]   what you sent: list, pending slice, or counts+latency (#83)
-  pidge listen [--timeout N]              block until the human MESSAGES you from the app, print + ack + exit (#48)
+  pidge listen [--timeout N] [--all] [--follow]
+                                          block until the human MESSAGES you from the app, print + ack + exit (#48)
+                                          --follow = print+ack and KEEP listening until --timeout
+                                          (exit 0 if any batch landed; one-shot stays the default)
+                                          --all (#131) = the SINGLE EAR: also hear notification ANSWERS
+                                          (kind notification_reply + self-contained ref) — nothing the human
+                                          says can be missed by a looped listen --all
+  pidge skill install                     write .claude/skills/pidge/SKILL.md generated from the
+                                          live manifest (persistent Pidge knowledge for Claude Code)
   pidge --help
 
 REALTIME (#118)
@@ -157,6 +198,9 @@ OPTIONS (notify / ask)
   --correlation-id ID      idempotency + routing key (auto-generated if omitted)
   --thread ID              conversation handle (#49): sends sharing it group as ONE
                            strand on the phone — use it for follow-ups
+  --after CID              decision queue (#157): HELD until that notification is
+                           answered — chain N decisions so the human sees one at a
+                           time ("Decisão 2/3" --after <cid-da-1>); snooze doesn't advance
   --collapse-key KEY       replace/update a prior notification
   --param KEY=VALUE        pass ANY raw /notify field (repeatable) — future server
                            fields work without a CLI update; the manifest is the contract
@@ -166,9 +210,13 @@ OPTIONS (notify / ask)
 
 ENV
   PIDGE_URL     your Pidge server (default http://localhost:3000; HERALD_URL honored)
-  PIDGE_TOKEN   your channel's bearer key (required; HERALD_TOKEN honored)
-                with neither set, ~/.config/pidge/env (KEY=VALUE) is read — the
-                key-free path: the human writes the file once, no secret in chat
+  PIDGE_TOKEN   your channel's bearer key (required; HERALD_TOKEN honored). Setting
+                this per agent at launch is the cleanest multi-agent isolation —
+                env var always wins over any file.
+  PIDGE_AGENT   <id> namespacing the config file to ~/.config/pidge/agents/<id>/env
+                so N agents on one machine never share an identity (the CLI still
+                writes the key — no secret in the agent's chat). Unset ⇒ the legacy
+                shared ~/.config/pidge/env (single-agent only).
 
 OUTPUT
   stdout is machine-readable (notify→201 JSON; ask/wait→chosen_action JSON);
@@ -197,7 +245,9 @@ const command = parsed.positionals[0];
 // `pidge --help` / `-h` / `help` → full help on stdout, exit 0. No command → stderr, exit 1.
 if (v.help || command === 'help') { console.log(USAGE); process.exit(0); }
 if (!command) { console.error(USAGE); process.exit(1); }
-if (!TOKEN) die('pidge: set PIDGE_TOKEN (env var, or put PIDGE_TOKEN=… in ~/.config/pidge/env)');
+// `setup` is the command that CREATES the token config — it must run without one.
+if (!TOKEN && command !== 'setup')
+  die('pidge: set PIDGE_TOKEN (env var, or put PIDGE_TOKEN=… in ~/.config/pidge/env) — or onboard with: pidge setup --claim <code> (ask your human for the code: Pidge app → Canais → o canal → copiar prompt de setup)');
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const headers = { authorization: `Bearer ${TOKEN}`, 'content-type': 'application/json' };
@@ -217,7 +267,7 @@ function fetchT(url, opts = {}, timeoutMs = 30000) {
 // The server advertises its manifest version on every response. When it's newer
 // than what this CLI shipped knowing, nudge ONCE on stderr — the agent re-reads
 // the manifest (whats_new) and learns the new capabilities without polling.
-const KNOWN_MANIFEST_VERSION = 16;
+const KNOWN_MANIFEST_VERSION = 25;
 let newsWarned = false;
 function checkManifestNews(res) {
   const v = parseInt(res.headers.get('x-pidge-manifest-version') || '0', 10);
@@ -372,6 +422,7 @@ function buildBody() {
   if (v['reply-to'] !== undefined) body.reply_to = v['reply-to'];
   if (v['correlation-id'] !== undefined) body.correlation_id = v['correlation-id'];
   if (v.thread !== undefined) body.thread_id = v.thread;
+  if (v.after !== undefined) body.after = v.after;
   if (v['collapse-key'] !== undefined) body.collapse_key = v['collapse-key'];
   if (v.actions !== undefined) body.actions = v.actions.split(',').filter(Boolean);
 
@@ -379,6 +430,11 @@ function buildBody() {
   if (customs.length) {
     body.custom_actions = customs.map((spec) => {
       const [id, label, ...flags] = spec.split(':');
+      // #157 P2: fail fast locally — the rule is stable and the server 422
+      // costs a round-trip an agent then has to interpret.
+      if (!/^[a-z0-9_]{1,40}$/.test(id || '')) {
+        die(`pidge: --custom-action id ${JSON.stringify(id)} is invalid — lowercase letters, digits and underscore only (^[a-z0-9_]{1,40}$)`, 1);
+      }
       const ca = { id, label };
       if (flags.includes('destructive')) ca.style = 'destructive';
       if (flags.includes('confirm')) ca.confirm = true;
@@ -613,8 +669,235 @@ async function waitForAnswer(cid, { timeout, interval }) {
 
 const num = (val, fallback) => (val !== undefined ? parseInt(val, 10) : fallback);
 
+// ---------------------------------------------------------------------------
+// Onboarding v2 (#110): setup --claim / doctor / whoami / skill install.
+// ---------------------------------------------------------------------------
+
+const CONFIG_DIR = pidgeConfigDir();
+const CONFIG_FILE = path.join(CONFIG_DIR, 'env');
+// True when we're reading the LEGACY shared file (no PIDGE_AGENT, no env var) —
+// the multi-agent footgun. doctor warns on it.
+const ON_SHARED_FILE = !AGENT_ID && !process.env.PIDGE_TOKEN && !process.env.HERALD_TOKEN && !!FILE_ENV.PIDGE_TOKEN;
+
+// Where the token came from — doctor narrates it, setup respects precedence.
+function tokenSource() {
+  if (process.env.PIDGE_TOKEN || process.env.HERALD_TOKEN) return 'env var (per-agent)';
+  if (FILE_ENV.PIDGE_TOKEN) return CONFIG_FILE + (AGENT_ID ? ` (PIDGE_AGENT=${AGENT_ID})` : ' (shared)');
+  return null;
+}
+
+// GET /whoami — which channel does this key speak for. Returns {res, data}.
+async function fetchWhoami(base = BASE, token = TOKEN) {
+  const res = await fetchT(`${base}/api/v1/whoami`, {
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+  });
+  let data = {};
+  try { data = await res.json(); } catch { /* leave {} */ }
+  return { res, data };
+}
+
+// doctor: validate the setup WITHOUT exposing secrets. Narration on stderr,
+// a compact machine-readable line on stdout. Exit 0 healthy / 2 broken.
+async function runDoctor(base = BASE, token = TOKEN) {
+  const source = token === TOKEN ? tokenSource() : CONFIG_FILE; // post-setup call passes the fresh token
+  if (!token) {
+    console.error('pidge doctor: NO TOKEN — set PIDGE_TOKEN, or onboard with `pidge setup --claim <code>` (the human copies the code from the Pidge app)');
+    process.exit(2);
+  }
+  console.error(`pidge doctor: token found (${source || 'passed in'}) — never displayed`);
+  console.error(`pidge doctor: server ${base}`);
+  let out;
+  try {
+    out = await fetchWhoami(base, token);
+  } catch (e) {
+    console.error(`pidge doctor: server UNREACHABLE — ${e.message} (check the URL; is it ${base}?)`);
+    process.exit(2);
+  }
+  const { res, data } = out;
+  checkManifestNews(res);
+  if (res.status === 401) {
+    console.error('pidge doctor: server reachable but the key is INVALID/REVOKED — re-onboard: ask your human for a fresh claim code (Pidge app → Canais → o canal → copiar prompt de setup)');
+    process.exit(2);
+  }
+  if (res.status === 404) {
+    // pre-#110 server: no /whoami yet — the key may still be fine; prove it on the manifest.
+    const m = await fetchT(`${base}/api/v1/manifest`, { headers: { authorization: `Bearer ${token}` } }).catch(() => null);
+    if (m && m.status === 200) {
+      console.error('pidge doctor: key VALID (server predates /whoami — channel/device detail unavailable; update the server to see it)');
+      console.log(JSON.stringify({ ok: true, base_url: base, channel: null, devices: null }));
+      process.exit(0);
+    }
+    console.error(`pidge doctor: unexpected ${m ? m.status : 'network error'} on the manifest — server looks broken`);
+    process.exit(2);
+  }
+  if (res.status !== 200) {
+    console.error(`pidge doctor: unexpected ${res.status} from /whoami — ${JSON.stringify(data)}`);
+    process.exit(2);
+  }
+  const devices = data.devices ?? 0;
+  console.error(`pidge doctor: key valid — canal "${data.channel && data.channel.name}" · ${devices} device(s)`);
+  if (devices === 0)
+    console.error('pidge doctor: WARNING — 0 devices: sends will reach NOBODY until the human installs/opens the Pidge app on their iPhone');
+  if (ON_SHARED_FILE)
+    console.error(`pidge doctor: WARNING — reading the SHARED file ${CONFIG_FILE}. If another agent runs on this machine, it reads the SAME key and you'll send as each other (the 2026-06-13 incident). Isolate: set PIDGE_AGENT=<id> at this agent's launch (config → ~/.config/pidge/agents/<id>/env) or give it its own PIDGE_TOKEN.`);
+  console.error('pidge doctor: all good — try: pidge ask --template decision --title "Pidge funcionando?"');
+  console.log(JSON.stringify({ ok: true, base_url: base, channel: data.channel, devices, manifest_version: data.manifest_version }));
+  process.exit(0);
+}
+
+// setup --claim: exchange the single-use code for the key, store it ourselves
+// (the secret never appears on screen or in the chat the prompt was pasted in),
+// then prove the loop with doctor.
+async function runSetup() {
+  const code = v.claim;
+  if (!code) die('pidge: usage: pidge setup --claim <code> [--url <base>]   (the human copies the code from the Pidge app)', 1);
+  const base = (v.url || process.env.PIDGE_URL || FILE_ENV.PIDGE_URL || 'https://pidge.sh').replace(/\/+$/, '');
+
+  // THE SHARED-CONFIG GUARD (real incident, 2026-06-13). Only the FILE path can
+  // collide; --print writes nothing, so skip it there. CONFIG_FILE is now
+  // per-agent when PIDGE_AGENT is set (no collision by construction), but on the
+  // legacy shared file two agents still share it — refuse to clobber a file that
+  // still authenticates as some channel unless --force. Checked BEFORE the
+  // exchange so the single-use code survives the refusal.
+  if (!v.print && !v.force && FILE_ENV.PIDGE_TOKEN) {
+    let owner = null;
+    try {
+      const { res: wres, data: wdata } = await fetchWhoami(base, FILE_ENV.PIDGE_TOKEN);
+      if (wres.status === 200 && wdata.channel) owner = wdata.channel.name;
+      else if (wres.status !== 401) owner = 'um canal (servidor não confirmou)';
+      // 401 ⇒ the stored key is dead — overwriting a corpse needs no --force.
+    } catch {
+      owner = 'um canal (servidor inalcançável para confirmar)';
+    }
+    if (owner) {
+      die(`pidge: ${CONFIG_FILE} já guarda a chave de "${owner}". Sobrescrever faria qualquer agente que lê esse arquivo enviar como o canal novo (incidente real: um cron foi sequestrado assim). O jeito certo de rodar VÁRIOS agentes na mesma máquina: dê a cada um um PIDGE_AGENT=<id> no launch (cada um ganha ~/.config/pidge/agents/<id>/env isolado), ou um PIDGE_TOKEN próprio, ou rode com --print e cole o export no launcher DESTE agente. Substituir mesmo assim? --force (o claim code continua válido — nada foi consumido).`, 2);
+    }
+  }
+
+  let res, data = {};
+  try {
+    res = await fetchT(`${base}/api/v1/claim`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ code }),
+    });
+    try { data = await res.json(); } catch { /* leave {} */ }
+  } catch (e) {
+    die(`pidge: claim failed (network): ${e.message} — is the server URL right? (${base})`, 2);
+  }
+  if (res.status === 404)
+    die('pidge: claim code unknown, EXPIRED (15 min TTL) or already used — ask your human for a fresh one (Pidge app → Canais → o canal → copiar prompt de setup)', 2);
+  if (!(res.status >= 200 && res.status < 300) || !data.key)
+    die(`pidge: claim failed (${res.status}): ${JSON.stringify(data)}`, 2);
+
+  const finalBase = (data.base_url || base).replace(/\/+$/, '');
+  const channelName = data.channel && data.channel.name;
+
+  // --print: the pure per-agent path — emit the export lines (the HUMAN runs
+  // this in THEIR terminal and pastes them into the agent's launcher). Stores
+  // nothing; the key shows on screen, so DON'T let an agent run --print (the
+  // key would land in its context — that's what the file path is for). stdout
+  // is eval-able; the guidance goes to stderr.
+  if (v.print) {
+    console.log(`export PIDGE_URL=${finalBase}`);
+    console.log(`export PIDGE_TOKEN=${data.key}`);
+    console.error(`pidge: canal "${channelName}" — modo POR-AGENTE (nada gravado em disco). Cole as duas linhas no ambiente de lançamento DESTE agente (systemd/launcher/cron/profile). Cada agente tem a SUA chave; perdeu, é só pegar outro código no app e re-rodar (a chave do canal é a MESMA). NÃO rode --print de dentro de um agente — a chave apareceria no contexto dele.`);
+    await runDoctor(finalBase, data.key);
+    return;
+  }
+
+  // File path (default): the CLI writes the key — the agent never sees it
+  // (#57). Per-agent when PIDGE_AGENT is set; otherwise the legacy shared file.
+  fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(CONFIG_FILE, `PIDGE_URL=${finalBase}\nPIDGE_TOKEN=${data.key}\n`, { mode: 0o600 });
+  try { fs.chmodSync(CONFIG_FILE, 0o600); } catch { /* mode set on create */ }
+  console.error(`pidge: canal "${channelName}" configurado — chave em ${CONFIG_FILE} (chmod 600, nunca exibida)`);
+  if (!AGENT_ID)
+    console.error('pidge: este é o arquivo COMPARTILHADO (single-agent). Vai rodar 2+ agentes nesta máquina? Dê a cada um PIDGE_AGENT=<id> no launch (arquivo isolado por agente) — senão eles enviam como o mesmo canal.');
+  await runDoctor(finalBase, data.key);
+}
+
+// skill install (#110e): persistent Pidge knowledge for Claude Code agents —
+// a skill generated FROM the live manifest (so it can't drift), versioned with
+// manifest_version (re-run to update; whats_new is the changelog).
+async function runSkillInstall() {
+  let res, m;
+  try {
+    res = await fetchT(`${BASE}/api/v1/manifest`, { headers });
+    m = await res.json();
+  } catch (e) {
+    die(`pidge: could not read the manifest: ${e.message}`, 2);
+  }
+  if (res.status !== 200) die(`pidge: manifest read failed (${res.status})`, 2);
+  const table = (m.templates && m.templates.decision_table) || [];
+  const profileTable = (m.profiles && m.profiles.decision_table) || [];
+  const notes = m.notes || [];
+  const exits = (m.cli && m.cli.output) || '';
+  const skill = `---
+name: pidge
+description: Send rich, actionable iPhone notifications to your human and get their decision back (Pidge). Use when finishing long tasks (report), needing a decision/approval, sending FYIs with substance, or anything time-anchored. Also covers reading the human's replies/messages back.
+---
+
+# Pidge — notify your human, get answers back
+
+Generated from manifest v${m.manifest_version} of ${BASE} — re-run \`pidge skill install\` to update (any API response header X-Pidge-Manifest-Version > ${m.manifest_version} means there's news).
+
+All commands: \`npx pidge-cli …\` (Node ≥18; reads ~/.config/pidge/env — no token in context). Not set up? \`pidge doctor\` tells you; onboard with \`pidge setup --claim <code>\` (the human copies the code from the Pidge app).
+
+## Pick the right send (decision table)
+
+${table.map((r) => `- ${r}`).join('\n')}
+
+## How it intrudes (profiles — the human owns them)
+
+${profileTable.map((r) => `- ${r}`).join('\n')}
+
+## The contract
+
+${notes.map((n) => `- ${n}`).join('\n')}
+
+## Getting answers
+
+- \`pidge ask …\` blocks and prints chosen_action JSON; \`pidge wait <cid>\` blocks on an existing send.
+- \`pidge listen\` blocks until the human MESSAGES you from the app (composer) — run it when idle.
+- ${exits}
+
+## Full spec
+
+\`curl $PIDGE_URL/api/v1/manifest -H "Authorization: Bearer $PIDGE_TOKEN"\` — the always-current contract (fields, templates, custom actions, media, threads, realtime).
+`;
+  const dir = path.join(process.cwd(), '.claude', 'skills', 'pidge');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'SKILL.md');
+  fs.writeFileSync(file, skill);
+  console.error(`pidge: skill written to ${file} (manifest v${m.manifest_version}) — your future sessions in this project know Pidge now`);
+  console.log(JSON.stringify({ ok: true, file, manifest_version: m.manifest_version }));
+  process.exit(0);
+}
+
 (async () => {
   switch (command) {
+    case 'setup': {
+      await runSetup(); // exits via runDoctor
+      break;
+    }
+    case 'doctor': {
+      await runDoctor();
+      break;
+    }
+    case 'whoami': {
+      const { res, data } = await fetchWhoami().catch((e) => { die(`pidge: whoami failed (network): ${e.message}`, 2); });
+      checkManifestNews(res);
+      if (res.status !== 200) die(`pidge: whoami failed (${res.status}): ${JSON.stringify(data)}`, 2);
+      console.log(JSON.stringify(data, null, 2));
+      console.error(`pidge: you are canal "${data.channel && data.channel.name}" · ${data.devices ?? '?'} device(s)`);
+      process.exit(0);
+      break;
+    }
+    case 'skill': {
+      if (parsed.positionals[1] !== 'install') die('pidge: usage: pidge skill install', 1);
+      await runSkillInstall();
+      break;
+    }
     case 'notify': {
       const { ok, info, raw } = await doNotify();
       console.log(raw);
@@ -639,7 +922,20 @@ const num = (val, fallback) => (val !== undefined ? parseInt(val, 10) : fallback
       const { ok, info } = await doNotify();
       if (!ok) process.exit(2);
       console.error(`pidge: sent (${info.registered_devices} device(s)) — waiting on ${cid}`);
-      await waitForAnswer(cid, { timeout: num(v.timeout, 600), interval: num(v.interval, 30) });
+      // #132: no --timeout ⇒ obey the template's suggestion from the 201 echo
+      // (human decisions take 30-40 min in the wild; a 600 s default misread
+      // them as silence). Explicit --timeout always wins.
+      let timeout = num(v.timeout, NaN);
+      if (!Number.isFinite(timeout)) {
+        if (info.suggested_ask_timeout) {
+          timeout = info.suggested_ask_timeout;
+          const mins = Math.round(timeout / 60);
+          console.error(`pidge: timeout ${mins} min — suggested by template ${info.template || v.template} (override with --timeout)`);
+        } else {
+          timeout = 600;
+        }
+      }
+      await waitForAnswer(cid, { timeout, interval: num(v.interval, 30) });
       break;
     }
     case 'wait': {
@@ -715,12 +1011,35 @@ const num = (val, fallback) => (val !== undefined ? parseInt(val, 10) : fallback
       // the whole session never had a healthy round-trip (#119).
       // At-least-once: the ack happens AFTER the print — a crash re-serves them;
       // dedupe by id if you've seen one before.
+      // --all (#131): the SINGLE EAR — the queue also serves notification
+      // ANSWERS (kind notification_reply, with a self-contained ref), so a
+      // fire-and-forget notify can't lose its reply. Without --all the original
+      // composer-only contract stands (no double-consumption for ask/wait users).
       const timeout = num(v.timeout, 600);
       let deadline = Date.now() + timeout * 1000;
+      const queueQs = v.all ? '?all=true' : '';
+      // #157 P2 --follow: print+ack a batch and KEEP listening until the
+      // timeout — the supervisor loop without re-spawning a process per batch.
+      let gotAny = false;
+      const followEnd = () => {
+        if (v.follow && gotAny) {
+          console.error(`pidge: --follow window ended after ${timeout}s — batches were delivered`);
+          process.exit(0);
+        }
+        return false;
+      };
 
-      // Print + ack + exit 0 — shared by the WS and polling paths.
+      // Print + ack (+ exit 0 unless --follow) — shared by the WS and polling paths.
       const printAndAck = async (msgs) => {
         console.log(JSON.stringify(msgs, null, 2));
+        // #131: narrate answers so the agent knows WHICH notification spoke back.
+        for (const m of msgs) {
+          if (m.kind === 'notification_reply' && m.ref) {
+            const said = m.text ? `: ${String(m.text).slice(0, 120)}` : '';
+            console.error(`pidge: reply to your notification ${m.ref.correlation_id} ("${m.ref.title}") — ${m.action_id || m.ref.event_kind}${said}`);
+            if (m.truncated) console.error('pidge: that reply hit the server cap (truncated:true) — tell your human the tail was lost');
+          }
+        }
         const upTo = Math.max(...msgs.map((m) => m.id));
         try {
           // fetchT, not fetch: a wedged proxy stalling this ack would otherwise
@@ -738,7 +1057,9 @@ const num = (val, fallback) => (val !== undefined ? parseInt(val, 10) : fallback
         } catch (e) {
           console.error(`pidge: WARNING — ack failed (network: ${e.message}); these messages will be re-served next listen`);
         }
-        process.exit(0);
+        gotAny = true;
+        if (!v.follow) process.exit(0);
+        console.error('pidge: --follow — still listening');
       };
 
       // Realtime path (#118): hold ConversationChannel — the human sees "ouvindo
@@ -750,12 +1071,15 @@ const num = (val, fallback) => (val !== undefined ? parseInt(val, 10) : fallback
           if (draining) return;
           draining = true;
           try {
-            const res = await fetchT(`${BASE}/api/v1/messages`, { headers });
+            const res = await fetchT(`${BASE}/api/v1/messages${queueQs}`, { headers });
             checkManifestNews(res);
             if (res.status === 200) {
               health.ok();
               const msgs = (await res.json().catch(() => ({}))).messages || [];
-              if (msgs.length) { finish('got-messages'); await printAndAck(msgs); }
+              if (msgs.length) {
+                if (!v.follow) finish('got-messages');
+                await printAndAck(msgs);
+              }
             } else if (res.status >= 500) {
               health.fail(`backlog read ${res.status}`);
             }
@@ -766,16 +1090,29 @@ const num = (val, fallback) => (val !== undefined ? parseInt(val, 10) : fallback
           }
         };
         let announced = false;
-        const outcome = await cableSession({
+        const sessions = [cableSession({
           channel: 'ConversationChannel',
           deadline,
           onUp: (finish) => {
-            if (!announced) { announced = true; console.error('pidge: listening over the realtime socket (the human sees "ouvindo agora")'); }
+            if (!announced) { announced = true; console.error(`pidge: listening over the realtime socket${v.all ? ' — single ear: composer + notification answers (#131)' : ''} (the human sees "ouvindo agora")`); }
             drain(finish);
           },
           onFrame: (m, finish) => { if (m.type === 'message') drain(finish); },
-        });
+        })];
+        // --all (#131): answers broadcast on InboxChannel, not Conversation — a
+        // second subscription wakes the same HTTP drain (the queue is the ledger;
+        // the loser session leaks until exit, harmless in a one-shot process).
+        if (v.all) {
+          sessions.push(cableSession({
+            channel: 'InboxChannel',
+            deadline,
+            onUp: (finish) => drain(finish),
+            onFrame: (m, finish) => { if (m.type === 'event' && m.responded) drain(finish); },
+          }));
+        }
+        const outcome = await Promise.race(sessions);
         if (outcome === 'deadline') {
+          followEnd();
           health.exitTimeout(`timed out after ${timeout}s — no message from the human`);
         }
         if (outcome === 'got-messages') {
@@ -788,7 +1125,10 @@ const num = (val, fallback) => (val !== undefined ? parseInt(val, 10) : fallback
         const waitS = health.degraded ? 0 : Math.max(0, Math.min(25, Math.ceil((deadline - Date.now()) / 1000)));
         const askedAt = Date.now();
         try {
-          const res = await fetchT(`${BASE}/api/v1/messages${waitS > 0 ? `?wait=${waitS}` : ''}`, { headers }, (waitS + 10) * 1000);
+          const qs = new URLSearchParams();
+          if (waitS > 0) qs.set('wait', String(waitS));
+          if (v.all) qs.set('all', 'true');
+          const res = await fetchT(`${BASE}/api/v1/messages${qs.size ? `?${qs}` : ''}`, { headers }, (waitS + 10) * 1000);
           checkManifestNews(res);
           if (res.status === 200) {
             health.ok();
@@ -805,6 +1145,7 @@ const num = (val, fallback) => (val !== undefined ? parseInt(val, 10) : fallback
           health.fail(`network: ${e.message}`);
         }
         if (Date.now() >= deadline) {
+          followEnd();
           health.exitTimeout(`timed out after ${timeout}s — no message from the human`);
         }
         const pace = health.degraded ? DEGRADED_INTERVAL_S : num(v.interval, 5);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pidge-cli",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Send rich, actionable iPhone notifications to a human and block until they answer. Built for AI agents.",
   "keywords": [
     "pidge",