phaedo-mcp 0.2.2 → 0.3.0

package/delegation-sync.js

@@ -0,0 +1,89 @@
+// Delegation-promotion transport (MCP → relay → extension).
+//
+// Deposits act-as-me delegation SUGGESTIONS (built by consult-core.js
+// buildDelegationPromotions from the consult override history) into the relay's
+// `agent_to_ext` mailbox slot, encrypted under fp_sync_key.
+//
+// ⚠️ KEY DEPENDENCY (not merely historical — see
+// docs/roadmap/paired-client-identity-2026-07-22.md). fp_sync_key is derived from
+// pair_key, and the EXTENSION drains this lane with its OWN single fp_sync_key — no
+// multi-client key loop, unlike the phone's drains. So this deposit is readable only
+// when the MCP and the extension share a pair_key (the original "Option B": the
+// extension's pairing exported to mcp/pairing.json). An MCP paired independently via
+// `pair.js` derives a DIFFERENT key, and the extension logs "likely key mismatch" and
+// drops the suggestion silently. Independent pairing is what makes the MCP a distinct
+// principal for §10.5 `agents` scoping, so these two properties are in tension until
+// the extension's drain gains the phone's try-each-verified-client loop.
+//
+// The extension union-merges
+// the suggestions (sync-merge.js mergeAgentSuggestions) into suggested_rules, where the
+// existing popup review card surfaces them for endorsement.
+//
+// Trust posture: the MCP only ever proposes SUGGESTIONS — never an authored rule. The
+// subject still endorses (the authored-only invariant holds). Best-effort and isolated:
+// a deposit failure never affects the consultation that triggered it. The relay only
+// ever holds ciphertext (the agent_to_ext slot is separate from the phone's to_ext, so
+// a deposit can neither clobber nor be clobbered by the phone's fingerprint sync).
+
+import { Phaedo, b64uDec } from './lib/phaedo-crypto.js';
+
+const { Kdf, Envelope } = Phaedo;
+const DEFAULT_RELAY = 'https://phaedo-relay.fly.dev';
+
+export function relayBaseFromEnv(env = process.env) {
+  return env.PHAEDO_RELAY || DEFAULT_RELAY;
+}
+
+// Wrap delegation suggestions into the same envelope shape the extension's fp-mailbox
+// drain expects: ciphertext over `{ data: { suggested_rules: [...] } }`. Returns the
+// deposit body `{ envelope }`. Pure crypto (no network) so the round-trip is testable.
+export async function buildDelegationDeposit(pairKeyB64u, suggestions, { now = () => new Date().toISOString() } = {}) {
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try {
+    fpSyncKey = await Kdf.deriveFpSyncKey(pairKey);
+  } finally {
+    pairKey.fill(0);
+  }
+  try {
+    const inner = { kind: 'delegation_suggestions', data: { suggested_rules: suggestions } };
+    const plaintext = new TextEncoder().encode(JSON.stringify(inner));
+    const envelope = await Envelope.wrap(plaintext, fpSyncKey, { artifact_kind: 'delegation_suggestions', created_at: now() });
+    plaintext.fill(0);
+    return { envelope };
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+// Deposit the suggestions to the relay's agent_to_ext slot. Best-effort: returns
+// { deposited, ... } and never throws (a transport failure must not break the consult).
+// `deps.fetch` is injectable for tests.
+export async function depositDelegationSuggestions(pairing, suggestions, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  const list = Array.isArray(suggestions) ? suggestions : [];
+  // Precise reasons so the caller can surface WHY a deposit didn't happen (a missing
+  // relay_device_id means a local-only pairing — the deposit silently no-ops otherwise).
+  if (!list.length) return { deposited: false, reason: 'no-suggestions' };
+  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 buildDelegationDeposit(pairing.pair_key, list, deps);
+    const base = `${deps.relayBase || relayBaseFromEnv()}/fp-mailbox/${encodeURIComponent(pairing.relay_device_id)}/agent_to_ext`;
+    // Per-device auth header (relay/auth.js). Without it the relay 401s. A pairing.json
+    // from an older mobile build that predates the auth layer won't have relay_device_secret
+    // → no header → 401 → the deposit no-ops, which is the correct failure mode (user re-pairs).
+    const authHeader = pairing.relay_device_secret
+      ? { Authorization: `Bearer ${pairing.relay_device_id}:${pairing.relay_device_secret}` }
+      : {};
+    const res = await fetchFn(base, {
+      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) };
+  }
+}

package/escalation-policy.sample.json

@@ -0,0 +1,13 @@
+{
+  "version": "0.1",
+  "_comment": "Subject-configurable PUSH policy for phaedo_escalate (docs/roadmap/escalation-and-push.md). Controls which consult signals WAKE your phone for a live decision. `escalate` ALWAYS pushes (it means a human is needed) and is not configurable here. Only `clarify` is tunable: mode is \"always\" | \"consequential\" (the default: irreversible OR high-magnitude actions only) | \"never\". A per-domain override (by_domain, substring match, case-insensitive) beats the default. Portable: copy into the vault as phaedo_fingerprint.escalation_policy to sync across devices, or point PHAEDO_ESCALATION_POLICY at this file to try it. The file overrides the vault policy.",
+  "clarify": {
+    "default": "consequential",
+    "by_domain": {
+      "financial": "always",
+      "legal": "always",
+      "writing": "never",
+      "internal note": "never"
+    }
+  }
+}

package/escalation.js

@@ -0,0 +1,383 @@
+// Real-time escalation client (MCP → relay → subject's device → back).
+//
+// The delivery channel the act-as-me endgame needs once agents act AUTONOMOUSLY for
+// the subject (docs/roadmap/escalation-and-push.md). When a consult returns a
+// process-BLOCKING signal — `escalate` (or `clarify`) — and the agent is running
+// unattended, there is no one at the agent's conversation to answer. This routes the
+// decision to the subject's phone in real time, waits within a bounded window, and
+// returns approve / deny / modify so the agent can resume — or applies the SAFE
+// DEFAULT when the window lapses (an `escalate` means "hold for a human", so the
+// no-response default is do-not-proceed, never a guess).
+//
+// §10.4 boundary on the wire: the escalation payload carries the ACTION under
+// question (the agent's own descriptor) + the consult's `signal`/`rationale_hint` —
+// NEVER fingerprint layer content. And even that is sealed under fp_sync_key (the
+// same HKDF(pair_key) key the delegation deposit uses), so the relay stays
+// zero-knowledge: it forwards ciphertext and wakes the device, nothing more.
+//
+// Honesty rail (roadmap Q7): a real-time approve/deny IS an outcome — the strongest
+// possible act-as-me signal. The orchestrator returns a `record_outcome` mapping
+// (approve→approved, deny→rejected, modify→modified) so the SAME §10.6 receipt +
+// override-learning loop picks it up automatically. A TIMEOUT is "no answer", not an
+// override — it maps to `unknown` and teaches nothing.
+
+import { Phaedo, b64uDec } from './lib/phaedo-crypto.js';
+import { normalizeActionBinding } from './action-binding.js';
+
+const { Kdf, Envelope } = Phaedo;
+const DEFAULT_RELAY = 'https://phaedo-relay.fly.dev';
+
+export function relayBaseFromEnv(env = process.env) {
+  return env.PHAEDO_RELAY || DEFAULT_RELAY;
+}
+
+// The Authorization header for relay HTTP routes (relay/auth.js per-device bearer).
+// Without this, deposit/poll return 401. A pairing without a relay_device_secret (e.g.
+// from an older mobile build that predates the auth layer) gets no header — relay 401s,
+// which surfaces as deposit-failed-401 from the orchestrator.
+function relayAuthHeader(pairing) {
+  if (!pairing || !pairing.relay_device_id || !pairing.relay_device_secret) return {};
+  return { Authorization: `Bearer ${pairing.relay_device_id}:${pairing.relay_device_secret}` };
+}
+
+// Which consult signals are BLOCKING enough to WAKE the subject (roadmap Q1). The two
+// blocking signals are not equal:
+//   - `escalate` = "hold for a live human go/no-go on a consequential call." Blocking by
+//     definition → ALWAYS push.
+//   - `clarify` = "I need more info before acting." This is the agent's default reflex
+//     when uncertain, so it fires often, including on low-stakes calls. Waking the phone
+//     for every clarify would cry wolf — so push a clarify ONLY when the action is also
+//     CONSEQUENTIAL (irreversible OR high magnitude). Below that bar an autonomous agent
+//     should resolve the clarify itself (ask in-flow / state a reasonable assumption) and
+//     it surfaces in the deferred review queue — no interruption.
+// Unknown stakes (no descriptor) reads as low-stakes for clarify: the agent can always
+// raise an explicit `escalate` when it really needs the subject. Ultimately this whole
+// policy is subject-configurable via a standing rule; this is the sensible default.
+export function isConsequential(actionDescriptor = {}) {
+  const ad = actionDescriptor || {};
+  return ad.reversible === false || ad.magnitude === 'high';
+}
+
+// ── Subject-configurable push policy (the standing knob) ───────────────────────
+// The stakes-gated default above is just that — a default. A subject can override how
+// `clarify` is pushed, globally and per-domain, via an escalation policy that rides the
+// vault (portable: `phaedo_fingerprint.escalation_policy`, syncs across devices) and/or a
+// local file (`PHAEDO_ESCALATION_POLICY`, for power users / testing) — the same dual home
+// as consult policies (`consult-policy.js`). Shape:
+//   { "clarify": { "default": "always" | "consequential" | "never",
+//                  "by_domain": { "financial": "always", "writing": "never" } } }
+// `escalate` is deliberately NOT configurable: it means "a human is needed", so suppressing
+// the wake would strand a blocking decision — it always pushes. Only `clarify` is tunable.
+const CLARIFY_MODES = new Set(['always', 'consequential', 'never']);
+
+// Merge policy sources (later wins; `by_domain` deep-merged, `default` shallow-overridden).
+// Defensive: ignores malformed entries and unknown modes. Never throws.
+export function mergeEscalationPolicy(...sources) {
+  const clarify = { default: undefined, by_domain: {} };
+  for (const s of sources) {
+    const c = s && typeof s === 'object' ? s.clarify : null;
+    if (!c || typeof c !== 'object') continue;
+    if (typeof c.default === 'string' && CLARIFY_MODES.has(c.default.toLowerCase())) clarify.default = c.default.toLowerCase();
+    if (c.by_domain && typeof c.by_domain === 'object') {
+      for (const [k, v] of Object.entries(c.by_domain)) {
+        if (typeof v === 'string' && CLARIFY_MODES.has(v.toLowerCase())) clarify.by_domain[String(k).toLowerCase()] = v.toLowerCase();
+      }
+    }
+  }
+  return { clarify };
+}
+
+// Resolve the effective policy for a consult: the vault-embedded policy (portable) merged
+// under the local-file override (`opts.escalationPolicy`). Pure; defensive.
+export function loadEscalationPolicy(vd, opts = {}) {
+  return mergeEscalationPolicy(vd?.phaedo_fingerprint?.escalation_policy, opts.escalationPolicy);
+}
+
+// Does a `by_domain` KEY govern this action domain? EXACT match, or a dot-hierarchy
+// PARENT match (`finance` governs `finance.crypto_trading`).
+//
+// This deliberately replaces the old bidirectional substring test
+// (`domain.includes(k) || k.includes(domain)`), which was both wrong and unsafe:
+//   - `legal` spuriously governed `paralegal`, and `care` governed `healthcare` —
+//     accidental substrings, not subdomains. So a subject who set `legal: never` to
+//     silence legal noise ALSO silenced every paralegal action, and a suppressed
+//     clarify never reaches the phone: the failure is invisible by construction.
+//   - the reverse direction (`k.includes(domain)`) let a narrow key govern a broad
+//     action — a `finance.crypto_trading` rule firing on a bare `finance` action.
+// A real subdomain rides a `.` boundary; a coincidental letter overlap does not.
+// Parent→child only (a `finance` rule covers its subdomains; a crypto rule does NOT
+// reach up to govern general finance). Anything unmatched falls to `default`, which
+// the subject controls — never to a wrong, more-specific rule.
+function domainRuleApplies(key, domain) {
+  return domain === key || domain.startsWith(key + '.');
+}
+
+// The clarify push mode for an action under a policy: the MOST SPECIFIC per-domain
+// override wins over the default, which falls back to the built-in 'consequential'.
+//
+// "Most specific" = the longest applicable key, so `finance.crypto_trading` beats a
+// bare `finance` for a crypto action. This is also what makes the result
+// DETERMINISTIC: the old first-match-wins loop returned different modes for the same
+// action depending on JSON key order, so a subject's specific rule could lose to a
+// general one purely by where it sat in the object.
+export function resolveClarifyMode(actionDescriptor = {}, policy = null) {
+  const c = policy && policy.clarify;
+  if (!c) return 'consequential';
+  const domain = String(actionDescriptor?.domain || '').toLowerCase();
+  if (domain && c.by_domain) {
+    let best = null;
+    for (const [k, mode] of Object.entries(c.by_domain)) {
+      if (!CLARIFY_MODES.has(mode)) continue;
+      if (domainRuleApplies(k, domain) && (best === null || k.length > best.k.length)) best = { k, mode };
+    }
+    if (best) return best.mode;
+  }
+  return CLARIFY_MODES.has(c.default) ? c.default : 'consequential';
+}
+
+// Does this signal WAKE the subject? `escalate` always; `clarify` per the policy
+// (`always` | `never` | `consequential` = irreversible/high-magnitude). Backward
+// compatible: with no policy, clarify falls back to the stakes-gated default.
+export function shouldEscalate(signal, actionDescriptor = {}, policy = null) {
+  const s = String(signal);
+  if (s === 'escalate') return true;
+  if (s === 'clarify') {
+    const mode = resolveClarifyMode(actionDescriptor, policy);
+    return mode === 'always' ? true : mode === 'never' ? false : isConsequential(actionDescriptor);
+  }
+  return false;
+}
+
+// The decision vocabulary the phone returns, mapped to the §10.6 receipt user_action.
+const DECISION_OUTCOME = { approve: 'approved', deny: 'rejected', modify: 'modified' };
+
+// Build the §10.4-safe escalation payload from the consult request + its response.
+// PURE. Pulls ONLY the agent's own action descriptor + the constrained consult
+// signal/rationale — no vault data is in scope here at all. Truncates free text so a
+// runaway descriptor can't bloat the (encrypted) wire payload.
+export function buildEscalationPayload(consultRequest = {}, consultResponse = {}) {
+  const ad = (consultRequest.action_descriptor && typeof consultRequest.action_descriptor === 'object') ? consultRequest.action_descriptor : {};
+  const clip = (s, n) => (typeof s === 'string' ? s.replace(/\s+/g, ' ').trim().slice(0, n) : undefined);
+  // The §10.2 binding, when the agent sent one. `summary` above is the agent's
+  // PROSE — its account of what it is about to do. This is the call itself. The
+  // subject approving an escalation should see both, because the whole class of
+  // approval-gate bypasses works by making the two differ.
+  let bnd = null;
+  try { bnd = normalizeActionBinding(consultRequest.action_binding); } catch { bnd = null; }
+  return {
+    consultation_type: typeof consultRequest.consultation_type === 'string' ? consultRequest.consultation_type : undefined,
+    agent_id: clip(consultRequest.agent_id, 120),
+    action: {
+      domain: clip(ad.domain, 80),
+      summary: clip(ad.summary, 280),
+      magnitude: ['low', 'medium', 'high'].includes(ad.magnitude) ? ad.magnitude : undefined,
+      reversible: typeof ad.reversible === 'boolean' ? ad.reversible : undefined,
+      amount: typeof ad.amount === 'number' && isFinite(ad.amount) ? ad.amount : undefined,
+      ...(bnd ? {
+        tool_name: bnd.tool_name,
+        arguments_hash: bnd.arguments_hash,
+        ...(bnd.arguments_preview ? { arguments_preview: bnd.arguments_preview } : {}),
+      } : {}),
+    },
+    signal: clip(consultResponse.signal, 40),
+    rationale_hint: clip(consultResponse.rationale_hint, 280),
+  };
+}
+
+// Seal the payload under fp_sync_key into the deposit body { request_id, envelope,
+// window_ms }. PURE crypto (no network) so the round-trip is testable in isolation,
+// mirroring delegation-sync.js buildDelegationDeposit.
+export async function buildEscalationDeposit(pairKeyB64u, requestId, payload, { windowMs, now = () => new Date().toISOString() } = {}) {
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try {
+    fpSyncKey = await Kdf.deriveFpSyncKey(pairKey);
+  } finally {
+    pairKey.fill(0);
+  }
+  try {
+    const inner = { kind: 'escalation_request', request_id: requestId, data: payload };
+    const plaintext = new TextEncoder().encode(JSON.stringify(inner));
+    const envelope = await Envelope.wrap(plaintext, fpSyncKey, { artifact_kind: 'escalation_request', created_at: now() });
+    plaintext.fill(0);
+    return { request_id: requestId, envelope, ...(windowMs ? { window_ms: windowMs } : {}) };
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+// Decrypt the subject's decision (the phone's response body { envelope }) under
+// fp_sync_key. Returns the inner { decision, note?, modified? } or null on any
+// failure (a malformed/forged response must never crash the agent's resume path).
+export async function unwrapEscalationResponse(pairKeyB64u, body) {
+  if (!body || !body.envelope) return null;
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try {
+    fpSyncKey = await Kdf.deriveFpSyncKey(pairKey);
+  } catch { pairKey.fill(0); return null; }
+  pairKey.fill(0);
+  try {
+    const plaintext = await Envelope.unwrap(body.envelope, fpSyncKey);
+    const inner = JSON.parse(new TextDecoder().decode(plaintext));
+    if (inner && inner.kind === 'escalation_response' && inner.data) return inner.data;
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function genRequestId() {
+  if (typeof crypto !== 'undefined' && crypto.randomUUID) return crypto.randomUUID();
+  return `esc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// ── Non-blocking deposit + single-poll (for the MCP tools) ─────────────────────
+// A multi-minute BLOCKING tool call is hostile to MCP clients (many time out), so the
+// agent-facing tools use a two-call shape: phaedo_escalate deposits + wakes the device
+// and returns immediately; phaedo_escalation_status polls once. The agent decides when
+// to stop waiting; the safe default once it gives up is HOLD (do-not-proceed).
+
+// Deposit the (encrypted) decision request and wake the device. Returns
+// { deposited, request_id, window_ms, expires_at } or { deposited:false, reason }.
+// Never throws.
+export async function depositEscalation(pairing, consultRequest, consultResponse, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  const signal = consultResponse && consultResponse.signal;
+  if (!pairing || !pairing.pair_key) return { deposited: false, reason: 'unpaired', signal };
+  if (!pairing.relay_device_id) return { deposited: false, reason: 'no-relay-device-id', signal };
+  const windowMs = Math.max(1000, Number(deps.windowMs) || 3 * 60 * 1000);
+  const relayBase = deps.relayBase || relayBaseFromEnv();
+  const requestId = deps.requestId || genRequestId();
+  try {
+    const body = await buildEscalationDeposit(pairing.pair_key, requestId, buildEscalationPayload(consultRequest, consultResponse), { windowMs });
+    const res = await fetchFn(`${relayBase}/escalation/${encodeURIComponent(pairing.relay_device_id)}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...relayAuthHeader(pairing) },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(deps.depositTimeoutMs || 8000),
+    });
+    if (!res || !res.ok) return { deposited: false, reason: `deposit-failed-${res && res.status}`, request_id: requestId, signal };
+    let info = {};
+    try { info = await res.json(); } catch { /* body optional */ }
+    return { deposited: true, request_id: requestId, window_ms: windowMs, expires_at: info.expires_at, woke: info.woke, signal };
+  } catch (e) {
+    return { deposited: false, reason: `deposit-error:${String(e && e.message || e)}`, request_id: requestId, signal };
+  }
+}
+
+// Poll ONCE for a decision. Returns { resolved:true, decision, proceed, outcome, note?,
+// modified? } when answered, { resolved:false, status:'pending' } while waiting, or
+// { resolved:false, status:'expired' } once the agent's deadline has passed (the caller
+// then applies the safe-default hold). Never throws.
+export async function pollEscalationOnce(pairing, requestId, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  if (!pairing || !pairing.pair_key || !requestId) return { resolved: false, status: 'expired', reason: 'bad-args' };
+  if (deps.expiresAt && (deps.now ? deps.now() : Date.now()) > deps.expiresAt) return { resolved: false, status: 'expired' };
+  const relayBase = deps.relayBase || relayBaseFromEnv();
+  let body = null;
+  try {
+    const res = await fetchFn(`${relayBase}/escalation/response/${encodeURIComponent(requestId)}`, {
+      headers: relayAuthHeader(pairing),
+      signal: AbortSignal.timeout(deps.pollTimeoutMs || 8000),
+    });
+    if (res && res.ok) body = await res.json();
+  } catch { /* transient */ }
+  if (!body) return { resolved: false, status: 'pending' };
+  const data = await unwrapEscalationResponse(pairing.pair_key, body);
+  if (!data || !DECISION_OUTCOME[data.decision]) return { resolved: false, status: 'pending' };
+  return {
+    resolved: true,
+    decision: data.decision,
+    proceed: data.decision !== 'deny',
+    note: typeof data.note === 'string' ? data.note : undefined,
+    modified: data.decision === 'modify' ? (data.modified ?? null) : undefined,
+    outcome: DECISION_OUTCOME[data.decision],
+    request_id: requestId,
+  };
+}
+
+// The SAFE DEFAULT applied when the window lapses with no answer (roadmap §crux).
+// `escalate` already means "hold for a human", so absent a decision the agent must
+// NOT proceed — it holds. A timeout is not an override, so it teaches nothing
+// (outcome 'unknown'). Returned in the same shape as a real decision so the caller
+// has one code path.
+function safeDefault(signal) {
+  return {
+    decision: 'hold',
+    resolved: false,
+    reason: 'timeout',
+    proceed: false,                 // do-not-proceed is the safe default for a blocking escalate/clarify
+    outcome: 'unknown',             // no answer ⇒ no act-as-me signal
+    signal,
+  };
+}
+
+// Orchestrate one real-time escalation: deposit → poll within the window → decision
+// or safe-default. Best-effort and self-contained — every failure path resolves to a
+// safe-default rather than throwing into the agent. `deps.fetch`, `deps.sleep`,
+// `deps.now`, `deps.pollMs`, `deps.windowMs`, `deps.relayBase` are injectable for tests.
+//
+//   pairing            : { pair_key, relay_device_id } (loadPairingRecord)
+//   consultRequest     : the args passed to phaedo_consult
+//   consultResponse    : the §10.3 response it returned (must be escalate/clarify)
+// Returns:
+//   { resolved, decision, proceed, note?, outcome, request_id, signal, reason? }
+export async function requestEscalationDecision(pairing, consultRequest, consultResponse, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  const wait = deps.sleep || sleep;
+  const now = deps.now || (() => Date.now());
+  const signal = consultResponse && consultResponse.signal;
+
+  if (!pairing || !pairing.pair_key) return { ...safeDefault(signal), reason: 'unpaired' };
+  if (!pairing.relay_device_id) return { ...safeDefault(signal), reason: 'no-relay-device-id' };
+
+  const windowMs = Math.max(1000, Number(deps.windowMs) || 3 * 60 * 1000);
+  const pollMs = Math.max(250, Number(deps.pollMs) || 3000);
+  const relayBase = deps.relayBase || relayBaseFromEnv();
+  const requestId = deps.requestId || genRequestId();
+
+  // 1. Deposit the (encrypted) decision request; the relay wakes the device.
+  try {
+    const body = await buildEscalationDeposit(pairing.pair_key, requestId, buildEscalationPayload(consultRequest, consultResponse), { windowMs });
+    const res = await fetchFn(`${relayBase}/escalation/${encodeURIComponent(pairing.relay_device_id)}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...relayAuthHeader(pairing) },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(deps.depositTimeoutMs || 8000),
+    });
+    if (!res || !res.ok) return { ...safeDefault(signal), reason: `deposit-failed-${res && res.status}`, request_id: requestId };
+  } catch (e) {
+    return { ...safeDefault(signal), reason: `deposit-error:${String(e && e.message || e)}`, request_id: requestId };
+  }
+
+  // 2. Poll for the decision until the window lapses.
+  const deadline = now() + windowMs;
+  const pollUrl = `${relayBase}/escalation/response/${encodeURIComponent(requestId)}`;
+  while (now() < deadline) {
+    await wait(pollMs);
+    let body = null;
+    try {
+      const res = await fetchFn(pollUrl, { headers: relayAuthHeader(pairing), signal: AbortSignal.timeout(deps.pollTimeoutMs || 8000) });
+      if (res && res.ok) body = await res.json();
+    } catch { /* transient — keep polling */ }
+    if (!body) continue;
+    const data = await unwrapEscalationResponse(pairing.pair_key, body);
+    if (!data || !DECISION_OUTCOME[data.decision]) continue;   // ignore unparseable/unknown decisions; keep waiting
+    return {
+      resolved: true,
+      decision: data.decision,
+      proceed: data.decision !== 'deny',
+      note: typeof data.note === 'string' ? data.note : undefined,
+      modified: data.decision === 'modify' ? (data.modified ?? null) : undefined,
+      outcome: DECISION_OUTCOME[data.decision],
+      request_id: requestId,
+      signal,
+    };
+  }
+  // 3. Window lapsed — safe default (hold; no learning).
+  return { ...safeDefault(signal), request_id: requestId };
+}

package/fingerprint-source.js

@@ -12,6 +12,8 @@ import { readFile } from 'fs/promises';
 import { resolve } from 'path';
 import { hasPairingRecord, loadPairingRecord, loadFingerprintFromPhone, PhoneError } from './phone-source.js';
 import { defaultStateDir, writeCache, readCache, clearCache } from './cache.js';
+import { foldLocalCapture, isLocalCaptureOwner } from './capture-local.js';
+import { Capabilities, AuthoredSource } from './lib/phaedo-crypto.js';
 
 // §4.1 protocol-identity normalization (consumer defense-in-depth, 2026-06-16).
 // A stored fingerprint from a producer that predates identity stamping (or whose
@@ -38,6 +40,39 @@ function normalizeIdentity(vd) {
   return { ...vd, phaedo_fingerprint: { ...fp, ...patch } };
 }
 
+
+// §5 CANONICAL ON READ — the step-3 read path, applied ONCE at the boundary.
+//
+// The agent's authored-content readers (ap2.js buildIntentMandatePayload, autonomy-promotion.js,
+// consult-core.js delegation authoring) all take a FINGERPRINT, not a vault. Threading the §5
+// configuration through every one of them would mean changing four signatures and every caller,
+// and would leave four places that must each remember to check §5.4.
+//
+// Folding here instead makes every downstream reader correct by construction, and means step 3
+// (deleting fp.standing_rules) changes nothing about what any of them see. One fold, one §5.4
+// check, one place to be wrong.
+//
+// §5.4 matters more on this path than anywhere else: these entries become AUTHORIZATIONS — what
+// the agent may do without asking — so a configuration belonging to another identity, or to a
+// fingerprint since replaced by a restore or a cross-device merge, must not govern. Falls back
+// to the A-home rather than throwing; an agent that cannot resolve policy must still run the
+// safe path.
+export function foldConfigHome(vd) {
+  if (!vd || typeof vd !== 'object') return vd;
+  const fp = vd.phaedo_fingerprint;
+  const cfg = vd.phaedo_user_configuration;
+  if (!fp || typeof fp !== 'object' || !cfg || typeof cfg !== 'object') return vd;
+  if (!Capabilities || !AuthoredSource) return vd;          // vendored module missing → leave as-is
+  if (!AuthoredSource.configGoverns(cfg, fp)) return vd;    // §5.4 — not this subject's
+  if (!Array.isArray(cfg.standing_instructions)) return vd; // not a statement about rules
+  const next = { ...fp };
+  // An EMPTY standing_instructions is a statement ("no rules"), not an absence — leaving the
+  // A-home in place there would resurrect rules the subject deleted (#247's lesson).
+  if (cfg.standing_instructions.length) next.standing_rules = cfg.standing_instructions;
+  else delete next.standing_rules;
+  return { ...vd, phaedo_fingerprint: next };
+}
+
 // Resolution order for the local fixture (1a):
 //   1. PHAEDO_FINGERPRINT env var (absolute or cwd-relative path)
 //   2. ./fingerprint.json next to the server
@@ -52,6 +87,35 @@ function resolveSourcePath(baseDir) {
 //     phaedo_session_metrics }
 // Throws on unreadable/invalid source — the tool layer maps that to
 // decryption_failed (the §9.5 "couldn't obtain plaintext fingerprint" case).
+// PROVENANCE. A cache fallback used to be indistinguishable from a live phone read — same
+// object, same shape, no marker anywhere — so an agent answered "yes, you're pre-approved"
+// from a 22-hour-old snapshot with total confidence, and `pull.js` printed "Read your
+// profile from the phone" either way. There was no signal to notice. Callers that make
+// AUTHORITY decisions must be able to tell the difference.
+//
+// Carried on a SYMBOL deliberately: it never serializes, never reaches a schema, never rides
+// a sync, and cannot be mistaken for spec'd fingerprint content. It is a fact about THIS
+// read, not about the artifact.
+export const SOURCE = Symbol('phaedo.fingerprint.source');
+
+function stamp(vd, cached) {
+  if (!vd || typeof vd !== 'object') return vd;
+  const cachedAt = Number(cached?.cachedAt) || null;   // readCache returns { vault, cachedAt }
+  try {
+    Object.defineProperty(vd, SOURCE, {
+      value: { live: false, cachedAt, ageMs: cachedAt ? Date.now() - cachedAt : null },
+      enumerable: false, configurable: true, writable: true,
+    });
+  } catch { /* frozen object — provenance is best-effort, never fatal */ }
+  return vd;
+}
+
+/** Provenance of a loaded fingerprint. Absent marker → a live read. */
+export function sourceOf(vd) {
+  const s = vd && vd[SOURCE];
+  return s || { live: true, cachedAt: null, ageMs: 0 };
+}
+
 export async function loadFingerprint(baseDir) {
   // Explicit local source wins over phone pairing: if PHAEDO_FINGERPRINT names a
   // file, honor it and skip the phone entirely. Pointing at a concrete fingerprint
@@ -69,7 +133,7 @@ export async function loadFingerprint(baseDir) {
     try {
       const vd = await loadFingerprintFromPhone(rec);
       await writeCache(stateDir, vd);
-      return normalizeIdentity(vd);
+      return foldConfigHome(normalizeIdentity(vd));
     } catch (err) {
       // A 4xx means the phone REACHED us and rejected this client (revoked /
       // invalid credentials / failed handshake). Revocation must be effective:
@@ -81,7 +145,7 @@ export async function loadFingerprint(baseDir) {
         throw err;
       }
       const cached = await readCache(stateDir);
-      if (cached) return normalizeIdentity(cached.vault); // phone unreachable → encrypted cache (may be stale)
+      if (cached) return stamp(foldConfigHome(normalizeIdentity(cached.vault)), cached); // phone unreachable → encrypted cache (may be stale)
       throw err;                        // no phone + no cache → cannot serve
     }
   }
@@ -98,7 +162,17 @@ export async function loadFingerprint(baseDir) {
   if (!vd || typeof vd !== 'object' || !vd.phaedo_fingerprint) {
     throw new Error(`Fingerprint source at ${path} is missing phaedo_fingerprint.`);
   }
-  return normalizeIdentity(vd);
+  // mcp-local capture tier (desktop-capture-deposit.md §4 tier 3): unpaired,
+  // phone-less serving is the one configuration where NOBODY else drains what the
+  // capture hook accumulated on this machine — fold its local state into the
+  // served fingerprint at read time (capture-local.js; read-time overlay, no
+  // persistence, idempotent). Owner-gated: a paired setup never reaches this
+  // branch, and an explicit PHAEDO_FINGERPRINT ("use THIS file") stays verbatim —
+  // it is the hermetic-test escape hatch.
+  if (!process.env.PHAEDO_FINGERPRINT && await isLocalCaptureOwner(hasPairingRecord(baseDir))) {
+    return foldConfigHome(normalizeIdentity(await foldLocalCapture(vd)));
+  }
+  return foldConfigHome(normalizeIdentity(vd));
 }
 
 // Like loadFingerprint, but PREFERS the at-rest encrypted cache over a live phone pull.
@@ -129,7 +203,7 @@ export async function loadFingerprint(baseDir) {
 export async function loadFingerprintPreferCache(baseDir) {
   if (!process.env.PHAEDO_FINGERPRINT && hasPairingRecord(baseDir)) {
     const cached = await readCache(defaultStateDir());
-    if (cached) return normalizeIdentity(cached.vault);
+    if (cached) return stamp(foldConfigHome(normalizeIdentity(cached.vault)), cached);
   }
   return loadFingerprint(baseDir);
 }