phaedo-mcp 0.2.2 → 0.3.1

package/ship-actions.js

@@ -0,0 +1,164 @@
+// Ship actions — which shell commands are a decision the subject would want consulted on.
+//
+// The precedent track's Phase 1 (docs/roadmap/precedent-and-sync-design-2026-09-13.md) is
+// starved of outcome data because nothing consults: no receipt has been written since
+// 2026-07-28. The decisions the subject actually delegates, every week, are the ones a
+// coding agent takes on their behalf — merging a PR, deploying the relay, cutting a phone
+// build. This module names those, so the PreToolUse hook (hooks/pre-ship.mjs) can consult
+// before they run. Everything else a shell does is not a decision and is ignored.
+//
+// PURE: (command string) -> classification | null. No I/O.
+
+import { createHash } from 'node:crypto';
+
+// One entry per class. `match` sees one simple command, already split out of a compound
+// line and stripped of env assignments and `npx`. The descriptor is what the consult
+// reasons about — magnitude is the stakes, reversible is whether it can be walked back.
+const CLASSES = [
+  {
+    id: 'merge_pr',
+    // `gh pr merge` — reversible (a revert), medium. `--admin` skips required checks, which
+    // is a different act: high.
+    match: (w) => w[0] === 'gh' && w[1] === 'pr' && w[2] === 'merge',
+    describe: (w) => {
+      const num = w.slice(3).find((x) => /^#?\d+$/.test(x));
+      const admin = w.includes('--admin');
+      // `-R/--repo` names the repository when the agent is not inside it; the hook passes it
+      // through when it asks GitHub for the PR's check state (B6).
+      const ri = w.findIndex((x) => x === '-R' || x === '--repo');
+      const repo = ri >= 0 ? w[ri + 1] : (w.find((x) => x.startsWith('--repo='))?.split('=')[1]);
+      return {
+        magnitude: admin ? 'high' : 'medium',
+        reversible: true,
+        summary: `${admin ? 'admin-merge' : 'merge'} ${num ? `PR #${num.replace('#', '')}` : "this branch's PR"}`,
+        pr: num ? num.replace('#', '') : null,
+        repo: repo || null,
+      };
+    },
+  },
+  {
+    id: 'deploy',
+    // `fly deploy` — production for every paired phone. Reversible (`fly releases` rollback)
+    // but high: a bad relay breaks sync for everyone until it is rolled back.
+    match: (w) => (w[0] === 'fly' || w[0] === 'flyctl') && w[1] === 'deploy',
+    describe: (w) => {
+      const i = w.findIndex((x) => x === '-a' || x === '--app');
+      const app = i >= 0 ? w[i + 1] : null;
+      return { magnitude: 'high', reversible: true, summary: `deploy${app ? ` ${app}` : ''} to Fly` };
+    },
+  },
+  {
+    id: 'app_build',
+    // `eas build` — a build artifact, nothing reaches a device yet. Low.
+    match: (w) => isEas(w[0]) && w[1] === 'build',
+    describe: (w) => ({ magnitude: 'low', reversible: true, summary: `phone build${platform(w)}` }),
+  },
+  {
+    id: 'app_submit',
+    // `eas submit` (or `eas build --auto-submit`) — the build goes to TestFlight / the store.
+    match: (w) => isEas(w[0]) && (w[1] === 'submit' || (w[1] === 'build' && w.includes('--auto-submit'))),
+    describe: (w) => ({ magnitude: 'medium', reversible: true, summary: `submit phone build${platform(w)}` }),
+  },
+  {
+    id: 'push_main',
+    // A direct push to the default branch, skipping review. A force-push there rewrites
+    // shared history: high, and not cleanly reversible.
+    match: (w) => w[0] === 'git' && w[1] === 'push' && w.slice(2).some((x) => /^\+?(?:[^:]*:)?(?:refs\/heads\/)?(?:main|master)$/.test(x)),
+    describe: (w) => {
+      const force = w.some((x) => x === '-f' || x === '--force' || x.startsWith('--force-with-lease') || x.startsWith('+'));
+      return force
+        ? { magnitude: 'high', reversible: false, summary: 'force-push to main' }
+        : { magnitude: 'medium', reversible: true, summary: 'push directly to main' };
+    },
+  },
+];
+
+// Order matters for one pair: `eas build --auto-submit` is a submit, not a build.
+const ORDER = ['merge_pr', 'deploy', 'app_submit', 'app_build', 'push_main'];
+
+function isEas(w0) { return w0 === 'eas' || w0 === 'eas-cli'; }
+function platform(w) {
+  const i = w.findIndex((x) => x === '--platform' || x === '-p');
+  const p = i >= 0 ? w[i + 1] : (w.find((x) => x.startsWith('--platform='))?.split('=')[1]);
+  return p ? ` (${p})` : '';
+}
+
+// Split a shell line into simple commands on && || ; | and newlines. Not a shell parser —
+// quotes are honoured only enough that `git commit -m "a && b"` does not split.
+export function splitCommands(line) {
+  const out = [];
+  let cur = '';
+  let q = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (q) { cur += c; if (c === q) q = null; continue; }
+    if (c === '"' || c === "'") { q = c; cur += c; continue; }
+    if (c === '\n' || c === ';' || c === '|' || (c === '&' && line[i + 1] === '&')) {
+      if (c === '&' || (c === '|' && line[i + 1] === '|')) i++;
+      out.push(cur); cur = '';
+      continue;
+    }
+    cur += c;
+  }
+  out.push(cur);
+  return out.map((s) => s.trim()).filter(Boolean);
+}
+
+// Words of one simple command, with leading env assignments, `npx`/`npx --yes`, and a
+// quoted-string's quotes removed.
+export function words(cmd) {
+  const w = (cmd.match(/"[^"]*"|'[^']*'|\S+/g) || []).map((x) => x.replace(/^["']|["']$/g, ''));
+  while (w.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(w[0])) w.shift();
+  if (w[0] === 'npx') { w.shift(); while (w[0] && w[0].startsWith('-')) w.shift(); }
+  // A path to the binary (`/opt/homebrew/bin/gh`, `./node_modules/.bin/eas`) is the binary.
+  if (w[0]) w[0] = w[0].split('/').pop();
+  return w;
+}
+
+// Stakes order for a line that chains several ship actions: irreversible first, then by
+// magnitude. A line that merges and then deploys is consulted on the deploy — consulting on
+// the merge would let the riskier half ride on the safer half's answer.
+const MAG_RANK = { low: 0, medium: 1, high: 2 };
+const stakes = (d) => (d.reversible === false ? 10 : 0) + (MAG_RANK[d.magnitude] ?? 1);
+
+/**
+ * Classify a Bash command. Returns null when no part of it is a ship action, else the
+ * highest-stakes ship action in it (ties: the first), with `multiple` set when the line
+ * chains more than one.
+ *
+ * @returns {null | { class, summary, multiple, action_descriptor, action_binding }}
+ */
+export function classifyShipCommand(command) {
+  if (typeof command !== 'string' || !command.trim()) return null;
+  const hits = [];
+  for (const seg of splitCommands(command)) {
+    const w = words(seg);
+    if (!w.length) continue;
+    for (const id of ORDER) {
+      const k = CLASSES.find((c) => c.id === id);
+      if (k.match(w)) { hits.push({ id, seg, d: k.describe(w) }); break; }
+    }
+  }
+  if (!hits.length) return null;
+  const first = hits.reduce((best, h) => (stakes(h.d) > stakes(best.d) ? h : best));
+  return {
+    class: first.id,
+    summary: first.d.summary,
+    multiple: hits.length > 1,
+    // merge_pr only: which PR, and in which repo (null = the current branch's, here).
+    ...(first.id === 'merge_pr' ? { pr: first.d.pr, repo: first.d.repo } : {}),
+    action_descriptor: {
+      domain: 'engineering',
+      reversible: first.d.reversible,
+      magnitude: first.d.magnitude,
+      summary: first.d.summary,
+    },
+    // §10.2 binding: the concrete call this descriptor claims to describe — a digest of the
+    // whole line, never the line itself beyond a short preview.
+    action_binding: {
+      tool_name: 'Bash',
+      arguments_hash: createHash('sha256').update(command).digest('hex'),
+      arguments_preview: first.seg.slice(0, 120),
+    },
+  };
+}

