phaedo-mcp 0.3.0 → 0.3.1

package/install.mjs

@@ -35,6 +35,18 @@ const CAPTURE_HOOK_PATH = join(BASE_DIR, 'hooks', 'session-end.mjs');
 const ENTRY_KEY = 'phaedo';
 const HOOK_MARKER = 'hooks/session-start.mjs';         // identifies our SessionStart entry
 const CAPTURE_HOOK_MARKER = 'hooks/session-end.mjs';   // identifies our SessionEnd capture entry
+// The same capture, run on Stop (end of each turn) for sessions that stay open for days
+// (the desktop app's) — throttled per session inside the hook, so most Stops cost one read.
+const STOP_CAPTURE_HOOK_PATH = join(BASE_DIR, 'hooks', 'stop-capture.mjs');
+const STOP_CAPTURE_HOOK_MARKER = 'hooks/stop-capture.mjs';
+const SHIP_HOOK_PATH = join(BASE_DIR, 'hooks', 'pre-ship.mjs');
+const SHIP_HOOK_MARKER = 'hooks/pre-ship.mjs';           // identifies our ship-consult entries
+// The ship hook (consult before a merge / deploy / phone build) runs on four Bash events:
+// before the command, when a prompt is shown (the evidence a person was asked), and after
+// it ran or failed (to record that person's yes). Its own budget is 12s; the timeout is
+// the backstop.
+export const SHIP_HOOK_EVENTS = ['PreToolUse', 'PermissionRequest', 'PostToolUse', 'PostToolUseFailure'];
+const SHIP_HOOK_ENTRY = { matcher: 'Bash', timeout: 15 };
 
 // ── Client registry ──────────────────────────────────────────────────────────
 // Every supported client stores MCP servers as a top-level `mcpServers` object,
