pidge-cli 0.11.0 → 0.11.1

package/README.md

@@ -33,6 +33,13 @@ then gets the answer as JSON — no webhook, no polling loop to write.
 > stdout now carries only the `operating_contract`, so the key never lands in an agent's
 > transcript/logs.
 >
+> **v0.11.1** (Pidge manifest v31): **`pidge doctor` now probes the realtime path** (#171) —
+> after the HTTP checks it opens a quick `/cable` subscription and reports `realtime: ok` or
+> `realtime: INDISPONÍVEL` (the #119 failure class an HTTP-only doctor couldn't see: an edge
+> killing held responses, a proxy refusing the WebSocket). Exit stays `0` — an unavailable WS
+> just degrades `listen` to polling — but you learn it BEFORE the first deaf listen. The doctor
+> hint now leads with `pidge hello`, and the version nudge knows v31 (#229).
+>
 > **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
@@ -138,7 +145,7 @@ npx pidge-cli notify --title "Relatório" --file ./relatorio.xlsx
 | `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. |
+| `doctor` | Validate the setup **without exposing secrets**: env source, server reachable, key valid, **honest device reach**, channel ownership, and (**v0.11.1, #171**) a **realtime probe** (`realtime: ok / INDISPONÍVEL` — exit stays 0; an unavailable WS just degrades `listen` to polling). 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. |
 | `--version` | Print the CLI version. |

package/bin/pidge.js

@@ -302,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 = 30;
+const KNOWN_MANIFEST_VERSION = 31;
 let newsWarned = false;
 function checkManifestNews(res) {
   const v = parseInt(res.headers.get('x-pidge-manifest-version') || '0', 10);
@@ -381,10 +381,10 @@ function wantRealtime() {
 // The server pings every ~3 s — that heartbeat is the liveness check (silence
 // >15 s ⇒ the socket is dead even if TCP hasn't noticed; close → caller
 // reconnects). Returns {close()} or null if the constructor itself failed.
-function cableSubscribe({ channel, onUp, onFrame, onDown }) {
+function cableSubscribe({ channel, onUp, onFrame, onDown, base = BASE, token = TOKEN }) {
   let ws;
   try {
-    ws = new WebSocket(BASE.replace(/^http/, 'ws') + '/cable', ['actioncable-v1-json', TOKEN]);
+    ws = new WebSocket(base.replace(/^http/, 'ws') + '/cable', ['actioncable-v1-json', token]);
   } catch (e) { onDown(e.message); return null; }
   const identifier = JSON.stringify({ channel });
   let lastBeat = Date.now();
@@ -452,6 +452,41 @@ async function cableSession({ channel, deadline, onUp, onFrame }) {
   return 'deadline';
 }
 
+// #171: doctor's realtime probe — the failure class an HTTP-only doctor can't
+// see (#119: an edge killing held responses, a proxy refusing the upgrade). A
+// green HTTP doctor can coexist with a `listen` that's deaf over the socket.
+// Open ONE ConversationChannel subscription on /cable (reusing cableSubscribe —
+// the same client `listen` holds), wait for confirm_subscription, close — all
+// within ≤5 s. Degrade is the CONTRACT, not a failure: an unavailable WS just
+// means `listen` polls (works, less instant), so this NEVER changes the exit
+// code — it only lets the agent KNOW before the first deaf listen. Resolves
+// {ok, ms} | {ok:false, reason} | {skipped:true} (Node <22 has no native
+// WebSocket — same gate as wantRealtime, :373).
+function probeRealtime(base, token) {
+  if (typeof WebSocket !== 'function') return Promise.resolve({ skipped: true });
+  return new Promise((resolve) => {
+    const started = Date.now();
+    let settled = false;
+    let sub = null;
+    const done = (result) => {
+      if (settled) return; settled = true;
+      clearTimeout(guard);
+      if (sub) sub.close();
+      resolve(result);
+    };
+    const guard = setTimeout(() => done({ ok: false, reason: 'no confirm_subscription within 5s' }), 5000);
+    sub = cableSubscribe({
+      channel: 'ConversationChannel',
+      base,
+      token,
+      onUp: () => done({ ok: true, ms: Date.now() - started }),
+      onFrame: () => { /* a stray frame during the probe is irrelevant */ },
+      onDown: (why) => done({ ok: false, reason: why }),
+    });
+    if (!sub) done({ ok: false, reason: 'WebSocket constructor failed' });
+  });
+}
+
 // Map CLI flags → the /notify JSON body, including only what was provided.
 function buildBody() {
   if (!v.title) die('pidge: --title is required', 1);
@@ -1093,8 +1128,25 @@ async function runDoctor(base = BASE, token = TOKEN, sourceLabel = null) {
     console.error('pidge doctor: BROKEN (exit 2) — devices exist but 0 are reachable (all disabled or on the wrong APNs environment): a send reaches nobody.');
     process.exit(2);
   }
-  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 }));
+  // #171: probe the realtime path (the #119 failure class an HTTP-only doctor
+  // misses). Exit stays 0 either way — an unavailable WS degrades to polling.
+  const rt = await probeRealtime(base, token);
+  let realtime;
+  if (rt.skipped) {
+    realtime = 'skipped';
+    console.error('pidge doctor: realtime: skipped — this Node lacks a native WebSocket (need Node ≥22); `listen` will poll. Upgrade Node for instant delivery.');
+  } else if (rt.ok) {
+    realtime = 'ok';
+    console.error(`pidge doctor: realtime: ok (ws connect + subscribe em ${rt.ms}ms)`);
+  } else {
+    realtime = 'unavailable';
+    console.error(`pidge doctor: realtime: INDISPONÍVEL — ${rt.reason}. O \`listen\` degrada pra polling (funciona, menos instantâneo); use --no-realtime pra fixar o piso.`);
+  }
+  // #229: lead with `pidge hello` — the first-contact WOW (send + wait in one),
+  // the same debut the /agent-setup guide leads with. It's a thin wrapper over
+  // `ask --template onboarding` (the underlying mechanism, if you need it raw).
+  console.error('pidge doctor: all good — try: pidge hello   (first-contact WOW — send + wait in one; equivalent: pidge ask --template onboarding)');
+  console.log(JSON.stringify({ ok: true, base_url: base, channel: data.channel, devices, manifest_version: data.manifest_version, realtime }));
   process.exit(0);
 }
 

package/package.json

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