phaedo-mcp 0.3.7 → 0.3.13

package/README.md

@@ -123,6 +123,51 @@ will then tell you there's no profile until you pair your phone.
 You can disconnect this computer at any time from the **Agents** screen on your
 phone.
 
+### Learn from your ChatGPT or Claude history
+
+```bash
+npm run import -- ~/Downloads/your-export.zip
+```
+
+Get the file from ChatGPT (Settings → Data controls → Export data) or Claude (Settings → Privacy →
+Export data); each emails a zip. Phaedo reads the last year of conversations (`--all` for
+everything, `--dry-run` to count first) through the same on-device detectors as Claude Code
+capture, keeps only the counts, and discards the text — delete the export afterwards. Importing
+the same file again replaces, never doubles. Paired: the patterns go to your phone. Not paired:
+they become your starter profile. In the Claude Code plugin, it's `/phaedo:import`.
+
+### See what Phaedo learned — keep it or remove it
+
+```bash
+npm run learned
+```
+
+Lists what Phaedo inferred from how you work (not your interview answers or your rules), one
+plain sentence each, and flags pairs that disagree ("favor speed" vs "favor quality").
+`npm run learned -- --remove 3,5` stops those shaping answers and decisions on this computer —
+the list is applied every time the profile loads, so a pattern your sessions keep showing stays
+removed. `--keep all` marks the rest reviewed; `--forgotten` and `--restore <n>` undo.
+`/phaedo:status` says when there are new things to look at. To remove something from the phone's
+profile itself, use the Phaedo app. In the Claude Code plugin, it's `/phaedo:learned`.
+
+### Give agents without MCP the same profile
+
+Codex, Copilot CLI, Gemini CLI and Antigravity each read a personal instructions file at the
+start of every session. One command writes a short version of your profile (your rules and how
+you like answers) into each one found on this computer:
+
+```bash
+npm run rules
+```
+
+It goes into `~/.codex/AGENTS.md`, `~/.copilot/copilot-instructions.md` and
+`~/.gemini/GEMINI.md` (shared by Gemini CLI and Antigravity), inside a marked block; the rest
+of each file is left alone. Cursor has no personal file, so name a project:
+`npm run rules -- --project ~/code/app` writes `.cursor/rules/phaedo.mdc` and keeps it out of
+git. Phaedo refreshes these files whenever a Claude Code session starts with Phaedo on, and
+only those you set up. `npm run rules -- --dry-run` shows the text first;
+`npm run rules -- --remove` takes it out. In the Claude Code plugin, it's `/phaedo:rules`.
+
 ---
 
 ## Reference
@@ -356,22 +401,41 @@ detectors, and a model call can never break or stall a session (30s budget, hook
 exits 0). Prefer the `setup:capture-model` config file over an env var — the file reaches
 Dock-launched Claude Desktop, a shell `export` does not.
 
-### Consult before shipping, from Claude Code (`hooks/pre-ship.mjs`)
-
-`npm run setup:code-hook` also installs a **ship hook** on Bash (PreToolUse,
-PermissionRequest, PostToolUse, PostToolUseFailure). Before an agent merges a PR
-(`gh pr merge`), deploys (`fly deploy`), builds or submits a phone app (`eas build` /
-`eas submit`) or pushes straight to `main`, the hook runs a full `phaedo_consult` on it
-(`ship-actions.js` names these; every other command is ignored in ~50 ms) and writes a
-§10.6 receipt, `agent_id: claude-code/ship-hook`.
+### Your personal reviewer in Claude Code (`hooks/pre-ship.mjs`)
+
+`npm run setup:code-hook` (or the Claude plugin) installs this hook on PreToolUse,
+PermissionRequest, PostToolUse and PostToolUseFailure, for shell commands and for
+connected-app (MCP) tool calls. Before an agent does something people disagree about, the
+hook runs a full `phaedo_consult` on it and writes a §10.6 receipt, `agent_id:
+claude-code/ship-hook`. `ship-actions.js` names what counts:
+
+- **Shell:** merge a PR (`gh pr merge`), deploy (`fly deploy`, `vercel --prod`, `netlify deploy
+  --prod`, `firebase deploy`, `terraform apply|destroy`, `kubectl apply|delete`), build or
+  submit a phone app (`eas build` / `eas submit`), push straight to `main`, force-push any
+  branch, delete a remote branch, open a PR, comment on or review a PR or issue, publish a
+  package (`npm`/`pnpm`/`yarn`/`bun publish`, `cargo publish`, `twine upload`, `gem push`;
+  never `--dry-run`), create a GitHub release.
+- **Connected apps:** any tool whose name says it sends, replies, forwards, posts, publishes,
+  comments, shares or invites; pays, purchases, transfers or checks out; deletes, purges,
+  destroys or trashes; or merges — through any MCP server except Phaedo's own. The receipt
+  records who or what the call targets (recipient, channel, subject, amount), never a message
+  body.
+
+Every other command or tool is ignored in about 50 ms.
+
+**Why it matters in auto mode.** Auto mode's reviewer judges an action by its type and lets
+routine ones through. Phaedo asks the other question — would *this* person want to see this
+one? — and when the answer is yes it returns `ask`, which forces a real prompt even in auto
+mode, with the reason in your terms: "it can't be undone", "it spends $250", or "your rule:
+ask me before posting in #eng". When the answer is no, it stays quiet.
 
 - **It only ever adds friction.** It never returns `allow`. A permissive answer leaves
   Claude Code's own permission flow untouched; `escalate` / `clarify` / `decline` returns
   `ask`, so the action comes to you with one plain line saying why.
 - **Outcomes are yours, never inferred.** The hook records `approved` only when it has
