phaedo-mcp 0.2.2 → 0.3.1

package/fingerprint-source.js

@@ -5,13 +5,17 @@
 //   Phase 1b (phone): if a pairing record is configured (PHAEDO_PAIRING or
 //     mcp/pairing.json), authorize → pull /v1/profile → unwrap the §7.2 envelope
 //     from the paired phone (phone-source.js). Spec-faithful; no plaintext at rest.
-//   Phase 1a (local): otherwise read a local vault-payload JSON (or the shipped
-//     sample) — the decoupled stand-in that runs out of the box.
+//   Phase 1a (local): otherwise read a local vault-payload JSON. With neither, there is
+//     no profile — tools say so (NO_PROFILE_MESSAGE); the shipped sample is opt-in only.
 
 import { readFile } from 'fs/promises';
-import { resolve } from 'path';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
 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';
+import { PhaedoError } from './errors.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,20 +42,101 @@ 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)
+//   1. PHAEDO_FINGERPRINT env var (absolute or cwd-relative path, or `sample`)
 //   2. ./fingerprint.json next to the server
-//   3. ./sample-fingerprint.json (shipped demo fixture)
+//   — nothing else. There is deliberately NO silent fallback to the shipped sample.
+//
+// NO PROFILE IS AN ANSWER, NOT A DEMO. Until 2026-10-20 an unpaired install with no file fell
+// back to sample-fingerprint.json — so a stranger who ran `npx phaedo-mcp` had a made-up
+// person's style injected into their assistant, with nothing anywhere saying so (the response
+// carried `fingerprint_id: sample-0000…`, which no human reads). The sample is still one word
+// away for anyone who wants to try it — PHAEDO_FINGERPRINT=sample — but it has to be asked for.
+const SAMPLE_KEYWORD = 'sample';
+// The sample ships beside this module, whatever base dir the caller serves from.
+const SAMPLE_PATH = resolve(dirname(fileURLToPath(import.meta.url)), 'sample-fingerprint.json');
 function resolveSourcePath(baseDir) {
-  if (process.env.PHAEDO_FINGERPRINT) return resolve(process.cwd(), process.env.PHAEDO_FINGERPRINT);
+  const env = process.env.PHAEDO_FINGERPRINT;
+  if (env === SAMPLE_KEYWORD) return SAMPLE_PATH;
+  if (env) return resolve(process.cwd(), env);
   return resolve(baseDir, 'fingerprint.json');
 }
 
+// Read by the assistant (a tool error) and, through it, by the person — so plain words, and
+// it says what did NOT happen as well as what to do.
+export const NO_PROFILE_MESSAGE =
+  'No Phaedo profile is set up on this computer, so there is nothing to load and Phaedo has ' +
+  'not changed how the assistant responds. A profile comes from the Phaedo phone app, which is ' +
+  'not open to the public yet (https://phaedo.so to hear when it is). To try Phaedo with a made-up example profile ' +
+  'instead, set PHAEDO_FINGERPRINT=sample in this server\'s settings.';
+
 // Returns the vault payload:
 //   { phaedo_fingerprint, phaedo_behavioral_signals, phaedo_linguistic_profile,
 //     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 +154,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 +166,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
     }
   }
@@ -90,15 +175,29 @@ export async function loadFingerprint(baseDir) {
   let raw;
   try {
     raw = await readFile(path, 'utf8');
-  } catch {
-    // Fall back to the shipped sample so a fresh checkout runs out of the box.
-    raw = await readFile(resolve(baseDir, 'sample-fingerprint.json'), 'utf8');
+  } catch (err) {
+    // Only the default location may be absent quietly. A path the user NAMED that doesn't
+    // read is their mistake to see, not "no profile".
+    if (!process.env.PHAEDO_FINGERPRINT && err?.code === 'ENOENT') {
+      throw new PhaedoError('decryption_failed', NO_PROFILE_MESSAGE);
+    }
+    throw new PhaedoError('decryption_failed', `Could not read the Phaedo profile at ${path} (${err?.code || err?.message || err}).`);
   }
   const vd = JSON.parse(raw);
   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 +228,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);
 }

