pidge-cli 0.9.2 → 0.11.0

package/README.md

@@ -20,7 +20,7 @@ then gets the answer as JSON — no webhook, no polling loop to write.
 > reports honest device reach + warns on a silent key swap.
 >
 > **v0.9.1** (Pidge manifest v28): full spec conformance — `setup` now **declares your
-> operating contract** (`listen_mode`, default `turn_based`; `--listen-mode always_on`
+> operating contract** (`listen_mode`, default `turn_based`; `--listen-mode persistent`
 > for a supervisor); `contract set` rejects an unknown key/bad value **locally**;
 > `whoami` reports honest device reach and SHOUTS on a silent key swap (not just
 > `doctor`); `doctor` **exits 2** when devices exist but none are reachable; `--follow`
@@ -32,6 +32,20 @@ then gets the answer as JSON — no webhook, no polling loop to write.
 > **v0.9.2**: `contract set` no longer prints the channel JSON (which echoed the key) —
 > stdout now carries only the `operating_contract`, so the key never lands in an agent's
 > transcript/logs.
+>
+> **v0.11.0** (Pidge manifest v30): the **first-contact WOW** (#217). New **`pidge hello`** —
+> your channel's debut handshake, narrated LIVE on the lock screen by a server-driven 3-stage
+> Live Activity (Conectando → toque para confirmar → Concluído ✓) so your human *sees* the
+> agent→human→agent loop close. Send + wait in one; run it as your first contact on a fresh
+> channel. (It's a thin `ask --template onboarding` wrapper — that path already works on v0.10.0.)
+>
+> **v0.10.0** (Pidge manifest v29): the onboarding-close batch. **`pidge selftest`** proves
+> your listener works by ROUND-TRIP (#205) — fire a nonce, run the listener, confirm it
+> picks it up + acks in time (PASS exit 0 / FAIL exit 2 with the likely cause). `listen_mode`
+> grew to **`turn_based | persistent | external_daemon`** (`always_on` is a tolerated alias),
+> so you declare the mode that matches your runtime. And `listen` installs an **orphan-zombie
+> guard**: a background listener whose parent (harness) dies exits instead of consuming the
+> channel forever. The full operating guide now lives at `<base>/agent-setup`.
 
 ## Setup in one command (v0.8.0 — the claim flow)
 
@@ -113,6 +127,7 @@ npx pidge-cli notify --title "Relatório" --file ./relatorio.xlsx
 
 | Command | What it does |
 |---|---|
+| `hello` | **v0.11.0 (#217):** your channel's **first-contact WOW** — send the onboarding handshake **and block** until the human confirms. The server narrates a 3-stage Live Activity on the lock screen (Conectando → toque para confirmar → Concluído ✓) so they *see* the agent→human→agent loop close. Run it as your **first** contact on a fresh channel. A thin `ask --template onboarding` wrapper with friendly default copy. |
 | `ask` | Send a notification **and block** until the human answers; prints the chosen action JSON. The default for agents. |
 | `notify` | Send only. Prints the raw 201 JSON; the `correlation_id` + warnings go to stderr. |
 | `wait <correlation_id>` | Block on an already-sent notification until it's answered. |
@@ -120,8 +135,9 @@ npx pidge-cli notify --title "Relatório" --file ./relatorio.xlsx
 | `inbox` | What you sent: list, `--pending` slice, or `--summary` (counts + answer latency). |
 | `listen` | Block until the human **messages you** from the app; prints them, exits `0`. One-shot — loop it. **v0.9.0:** a read message is DELIVERED (gray ✓✓), **not** done — `ack` it after the work (`--ack-on-read` for the old immediate-consume). |
 | `ack --up-to <id>` | **v0.9.0:** mark messages PROCESSED (green ✓✓) **after** you've handled them; `--renew` heartbeats the visibility-timeout lease on a long task. |
-| `contract set <k>=<v>` / `contract show` | **v0.9.0:** DECLARE how you operate (`keep_connection_alive`, `mirror_in_origin_session`, `listen_mode=turn_based\|always_on`, `quiet_when_idle`). **Advisory, never policy** — you declare, the human registers their expectation and *sees* if you honor it; Pidge enforces nothing. An unknown key/bad value is rejected locally (exit 1). |
-| `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. **v0.9.0** also claims channel ownership so `doctor` can warn on a silent key swap. **v0.9.1** declares your `operating_contract` (default `listen_mode=turn_based`; `--listen-mode always_on` for a supervisor). |
+| `contract set <k>=<v>` / `contract show` | **v0.9.0:** DECLARE how you operate (`keep_connection_alive`, `mirror_in_origin_session`, `listen_mode=turn_based\|persistent\|external_daemon`, `quiet_when_idle`). **Advisory, never policy** — you declare, the human registers their expectation and *sees* if you honor it; Pidge enforces nothing. An unknown key/bad value is rejected locally (exit 1). |
+| `selftest [--window N]` | **v0.10.0 (#205):** prove your listener works by ROUND-TRIP — fire a nonce, run the listener, confirm it picks it up + acks in time. PASS exit `0` / FAIL exit `2` with the likely cause (timeout / orphan / transport). Run it as the last onboarding step + whenever sends seem to go unheard. |
+| `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. **v0.9.0** also claims channel ownership so `doctor` can warn on a silent key swap. **v0.9.1+** declares your `operating_contract` (default `listen_mode=turn_based`; `--listen-mode persistent\|external_daemon` for a supervisor/daemon). |
 | `doctor` | Validate the setup **without exposing secrets**: env source, server reachable, key valid, **honest device reach**, channel ownership. 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. |

package/bin/pidge.js

@@ -138,6 +138,7 @@ const OPTIONS = {
   ids: { type: 'string' },                     // ack: process this comma-list of ids
   renew: { type: 'boolean' },                  // ack: heartbeat the visibility-timeout lease (state=delivered)
   'ack-on-read': { type: 'boolean' },          // listen: restore the pre-0.9 immediate-consume
+  window: { type: 'string' },                  // selftest: reachability window in seconds (default 30)
 };
 
 const USAGE = `pidge — send an iPhone notification to a human and block until they answer.
@@ -151,11 +152,15 @@ USAGE
                                                    (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
-                                          --listen-mode turn_based|always_on  declare how you
-                                                   operate (#182; default turn_based)
+                                          --listen-mode turn_based|persistent|external_daemon
+                                                   declare how you operate (#182; default turn_based)
   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 hello  [options]                  FIRST-CONTACT WOW (#217): your channel's debut handshake,
+                                          narrated LIVE on the lock screen by a 3-stage Live Activity
+                                          (Conectando → toque para confirmar → Concluído ✓). send + wait
+                                          in one — run it as your FIRST contact on a fresh channel.
   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
@@ -174,8 +179,13 @@ USAGE
                                           --renew heartbeats the lease on a long task (state=delivered)
   pidge contract set <key>=<value> | contract show
                                           DECLARE how you operate (#182): keep_connection_alive,
-                                          mirror_in_origin_session, listen_mode=turn_based|always_on,
-                                          quiet_when_idle. A CONTRACT, never policy (the human can force it).
+                                          mirror_in_origin_session,
+                                          listen_mode=turn_based|persistent|external_daemon,
+                                          quiet_when_idle. ADVISORY, never policy (the human SEES if you honor it).
+  pidge selftest [--window N]             prove your listener works by ROUND-TRIP (#205): fire a nonce,
+                                          run the listener, confirm it picks it up + acks in time.
+                                          PASS exit 0 / FAIL exit 2 (with the likely cause). Run it as the
+                                          last onboarding step + whenever sends seem to go unheard.
   pidge skill install                     write .claude/skills/pidge/SKILL.md generated from the
                                           live manifest (persistent Pidge knowledge for Claude Code)
   pidge --version                         print the CLI version
@@ -292,7 +302,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 = 28;
+const KNOWN_MANIFEST_VERSION = 30;
 let newsWarned = false;
 function checkManifestNews(res) {
   const v = parseInt(res.headers.get('x-pidge-manifest-version') || '0', 10);
@@ -825,9 +835,11 @@ async function declareOperatingContract(base, token, channelId) {
   if (!channelId) return null;
   const mode = v['listen-mode'];
   let contract;
-  if (mode === 'always_on') contract = { listen_mode: 'always_on', keep_connection_alive: true };
-  else if (!mode || mode === 'turn_based') contract = { listen_mode: 'turn_based', keep_connection_alive: false };
-  else { console.error(`pidge: --listen-mode must be turn_based or always_on (got "${mode}") — skipping the contract declaration`); return null; }
+  // turn_based holds no connection; persistent/external_daemon/always_on all keep one
+  // alive (a supervisor or daemon holding the listen). §3c.
+  if (!mode || mode === 'turn_based') contract = { listen_mode: 'turn_based', keep_connection_alive: false };
+  else if (['persistent', 'external_daemon', 'always_on'].includes(mode)) contract = { listen_mode: mode, keep_connection_alive: true };
+  else { console.error(`pidge: --listen-mode must be turn_based | persistent | external_daemon (got "${mode}") — skipping the contract declaration`); return null; }
   try {
     const res = await fetchT(`${base}/api/v1/channels/${channelId}`, {
       method: 'PATCH',
@@ -852,7 +864,10 @@ async function declareOperatingContract(base, token, channelId) {
 const OPERATING_CONTRACT_SPEC = {
   keep_connection_alive: 'boolean',
   mirror_in_origin_session: 'boolean',
-  listen_mode: ['turn_based', 'always_on'],
+  // §3c: match your RUNTIME. turn_based (no event loop — block-and-exit) · persistent
+  // (a supervisor holding the socket, --follow) · external_daemon (a daemon outside the
+  // session). always_on stays as a tolerated deprecated alias of persistent.
+  listen_mode: ['turn_based', 'persistent', 'external_daemon', 'always_on'],
   quiet_when_idle: 'boolean',
 };
 // Coerce + validate one operating_contract value against the allowlist. Returns
@@ -934,6 +949,92 @@ async function runContract() {
   process.exit(0);
 }
 
+// Orphan-zombie guard (§3c pitfall #1): when `npx pidge-cli listen` is launched as a
+// background task and the harness later kills the npx wrapper, the node LEAF can
+// orphan and keep consuming the channel forever without ever waking the agent. A
+// long-running listen polls its parent: if it had a real parent at startup and that
+// parent dies (re-parented to pid 1), it exits so it stops eating the queue. Skipped
+// when started detached (ppid 1 already — e.g. an external_daemon under systemd).
+function installOrphanWatchdog() {
+  if (process.ppid === 1) return; // already detached — nothing to orphan from
+  const t = setInterval(() => {
+    if (process.ppid === 1) {
+      console.error('pidge: parent process died — exiting so I stop consuming the channel (orphan-zombie guard). Relaunch from your harness.');
+      process.exit(0);
+    }
+  }, 2000);
+  if (t.unref) t.unref(); // never keep the process alive just for the watchdog
+}
+
+// selftest (#205): prove the listener works by ROUND-TRIP, not prose. Fire a nonce
+// onto our own queue, run the listener (long-poll floor — the reachability path) for
+// the window, ack the nonce, then read the server's verdict. PASS = it round-tripped
+// in time. FAIL = the server's window verdict + a likely CAUSE the server can't see
+// (the orphan/`&`/transport bugs). Only the nonce is acked (ids:[id]) and any real
+// messages briefly served are re-served fast (lease=60), so it doesn't eat the queue.
+async function doSelftest() {
+  // Guard the parse: a non-numeric --window (e.g. "30s", a typo) must NOT become NaN
+  // — that would make the deadline NaN, skip the poll loop entirely, and mis-report a
+  // perfectly fine listener as "orphaned/dead" (the most misleading failure possible).
+  const rawWindow = num(v.window, 30);
+  const windowS = Math.max(5, Math.min(120, Number.isFinite(rawWindow) ? rawWindow : 30));
+  let fired;
+  try {
+    const res = await fetchT(`${BASE}/api/v1/selftest`, {
+      method: 'POST', headers, body: JSON.stringify({ window_seconds: windowS }),
+    });
+    checkManifestNews(res);
+    if (res.status < 200 || res.status >= 300) die(`pidge: selftest: the server refused (${res.status}) — is your key valid? try \`pidge doctor\``, 2);
+    fired = await res.json();
+  } catch (e) {
+    die(`pidge: selftest failed (network): ${e.message}`, 2);
+  }
+  const id = fired.id;
+  console.error(`pidge: self-test fired (id ${id}) — listening up to ${windowS}s to prove the round-trip (a nonce on your own queue; PASS = your listener picks it up + acks it in time)`);
+
+  const deadline = Date.now() + windowS * 1000;
+  let sawNonce = false;
+  while (Date.now() < deadline && !sawNonce) {
+    const waitS = Math.max(0, Math.min(25, Math.ceil((deadline - Date.now()) / 1000)));
+    const askedAt = Date.now();
+    try {
+      const qs = new URLSearchParams({ all: 'true', lease: '60' });
+      if (waitS > 0) qs.set('wait', String(waitS));
+      const res = await fetchT(`${BASE}/api/v1/messages?${qs}`, { headers }, (waitS + 10) * 1000);
+      if (res.status === 200) {
+        const msgs = (await res.json().catch(() => ({}))).messages || [];
+        if (msgs.some((m) => m.id === id)) {
+          sawNonce = true;
+          // ack ONLY the nonce (ids, not up_to) so real pending messages aren't consumed.
+          try { await fetchT(`${BASE}/api/v1/messages/ack`, { method: 'POST', headers, body: JSON.stringify({ ids: [ id ] }) }); } catch { /* server verdict is the source of truth */ }
+        }
+      }
+    } catch { /* keep trying until the deadline */ }
+    // pace: if the poll returned fast (the server didn't actually hold ?wait=), don't busy-spin.
+    if (!sawNonce && Date.now() - askedAt < 1000 && Date.now() < deadline) await sleep(1000);
+  }
+
+  let verdict = {};
+  try {
+    const res = await fetchT(`${BASE}/api/v1/selftest/${id}`, { headers });
+    if (res.status === 200) verdict = await res.json();
+  } catch (e) {
+    die(`pidge: selftest: couldn't read the result (${e.message})`, 2);
+  }
+
+  if (verdict.status === 'passed') {
+    console.error('pidge: ✅ SELF-TEST PASSED — your listener received the nonce and acked it in time. Reachability proven.');
+    console.log(JSON.stringify({ status: 'passed', id, window_seconds: windowS }));
+    process.exit(0);
+  }
+  const cause = sawNonce
+    ? 'your listener received the nonce but acked it AFTER the window — a slow/flaky transport, or the work between read and ack took too long. Widen --window, or make your real listen loop ack sooner.'
+    : 'your listener never received the nonce in the window — likely an ORPHANED/detached listener (an npx leaf left running, or a loose `&`), or a dead transport. Run ONE single-process listener as a tracked background task; `pidge listen --no-realtime` is the robust floor.';
+  console.error(`pidge: ❌ SELF-TEST FAILED — ${cause}`);
+  console.log(JSON.stringify({ status: verdict.status || 'failed', id, saw_nonce: sawNonce }));
+  process.exit(2);
+}
+
 // 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, sourceLabel = null) {
@@ -1176,6 +1277,31 @@ ${notes.map((n) => `- ${n}`).join('\n')}
       process.exit(ok ? 0 : 2);
       break;
     }
+    case 'hello': {
+      // #217 — the first-contact WOW: fire the onboarding handshake and block on
+      // your human's confirmation. The SERVER narrates a 3-stage Live Activity on
+      // the lock screen (Conectando → toque para confirmar → Concluído ✓) so your
+      // human SEES the agent→human→agent loop close. One command: send + wait.
+      // Run it as your FIRST contact on a fresh channel. A thin wrapper over `ask`:
+      // it just pins template=onboarding and friendly default copy.
+      if (v.profile === 'tracking')
+        die('pidge: `hello --profile tracking` makes no sense — the handshake waits for a confirmation, which tracking (Live-Activity-only) never produces', 1);
+      v.template = 'onboarding';
+      if (v.title === undefined) v.title = 'Seu agente está pronto 🐦';
+      if (v.body === undefined) v.body = 'Toque em Feito ✓ para confirmar que me recebeu — você vai ver o teste fechar na tela.';
+      const cid = v['correlation-id'] || crypto.randomUUID();
+      v['correlation-id'] = cid;
+      console.error(`pidge: correlation_id=${cid}`);
+      const { ok, info } = await doNotify();
+      if (!ok) process.exit(2);
+      console.error(`pidge: WOW sent (${info.registered_devices} device(s)) — watch the lock screen narrate the handshake; waiting for your human to confirm on ${cid}`);
+      // No --timeout ⇒ obey the template's suggestion from the 201 echo (onboarding
+      // = 3600 s); explicit --timeout always wins.
+      let timeout = num(v.timeout, NaN);
+      if (!Number.isFinite(timeout)) timeout = info.suggested_ask_timeout || 3600;
+      await waitForAnswer(cid, { timeout, interval: num(v.interval, 30) });
+      break;
+    }
     case 'ask': {
       // Send, then block on the answer in one shot. stdout = ONLY chosen_action JSON.
       // tracking is Live-Activity-only: it NEVER produces a chosen_action, so an ask
@@ -1271,6 +1397,12 @@ ${notes.map((n) => `- ${n}`).join('\n')}
       await runContract();
       break;
     }
+    case 'selftest': {
+      // #205: prove reachability by round-trip. Fire a nonce, run the listener,
+      // confirm it picks it up + acks in time. PASS exit 0 / FAIL exit 2.
+      await doSelftest();
+      break;
+    }
     case 'inbox': {
       // #83: what this channel sent — the list (default), the pending slice
       // (--pending = delivered + still unanswered) or the one-call summary
@@ -1318,6 +1450,7 @@ ${notes.map((n) => `- ${n}`).join('\n')}
       // 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).
+      installOrphanWatchdog(); // §3c: a killed-parent orphan exits instead of eating the queue
       const timeout = num(v.timeout, 600);
       let deadline = Date.now() + timeout * 1000;
       const queueQs = v.all ? '?all=true' : '';

package/package.json

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