phaedo-mcp 0.2.2 → 0.3.1

package/server.js

@@ -16,15 +16,20 @@ 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 { loadFingerprint, sourceOf } from './fingerprint-source.js';
 import { hasPairingRecord, loadPairingRecord } 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 { resolveConsultation, checkAuthorization, CONSULTATION_TYPES, consultDrivers, withRevision } from './consult.js';
 import { defaultStateDir } from './cache.js';
+import { buildConsultOpts, loadConsultVd } from './consult-runtime.js';
 import { buildReceipt, appendReceipt, receiptsCapFromEnv, readReceipts, markOutcome, USER_ACTIONS } from './receipts.js';
 
 const BASE_DIR = dirname(fileURLToPath(import.meta.url));
@@ -35,33 +40,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;
 }
 
-// Load the fingerprint for a consult and fold in the act-as-me channel: delegation
-// signals derived from this subject's own override history (§10.6 receipts). The
-// origin-aware resolver then lets a `delegation` correction outrank a `self` signal on
-// the same dimension. Best-effort — if receipts are unreadable, the consult still
-// answers from the plain fingerprint (delegation learning never breaks a consultation).
-async function loadConsultVd(baseDir, { preferCache = false } = {}) {
-  // preferCache (escalation): read the at-rest cache instead of a live phone pull, so the
-  // escalation doesn't add a fingerprint-read AUTHORIZE prompt on top of its decision card.
-  const vd = preferCache ? await loadFingerprintPreferCache(baseDir) : await loadFingerprint(baseDir);
-  try {
-    // Two delegation sources, both origin-aware: live override history (every override)
-    // + the subject's ENDORSED, portable delegation rules (authored_delegation). The
-    // authored rule thus shapes consult too, not only the §9 injection it already renders in.
-    const signals = deriveDelegationSignals(await readReceipts(defaultStateDir()))
-      .concat(authoredDelegationSignals(vd && vd.phaedo_fingerprint));
-    return withDelegationSignals(vd, signals);
-  } catch (e) {
-    process.stderr.write(`[phaedo-mcp] delegation derive skipped (consult unaffected): ${e.message}\n`);
-    return vd;
-  }
+// 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;
 }
 
 // Act-as-me PROMOTION (delegation-sync.js): when the override history shows an
@@ -115,20 +140,32 @@ 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`);
   }
 }
 
-const CONSULT_OPTS = consultOptsFromEnv(process.env);
+// Env config + the subject's deference policies + this install's paired-client id —
+// built in consult-runtime.js, the one copy the Claude Code ship hook shares.
+const CONSULT_OPTS = buildConsultOpts(BASE_DIR, process.env);
 // Real-time escalation window (docs/roadmap/escalation-and-push.md §crux): how long a
 // blocking decision waits for the subject before the agent applies the safe-default
 // (hold). Configurable; bounded by the relay's own MAX_WINDOW_MS.
@@ -136,15 +173,6 @@ const ESCALATION_WINDOW_MS = (() => {
   const n = Number(process.env.PHAEDO_ESCALATION_WINDOW_MS);
   return Number.isFinite(n) && n > 0 ? n : 3 * 60 * 1000;
 })();
-// Deference policies: PHAEDO_CONSULT_POLICIES if set, else the default file beside
-// the server (mcp/consult-policies.json — what policy-editor.html produces). Zero
-// config: drop the file in and restart the client. (Portable vault policies in
-// phaedo_consult_policies always apply too, regardless of this file.)
-const POLICIES_PATH = process.env.PHAEDO_CONSULT_POLICIES || join(BASE_DIR, 'consult-policies.json');
-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`); }
-}
 
 // 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 +185,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 +205,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 +239,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,
@@ -214,9 +266,18 @@ server.registerTool(
   {
     title: 'Consult the Phaedo fingerprint at a decision point',
     description:
-      "Ask how the user's cognitive pattern bears on a decision — without ingesting the fingerprint. " +
-      'Returns a signal (proceed | proceed_with_note | clarify | escalate | decline), a confidence, a ' +
-      'short rationale_hint, and a deference_level (how strongly to weight it). Use at agent decision points.',
+      // Names the MOMENTS. "Use at agent decision points" told no agent when it was at one: not
+      // one consultation was written between 2026-07-28 and 2026-10-18. And it closes the loop —
+      // the receipt_id is the only handle that attributes the user's reaction to THIS action.
+      'Ask how the user would want an action handled, before you take it on their behalf — without ' +
+      'reading their profile. Call it BEFORE any consequential action you are about to take for the ' +
+      'user: merging or deploying, publishing or posting, sending a message, paying or committing money, ' +
+      'deleting, or changing an account or setting. Describe the action in action_descriptor (domain, ' +
+      'reversible, magnitude, a short summary; amount when money moves) and bind it to the exact call ' +
+      'with action_binding. Returns a signal (proceed | proceed_with_note | clarify | escalate | decline | ' +
+      'insufficient_signal), a confidence, a short rationale_hint, a deference_level (how strongly to ' +
+      'weight it) and a receipt_id. Keep the receipt_id: when the user reacts to what you did — confirms ' +
+      'it, overrides it, or wants it done differently — record that with phaedo_record_outcome.',
     inputSchema: {
       consultation_type: z.enum(CONSULTATION_TYPES),
       agent_id: z.string().optional(),
@@ -235,6 +296,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 +306,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 raw = await resolveConsultation(vd, args || {}, CONSULT_OPTS);
+      const response = withStaleAuthorityGuard(raw, 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
+      try { drivers = withRevision(consultDrivers(vd, args || {}, CONSULT_OPTS), raw); } catch { /* provenance is non-critical */ }
+      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 +366,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 +375,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 {
@@ -343,10 +426,13 @@ server.registerTool(
   {
     title: 'Record what the subject decided about a consulted action',
     description:
-      'After you consulted Phaedo and the USER decided what to do, record their outcome on the receipt: ' +
-      'approved | rejected | modified | unknown. Record what the USER chose, NOT whether you proceeded. ' +
-      'A rejected/modified outcome teaches Phaedo how the user wants delegated work handled (the act-as-me ' +
-      'channel). Defaults to the most recent receipt; pass receipt_id to mark a specific one.',
+      'Record what the USER decided about an action you consulted Phaedo on: approved | rejected | ' +
+      'modified | unknown. Call it when the user reacts to that action — they confirm it (approved), ' +
+      'refuse or undo it (rejected), or want it done differently (modified). Always pass the receipt_id ' +
+      'that phaedo_consult (or a Phaedo hook) gave you; without it the most recent receipt is marked, ' +
+      'which may be a different action. Record what the user chose, never whether you proceeded: ' +
+      'silence is not approval, and an approval you inferred teaches nothing. A rejected/modified ' +
+      'outcome teaches Phaedo how the user wants delegated work handled (the act-as-me channel).',
     inputSchema: {
       outcome: z.enum(USER_ACTIONS),
       receipt_id: z.string().optional(),
@@ -423,6 +509,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 +522,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 raw = await resolveConsultation(vd, req, CONSULT_OPTS);
+      const response = withStaleAuthorityGuard(raw, vd);
       let drivers = [];
-      try { drivers = consultDrivers(vd, req); } catch { /* non-critical */ }
-      await emitReceipt('phaedo_escalate', req, response, drivers);   // the decision being escalated
+      try { drivers = withRevision(consultDrivers(vd, req, CONSULT_OPTS), raw); } catch { /* non-critical */ }
+      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 +543,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 +557,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 +653,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: inject, consult, escalate, sign.",
+  "version": "0.3.1",
   "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.1",
       "transport": {
         "type": "stdio"
       }