-  evidence you were asked: Claude Code fired PermissionRequest for that command, and the
-  command then ran. That holds in every mode except auto / dontAsk, where no person
-  answers. Decline and the agent records `rejected` (Claude Code fires no hook for a
+  evidence you were asked: Claude Code fired PermissionRequest for that call, and the
+  call then ran. In auto mode that counts only when Phaedo itself asked (the prompt it forced
+  is yours; any other is the classifier's); in dontAsk, never. Decline and the agent records `rejected` (Claude Code fires no hook for a
   decline). No prompt shown, nothing recorded; the agent is told so, and records your
   reaction only if you give one.
 - **What a merge changes.** Before `gh pr merge` the hook reads the PR from GitHub (read-only):
@@ -385,6 +449,27 @@ PermissionRequest, PostToolUse, PostToolUseFailure). Before an agent merges a PR
 - **Fail-safe:** any error, timeout (12 s) or unusable profile → no output, the command
   runs as if the hook weren't there.
 
+### The same check in Cursor, Copilot CLI, Codex and Gemini CLI (`hooks/agent-hook.mjs`)
+
+```bash
+cd ~/phaedo/mcp && npm run setup:agent-hooks
+```
+
+This adds Phaedo's check to each of these agents found on this computer, beside any hooks you
+already have: `~/.cursor/hooks.json`, `~/.copilot/hooks/phaedo.json`, `~/.codex/hooks.json`
+and `~/.gemini/settings.json`. The same actions are reviewed, with the same consult and the
+same decision records (each names the agent that asked).
+
+- **Cursor and Copilot CLI** can show a confirmation prompt, so you get one, with the reason.
+- **Codex and Gemini CLI** can't prompt from a hook, so Phaedo pauses the action once with the
+  reason; the agent asks you in the chat, and the same command run again within 15 minutes goes
+  through. It never blocks twice in a row and never says yes on your behalf.
+- **Codex** skips new hooks until you trust them: run `/hooks` in Codex once and trust Phaedo's.
+- **Antigravity** has no hooks, so it gets your profile (`npm run rules`) but not this check.
+- Outcomes aren't recorded automatically in these agents yet; `npm run ship-readout` shows
+  what they asked.
+- `npm run unsetup` (uninstall) takes them all out.
+
 ## Consult at decision points (`phaedo_consult`, §10)
 
 Beyond injecting style, an agent can **ask the fingerprint how the user's pattern

package/agent-hooks.js