package/ship-readout.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+// Ship-hook readout — what the Claude Code ship hook (hooks/pre-ship.mjs) has seen: how many
+// merges / deploys / phone builds it consulted on, what Phaedo answered, what the subject
+// said, and whether agreement has anything to score yet. The precedent track's Phase 1
+// exit is "receipts gain marked outcomes in normal use"; this is how to see whether they do.
+//
+//   npm run ship-readout              # last 30 days
+//   npm run ship-readout -- --days 90
+//
+// All local: decrypts the receipt store with the local key; prints counts and the summary
+// line each receipt already carries (never layer content).
+
+import { computeAgreement } from './agreement.js';
+import { AGENT_ID } from './hooks/pre-ship.mjs';
+
+export const DEFAULT_DAYS = 30;
+const PERMISSIVE = new Set(['proceed', 'proceed_with_note']);
+const ASKING = new Set(['escalate', 'clarify', 'decline']);
+
+// The action a hook receipt was about, from the summary ship-actions.js wrote.
+export function actionKind(summary) {
+  const s = String(summary || '');
+  if (/^(admin-)?merge\b/.test(s)) return 'merge';
+  if (/^deploy\b/.test(s)) return 'deploy';
+  if (/^submit\b/.test(s)) return 'phone submit';
+  if (/^phone build\b/.test(s)) return 'phone build';
+  if (/push/.test(s)) return 'push to main';
+  return 'other';
+}
+
+/**
+ * (receipts, { now, windowDays }) -> the readout, PURE. Only receipts the ship hook wrote
+ * count — the agreement figure here is the hook's own, not the whole store's.
+ */
+export function shipReadout(receipts, { now = Date.now(), windowDays = DEFAULT_DAYS } = {}) {
+  const since = now - windowDays * 24 * 60 * 60 * 1000;
+  const mine = (Array.isArray(receipts) ? receipts : []).filter((r) => r?.agent_id === AGENT_ID);
+  const inWindow = mine.filter((r) => { const t = Date.parse(r?.created_at); return Number.isFinite(t) && t >= since && t <= now; });
+  const kinds = {};
+  const answers = { go_ahead: 0, flagged: 0, unsure: 0 };
+  const outcomes = { approved: 0, rejected: 0, modified: 0, unmarked: 0 };
+  for (const r of inWindow) {
+    const k = actionKind(r.request?.action_descriptor?.summary);
+    kinds[k] = (kinds[k] || 0) + 1;
+    const sig = r.response?.signal;
+    if (PERMISSIVE.has(sig)) answers.go_ahead++; else if (ASKING.has(sig)) answers.flagged++; else answers.unsure++;
+    const a = r.user_action;
+    if (a === 'approved' || a === 'rejected' || a === 'modified') outcomes[a]++; else outcomes.unmarked++;
+  }
+  const agreement = computeAgreement(inWindow, { now, windowDays }).overall;
+  const newest = inWindow[inWindow.length - 1] || null;
+  return {
+    window_days: windowDays,
+    total_ever: mine.length,
+    consults: inWindow.length,
+    kinds,
+    answers,
+    outcomes,
+    agreement: { scored: agreement.scored, agreements: agreement.agreements, rate: agreement.rate },
+    newest: newest && {
+      at: newest.created_at,
+      summary: newest.request?.action_descriptor?.summary || null,
+      signal: newest.response?.signal || null,
+      user_action: newest.user_action || null,
+    },
+  };
+}
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const KIND_PLURAL = { merge: 'merges', deploy: 'deploys', 'phone build': 'phone builds', 'phone submit': 'phone submits', 'push to main': 'pushes to main', other: 'others' };
+const saidIt = (sig) => (PERMISSIVE.has(sig) ? 'go ahead' : ASKING.has(sig) ? 'flagged for you' : "didn't know");
+
+// Plain lines for the terminal. No confidences, no protocol terms beyond the summary.
+export function formatReadout(o) {
+  const lines = [`Ship hook — last ${o.window_days} days`];
+  if (!o.consults) {
+    lines.push(o.total_ever
+      ? `  Nothing in this window (${plural(o.total_ever, 'consult')} before it). Try --days ${o.window_days * 3}.`
+      : '  No consults yet. Is the hook installed? (npm run setup:code-hook, then a new Claude Code session)');
+    return lines.join('\n');
+  }
+  const kinds = Object.entries(o.kinds).sort((a, b) => b[1] - a[1]).map(([k, n]) => plural(n, k, KIND_PLURAL[k]));
+  lines.push(`  ${plural(o.consults, 'consult')}: ${kinds.join(', ')}`);
+  const ans = [`go ahead ${o.answers.go_ahead}×`, `flagged for you ${o.answers.flagged}×`];
+  if (o.answers.unsure) ans.push(`didn't know ${o.answers.unsure}×`);
+  lines.push(`  Phaedo said: ${ans.join(', ')}`);
+  const { approved, rejected, modified, unmarked } = o.outcomes;
+  lines.push(`  You said: yes ${approved}, no ${rejected}, changed it ${modified} — ${unmarked} not marked`);
+  lines.push(o.agreement.scored
+    ? `  Phaedo matched you on ${o.agreement.agreements} of ${o.agreement.scored} decisions it could be scored on`
+    : '  Nothing to score yet (needs a "go ahead" you then answered)');
+  if (o.newest) {
+    const day = String(o.newest.at).slice(0, 10);
+    lines.push(`  Newest: ${day} ${o.newest.summary || '(no summary)'} → Phaedo: ${saidIt(o.newest.signal)}${o.newest.user_action ? ` · you: ${o.newest.user_action}` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+if (process.argv[1] && process.argv[1].endsWith('ship-readout.js')) {
+  const i = process.argv.indexOf('--days');
+  const days = i > 0 ? Number(process.argv[i + 1]) : DEFAULT_DAYS;
+  const { readReceipts } = await import('./receipts.js');
+  const { defaultStateDir } = await import('./cache.js');
+  const rs = await readReceipts(defaultStateDir());
+  console.log(formatReadout(shipReadout(rs, { windowDays: Number.isFinite(days) && days > 0 ? days : DEFAULT_DAYS })));
+}

package/signing-audit.js

@@ -0,0 +1,111 @@
+// §8.3 signing audit — "what did I sign, and when."
+//
+// A signed mandate is a CREDENTIAL asserted to a third party, so minting one is at least as
+// audit-worthy as a consultation. But it is NOT a §10.6 consultation receipt: it has no
+// signal, no deference level, and it must not feed the act-as-me learning loop or the
+// agreement-rate metric (which would corrupt both). So this is its OWN small append-only,
+// encrypted-at-rest log — the same atomic-write + domain-separated-key discipline as
+// receipts.js, but a separate artifact.
+//
+// It records a DIGEST of what was signed plus coarse metadata (grant count, expiry,
+// requesting client) — never the full mandate, never the signature bytes. The digest is the
+// stable reference: given the mandate later, an auditor recomputes it and confirms it is the
+// object that was signed.
+
+import { mkdir, writeFile, readFile, rename, chmod } from 'fs/promises';
+import { existsSync } from 'fs';
+import { createHash, randomUUID } from 'crypto';
+import { join } from 'path';
+import { Phaedo } from './lib/phaedo-crypto.js';
+import { getOrCreateCacheKey } from './cache.js';
+import { signingInput } from './signing.js';
+
+const { Envelope } = Phaedo;
+
+export const SIGNING_AUDIT_CONTEXT = 'phaedo:signing-audit:enc:v0.1';
+export const DEFAULT_CAP = 5000;
+const FILE = 'signing-audit.enc';
+
+function auditPath(stateDir) { return join(stateDir, FILE); }
+
+async function deriveKey(stateDir) {
+  const root = await getOrCreateCacheKey(stateDir);
+  const ikm = await crypto.subtle.importKey('raw', root, 'HKDF', false, ['deriveBits']);
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(0), info: new TextEncoder().encode(SIGNING_AUDIT_CONTEXT) },
+    ikm, 32 * 8,
+  );
+  return new Uint8Array(bits);
+}
+
+async function readStore(stateDir) {
+  const p = auditPath(stateDir);
+  if (!existsSync(p)) return { records: [] };
+  const key = await deriveKey(stateDir);
+  const { envelope } = JSON.parse(await readFile(p, 'utf8'));
+  const plaintext = await Envelope.unwrap(envelope, key);
+  try {
+    const store = JSON.parse(new TextDecoder().decode(plaintext));
+    return Array.isArray(store?.records) ? store : { records: [] };
+  } finally {
+    plaintext.fill(0);
+  }
+}
+
+async function writeStore(stateDir, store, now) {
+  await mkdir(stateDir, { recursive: true, mode: 0o700 });
+  const key = await deriveKey(stateDir);
+  const plaintext = new TextEncoder().encode(JSON.stringify(store));
+  const envelope = await Envelope.wrap(plaintext, key, {
+    artifact_kind: 'signing_audit',
+    count: store.records.length,
+    created_at: new Date(now).toISOString(),
+  });
+  plaintext.fill(0);
+  const p = auditPath(stateDir);
+  const tmp = `${p}.tmp`;
+  await writeFile(tmp, JSON.stringify({ envelope }), { mode: 0o600 });
+  await chmod(tmp, 0o600);
+  await rename(tmp, p);   // atomic on POSIX
+}
+
+/**
+ * Build a signing-audit record from a signed mandate. Records the digest of the SIGNED bytes
+ * (§6 canonical form, `signature` omitted) — not the mandate content and not the signature.
+ */
+export function buildSigningAuditRecord({ requestId, mandate, clientId, agentId, now = Date.now() }) {
+  const digest = createHash('sha256').update(signingInput(mandate, { field: 'signature' })).digest('base64url');
+  const grants = Array.isArray(mandate?.grants) ? mandate.grants.length : 0;
+  return {
+    audit_id: randomUUID(),
+    signed_at: typeof mandate?.signed_at === 'string' ? mandate.signed_at : new Date(now).toISOString(),
+    request_id: typeof requestId === 'string' ? requestId : null,
+    // WHO the credential was minted for: the paired client that served the ceremony.
+    client_id: typeof clientId === 'string' && clientId ? clientId : null,
+    // WHO claimed to ask (self-asserted, audit label only — mirrors §10.6).
+    agent_id: typeof agentId === 'string' && agentId ? agentId : null,
+    mandate_digest: digest,
+    grant_count: grants,
+    mandate_expires_at: typeof mandate?.expires_at === 'string' ? mandate.expires_at : null,
+  };
+}
+
+let _chain = Promise.resolve();
+/**
+ * Append a signing-audit record. Serialized per process (like receipts) so two concurrent
+ * signs can't clobber the store. Best-effort by contract at the call site: a failed audit
+ * write must never make a real signature look unsigned — the caller logs and continues.
+ */
+export async function appendSigningAudit(stateDir, record, { cap = DEFAULT_CAP, now = Date.now() } = {}) {
+  _chain = _chain.then(async () => {
+    const store = await readStore(stateDir).catch(() => ({ records: [] }));
+    store.records.push(record);
+    if (store.records.length > cap) store.records = store.records.slice(-cap);
+    await writeStore(stateDir, store, now);
+  });
+  return _chain;
+}
+
+export async function readSigningAudit(stateDir) {
+  return (await readStore(stateDir).catch(() => ({ records: [] }))).records;
+}

package/signing-request.js

@@ -0,0 +1,217 @@
+// §8.3 signing ceremony — the MCP (server) half of the round-trip.
+//
+// The server holds the mandate; the phone holds the only key that can sign it. This module
+// deposits a SIGN REQUEST for the subject, polls for the signed result, and VERIFIES it —
+// reusing the escalation transport (relay lane, envelope crypto, first-answer-wins,
+// push-to-wake) but NOT its semantics. An escalation answer is approve/deny/modify — a
+// decision internal to the subject's system. A signature is a credential asserted to a
+// third party. Conflating them is the §10.2 action_binding failure mode one layer up, so
+// the request carries a distinct `kind` and the response is a signature or an explicit
+// refusal, never a decision verb.
+//
+// SIGN WHAT YOU SEE. The request carries the mandate OBJECT, not pre-computed bytes. The
+// phone renders that object AND derives the signing input from it, so it cannot be shown
+// one thing and made to sign another. The server re-derives the same bytes here and
+// verifies against them, which independently confirms the phone signed the mandate the
+// server actually built.
+
+import { Phaedo, b64uDec } from './lib/phaedo-crypto.js';
+import { signingInput, verifyEs256 } from './signing.js';
+
+const { Kdf, Envelope } = Phaedo;
+const DEFAULT_RELAY = 'https://phaedo-relay.fly.dev';
+
+const SIGN_REQUEST_KIND = 'sign_request';
+const SIGN_RESPONSE_KIND = 'sign_response';
+// AP2 mandates omit `signature` from the signing input (the field the signature fills).
+const AP2_SIGNATURE_FIELD = 'signature';
+
+export function relayBaseFromEnv(env = process.env) {
+  // PHAEDO_RELAY is the name every other lane reads (escalation, receipts, capture, delegation).
+  // This one read PHAEDO_RELAY_URL alone, so a self-hosted relay silently did NOT cover the §8.3
+  // signing ceremony — sign requests kept going to the default host. The old name is still
+  // honoured so an existing setup does not break.
+  return env.PHAEDO_RELAY || env.PHAEDO_RELAY_URL || DEFAULT_RELAY;
+}
+
+function relayAuthHeader(pairing) {
+  const id = pairing && pairing.relay_device_id;
+  const secret = pairing && pairing.relay_device_secret;
+  return id && secret ? { authorization: `Bearer ${id}:${secret}` } : {};
+}
+
+function genRequestId() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID();
+  return `sig-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Build the encrypted SIGN REQUEST deposit body. Sealed under fp_sync_key, exactly like an
+ * escalation request, and posted to the same relay lane — the phone routes on `kind`.
+ * `mandate` is the object to be signed (unsigned; the `signature` field stays null/absent).
+ */
+export async function buildSignRequestDeposit(pairKeyB64u, requestId, mandate, { windowMs, now = () => new Date().toISOString() } = {}) {
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try {
+    fpSyncKey = await Kdf.deriveFpSyncKey(pairKey);
+  } finally {
+    pairKey.fill(0);
+  }
+  try {
+    const inner = { kind: SIGN_REQUEST_KIND, request_id: requestId, data: { mandate } };
+    const plaintext = new TextEncoder().encode(JSON.stringify(inner));
+    const envelope = await Envelope.wrap(plaintext, fpSyncKey, { artifact_kind: SIGN_REQUEST_KIND, created_at: now() });
+    plaintext.fill(0);
+    return { request_id: requestId, envelope, ...(windowMs ? { window_ms: windowMs } : {}) };
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+/**
+ * Decrypt the phone's SIGN RESPONSE. Returns the inner data — either
+ * `{ signature, encoding, signed_at }` or `{ refused: true, reason? }` — or null on any
+ * failure. A malformed or forged response must never crash the agent's resume path.
+ */
+export async function unwrapSignResponse(pairKeyB64u, body) {
+  if (!body || !body.envelope) return null;
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try {
+    fpSyncKey = await Kdf.deriveFpSyncKey(pairKey);
+  } catch { pairKey.fill(0); return null; }
+  pairKey.fill(0);
+  try {
+    const plaintext = await Envelope.unwrap(body.envelope, fpSyncKey);
+    const inner = JSON.parse(new TextDecoder().decode(plaintext));
+    if (inner && inner.kind === SIGN_RESPONSE_KIND && inner.data) return inner.data;
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+/**
+ * Verify a signed mandate. The mandate is re-canonicalized here (signature field omitted)
+ * and checked against the subject's published signing key — so a valid result means BOTH
+ * that the signature is genuine AND that the phone signed the exact mandate the server
+ * built. Returns { verified, reason? }.
+ *
+ * `signingPublicKey` is the base64 X9.63 point from `phaedo_signing_public_key` (published
+ * over the trusted pairing, §8.3 step 2). If it is missing, verification cannot proceed —
+ * that is distinct from a bad signature and is reported as such.
+ */
+export function verifySignedMandate({ mandate, signature, encoding = 'der', signingPublicKey }) {
+  if (!signingPublicKey) return { verified: false, reason: 'no-published-signing-key' };
+  if (typeof signature !== 'string' || !signature) return { verified: false, reason: 'no-signature' };
+  let sigBytes, keyBytes;
+  try {
+    sigBytes = Buffer.from(signature, 'base64');
+    keyBytes = Buffer.from(signingPublicKey, 'base64');
+  } catch {
+    return { verified: false, reason: 'undecodable' };
+  }
+  try {
+    const verified = verifyEs256({
+      payload: mandate,
+      signature: sigBytes,
+      publicKey: keyBytes,
+      encoding,
+      field: AP2_SIGNATURE_FIELD,
+    });
+    return verified ? { verified: true } : { verified: false, reason: 'signature-mismatch' };
+  } catch (e) {
+    // A malformed KEY (not a bad signature) throws in the core; surface it as its own
+    // reason rather than reporting "not the subject's signature".
+    return { verified: false, reason: `key-error:${String(e && e.message || e)}` };
+  }
+}
+
+/** The exact bytes the phone is asked to sign — exported so a caller/test can assert the
+ *  server and phone agree on them. */
+export function mandateSigningInput(mandate) {
+  return signingInput(mandate, { field: AP2_SIGNATURE_FIELD });
+}
+
+/**
+ * Deposit a SIGN REQUEST and wake the device. Returns
+ * { deposited, request_id, window_ms, expires_at } or { deposited:false, reason }.
+ */
+export async function depositSignRequest(pairing, mandate, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  if (!pairing || !pairing.pair_key) return { deposited: false, reason: 'unpaired' };
+  if (!pairing.relay_device_id) return { deposited: false, reason: 'no-relay-device-id' };
+  if (!mandate || typeof mandate !== 'object') return { deposited: false, reason: 'no-mandate' };
+  // A mandate that already carries a signature must not be re-sent for signing.
+  if (mandate.signature != null) return { deposited: false, reason: 'already-signed' };
+
+  const windowMs = Math.max(1000, Number(deps.windowMs) || 5 * 60 * 1000);
+  const relayBase = deps.relayBase || relayBaseFromEnv();
+  const requestId = deps.requestId || genRequestId();
+  try {
+    const body = await buildSignRequestDeposit(pairing.pair_key, requestId, mandate, { windowMs });
+    const res = await fetchFn(`${relayBase}/escalation/${encodeURIComponent(pairing.relay_device_id)}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...relayAuthHeader(pairing) },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(deps.depositTimeoutMs || 8000),
+    });
+    if (!res || !res.ok) return { deposited: false, reason: `deposit-failed-${res && res.status}`, request_id: requestId };
+    let info = {};
+    try { info = await res.json(); } catch { /* body optional */ }
+    return { deposited: true, request_id: requestId, window_ms: windowMs, expires_at: info.expires_at, woke: info.woke };
+  } catch (e) {
+    return { deposited: false, reason: `deposit-error:${String(e && e.message || e)}`, request_id: requestId };
+  }
+}
+
+/**
+ * Poll ONCE for a signed mandate. Returns:
+ *   { resolved:true, signed:true, mandate }             — signature verified; mandate now carries it
+ *   { resolved:true, signed:false, reason:'refused' }   — the subject declined to sign
+ *   { resolved:true, signed:false, reason:'verify-failed', detail } — a response arrived but did not verify
+ *   { resolved:false, status:'pending' | 'expired' }
+ * Never throws. A verify failure is resolved-but-unsigned, never silently treated as signed.
+ */
+export async function pollSignOnce(pairing, requestId, mandate, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  if (!pairing || !pairing.pair_key || !requestId) return { resolved: false, status: 'expired', reason: 'bad-args' };
+  if (deps.expiresAt && (deps.now ? deps.now() : Date.now()) > deps.expiresAt) return { resolved: false, status: 'expired' };
+  const relayBase = deps.relayBase || relayBaseFromEnv();
+  let body = null;
+  try {
+    const res = await fetchFn(`${relayBase}/escalation/response/${encodeURIComponent(requestId)}`, {
+      headers: relayAuthHeader(pairing),
+      signal: AbortSignal.timeout(deps.pollTimeoutMs || 8000),
+    });
+    if (res && res.ok) body = await res.json();
+  } catch { /* transient */ }
+  if (!body) return { resolved: false, status: 'pending' };
+
+  const data = await unwrapSignResponse(pairing.pair_key, body);
+  if (!data) return { resolved: false, status: 'pending' };   // undecryptable → keep waiting, don't crash
+
+  if (data.refused === true) {
+    return { resolved: true, signed: false, reason: 'refused', request_id: requestId };
+  }
+
+  const check = verifySignedMandate({
+    mandate,
+    signature: data.signature,
+    encoding: data.encoding || 'der',
+    signingPublicKey: deps.signingPublicKey,
+  });
+  if (!check.verified) {
+    return { resolved: true, signed: false, reason: 'verify-failed', detail: check.reason, request_id: requestId };
+  }
+  return {
+    resolved: true,
+    signed: true,
+    request_id: requestId,
+    mandate: { ...mandate, signature: data.signature, signature_encoding: data.encoding || 'der',
+               signed_at: typeof data.signed_at === 'string' ? data.signed_at : undefined },
+  };
+}