phaedo-mcp 0.2.1 → 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,15 +1,15 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.2.1",
+  "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": {
     "type": "git",
-    "url": "git+https://github.com/phaedo-labs/phaedo.git",
+    "url": "git+https://github.com/phaedo-labs/phaedo-mcp.git",
     "directory": "mcp"
   },
   "keywords": [
@@ -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/pairing.js

@@ -124,6 +124,7 @@ export async function pairAtEndpoint(endpoint, { code, relayDeviceId = null, log
   // Long-term ECDH → pair_key; SAS (the MITM anchor) over both pubkeys.
   const shared  = await Identity.deriveSharedWithPeer(vaultPub);
   const pairKey = await Kdf.derivePairKey(shared, body.client_id);
+  shared.fill(0);   // raw ECDH secret consumed — zero it (matches phone-source.js key hygiene)
   const sas     = Kdf.formatSAS(await Kdf.deriveSAS(extPub, vaultPub));
 
   log('');
@@ -148,11 +149,14 @@ export async function pairAtEndpoint(endpoint, { code, relayDeviceId = null, log
   // escalation/fp-mailbox deposits get 401.
   const relaySecret = body.relay_device_secret || null;
 
+  const pairKeyEnc = b64uEnc(pairKey);
+  pairKey.fill(0);   // persisted as base64url below — zero the long-lived key buffer
+
   return {
     endpoint,
     client_id:     body.client_id,
     client_secret: body.client_secret,
-    pair_key:      b64uEnc(pairKey),
+    pair_key:      pairKeyEnc,
     vault_pub:     body.vault_pub,
     sas,
     ...(relayId ? { relay_device_id: relayId } : {}),

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,21 +23,52 @@
 // 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
     ? resolve(process.cwd(), process.env.PHAEDO_PAIRING)
     : resolve(baseDir, 'pairing.json');
-  const rec = JSON.parse(await readFile(path, 'utf8'));
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (e) {
+    // No pairing file = UNPAIRED (a valid local-only state), not an error. Return
+    // null so callers that pass the record to depositEscalation / pollEscalation /
+    // the best-effort deposit channels get a graceful "unpaired" instead of an
+    // ENOENT throw. (hasPairingRecord() gates the fingerprint-pull path, so it only
+    // calls this when the file exists.)
+    if (e && e.code === 'ENOENT') return null;
+    throw e;
+  }
+  const rec = JSON.parse(raw);
   for (const k of ['endpoint', 'client_id', 'client_secret', 'pair_key']) {
     if (!rec[k]) throw new Error(`Pairing record at ${path} is missing "${k}".`);
   }
@@ -43,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();
 
@@ -62,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();
@@ -88,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`);