@@ -0,0 +1,160 @@
+// Phaedo — wire the merge check (hooks/agent-hook.mjs) into Cursor, Copilot CLI, Codex and
+// Gemini CLI. Each keeps its hooks in its own user-level file; Phaedo's entry is recognised by
+// the script path, merged in beside whatever is there, and removed on uninstall.
+//
+//   Cursor   ~/.cursor/hooks.json            beforeShellExecution + beforeMCPExecution
+//   Copilot  ~/.copilot/hooks/phaedo.json    preToolUse  (a file of Phaedo's own)
+//   Codex    ~/.codex/hooks.json             PreToolUse  (new hooks need trusting in /hooks)
+//   Gemini   ~/.gemini/settings.json         hooks.BeforeTool
+//
+// Antigravity documents no hooks, so it gets the profile (rules-files.js) but no merge check.
+// The merge functions are PURE (config in, config out); applyAgentHooks does the file I/O.
+
+import { homedir } from 'os';
+import { join, resolve, dirname } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, rmSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { MCP_HOOK_MATCHER } from './ship-actions.js';
+
+export const AGENT_HOOK_PATH = join(dirname(fileURLToPath(import.meta.url)), 'hooks', 'agent-hook.mjs');
+export const MARKER = 'hooks/agent-hook.mjs';
+export const TIMEOUT_S = 15;              // above the hook's own 12 s budget
+const SHIP_MATCHER = `Bash|${MCP_HOOK_MATCHER}`;
+// Gemini names MCP tools mcp_<server>_<tool> (one underscore), so the same verbs, one prefix.
+const GEMINI_MATCHER = `run_shell_command|${MCP_HOOK_MATCHER.replace(/^mcp__/, 'mcp_')}`;
+
+const norm = (s) => String(s ?? '').replace(/\\/g, '/');
+const ours = (cmd) => norm(cmd).includes(MARKER);
+export const agentCommand = (agent, { nodePath = process.execPath, hookPath = AGENT_HOOK_PATH } = {}) => `"${nodePath}" "${hookPath}" ${agent}`;
+
+/** Where each agent keeps its hooks, for this home and environment. */
+export function hookFiles({ home = homedir(), env = process.env } = {}) {
+  const codexHome = env.CODEX_HOME ? resolve(env.CODEX_HOME) : join(home, '.codex');
+  const copilotHome = env.COPILOT_HOME ? resolve(env.COPILOT_HOME) : join(home, '.copilot');
+  return {
+    cursor:  { label: 'Cursor', dir: join(home, '.cursor'), file: join(home, '.cursor', 'hooks.json') },
+    copilot: { label: 'Copilot CLI', dir: copilotHome, file: join(copilotHome, 'hooks', 'phaedo.json'), ownFile: true },
+    codex:   { label: 'Codex', dir: codexHome, file: join(codexHome, 'hooks.json'), note: 'In Codex, run /hooks once and trust the Phaedo hook — Codex skips new hooks until you do.' },
+    gemini:  { label: 'Gemini CLI', dir: join(home, '.gemini'), file: join(home, '.gemini', 'settings.json') },
+  };
+}
+
+const clone = (o) => JSON.parse(JSON.stringify(o ?? {}));
+const arr = (v) => (Array.isArray(v) ? v : []);
+
+// Cursor and Copilot: { hooks: { event: [ {command…} ] } } — one flat entry per hook.
+function mergeFlat(config, events, entry, cmdOf) {
+  const c = clone(config);
+  c.version ??= 1;
+  c.hooks = c.hooks && typeof c.hooks === 'object' ? c.hooks : {};
+  for (const ev of events) {
+    const rest = arr(c.hooks[ev]).filter((h) => !ours(cmdOf(h)));
+    c.hooks[ev] = [...rest, entry];
+  }
+  return c;
+}
+function removeFlat(config, events, cmdOf) {
+  const c = clone(config);
+  if (!c.hooks || typeof c.hooks !== 'object') return c;
+  for (const ev of events) {
+    if (!Array.isArray(c.hooks[ev])) continue;
+    c.hooks[ev] = c.hooks[ev].filter((h) => !ours(cmdOf(h)));
+    if (!c.hooks[ev].length) delete c.hooks[ev];
+  }
+  return c;
+}
+
+// Codex and Gemini: { hooks: { Event: [ { matcher, hooks: [ {command…} ] } ] } } — Claude-style groups.
+function mergeGrouped(container, event, group) {
+  const c = clone(container);
+  c.hooks = c.hooks && typeof c.hooks === 'object' ? c.hooks : {};
+  const rest = removeGrouped({ hooks: { [event]: arr(c.hooks[event]) } }, event).hooks[event] || [];
+  c.hooks[event] = [...rest, group];
+  return c;
+}
+function removeGrouped(container, event) {
+  const c = clone(container);
+  if (!c.hooks || !Array.isArray(c.hooks[event])) return c;
+  c.hooks[event] = c.hooks[event]
+    .map((g) => ({ ...g, hooks: arr(g?.hooks).filter((h) => !ours(h?.command)) }))
+    .filter((g) => g.hooks.length);
+  if (!c.hooks[event].length) delete c.hooks[event];
+  return c;
+}
+
+const CURSOR_EVENTS = ['beforeShellExecution', 'beforeMCPExecution'];
+
+/** The agent's config with Phaedo's hook in (replacing any older Phaedo entry). PURE. */
+export function mergeAgentHook(agent, config, opts = {}) {
+  const cmd = agentCommand(agent, opts);
+  switch (agent) {
+    case 'cursor':
+      return mergeFlat(config, CURSOR_EVENTS, { command: cmd, timeout: TIMEOUT_S }, (h) => h?.command);
+    case 'copilot':
+      return mergeFlat(config, ['preToolUse'], { type: 'command', bash: cmd, powershell: `& ${cmd}`, timeoutSec: TIMEOUT_S }, (h) => h?.bash ?? h?.command ?? h?.powershell);
+    case 'codex':
+      return mergeGrouped(config, 'PreToolUse', { matcher: SHIP_MATCHER, hooks: [{ type: 'command', command: cmd, timeout: TIMEOUT_S, statusMessage: 'Checking with Phaedo' }] });
+    case 'gemini':
+      return mergeGrouped(config, 'BeforeTool', { matcher: GEMINI_MATCHER, hooks: [{ type: 'command', command: cmd, timeout: TIMEOUT_S * 1000, name: 'phaedo-merge-check' }] });
+    default: throw new Error(`unknown agent: ${agent}`);
+  }
+}
+
+/** The agent's config with every Phaedo hook entry taken out. PURE. */
+export function removeAgentHook(agent, config) {
+  switch (agent) {
+    case 'cursor': return removeFlat(config, CURSOR_EVENTS, (h) => h?.command);
+    case 'copilot': return removeFlat(config, ['preToolUse'], (h) => h?.bash ?? h?.command ?? h?.powershell);
+    case 'codex': return removeGrouped(config, 'PreToolUse');
+    case 'gemini': return removeGrouped(config, 'BeforeTool');
+    default: throw new Error(`unknown agent: ${agent}`);
+  }
+}
+
+function readJson(path) {
+  if (!existsSync(path)) return { config: {}, existed: false };
+  const raw = readFileSync(path, 'utf8');
+  if (!raw.trim()) return { config: {}, existed: true };
+  const config = JSON.parse(raw);   // throws on comments or damage — the caller refuses to touch it
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('not a JSON object');
+  return { config, existed: true };
+}
+
+/**
+ * Install or remove the merge check for every agent found (or `only`). Returns result
+ * records in install.mjs's shape: { name, status, detail }.
+ */
+export function applyAgentHooks({ action, dryRun = false, home = homedir(), env = process.env, only = null, nodePath, hookPath } = {}) {
+  const out = [];
+  for (const [agent, t] of Object.entries(hookFiles({ home, env }))) {
+    if (only && !only.includes(agent)) continue;
+    const name = `${t.label} merge check`;
+    if (action === 'install' && !existsSync(t.dir)) continue;          // not installed here
+    let read;
+    try { read = readJson(t.file); } catch (e) {
+      out.push({ name, status: 'error', detail: `${t.file} isn't plain JSON (${e.message}); not touched` });
+      continue;
+    }
+    if (action === 'uninstall') {
+      if (!read.existed) continue;
+      const next = removeAgentHook(agent, read.config);
+      if (JSON.stringify(next) === JSON.stringify(read.config)) continue;
+      const empty = t.ownFile && !Object.keys(next.hooks || {}).length;
+      if (!dryRun) {
+        if (empty) rmSync(t.file);
+        else { copyFileSync(t.file, `${t.file}.phaedo.bak`); writeFileSync(t.file, JSON.stringify(next, null, 2) + '\n'); }
+      }
+      out.push({ name, status: dryRun ? 'would-remove' : 'removed', detail: t.file });
+      continue;
+    }
+    const next = mergeAgentHook(agent, read.config, { nodePath, hookPath });
+    if (JSON.stringify(next) === JSON.stringify(read.config)) { out.push({ name, status: 'unchanged', detail: 'already configured' }); continue; }
+    if (!dryRun) {
+      if (read.existed) copyFileSync(t.file, `${t.file}.phaedo.bak`);
+      mkdirSync(dirname(t.file), { recursive: true });
+      writeFileSync(t.file, JSON.stringify(next, null, 2) + '\n');
+    }
+    out.push({ name, status: dryRun ? 'would-write' : 'configured', detail: t.file, ...(t.note ? { restartHint: t.note } : {}) });
+  }
+  return out;
+}

