phaedo-mcp 0.2.1 → 0.3.0

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.1' });
+// 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,10 +1,10 @@
 {
   "$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: style injection, decision consults + real-time escalation.",
-  "version": "0.2.1",
+  "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",
+    "url": "https://github.com/phaedo-labs/phaedo-mcp",
     "source": "github",
     "subfolder": "mcp"
   },
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "phaedo-mcp",
-      "version": "0.2.1",
+      "version": "0.3.0",
       "transport": {
         "type": "stdio"
       }

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;
+}