phaedo-mcp 0.1.1 → 0.2.0

package/consult-policy.js

@@ -49,6 +49,14 @@ export function normalizePolicies(raw) {
       magMax: m.magnitude_max != null ? magRank(m.magnitude_max) : null,
       reversible: typeof m.reversible === 'boolean' ? m.reversible : null,
       amountGt: typeof m.amount_gt === 'number' && isFinite(m.amount_gt) ? m.amount_gt : null,
+      // Conditional + revocable authority (§10.5). `expiresAt` is ENFORCED: a lapsed
+      // authorization stops firing (time-bound = revocable, no identity needed; the
+      // direction is always authority-NARROWING, so it's fail-safe). `agents` is
+      // RESERVED (parsed, not yet enforced): scoping authority to specific agents needs
+      // an AUTHENTICATED agent identity — a self-asserted agent_id would be false
+      // security — so enforcement waits for that (build-later).
+      expiresAt: typeof r.expires_at === 'string' && Number.isFinite(Date.parse(r.expires_at)) ? Date.parse(r.expires_at) : null,
+      agents: Array.isArray(r.agents) ? r.agents.map((a) => String(a).toLowerCase()).filter(Boolean) : [],
       effect,
       note: typeof r.note === 'string' ? r.note : null,
     });
@@ -56,16 +64,50 @@ export function normalizePolicies(raw) {
   return out;
 }
 