package/consult-core.js

@@ -489,16 +489,53 @@ function resolveActionApproval(vd, n, suppressed) {
   } else {
     signal = p.score >= 0.7 ? 'proceed_with_note' : 'proceed';
   }
-  const domain = n.domain ? ` in the ${n.domain} domain` : '';
-  const posture = p.score >= 0.55 ? 'favors caution and human review'
-                : p.score <= 0.4  ? 'favors acting and adjusting'
-                : 'weighs the main risks before committing';
-  const hint = irreversible
-    ? `On irreversible${mag >= 2 ? ', high-magnitude' : ''} actions${domain}, the subject ${posture}.`
-    : `On reversible actions${domain}, the subject ${posture}.`;
+  const hint = actionApprovalHint({ signal, score: p.score, irreversible, mag, thinEvidence, domain: n.domain });
   return { signal, hint, coverage: p.coverage, found: p.found, withheld: p.withheld, signalConfidence: p.signalConfidence };
 }
 
+// The rationale must explain the SIGNAL, not just the subject's general posture. It used to
+// state the posture alone, so a cautious subject's low-stakes, reversible action came back
+// "proceed_with_note — the subject favors caution and human review": an answer and a reason
+// pointing opposite ways, which an agent can't act on and a person can't trust. Now the sentence
+// says how this person leans in this situation, then what that means for this action.
+export function actionApprovalHint({ signal, score, irreversible, mag, thinEvidence, domain }) {
+  const where = domain ? ` in the ${domain} domain` : '';
+  const situation = irreversible
+    ? `On irreversible${mag >= 2 ? ', high-stakes' : ''} actions${where}`
+    : mag >= 2 ? `On high-stakes actions${where}`
+    : domain ? `In the ${domain} domain` : 'In general';   // the ending names the low stakes, once
+  const lean = score >= 0.55 ? 'cautious' : score <= 0.4 ? 'acting' : 'balanced';
+  const posture = lean === 'cautious' ? 'favors caution and human review'
+                : lean === 'acting' ? 'favors acting and adjusting'
+                : 'weighs the main risks before committing';
+  const lowStakes = !irreversible && mag < 2;
+  // Each ending carries its own connector: "but" when the answer goes against the lean.
+  let consequence;
+  switch (signal) {
+    case 'proceed':
+      consequence = lean === 'cautious' ? ', but this one is reversible and low-stakes, so going ahead fits'
+                  : lean === 'balanced' ? ', and this one is reversible and low-stakes, so going ahead fits'
+                  : ', so going ahead fits';
+      break;
+    case 'proceed_with_note':
+      consequence = lean !== 'cautious' ? ', so go ahead and tell them what you did'
+                  : lowStakes ? ', but this one is reversible and low-stakes, so go ahead and tell them what you did'
+                  : ', but the evidence you gave is enough to go ahead; tell them what you did';
+      break;
+    case 'clarify':
+      consequence = thinEvidence ? `, ${lean === 'acting' ? 'but' : 'and'} no evidence was offered, so ask before acting`
+                  : lean === 'acting' ? ', but this one is unclear enough to ask before acting'
+                  : ', so ask before acting';
+      break;
+    case 'escalate':
+      consequence = lean === 'acting' ? ', but the stakes here call for checking with them first' : ', so check with them first';
+      break;
+    default:
+      consequence = '';
+  }
+  return `${situation}, the subject ${posture}${consequence}.`;
+}
+
 function resolveDomainRiskCheck(vd, n, suppressed) {
   const p = profile(vd, RELEVANT_CUES.domain_risk_check, false, n.domain, suppressed);
   const high = p.score >= 0.55;

package/escalation.js

@@ -181,9 +181,37 @@ export function buildEscalationPayload(consultRequest = {}, consultResponse = {}
     },
     signal: clip(consultResponse.signal, 40),
     rationale_hint: clip(consultResponse.rationale_hint, 280),
+    why_asked: whyAsked(consultRequest, consultResponse),
   };
 }
 
