@pingroom/cli 0.7.2 → 0.7.3

package/lib/commands/connect.js

@@ -0,0 +1,726 @@
+// Connecting: QR pairing, the email fallback, Agent Inbox activation, and the
+// bare `pingroom` status/prompt. Everything a human touches once and then never
+// thinks about again.
+
+import { EXIT } from '../constants.js';
+import {
+  fail, isInteractive, isJsonObject, isNonEmptyString, isNullableString, sleep, stripControlChars,
+} from '../util.js';
+import { HELP, commandHelp } from '../help.js';
+import { apiDetail, httpJson, requireSafeUrl, retryAfterMs } from '../http.js';
+import {
+  credentialsPath, readStoredCredential, resolveApiBase, resolveRoom, saveCredential,
+} from '../config.js';
+
+// --- connecting (pairing + email fallback) ---------------------------------
+//
+// Wire contract: AGENT_PAIRING_SPEC.md. The shape is deliberately one gesture —
+// scanning the QR is where the human picks BOTH the account and the delivery
+// room, so an agent can never end up connected with nobody's say-so about where
+// it pings. There is no `login` subcommand: `pingroom` resolves the state.
+
+// The scopes this CLI can actually use, one per command surface. Requested at
+// registration so the approval screen shows exactly what it is granting; the
+// server intersects, so asking for less is always safe and asking for more than
+// the human approves is impossible.
+const CLI_SCOPES = [
+  'pingroom:rooms:read',        // resolve/display the connected room
+  'pingroom:broadcast:send',    // ping
+  'pingroom:attachments:write', // ping --attach (the upload leg)
+  'pingroom:notifications:read',// listen
+  'pingroom:questions:ask',     // ask / watch / cancel / list, and the hook
+  'pingroom:handoffs:create',   // handoff / handoffs
+  'pingroom:live:write',        // live start/update/end/get
+];
+
+// What the human reads on the approval screen. A product name, not a package
+// id: the phone shows it verbatim ("PingRoom CLI wants to connect").
+const AGENT_LABEL = 'PingRoom CLI';
+// A connect command should prove the phone round-trip, but it must not hold a
+// terminal for the onboarding Question's full 24-hour server TTL. The Question
+// remains answerable after this local deadline and the credential is already
+// durable before the wait begins.
+const ACTIVATION_MAX_WAIT_MS = 2 * 60 * 1000;
+// The wait route is limited to 30 requests/minute. Keep immediate pending or
+// answered-without-completion observations safely below that ceiling while a
+// mixed-version or commit-propagation race is still being reconciled.
+const ACTIVATION_MIN_POLL_INTERVAL_MS = 2100;
+
+function activationMaxWaitMs() {
+  // Keep production fixed at two minutes. The guarded override lets the real
+  // subprocess tests exercise deadline behavior without holding the suite for
+  // two minutes; it is ignored outside NODE_ENV=test.
+  if (process.env.NODE_ENV === 'test') {
+    const testValue = Number(process.env.PINGROOM_INTERNAL_ACTIVATION_TIMEOUT_MS);
+    if (Number.isInteger(testValue) && testValue > 0 && testValue <= ACTIVATION_MAX_WAIT_MS) {
+      return testValue;
+    }
+  }
+  return ACTIVATION_MAX_WAIT_MS;
+}
+
+// Widest QR we render (compact half-block form of a ~110-char pair URL is 39
+// columns). Anything narrower would wrap and become unscannable, so we print
+// the URL alone instead of a broken QR.
+const QR_MIN_COLUMNS = 41;
+
+/**
+ * Draw the pair URL as a scannable QR. Returns false when it could not — a too
+ * narrow terminal, or the optional dependency being absent (someone vendored
+ * just bin/) — and the caller falls back to the printed URL, which always works.
+ */
+async function renderQr(url) {
+  // A real terminal reports its width on the stream; COLUMNS covers the rest.
+  // Unknown width is treated as wide enough — the URL is printed either way.
+  const columns = Number(process.stdout.columns || process.env.COLUMNS || 0);
+  if (columns > 0 && columns < QR_MIN_COLUMNS) return false;
+
+  let qr;
+  try {
+    const mod = await import('qrcode-terminal');
+    qr = mod.default || mod;
+  } catch { return false; }
+  if (!qr || typeof qr.generate !== 'function') return false;
+
+  try {
+    let art = '';
+    // Call it as a method: qrcode-terminal reads its error-correction level off
+    // `this`, so a detached `generate` reference silently builds a version-1
+    // code and throws on anything longer than a few characters.
+    // `small` is the half-block form: two module rows per text row, so the code
+    // stays square-ish and fits an 80-column terminal.
+    qr.generate(url, { small: true }, (rendered) => { art = rendered; });
+    if (!art) return false;
+    process.stdout.write(`\n${art}\n`);
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * A line-at-a-time reader over stdin.
+ *
+ * Deliberately not node:readline: its Interface keeps consuming while we are
+ * awaiting an HTTP round trip between two questions and drops the lines nobody
+ * is listening for, which silently loses piped answers. This queues every line
+ * instead, so the answers can arrive in one blob or one keystroke at a time.
+ *
+ * ask() resolves `null` — never a string — once the input is closed, so it can
+ * never be confused with a real empty line. That distinction is load-bearing:
+ * callers treat an empty line as "take the default", and a caller that reads EOF
+ * as an empty line will take that default again on the next question, and the
+ * next, forever, because nothing will ever arrive to change its mind. Callers
+ * that genuinely want the empty-line behaviour opt in with `?? ''`.
+ */
+function createPrompter() {
+  const queued = [];
+  const waiting = [];
+  let buffer = '';
+  let closed = false;
+
+  const deliver = (line) => {
+    const waiter = waiting.shift();
+    if (waiter) waiter(line);
+    else queued.push(line);
+  };
+  const onData = (chunk) => {
+    buffer += chunk;
+    let idx;
+    while ((idx = buffer.indexOf('\n')) !== -1) {
+      deliver(buffer.slice(0, idx).replace(/\r$/, ''));
+      buffer = buffer.slice(idx + 1);
+    }
+  };
+  const onEnd = () => {
+    if (closed) return;
+    closed = true;
+    if (buffer) { deliver(buffer); buffer = ''; }
+    while (waiting.length) waiting.shift()(null);
+  };
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', onData);
+  process.stdin.once('end', onEnd);
+  process.stdin.resume();
+
+  return {
+    ask(question) {
+      process.stdout.write(question);
+      if (queued.length > 0) return Promise.resolve(queued.shift());
+      if (closed) return Promise.resolve(null);
+      return new Promise((resolve) => { waiting.push(resolve); });
+    },
+    close() {
+      process.stdin.off('data', onData);
+      process.stdin.off('end', onEnd);
+      process.stdin.pause();
+    },
+  };
+}
+
+/** POST /api/agent/auth — anonymous registration, yields the pre-claim credential. */
+async function registerAnonymous(apiBase) {
+  const { res, json } = await httpJson('POST', `${apiBase}/api/agent/auth`, {
+    body: { type: 'anonymous', agent_label: AGENT_LABEL, scopes: CLI_SCOPES },
+  });
+  if (!res.ok || !json || typeof json.credential !== 'string') {
+    const detail = apiDetail(res, json);
+    fail(`could not start a connection: ${detail}`);
+  }
+  return json.credential;
+}
+
+/**
+ * "✓ Connected as @agt_ab12 → #Project X" — the room half is omitted if unknown,
+ * and widened to "→ all rooms" / "→ #Project X +2 more" when the human granted
+ * this agent more than the one delivery room.
+ */
+function connectedLine(cred) {
+  const who = cred.handle ? `@${cred.handle}` : 'this machine';
+  const room = cred.room && (cred.room.name || cred.room.invite_code);
+  const access = cred.room_access ?? cred.roomAccess;
+
+  if (access === 'all') return `✓ Connected as ${who} → all rooms`;
+
+  if (!room) return `✓ Connected as ${who}`;
+
+  const extra = Math.max(0, (Array.isArray(cred.rooms) ? cred.rooms.length : 0) - 1);
+  return `✓ Connected as ${who} → #${room}${extra > 0 ? ` +${extra} more` : ''}`;
+}
+
+function activationFailureDetail(result) {
+  if (result.error) return result.error.message;
+  const status = result.res ? `HTTP ${result.res.status}` : 'request failed';
+  return (result.json && (result.json.message || result.json.error || result.json.code)) || status;
+}
+
+function validateActivationEnsure(json) {
+  const room = json?.room;
+  const question = json?.question;
+  const validState = question?.state === 'pending'
+    || question?.state === 'answered'
+    || question?.state === 'expired'
+    || question?.state === 'cancelled';
+  if (
+    !isJsonObject(json)
+    || json.onboarded !== true
+    || typeof json.replayed !== 'boolean'
+    || !isJsonObject(room)
+    || !isNonEmptyString(room.id)
+    || typeof room.name !== 'string'
+    || !isNonEmptyString(room.invite_code)
+    || typeof room.is_agent_inbox !== 'boolean'
+    || !isJsonObject(question)
+    || !isNonEmptyString(question.id)
+    || question.kind !== 'question'
+    || !isNonEmptyString(question.prompt)
+    || !Array.isArray(question.options)
+    || question.options.some((option) => (
+      !isJsonObject(option)
+      || !isNonEmptyString(option.value)
+      || !isNonEmptyString(option.label)
+    ))
+    || !validState
+    || !isNullableString(question.expires_at)
+    || !isNullableString(question.created_at)
+  ) {
+    return { error: 'PingRoom returned an incomplete Agent Inbox ensure response' };
+  }
+  return { question };
+}
+
+function validateActivationWait(json, questionId) {
+  const state = json?.state;
+  const validState = state === 'pending' || state === 'answered' || state === 'expired' || state === 'cancelled';
+  if (
+    !isJsonObject(json)
+    || !isNonEmptyString(json.id)
+    || json.id !== questionId
+    || json.kind !== 'question'
+    || !validState
+    || (json.activation_completed !== undefined && typeof json.activation_completed !== 'boolean')
+    || (state !== 'answered' && json.activation_completed === true)
+  ) {
+    return { error: 'PingRoom returned a mismatched Agent Inbox wait response' };
+  }
+
+  if (state === 'answered') {
+    const answer = json.answer;
+    const responder = answer?.responder;
+    if (
+      !isJsonObject(answer)
+      || !isNullableString(answer.value)
+      || !isNullableString(answer.label)
+      || !isNullableString(answer.text)
+      || (!isNonEmptyString(answer.value) && !isNonEmptyString(answer.text))
+      || !isNullableString(answer.answered_at)
+      || (responder !== null && !isJsonObject(responder))
+      || (isJsonObject(responder)
+        && (!isNullableString(responder.id) || !isNullableString(responder.display_name)))
+    ) {
+      return { error: 'PingRoom returned an answered activation without a valid answer' };
+    }
+  } else if (json.answer !== undefined && json.answer !== null) {
+    return { error: 'PingRoom returned an answer for an unresolved activation' };
+  }
+
+  return { value: json };
+}
+
+function activationRetryDelay(result, transientRun, deadline) {
+  const fromHeader = result.res?.status === 429 ? retryAfterMs(result.res) : null;
+  const fallback = Math.min(1000 * 2 ** Math.max(0, transientRun - 1), 10_000);
+  return Math.max(0, Math.min(fromHeader ?? fallback, deadline - Date.now()));
+}
+
+function activationIncomplete(detail, instruction = 'Run "pingroom activate" to retry with this saved connection.') {
+  const safeDetail = detail ? `: ${stripControlChars(detail)}` : '';
+  process.stdout.write(`  Agent Inbox activation is not complete${safeDetail}\n`);
+  process.stdout.write('  Your connection is saved and usable.\n');
+  process.stdout.write(`  ${instruction}\n`);
+}
+
+/**
+ * Prove the freshly paired credential can complete a human round-trip. This is
+ * intentionally best-effort: saveCredential() has already committed the active
+ * bearer atomically, so no activation outage can roll back or corrupt it.
+ */
+async function activateInboxAfterPairing(cred) {
+  const headers = { Authorization: `Bearer ${cred.token}` };
+  const overallDeadline = Date.now() + activationMaxWaitMs();
+  process.stdout.write('  Sending a test question to PingRoom…\n');
+
+  let ensured;
+  let ensureTransientRun = 0;
+  while (Date.now() < overallDeadline) {
+    ensured = await httpJson('POST', `${cred.apiBase}/api/agent/inbox/ensure`, {
+      body: {},
+      headers,
+      soft: true,
+      signal: AbortSignal.timeout(Math.max(1, Math.min(15_000, overallDeadline - Date.now()))),
+    });
+    const transient = ensured.error || ensured.res?.status === 429 || ensured.res?.status >= 500;
+    if (!transient) break;
+    ensureTransientRun += 1;
+    await sleep(activationRetryDelay(ensured, ensureTransientRun, overallDeadline));
+  }
+
+  if (!ensured.res?.ok) {
+    const detail = Date.now() >= overallDeadline
+      ? 'the two-minute activation deadline elapsed while PingRoom was unavailable'
+      : activationFailureDetail(ensured);
+    activationIncomplete(detail);
+    return false;
+  }
+
+  const ensureEnvelope = validateActivationEnsure(ensured.json);
+  if (ensureEnvelope.error) {
+    activationIncomplete(ensureEnvelope.error);
+    return false;
+  }
+  const { question } = ensureEnvelope;
+
+  process.stdout.write('  Answer “PingRoom connected. Can you answer this?” on your phone.\n');
+  // The server stamp, not the terminal state by itself, is the activation
+  // authority. A terminal answer without the stamp cannot become a valid
+  // receipt-before-answer sequence later, so fail clearly instead of polling a
+  // state the server intentionally will not rewrite.
+  const deadline = overallDeadline;
+  let transientRun = 0;
+
+  while (Date.now() < deadline) {
+    const pollStartedAt = Date.now();
+    const remainingSeconds = Math.max(0, Math.ceil((deadline - Date.now()) / 1000));
+    const hold = Math.min(20, remainingSeconds);
+    const waited = await httpJson(
+      'GET',
+      `${cred.apiBase}/api/agent/handoffs/${encodeURIComponent(question.id)}/wait?timeout=${hold}`,
+      {
+        headers,
+        soft: true,
+        signal: AbortSignal.timeout(Math.max(1, Math.min(
+          hold * 1000 + 10_000,
+          deadline - Date.now(),
+        ))),
+      },
+    );
+
+    const transient = waited.error || waited.res?.status === 429 || waited.res?.status >= 500;
+    if (transient) {
+      transientRun += 1;
+      const retryDelay = activationRetryDelay(waited, transientRun, deadline);
+      const cadenceDelay = ACTIVATION_MIN_POLL_INTERVAL_MS - (Date.now() - pollStartedAt);
+      await sleep(Math.max(0, Math.min(Math.max(retryDelay, cadenceDelay), deadline - Date.now())));
+      continue;
+    }
+    transientRun = 0;
+
+    if (!waited.res?.ok) {
+      activationIncomplete(activationFailureDetail(waited));
+      return false;
+    }
+
+    const waitEnvelope = validateActivationWait(waited.json, question.id);
+    if (waitEnvelope.error) {
+      activationIncomplete(waitEnvelope.error);
+      return false;
+    }
+    const resolved = waitEnvelope.value;
+    const state = resolved.state;
+    if (state === 'answered') {
+      if (resolved.activation_completed !== true) {
+        activationIncomplete(
+          'the test question was answered without verified phone receipt before the answer',
+          'Update the PingRoom app if needed, then run "pingroom activate" to send a fresh test with this saved connection.',
+        );
+        return false;
+      }
+      const answer = resolved.answer.text || resolved.answer.label || resolved.answer.value;
+      process.stdout.write(`✓ Test question answered (${stripControlChars(answer)}). Agent Inbox is ready.\n`);
+      return true;
+    }
+    if (state === 'expired' || state === 'cancelled') {
+      activationIncomplete(
+        `the test question ${state}`,
+        'Run "pingroom activate" to send a fresh test with this saved connection.',
+      );
+      return false;
+    }
+    // `pending` at the bounded hold timeout — continue at a throttle-safe
+    // cadence until the local/server deadline.
+    const cadenceDelay = ACTIVATION_MIN_POLL_INTERVAL_MS - (Date.now() - pollStartedAt);
+    await sleep(Math.max(0, Math.min(cadenceDelay, deadline - Date.now())));
+  }
+
+  activationIncomplete(
+    'still waiting for the test answer at the activation deadline',
+  );
+  return false;
+}
+
+/** Retry activation only for the durable credential created by QR pairing. */
+export async function activateStoredInbox(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('activate')}\n`); return EXIT.OK; }
+  if (args._.length > 0) fail('usage: pingroom activate', EXIT.USAGE);
+  if (args.token !== undefined) {
+    fail('pingroom activate uses the saved QR-paired credential; remove --token', EXIT.USAGE);
+  }
+  const unsupported = Object.keys(args).filter((key) => !['_', 'help', 'api', 'token'].includes(key));
+  if (unsupported.length > 0) {
+    fail('usage: pingroom activate [--api <url>]', EXIT.USAGE);
+  }
+
+  const credential = readStoredCredential();
+  if (!credential) {
+    fail('no saved QR-paired credential; run "pingroom" in an interactive terminal first', EXIT.USAGE);
+  }
+  if (!credential.room || !isNonEmptyString(credential.room.invite_code)) {
+    // Granting every room is a valid answer that pins no destination, so the
+    // fix there is picking one — not pairing again, which would only offer the
+    // same choice back.
+    fail(
+      credential.room_access === 'all'
+        ? 'this agent was granted all rooms but no delivery room; pick one in the PingRoom app under Connected Agents, then run "pingroom activate" again'
+        : 'the saved credential has no QR-selected delivery room; reconnect with QR pairing before running "pingroom activate"',
+      EXIT.USAGE,
+    );
+  }
+  if (!Array.isArray(credential.scopes) || !credential.scopes.includes('pingroom:handoffs:create')) {
+    fail('the saved credential lacks pingroom:handoffs:create; reconnect with QR pairing before running "pingroom activate"', EXIT.USAGE);
+  }
+
+  const apiBase = resolveApiBase(args);
+  requireSafeUrl('--api', apiBase);
+  if (!isNonEmptyString(credential.api_url)) {
+    fail('the saved QR-paired credential has no trusted API origin; pair again before running "pingroom activate"', EXIT.USAGE);
+  }
+  let credentialOrigin;
+  let targetOrigin;
+  try {
+    credentialOrigin = new URL(credential.api_url).origin;
+    targetOrigin = new URL(apiBase).origin;
+  } catch {
+    fail('the saved QR-paired credential has an invalid API origin; pair again', EXIT.USAGE);
+  }
+  if (credentialOrigin !== targetOrigin) {
+    fail(`stored credential is bound to ${credentialOrigin}; refusing to send it to ${targetOrigin}`, EXIT.USAGE);
+  }
+  process.stdout.write(`${connectedLine(credential)}\n`);
+
+  const completed = await activateInboxAfterPairing({
+    ...credential,
+    apiBase,
+  });
+  return completed ? EXIT.OK : EXIT.ERROR;
+}
+
+/**
+ * The QR path. Mints a pre-claim credential, asks the server for a pairing
+ * token, renders it, then polls until the human approves. Returns a credential
+ * object, or null when the pairing lapsed and the user declined a fresh one.
+ */
+async function connectByPairing(apiBase, ask) {
+  for (;;) {
+    const preClaim = await registerAnonymous(apiBase);
+    const headers = { Authorization: `Bearer ${preClaim}` };
+
+    const start = await httpJson('POST', `${apiBase}/api/agent/auth/pair/start`, {
+      body: { scopes: CLI_SCOPES },
+      headers,
+    });
+    if (!start.res.ok || !start.json || typeof start.json.pair_url !== 'string') {
+      const detail = (start.json && (start.json.message || start.json.error || start.json.code))
+        || `HTTP ${start.res.status}`;
+      fail(`could not start pairing: ${detail}`);
+    }
+
+    // The URL is server-controlled and goes straight to the terminal, so strip
+    // C0/C1 controls: an --api / config api_url pointing at a hostile host could
+    // otherwise emit ANSI escapes that repaint or hide the line the user is
+    // about to trust with their account.
+    const pairUrl = stripControlChars(start.json.pair_url);
+    // 900s is the server's pre-claim lifetime; never poll past it, and clamp the
+    // server's suggested interval so a bad value can't busy-loop or stall.
+    // The 1000ms floor is not cosmetic: AGENT_PAIRING_SPEC.md throttles
+    // pair/status at `60,1`, so a faster floor spends the pairing window
+    // collecting 429s instead of the approval.
+    const lifetimeMs = Math.max(1, Number(start.json.expires_in) || 900) * 1000;
+    const intervalMs = Math.min(Math.max(Number(start.json.poll_interval_ms) || 1500, 1000), 10_000);
+    const deadline = Date.now() + lifetimeMs;
+
+    const drew = await renderQr(pairUrl);
+    process.stdout.write(`${drew ? '  Or open' : '  Open'}: ${pairUrl}\n`);
+    process.stdout.write('  Waiting for approval… ');
+
+    // A transient failure must not end a wait the human is mid-way through.
+    // Network errors, 5xx and 429 are the load balancer / rate limiter talking,
+    // not the pairing being over; hard-failing on the first one throws away the
+    // whole 15 minutes over a single blip. 401/403/404 still exit immediately —
+    // those say the pre-claim is gone, and retrying can only spin.
+    // The `Date.now() < deadline` bound is what keeps a *persistent* outage from
+    // retrying forever: it ends at the same moment a clean poll would have.
+    let transientRun = 0;
+    let lastTransient = null;
+    let warnedTransient = false;
+
+    while (Date.now() < deadline) {
+      const { res, json, error } = await httpJson(
+        'GET', `${apiBase}/api/agent/auth/pair/status`, { headers, soft: true },
+      );
+
+      if (error || res.status >= 500 || res.status === 429) {
+        transientRun += 1;
+        lastTransient = error
+          ? error.message
+          : `HTTP ${res.status}`;
+        // Say something rather than sitting mute: a user watching a QR with no
+        // output cannot tell a slow approval from a broken endpoint.
+        if (transientRun === 3 && !warnedTransient) {
+          warnedTransient = true;
+          process.stdout.write(`\n  (still trying — ${lastTransient}) `);
+        }
+        // Ride out a short blip at the normal cadence, then back off
+        // geometrically so a real outage is not also a thundering herd. Never
+        // sleep past the deadline this loop is bounded by.
+        const backoff = Math.min(intervalMs * 2 ** Math.max(0, transientRun - 3), 30_000);
+        await sleep(Math.max(0, Math.min(backoff, deadline - Date.now())));
+        continue;
+      }
+
+      transientRun = 0;
+
+      if (!res.ok) {
+        process.stdout.write('\n');
+        const detail = apiDetail(res, json);
+        fail(`pairing failed: ${detail}`);
+      }
+      const status = json && json.status;
+      if (status === 'active') {
+        // A server that says "active" with no credential has not paired us.
+        // Without this, `token: undefined` is written to credentials.json and
+        // every later command reads a credential file that exists but cannot
+        // authenticate — a far more confusing failure than stopping here.
+        if (typeof json.credential !== 'string' || json.credential === '') {
+          process.stdout.write('\n');
+          fail('pairing succeeded but the server returned no credential');
+        }
+        const cred = {
+          token: json.credential,
+          handle: json.handle,
+          room: json.room,
+          rooms: Array.isArray(json.rooms) ? json.rooms : [],
+          roomAccess: typeof json.room_access === 'string' ? json.room_access : null,
+          account: json.account,
+          scopes: json.scopes,
+          apiBase,
+        };
+        saveCredential(cred);
+        process.stdout.write(`${connectedLine(cred)}\n`);
+        // Connecting deliberately sends nothing to the human's phone. The
+        // approval they just tapped IS the round-trip; a test Question on top of
+        // it was one more thing to answer before the tool could be used, and it
+        // made a healthy connection look broken whenever the answer was slow.
+        // `pingroom activate` still sends one for anyone who wants the proof.
+        return cred;
+      }
+      if (status === 'expired') break;
+      // `pending` (or anything unrecognized) — keep waiting.
+      await sleep(intervalMs);
+    }
+
+    if (transientRun > 0) {
+      process.stdout.write(`\n  Gave up waiting — the server kept failing (last: ${lastTransient}).\n`);
+    } else {
+      process.stdout.write(`\n  That code expired.\n`);
+    }
+
+    // `null` means the input is closed, and that is the whole point of this
+    // guard. Reading EOF as "" would fall through the y/yes test below (empty
+    // means "take the default: yes"), restart the for(;;), mint another
+    // anonymous registration, and do it again — a Ctrl-D or a piped stdin turns
+    // a single pairing attempt into thousands of registrations against the API.
+    const again = await ask('  Show a fresh QR code? [Y/n]: ');
+    if (again === null) { process.stdout.write('\n'); return null; }
+    const answer = again.trim().toLowerCase();
+    if (answer && answer !== 'y' && answer !== 'yes') return null;
+  }
+}
+
+/**
+ * The email fallback, over the unchanged claim/* endpoints: the server mails a
+ * link, the web page shows a 6-digit code, the user reads it back here.
+ */
+async function connectByEmail(apiBase, ask) {
+  const preClaim = await registerAnonymous(apiBase);
+  const headers = { Authorization: `Bearer ${preClaim}` };
+
+  // `?? ''` preserves the old EOF behaviour deliberately: ask() now returns null
+  // at EOF, and without the coalesce this would throw a TypeError on `.trim()`
+  // instead of reaching the "this is required" error the user should see.
+  const email = (await ask('  Your PingRoom email: ') ?? '').trim();
+  if (!email) fail('an email address is required', EXIT.USAGE);
+
+  const start = await httpJson('POST', `${apiBase}/api/agent/auth/claim/start`, {
+    body: { email },
+    headers,
+  });
+  if (!start.res.ok) {
+    const detail = (start.json && (start.json.message || start.json.error || start.json.code))
+      || `HTTP ${start.res.status}`;
+    fail(`could not send the email: ${detail}`);
+  }
+
+  process.stdout.write('  Sent. Open the link in that email — the page shows a 6-digit code.\n');
+
+  // A mistyped code is the common case, so allow a few tries before giving up.
+  // The server locks the registration out after its own attempt cap anyway.
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    // Same reason as the email prompt: EOF stays an empty answer, which the
+    // server rejects, rather than a TypeError on null.
+    const otp = (await ask('  Code: ') ?? '').trim();
+    const done = await httpJson('POST', `${apiBase}/api/agent/auth/claim/complete`, {
+      body: { email, otp },
+      headers,
+    });
+    if (done.res.ok && done.json && typeof done.json.credential === 'string') {
+      const cred = {
+        token: done.json.credential,
+        handle: done.json.handle,
+        // claim/complete carries no room — the email flow does not choose one.
+        room: done.json.room,
+        account: done.json.account,
+        scopes: done.json.scopes,
+        apiBase,
+      };
+      saveCredential(cred);
+      process.stdout.write(`${connectedLine(cred)}\n`);
+      if (!cred.room) {
+        process.stdout.write('  For room commands: pingroom config set default_room <invite code>\n');
+        process.stdout.write('  For private Inbox/Handoff delivery, reconnect with QR pairing.\n');
+      }
+      return cred;
+    }
+    const detail = (done.json && (done.json.message || done.json.error || done.json.code))
+      || `HTTP ${done.res.status}`;
+    if (attempt === 3) fail(`could not connect: ${detail}`);
+    process.stderr.write(`pingroom: ${detail}\n`);
+  }
+  return null;
+}
+
+/**
+ * Resolve the unconnected state interactively. Refuses outright when there is no
+ * TTY — a hung prompt in CI is worse than a clean failure, and the fix there is
+ * PINGROOM_TOKEN, not a QR nobody can scan.
+ */
+export async function connect(args) {
+  if (!isInteractive()) {
+    fail(
+      'not connected, and this is not an interactive terminal. Set PINGROOM_TOKEN (CI, pipes), or run "pingroom" from a terminal to pair.',
+      EXIT.USAGE,
+    );
+  }
+
+  const apiBase = resolveApiBase(args);
+  requireSafeUrl('--api', apiBase);
+
+  const prompter = createPrompter();
+  const ask = (question) => prompter.ask(question);
+  try {
+    process.stdout.write('  Not connected. How do you want to connect?\n');
+    process.stdout.write('    1) Scan a QR code with the PingRoom app\n');
+    process.stdout.write('    2) Email me a code\n');
+    // EOF here means "no answer", which is what the default already covers, so
+    // coalesce rather than crash on null — the pairing branch below is the one
+    // that must distinguish EOF, and it does.
+    const choice = (await ask('  Choose [1]: ') ?? '').trim();
+    if (choice && choice !== '1' && choice !== '2') {
+      process.stderr.write('pingroom: choose 1 or 2\n');
+      return EXIT.USAGE;
+    }
+
+    const cred = choice === '2'
+      ? await connectByEmail(apiBase, ask)
+      : await connectByPairing(apiBase, ask);
+
+    return cred ? EXIT.OK : EXIT.EXPIRED;
+  } finally {
+    prompter.close();
+  }
+}
+
+// --- status / bare invocation ----------------------------------------------
+
+/**
+ * `pingroom` with no arguments. Connected -> one status line then the usual
+ * help. Not connected -> pair (interactive) or, in a pipe/CI, say so on stderr
+ * and still print the help rather than prompting into the void.
+ */
+export async function bare(args) {
+  const envToken = process.env.PINGROOM_TOKEN;
+  const stored = readStoredCredential();
+
+  if (envToken) {
+    process.stdout.write('Using the agent token from PINGROOM_TOKEN.\n');
+    if (stored) process.stdout.write(`(the stored credential in ${credentialsPath()} is ignored while it is set)\n`);
+    const room = resolveRoom(args);
+    if (room) process.stdout.write(`Default room: ${room}\n`);
+    process.stdout.write(`\n${HELP}\n`);
+    return EXIT.OK;
+  }
+
+  if (stored) {
+    process.stdout.write(`${connectedLine(stored)}\n`);
+    const room = resolveRoom(args);
+    if (room) process.stdout.write(`Default room: ${room}\n`);
+    process.stdout.write(`\n${HELP}\n`);
+    return EXIT.OK;
+  }
+
+  if (!isInteractive()) {
+    process.stderr.write('pingroom: not connected. Set PINGROOM_TOKEN, or run "pingroom" from an interactive terminal to pair.\n');
+    process.stdout.write(`${HELP}\n`);
+    return EXIT.OK;
+  }
+
+  return connect(args);
+}