@@ -74,7 +86,13 @@ export function serverEntry({ nodePath = process.execPath, serverPath = SERVER_P
   return entry;
 }
 
-// ── Consult model judge config (on by default) ────────────────────────────────
+// ── Consult model judge config (OFF by default — opt in) ──────────────────────
+// Was on by default. Measured 2026-10-18 on the dev Mac against the same cached profile:
+// llama3.1:8b answered a $12k IRREVERSIBLE payment `clarify 0.9` on one run and
+// `proceed_with_note 0.9` on the next — flipping between runs, toward proceeding, with
+// high confidence both times — where the rule engine says `clarify` every time. A judge
+// that can talk itself into a payment does not get to be the default. Opt in with
+// --model-judge (auto-detect) or --consult-model <id> (pin).
 // The MCP server runs the consult model judge when PHAEDO_CONSULT_MODEL is set;
 // it falls back to the local rule engine if the model/Ollama isn't there, so
 // defaulting it ON is safe. We write a LOCAL endpoint only (privacy-clean); a
@@ -88,15 +106,21 @@ export function buildConsultEnv({ model = DEFAULT_CONSULT_MODEL, url = DEFAULT_C
 }
 
 // Probe local Ollama so "on by default" works with whatever model the user has.
-// Picks the first installed general-purpose model (skips the phaedo extraction
-// fine-tune). Falls back to the default string + reachable:false on any failure.
+// Prefers the default when it is installed, else the first installed CHAT model —
+// skipping the phaedo extraction fine-tunes and embedding models. An embedding model
+// cannot answer a chat prompt: `nomic-embed-text` was picked on the dev Mac (it sorts
+// before llama3.1:8b), every judge call failed in ~15 ms and fell back to the rules,
+// and the installer kept printing "model judge ON" for a judge that had never run.
+// Falls back to the default string + reachable:false on any failure.
+const NOT_A_JUDGE = /phaedo|extract|embed|nomic|bge|minilm|mxbai|arctic|e5-|gte-|rerank/i;
 export async function detectConsultModel({ url = DEFAULT_CONSULT_URL, fallback = DEFAULT_CONSULT_MODEL, fetchImpl = globalThis.fetch } = {}) {
   try {
     const res = await fetchImpl(`${url.replace(/\/$/, '')}/api/tags`, { signal: AbortSignal.timeout(1500) });
     if (!res.ok) return { model: fallback, reachable: false, hadModels: false };
     const data = await res.json();
     const names = (data.models || []).map((m) => m.name || m.model).filter(Boolean);
-    const general = names.find((n) => !/phaedo|extract/i.test(n));
+    const bare = (n) => String(n).replace(/:latest$/, '');
+    const general = names.find((n) => bare(n) === bare(fallback)) || names.find((n) => !NOT_A_JUDGE.test(n));
     return { model: general || fallback, reachable: true, hadModels: names.length > 0, picked: !!general };
   } catch {
     return { model: fallback, reachable: false, hadModels: false };
@@ -161,14 +185,18 @@ const isPhaedoHookEntryFor = (marker) => (e) =>
 
 // Generic per-event merge/remove — the SessionStart (injection) and SessionEnd
 // (capture) entries use the same shape, distinguished by their script-path marker.
-export function mergeHookEntry(settings, event, command, marker) {
+// `matcher` / `timeout` (optional) are for tool events: the ship hook filters to Bash.
+export function mergeHookEntry(settings, event, command, marker, { matcher, timeout } = {}) {
   const isOurs = isPhaedoHookEntryFor(marker);
   const next = { ...settings, hooks: { ...(settings.hooks || {}) } };
   const prior = Array.isArray(next.hooks[event]) ? next.hooks[event] : [];
   const others = prior.filter((e) => !isOurs(e)); // drop a stale phaedo entry (path refresh)
   const existing = prior.find(isOurs);
-  const already = !!existing && existing.hooks.some((h) => h.command === command);
-  next.hooks[event] = [...others, { hooks: [{ type: 'command', command }] }];
+  const handler = { type: 'command', command, ...(timeout ? { timeout } : {}) };
+  const entry = { ...(matcher ? { matcher } : {}), hooks: [handler] };
+  const already = !!existing && existing.matcher === entry.matcher &&
+    existing.hooks.some((h) => h.command === command && h.timeout === handler.timeout);
+  next.hooks[event] = [...others, entry];
   return { settings: next, changed: !already };
 }
 
@@ -208,11 +236,18 @@ export function applyCodeHook({ action, dryRun = false, home = homedir() } = {})
     if (!read.existed) return { name, status: 'absent', detail: 'no settings.json' };
     const start = removeSessionStartHook(read.config);
     const both = removeHookEntry(start.settings, 'SessionEnd', CAPTURE_HOOK_MARKER);
-    if (!start.changed && !both.changed) return { name, status: 'absent', detail: 'no phaedo hook to remove' };
-    if (!dryRun) { backup(path); writeConfig(path, both.settings); }
+    const stop = removeHookEntry(both.settings, 'Stop', STOP_CAPTURE_HOOK_MARKER);
+    let s = stop.settings;
+    let shipChanged = false;
+    for (const ev of SHIP_HOOK_EVENTS) {
+      const r = removeHookEntry(s, ev, SHIP_HOOK_MARKER);
+      s = r.settings; shipChanged = shipChanged || r.changed;
+    }
+    if (!start.changed && !both.changed && !stop.changed && !shipChanged) return { name, status: 'absent', detail: 'no phaedo hook to remove' };
+    if (!dryRun) { backup(path); writeConfig(path, s); }
     return { name, status: dryRun ? 'would-remove' : 'removed', detail: path };
   }
-  // Always install SessionStart injection. Only install the SessionEnd CAPTURE hook
+  // Always install SessionStart injection. Only install the SessionEnd + Stop CAPTURE hooks
   // when its dependencies actually resolve from THIS install location: the hook loads
   // capture/* and extraction/delta-lift.js via lib/capture-home.js — repo root in a
   // clone, mcp/vendor/ in the published tarball (build-package.mjs vendors the
@@ -225,17 +260,27 @@ export function applyCodeHook({ action, dryRun = false, home = homedir() } = {})
   let captureNote = '';
   if (captureHookAvailable()) {
     const both = mergeHookEntry(settings, 'SessionEnd', hookCommand({ hookPath: CAPTURE_HOOK_PATH }), CAPTURE_HOOK_MARKER);
-    settings = both.settings; captureChanged = both.changed;
+    const stop = mergeHookEntry(both.settings, 'Stop', hookCommand({ hookPath: STOP_CAPTURE_HOOK_PATH }), STOP_CAPTURE_HOOK_MARKER);
+    settings = stop.settings; captureChanged = both.changed || stop.changed;
   } else {
     // Never leave a broken capture hook wired if we can't run it here.
     const rm = removeHookEntry(settings, 'SessionEnd', CAPTURE_HOOK_MARKER);
-    settings = rm.settings; captureChanged = rm.changed;
+    const rmStop = removeHookEntry(rm.settings, 'Stop', STOP_CAPTURE_HOOK_MARKER);
+    settings = rmStop.settings; captureChanged = rm.changed || rmStop.changed;
     captureNote = ' (capture hook skipped — not available in this install; injection only)';
   }
-  const changed = start.changed || captureChanged;
+  // Ship hook: consult before a merge / deploy / phone build. Its imports are all inside
+  // mcp/, so it runs wherever the server does — no availability gate needed.
+  let shipChanged = false;
+  for (const ev of SHIP_HOOK_EVENTS) {
+    const r = mergeHookEntry(settings, ev, hookCommand({ hookPath: SHIP_HOOK_PATH }), SHIP_HOOK_MARKER, SHIP_HOOK_ENTRY);
+    settings = r.settings; shipChanged = shipChanged || r.changed;
+  }
+  const changed = start.changed || captureChanged || shipChanged;
   if (!changed) return { name, status: 'unchanged', detail: `already configured${captureNote}` };
   if (!dryRun) { if (read.existed) backup(path); writeConfig(path, settings); }
-  return { name, status: dryRun ? 'would-write' : 'configured', detail: path + captureNote };
+  return { name, status: dryRun ? 'would-write' : 'configured', detail: path + captureNote,
+    restartHint: 'Start a new Claude Code session — hooks load when a session starts.' };
 }
 
 // The SessionEnd capture hook can only run where its imported modules resolve —
@@ -370,6 +415,7 @@ function parseArgs(argv) {
     else if (a === '--consult-model') opts.consultModel = argv[++i];
     else if (a === '--consult-url') opts.consultUrl = argv[++i];
     else if (a === '--no-model-judge') opts.noModelJudge = true;
+    else if (a === '--model-judge') opts.modelJudge = true;
     else if (a === '--capture-model') opts.captureModel = argv[++i];
     else if (a === '--capture-url') opts.captureUrl = argv[++i];
     else if (a === '--help' || a === '-h') opts.help = true;
@@ -396,10 +442,11 @@ const HELP = `Phaedo MCP installer
   node install.mjs --dry-run       preview changes, write nothing
   node install.mjs --only <id>     one client only: claude-desktop | cursor | claude-code
 
-  Consult model judge (ON by default, local Ollama, falls back to the rule engine):
-  node install.mjs --consult-model <id>   pin the model (e.g. llama3.1:8b)
+  Consult model judge (OFF by default — the rule engine answers; opt in below):
+  node install.mjs --model-judge          turn it on, auto-detecting a local Ollama chat model
+  node install.mjs --consult-model <id>   turn it on with a pinned model (e.g. llama3.1:8b)
   node install.mjs --consult-url <url>    endpoint (default http://localhost:11434)
-  node install.mjs --no-model-judge       rule engine only (no model env)
+  node install.mjs --no-model-judge       rule engine only (the default; kept for scripts)
 `;
 
 function runPairing() {
@@ -427,12 +474,12 @@ async function main(argv) {
 
   const action = opts.uninstall ? 'uninstall' : 'install';
 
-  // Consult model judge: ON by default. Pin it if --consult-model is given,
-  // otherwise probe local Ollama and pick an installed general model. Off with
-  // --no-model-judge. Always falls back to the rule engine at runtime, so a
-  // missing model never breaks consultation.
+  // Consult model judge: OFF unless asked for (see the measurement above buildConsultEnv).
+  // --consult-model pins one; --model-judge probes local Ollama for an installed chat model.
+  // Always falls back to the rule engine at runtime, so a missing model never breaks
+  // consultation. A plain install REMOVES a judge env an earlier default-on install wrote.
   let env = {}, consultNote = '';
-  if (action === 'install' && !opts.noModelJudge) {
+  if (action === 'install' && !opts.noModelJudge && (opts.consultModel || opts.modelJudge)) {
     const url = opts.consultUrl || DEFAULT_CONSULT_URL;
     if (opts.consultModel) {
       env = buildConsultEnv({ model: opts.consultModel, url });
@@ -445,7 +492,7 @@ async function main(argv) {
         : `model judge ON → ${d.model} @ ${url} (Ollama not detected — falls back to the rule engine until it's running)`;
     }
   } else if (action === 'install') {
-    consultNote = 'model judge OFF (rule engine only)';
+    consultNote = 'model judge OFF — the rule engine answers (opt in: --model-judge)';
   }
   const entry = serverEntry({ env });
   console.log(`Phaedo MCP — ${action}${opts.dryRun ? ' (dry run)' : ''}`);
@@ -490,7 +537,7 @@ async function main(argv) {
       console.log('\nNext:');
       console.log('  1. Pair with your phone:  npm run pair   (or re-run with --pair)');
       console.log('  2. Restart any client that was already open:');
-      for (const r of touched) console.log(`       • ${r.name}: ${r.restartHint}`);
+      for (const r of touched) if (r.restartHint) console.log(`       • ${r.name}: ${r.restartHint}`);
       console.log('  3. Inject your fingerprint at session start:');
       console.log('       • any client: run the `/phaedo` prompt (one click), or call');
       console.log('         the `phaedo_request_injection` tool.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",
@@ -32,6 +32,9 @@
     "consult.js",
     "consult-core.js",
     "consult-policy.js",
+    "consult-runtime.js",
+    "ship-actions.js",
+    "ship-readout.js",
     "action-binding.js",
     "autonomy-promotion.js",
     "ap2.js",
@@ -80,9 +83,10 @@
     "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-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",
+    "test": "node test-smoke.mjs && node test-no-profile.mjs && node test-phone-boundary.mjs && node test-cache.mjs && node test-pairing.mjs && node test-revoke.mjs && node test-install.mjs && node test-consult.mjs && node test-consult-policy.mjs && node test-amount-bands.mjs && node test-resolver-revision.mjs && node test-ship-actions.mjs && node test-ship-hook.mjs && node test-ship-readout.mjs && node test-action-binding.mjs && node test-autonomy-promotion.mjs && node test-ap2.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-capture-sync.mjs && node test-capture-hook.mjs && node test-stop-capture.mjs && node test-capture-local.mjs && node test-capture-a11y.mjs && node test-vendored-capture.mjs && node test-escalation.mjs && node test-domain.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-calibration.mjs && node test-identity.mjs && node test-signing.mjs && node test-sign-request.mjs && node test-signing-audit.mjs && node test-delegation-domain-fragmentation.mjs && node test-stale-authority.mjs && node test-config-home-fold.mjs && node test-precedence-and-ceiling.mjs && node test-package-closure.mjs",
     "receipts": "node receipts.js list",
     "agreement": "node agreement.js",
+    "ship-readout": "node ship-readout.js",
     "calibration": "node calibration.js",
     "health": "node health.js",
     "validate": "node ../spec/validate-fingerprint.mjs sample-fingerprint.json",

package/phone-source.js

@@ -163,7 +163,12 @@ async function getSession(rec, deps) {
 // (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 || {};
+  // Prefer every paired browser's counters combined (`metrics_combined`, 2026-10-01): the subject
+  // is one person across browsers, and `metrics` is only the browser that posted last. A phone
+  // that predates the sibling sends only `metrics`, which still serves.
+  const m = (inner.metrics_combined && typeof inner.metrics_combined === 'object' && !Array.isArray(inner.metrics_combined))
+    ? inner.metrics_combined
+    : (inner.metrics || {});
   return {
     phaedo_fingerprint: inner.data,
     ...(inner.user_configuration && typeof inner.user_configuration === 'object'

package/receipts.js

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

package/server.js

@@ -16,8 +16,8 @@ import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
-import { loadFingerprint, loadFingerprintPreferCache, sourceOf } from './fingerprint-source.js';
-import { hasPairingRecord, loadPairingRecord, readServingClientId } from './phone-source.js';
+import { loadFingerprint, sourceOf } from './fingerprint-source.js';
+import { hasPairingRecord, loadPairingRecord } from './phone-source.js';
 import { depositDelegationSuggestions } from './delegation-sync.js';
 import { depositReceiptsDigest, drainAndApplyMarks } from './receipts-sync.js';
 import { buildDelegationPromotions } from './consult-core.js';
@@ -27,8 +27,9 @@ import { buildIntentMandatePayload } from './ap2.js';
 import { depositSignRequest, pollSignOnce } from './signing-request.js';
 import { buildSigningAuditRecord, appendSigningAudit } from './signing-audit.js';
 import { buildInjectionResponse, errorResponse, PhaedoError } from './projection.js';
-import { resolveConsultation, checkAuthorization, consultOptsFromEnv, CONSULTATION_TYPES, consultDrivers, deriveDelegationSignals, withDelegationSignals, authoredDelegationSignals } from './consult.js';
+import { resolveConsultation, checkAuthorization, CONSULTATION_TYPES, consultDrivers, withRevision } from './consult.js';
 import { defaultStateDir } from './cache.js';
+import { buildConsultOpts, loadConsultVd } from './consult-runtime.js';
 import { buildReceipt, appendReceipt, receiptsCapFromEnv, readReceipts, markOutcome, USER_ACTIONS } from './receipts.js';
 
 const BASE_DIR = dirname(fileURLToPath(import.meta.url));
@@ -88,28 +89,6 @@ function withStaleAuthorityGuard(response, vd) {
   return out;
 }
 
-// Load the fingerprint for a consult and fold in the act-as-me channel: delegation
-// signals derived from this subject's own override history (§10.6 receipts). The
-// origin-aware resolver then lets a `delegation` correction outrank a `self` signal on
-// the same dimension. Best-effort — if receipts are unreadable, the consult still
-// answers from the plain fingerprint (delegation learning never breaks a consultation).
-async function loadConsultVd(baseDir, { preferCache = false } = {}) {
-  // preferCache (escalation): read the at-rest cache instead of a live phone pull, so the
-  // escalation doesn't add a fingerprint-read AUTHORIZE prompt on top of its decision card.
-  const vd = preferCache ? await loadFingerprintPreferCache(baseDir) : await loadFingerprint(baseDir);
-  try {
-    // Two delegation sources, both origin-aware: live override history (every override)
-    // + the subject's ENDORSED, portable delegation rules (authored_delegation). The
-    // authored rule thus shapes consult too, not only the §9 injection it already renders in.
-    const signals = deriveDelegationSignals(await readReceipts(defaultStateDir()))
-      .concat(authoredDelegationSignals(vd && vd.phaedo_fingerprint));
-    return withDelegationSignals(vd, signals);
-  } catch (e) {
-    process.stderr.write(`[phaedo-mcp] delegation derive skipped (consult unaffected): ${e.message}\n`);
-    return vd;
-  }
-}
-
 // Act-as-me PROMOTION (delegation-sync.js): when the override history shows an
 // ESTABLISHED pattern that isn't already authored/staged, deposit a delegation
 // SUGGESTION across the sync boundary (relay agent_to_ext) for the subject to review +
@@ -184,7 +163,9 @@ async function maybeDepositDelegationPromotions(vd) {
   }
 }
 
-const CONSULT_OPTS = consultOptsFromEnv(process.env);
+// Env config + the subject's deference policies + this install's paired-client id —
+// built in consult-runtime.js, the one copy the Claude Code ship hook shares.
+const CONSULT_OPTS = buildConsultOpts(BASE_DIR, process.env);
 // Real-time escalation window (docs/roadmap/escalation-and-push.md §crux): how long a
 // blocking decision waits for the subject before the agent applies the safe-default
 // (hold). Configurable; bounded by the relay's own MAX_WINDOW_MS.
@@ -192,20 +173,6 @@ const ESCALATION_WINDOW_MS = (() => {
   const n = Number(process.env.PHAEDO_ESCALATION_WINDOW_MS);
   return Number.isFinite(n) && n > 0 ? n : 3 * 60 * 1000;
 })();
-// Deference policies: PHAEDO_CONSULT_POLICIES if set, else the default file beside
-// the server (mcp/consult-policies.json — what policy-editor.html produces). Zero
-// config: drop the file in and restart the client. (Portable vault policies in
-// phaedo_consult_policies always apply too, regardless of this file.)
-const POLICIES_PATH = process.env.PHAEDO_CONSULT_POLICIES || join(BASE_DIR, 'consult-policies.json');
-if (existsSync(POLICIES_PATH)) {
-  try { CONSULT_OPTS.policies = JSON.parse(readFileSync(POLICIES_PATH, 'utf8')); }
-  catch (e) { process.stderr.write(`[phaedo-mcp] ignoring malformed consult policies (${POLICIES_PATH}): ${e.message}\n`); }
-}
-// §10.5 `agents`: this process's OWN paired-client identity, resolved once at startup.
-// One server serves one paired client, so it never asks a caller who is calling — it
-// reads who it IS. Null (unpaired / unreadable) makes `agents`-scoped RELAXING rules
-// inert, which is the fail-safe direction; the server still answers everything else.
-CONSULT_OPTS.clientId = readServingClientId(BASE_DIR);
 
 // Escalation PUSH policy (which signals wake the subject): the subject-configurable knob
 // over the stakes-gated default. Local file (PHAEDO_ESCALATION_POLICY, else
@@ -299,9 +266,18 @@ server.registerTool(
   {
     title: 'Consult the Phaedo fingerprint at a decision point',
     description:
-      "Ask how the user's cognitive pattern bears on a decision — without ingesting the fingerprint. " +
-      'Returns a signal (proceed | proceed_with_note | clarify | escalate | decline), a confidence, a ' +
-      'short rationale_hint, and a deference_level (how strongly to weight it). Use at agent decision points.',
+      // Names the MOMENTS. "Use at agent decision points" told no agent when it was at one: not
+      // one consultation was written between 2026-07-28 and 2026-10-18. And it closes the loop —
+      // the receipt_id is the only handle that attributes the user's reaction to THIS action.
+      'Ask how the user would want an action handled, before you take it on their behalf — without ' +
+      'reading their profile. Call it BEFORE any consequential action you are about to take for the ' +
+      'user: merging or deploying, publishing or posting, sending a message, paying or committing money, ' +
+      'deleting, or changing an account or setting. Describe the action in action_descriptor (domain, ' +
+      'reversible, magnitude, a short summary; amount when money moves) and bind it to the exact call ' +
+      'with action_binding. Returns a signal (proceed | proceed_with_note | clarify | escalate | decline | ' +
+      'insufficient_signal), a confidence, a short rationale_hint, a deference_level (how strongly to ' +
+      'weight it) and a receipt_id. Keep the receipt_id: when the user reacts to what you did — confirms ' +
+      'it, overrides it, or wants it done differently — record that with phaedo_record_outcome.',
     inputSchema: {
       consultation_type: z.enum(CONSULTATION_TYPES),
       agent_id: z.string().optional(),
@@ -334,12 +310,12 @@ server.registerTool(
       // the two tools an autonomous agent actually uses answered from a possibly-revoked cached
       // profile with no downgrade and no provenance. That is the 2026-07-25 device defect (a
       // revoked $500 grant honoured from a 22h cache) still live on the paths that matter most.
-      const response = withStaleAuthorityGuard(
-        await resolveConsultation(vd, args || {}, CONSULT_OPTS), vd);
+      const raw = await resolveConsultation(vd, args || {}, CONSULT_OPTS);
+      const response = withStaleAuthorityGuard(raw, vd);
       // Provenance for the local audit receipt only — the cues that drove this
       // (never in `response`; §10.4). Best-effort: a failure must not block the answer.
       let drivers = [];
-      try { drivers = consultDrivers(vd, args || {}); } catch { /* provenance is non-critical */ }
+      try { drivers = withRevision(consultDrivers(vd, args || {}, CONSULT_OPTS), raw); } catch { /* provenance is non-critical */ }
       const receiptId = await emitReceipt('phaedo_consult', args, response, drivers); // every resolution, abstains included
       if (receiptId) response.receipt_id = receiptId;   // the handle for phaedo_record_outcome
       await maybeDepositDelegationPromotions(vd);                    // act-as-me promotion (best-effort)
@@ -450,10 +426,13 @@ server.registerTool(
   {
     title: 'Record what the subject decided about a consulted action',
     description:
-      'After you consulted Phaedo and the USER decided what to do, record their outcome on the receipt: ' +
-      'approved | rejected | modified | unknown. Record what the USER chose, NOT whether you proceeded. ' +
-      'A rejected/modified outcome teaches Phaedo how the user wants delegated work handled (the act-as-me ' +
-      'channel). Defaults to the most recent receipt; pass receipt_id to mark a specific one.',
+      'Record what the USER decided about an action you consulted Phaedo on: approved | rejected | ' +
+      'modified | unknown. Call it when the user reacts to that action — they confirm it (approved), ' +
+      'refuse or undo it (rejected), or want it done differently (modified). Always pass the receipt_id ' +
+      'that phaedo_consult (or a Phaedo hook) gave you; without it the most recent receipt is marked, ' +
+      'which may be a different action. Record what the user chose, never whether you proceeded: ' +
+      'silence is not approval, and an approval you inferred teaches nothing. A rejected/modified ' +
+      'outcome teaches Phaedo how the user wants delegated work handled (the act-as-me channel).',
     inputSchema: {
       outcome: z.enum(USER_ACTIONS),
       receipt_id: z.string().optional(),
@@ -547,10 +526,10 @@ server.registerTool(
       // UNCONDITIONALLY, so without the guard it always reasoned from a possibly-stale profile
       // and then told the agent the signal was not blocking — i.e. "just proceed", and never
       // wake the subject, on authority that may have been revoked hours earlier.
-      const response = withStaleAuthorityGuard(
-        await resolveConsultation(vd, req, CONSULT_OPTS), vd);
+      const raw = await resolveConsultation(vd, req, CONSULT_OPTS);
+      const response = withStaleAuthorityGuard(raw, vd);
       let drivers = [];
-      try { drivers = consultDrivers(vd, req); } catch { /* non-critical */ }
+      try { drivers = withRevision(consultDrivers(vd, req, CONSULT_OPTS), raw); } catch { /* non-critical */ }
       const escReceiptId = await emitReceipt('phaedo_escalate', req, response, drivers);   // the decision being escalated
       await maybeDepositReceiptsDigest();                              // G1+G2 audit channel
 

package/server.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.phaedo-labs/phaedo-mcp",
-  "description": "Carry your Phaedo cognitive fingerprint into any MCP client: injection, consults, escalation, mandate signing.",
-  "version": "0.3.0",
+  "description": "Carry your Phaedo cognitive fingerprint into any MCP client: inject, consult, escalate, sign.",
+  "version": "0.3.1",
   "repository": {
     "url": "https://github.com/phaedo-labs/phaedo-mcp",
     "source": "github",
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "phaedo-mcp",
-      "version": "0.3.0",
+      "version": "0.3.1",
       "transport": {
         "type": "stdio"
       }

package/ship-actions.js

@@ -0,0 +1,164 @@
+// Ship actions — which shell commands are a decision the subject would want consulted on.
+//
+// The precedent track's Phase 1 (docs/roadmap/precedent-and-sync-design-2026-09-13.md) is
+// starved of outcome data because nothing consults: no receipt has been written since
+// 2026-07-28. The decisions the subject actually delegates, every week, are the ones a
+// coding agent takes on their behalf — merging a PR, deploying the relay, cutting a phone
+// build. This module names those, so the PreToolUse hook (hooks/pre-ship.mjs) can consult
+// before they run. Everything else a shell does is not a decision and is ignored.
+//
+// PURE: (command string) -> classification | null. No I/O.
+
+import { createHash } from 'node:crypto';
+
+// One entry per class. `match` sees one simple command, already split out of a compound
+// line and stripped of env assignments and `npx`. The descriptor is what the consult
+// reasons about — magnitude is the stakes, reversible is whether it can be walked back.
+const CLASSES = [
+  {
+    id: 'merge_pr',
+    // `gh pr merge` — reversible (a revert), medium. `--admin` skips required checks, which
+    // is a different act: high.
+    match: (w) => w[0] === 'gh' && w[1] === 'pr' && w[2] === 'merge',
+    describe: (w) => {
+      const num = w.slice(3).find((x) => /^#?\d+$/.test(x));
+      const admin = w.includes('--admin');
+      // `-R/--repo` names the repository when the agent is not inside it; the hook passes it
+      // through when it asks GitHub for the PR's check state (B6).
+      const ri = w.findIndex((x) => x === '-R' || x === '--repo');
+      const repo = ri >= 0 ? w[ri + 1] : (w.find((x) => x.startsWith('--repo='))?.split('=')[1]);
+      return {
+        magnitude: admin ? 'high' : 'medium',
+        reversible: true,
+        summary: `${admin ? 'admin-merge' : 'merge'} ${num ? `PR #${num.replace('#', '')}` : "this branch's PR"}`,
+        pr: num ? num.replace('#', '') : null,
+        repo: repo || null,
+      };
+    },
+  },
+  {
+    id: 'deploy',
+    // `fly deploy` — production for every paired phone. Reversible (`fly releases` rollback)
+    // but high: a bad relay breaks sync for everyone until it is rolled back.
+    match: (w) => (w[0] === 'fly' || w[0] === 'flyctl') && w[1] === 'deploy',
+    describe: (w) => {
+      const i = w.findIndex((x) => x === '-a' || x === '--app');
+      const app = i >= 0 ? w[i + 1] : null;
+      return { magnitude: 'high', reversible: true, summary: `deploy${app ? ` ${app}` : ''} to Fly` };
+    },
+  },
+  {
+    id: 'app_build',
+    // `eas build` — a build artifact, nothing reaches a device yet. Low.
+    match: (w) => isEas(w[0]) && w[1] === 'build',
+    describe: (w) => ({ magnitude: 'low', reversible: true, summary: `phone build${platform(w)}` }),
+  },
+  {
+    id: 'app_submit',
+    // `eas submit` (or `eas build --auto-submit`) — the build goes to TestFlight / the store.
+    match: (w) => isEas(w[0]) && (w[1] === 'submit' || (w[1] === 'build' && w.includes('--auto-submit'))),
+    describe: (w) => ({ magnitude: 'medium', reversible: true, summary: `submit phone build${platform(w)}` }),
+  },
+  {
+    id: 'push_main',
+    // A direct push to the default branch, skipping review. A force-push there rewrites
+    // shared history: high, and not cleanly reversible.
+    match: (w) => w[0] === 'git' && w[1] === 'push' && w.slice(2).some((x) => /^\+?(?:[^:]*:)?(?:refs\/heads\/)?(?:main|master)$/.test(x)),
+    describe: (w) => {
+      const force = w.some((x) => x === '-f' || x === '--force' || x.startsWith('--force-with-lease') || x.startsWith('+'));
+      return force
+        ? { magnitude: 'high', reversible: false, summary: 'force-push to main' }
+        : { magnitude: 'medium', reversible: true, summary: 'push directly to main' };
+    },
+  },
+];
+
+// Order matters for one pair: `eas build --auto-submit` is a submit, not a build.
+const ORDER = ['merge_pr', 'deploy', 'app_submit', 'app_build', 'push_main'];
+
+function isEas(w0) { return w0 === 'eas' || w0 === 'eas-cli'; }
+function platform(w) {
+  const i = w.findIndex((x) => x === '--platform' || x === '-p');
+  const p = i >= 0 ? w[i + 1] : (w.find((x) => x.startsWith('--platform='))?.split('=')[1]);
+  return p ? ` (${p})` : '';
+}
+
+// Split a shell line into simple commands on && || ; | and newlines. Not a shell parser —
+// quotes are honoured only enough that `git commit -m "a && b"` does not split.
+export function splitCommands(line) {
+  const out = [];
+  let cur = '';
+  let q = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (q) { cur += c; if (c === q) q = null; continue; }
+    if (c === '"' || c === "'") { q = c; cur += c; continue; }
+    if (c === '\n' || c === ';' || c === '|' || (c === '&' && line[i + 1] === '&')) {
+      if (c === '&' || (c === '|' && line[i + 1] === '|')) i++;
+      out.push(cur); cur = '';
+      continue;
+    }
+    cur += c;
+  }
+  out.push(cur);
+  return out.map((s) => s.trim()).filter(Boolean);
+}
+
+// Words of one simple command, with leading env assignments, `npx`/`npx --yes`, and a
+// quoted-string's quotes removed.
+export function words(cmd) {
+  const w = (cmd.match(/"[^"]*"|'[^']*'|\S+/g) || []).map((x) => x.replace(/^["']|["']$/g, ''));
+  while (w.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(w[0])) w.shift();
+  if (w[0] === 'npx') { w.shift(); while (w[0] && w[0].startsWith('-')) w.shift(); }
+  // A path to the binary (`/opt/homebrew/bin/gh`, `./node_modules/.bin/eas`) is the binary.
+  if (w[0]) w[0] = w[0].split('/').pop();
+  return w;
+}
+
+// Stakes order for a line that chains several ship actions: irreversible first, then by
+// magnitude. A line that merges and then deploys is consulted on the deploy — consulting on
+// the merge would let the riskier half ride on the safer half's answer.
+const MAG_RANK = { low: 0, medium: 1, high: 2 };
+const stakes = (d) => (d.reversible === false ? 10 : 0) + (MAG_RANK[d.magnitude] ?? 1);
+
+/**
+ * Classify a Bash command. Returns null when no part of it is a ship action, else the
+ * highest-stakes ship action in it (ties: the first), with `multiple` set when the line
+ * chains more than one.
+ *
+ * @returns {null | { class, summary, multiple, action_descriptor, action_binding }}
+ */
+export function classifyShipCommand(command) {
+  if (typeof command !== 'string' || !command.trim()) return null;
+  const hits = [];
+  for (const seg of splitCommands(command)) {
+    const w = words(seg);
+    if (!w.length) continue;
+    for (const id of ORDER) {
+      const k = CLASSES.find((c) => c.id === id);
+      if (k.match(w)) { hits.push({ id, seg, d: k.describe(w) }); break; }
+    }
+  }
+  if (!hits.length) return null;
+  const first = hits.reduce((best, h) => (stakes(h.d) > stakes(best.d) ? h : best));
+  return {
+    class: first.id,
+    summary: first.d.summary,
+    multiple: hits.length > 1,
+    // merge_pr only: which PR, and in which repo (null = the current branch's, here).
+    ...(first.id === 'merge_pr' ? { pr: first.d.pr, repo: first.d.repo } : {}),
+    action_descriptor: {
+      domain: 'engineering',
+      reversible: first.d.reversible,
+      magnitude: first.d.magnitude,
+      summary: first.d.summary,
+    },
+    // §10.2 binding: the concrete call this descriptor claims to describe — a digest of the
+    // whole line, never the line itself beyond a short preview.
+    action_binding: {
+      tool_name: 'Bash',
+      arguments_hash: createHash('sha256').update(command).digest('hex'),
+      arguments_preview: first.seg.slice(0, 120),
+    },
+  };
+}