pidge-cli 0.7.0 → 0.8.1

package/README.md

@@ -11,19 +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.7.0 — the claim flow)
+## 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, writes ~/.config/pidge/env (chmod 600)
-#   and runs `pidge doctor`. The secret never appears on screen or in any chat.
+# → 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

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+/, '');
@@ -107,14 +122,21 @@ const OPTIONS = {
   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 in
-                                          ~/.config/pidge/env (chmod 600), run doctor
+                                          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)
@@ -188,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);
@@ -241,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 = 24;
+const KNOWN_MANIFEST_VERSION = 26;
 let newsWarned = false;
 function checkManifestNews(res) {
   const v = parseInt(res.headers.get('x-pidge-manifest-version') || '0', 10);
@@ -647,13 +673,16 @@ 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_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';
-  if (FILE_ENV.PIDGE_TOKEN) return CONFIG_FILE;
+  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;
 }
 
@@ -669,8 +698,11 @@ async function fetchWhoami(base = BASE, token = TOKEN) {
 
 // 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
+async function runDoctor(base = BASE, token = TOKEN, sourceLabel = null) {
+  // sourceLabel is passed by setup (it knows exactly where the key went —
+  // a per-agent file, the shared file, or NOWHERE for --print); the bare
+  // `doctor` command computes it from the env/file precedence.
+  const source = sourceLabel || (token === TOKEN ? tokenSource() : CONFIG_FILE);
   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);
@@ -709,6 +741,8 @@ async function runDoctor(base = BASE, token = TOKEN) {
   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);
@@ -721,6 +755,28 @@ 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`, {
@@ -737,11 +793,30 @@ async function runSetup() {
     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, 'fresh claim (per-agent env — not stored on disk)');
+    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: configured for canal "${data.channel && data.channel.name}" — key stored in ${CONFIG_FILE} (chmod 600, never displayed)`);
-  await runDoctor(finalBase, data.key);
+  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, CONFIG_FILE);
 }
 
 // skill install (#110e): persistent Pidge knowledge for Claude Code agents —

package/package.json

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