-// Merge policy sources, most-portable first:
-//   1. inside the fingerprint (`phaedo_fingerprint.consult_policies`) — rides
-//      `inner.data` on the phone pull, so it travels everywhere the fingerprint
-//      does (extension ↔ phone ↔ MCP) with NO profile-schema change. Preferred
-//      home for authored, synced policies.
-//   2. a top-level vault sibling (`phaedo_consult_policies`) — local/extension use.
-//   3. opts.policies — a loaded local file (server: mcp/consult-policies.json).
+// Project the AUTHORIZATION-kind entries of `standing_rules` (Proposal 0007 — the
+// single authored home) into the raw consult_policies rule shape normalizePolicies
+// consumes. `kind:"instruction"` entries are verbatim injection rules, not gates —
+// the resolver ignores them. `note` falls back to the injectable `text` so the
+// rationale_hint still names the rule.
+function authorizationsFromStandingRules(fp) {
+  const rules = Array.isArray(fp?.standing_rules) ? fp.standing_rules : [];
+  return rules
+    .filter((r) => r && r.kind === 'authorization' && r.effect)
+    .map((r) => ({ id: r.instruction_id || null, match: r.match || {}, effect: r.effect, note: r.note || r.text || null, expires_at: r.expires_at, agents: r.agents }));
+}
+
+// Project a bound `kind:"instruction"` (Proposal 0007 §D) into a consultation BIAS.
+// An instruction carries prose + a `decision` dimension + polarity, but not a
+// structured enum value, so it cannot resolve a dimension to a value the way an
+// inferred signal does. v0.1 semantics, deliberately conservative: a NEGATIVE
+// (anti-preference / "I won't…") bound rule nudges the matching-domain consultation
+// one step cautious (bias_cautious) — authored rules may make the agent MORE
+// deferential, never less. POSITIVE-polarity rules expand autonomy, the riskier
+// direction, and are NOT projected in v0.1 (they still inject verbatim); that is
+// gated behind structured per-dimension values. An unscoped (no decision.domain)
+// rule biases all actions cautious — global by construction.
+function biasesFromStandingRules(fp) {
+  const rules = Array.isArray(fp?.standing_rules) ? fp.standing_rules : [];
+  return rules
+    .filter((r) => r && r.kind === 'instruction' && r.decision && r.decision.polarity === 'negative')
+    .map((r) => ({ id: r.instruction_id || null, match: { domains: r.decision.domain ? [r.decision.domain] : [] }, effect: 'bias_cautious', note: r.text || null }));
+}
+
+// Merge policy sources, the authored home first:
+//   1. `phaedo_fingerprint.standing_rules` — the Proposal 0007 authored home:
+//      kind:authorization → a deterministic gate; kind:instruction bound negative →
+//      a cautious bias (§D). Rides `inner.data` on the phone pull, travels everywhere
+//      the fingerprint does (extension ↔ phone ↔ MCP) with NO profile-schema change.
+//   2. `phaedo_fingerprint.consult_policies` — DEPRECATED (0007) back-compat read path.
+//   3. a top-level vault sibling (`phaedo_consult_policies`) — DEPRECATED, local/extension use.
+//   4. opts.policies — a loaded local file (server: mcp/consult-policies.json).
+// Force rules (authorizations) always take precedence over bias rules in applyPolicies,
+// so ordering within the list only affects which same-class rule wins (first match).
 // Defensive — never throws.
 export function loadPolicies(vd, opts = {}) {
   let list = [];
+  try { list = list.concat(normalizePolicies(authorizationsFromStandingRules(vd?.phaedo_fingerprint))); } catch { /* ignore */ }
+  try { list = list.concat(normalizePolicies(biasesFromStandingRules(vd?.phaedo_fingerprint))); } catch { /* ignore */ }
   try { list = list.concat(normalizePolicies(vd?.phaedo_fingerprint?.consult_policies)); } catch { /* ignore */ }
   try { list = list.concat(normalizePolicies(vd?.phaedo_consult_policies)); } catch { /* ignore */ }
   try { if (opts.policies) list = list.concat(normalizePolicies(opts.policies)); } catch { /* ignore */ }
@@ -94,9 +136,16 @@ function ruleMatches(rule, n) {
 // This is the engine behind the lightweight `phaedo_check_authorization` pre-flight
 // (brief M3) — an agent can ask "is this already decided by a standing rule?" without
 // paying for a full consultation. voice_draft is exempt (a redirect, not a decision).
-export function matchAuthorization(n, policies) {
+// A rule is ACTIVE only if it has not lapsed (§10.5 revocable authority). `expiresAt`
+// is enforced; `agents` scoping is reserved (see normalizePolicies). Authority-narrowing
+// only — an expired rule simply stops applying.
+function ruleActive(rule, now) {
+  return !(rule.expiresAt != null && now >= rule.expiresAt);
+}
+
+export function matchAuthorization(n, policies, { now = Date.now() } = {}) {
   if (!policies || !policies.length || n.type === 'voice_draft') return null;
-  const matched = policies.filter((r) => ruleMatches(r, n));
+  const matched = policies.filter((r) => ruleActive(r, now) && ruleMatches(r, n));
   const force = matched.find((r) => r.effect in FORCE);
   if (!force) return null;
   return { rule: force, signal: FORCE[force.effect], note: force.note || FORCE_NOTES[force.effect] };
@@ -107,10 +156,10 @@ export function matchAuthorization(n, policies) {
 // Else apply the first matching BIAS rule (nudge one step on the ladder). Returns a
 // NEW response (§10.3 shape preserved; provenance in rationale_hint). voice_draft is
 // never policy-overridden (it's a redirect, not a decision).
-export function applyPolicies(response, n, policies) {
+export function applyPolicies(response, n, policies, { now = Date.now() } = {}) {
   if (!policies || !policies.length || n.type === 'voice_draft') return response;
 
-  const auth = matchAuthorization(n, policies);
+  const auth = matchAuthorization(n, policies, { now });
   if (auth) {
     return {
       ...response,
@@ -121,7 +170,7 @@ export function applyPolicies(response, n, policies) {
     };
   }
 
-  const matched = policies.filter((r) => ruleMatches(r, n));
+  const matched = policies.filter((r) => ruleActive(r, now) && ruleMatches(r, n));
   const bias = matched[0];
   if (!bias) return response;
   const i = LADDER.indexOf(response.signal);

package/consult.js

@@ -14,12 +14,14 @@ import { loadPolicies, applyPolicies } from './consult-policy.js';
 import { PhaedoError } from './errors.js';
 import {
   resolveConsultationCore, buildConsultationResponse, checkAuthorization, normalizeRequest,
-  shape, SIGNALS, CONSULTATION_TYPES, validateVaultShape,
+  shape, SIGNALS, CONSULTATION_TYPES, validateVaultShape, consultDrivers,
+  deriveDelegationSignals, withDelegationSignals, buildDelegationPromotions, DELEGATION_PROMOTION_FLOOR,
+  authoredDelegationSignals,
 } from './consult-core.js';
 
 // Re-export the core surface so existing importers (server.js, tests,
 // spec/test-schemas.mjs) keep their `from './consult.js'` paths.
-export { CONSULTATION_TYPES, buildConsultationResponse, resolveConsultationCore, checkAuthorization, validateVaultShape };
+export { CONSULTATION_TYPES, buildConsultationResponse, resolveConsultationCore, checkAuthorization, validateVaultShape, consultDrivers, deriveDelegationSignals, withDelegationSignals, buildDelegationPromotions, DELEGATION_PROMOTION_FLOOR, authoredDelegationSignals };
 
 // ── Model resolver (richest fingerprint, LOCAL compute — opt-in) ──────────────
 // When a local model is configured (PHAEDO_CONSULT_MODEL + an Ollama/OpenAI-

package/fingerprint-source.js

@@ -13,6 +13,31 @@ import { resolve } from 'path';
 import { hasPairingRecord, loadPairingRecord, loadFingerprintFromPhone, PhoneError } from './phone-source.js';
 import { defaultStateDir, writeCache, readCache, clearCache } from './cache.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
+// phone copy was never re-persisted) can arrive missing the REQUIRED §4.1 fields
+// — `npm run health` surfaced exactly this on a live fingerprint. The
+// deterministic ones (phaedo_protocol_version, schema_revision) are safe for any
+// consumer to ensure; subject_id falls back to the existing, stable, non-PII
+// `fingerprint_id` when absent, rather than minting a value that would churn on
+// every load. This makes the reference server serve §4.1-conformant fingerprints
+// regardless of producer staleness. Source cleanup (re-persisting these on the
+// phone) remains the producer's job. SEMANTIC hygiene (episodic/opaque content)
+// is deliberately NOT masked here: health keeps surfacing it as an honest
+// producer signal, and context-block's render guard protects the AI projection.
+const IDENTITY_PROTOCOL_VERSION = '0.1';
+const IDENTITY_SCHEMA_REVISION = 1;
+function normalizeIdentity(vd) {
+  const fp = vd && vd.phaedo_fingerprint;
+  if (!fp || typeof fp !== 'object') return vd;
+  const patch = {};
+  if (fp.phaedo_protocol_version === undefined) patch.phaedo_protocol_version = IDENTITY_PROTOCOL_VERSION;
+  if (fp.schema_revision === undefined) patch.schema_revision = IDENTITY_SCHEMA_REVISION;
+  if (fp.subject_id === undefined && typeof fp.fingerprint_id === 'string' && fp.fingerprint_id) patch.subject_id = fp.fingerprint_id;
+  if (!Object.keys(patch).length) return vd;
+  return { ...vd, phaedo_fingerprint: { ...fp, ...patch } };
+}
+
 // Resolution order for the local fixture (1a):
 //   1. PHAEDO_FINGERPRINT env var (absolute or cwd-relative path)
 //   2. ./fingerprint.json next to the server
@@ -44,7 +69,7 @@ export async function loadFingerprint(baseDir) {
     try {
       const vd = await loadFingerprintFromPhone(rec);
       await writeCache(stateDir, vd);
-      return vd;
+      return normalizeIdentity(vd);
     } catch (err) {
       // A 4xx means the phone REACHED us and rejected this client (revoked /
       // invalid credentials / failed handshake). Revocation must be effective:
@@ -56,7 +81,7 @@ export async function loadFingerprint(baseDir) {
         throw err;
       }
       const cached = await readCache(stateDir);
-      if (cached) return cached.vault; // phone unreachable → encrypted cache (may be stale)
+      if (cached) return normalizeIdentity(cached.vault); // phone unreachable → encrypted cache (may be stale)
       throw err;                        // no phone + no cache → cannot serve
     }
   }
@@ -73,5 +98,38 @@ 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 vd;
+  return normalizeIdentity(vd);
+}
+
+// Like loadFingerprint, but PREFERS the at-rest encrypted cache over a live phone pull.
+// Used by the escalation path so reading the fingerprint (to compute the consult signal)
+// doesn't trigger a SECOND prompt — the fingerprint-read AUTHORIZE — on top of the
+// escalation decision card the subject already answers. One prompt per escalation, not two.
+//
+// The cache is seeded + refreshed by the normal live-pull consults, so it stays current; a
+// consult SIGNAL tolerates a slightly-stale fingerprint (it doesn't change minute to minute).
+// Falls back to a live pull only when no cache exists yet (first run on this machine), which
+// seeds it. Revocation safety is unaffected: a revoked MCP's escalation can't be decrypted by
+// the phone anyway (its client entry is gone), so it never reaches the subject regardless of
+// what the MCP read locally.
+// Like loadFingerprint, but PREFERS the at-rest encrypted cache over a live phone pull.
+// Used by the escalation path so reading the fingerprint (to compute the consult signal)
+// NEVER triggers an interactive fingerprint-read AUTHORIZE on top of the escalation
+// decision card. One prompt per escalation — the decision — not two, and critically no
+// authorize modal racing the decision modal on the phone (that double-present crashed iOS).
+//
+// Uses ANY decryptable cache regardless of age. Revocation is enforced PHONE-SIDE for the
+// escalation path: a revoked agent's escalation can't be decrypted by the phone (its client
+// registry entry is gone), so reading a stale cache here yields nothing the agent can
+// actually deliver to the subject. (The normal consult path — loadFingerprint — still does
+// the live pull with its 4xx-purge revocation, so a revoked agent stops getting fresh reads
+// there.) Falls through to a live pull ONLY when no cache exists at all (first run on this
+// machine), which seeds it; run one phaedo_consult after pairing to seed without an
+// escalation in flight.
+export async function loadFingerprintPreferCache(baseDir) {
+  if (!process.env.PHAEDO_FINGERPRINT && hasPairingRecord(baseDir)) {
+    const cached = await readCache(defaultStateDir());
+    if (cached) return normalizeIdentity(cached.vault);
+  }
+  return loadFingerprint(baseDir);
 }

package/hooks/session-start.mjs

@@ -20,7 +20,7 @@
 
 import { fileURLToPath } from 'url';
 import { dirname, resolve } from 'path';
-import { loadFingerprint } from '../fingerprint-source.js';
+import { loadFingerprintPreferCache } from '../fingerprint-source.js';
 import { buildInjectionResponse } from '../projection.js';
 
 // hooks/ lives one level under mcp/ — the sources resolve against mcp/.
@@ -37,7 +37,14 @@ function emitContext(text) {
 }
 
 async function run() {
-  const vd = await loadFingerprint(MCP_DIR);
+  // PREFER the at-rest encrypted cache over a live phone pull. Claude Code (and Claude
+  // Desktop's per-tab MCP spawn) runs SessionStart often — including on every tab bounce
+  // to a session that uses this hook — so a LIVE pull here surfaces a stray "authorize"
+  // sheet on the phone with no live caller behind it, since the user didn't initiate
+  // anything from the subject side. The cache is exactly what session-start should rely
+  // on: fast, non-interrupting, and refreshed by any real consult/escalate that follows.
+  // Same pattern that #76 applied to escalation (cache-preferred fingerprint read).
+  const vd = await loadFingerprintPreferCache(MCP_DIR);
   const response = buildInjectionResponse(vd, { requested_layers: ['all'], mode: 'standard' });
   if (response && response.projection) emitContext(response.projection);
 }

package/install.mjs

@@ -356,6 +356,12 @@ async function main(argv) {
       } else {
         console.log('       • Claude Code: `--code-hook` makes it automatic at every session start.');
       }
+      console.log('  4. Let Phaedo learn how you delegate — set `phaedo_record_outcome`');
+      console.log('     to "Always allow" in your client\'s tool-permission settings.');
+      console.log('     It records when you override an agent (the act-as-me signal); on');
+      console.log('     "Ask" it prompts every time, so the learning stays cold if skipped.');
+      console.log('     It only writes a local, encrypted audit receipt — nothing leaves the');
+      console.log('     device, and an authored rule still needs your explicit endorsement.');
     }
     if (opts.pair && !opts.dryRun && touched.length) return runPairing();
   }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.1.1",
+  "version": "0.2.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).",
   "mcpName": "io.github.galavoxx/phaedo-mcp",
-  "homepage": "https://getphaedo.com",
+  "homepage": "https://phaedo.so",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/galavoxx/phaedo-mcp.git"
@@ -33,6 +33,7 @@
     "consult-policy.js",
     "receipts.js",
     "agreement.js",
+    "calibration.js",
     "phone-source.js",
     "cache.js",
     "pairing.js",
@@ -54,15 +55,19 @@
     "start": "node server.js",
     "build": "node build-package.mjs",
     "prepack": "node build-package.mjs",
+    "pretest": "node build-package.mjs",
     "setup": "node install.mjs",
     "setup:pair": "node install.mjs --pair",
     "setup:code-hook": "node install.mjs --code-hook",
     "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-receipts.mjs && node test-agreement.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-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",
     "receipts": "node receipts.js list",
     "agreement": "node agreement.js",
+    "calibration": "node calibration.js",
+    "health": "node health.js",
+    "validate": "node ../spec/validate-fingerprint.mjs sample-fingerprint.json",
     "smoke": "node test-smoke.mjs",
     "smoke:phone": "node test-phone-boundary.mjs",
     "smoke:cache": "node test-cache.mjs",
@@ -71,8 +76,10 @@
     "smoke:install": "node test-install.mjs",
     "smoke:consult": "node test-consult.mjs",
     "smoke:policy": "node test-consult-policy.mjs",
+    "smoke:escalation": "node test-escalation.mjs",
     "smoke:receipts": "node test-receipts.mjs",
-    "smoke:agreement": "node test-agreement.mjs"
+    "smoke:agreement": "node test-agreement.mjs",
+    "smoke:calibration": "node test-calibration.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/pairing.js

@@ -137,6 +137,17 @@ export async function pairAtEndpoint(endpoint, { code, relayDeviceId = null, log
   if (outcome === 'denied')  throw new Error('pairing was denied on the phone');
   if (outcome === 'timeout') throw new Error('timed out waiting for phone confirmation');
 
+  // The relay lane id: prefer the one resolved during a relay rendezvous, but a LAN
+  // pairing ALSO needs it (the escalation channel + fp-mailbox deposit to the relay by
+  // this id). The phone returns its current relay_device_id in the /v1/pair response
+  // (localServer.ts), so capture it whichever rendezvous we used — without it, a LAN
+  // pairing has no relay lane and phaedo_escalate fails with "no-relay-device-id".
+  const relayId = relayDeviceId || body.relay_device_id || null;
+  // Per-device bearer (relay/auth.js): the phone shares the secret it minted with paired
+  // clients so they can authenticate to the relay AS this device. Without it,
+  // escalation/fp-mailbox deposits get 401.
+  const relaySecret = body.relay_device_secret || null;
+
   return {
     endpoint,
     client_id:     body.client_id,
@@ -144,7 +155,8 @@ export async function pairAtEndpoint(endpoint, { code, relayDeviceId = null, log
     pair_key:      b64uEnc(pairKey),
     vault_pub:     body.vault_pub,
     sas,
-    ...(relayDeviceId ? { relay_device_id: relayDeviceId } : {}),
+    ...(relayId ? { relay_device_id: relayId } : {}),
+    ...(relaySecret ? { relay_device_secret: relaySecret } : {}),
   };
 }
 

package/receipts.js

@@ -87,8 +87,18 @@ async function writeStore(stateDir, store, now) {
 // 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, now = Date.now() }) {
+export function buildReceipt({ via, agentId, 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.
+  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 } : {}),
+    ...(d?.value != null ? { value: String(d.value) } : {}),
+    confidence: typeof d?.confidence === 'number' ? d.confidence : null,
+    basis: typeof d?.basis === 'string' ? d.basis : null,
+  })) : [];
   return {
     receipt_id: crypto.randomUUID(),
     created_at: new Date(now).toISOString(),
@@ -109,6 +119,7 @@ export function buildReceipt({ via, agentId, request, response, now = Date.now()
       confidence: typeof response?.confidence === 'number' ? response.confidence : null,
       deference_level: response?.deference_level ?? null,
     },
+    ...(drv.length ? { drivers: drv } : {}),
     user_action: null,
   };
 }

package/sample-fingerprint.json

@@ -1,6 +1,9 @@
 {
   "phaedo_fingerprint": {
+    "phaedo_protocol_version": "0.1",
     "fingerprint_id": "sample-0000-0000-0000-000000000000",
+    "subject_id": "sample-subj-0000-0000-000000000000",
+    "schema_revision": 1,
     "updated_at": "2026-06-01T12:00:00.000Z",
     "persona_strength": 0.58,
     "layers": {