phaedo-mcp 0.2.2 → 0.3.0

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/session-end.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+// Phaedo — Claude Code SessionEnd capture hook (Track A, option (a)).
+//
+// Claude Code runs this when a session ends, passing hook input on stdin
+// ({ session_id, transcript_path, ... }). The hook:
+//   1. reads the session transcript JSONL (local file, never leaves the machine),
+//   2. parses it to an exchange_batch (capture/transcript.js),
+//   3. runs the deterministic Path-A detectors over the user messages
+//      (capture/detectors.js — the parity-tested mirror of the extension's tables),
+//      optionally enriched by a LOCAL model classifying the regex-miss messages
+//      against the same taxonomy (capture/model-detect.js, option (b) — opt-in
+//      via PHAEDO_CAPTURE_MODEL, e.g. `llama3.1:8b` on Ollama; fail-safe),
+//   4. folds this session's counts into the durable per-surface state, REPLACING
+//      any prior contribution from the same session (capture/state.js — resume-safe),
+//   5. lifts the CUMULATIVE counters into source='delta' §5.1 signals
+//      (extraction/delta-lift.js — idempotent snapshot semantics), and
+//   6. deposits the signal delta to the relay's capture_to_owner lane
+//      (mcp/capture-sync.js — ciphertext under fp_sync_key, best-effort).
+//
+// The raw transcript is read, counted, and DISCARDED — nothing derived from it
+// but signal names + integers is ever persisted or transmitted (the discard-raw
+// contract). Wire it up with `npm run setup:code-hook` (installs SessionStart
+// injection + this SessionEnd capture together), or by hand in
+// ~/.claude/settings.json:
+//   { "hooks": { "SessionEnd": [ { "hooks": [
+//       { "type": "command", "command": "<node> <abs path to this file>" }
+//   ] } ] } }
+//
+// FAIL-SAFE: any error (no transcript, unpaired, relay down, corrupt state)
+// exits 0 with NO output — capture must never break or slow a session's end.
+// Unpaired machines still accumulate local state; deposits begin once paired.
+//
+// Packaging note: the capture/extraction modules load via lib/capture-home.js —
+// repo root in the dev clone, mcp/vendor/ in the published npm tarball
+// (build-package.mjs vendors the whole closure; test-vendored-capture.mjs proves
+// the rootless layout works).
+
+import { readFileSync, existsSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { loadCaptureModule } from '../lib/capture-home.js';
+import { isMainModule } from '../lib/is-main.js';
+import { loadPairingRecord } from '../phone-source.js';
+import { buildCaptureDelta, depositCaptureDelta } from '../capture-sync.js';
+
+// The capture stack loads through lib/capture-home.js so this hook runs BOTH
+// from the dev clone (repo-root sources) and from the published npm tarball
+// (build-package.mjs vendors them under mcp/vendor/). Top-level await: the
+// install gate (install.mjs captureHookAvailable) guarantees these resolve
+// wherever the hook is actually wired.
+const [
+  { transcriptToBatch },
+  { accumulateBatchCounts },
+  { captureModelOpts, enrichCountsWithModel },
+  { deriveSourceDeviceId },
+  { defaultStatePath, loadState, saveState, applySession, cumulativeCounts },
+  { liftDeltaSignals },
+] = await Promise.all([
+  'capture/transcript.js',
+  'capture/detectors.js',
+  'capture/model-detect.js',
+  'capture/source-id.js',
+  'capture/state.js',
+  'extraction/delta-lift.js',
+].map(loadCaptureModule));
+
+const MCP_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const SURFACE = 'claude-code';
+// Option (b): with a local capture model configured — env var OR the
+// capture-model.json the installer writes — allow headroom for one
+// classification call (its own 15s timeout) on top of the deterministic pass.
+// Without one, the original tight budget stands.
+const BUDGET_MS = captureModelOpts(process.env).model ? 30000 : 10000;
+// Cap the transcript bytes we read+parse. The budget is a setTimeout race, which a
+// setTimeout CANNOT preempt while the synchronous read/parse runs — so a huge transcript
+// (long agentic sessions accumulate tool_result blobs) would block session-end past
+// BUDGET_MS regardless. Recent behavior lives at the END of an append-only log, so on an
+// oversized file we read only the last MAX_READ_BYTES and start parsing at the first
+// whole line. 24 MB ≈ well under 100ms to parse — comfortably inside the budget.
+const MAX_READ_BYTES = 24 * 1024 * 1024;
+
+// Read the whole file, or just its tail when it exceeds MAX_READ_BYTES (dropping the
+// leading partial line). Returns '' on any IO error (caller treats as unreadable).
+function readTranscriptCapped(path) {
+  let size;
+  try { size = statSync(path).size; } catch { return readFileSync(path, 'utf8'); }
+  if (size <= MAX_READ_BYTES) return readFileSync(path, 'utf8');
+  const fd = openSync(path, 'r');
+  try {
+    const buf = Buffer.allocUnsafe(MAX_READ_BYTES);
+    readSync(fd, buf, 0, MAX_READ_BYTES, size - MAX_READ_BYTES);
+    const text = buf.toString('utf8');
+    const nl = text.indexOf('\n');
+    return nl >= 0 ? text.slice(nl + 1) : text;   // drop the partial first line
+  } finally { closeSync(fd); }
+}
+
+// ── Capture pairing (whose key encrypts the deposit) ─────────────────────────
+// The capture_to_owner envelope must be decryptable by the DRAINING owner. The
+// PHONE is the tier-1 owner and its drain is BUILT (fpSync.drainCapture): it
+// holds every client's pair_key and tries each until one decrypts, so the plain
+// <mcp>/pairing.json — whatever pairing this machine rides — is the right
+// default. The pairing.capture.json export (the extension's phaedo_local_pairing,
+// copied by hand so the EXTENSION could decrypt) is RETIRED as a requirement:
+// it remains a supported override for a phone app that predates the drain, or
+// to pin the key explicitly. Resolution order:
+//   1. PHAEDO_CAPTURE_PAIRING (explicit path)
+//   2. <mcp>/pairing.capture.json — legacy/override (gitignored); delete it once
+//      the phone build with drainCapture is installed
+//   3. <mcp>/pairing.json — the default
+// Needs pair_key + relay_device_id (+ relay_device_secret for relay auth).
+export class CapturePairingError extends Error {}
+
+// Returns a valid capture pairing record, or null when NO capture pairing is
+// configured (caller may fall back to mcp/pairing.json). THROWS CapturePairingError
+// when a capture-pairing file is PRESENT but broken (unparseable, or missing
+// pair_key/relay_device_id): silently falling back to a DIFFERENT pairing would
+// encrypt every deposit under the wrong key to the wrong relay slot — the exact
+// live-test failure the override exists to prevent, reinstated by a typo. The caller
+// must skip the deposit instead. A record lacking relay_device_secret is returned but
+// warned about (its deposits will 401 until the user re-pairs).
+export function loadCapturePairing(mcpDir, env = process.env, warn = (m) => process.stderr.write(`[phaedo capture] ${m}\n`)) {
+  const candidates = [
+    { path: env.PHAEDO_CAPTURE_PAIRING && resolve(process.cwd(), env.PHAEDO_CAPTURE_PAIRING), explicit: true },
+    { path: resolve(mcpDir, 'pairing.capture.json'), explicit: false },
+  ].filter((c) => c.path);
+  for (const { path, explicit } of candidates) {
+    if (!existsSync(path)) {
+      if (explicit) throw new CapturePairingError(`PHAEDO_CAPTURE_PAIRING points at a missing file: ${path} — not depositing (would use the wrong key).`);
+      continue;
+    }
+    let rec;
+    try { rec = JSON.parse(readFileSync(path, 'utf8')); }
+    catch (e) { throw new CapturePairingError(`capture pairing ${path} is not valid JSON (${e.message}) — not depositing (would use the wrong key). Re-export the extension's pairing.`); }
+    if (!rec || !rec.pair_key || !rec.relay_device_id) {
+      throw new CapturePairingError(`capture pairing ${path} is missing pair_key/relay_device_id — not depositing (would use the wrong key). Re-export the extension's pairing.`);
+    }
+    if (!rec.relay_device_secret) warn(`capture pairing ${path} has no relay_device_secret — deposits will 401 until you re-pair the extension.`);
+    return rec;
+  }
+  return null;
+}
+
+// The full capture pass, dependency-injectable for tests.
+//   input — the hook's stdin JSON ({ session_id, transcript_path, ... }).
+//   deps  — { readFile, statePath, pairing, fetch, relayBase, now, mcpDir }.
+// Returns a result record (never throws).
+export async function runCaptureHook(input, deps = {}) {
+  const read = deps.readFile || readTranscriptCapped;
+  const statePath = deps.statePath || defaultStatePath();
+  const nowIso = deps.now || new Date().toISOString();
+
+  const transcriptPath = input && input.transcript_path;
+  if (!transcriptPath) return { deposited: false, reason: 'no-transcript-path' };
+  let text;
+  try { text = read(transcriptPath); } catch { return { deposited: false, reason: 'transcript-unreadable' }; }
+
+  const batch = transcriptToBatch(text, { sessionId: input.session_id });
+  if (!batch.exchanges.length) return { deposited: false, reason: 'no-exchanges' };
+  let counts = accumulateBatchCounts(batch);
+
+  // Option (b) — model-backed detector enrichment (capture/model-detect.js):
+  // classify the regex-MISS messages against the same correction taxonomy and
+  // fold the hits into this session's counts BEFORE the per-session-replace
+  // state apply, so re-fires stay resume-safe and the deposit stays pure delta.
+  // Opt-in (PHAEDO_CAPTURE_MODEL env, or the installer-written
+  // capture-model.json); any failure leaves the regex counts intact.
+  let modelAdded = 0;
+  const modelOpts = deps.captureModel !== undefined ? deps.captureModel : captureModelOpts(deps.env);
+  if (modelOpts && modelOpts.model) {
+    const enriched = await enrichCountsWithModel(batch, counts, modelOpts);
+    counts = enriched.counts;
+    modelAdded = enriched.added;
+  }
+
+  // Pairing is optional: without one we still accumulate state locally (the
+  // mcp-local owner tier can read it); the deposit just no-ops as 'unpaired'.
+  // A capture-specific pairing (the extension's, exported) wins over the MCP's
+  // own pairing.json so the draining owner can actually decrypt the deposit.
+  let pairing = deps.pairing;
+  if (pairing === undefined) {
+    try {
+      pairing = loadCapturePairing(deps.mcpDir || MCP_DIR, deps.env);
+    } catch (e) {
+      // A capture-pairing file exists but is broken: do NOT fall back to a different
+      // key (that silently deposits to the wrong slot). Accumulate state, skip deposit.
+      if (!(e instanceof CapturePairingError)) throw e;
+      process.stderr.write(`[phaedo capture] ${e.message}\n`);
+      const sourceId0 = deriveSourceDeviceId(null, SURFACE);
+      const st = applySession(loadState(statePath), sourceId0, batch.session_local_id || input.session_id, counts, { now: nowIso });
+      try { saveState(statePath, st); } catch { /* non-fatal */ }
+      return { deposited: false, reason: 'capture-pairing-invalid', counted: counts.message_count };
+    }
+    if (!pairing) {
+      try { pairing = await loadPairingRecord(deps.mcpDir || MCP_DIR); } catch { pairing = null; }
+    }
+  }
+  const sourceId = deriveSourceDeviceId(pairing, SURFACE);
+
+  const state = applySession(loadState(statePath), sourceId, batch.session_local_id || input.session_id, counts, { now: nowIso });
+  try { saveState(statePath, state); } catch { /* state loss just restarts counters — never fatal */ }
+
+  const signals = liftDeltaSignals(cumulativeCounts(state, sourceId).behavioral_signals, nowIso);
+  if (!signals.length) return { deposited: false, reason: 'no-signal', counted: counts.message_count };
+
+  const delta = buildCaptureDelta(signals, { sourceSurface: SURFACE, sourceDeviceId: sourceId, capturedAt: nowIso });
+  // capture-sync's `now` dep is a FUNCTION (envelope created_at); ours is an ISO string.
+  const res = await depositCaptureDelta(pairing, delta, { ...deps, now: () => nowIso });
+  // Surface a deposit that FAILED for a fixable reason (a 401 = the pairing lost its
+  // relay_device_secret; re-pair). 'unpaired'/'no-relay-device-id' are expected
+  // local-only states, not worth a warning. Goes to stderr — Claude Code parses only
+  // stdout, so this never disturbs the session, but it appears in the hook's error log.
+  if (res && res.deposited === false && (res.status === 401 || (res.reason && /^http-/.test(String(res.reason))))) {
+    process.stderr.write(`[phaedo capture] deposit rejected (${res.status || res.reason}) — re-pair the extension so capture can sync.\n`);
+  }
+  return { ...res, counted: counts.message_count, signals: signals.length, ...(modelAdded ? { model_added: modelAdded } : {}) };
+}
+
+// ── script entry (Claude Code invokes this file directly) ────────────────────
+// Symlink-safe (lib/is-main.js): the naive URL comparison silently returns false
+// whenever the hook is reached through a link, turning this hook into a no-op that
+// exits 0 and loses the session.
+const isMain = isMainModule(import.meta.url);
+if (isMain) {
+  const readStdin = () => new Promise((res) => {
+    let data = '';
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => res(data));
+    process.stdin.on('error', () => res(''));
+  });
+  const run = async () => {
+    let input = {};
+    try { input = JSON.parse(await readStdin()); } catch { /* no/bad input → no-op */ }
+    await runCaptureHook(input);
+  };
+  const timeout = new Promise((res) => setTimeout(res, BUDGET_MS));
+  Promise.race([run().catch(() => {}), timeout])
+    .then(() => process.exit(0))
+    .catch(() => process.exit(0)); // a hook must never break the session
+}

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,10 @@ 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
 
 // ── Client registry ──────────────────────────────────────────────────────────
 // Every supported client stores MCP servers as a top-level `mcpServers` object,
@@ -147,32 +149,50 @@ 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.
+export function mergeHookEntry(settings, event, command, marker) {
+  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 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.SessionStart = [...others, { hooks: [{ type: 'command', command }] }];
+  next.hooks[event] = [...others, { hooks: [{ type: 'command', command }] }];
   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 +206,46 @@ 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);
+    if (!start.changed && !both.changed) return { name, status: 'absent', detail: 'no phaedo hook to remove' };
+    if (!dryRun) { backup(path); writeConfig(path, both.settings); }
     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 CAPTURE hook
+  // 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);
+    settings = both.settings; captureChanged = both.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;
+    captureNote = ' (capture hook skipped — not available in this install; injection only)';
+  }
+  const changed = start.changed || captureChanged;
+  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 };
+}
+
+// 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 +291,87 @@ 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 === '--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,7 +384,15 @@ 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
 
@@ -332,6 +460,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 +473,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?');

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);
+}