phaedo-mcp 0.2.2 → 0.3.1

package/install.mjs

@@ -22,7 +22,7 @@
 //   node install.mjs --only cursor   restrict to one client id
 //   node install.mjs --help
 
-import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, copyFileSync, mkdirSync, rmSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
@@ -31,8 +31,22 @@ import { spawnSync } from 'child_process';
 const BASE_DIR = dirname(fileURLToPath(import.meta.url));
 const SERVER_PATH = join(BASE_DIR, 'server.js');
 const HOOK_PATH = join(BASE_DIR, 'hooks', 'session-start.mjs');
+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 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,
@@ -72,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
@@ -86,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 };
@@ -147,32 +173,54 @@ export function hookCommand({ nodePath = process.execPath, hookPath = HOOK_PATH
   return `"${nodePath}" "${hookPath}"`;
 }
 
-const isPhaedoHookEntry = (e) =>
+// Match the marker path-separator-agnostically: the marker uses forward slashes
+// ('hooks/session-end.mjs') but the command is built with path.join(), which on Windows
+// yields backslashes ('...\\hooks\\session-end.mjs'). Without normalizing, Windows never
+// recognizes its own hook entries — re-installs duplicate them and uninstall can't remove
+// them. Normalize both sides to forward slashes before the substring test.
+const norm = (s) => String(s).replace(/\\/g, '/');
+const isPhaedoHookEntryFor = (marker) => (e) =>
   e && Array.isArray(e.hooks) &&
-  e.hooks.some((h) => typeof h.command === 'string' && h.command.includes(HOOK_MARKER));
+  e.hooks.some((h) => typeof h.command === 'string' && norm(h.command).includes(norm(marker)));
 
-export function mergeSessionStartHook(settings, command) {
+// Generic per-event merge/remove — the SessionStart (injection) and SessionEnd
+// (capture) entries use the same shape, distinguished by their script-path 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.SessionStart) ? next.hooks.SessionStart : [];
-  const others = prior.filter((e) => !isPhaedoHookEntry(e)); // drop a stale phaedo entry (path refresh)
-  const existing = prior.find(isPhaedoHookEntry);
-  const already = !!existing && existing.hooks.some((h) => h.command === command);
-  next.hooks.SessionStart = [...others, { hooks: [{ type: 'command', command }] }];
+  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 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 };
 }
 
-export function removeSessionStartHook(settings) {
-  if (!settings.hooks || !Array.isArray(settings.hooks.SessionStart)) return { settings, changed: false };
-  const prior = settings.hooks.SessionStart;
-  const others = prior.filter((e) => !isPhaedoHookEntry(e));
+export function removeHookEntry(settings, event, marker) {
+  const isOurs = isPhaedoHookEntryFor(marker);
+  if (!settings.hooks || !Array.isArray(settings.hooks[event])) return { settings, changed: false };
+  const prior = settings.hooks[event];
+  const others = prior.filter((e) => !isOurs(e));
   if (others.length === prior.length) return { settings, changed: false };
   const hooks = { ...settings.hooks };
-  if (others.length) hooks.SessionStart = others; else delete hooks.SessionStart;
+  if (others.length) hooks[event] = others; else delete hooks[event];
   const next = { ...settings, hooks };
   if (Object.keys(next.hooks).length === 0) delete next.hooks;
   return { settings: next, changed: true };
 }
 
+// Back-compat wrappers (SessionStart injection hook).
+export function mergeSessionStartHook(settings, command) {
+  return mergeHookEntry(settings, 'SessionStart', command, HOOK_MARKER);
+}
+export function removeSessionStartHook(settings) {
+  return removeHookEntry(settings, 'SessionStart', HOOK_MARKER);
+}
+
 // action: 'install' | 'uninstall'. Returns a result record. settings.json is a
 // small, safe-to-create file (unlike the CLI-owned ~/.claude.json).
 export function applyCodeHook({ action, dryRun = false, home = homedir() } = {}) {
@@ -186,15 +234,63 @@ export function applyCodeHook({ action, dryRun = false, home = homedir() } = {})
   }
   if (action === 'uninstall') {
     if (!read.existed) return { name, status: 'absent', detail: 'no settings.json' };
-    const { settings, changed } = removeSessionStartHook(read.config);
-    if (!changed) return { name, status: 'absent', detail: 'no phaedo hook to remove' };
-    if (!dryRun) { backup(path); writeConfig(path, settings); }
+    const start = removeSessionStartHook(read.config);
+    const both = removeHookEntry(start.settings, 'SessionEnd', CAPTURE_HOOK_MARKER);
+    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 };
   }
