phaedo-mcp 0.2.2 → 0.3.1

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",
-  "description": "Phaedo MCP server — inject your cognitive fingerprint into any MCP client, and consult your decision pattern at agent decision points (docs/protocol/mcp-binding.md).",
+  "description": "Phaedo MCP server \u2014 inject your cognitive fingerprint into any MCP client, and consult your decision pattern at agent decision points (docs/protocol/mcp-binding.md).",
   "mcpName": "io.github.phaedo-labs/phaedo-mcp",
   "homepage": "https://phaedo.so",
   "repository": {
@@ -32,16 +32,33 @@
     "consult.js",
     "consult-core.js",
     "consult-policy.js",
+    "consult-runtime.js",
+    "ship-actions.js",
+    "ship-readout.js",
+    "action-binding.js",
+    "autonomy-promotion.js",
+    "ap2.js",
     "receipts.js",
+    "receipts-sync.js",
     "agreement.js",
     "calibration.js",
+    "health.js",
     "phone-source.js",
+    "delegation-sync.js",
+    "escalation.js",
+    "signing.js",
+    "signing-request.js",
+    "signing-audit.js",
+    "capture-sync.js",
+    "capture-local.js",
+    "capture-a11y.js",
     "cache.js",
     "pairing.js",
     "pair.js",
     "pull.js",
     "install.mjs",
     "build-package.mjs",
+    "vendored-files.mjs",
     "vendor/",
     "lib/",
     "hooks/",
@@ -50,7 +67,9 @@
     "sample-fingerprint.json",
     "pairing.sample.json",
     "consult-policies.sample.json",
-    "README.md"
+    "escalation-policy.sample.json",
+    "README.md",
+    "NOTICE"
   ],
   "scripts": {
     "start": "node server.js",
@@ -60,12 +79,14 @@
     "setup": "node install.mjs",
     "setup:pair": "node install.mjs --pair",
     "setup:code-hook": "node install.mjs --code-hook",
+    "setup:capture-model": "node install.mjs --capture-model",
     "unsetup": "node install.mjs --uninstall",
     "pair": "node pair.js",
     "pull": "node pull.js",
-    "test": "node test-smoke.mjs && node test-phone-boundary.mjs && node test-cache.mjs && node test-pairing.mjs && node test-revoke.mjs && node test-install.mjs && node test-consult.mjs && node test-consult-policy.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-escalation.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-calibration.mjs && node test-identity.mjs",
+    "test": "node test-smoke.mjs && node test-no-profile.mjs && node test-phone-boundary.mjs && node test-cache.mjs && node test-pairing.mjs && node test-revoke.mjs && node test-install.mjs && node test-consult.mjs && node test-consult-policy.mjs && node test-amount-bands.mjs && node test-resolver-revision.mjs && node test-ship-actions.mjs && node test-ship-hook.mjs && node test-ship-readout.mjs && node test-action-binding.mjs && node test-autonomy-promotion.mjs && node test-ap2.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-capture-sync.mjs && node test-capture-hook.mjs && node test-stop-capture.mjs && node test-capture-local.mjs && node test-capture-a11y.mjs && node test-vendored-capture.mjs && node test-escalation.mjs && node test-domain.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-calibration.mjs && node test-identity.mjs && node test-signing.mjs && node test-sign-request.mjs && node test-signing-audit.mjs && node test-delegation-domain-fragmentation.mjs && node test-stale-authority.mjs && node test-config-home-fold.mjs && node test-precedence-and-ceiling.mjs && node test-package-closure.mjs",
     "receipts": "node receipts.js list",
     "agreement": "node agreement.js",
+    "ship-readout": "node ship-readout.js",
     "calibration": "node calibration.js",
     "health": "node health.js",
     "validate": "node ../spec/validate-fingerprint.mjs sample-fingerprint.json",
@@ -80,7 +101,10 @@
     "smoke:escalation": "node test-escalation.mjs",
     "smoke:receipts": "node test-receipts.mjs",
     "smoke:agreement": "node test-agreement.mjs",
-    "smoke:calibration": "node test-calibration.mjs"
+    "smoke:calibration": "node test-calibration.mjs",
+    "smoke:binding": "node test-action-binding.mjs",
+    "smoke:autonomy": "node test-autonomy-promotion.mjs",
+    "smoke:ap2": "node test-ap2.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/phone-source.js

@@ -1,7 +1,14 @@
-// MCP Phase 1b — real key boundary (Option B: share the extension's pairing).
+// MCP Phase 1b — real key boundary.
 //
-// Given a pairing record that already holds `pair_key` (exported from the paired
-// extension), this runs the spec-faithful authorize → pull → decrypt flow — a
+// The pairing record may come from EITHER provenance: `pair.js`, which pairs this
+// server as its own SAS-approved, revocable client (mcp-revocable-approval-plan.md,
+// DONE + device-verified), or the older "Option B" export of the extension's
+// `phaedo_local_pairing`. This path works under both — the phone's drains try each
+// verified client's key — but the extension-facing `agent_to_ext` lane does NOT;
+// see delegation-sync.js and docs/roadmap/paired-client-identity-2026-07-22.md.
+//
+// Given a pairing record holding `pair_key`, this runs the spec-faithful
+// authorize → pull → decrypt flow — a
 // direct port of popup.js reAuthorize (:745) + silentSync (:883):
 //
 //   authorize: fresh ephemeral X25519, HMAC-bound to pair_key, POST /v1/authorize,
@@ -16,15 +23,34 @@
 // after the one-time pairing.
 
 import { readFile } from 'fs/promises';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
-import { Phaedo, b64uEnc, b64uDec } from './lib/phaedo-crypto.js';
+import { Phaedo, b64uEnc, b64uDec, Capabilities } from './lib/phaedo-crypto.js';
 
 const { Identity, Kdf, Envelope } = Phaedo;
 const EXPIRY_SKEW_MS = 30 * 1000; // re-auth this early to avoid edge-of-expiry races
-const TIMEOUT_MS = 5000;          // fail fast when the phone is unreachable → cache fallback
 
-// ── Pairing record (Option B: exported from the extension's phaedo_local_pairing)
+// TWO timeouts, because the two requests wait on completely different things.
+//
+// `/v1/profile` waits on a MACHINE: the phone either answers or it doesn't, so failing fast
+// is right — an unreachable phone should fall back to the cache quickly.
+//
+// `/v1/authorize` waits on a PERSON: they must notice their phone, read the card, and pass
+// a biometric gate. A single 5s budget covered both, which made every authorize a race the
+// subject usually lost — the client aborted, the card vanished mid-tap, and an approval
+// completed seconds later landed on a request nobody was listening for. Worse, the abort is
+// a TRANSIENT failure, so it took the silent cache fallback: the agent then answered
+// authorization questions from a stale fingerprint while sounding certain. Observed on
+// device 2026-07-25 — the cache had not been refreshed for ~22 hours and a REVOKED payment
+// grant was still being honoured, because no live pull had ever completed.
+//
+// Face ID on the first try can fit in 5s. A passcode fallback cannot, and neither can a
+// phone that is face-down on a table. Two minutes is the human budget; the phone's own card
+// expiry remains the real bound, this just stops the client giving up first.
+const TIMEOUT_MS = 5000;             // reachability: /v1/profile
+const APPROVE_TIMEOUT_MS = 120000;   // human-in-the-loop: /v1/authorize
+
+// ── Pairing record (from `pair.js`, or the legacy extension export — see header)
 // { endpoint, client_id, client_secret, pair_key (b64url 32B), vault_pub, ... }
 export async function loadPairingRecord(baseDir) {
   const path = process.env.PHAEDO_PAIRING
@@ -55,6 +81,30 @@ export function hasPairingRecord(baseDir) {
   return existsSync(resolve(baseDir, 'pairing.json'));
 }
 
+// This server's OWN paired-client identifier — the identity §10.5 `agents` scoping
+// matches on (`docs/roadmap/paired-client-identity-2026-07-22.md`).
+//
+// Read SYNCHRONOUSLY at startup, beside the policy file, because it is process-wide
+// configuration rather than per-call state: one MCP server process serves exactly one
+// paired client, so this cannot change between calls without a restart. That is also
+// what makes the whole design work — the server never has to ask a caller who it is.
+//
+// Fail-safe by construction: any failure (no pairing, unreadable, malformed, missing
+// or non-string `client_id`) yields null, and null makes every `agents`-scoped
+// RELAXING rule inert. A broken read can therefore only ever withhold authority, never
+// grant it. Never throws.
+export function readServingClientId(baseDir) {
+  const path = process.env.PHAEDO_PAIRING
+    ? resolve(process.cwd(), process.env.PHAEDO_PAIRING)
+    : resolve(baseDir, 'pairing.json');
+  try {
+    const id = JSON.parse(readFileSync(path, 'utf8'))?.client_id;
+    return typeof id === 'string' && id.trim() ? id.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 // In-memory session cache, keyed by endpoint. Holds session_key (never persisted).
 const _sessions = new Map();
 
@@ -74,8 +124,14 @@ async function authorize(rec, deps) {
       scopes: ['profile:full'],
       eph_ext_pub: b64uEnc(eph.publicKey),
       eph_mac: b64uEnc(extMac),
+      // What this agent can do, for the §5 step-3 upgrade gate. The agent reads authored
+      // content but has no channel of its own to the extension, so the phone records this and
+      // couriers it on. Rides the authorize body because that is the one request the agent
+      // makes that the phone authenticates AND that recurs — sessions expire, so the record
+      // refreshes while the agent is in use and goes stale when it is not, which is the intent.
+      capabilities: Capabilities.advertise('agent'),
     }),
-    signal: AbortSignal.timeout(TIMEOUT_MS),
+    signal: AbortSignal.timeout(APPROVE_TIMEOUT_MS),   // waits on a human, not a machine
   });
   if (!res.ok) throw new PhoneError(`authorize failed (${res.status})`, res.status);
   const body = await res.json();
@@ -100,12 +156,29 @@ async function getSession(rec, deps) {
 }
 
 // Map the §9-profile inner plaintext to the vault payload shape the projection
-// expects. Profile inner is { data: <fingerprint>, metrics: {signals, ling,
-// sessions}, scopes } (mobile localServer handleProfile + popup restoreMetrics).
-function toVaultPayload(inner) {
-  const m = inner.metrics || {};
+// expects. Profile inner is { data: <fingerprint>, user_configuration?, metrics:
+// {signals, ling, sessions}, scopes } (mobile localServer handleProfile + popup
+// restoreMetrics). The optional §5 sibling (config home migration, part 3) maps
+// to phaedo_user_configuration, activating the canonical authored read
+// (consult-policy loadPolicies / context-block renderContextBlock); absent —
+// pre-part-3 phone — consumers fall back to the fingerprint A-home unchanged.
+export function toVaultPayload(inner) {
+  // Prefer every paired browser's counters combined (`metrics_combined`, 2026-10-01): the subject
+  // is one person across browsers, and `metrics` is only the browser that posted last. A phone
+  // that predates the sibling sends only `metrics`, which still serves.
+  const m = (inner.metrics_combined && typeof inner.metrics_combined === 'object' && !Array.isArray(inner.metrics_combined))
+    ? inner.metrics_combined
+    : (inner.metrics || {});
   return {
     phaedo_fingerprint: inner.data,
+    ...(inner.user_configuration && typeof inner.user_configuration === 'object'
+      ? { phaedo_user_configuration: inner.user_configuration } : {}),
+    // §8.3 signing public key — a sibling of the fingerprint, carried through so a
+    // consumer can VERIFY a signature the phone produced (e.g. an AP2 mandate) against a
+    // key learned over the trusted pairing channel, not one asserted in the signed object
+    // itself. A plain non-empty string or nothing; never trusted from inside `data`.
+    ...(typeof inner.signing_public_key === 'string' && inner.signing_public_key
+      ? { phaedo_signing_public_key: inner.signing_public_key } : {}),
     phaedo_behavioral_signals: m.signals || {},
     phaedo_linguistic_profile: m.ling || {},
     phaedo_session_metrics: m.sessions || {},

package/projection.js

@@ -87,7 +87,10 @@ export function buildInjectionResponse(vd, request = {}, now = Date.now()) {
   }
 
   const { vd: selectedVd, included } = selectLayers(vd, request.requested_layers);
-  const projection = PhaedoContext.renderContextBlock(selectedVd);
+  // §5.2 v0.2: the §9.2 session_context (domain / task_hint) drives deterministic
+  // activation of domain/task-scoped standing instructions; absent, scoped rules
+  // render with a conditional prefix instead.
+  const projection = PhaedoContext.renderContextBlock(selectedVd, { sessionContext: request.session_context || null });
   if (!projection) {
     throw new PhaedoError('decryption_failed', 'Fingerprint produced no projection (empty or missing layers).');
   }

package/pull.js

@@ -7,7 +7,7 @@
 
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
-import { loadFingerprint } from './fingerprint-source.js';
+import { loadFingerprint, sourceOf } from './fingerprint-source.js';
 
 const BASE_DIR = dirname(fileURLToPath(import.meta.url));
 
@@ -15,10 +15,26 @@ loadFingerprint(BASE_DIR)
   .then((vd) => {
     const fp = (vd && vd.phaedo_fingerprint) || {};
     const layers = fp.layers ? Object.keys(fp.layers).length : 0;
+    const src = sourceOf(vd);
+    // This line used to say "from the phone" unconditionally — including when the pull had
+    // failed and the at-rest cache was served instead. That is precisely how a 22-hour-old
+    // profile went unnoticed while the agent answered authorization questions from it. The
+    // whole point of this command is to verify the pairing works, so it has to distinguish
+    // "your phone answered" from "your phone didn't, here's an old copy".
+    if (src.live) {
+      process.stdout.write(
+        `✓ Read your profile from the phone — fingerprint ${fp.fingerprint_id || '(no id)'}, ${layers} layer(s).\n`
+      );
+      process.exit(0);
+    }
+    const hours = src.ageMs != null ? Math.round(src.ageMs / 3600000) : null;
     process.stdout.write(
-      `✓ Read your profile from the phone — fingerprint ${fp.fingerprint_id || '(no id)'}, ${layers} layer(s).\n`
+      `⚠ Could NOT reach your phone — served a CACHED copy${hours != null ? ` about ${hours}h old` : ''} ` +
+      `(fingerprint ${fp.fingerprint_id || '(no id)'}, ${layers} layer(s)).\n` +
+      `  Anything you changed since then — including a revoked authorization — is NOT reflected.\n` +
+      `  Open Phaedo on your phone and approve the card, then run this again.\n`
     );
-    process.exit(0);
+    process.exit(2);                       // distinct from 1 (hard failure) — stale, not broken
   })
   .catch((err) => {
     process.stderr.write(`✗ Couldn't read your profile: ${err.message}\n`);

package/receipts-sync.js

@@ -0,0 +1,197 @@
+// §10.6 receipts audit channel — MCP ↔ phone transport (G1+G2).
+//
+// Closes the act-as-me learning loop: today receipts written by `phaedo_consult` /
+// `phaedo_escalate` sit at `user_action: null` until the subject runs `node receipts.js
+// mark` — a dev CLI only. This module puts the audit on the subject's PHONE so they can
+// mark outcomes in the flow, which then feeds delegation learning (consult-core.js
+// `deriveDelegationSignals`).
+//
+// Two directions over the existing fp-mailbox transport (relay/mailbox.js):
+//
+//   agent_to_phone  — MCP deposits a digest of the latest UNMARKED receipts (a single
+//                     payload with at most N entries, last-write-wins idempotent: the
+//                     phone always sees the latest snapshot). §10.4-safe: only the
+//                     fields the phone needs to render — receipt_id, created_at, via,
+//                     agent_id, action_descriptor, response.signal — never `drivers`
+//                     (local provenance) and never layer content.
+//   phone_to_agent  — phone deposits a BATCH of `{ receipt_id, outcome }`; this module
+//                     drains and calls `markOutcome` per mark. Idempotent on the MCP
+//                     side (re-marking the same outcome is a no-op), so re-draining is
+//                     safe and the phone need not track per-mark ACKs — the next
+//                     receipts digest reflects applied marks (`user_action` set).
+//
+// Crypto: fp_sync_key derived from this server's pair_key. Drained by the PHONE, whose
+// multi-client loop tries each verified client's key — so independent pairing is fine
+// here (unlike agent_to_ext, see delegation-sync.js). The relay only ever sees
+// ciphertext. Best-effort and isolated:
+// a deposit/drain failure must NEVER break the tool that triggered it.
+
+import { Phaedo, b64uDec } from './lib/phaedo-crypto.js';
+import { readReceipts, markOutcome, USER_ACTIONS } from './receipts.js';
+import { agreementDigest } from './agreement.js';
+
+const { Kdf, Envelope } = Phaedo;
+const DEFAULT_RELAY = 'https://phaedo-relay.fly.dev';
+const DIGEST_CAP    = 50;   // phone shows recent N — enough for the latest sittings, bounded payload
+
+export function relayBaseFromEnv(env = process.env) {
+  return env.PHAEDO_RELAY || DEFAULT_RELAY;
+}
+
+// Strip a receipt down to the §10.4-safe fields the phone renders. NEVER includes
+// `drivers` (local provenance cues that would expose Decision&Risk reasoning to the
+// subject device — fine on this device, but the audit UI doesn't need them and not
+// shipping them keeps the digest small + the boundary tight).
+function digestFields(r) {
+  if (!r || typeof r !== 'object') return null;
+  return {
+    receipt_id:  r.receipt_id,
+    created_at:  r.created_at,
+    via:         r.via,
+    agent_id:    r.agent_id || null,
+    // The paired client that actually SERVED the call, beside the vendor string it
+    // claimed. §10.4-safe (an opaque id the subject's own phone issued, not persona
+    // content) and the phone is the one surface that can render it usefully: it holds
+    // the client registry, so it can show the friendly NAME where the receipt holds
+    // only the id. Without it the Activity screen can only report what the agent said
+    // it was — which is precisely the claim §10.5 stopped trusting.
+    client_id:   r.client_id || null,
+    request: {
+      consultation_type: r?.request?.consultation_type || null,
+      action_descriptor: {
+        domain:     r?.request?.action_descriptor?.domain     ?? null,
+        reversible: r?.request?.action_descriptor?.reversible ?? null,
+        magnitude:  r?.request?.action_descriptor?.magnitude  ?? null,
+        amount:     r?.request?.action_descriptor?.amount     ?? null,
+        summary:    r?.request?.action_descriptor?.summary    ?? null,
+      },
+    },
+    response: {
+      signal:          r?.response?.signal          ?? null,
+      deference_level: r?.response?.deference_level ?? null,
+    },
+    user_action: r.user_action ?? null,   // already-marked entries stay visible (phone shows status)
+  };
+}
+
+// Pure-crypto: take the local receipts list, build a §10.4-safe digest of the most
+// recent `cap` entries, and seal it under fp_sync_key. Returns `{ envelope }` — the
+// same shape `agent_to_ext` (delegation-sync) uses, so the relay's mailbox accepts it.
+export async function buildReceiptsDeposit(pairKeyB64u, receipts, { cap = DIGEST_CAP, now = () => new Date().toISOString() } = {}) {
+  const list = Array.isArray(receipts) ? receipts : [];
+  // Most-recent N (receipts are append-only, ordered by creation in the store).
+  const head = list.slice(-cap).map(digestFields).filter(Boolean);
+  // Agreement rides the SAME digest, but is computed over the WHOLE store, not the
+  // capped head — the rate is a 30-day property of the subject's history, and slicing
+  // it to the last 50 entries would silently redefine the metric.
+  const generatedAt = now();
+  const agreementAt = Date.parse(generatedAt);
+  const agreement = agreementDigest(list, { now: Number.isFinite(agreementAt) ? agreementAt : Date.now() });
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try {
+    fpSyncKey = await Kdf.deriveFpSyncKey(pairKey);
+  } finally {
+    pairKey.fill(0);
+  }
+  try {
+    const inner = { kind: 'receipts_digest', data: { receipts: head, agreement, generated_at: generatedAt } };
+    const plaintext = new TextEncoder().encode(JSON.stringify(inner));
+    const envelope = await Envelope.wrap(plaintext, fpSyncKey, { artifact_kind: 'receipts_digest', created_at: now() });
+    plaintext.fill(0);
+    return { envelope };
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+// Decrypt a phone-deposited marks payload. Returns `{ marks: [{receipt_id, outcome}, ...] }`
+// or null on a malformed/wrong-key envelope. Pure (no I/O) so it's testable.
+export async function parseMarksDeposit(pairKeyB64u, envelope) {
+  if (!envelope) return null;
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try { fpSyncKey = await Kdf.deriveFpSyncKey(pairKey); }
+  finally { pairKey.fill(0); }
+  try {
+    const plaintext = await Envelope.unwrap(envelope, fpSyncKey);
+    let inner;
+    try { inner = JSON.parse(new TextDecoder().decode(plaintext)); }
+    finally { if (plaintext.fill) plaintext.fill(0); }
+    if (!inner || inner.kind !== 'receipt_marks' || !inner.data) return null;
+    const arr = Array.isArray(inner.data.marks) ? inner.data.marks : [];
+    return {
+      marks: arr
+        .map((m) => ({
+          receipt_id: typeof m?.receipt_id === 'string' ? m.receipt_id : null,
+          outcome:    typeof m?.outcome    === 'string' ? m.outcome    : null,
+        }))
+        .filter((m) => m.receipt_id && USER_ACTIONS.includes(m.outcome)),
+    };
+  } catch {
+    return null;
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+// Deposit a receipts digest to the relay's agent_to_phone slot. Best-effort; mirrors
+// `depositDelegationSuggestions` exactly (same auth, same timeout, same isolation —
+// a failure NEVER throws out into the consult/escalate path that called us).
+export async function depositReceiptsDigest(pairing, receipts, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  const list = Array.isArray(receipts) ? receipts : [];
+  if (!list.length) return { deposited: false, reason: 'no-receipts' };
+  if (!pairing || !pairing.pair_key) return { deposited: false, reason: 'unpaired' };
+  if (!pairing.relay_device_id) return { deposited: false, reason: 'no-relay-device-id' };
+  try {
+    const body = await buildReceiptsDeposit(pairing.pair_key, list, deps);
+    const url = `${deps.relayBase || relayBaseFromEnv()}/fp-mailbox/${encodeURIComponent(pairing.relay_device_id)}/agent_to_phone`;
+    const authHeader = pairing.relay_device_secret
+      ? { Authorization: `Bearer ${pairing.relay_device_id}:${pairing.relay_device_secret}` }
+      : {};
+    const res = await fetchFn(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...authHeader },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(deps.timeoutMs || 8000),
+    });
+    return { deposited: !!(res && res.ok), status: res && res.status, count: list.length };
+  } catch (e) {
+    return { deposited: false, reason: String(e && e.message || e) };
+  }
+}
+
+// Drain phone-deposited outcome marks from the phone_to_agent slot and apply each via
+// markOutcome (idempotent). Returns `{ applied, skipped }`. Best-effort; a transport
+// failure returns `{ applied: 0, skipped: 0, reason }` instead of throwing.
+export async function drainAndApplyMarks(pairing, stateDir, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  if (!pairing || !pairing.pair_key) return { applied: 0, skipped: 0, reason: 'unpaired' };
+  if (!pairing.relay_device_id) return { applied: 0, skipped: 0, reason: 'no-relay-device-id' };
+  try {
+    const url = `${deps.relayBase || relayBaseFromEnv()}/fp-mailbox/${encodeURIComponent(pairing.relay_device_id)}/phone_to_agent`;
+    const authHeader = pairing.relay_device_secret
+      ? { Authorization: `Bearer ${pairing.relay_device_id}:${pairing.relay_device_secret}` }
+      : {};
+    const res = await fetchFn(url, {
+      method: 'GET',
+      headers: authHeader,
+      signal: AbortSignal.timeout(deps.timeoutMs || 8000),
+    });
+    if (!res || !res.ok) return { applied: 0, skipped: 0, status: res && res.status };
+    const body = await res.json().catch(() => null);
+    const parsed = await parseMarksDeposit(pairing.pair_key, body && body.envelope);
+    if (!parsed) return { applied: 0, skipped: 0, reason: 'no-marks' };
+    let applied = 0, skipped = 0;
+    for (const m of parsed.marks) {
+      try {
+        const r = await markOutcome(stateDir, m.receipt_id, m.outcome);
+        if (r.matched) applied++; else skipped++;
+      } catch { skipped++; }
+    }
+    return { applied, skipped, total: parsed.marks.length };
+  } catch (e) {
+    return { applied: 0, skipped: 0, reason: String(e && e.message || e) };
+  }
+}

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;
   });
@@ -230,7 +261,7 @@ if (process.argv[1] && process.argv[1].endsWith('receipts.js')) {
       for (const r of rs.slice(-50)) {
         const ad = r.request.action_descriptor;
         console.log(
-          `${r.receipt_id.slice(0, 8)}  ${r.created_at}  ${r.via === 'phaedo_check_authorization' ? '[pre-flight]' : '[consult]  '}` +
+          `${r.receipt_id.slice(0, 8)}  ${r.created_at}  ${r.via === 'phaedo_check_authorization' ? '[pre-flight]' : r.agent_id === 'claude-code/ship-hook' ? '[ship-hook] ' : '[consult]  '}` +
           ` ${r.request.consultation_type}  ${ad.domain || '-'}` +
           `  → ${r.response.signal} (conf ${r.response.confidence}, def ${r.response.deference_level})` +
           `  user_action: ${r.user_action ?? '—'}`