package/health.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Projection health report (P2) — `npm run health`, run during dogfooding.
+//
+// Loads the LIVE decrypted fingerprint (phone pairing / at-rest cache / local
+// file, via the normal source resolution) and runs the §4.6/§4.7 + projection-
+// hygiene checks over it, printing a MEASURED report: conformance + summary-
+// hygiene errors (Proposal P0) and §4.7 unresolved dimensions (Proposal 0006).
+// This is the "projection cleanliness" number for the end-of-window eval
+// (docs/roadmap/dogfooding-eval-2026-06.md). Read-only — no network writes.
+//
+// Exit: 0 = clean · 1 = hygiene errors · 2 = could not load a fingerprint.
+
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadFingerprint } from './fingerprint-source.js';
+import { validateFingerprint, resolveLayer } from '../spec/validate-fingerprint.mjs';
+
+const baseDir = dirname(fileURLToPath(import.meta.url));
+
+let vd;
+try { vd = await loadFingerprint(baseDir); }
+catch (e) { console.error(`Could not load a fingerprint: ${e.message}`); process.exit(2); }
+
+const fp = vd && vd.phaedo_fingerprint;
+if (!fp) { console.log('No fingerprint yet (empty vault) — nothing to check.'); process.exit(0); }
+
+const layers = fp.layers || {};
+const errs = validateFingerprint(fp);                 // structural + §4.6 + summary hygiene (P0)
+
+// §4.7 (Proposal 0006): count dimensions and flag the ones a thin/conflicting
+// evidence set leaves unresolved (which a consumer must treat conservatively).
+let dimCount = 0;
+const unresolved = [];
+for (const [lid, L] of Object.entries(layers)) {
+  const res = resolveLayer(L.signals || []);
+  for (const [field, r] of Object.entries(res)) {
+    if (!r) continue;
+    dimCount++;
+    if (r.status === 'unresolved') unresolved.push(`${lid}.${field}`);
+  }
+}
+const sigCount = Object.values(layers).reduce((n, L) => n + ((L.signals || []).length), 0);
+
+console.log(`\nPhaedo projection health — fingerprint ${fp.fingerprint_id || '(no id)'}`);
+console.log(`  layers ${Object.keys(layers).length} · signals ${sigCount} · resolved dimensions ${dimCount}`);
+console.log(`  conformance + projection-hygiene errors: ${errs.length}`);
+for (const e of errs) console.log(`    ✗ ${e}`);
+console.log(`  §4.7 unresolved dimensions (conflicting + thin evidence): ${unresolved.length}`);
+for (const u of unresolved) console.log(`    ⚠ ${u}`);
+
+const clean = errs.length === 0;
+console.log(`\n${clean ? '✓ projection clean' : `✗ ${errs.length} hygiene issue(s)`}` +
+  `${unresolved.length ? ` · ${unresolved.length} unresolved dimension(s)` : ''}\n`);
+process.exit(clean ? 0 : 1);

package/hooks/pre-ship.mjs

