phaedo-mcp 0.2.2 → 0.3.0

package/lib/domain.js

@@ -0,0 +1,101 @@
+// §10.2 `action_descriptor.domain` — normalization and the published vocabulary.
+//
+// WHY ANY OF THIS EXISTS. `domain` is a bare `{"type":"string"}` the AGENT picks, and
+// everything downstream keys on it verbatim: §10.5 rule matching, the §10.6 receipt,
+// the delegation tally, §10.7's per-class approval counts. Observed live on the dev
+// machine: `financial` ×16, `finance` ×26, `finance.crypto_trading` ×1 — one concept,
+// three keys, and 7 approvals split 3/4 so neither class reached §10.7's
+// `MIN_APPROVALS = 5`. Analysis: `docs/roadmap/domain-identity-2026-07-22.md`.
+//
+// TWO FUNCTIONS, DELIBERATELY DISTINCT. Conflating them is how an alias table starts
+// granting authority nobody authored.
+//
+//   normalizeDomain()  lowercase + trim + collapse whitespace. Pure presentation;
+//                      `"Finance"` and `" finance"` cannot mean different things, so
+//                      merging them can lose no distinction anyone intended.
+//
+//   canonicalDomain()  normalizeDomain, then map a published ALIAS onto its canonical
+//                      term (`financial` → `finance`). This is a SEMANTIC claim, and
+//                      it is only safe where a wrong merge cannot expand authority.
+//
+// THE SAFETY PROPERTY, stated once and enforced at every call site: a vocabulary alias
+// may widen a GUARDRAIL's reach, never a GRANT's. `canonicalDomain` is therefore used
+// for evidence classification and for matching RESTRICTIVE rules; relaxing rules
+// (`autoproceed`, `bias_bold`) keep matching on `normalizeDomain` alone, exactly as
+// before. So adopting this vocabulary cannot hand any client more autonomy than it
+// already had — it can only make an existing guardrail cover more. If the table below
+// is wrong, the failure is "an agent asks when it needn't", never the reverse.
+//
+// ALIASES ARE SYNONYMS, NEVER GENERALIZATIONS. `financial` → `finance` is a synonym.
+// `crypto_trading` → `finance` would be a child→parent generalization, and it is
+// forbidden: a grant authored for the general class would silently cover a narrower,
+// riskier one the subject never demonstrated. Same defect that made dotted-suffix
+// stripping unsafe (v0.1.55), which is why `investing` is its own term here rather
+// than a `finance` alias, and why `crypto_trading` is absent entirely — an
+// unrecognized domain still works, it just does not merge.
+//
+// PUBLISHED, not private. The vocabulary below is a copy of `spec/domains.json` so the
+// npm package (whose `files` whitelist excludes `spec/`) is self-contained;
+// `mcp/test-domain.mjs` asserts the two cannot drift. A private synonym table would
+// put decision semantics somewhere the subject cannot read and a third-party
+// implementer cannot reproduce.
+
+/** Canonical terms → their aliases. Mirror of spec/domains.json `domains`. */
+const VOCABULARY = {
+  finance:       ['financial', 'finances', 'money', 'billing', 'invoicing', 'expenses', 'accounting'],
+  investing:     ['investment', 'investments', 'trading', 'brokerage', 'portfolio'],
+  legal:         ['contracts', 'compliance', 'regulatory'],
+  health:        ['medical', 'healthcare', 'wellness', 'clinical'],
+  scheduling:    ['calendar', 'meetings', 'appointments', 'availability', 'booking'],
+  communication: ['email', 'outbound email', 'messaging', 'messages', 'comms', 'correspondence'],
+  writing:       ['drafting', 'editing', 'content', 'copywriting', 'documentation'],
+  research:      ['analysis', 'reading', 'summarization', 'search'],
+  shopping:      ['purchasing', 'purchase', 'procurement', 'orders', 'commerce', 'ecommerce'],
+  travel:        ['trips', 'flights', 'lodging', 'itinerary', 'transportation'],
+  engineering:   ['code', 'coding', 'software', 'development', 'dev', 'devops', 'infrastructure', 'deployment'],
+  data:          ['files', 'records', 'storage', 'database', 'export'],
+  security:      ['access', 'permissions', 'credentials', 'authentication', 'authorization'],
+  people:        ['hr', 'human resources', 'hiring', 'recruiting', 'personnel', 'staffing'],
+  social:        ['social media', 'posting', 'publishing', 'community'],
+  support:       ['customer support', 'customer service', 'helpdesk', 'tickets'],
+  admin:         ['administration', 'settings', 'accounts', 'subscriptions', 'operations', 'ops'],
+};
+
+/** alias → canonical, plus every canonical term mapping to itself. */
+const ALIAS_TO_CANONICAL = (() => {
+  const m = new Map();
+  for (const [term, aliases] of Object.entries(VOCABULARY)) {
+    m.set(term, term);
+    for (const a of aliases) m.set(a, term);
+  }
+  return m;
+})();
+
+export const VOCABULARY_TERMS = Object.freeze(Object.keys(VOCABULARY).sort());
+export const VOCABULARY_MAP = VOCABULARY;
+
+/**
+ * Presentation-only normalization. Returns '' for anything unusable, which every
+ * caller already treats as "no domain".
+ */
+export function normalizeDomain(raw) {
+  if (typeof raw !== 'string') return '';
+  return raw.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+/**
+ * Normalize, then resolve a published alias to its canonical term. An unrecognized
+ * domain is returned normalized but otherwise untouched — free text stays legal and
+ * behaves exactly as it does today. Never throws.
+ */
+export function canonicalDomain(raw) {
+  const n = normalizeDomain(raw);
+  if (!n) return '';
+  return ALIAS_TO_CANONICAL.get(n) || n;
+}
+
+/** True iff this domain resolves to a published vocabulary term. */
+export function isVocabularyTerm(raw) {
+  const n = normalizeDomain(raw);
+  return !!n && ALIAS_TO_CANONICAL.has(n);
+}

package/lib/is-main.js

@@ -0,0 +1,40 @@
+// "Was this module executed directly?" — symlink-safe.
+//
+// The obvious ESM idiom
+//
+//     import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+//
+// is WRONG whenever any component of the path is a symlink. Node resolves
+// `import.meta.url` through symlinks (it is the module's real URL), while
+// `resolve(process.argv[1])` normalizes `.`/`..` but does NOT follow links — so
+// the two disagree and the check silently returns false.
+//
+// That is not a hypothetical. `os.tmpdir()` on macOS is `/var/folders/…`, a
+// symlink to `/private/var/folders/…`, which made the SessionEnd capture hook a
+// silent no-op for every macOS spawn from a temp path (caught by
+// test-vendored-capture.mjs, which spawns the hook exactly as Claude Code does).
+// The same trap is live in production for any install reached through a link — a
+// symlinked home directory, a linked global npm root, `/tmp` on macOS.
+//
+// A capture hook that quietly does nothing is the worst failure this codebase
+// has: it exits 0, prints nothing, and loses the session. So compare REAL paths,
+// and fall back to the plain URL comparison only if realpath throws (a deleted or
+// unreadable entry point — in which case "not main" is the safe answer anyway).
+
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// (import.meta.url of the caller, [argv]) -> boolean
+export function isMainModule(moduleUrl, argv = process.argv) {
+  const entry = argv && argv[1];
+  if (!entry || !moduleUrl) return false;
+  const self = fileURLToPath(moduleUrl);
+  const target = resolve(entry);
+  if (self === target) return true;                       // fast path, no IO
+  try {
+    return realpathSync(self) === realpathSync(target);
+  } catch {
+    return pathToFileURL(target).href === moduleUrl;      // best effort
+  }
+}

package/lib/phaedo-crypto.js

@@ -21,7 +21,7 @@ const ROOT = resolve(HERE, '..', '..');               // repo root — dev
 
 // Prefer the bundled copies (self-contained package) over the repo root (dev).
 // Load order matters: protocol → envelope → kdf → identity.
-for (const f of ['protocol.js', 'envelope.js', 'kdf.js', 'identity.js']) {
+for (const f of ['protocol.js', 'envelope.js', 'kdf.js', 'identity.js', 'capabilities.js', 'authored-source.js']) {
   const vf = resolve(VENDOR, f);
   require(existsSync(vf) ? vf : resolve(ROOT, f));
 }
@@ -31,6 +31,22 @@ if (!Phaedo?.Envelope || !Phaedo?.Kdf || !Phaedo?.Identity || !Phaedo?.Protocol)
   throw new Error('Phaedo crypto modules did not load (Protocol/Envelope/Kdf/Identity).');
 }
 
+// The §5 step-3 upgrade gate's vocabulary. The agent READS authored content, so it has to be
+// able to say what it can do — otherwise the gate stays shut on its silence forever, which is
+// correct but useless. Loaded here rather than imported directly so the published package picks
+// up the vendored copy exactly like the crypto modules do.
+export const Capabilities = globalThis.PhaedoCapabilities;
+if (!Capabilities?.advertise) {
+  throw new Error('Phaedo capabilities module did not load.');
+}
+
+// The step-3 read path's §5.4 rule. Used at the vd boundary so every authored-content reader
+// downstream is §5-canonical without threading the configuration through its signature.
+export const AuthoredSource = globalThis.PhaedoAuthoredSource;
+if (!AuthoredSource?.configGoverns) {
+  throw new Error('Phaedo authored-source module did not load.');
+}
+
 // base64url <-> Uint8Array (Node-native), matching the extension's wire encoding.
 export const b64uEnc = (u8) => Buffer.from(u8).toString('base64url');
 export const b64uDec = (s) => new Uint8Array(Buffer.from(s, 'base64url'));

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "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,30 @@
     "consult.js",
     "consult-core.js",
     "consult-policy.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 +64,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,10 +76,11 @@
     "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-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-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-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",
     "calibration": "node calibration.js",
@@ -80,7 +97,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,24 @@ 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) {
+// 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) {
   const m = 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) };
+  }
+}