+// WHY YOU'RE SEEING THIS — one plain line for the person on the phone, not the agent.
+// `rationale_hint` is written to the agent ("the subject favors caution… so check with them
+// first"); shown to the subject it reads as Phaedo talking about them in the third person, and it
+// never says what TRIGGERED the interruption. Pushary's default prompt rate flip-flopped twice in
+// October because users couldn't tell why they were being asked; a visible reason on every card
+// is the fix. PURE, and built only from what is already in the payload: the agent's descriptor,
+// the signal, and — when a standing rule decided it — that rule's own note. Never vault content.
+export function whyAsked(consultRequest = {}, consultResponse = {}) {
+  const ad = (consultRequest.action_descriptor && typeof consultRequest.action_descriptor === 'object') ? consultRequest.action_descriptor : {};
+  const hint = typeof consultResponse.rationale_hint === 'string' ? consultResponse.rationale_hint : '';
+  const rule = /^Per your standing rule: (.+?)\.?$/.exec(hint.trim());
+  if (rule) return `One of your rules says to check with you: ${rule[1]}.`.slice(0, 200);
+  const reasons = [];
+  if (ad.reversible === false) reasons.push("it can't be undone");
+  if (typeof ad.amount === 'number' && isFinite(ad.amount) && ad.amount > 0) {
+    reasons.push(`it spends $${ad.amount.toLocaleString('en-US', { maximumFractionDigits: 2 })}`);
+  } else if (ad.magnitude === 'high') reasons.push("it's high-stakes");
+  const what = reasons.length ? reasons.join(' and ') : null;
+  const signal = String(consultResponse.signal || '');
+  if (signal === 'clarify') {
+    return what ? `Phaedo asked because ${what}, and it isn't clear enough what you'd want.`
+                : "Phaedo asked because it isn't clear enough what you'd want here.";
+  }
+  return what ? `Phaedo asked because ${what}, and you usually want to see those yourself.`
+              : "Phaedo asked because it wasn't confident you'd want this done without you.";
+}
+
 // Seal the payload under fp_sync_key into the deposit body { request_id, envelope,
 // window_ms }. PURE crypto (no network) so the round-trip is testable in isolation,
 // mirroring delegation-sync.js buildDelegationDeposit.

