phaedo-mcp 0.2.2 → 0.3.0

package/receipts.js

@@ -25,7 +25,9 @@ import { mkdir, readFile, writeFile, chmod, rename } from 'fs/promises';
 import { existsSync } from 'fs';
 import { join } from 'path';
 import { Phaedo, b64uEnc, b64uDec } from './lib/phaedo-crypto.js';
+import { canonicalDomain } from './lib/domain.js';
 import { getOrCreateCacheKey, defaultStateDir } from './cache.js';
+import { normalizeActionBinding } from './action-binding.js';
 
 const { Envelope } = Phaedo;
 
@@ -105,11 +107,17 @@ function withStoreLock(stateDir, fn) {
 // never the projection (§10.4 holds inside the vault too). `via` records which
 // tool resolved it (phaedo_consult | phaedo_check_authorization) so M5 can weigh
 // full consultations and pre-flight matches separately.
-export function buildReceipt({ via, agentId, request, response, drivers, now = Date.now() }) {
+export function buildReceipt({ via, agentId, clientId, request, response, drivers, now = Date.now() }) {
   const ad = (request && typeof request.action_descriptor === 'object' && request.action_descriptor) || {};
   // Provenance (optional, §10.4-safe — LOCAL audit only): the Decision&Risk cues that
   // drove an inferred consult, each {cue, lean?/value?, confidence, basis}. No layer
   // text; coerced to the known shape; absent for deterministic pre-flights.
+  // Defensive: a malformed binding must not fail the receipt write (a receipt-write
+  // failure must never break the consultation — §10.6). The resolver has already
+  // rejected structurally-bad bindings with `request_malformed`, so anything that
+  // throws here is a caller bypassing it; record nothing rather than half of it.
+  let bnd = null;
+  try { bnd = normalizeActionBinding(request?.action_binding); } catch { bnd = null; }
   const drv = Array.isArray(drivers) ? drivers.slice(0, 16).map((d) => ({
     cue: typeof d?.cue === 'string' ? d.cue : null,
     ...(typeof d?.lean === 'number' ? { lean: d.lean } : {}),
@@ -121,16 +129,33 @@ export function buildReceipt({ via, agentId, request, response, drivers, now = D
     receipt_id: crypto.randomUUID(),
     created_at: new Date(now).toISOString(),
     via: via || 'phaedo_consult',
+    // WHO CLAIMED to be calling. Self-asserted, unverified, and never a gate — the
+    // same standing `action_descriptor` was given in v0.1.48. Audit label only.
     agent_id: typeof agentId === 'string' ? agentId : null,
+    // WHO ACTUALLY SERVED the call: this server's own paired-client id, established
+    // out-of-band with the phone under a user-verified SAS. This is the identity
+    // §10.5 `agents` scoping matches on, so the audit can distinguish which paired
+    // client acted from whichever vendor string it chose to claim. Null = unpaired.
+    client_id: typeof clientId === 'string' && clientId ? clientId : null,
     request: {
       consultation_type: request?.consultation_type || 'action_approval',
       action_descriptor: {
-        domain: typeof ad.domain === 'string' ? ad.domain : null,
+        // Canonical form, matching what the resolver reasoned about (lib/domain.js).
+        // The receipt is the evidence store the promotion tallies key on, so a raw
+        // `"Finance"` here would be a class of its own and split the subject's
+        // approvals away from `"finance"`.
+        domain: typeof ad.domain === 'string' ? (canonicalDomain(ad.domain) || null) : null,
         reversible: typeof ad.reversible === 'boolean' ? ad.reversible : null,
         magnitude: typeof ad.magnitude === 'string' ? ad.magnitude : null,
         amount: typeof ad.amount === 'number' ? ad.amount : null,
         summary: typeof ad.summary === 'string' ? ad.summary.slice(0, 500) : null,
       },
+      // §10.2 binding: the concrete call the descriptor above CLAIMS to describe.
+      // This is the field that makes a descriptor/action mismatch provable later —
+      // the descriptor is the agent's story, this is what it said it would run.
+      // Never the arguments themselves: a digest, the tool name, and at most a
+      // short human preview.
+      ...(bnd ? { action_binding: bnd } : {}),
     },
     response: {
       signal: response?.signal ?? null,
@@ -164,6 +189,12 @@ export async function updateUserAction(stateDir, receiptId, action, { now = Date
     const r = store.receipts.find((x) => x.receipt_id === receiptId);
     if (!r) return false;
     r.user_action = action;
+    // WHEN the outcome was recorded, alongside WHAT it was. Not decision latency —
+    // the subject may mark in a later sitting — but it does reveal a screenful of
+    // receipts stamped in one pass, which §10.7 autonomy promotion treats as
+    // bookkeeping rather than deliberate consent. Mutable with `user_action`, and
+    // only with it (§10.6: user_action is the sole mutable field; this is part of it).
+    r.user_action_at = new Date(now).toISOString();
     await writeStore(stateDir, store, now);
     return true;
   });

package/server.js

@@ -16,12 +16,16 @@ import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
-import { loadFingerprint, loadFingerprintPreferCache } from './fingerprint-source.js';
-import { hasPairingRecord, loadPairingRecord } from './phone-source.js';
+import { loadFingerprint, loadFingerprintPreferCache, sourceOf } from './fingerprint-source.js';
+import { hasPairingRecord, loadPairingRecord, readServingClientId } from './phone-source.js';
 import { depositDelegationSuggestions } from './delegation-sync.js';
 import { depositReceiptsDigest, drainAndApplyMarks } from './receipts-sync.js';
 import { buildDelegationPromotions } from './consult-core.js';
+import { buildAutonomyPromotions } from './autonomy-promotion.js';
 import { depositEscalation, pollEscalationOnce, shouldEscalate, loadEscalationPolicy } from './escalation.js';
+import { buildIntentMandatePayload } from './ap2.js';
+import { depositSignRequest, pollSignOnce } from './signing-request.js';
+import { buildSigningAuditRecord, appendSigningAudit } from './signing-audit.js';
 import { buildInjectionResponse, errorResponse, PhaedoError } from './projection.js';
 import { resolveConsultation, checkAuthorization, consultOptsFromEnv, CONSULTATION_TYPES, consultDrivers, deriveDelegationSignals, withDelegationSignals, authoredDelegationSignals } from './consult.js';
 import { defaultStateDir } from './cache.js';
@@ -35,11 +39,53 @@ const BASE_DIR = dirname(fileURLToPath(import.meta.url));
 const RECEIPTS_CAP = receiptsCapFromEnv(process.env);
 async function emitReceipt(via, args, response, drivers) {
   try {
-    const receipt = buildReceipt({ via, agentId: args?.agent_id, request: args, response, drivers });
+    // `clientId` is what the audit can actually rely on: the paired client that
+    // SERVED this call, versus `agentId` — the vendor string the caller claimed.
+    // Recording both is the point; they are believed to different degrees.
+    const receipt = buildReceipt({ via, agentId: args?.agent_id, clientId: CONSULT_OPTS.clientId, request: args, response, drivers });
     await appendReceipt(defaultStateDir(), receipt, { cap: RECEIPTS_CAP });
+    // RETURN THE HANDLE. The tool descriptions instruct the agent to record what the subject
+    // decided, but no tool gave it anything to name — so `phaedo_record_outcome` defaulted to
+    // 'latest' and attributed the decision to whatever receipt happened to be newest. A $12k
+    // payment rejection landed on an unrelated writing consult. That feeds deriveDelegationSignals
+    // and the §10.7 promotion evidence, so a mis-attributed override both erodes caution on the
+    // wrong dimension AND removes the contrary evidence that would have disqualified the right one.
+    return receipt.receipt_id;
   } catch (e) {
     process.stderr.write(`[phaedo-mcp] receipt write failed (consultation still answered): ${e.message}\n`);
   }
+  return null;
+}
+
+// Effects that let an agent act with LESS oversight. Only these are withheld when the read
+// is stale; a restrictive effect keeps applying, because a guardrail the subject may since
+// have removed still fails in the safe direction.
+const EXPANDING_SIGNALS = new Set(['proceed', 'autoproceed', 'bias_bold']);
+
+/**
+ * Downgrade an authority-EXPANDING answer that was computed from a stale (cached) read.
+ * Returns the response unchanged for a live read, or for any answer that already defers.
+ * Always annotates provenance so the caller can SAY where the answer came from — the
+ * silence is what let a stale "you're authorized" go unnoticed for a day.
+ */
+function withStaleAuthorityGuard(response, vd) {
+  const src = sourceOf(vd);
+  const out = { ...response };
+  const hours = src.ageMs != null ? Math.round(src.ageMs / 3600000) : null;
+  out.profile_source = src.live
+    ? { live: true }
+    : { live: false, cached_age_hours: hours, note: 'Answered from a cached profile — the subject\'s device could not be reached.' };
+  if (src.live) return out;
+  if (!EXPANDING_SIGNALS.has(String(response?.signal))) return out;
+
+  out.signal = 'escalate';
+  out.authorization_matched = false;
+  out.stale_downgrade = true;
+  out.rationale_hint =
+    `Withheld: this would have proceeded automatically, but the decision was computed from a cached copy of the ` +
+    `subject's profile${hours != null ? ` about ${hours}h old` : ''} because their device could not be reached. ` +
+    `A pre-approval that may since have been revoked must not be acted on unattended — ask the subject.`;
+  return out;
 }
 
 // Load the fingerprint for a consult and fold in the act-as-me channel: delegation
@@ -115,16 +161,26 @@ async function maybePullPhoneMarks() {
 async function maybeDepositDelegationPromotions(vd) {
   try {
     if (!hasPairingRecord(BASE_DIR)) return;                       // no extension to deposit to
-    const promos = buildDelegationPromotions(await readReceipts(defaultStateDir()), (vd && vd.phaedo_fingerprint) || {});
+    const receipts = await readReceipts(defaultStateDir());
+    const fp = (vd && vd.phaedo_fingerprint) || {};
+    // Two channels over one deposit. Delegation promotions learn from the subject's
+    // DISAGREEMENTS and can only make the agent more deferential; autonomy promotions
+    // (§10.7) learn from deliberate, repeated AGREEMENT and are the only channel that
+    // can propose less friction — bounded, binding-gated and expiring, and still only
+    // a proposal the subject endorses.
+    const promos = buildDelegationPromotions(receipts, fp)
+      .concat(buildAutonomyPromotions(receipts, fp));
     if (!promos.length) return;
-    const sig = promos.map(p => `${p.decision?.dimension}|${p.decision?.domain || ''}|${p.decision?.value}`).sort().join(',');
+    const sig = promos.map(p => p.source === 'autonomy_promotion'
+      ? `auto|${(p.match?.domains || []).join('+')}|${p.match?.magnitude_max}`
+      : `${p.decision?.dimension}|${p.decision?.domain || ''}|${p.decision?.value}`).sort().join(',');
     if (sig === _lastDepositSig) return;                           // identical set already deposited — skip the relay round-trip
     const res = await depositDelegationSuggestions(await loadPairingRecord(BASE_DIR), promos);
     if (res && res.deposited) _lastDepositSig = sig;               // latch only on success, so a failed deposit retries next consult
     else if (res && !res.deposited)                                // promotions existed but didn't land — say why (don't fail silently)
-      process.stderr.write(`[phaedo-mcp] ${promos.length} delegation promotion(s) ready but deposit skipped: ${res.reason || 'http ' + res.status}${res.reason === 'no-relay-device-id' ? ' — pairing has no relay lane (local-only pairing)' : ''}\n`);
+      process.stderr.write(`[phaedo-mcp] ${promos.length} rule promotion(s) ready but deposit skipped: ${res.reason || 'http ' + res.status}${res.reason === 'no-relay-device-id' ? ' — pairing has no relay lane (local-only pairing)' : ''}\n`);
   } catch (e) {
-    process.stderr.write(`[phaedo-mcp] delegation promotion deposit skipped: ${e.message}\n`);
+    process.stderr.write(`[phaedo-mcp] rule promotion deposit skipped: ${e.message}\n`);
   }
 }
 
@@ -145,6 +201,11 @@ if (existsSync(POLICIES_PATH)) {
   try { CONSULT_OPTS.policies = JSON.parse(readFileSync(POLICIES_PATH, 'utf8')); }
   catch (e) { process.stderr.write(`[phaedo-mcp] ignoring malformed consult policies (${POLICIES_PATH}): ${e.message}\n`); }
 }
+// §10.5 `agents`: this process's OWN paired-client identity, resolved once at startup.
+// One server serves one paired client, so it never asks a caller who is calling — it
+// reads who it IS. Null (unpaired / unreadable) makes `agents`-scoped RELAXING rules
+// inert, which is the fail-safe direction; the server still answers everything else.
+CONSULT_OPTS.clientId = readServingClientId(BASE_DIR);
 
 // Escalation PUSH policy (which signals wake the subject): the subject-configurable knob
 // over the stakes-gated default. Local file (PHAEDO_ESCALATION_POLICY, else
@@ -157,7 +218,12 @@ if (existsSync(ESCALATION_POLICY_PATH)) {
   catch (e) { process.stderr.write(`[phaedo-mcp] ignoring malformed escalation policy (${ESCALATION_POLICY_PATH}): ${e.message}\n`); }
 }
 
-const server = new McpServer({ name: 'phaedo', version: '0.2.2' });
+// Read from package.json rather than a literal: this string was pinned at '0.2.2'
+// while package.json moved on, so the handshake advertised a version that had not
+// been the package's for two months. One source of truth; test-package-closure.mjs
+// asserts the two agree.
+const PKG_VERSION = JSON.parse(readFileSync(join(BASE_DIR, 'package.json'), 'utf8')).version;
+const server = new McpServer({ name: 'phaedo', version: PKG_VERSION });
 
 // ── Tool: phaedo_request_injection (binding §3.1) ─────────────────────────────
 server.registerTool(
@@ -172,6 +238,7 @@ server.registerTool(
       session_context: z
         .object({
           platform: z.string().optional(),
+          domain: z.string().optional(),
           task_hint: z.string().optional(),
           audience_hint: z.string().optional(),
           max_tokens: z.number().optional(),
@@ -205,6 +272,24 @@ server.registerTool(
   }
 );
 
+// §10.2 `action_binding` — the concrete call the action_descriptor claims to
+// describe. Optional and back-compatible: an unbound request resolves exactly as
+// before. Shared by phaedo_consult / phaedo_check_authorization / phaedo_escalate
+// so the three can't drift. See mcp/action-binding.js for why this exists.
+const ACTION_BINDING_SCHEMA = z
+  .object({
+    tool_name: z.string().describe('The tool/function the agent is about to invoke.'),
+    arguments_hash: z.string().describe('Hex or base64url digest over the RFC 8785 canonical form of the arguments. Never the arguments themselves.'),
+    arguments_preview: z.string().optional().describe('Optional short human-readable summary of the arguments, shown to the subject on an escalation.'),
+  })
+  .optional()
+  .describe(
+    'Binds this consultation to the concrete call it describes. The action_descriptor is your ACCOUNT of the action; ' +
+    'this is the action. Recorded on the audit receipt so a later mismatch is provable, shown to the subject when an ' +
+    'escalation reaches their phone, and REQUIRED by any standing rule the subject marked require_binding before it ' +
+    'will auto-proceed.',
+  );
+
 // ── Tool: phaedo_consult (binding §3.2, spec §10) ─────────────────────────────
 // Agent consultation: query the fingerprint at a decision point and get back a
 // constrained SIGNAL (§10.3) — never layer content (§10.4 boundary). One tool,
@@ -235,6 +320,7 @@ server.registerTool(
           summary: z.string().optional(),
         })
         .optional(),
+      action_binding: ACTION_BINDING_SCHEMA,
       context: z.record(z.any()).optional(),
     },
     // Not read-only: appends a local §10.6 audit receipt and may best-effort deposit a
@@ -244,12 +330,18 @@ server.registerTool(
   async (args) => {
     try {
       const vd = await loadConsultVd(BASE_DIR);   // fingerprint + act-as-me delegation overlay
-      const response = await resolveConsultation(vd, args || {}, CONSULT_OPTS);
+      // STALE-AUTHORITY GUARD. This used to be applied to phaedo_check_authorization ALONE, so
+      // the two tools an autonomous agent actually uses answered from a possibly-revoked cached
+      // profile with no downgrade and no provenance. That is the 2026-07-25 device defect (a
+      // revoked $500 grant honoured from a 22h cache) still live on the paths that matter most.
+      const response = withStaleAuthorityGuard(
+        await resolveConsultation(vd, args || {}, CONSULT_OPTS), vd);
       // Provenance for the local audit receipt only — the cues that drove this
       // (never in `response`; §10.4). Best-effort: a failure must not block the answer.
       let drivers = [];
       try { drivers = consultDrivers(vd, args || {}); } catch { /* provenance is non-critical */ }
-      await emitReceipt('phaedo_consult', args, response, drivers); // every resolution, abstains included
+      const receiptId = await emitReceipt('phaedo_consult', args, response, drivers); // every resolution, abstains included
+      if (receiptId) response.receipt_id = receiptId;   // the handle for phaedo_record_outcome
       await maybeDepositDelegationPromotions(vd);                    // act-as-me promotion (best-effort)
       await maybeDepositReceiptsDigest();                            // G1+G2 audit channel — refresh the phone's view
       return {
@@ -298,6 +390,7 @@ server.registerTool(
           summary: z.string().optional(),
         })
         .optional(),
+      action_binding: ACTION_BINDING_SCHEMA,
     },
     // Deterministic pre-flight; appends a local audit receipt. Non-destructive, device-local.
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
@@ -306,12 +399,26 @@ server.registerTool(
     try {
       const req = { consultation_type: 'action_approval', ...(args || {}) };
       const vd = await loadFingerprint(BASE_DIR);
-      const response = checkAuthorization(vd, req, CONSULT_OPTS);
+      // STALENESS MAY NOT EXPAND AUTONOMY. When the live pull failed we are answering from
+      // an at-rest cache that predates anything the subject has changed since — including a
+      // REVOCATION. Observed on device 2026-07-25: a revoked $500 payment grant kept
+      // returning "authorized" from a 22-hour-old copy. A stale read may still make an agent
+      // MORE deferential (that direction is safe and useful phone-absent); it may never be
+      // the basis for proceeding unattended. Same asymmetry as `expires_at`, `require_binding`
+      // and the §10.2 domain aliases: narrow freely, widen never.
+      // The receipt is gated on `authorization_matched`, which the guard CLEARS — so the one
+      // case that most needs an audit trail (an authorization fired against a possibly-revoked
+      // cached grant and had to be withheld) used to leave no record at all. §10.6: "a matched
+      // deterministic pre-flight is a resolution and produces a receipt."
+      const preGuard = checkAuthorization(vd, req, CONSULT_OPTS);
+      const matchedPreGuard = preGuard.authorization_matched === true;
+      const response = withStaleAuthorityGuard(preGuard, vd);
       // A matched pre-flight IS a resolved decision (the authorization fired) →
       // receipt. A no-match is not a decision — no receipt (keeps the store from
       // filling with probes; the follow-up phaedo_consult writes its own).
-      if (response.authorization_matched) {
-        await emitReceipt('phaedo_check_authorization', req, { signal: response.signal, confidence: 1.0, deference_level: 'high' });
+      if (matchedPreGuard) {
+        const rid = await emitReceipt('phaedo_check_authorization', req, { signal: response.signal, confidence: 1.0, deference_level: 'high' });
+        if (rid) response.receipt_id = rid;
         await maybeDepositReceiptsDigest();                          // G1+G2 audit channel — only on a matched preflight (no-match writes no receipt)
       }
       return {
@@ -423,6 +530,7 @@ server.registerTool(
           summary: z.string().optional(),
         })
         .optional(),
+      action_binding: ACTION_BINDING_SCHEMA,
       context: z.record(z.any()).optional(),
     },
     // Opens a channel to an EXTERNAL entity (the subject's device, via the relay) and
@@ -435,10 +543,15 @@ server.registerTool(
       // Cache-preferred read: escalation shouldn't trigger a fingerprint-read authorize
       // prompt on top of the decision card the subject already answers (one prompt, not two).
       const vd = await loadConsultVd(BASE_DIR, { preferCache: true });
-      const response = await resolveConsultation(vd, req, CONSULT_OPTS);
+      // Guarded like the others, and it needs it MOST: this path reads the cache
+      // UNCONDITIONALLY, so without the guard it always reasoned from a possibly-stale profile
+      // and then told the agent the signal was not blocking — i.e. "just proceed", and never
+      // wake the subject, on authority that may have been revoked hours earlier.
+      const response = withStaleAuthorityGuard(
+        await resolveConsultation(vd, req, CONSULT_OPTS), vd);
       let drivers = [];
       try { drivers = consultDrivers(vd, req); } catch { /* non-critical */ }
-      await emitReceipt('phaedo_escalate', req, response, drivers);   // the decision being escalated
+      const escReceiptId = await emitReceipt('phaedo_escalate', req, response, drivers);   // the decision being escalated
       await maybeDepositReceiptsDigest();                              // G1+G2 audit channel
 
       // Self-gate: only wake the subject for a genuinely blocking signal. `escalate`
@@ -451,6 +564,7 @@ server.registerTool(
         const body = {
           request_type: 'escalation', escalated: false, signal: response.signal,
           rationale_hint: response.rationale_hint, confidence: response.confidence,
+          ...(escReceiptId ? { receipt_id: escReceiptId } : {}),
           ...(subThresholdClarify ? { reason: 'clarify_below_threshold' } : {}),
           message: subThresholdClarify
             ? 'Low-stakes clarification — handle it in your own flow (ask your clarifying question, or make a reasonable assumption and state it). It will surface in the user\'s review queue; no need to wake them. Raise an explicit escalate if you truly need a live decision.'
@@ -464,6 +578,11 @@ server.registerTool(
       const body = dep.deposited
         ? {
             request_type: 'escalation', escalated: true, status: 'pending',
+            // Both handles. `request_id` correlates the live decision; `receipt_id` names the
+            // §10.6 record to mark afterwards. Returning only the first meant
+            // phaedo_escalation_status could not mark correctly and a real-time approve/deny was
+            // auto-recorded onto whatever receipt happened to be newest.
+            ...(escReceiptId ? { receipt_id: escReceiptId } : {}),
             request_id: dep.request_id, window_ms: dep.window_ms, expires_at: dep.expires_at,
             signal: response.signal, rationale_hint: response.rationale_hint,
             // The relay's push-to-wake result for a BACKGROUNDED phone: { sent, reason }.
@@ -555,6 +674,177 @@ server.registerTool(
   }
 );
 
+// ── Tool: phaedo_sign_mandate (§8.3 signing ceremony) ─────────────────────────
+// Ask the subject to SIGN an AP2 Intent Mandate built from their standing authorizations.
+// Two-call shape like escalation: this deposits the request and returns immediately with a
+// request_id + the mandate; the agent then polls phaedo_sign_status. The subject signs on
+// their phone inside the Secure Enclave (the server never holds the key). Until a signature
+// comes back the mandate is a PROPOSAL, never a credential — do not present it as authorized.
+const SIGN_WINDOW_MS = 5 * 60 * 1000;
+
+server.registerTool(
+  'phaedo_sign_mandate',
+  {
+    title: 'Ask the subject to sign a payment authorization (AP2 Intent Mandate)',
+    description:
+      'Request the subject\'s cryptographic signature on an AP2 Intent Mandate built from their ' +
+      'standing authorizations — a credential a merchant or payments network can verify. Returns a ' +
+      'request_id and the unsigned mandate immediately; then poll phaedo_sign_status with BOTH, and ' +
+      'DO NOT treat the mandate as authorized until it returns signed. The subject signs on their ' +
+      'phone (Face ID, key in the Secure Enclave); they may also decline. Use only when you need a ' +
+      'verifiable payment credential — not for ordinary consultations.',
+    inputSchema: {
+      agent_id: z.string().optional(),
+      prompt_playback: z.string().optional(),  // your stated understanding of the request (AP2)
+    },
+    // Reaches the subject's device via the relay; read-only w.r.t. local state (no receipt yet).
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  },
+  async (args) => {
+    try {
+      const vd = await loadConsultVd(BASE_DIR, { preferCache: true });
+      const fp = (vd && vd.phaedo_fingerprint) || {};
+      const mandate = buildIntentMandatePayload(fp, {
+        agentId: args?.agent_id ?? null,
+        promptPlayback: args?.prompt_playback ?? null,
+      });
+      if (!mandate) {
+        const body = {
+          request_type: 'sign_mandate', status: 'nothing_to_sign',
+          message: 'The subject has granted no standing authorizations, so there is nothing to sign. ' +
+                   'An empty mandate must never be synthesized — it would read as unlimited authority.',
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: body };
+      }
+
+      // Make sure we hold the subject's signing key BEFORE the sheet goes up.
+      //
+      // Verification needs the published key. Fetching it lazily at poll time meant a live
+      // fingerprint pull fired WHILE the signing sheet was on screen — which puts an
+      // authorize card up right as that sheet dismisses, and iOS kills the app when two of
+      // these sheets overlap ("already presenting"; the nav layer warns about exactly this).
+      // Observed on device: the ceremony completed, then the app crashed and the pull that
+      // would have supplied the key died with it, so a genuine signature came back
+      // unverifiable. Pulling here is free of that hazard — no sheet exists yet — and it
+      // also fails fast, before the subject is asked to sign something we could not check.
+      if (!(vd && vd.phaedo_signing_public_key)) {
+        try { await loadConsultVd(BASE_DIR); } catch { /* best-effort; poll still retries */ }
+      }
+
+      const pairing = await loadPairingRecord(BASE_DIR);
+      const dep = await depositSignRequest(pairing, mandate, { windowMs: SIGN_WINDOW_MS });
+      const body = dep.deposited
+        ? {
+            request_type: 'sign_mandate', status: 'pending',
+            request_id: dep.request_id, window_ms: dep.window_ms, expires_at: dep.expires_at, woke: dep.woke,
+            mandate,
+            message: 'Sent to the subject to sign. Poll phaedo_sign_status with this request_id AND this ' +
+                     'mandate; do not treat it as authorized until it returns signed. If it expires or the ' +
+                     'subject declines, the mandate stays an unsigned proposal.',
+          }
+        : {
+            request_type: 'sign_mandate', status: 'unreachable', reason: dep.reason,
+            message: dep.reason === 'no-relay-device-id' || dep.reason === 'unpaired'
+              ? 'No real-time channel to the subject (no paired device with a relay lane). Cannot obtain a signature.'
+              : 'Could not reach the subject right now. The mandate remains an unsigned proposal.',
+          };
+      return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: body };
+    } catch (err) {
+      const code = err instanceof PhaedoError ? err.code : 'internal_error';
+      return { content: [{ type: 'text', text: `Phaedo sign-mandate error [${code}]: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── Tool: phaedo_sign_status ──────────────────────────────────────────────────
+// Poll a signing request opened with phaedo_sign_mandate. The `mandate` returned by that
+// call is passed back here to verify against — a tampered mandate simply fails verification
+// (the phone signed only what it displayed), so round-tripping it is safe and restart-proof.
+server.registerTool(
+  'phaedo_sign_status',
+  {
+    title: 'Check whether the subject has signed the mandate',
+    description:
+      'Poll a request from phaedo_sign_mandate. Pass the request_id AND the mandate that call returned. ' +
+      'Returns signed + the mandate carrying the verified signature once the subject signs, refused if ' +
+      'they declined, pending while you should keep waiting, or expired once the window lapsed. A signed ' +
+      'result is verified against the subject\'s published signing key before it is returned.',
+    inputSchema: {
+      request_id: z.string(),
+      mandate: z.record(z.any()),
+      expires_at: z.number().optional(),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  },
+  async (args) => {
+    try {
+      const vd = await loadConsultVd(BASE_DIR, { preferCache: true });
+      let signingPublicKey = vd && vd.phaedo_signing_public_key;
+      // NOTE: no live pull here, deliberately. A live pull raises an authorize card on the
+      // phone, and this runs while the signing sheet may still be dismissing — overlapping
+      // sheets crash iOS ("already presenting"), which is exactly how a good signature was
+      // lost on device. The key is fetched at DEPOSIT time instead (see phaedo_sign_mandate),
+      // where no sheet exists. If it is still missing here, report that honestly rather than
+      // interrupting the subject mid-ceremony to fix it.
+      const pairing = await loadPairingRecord(BASE_DIR);
+      const r = await pollSignOnce(pairing, args.request_id, args.mandate, {
+        expiresAt: args.expires_at, signingPublicKey,
+      });
+
+      // A stale key (the subject rotated their signing identity) would also present as a
+      // plain mismatch. That is NOT retried with a live pull here, on purpose: the pull
+      // raises an authorize card while the signing sheet may still be dismissing, and
+      // overlapping sheets crash iOS. Fetching at DEPOSIT time makes staleness effectively
+      // impossible anyway — the key is read moments before the sheet appears, and rotation
+      // requires a deliberate device action. A genuine mismatch is reported as such.
+
+      if (r.resolved && r.signed) {
+        // Audit the minted credential — its own log, NOT a §10.6 consult receipt (a
+        // signature has no signal and must not feed act-as-me learning). Records a digest
+        // of the signed bytes + coarse metadata, never the mandate content or the signature.
+        // Best-effort: a failed audit write must never make a real signature look unsigned.
+        let recorded = false;
+        try {
+          await appendSigningAudit(defaultStateDir(), buildSigningAuditRecord({
+            requestId: args.request_id, mandate: r.mandate, clientId: CONSULT_OPTS.clientId, agentId: r.mandate?.agent_id,
+          }));
+          recorded = true;
+        } catch (e) {
+          process.stderr.write(`[phaedo-mcp] signing-audit write failed (mandate still signed): ${e.message}\n`);
+        }
+        const body = {
+          request_type: 'sign_status', status: 'signed', mandate: r.mandate, recorded,
+          message: 'The subject signed. The mandate now carries a verified signature and may be presented ' +
+                   'as a credential.',
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: body };
+      }
+      if (r.resolved && !r.signed) {
+        const refused = r.reason === 'refused';
+        const body = {
+          request_type: 'sign_status', status: refused ? 'refused' : 'not_signed', reason: r.reason,
+          ...(r.detail ? { detail: r.detail } : {}),
+          message: refused
+            ? 'The subject declined to sign. Do not proceed with an action that needs this credential.'
+            : 'A response arrived but did not verify (' + (r.detail || 'unknown') + '). Treat as unsigned; do not proceed.',
+        };
+        return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: body };
+      }
+      const expired = r.status === 'expired';
+      const body = {
+        request_type: 'sign_status', status: r.status,
+        message: expired
+          ? 'The signing window lapsed with no signature. The mandate remains an unsigned proposal.'
+          : 'Not signed yet. Keep waiting; poll again shortly.',
+      };
+      return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: body };
+    } catch (err) {
+      const code = err instanceof PhaedoError ? err.code : 'request_malformed';
+      return { content: [{ type: 'text', text: `Phaedo sign-status error [${code}]: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 // ── Resource: phaedo://fingerprint/projection (binding §3.1) ──────────────────
 // Default projection (all layers, standard mode) for resource-only clients.
 server.registerResource(

package/server.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.phaedo-labs/phaedo-mcp",
-  "description": "Carry your Phaedo cognitive fingerprint into any MCP client: injection, consults, escalation.",
-  "version": "0.2.2",
+  "description": "Carry your Phaedo cognitive fingerprint into any MCP client: injection, consults, escalation, mandate signing.",
+  "version": "0.3.0",
   "repository": {
     "url": "https://github.com/phaedo-labs/phaedo-mcp",
     "source": "github",
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "phaedo-mcp",
-      "version": "0.2.2",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       }