@@ -0,0 +1,409 @@
+#!/usr/bin/env node
+// Phaedo — Claude Code ship hook (PreToolUse, PermissionRequest, PostToolUse,
+// PostToolUseFailure on Bash).
+//
+// WHY THIS EXISTS. The precedent track is starved: no consultation has been written since
+// 2026-07-28, so agreement, calibration and override learning have nothing to read. The
+// decisions this subject actually delegates, every week, are the ones a coding agent takes
+// for them — merging a PR, deploying the relay, cutting a phone build. This hook consults
+// Phaedo before those run (ship-actions.js names them) and writes a §10.6 receipt, so the
+// receipts accumulate in normal use instead of waiting for an agent to remember a tool.
+//
+// WHAT IT MAY DO — ONE RULE. The hook only ever ADDS friction; it never removes it. It
+// never returns `allow`, so it cannot pre-approve anything Claude Code would otherwise
+// have asked about. On a permissive answer it returns no decision at all (Claude Code's
+// own permission flow applies unchanged); on a cautious one it returns `ask`, which puts
+// the action in front of the subject. That is why it reads the at-rest profile cache and
+// skips the server's stale-authority guard: the guard exists to stop a stale read from
+// EXPANDING autonomy, and nothing here can.
+//
+// WHERE OUTCOMES COME FROM — SUBJECT-AUTHORED ONLY (§10.6 honesty rail). The one thing the
+// hook records itself is a yes the subject gave on a prompt, and it records that only on
+// EVIDENCE that the prompt was shown: Claude Code fires PermissionRequest when it is about
+// to show one. So, per call:
+//   - prompt shown, then the command ran → the subject said yes → `approved`. Whatever the
+//     consult answered, and in any permission mode — a yes on a `proceed` is the scoreable
+//     case agreement needs.
+//   - prompt shown, then declined → Claude Code fires NO hook for a manual denial
+//     (documented), so the agent is told the receipt id up front and records `rejected`.
+//   - no prompt (bypass mode, an allow rule) → nothing recorded. After the run the agent is
+//     told so, and records the subject's reaction only if they give one. Silence is never
+//     approval.
+// This replaces a guess: whether a hook's `ask` still prompts under bypassPermissions is
+// not documented, and no longer needs to be.
+//
+// FAIL-SAFE: any error, timeout or unrecognised input exits 0 with no output, so a broken
+// Phaedo never blocks or slows a merge beyond the budget. Wire it with
+// `npm run setup:code-hook` (install.mjs adds all four events).
+
+import { fileURLToPath } from 'url';
+import { dirname, resolve, join } from 'path';
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
+import { createHash } from 'crypto';
+import { execFile } from 'child_process';
+import { classifyShipCommand } from '../ship-actions.js';
+import { isMainModule } from '../lib/is-main.js';
+
+const MCP_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Never hold a command up for long. A consult with a model judge configured can take its
+// own timeout (PHAEDO_CONSULT_TIMEOUT_MS, default 15s); past this the hook says nothing.
+export const BUDGET_MS = 12000;
+
+// Signals that hand the action to the subject. `insufficient_signal` is not one: an
+// abstain is Phaedo saying it does not know, which is no reason to interrupt anyone.
+export const ASKING_SIGNALS = new Set(['escalate', 'clarify', 'decline']);
+
+// Permission modes in which a PermissionRequest is not evidence that a PERSON answered:
+// auto mode's classifier and dontAsk decide without one.
+const NO_HUMAN_MODES = new Set(['auto', 'dontAsk']);
+
+// The profile is read from the at-rest cache, which only a live read refreshes. Past this
+// age the agent is told once a day, so the subject hears about it in plain words.
+export const STALE_PROFILE_DAYS = 14;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const PENDING_TTL_MS = DAY_MS;
+
+// The caller label on the receipt. `via` stays `phaedo_consult` — the hook runs a full
+// consultation through the same path, and the receipt schema's `via` enum is closed — so
+// the free-text, self-asserted `agent_id` is where "this came from the ship hook" lives.
+export const AGENT_ID = 'claude-code/ship-hook';
+
+export const commandHash = (cmd) => createHash('sha256').update(String(cmd ?? '')).digest('hex');
+
+// ── CI state for a merge (precedent track Phase 1b, B6) ───────────────────────────────
+// Merging a PR whose checks are failing, or have not finished, is a bigger act than merging a
+// green one — and nothing the agent declares says so. CAUTION-ONLY, by measurement: on the
+// dev Mac's profile a normal merge answers `proceed` with or without `evidence_provided`, and
+// on an admin merge green evidence only SOFTENS the answer (clarify → proceed_with_note). So
+// green is RECORDED and changes nothing; failing or unfinished raises the merge to `high`.
+// The state comes from GitHub, read by the hook itself — never from the agent.
+export const CI_LOOKUP_MS = 4000;
+
+/** statusCheckRollup → 'red' | 'pending' | 'green' | 'none' (no checks configured). */
+export function ciStateFromRollup(rollup) {
+  const list = Array.isArray(rollup) ? rollup : [];
+  if (!list.length) return 'none';
+  const FAIL = new Set(['FAILURE', 'ERROR', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE', 'STALE']);
+  const OK = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
+  let pending = false;
+  for (const c of list) {
+    // CheckRun: status + conclusion. StatusContext: state.
+    const v = String(c?.conclusion || c?.state || '').toUpperCase();
+    if (FAIL.has(v)) return 'red';
+    const done = c?.__typename === 'StatusContext' ? v && v !== 'PENDING' && v !== 'EXPECTED' : String(c?.status || '').toUpperCase() === 'COMPLETED';
+    if (!done || !OK.has(v)) pending = true;
+  }
+  return pending ? 'pending' : 'green';
+}
+
+// How each state changes the consult, and the words the subject reads on the prompt.
+export const CI_RAISES = new Set(['red', 'pending']);
+const CI_WORDS = { red: 'its checks are failing', pending: "its checks haven't finished" };
+
+// ── What a merge changes (precedent track Phase 1b, B3) ───────────────────────────────
+// The classifier calls every merge `medium` — a 2-line typo fix and a 2,000-line rewrite of
+// the rule engine alike. Two facts from the PR raise it to `high`; nothing lowers it (a
+// lowered magnitude could let a §10.5 grant capped at `low` fire — the widening direction).
+//
+// LARGE: more than LARGE_LINES changed lines or LARGE_FILES files, markdown excluded. Set from
+// the dev repo's last 60 merged PRs (code-only p50 135 lines / 3 files, p90 848 / 14): about
+// 1 PR in 12 crosses either line.
+export const LARGE_LINES = 1000;
+export const LARGE_FILES = 20;
+// SENSITIVE: a changed path that matters more than its size. Generic rules for any repo (CI
+// and deploy config, migrations, auth / crypto / secrets / security / permissions by name —
+// test files excluded from the name rule), plus the repo's own list in `.phaedo-sensitive`
+// (one path prefix or `*` glob per line, # comments). The list is read from the BASE branch,
+// so a PR cannot shrink it for itself, and a PR that edits the list is sensitive by definition.
+export const SENSITIVE_FILE = '.phaedo-sensitive';
+const GENERIC_SENSITIVE = [
+  /^\.github\/workflows\//, /(^|\/)Dockerfile$/, /(^|\/)fly\.toml$/, /\.tf$/, /(^|\/)migrations?\//,
+];
+const SENSITIVE_NAME = /(^|[\/_.-])(auth|crypto|secrets?|security|permissions?)([\/_.-]|$)/i;
+const TEST_PATH = /(^|\/)(tests?|__tests__)\/|(^|\/)test[-_]|[._-]test\.|\.spec\./i;
+
+/** Parse `.phaedo-sensitive` text → patterns. */
+export function parseSensitiveList(text) {
+  return String(text || '').split(/\r?\n/).map((l) => l.replace(/#.*$/, '').trim()).filter(Boolean);
+}
+function patternMatches(pattern, path) {
+  if (!pattern.includes('*')) return path === pattern || path.startsWith(pattern);
+  const re = new RegExp('^' + pattern.split('*').map((x) => x.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*'));
+  return re.test(path);
+}
+export function isSensitivePath(path, repoPatterns = []) {
+  const p = String(path || '');
+  if (!p) return false;
+  if (p === SENSITIVE_FILE) return true;
+  if (GENERIC_SENSITIVE.some((re) => re.test(p))) return true;
+  if (!TEST_PATH.test(p) && SENSITIVE_NAME.test(p)) return true;
+  return repoPatterns.some((pat) => patternMatches(pat, p));
+}
+
+/** (PR facts, repo patterns) → { large, sensitive, lines, files } — PURE. */
+export function diffStakes(facts, repoPatterns = []) {
+  const all = Array.isArray(facts?.files) ? facts.files : [];
+  const code = all.filter((f) => !/\.md$/i.test(String(f?.path || '')));
+  const lines = code.reduce((n, f) => n + (Number(f?.additions) || 0) + (Number(f?.deletions) || 0), 0);
+  // gh lists at most 100 files; past that, the count it reports is the floor of the truth.
+  const truncated = Number(facts?.changedFiles) > all.length;
+  const files = truncated ? Number(facts.changedFiles) : code.length;
+  const large = lines > LARGE_LINES || files > LARGE_FILES || truncated;
+  const sensitive = all.some((f) => isSensitivePath(f?.path, repoPatterns));
+  return { large, sensitive, lines, files };
+}
+export const stakesValue = (st) => (!st ? 'unknown' : st.large && st.sensitive ? 'large+sensitive' : st.large ? 'large' : st.sensitive ? 'sensitive' : 'normal');
+
+function run(cmd, args, cwd, timeoutMs) {
+  return new Promise((res) => {
+    try {
+      execFile(cmd, args, { cwd: cwd || undefined, timeout: timeoutMs, windowsHide: true, maxBuffer: 4 * 1024 * 1024 },
+        (err, stdout) => res(err ? null : String(stdout)));
+    } catch { res(null); }
+  });
+}
+
+/**
+ * One read-only GitHub lookup for everything the hook needs about a merge, via the gh CLI the
+ * agent itself uses: { ci, stakes } — ci 'unknown' and stakes null on any failure.
+ */
+export async function lookupPrFacts(ship, cwd, {
+  gh = process.env.PHAEDO_SHIP_GH || 'gh', git = process.env.PHAEDO_SHIP_GIT || 'git', timeoutMs = CI_LOOKUP_MS,
+} = {}) {
+  const args = ['pr', 'view', ...(ship.pr ? [ship.pr] : []), ...(ship.repo ? ['--repo', ship.repo] : []),
+    '--json', 'statusCheckRollup,files,changedFiles,baseRefName'];
+  const out = await run(gh, args, cwd, timeoutMs);
+  let j = null;
+  try { j = out ? JSON.parse(out) : null; } catch { j = null; }
+  if (!j || typeof j !== 'object') return { ci: 'unknown', stakes: null };
+  // The repo's own list, from the base branch. Only when the merge targets THIS checkout
+  // (no --repo); a list we cannot read is an empty list — the generic rules still apply.
+  let patterns = [];
+  if (!ship.repo && typeof j.baseRefName === 'string' && /^[\w./-]+$/.test(j.baseRefName)) {
+    const text = await run(git, ['show', `origin/${j.baseRefName}:${SENSITIVE_FILE}`], cwd, 2000);
+    patterns = parseSensitiveList(text);
+  }
+  return { ci: ciStateFromRollup(j.statusCheckRollup), stakes: diffStakes(j, patterns) };
+}
+
+/** Back-compat: the CI state alone. */
+export async function lookupCiState(ship, cwd, opts) { return (await lookupPrFacts(ship, cwd, opts)).ci; }
+
+// The words the subject reads, joined into one line.
+export function raiseWords(ci, stakes) {
+  const w = [];
+  if (CI_RAISES.has(ci)) w.push(CI_WORDS[ci]);
+  if (stakes?.large) w.push(`it's a large change (${stakes.lines.toLocaleString('en-US')} lines across ${stakes.files} files)`);
+  if (stakes?.sensitive) w.push('it touches sensitive files');
+  return w.join('; ');
+}
+
+// ── Hook state: tool_use_id → its consult, so later events can find it. ───────────────
+// Ids, a command DIGEST and flags only — never the command. Entries pruned after a day.
+export function readState(path) {
+  try {
+    const j = JSON.parse(readFileSync(path, 'utf8'));
+    if (j && typeof j === 'object' && j.pending && typeof j.pending === 'object') return j;
+  } catch { /* missing or corrupt → fresh */ }
+  return { pending: {} };
+}
+export function writeState(path, state, now) {
+  const pending = {};
+  for (const [k, v] of Object.entries(state.pending || {})) if (now - Date.parse(v?.at) < PENDING_TTL_MS) pending[k] = v;
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ ...state, pending }), { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+// What the subject reads on the prompt. Plain words, no numbers, no protocol terms.
+export function promptReason(signal, summary, why) {
+  const what = why ? `${summary} — ${why}` : summary;
+  if (signal === 'decline') return `Phaedo thinks you'd say no to this one: ${what}. Go ahead anyway?`;
+  if (signal === 'clarify') return `Phaedo isn't sure how you'd want this handled: ${what}. Go ahead?`;
+  return `Phaedo thinks you'd want to OK this yourself: ${what}.`;
+}
+
+// What the agent reads before the command. It carries the receipt id — the one handle
+// that attributes an outcome to THIS decision rather than whatever receipt is newest.
+export function preContext({ summary, signal, receiptId, asked, hint }) {
+  const head = `Phaedo was consulted before this command (${summary}) and answered "${signal}"` +
+    (hint ? ` — ${hint}` : '') + `. receipt_id: ${receiptId}.`;
+  if (asked) {
+    return `${head} Phaedo flagged it for the user, so they may be asked to confirm. If they decline, ` +
+      `call phaedo_record_outcome with this receipt_id and "rejected" (or "modified" if they want it ` +
+      `done differently). A yes on the prompt is recorded automatically.`;
+  }
+  return `${head} If the user reacts to this specific action when you report it — says it was right, ` +
+    `objects, or wants it changed — call phaedo_record_outcome with this receipt_id and "approved", ` +
+    `"rejected" or "modified". Record only what they actually said about it; silence is not approval, ` +
+    `and do not record anything because you proceeded.`;
+}
+
+// After the command, when Phaedo had flagged it and no prompt was shown.
+export function unpromptedContext(receiptId) {
+  return `No confirmation prompt was shown for this command (receipt_id: ${receiptId}), though Phaedo ` +
+    `had flagged it for the user. Tell them in one line that it ran and Phaedo had flagged it, and ` +
+    `record their reaction with phaedo_record_outcome and this receipt_id if they give one. Silence ` +
+    `is not approval.`;
+}
+
+export function staleContext(days, mcpDir) {
+  return `Also: Phaedo's copy of the user's profile is ${days} days old (their phone has not been ` +
+    `reached since). Mention once, in one line, that they can refresh it by running ` +
+    `\`cd ${mcpDir} && npm run pull\` and approving on their phone.`;
+}
+
+/**
+ * One hook invocation. Pure apart from injected deps, so the whole flow is testable
+ * without a vault, a receipt store or Claude Code.
+ *
+ * deps: { consult(req) → { response, drivers, source? }, writeReceipt({request,response,drivers}) → id,
+ *         markOutcome(id, action), statePath, now, mcpDir? }
+ * Returns the JSON object to print, or null for no output.
+ */
+export async function runShipHook(input, deps) {
+  if (!input || input.tool_name !== 'Bash') return null;
+  const now = deps.now ?? Date.now();
+  const ev = input.hook_event_name;
+
+  if (ev === 'PreToolUse') {
+    const ship = classifyShipCommand(input.tool_input?.command);
+    if (!ship) return null;
+    // B6 + B3: one GitHub lookup per merge — check state, size, paths. Each can only raise.
+    let ci = null, stakes = null;
+    if (ship.class === 'merge_pr') {
+      if (deps.prFacts) ({ ci, stakes } = await deps.prFacts(ship, input.cwd));
+      else if (deps.ciState) ci = await deps.ciState(ship, input.cwd);
+    }
+    const why = raiseWords(ci, stakes);
+    const raised = why !== '';
+    const request = {
+      consultation_type: 'action_approval',
+      agent_id: AGENT_ID,
+      action_descriptor: raised ? { ...ship.action_descriptor, magnitude: 'high' } : ship.action_descriptor,
+      action_binding: ship.action_binding,
+    };
+    const { response, drivers, source } = await deps.consult(request);
+    const signal = String(response?.signal || '');
+    // Provenance: what the hook saw, beside what drove the answer. Local receipt only.
+    const extra = [];
+    if (ci) extra.push({ cue: 'ciState', value: ci, confidence: null, basis: ci === 'unknown' ? null : 'observed' });
+    if (ci && deps.prFacts) extra.push({ cue: 'diffStakes', value: stakesValue(stakes), confidence: null, basis: stakes ? 'observed' : null });
+    const allDrivers = extra.length ? [...(drivers || []), ...extra] : drivers;
+    const receiptId = await deps.writeReceipt({ request, response, drivers: allDrivers });
+    if (!receiptId) return null;     // no receipt = nothing to learn from; stay out of the way
+    const asked = ASKING_SIGNALS.has(signal);
+
+    const state = readState(deps.statePath);
+    if (input.tool_use_id) {
+      state.pending[input.tool_use_id] = {
+        receipt_id: receiptId, cmd_hash: commandHash(input.tool_input?.command),
+        asked, prompt_shown: false, at: new Date(now).toISOString(),
+      };
+    }
+    let context = preContext({
+      summary: ship.summary, signal, receiptId, asked,
+      hint: typeof response?.rationale_hint === 'string' ? response.rationale_hint : '',
+    });
+    if (raised) context += ` GitHub shows ${why}, so Phaedo treated this merge as high-stakes.`;
+    const ageDays = source && source.live === false && Number.isFinite(source.ageMs) ? Math.floor(source.ageMs / DAY_MS) : 0;
+    if (ageDays >= STALE_PROFILE_DAYS && !(now - Date.parse(state.stale_noted_at) < DAY_MS)) {
+      context += ' ' + staleContext(ageDays, deps.mcpDir || MCP_DIR);
+      state.stale_noted_at = new Date(now).toISOString();
+    }
+    writeState(deps.statePath, state, now);
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        ...(asked ? { permissionDecision: 'ask', permissionDecisionReason: promptReason(signal, ship.summary, why) } : {}),
+        additionalContext: context,
+      },
+    };
+  }
+
+  if (ev === 'PermissionRequest') {
+    // Evidence that a prompt is about to be shown for this command. PermissionRequest has
+    // no tool_use_id (documented), so match the newest pending consult on the same command.
+    if (NO_HUMAN_MODES.has(input.permission_mode)) return null;
+    const h = commandHash(input.tool_input?.command);
+    const state = readState(deps.statePath);
+    const hit = Object.values(state.pending)
+      .filter((e) => e.cmd_hash === h && !e.prompt_shown)
+      .sort((a, b) => Date.parse(b.at) - Date.parse(a.at))[0];
+    if (!hit) return null;
+    hit.prompt_shown = true;
+    writeState(deps.statePath, state, now);
+    return null;                     // never decide here — the subject answers the prompt
+  }
+
+  if (ev === 'PostToolUse' || ev === 'PostToolUseFailure') {
+    if (!input.tool_use_id) return null;
+    const state = readState(deps.statePath);
+    const entry = state.pending[input.tool_use_id];
+    if (!entry) return null;
+    delete state.pending[input.tool_use_id];
+    writeState(deps.statePath, state, now);
+    // An interrupted command is the subject changing their mind mid-run, which is not a
+    // clean yes — record nothing.
+    if (ev === 'PostToolUseFailure' && input.is_interrupt) return null;
+    if (entry.prompt_shown) {
+      // The command started after a prompt, so the subject said yes. A failed command is
+      // still an approved decision.
+      await deps.markOutcome(entry.receipt_id, 'approved');
+      return null;
+    }
+    if (!entry.asked) return null;   // permissive + unprompted: the pre-context already said how
+    return { hookSpecificOutput: { hookEventName: ev, additionalContext: unpromptedContext(entry.receipt_id) } };
+  }
+  return null;
+}
+
+// ── Real deps: the same consult path as the MCP server (consult-runtime.js). ──────────
+async function realDeps() {
+  const { loadConsultVd, buildConsultOpts } = await import('../consult-runtime.js');
+  const { resolveConsultation, consultDrivers, withRevision } = await import('../consult.js');
+  const { buildReceipt, appendReceipt, receiptsCapFromEnv, markOutcome } = await import('../receipts.js');
+  const { sourceOf } = await import('../fingerprint-source.js');
+  const { defaultStateDir } = await import('../cache.js');
+  const stateDir = defaultStateDir();
+  const quiet = () => {};
+  const opts = buildConsultOpts(MCP_DIR, process.env, { warn: quiet });
+  return {
+    statePath: join(stateDir, 'ship-hook.json'),
+    mcpDir: MCP_DIR,
+    prFacts: (ship, cwd) => lookupPrFacts(ship, cwd),
+    async consult(request) {
+      const vd = await loadConsultVd(MCP_DIR, { preferCache: true, warn: quiet });
+      const response = await resolveConsultation(vd, request, opts);
+      let drivers = [];
+      try { drivers = withRevision(consultDrivers(vd, request, opts), response); } catch { /* provenance is non-critical */ }
+      return { response, drivers, source: sourceOf(vd) };
+    },
+    async writeReceipt({ request, response, drivers }) {
+      const r = buildReceipt({ via: 'phaedo_consult', agentId: AGENT_ID, clientId: opts.clientId, request, response, drivers });
+      await appendReceipt(stateDir, r, { cap: receiptsCapFromEnv(process.env) });
+      return r.receipt_id;
+    },
+    async markOutcome(id, action) { await markOutcome(stateDir, id, action); },
+  };
+}
+
+async function main() {
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  const input = JSON.parse(raw);
+  // Cheap exit before importing the vault stack: most Bash calls are not ship actions.
+  if (input?.tool_name !== 'Bash') return;
+  if (input.hook_event_name === 'PreToolUse' && !classifyShipCommand(input.tool_input?.command)) return;
+  const out = await runShipHook(input, await realDeps());
+  if (out) process.stdout.write(JSON.stringify(out));
+}
+
+if (isMainModule(import.meta.url)) {
+  const timeout = new Promise((res) => setTimeout(res, BUDGET_MS));
+  Promise.race([main().catch(() => {}), timeout])
+    .then(() => process.exit(0))
+    .catch(() => process.exit(0)); // a hook must never break the session
+}