package/fingerprint-source.js

@@ -19,6 +19,7 @@ import { foldLocalCapture, isLocalCaptureOwner, localCaptureSessionCount } from
 import { Capabilities, AuthoredSource } from './lib/phaedo-crypto.js';
 import { PhaedoError } from './errors.js';
 import { configDir, isDirectoryEdition } from './lib/config-dir.js';
+import { applyForgotten, readLearnedState } from './learned.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
@@ -255,7 +256,16 @@ export function sourceOf(vd) {
   return s || { live: true, cachedAt: null, ageMs: 0 };
 }
 
-export async function loadFingerprint(baseDir) {
+// What the subject removed in `npm run learned` is taken out on EVERY read, so injection,
+// consult and the rules files all stop using it — even when the sessions keep showing it.
+// `unfiltered` is for that review screen alone, which has to list what was removed.
+const forgetting = (vd, { unfiltered = false } = {}) => (unfiltered ? vd : applyForgotten(vd, readLearnedState(defaultStateDir())));
+
+export async function loadFingerprint(baseDir, opts) {
+  return forgetting(await loadFingerprintUnfiltered(baseDir), opts);
+}
+
+async function loadFingerprintUnfiltered(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
   // is an unambiguous "use THIS" — it lets a user force a local file and makes the
@@ -345,10 +355,10 @@ export async function loadFingerprint(baseDir) {
 // there.) Falls through to a live pull ONLY when no cache exists at all (first run on this
 // machine), which seeds it; run one phaedo_consult after pairing to seed without an
 // escalation in flight.
-export async function loadFingerprintPreferCache(baseDir) {
+export async function loadFingerprintPreferCache(baseDir, opts) {
   if (!process.env.PHAEDO_FINGERPRINT && hasPairingRecord(baseDir)) {
     const cached = await readCache(defaultStateDir());
-    if (cached) return stamp(foldConfigHome(normalizeIdentity(cached.vault)), cached);
+    if (cached) return forgetting(stamp(foldConfigHome(normalizeIdentity(cached.vault)), cached), opts);
   }
-  return loadFingerprint(baseDir);
+  return loadFingerprint(baseDir, opts);
 }

package/history-import.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+// Phaedo — learn from your ChatGPT or Claude history, from the export file each one gives you.
+//
+//   npm run import -- ~/Downloads/chatgpt-export.zip
+//   npm run import -- ~/Downloads/claude-export.zip --all     # every conversation, not just the last year
+//   npm run import -- conversations.json --dry-run            # count what it would read, change nothing
+//
+// Get the file: ChatGPT → Settings → Data controls → Export data; Claude → Settings → Privacy →
+// Export data. Each emails a zip; its conversations.json is all this reads.
+//
+// Each conversation becomes {role, text} turns and goes through the SAME spine the Claude Code
+// hook and the Mac reader use (capture/exchanges.js → capture-core.js: the deterministic
+// detectors → per-session state → delta lift), as its own session keyed by the conversation's id,
+// so importing the same export twice replaces rather than doubles. One deposit to the phone at
+// the end when paired; a starter profile on this computer when not.
+//
+// DISCARD-RAW, as everywhere in capture: the text is read in memory, counted, and dropped.
+// Nothing derived from it but signal names and integers is kept or sent. Not in the directory
+// edition (its policy forbids reading chat history).
+
+import { execFileSync } from 'child_process';
+import { readFileSync, existsSync } from 'fs';
+import { resolve, dirname, extname } from 'path';
+import { fileURLToPath } from 'url';
+import { isMainModule } from './lib/is-main.js';
+
+export const DEFAULT_DAYS = 365;
+export const SURFACES = Object.freeze({ chatgpt: 'chatgpt-import', claude: 'claude-import' });
+const DAY = 24 * 60 * 60 * 1000;
+
+const text = (v) => (typeof v === 'string' ? v : '');
+const iso = (t) => {
+  if (typeof t === 'number' && Number.isFinite(t)) return new Date(t < 1e12 ? t * 1000 : t).toISOString();
+  const p = Date.parse(t);
+  return Number.isFinite(p) ? new Date(p).toISOString() : null;
+};
+
+/** Which service an export came from, by shape. PURE. */
+export function detectFormat(list) {
+  const first = Array.isArray(list) ? list.find((c) => c && typeof c === 'object') : null;
+  if (!first) return null;
+  if (first.mapping && typeof first.mapping === 'object') return 'chatgpt';
+  if (Array.isArray(first.chat_messages)) return 'claude';
+  return null;
+}
+
+// ChatGPT stores each conversation as a tree (every regenerate or edit is a branch). The
+// conversation the person actually had is the path from `current_node` up to the root.
+function chatgptTurns(c) {
+  const map = c.mapping || {};
+  let id = c.current_node && map[c.current_node] ? c.current_node : null;
+  if (!id) {   // no current_node: the deepest leaf of the first branch
+    id = Object.keys(map).find((k) => !map[k]?.parent) || null;
+    while (id && Array.isArray(map[id]?.children) && map[id].children.length) id = map[id].children[0];
+  }
+  const path = [];
+  const seen = new Set();
+  while (id && map[id] && !seen.has(id)) { seen.add(id); path.push(map[id]); id = map[id].parent; }
+  path.reverse();
+  const turns = [];
+  for (const node of path) {
+    const m = node.message;
+    const role = m?.author?.role;
+    if (role !== 'user' && role !== 'assistant') continue;
+    const ct = m.content?.content_type;
+    if (ct && ct !== 'text' && ct !== 'multimodal_text') continue;   // code runs, browsing, tool output
+    const body = (Array.isArray(m.content?.parts) ? m.content.parts : []).map(text).join('\n').trim();
+    if (body) turns.push({ role, text: body, id: m.id || node.id, timestamp: iso(m.create_time) });
+  }
+  return turns;
+}
+
+function claudeTurns(c) {
+  const turns = [];
+  for (const m of Array.isArray(c.chat_messages) ? c.chat_messages : []) {
+    const role = m?.sender === 'human' ? 'user' : m?.sender === 'assistant' ? 'assistant' : null;
+    if (!role) continue;
+    const parts = Array.isArray(m.content) ? m.content.filter((p) => p?.type === 'text').map((p) => text(p.text)) : [];
+    const body = (parts.length ? parts.join('\n') : text(m.text)).trim();
+    if (body) turns.push({ role, text: body, id: m.uuid, timestamp: iso(m.created_at) });
+  }
+  return turns;
+}
+
+/**
+ * The export's conversations as [{ id, at, turns }], newest first, within `days` of `now`
+ * (null = all). Never throws on a malformed entry; skips it. PURE.
+ */
+export function conversationsFrom(list, format, { now = Date.now(), days = DEFAULT_DAYS } = {}) {
+  const since = days == null ? -Infinity : now - days * DAY;
+  const out = [];
+  for (const c of Array.isArray(list) ? list : []) {
+    if (!c || typeof c !== 'object') continue;
+    const id = format === 'chatgpt' ? (c.conversation_id || c.id) : c.uuid;
+    const at = format === 'chatgpt' ? iso(c.update_time ?? c.create_time) : iso(c.updated_at ?? c.created_at);
+    if (!id || !at || Date.parse(at) < since || Date.parse(at) > now) continue;
+    const turns = format === 'chatgpt' ? chatgptTurns(c) : claudeTurns(c);
+    if (turns.some((t) => t.role === 'user') && turns.some((t) => t.role === 'assistant')) out.push({ id: String(id), at, turns });
+  }
+  return out.sort((a, b) => Date.parse(b.at) - Date.parse(a.at));
+}
+
+/** conversations.json from a .zip (system unzip, else bsdtar) or a .json path. */
+export function readExport(path) {
+  const p = resolve(path);
+  if (!existsSync(p)) throw Object.assign(new Error(`no file at ${p}`), { code: 'ENOENT' });
+  if (extname(p).toLowerCase() !== '.zip') return JSON.parse(readFileSync(p, 'utf8'));
+  const opts = { encoding: 'utf8', maxBuffer: 2 * 1024 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] };
+  for (const [cmd, args] of [['unzip', ['-p', p, 'conversations.json']], ['tar', ['-xOf', p, 'conversations.json']]]) {
+    try { const raw = execFileSync(cmd, args, opts); if (raw.trim()) return JSON.parse(raw); } catch { /* try the next */ }
+  }
+  throw new Error("couldn't find conversations.json in that zip — is it the ChatGPT or Claude data export?");
+}
+
+/**
+ * Fold every conversation through the capture spine and deposit once. deps: { fold, deposit,
+ * sourceId, statePath, now } — the real ones in the CLI, fakes in tests. Returns a summary.
+ */
+export async function importConversations(convos, format, deps) {
+  const surface = SURFACES[format];
+  let signals = [];
+  let messages = 0;
+  for (const c of convos) {
+    const r = await deps.fold(c, surface);
+    messages += r.counted || 0;
+    if (Array.isArray(r.signals)) signals = r.signals;     // cumulative: the last fold holds them all
+  }
+  const deposit = signals.length && deps.deposit ? await deps.deposit(signals, surface) : null;
+  return { conversations: convos.length, messages, signals: signals.length, deposited: Boolean(deposit?.deposited), deposit };
+}
+
+const plural = (n, w) => `${n.toLocaleString('en-US')} ${w}${n === 1 ? '' : 's'}`;
+
+/** The result in plain words. PURE. */
+export function summaryText(r, { service, days, dryRun = false, paired = false }) {
+  const span = days == null ? '' : ` from the last ${days === 365 ? 'year' : `${days} days`}`;
+  if (!r.conversations) return `No ${service} conversations${span} to read in that file.`;
+  const head = `${dryRun ? 'Would read' : 'Read'} ${plural(r.conversations, 'conversation')}${span} from ${service} (${plural(r.messages, 'message')} of yours).`;
+  if (dryRun) return `${head} Nothing was changed.`;
+  const learned = r.signals
+    ? `Phaedo found ${plural(r.signals, 'pattern')} in how you work${paired ? (r.deposited ? ' and sent them to your phone' : '; they\'ll reach your phone with the next sync') : ''}.`
+    : 'Phaedo found nothing new in how you work from these.';
+  return `${head} ${learned} Only counts were kept; you can delete the export file now. To see and prune what it learned: npm run learned`;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+async function main(argv) {
+  const file = argv.find((a) => !a.startsWith('--'));
+  const say = (s) => process.stdout.write(s + '\n');
+  if (!file) {
+    say('Usage: npm run import -- <ChatGPT or Claude export .zip, or its conversations.json> [--all] [--days N] [--dry-run]');
+    return 1;
+  }
+  const opt = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : null; };
+  const days = argv.includes('--all') ? null : (Number(opt('--days')) > 0 ? Number(opt('--days')) : DEFAULT_DAYS);
+  const dryRun = argv.includes('--dry-run');
+
+  let list;
+  try { list = readExport(file); } catch (e) { say(`✗ ${e.code === 'ENOENT' ? `No file at ${file}.` : e.message}`); return 1; }
+  const format = detectFormat(list);
+  if (!format) { say("✗ That doesn't look like a ChatGPT or Claude data export (no conversations in the shape either one uses)."); return 1; }
+  const service = format === 'chatgpt' ? 'ChatGPT' : 'Claude';
+  const convos = conversationsFrom(list, format, { days });
+  list = null;                                   // the raw export is not needed past this point
+
+  if (dryRun) {
+    const messages = convos.reduce((n, c) => n + c.turns.filter((t) => t.role === 'user').length, 0);
+    say(summaryText({ conversations: convos.length, messages, signals: 0 }, { service, days, dryRun: true }));
+    return 0;
+  }
+
+  const MCP_DIR = dirname(fileURLToPath(import.meta.url));
+  const { loadCaptureModule } = await import('./lib/capture-home.js');
+  const [{ turnsToBatch }, { foldBatchToSignals }, { deriveSourceDeviceId }] = await Promise.all(
+    ['capture/exchanges.js', 'capture/capture-core.js', 'capture/source-id.js'].map(loadCaptureModule));
+  const { loadPairingRecord } = await import('./phone-source.js');
+  const { buildCaptureDelta, depositCaptureDelta } = await import('./capture-sync.js');
+  let pairing = null;
+  try { pairing = await loadPairingRecord(MCP_DIR); } catch { pairing = null; }
+  const now = new Date().toISOString();
+  const sourceId = deriveSourceDeviceId(pairing, SURFACES[format]);
+
+  const r = await importConversations(convos, format, {
+    async fold(c, surface) {
+      const batch = turnsToBatch(c.turns, { sessionId: `${surface}:${c.id}`, platform: surface });
+      // Regex detectors only: a local model over a whole history would take hours.
+      const out = await foldBatchToSignals(batch, { sourceId, surface, sessionLocalId: `${surface}:${c.id}`, now, captureModel: null });
+      return { signals: out.signals, counted: batch.user_prompts.length };
+    },
+    deposit: pairing ? async (signals, surface) => {
+      const delta = buildCaptureDelta(signals, { sourceSurface: surface, sourceDeviceId: sourceId, capturedAt: now });
+      return depositCaptureDelta(pairing, delta, { now: () => now });
+    } : null,
+  });
+  say(summaryText(r, { service, days, paired: Boolean(pairing) }));
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  main(process.argv.slice(2)).then((c) => process.exit(c), (e) => { process.stderr.write(`✗ ${e.message}\n`); process.exit(1); });
+}