-  const { settings, changed } = mergeSessionStartHook(read.config, hookCommand());
-  if (!changed) return { name, status: 'unchanged', detail: 'already configured' };
+  // 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
+  // closure). captureHookAvailable() gates the wiring so a broken layout (e.g. a
+  // hand-copied hooks/ dir with neither home) degrades to injection-only instead of
+  // failing every session end with ERR_MODULE_NOT_FOUND.
+  const start = mergeSessionStartHook(read.config, hookCommand());
+  let settings = start.settings;
+  let captureChanged = false;
+  let captureNote = '';
+  if (captureHookAvailable()) {
+    const both = mergeHookEntry(settings, 'SessionEnd', hookCommand({ hookPath: CAPTURE_HOOK_PATH }), CAPTURE_HOOK_MARKER);
+    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);
+    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)';
+  }
+  // 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 };
+  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 —
+// the repo root (dev clone) or mcp/vendor/ (published tarball), mirroring
+// lib/capture-home.js's resolution exactly.
+export function captureHookAvailable(hookPath = CAPTURE_HOOK_PATH) {
+  const hookDir = dirname(hookPath);
+  const homes = [join(hookDir, '..', '..'), join(hookDir, '..', 'vendor')];
+  return homes.some((h) => existsSync(join(h, 'capture', 'transcript.js')) &&
+                           existsSync(join(h, 'extraction', 'delta-lift.js')));
 }
 
 function backup(path) {
@@ -240,18 +336,88 @@ export function applyToClient(client, { action, entry, dryRun = false } = {}) {
   return { ...client, status: dryRun ? 'would-write' : 'configured', detail: configPath };
 }
 
+// Default on-disk locations for everything the server persists. The state dir
+// (cache.key + cache.enc + receipts.enc) mirrors mcp/cache.js; the pairing/identity
+// records sit next to the server.
+const STATE_DIR = process.env.PHAEDO_MCP_STATE_DIR || join(homedir(), '.phaedo-mcp');
+
+// Delete all local Phaedo state the server wrote — the "leave nothing behind" half
+// of uninstall. Client-config removal only unwires the server; without this the
+// derived key material (cache.key), the ciphertext at-rest cache (cache.enc), the
+// §10.6 receipts audit store (receipts.enc), and the pairing/identity records all
+// persist on disk after "uninstall". Parameterized (stateDir/baseDir) so it's
+// node-testable against temp dirs, not the real home.
+export function purgeLocalData({ stateDir = STATE_DIR, baseDir = BASE_DIR, dryRun = false } = {}) {
+  const targets = [
+    stateDir,                          // cache.key + cache.enc + receipts.enc
+    join(baseDir, 'pairing.json'),
+    join(baseDir, 'identity.json'),
+  ];
+  const removed = [];
+  for (const t of targets) {
+    if (!existsSync(t)) continue;
+    if (!dryRun) {
+      try { rmSync(t, { recursive: true, force: true }); }
+      catch (e) { removed.push(`${t} (error: ${e.message})`); continue; }
+    }
+    removed.push(t);
+  }
+  return removed;
+}
+
+// ── Capture-model config (--capture-model) ────────────────────────────────────
+// The durable on-switch for the SessionEnd capture hook's option-(b) model
+// detector: <state dir>/capture-model.json, read by capture/model-detect.js
+// captureModelOpts (env vars still win as a per-session override). A config
+// FILE — not env in the MCP client entries — because the hook is spawned by
+// Claude Code / Cowork, not by the MCP server, and Dock-launched apps never
+// read shell-profile exports. `off` removes the file. Exported for tests.
+export async function applyCaptureModelConfig(model, { url, stateDir = STATE_DIR, dryRun = false, fetchImpl } = {}) {
+  const path = join(stateDir, 'capture-model.json');
+  if (model === 'off') {
+    if (!existsSync(path)) return { status: 'unchanged', detail: 'capture model already off', path };
+    if (!dryRun) rmSync(path);
+    return { status: dryRun ? 'would-remove' : 'removed', detail: `capture model OFF (${path})`, path };
+  }
+  if (!model || typeof model !== 'string') {
+    return { status: 'error', detail: '--capture-model needs a model name (e.g. llama3.1:8b) or "off"', path };
+  }
+  if (!dryRun) {
+    mkdirSync(stateDir, { recursive: true });
+    writeFileSync(path, JSON.stringify({ model, ...(url ? { url } : {}) }, null, 2) + '\n', 'utf8');
+  }
+  // Advisory reachability/presence probe (same endpoint shape as the consult
+  // judge's) — config is written regardless; the hook fails safe to regex-only.
+  let note = '';
+  try {
+    const probeUrl = (url || 'http://localhost:11434').replace(/\/$/, '');
+    const res = await (fetchImpl || globalThis.fetch)(`${probeUrl}/api/tags`, { signal: AbortSignal.timeout(1500) });
+    const names = res.ok ? ((await res.json()).models || []).map((m) => m.name || m.model).filter(Boolean) : [];
+    note = names.some((n) => n === model || n.startsWith(`${model}:`))
+      ? ' (model found in Ollama)'
+      : ` (endpoint reachable but "${model}" not pulled — run: ollama pull ${model})`;
+  } catch {
+    note = ' (endpoint not reachable — hook stays regex-only until it is)';
+  }
+  return { status: dryRun ? 'would-write' : 'configured', detail: `capture model → ${model}${url ? ` @ ${url}` : ''}${note}`, path };
+}
+
 function parseArgs(argv) {
-  const opts = { pair: false, uninstall: false, dryRun: false, only: null, codeHook: false, help: false };
+  const opts = { pair: false, uninstall: false, purge: false, dryRun: false, only: null, codeHook: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--pair') opts.pair = true;
     else if (a === '--uninstall') opts.uninstall = true;
+    else if (a === '--purge') opts.purge = true;
     else if (a === '--dry-run') opts.dryRun = true;
     else if (a === '--only') opts.only = argv[++i];
     else if (a === '--code-hook') opts.codeHook = true;
     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;
     else throw new Error(`unknown option: ${a}`);
   }
@@ -264,14 +430,23 @@ const HELP = `Phaedo MCP installer
   node install.mjs --pair          configure, then run the one-time pairing
   node install.mjs --code-hook     also add the Claude Code SessionStart hook
                                    (true auto-injection; ~/.claude/settings.json)
+  node install.mjs --capture-model <name|off>   turn the capture hook's local
+                                   model detector on (e.g. llama3.1:8b) or off.
+                                   Writes <state dir>/capture-model.json, which
+                                   reaches EVERY launch path (Dock apps never
+                                   read shell-profile exports). --capture-url
+                                   overrides the endpoint (default Ollama).
   node install.mjs --uninstall     remove the phaedo entry (and hook) everywhere
+  node install.mjs --uninstall --purge   ALSO delete all local Phaedo data on disk
+                                   (cache, key, receipts, pairing/identity records)
   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() {
@@ -299,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 });
@@ -317,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)' : ''}`);
@@ -332,6 +507,11 @@ async function main(argv) {
   if (opts.codeHook || action === 'uninstall') {
     results.push(applyCodeHook({ action, dryRun: opts.dryRun }));
   }
+  // Capture-model on-switch (state-dir config file; see applyCaptureModelConfig).
+  if (action === 'install' && opts.captureModel !== undefined) {
+    const r = await applyCaptureModelConfig(opts.captureModel, { url: opts.captureUrl, dryRun: opts.dryRun });
+    results.push({ name: 'capture-model', ...r });
+  }
   const touched = [];
   for (const r of results) {
     const mark = { configured: '✓', removed: '✓', 'would-write': '·', 'would-remove': '·',
@@ -340,6 +520,16 @@ async function main(argv) {
     if (r.status === 'configured' || r.status === 'would-write') touched.push(r);
   }
 
+  if (opts.purge) {
+    const removed = purgeLocalData({ dryRun: opts.dryRun });
+    console.log(`\n${opts.dryRun ? 'Would delete' : 'Deleted'} local Phaedo data:`);
+    if (removed.length) for (const p of removed) console.log(`  ✓ ${p}`);
+    else console.log('  (nothing on disk to delete)');
+  } else if (action === 'uninstall') {
+    console.log(`\nLocal key material, cache, and receipts remain on disk (${STATE_DIR}, plus pairing.json/identity.json).`);
+    console.log('Run `node install.mjs --uninstall --purge` to delete those too.');
+  }
+
   if (action === 'install') {
     if (!touched.length) {
       console.log('\nNo clients were updated. Are Claude Desktop / Cursor / Claude Code installed?');
@@ -347,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/lib/capture-home.js

@@ -0,0 +1,46 @@
+// Where the capture stack lives — repo root (dev) or mcp/vendor/ (published).
+//
+// The SessionEnd hook and the mcp-local tier-3 fold import capture/* and a
+// slice of extraction/* . In the dev clone those live at the repo root (the
+// single source of truth, shared with the extension and parity-tested); in the
+// published npm tarball build-package.mjs vendors them under mcp/vendor/.
+//
+// Unlike lib/phaedo-crypto.js (which prefers the vendored copies), this
+// resolver PREFERS THE REPO ROOT when it exists: the hook runs headless on
+// every session end, and a stale vendor/ left behind by an earlier `npm test`
+// build on a dev clone would silently shadow freshly-pulled, parity-tested
+// sources. A published install has no repo root two levels up, so it always
+// lands on vendor/ there; the vendored copies are exercised by
+// test-vendored-capture.mjs (a rootless layout), so they can't rot unnoticed.
+
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url)); // mcp/lib
+const ROOT = resolve(HERE, '..', '..');               // repo root — dev
+const VENDOR = resolve(HERE, '..', 'vendor');         // mcp/vendor — bundled (npm package)
+
+// Absolute path for a capture-stack module, e.g. 'capture/state.js' or
+// 'extraction/delta-lift.js' — or null when it exists in neither home.
+export function captureModulePath(subpath) {
+  const dev = resolve(ROOT, subpath);
+  if (existsSync(dev)) return dev;
+  const vendored = resolve(VENDOR, subpath);
+  return existsSync(vendored) ? vendored : null;
+}
+
+// True when the whole capture stack is loadable from this install location
+// (the install.mjs gate for wiring the SessionEnd hook).
+export function captureStackAvailable() {
+  return !!(captureModulePath('capture/transcript.js') && captureModulePath('extraction/delta-lift.js'));
+}
+
+// Dynamic-import a capture-stack module from whichever home resolves. Throws
+// ERR_MODULE_NOT_FOUND-equivalent when neither does (callers that must degrade
+// gracefully — capture-local.js — catch it).
+export function loadCaptureModule(subpath) {
+  const path = captureModulePath(subpath);
+  if (!path) throw new Error(`capture module not found in repo root or vendor/: ${subpath}`);
+  return import(pathToFileURL(path).href);
+}

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'));