pidge-cli 0.6.0 → 0.7.0

package/README.md

@@ -11,6 +11,19 @@ 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.7.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, writes ~/.config/pidge/env (chmod 600)
+#   and runs `pidge doctor`. The secret never appears on screen or in any chat.
+
+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)
+```
+
 ## Use it (no install — via npx)
 
 ```bash
@@ -55,6 +68,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

@@ -90,6 +90,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 +103,35 @@ 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' },
 };
 
 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 in
+                                          ~/.config/pidge/env (chmod 600), run doctor
+  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)
@@ -124,7 +143,9 @@ REALTIME (#118)
   --realtime      force WS (warns + falls back to polling if unavailable)
   --no-realtime   polling only (the ?wait= long-poll, capped 25 s server-side)
   Degrade ladder, narrated on stderr: WS → ?wait= long-poll → plain GETs every
-  ~45 s after 3 consecutive failures on held polls (#119).
+  ~45 s after 3 consecutive failures on held polls (#119). Degrade is STICKY for
+  the session (we can't probe held-poll health without re-paying the failure) —
+  re-invoke the command to retry the fast path.
 
 OPTIONS (notify / ask)
   --title TEXT             (required) the headline
@@ -155,6 +176,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
@@ -195,15 +219,29 @@ 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' };
 
+// fetch with a hard timeout (#119 review): a wedged edge proxy can stall even a
+// short POST forever, and a hung ack on the realtime listen path would pin the
+// process past its deadline — worse than going deaf. NOTHING in this CLI should
+// await a fetch that can't time out. A held long-poll passes its own (larger)
+// timeout; everything else uses the 30 s default.
+function fetchT(url, opts = {}, timeoutMs = 30000) {
+  const ms = parseInt(process.env.PIDGE_FETCH_TIMEOUT || '', 10) || timeoutMs; // test/ops hook
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(new Error(`timeout after ${ms}ms`)), ms);
+  return fetch(url, { ...opts, signal: ctl.signal }).finally(() => clearTimeout(t));
+}
+
 // 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 = 24;
 let newsWarned = false;
 function checkManifestNews(res) {
   const v = parseInt(res.headers.get('x-pidge-manifest-version') || '0', 10);
@@ -331,9 +369,10 @@ async function cableSession({ channel, deadline, onUp, onFrame }) {
     if (outcome === 'deadline') return 'deadline';
     if (!outcome.startsWith('down: ')) return outcome; // caller-driven finish (e.g. 'answered')
     wsFails++;
-    if (wsFails >= 4) return 'ws-unavailable';
+    const MAX_WS_FAILS = 4; // then fall back to polling for the rest of the session
+    if (wsFails >= MAX_WS_FAILS) return 'ws-unavailable';
     const backoff = Math.min(2000 * wsFails, 10000);
-    console.error(`pidge: realtime socket ${outcome.replace('down: ', '')} — reconnecting in ${Math.round(backoff / 1000)}s (attempt ${wsFails}/3)`);
+    console.error(`pidge: realtime socket ${outcome.replace('down: ', '')} — reconnecting in ${Math.round(backoff / 1000)}s (attempt ${wsFails}/${MAX_WS_FAILS})`);
     await sleep(backoff);
   }
   return 'deadline';
@@ -357,6 +396,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);
 
@@ -364,6 +404,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;
@@ -499,7 +544,7 @@ async function doWait(cid, { timeout, interval }) {
     const url = `${BASE}/api/v1/notifications/${encodeURIComponent(cid)}${waitS > 0 ? `?wait=${waitS}` : ''}`;
     const askedAt = Date.now();
     try {
-      const res = await fetch(url, { headers });
+      const res = await fetchT(url, { headers }, (waitS + 10) * 1000);
       checkManifestNews(res);
       if (res.status === 200) {
         health.ok();
@@ -552,7 +597,7 @@ async function realtimeWait(cid, { timeout, interval }) {
   const deadline = Date.now() + timeout * 1000;
   const answered = async () => {
     try {
-      const res = await fetch(`${BASE}/api/v1/notifications/${encodeURIComponent(cid)}`, { headers });
+      const res = await fetchT(`${BASE}/api/v1/notifications/${encodeURIComponent(cid)}`, { headers });
       if (res.status !== 200) return false;
       const data = await res.json().catch(() => ({}));
       return !!(data.responded && data.chosen_action && data.chosen_action.kind !== 'snoozed');
@@ -598,8 +643,189 @@ 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 = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'pidge');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'env');
+
+// 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';
+  if (FILE_ENV.PIDGE_TOKEN) return CONFIG_FILE;
+  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');
+  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(/\/+$/, '');
+  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(/\/+$/, '');
+  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: configured for canal "${data.channel && data.channel.name}" — key stored in ${CONFIG_FILE} (chmod 600, never displayed)`);
+  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);
@@ -624,7 +850,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': {
@@ -700,15 +939,42 @@ 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 {
-          const ack = await fetch(`${BASE}/api/v1/messages/ack`, {
+          // fetchT, not fetch: a wedged proxy stalling this ack would otherwise
+          // pin the process forever (the WS drain path awaits printAndAck's exit
+          // with no deadline) — messages are already printed, so a timeout here
+          // just re-serves them next listen (at-least-once).
+          const ack = await fetchT(`${BASE}/api/v1/messages/ack`, {
             method: 'POST', headers, body: JSON.stringify({ up_to: upTo }),
           });
           if (ack.status >= 200 && ack.status < 300) {
@@ -719,7 +985,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
@@ -731,12 +999,15 @@ const num = (val, fallback) => (val !== undefined ? parseInt(val, 10) : fallback
           if (draining) return;
           draining = true;
           try {
-            const res = await fetch(`${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}`);
             }
@@ -747,16 +1018,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') {
@@ -769,7 +1053,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 fetch(`${BASE}/api/v1/messages${waitS > 0 ? `?wait=${waitS}` : ''}`, { headers });
+          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();
@@ -786,6 +1073,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.0",
+  "version": "0.7.0",
   "description": "Send rich, actionable iPhone notifications to a human and block until they answer. Built for AI agents.",
   "keywords": [
     "pidge",