@jossuealcala/madre 0.3.2 → 0.4.0

package/src/chats.mjs

@@ -0,0 +1,193 @@
+// A project has one memory and many conversations.
+//
+// The archive, the crew, the modules and the privacy list belong to the project: they are what
+// MADRE knows about this codebase, and they do not start over because somebody opened a new
+// thread. A conversation is only the record of one line of work — its own ledger, its own
+// transcript, its own window — and everything it says feeds the same archive.
+//
+// The first conversation is the ledger that was always there, kept exactly where it was: no file
+// is moved to add this, so a room that existed before opens as it always did and simply gains a
+// name. New conversations get a folder of their own next to it.
+//
+//   <room>/events.jsonl              the first conversation
+//   <room>/chats/<id>/events.jsonl   every one after it
+//   <room>/chats.json                their names, and which one is open
+//
+// Nothing here starts a room or reads a ledger. It keeps the list.
+
+import { readFile, writeFile, mkdir, rm, readdir, open, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const MAIN_CHAT = 'main';
+export const CHAT_TITLE_MAX = 80;
+const FILE = 'chats.json';
+
+export const isChatId = (id) => typeof id === 'string' && (id === MAIN_CHAT || /^[a-z0-9]{8,32}$/.test(id));
+
+// Where one conversation's ledger lives. The first one never moved.
+export function chatLedger(roomDir, id) {
+  return id === MAIN_CHAT ? join(roomDir, 'events.jsonl') : join(roomDir, 'chats', id, 'events.jsonl');
+}
+
+async function readIndex(roomDir) {
+  try {
+    const raw = JSON.parse(await readFile(join(roomDir, FILE), 'utf8'));
+    if (raw && typeof raw === 'object' && raw.chats && typeof raw.chats === 'object') return raw;
+  } catch { /* no index yet, or an unreadable one: the room still opens */ }
+  return null;
+}
+
+async function writeIndex(roomDir, index) {
+  await mkdir(roomDir, { recursive: true }).catch(() => {});
+  await writeFile(join(roomDir, FILE), JSON.stringify(index, null, 2));
+  return index;
+}
+
+// The list, with the first conversation always in it. A room that predates conversations reads
+// as one conversation, which is what it was.
+export async function chatIndex(roomDir) {
+  const index = await readIndex(roomDir);
+  const now = new Date().toISOString();
+  if (!index) return { active: MAIN_CHAT, chats: { [MAIN_CHAT]: { title: null, createdAt: now, updatedAt: now, messages: 0, preview: null } } };
+  if (!index.chats[MAIN_CHAT]) index.chats[MAIN_CHAT] = { title: null, createdAt: now, updatedAt: now, messages: 0, preview: null };
+  if (!index.chats[index.active]) index.active = MAIN_CHAT;
+  return index;
+}
+
+const shape = (id, entry, active) => ({
+  id,
+  title: entry.title || (id === MAIN_CHAT ? 'First conversation' : 'Untitled'),
+  named: Boolean(entry.title),
+  createdAt: entry.createdAt ?? null,
+  updatedAt: entry.updatedAt ?? entry.createdAt ?? null,
+  messages: Number(entry.messages ?? 0),
+  preview: entry.preview ?? null,
+  active: id === active,
+});
+
+// Newest first, because that is the order a person looks for a conversation in.
+export async function listChats(roomDir) {
+  const index = await chatIndex(roomDir);
+  const chats = Object.entries(index.chats)
+    .map(([id, entry]) => shape(id, entry, index.active))
+    .sort((a, b) => String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? '')));
+  return { active: index.active, chats };
+}
+
+export async function createChat(roomDir, { title = null, now = new Date().toISOString() } = {}) {
+  const index = await chatIndex(roomDir);
+  const id = randomUUID().replace(/-/g, '').slice(0, 16);
+  index.chats[id] = { title: title ? String(title).slice(0, CHAT_TITLE_MAX) : null, createdAt: now, updatedAt: now, messages: 0, preview: null };
+  index.active = id;
+  await mkdir(join(roomDir, 'chats', id), { recursive: true });
+  await writeIndex(roomDir, index);
+  return shape(id, index.chats[id], index.active);
+}
+
+export async function openChat(roomDir, id) {
+  const index = await chatIndex(roomDir);
+  if (!index.chats[id]) return null;
+  index.active = id;
+  await writeIndex(roomDir, index);
+  return shape(id, index.chats[id], index.active);
+}
+
+export async function renameChat(roomDir, id, title) {
+  const index = await chatIndex(roomDir);
+  if (!index.chats[id]) return null;
+  const named = String(title ?? '').trim().slice(0, CHAT_TITLE_MAX);
+  index.chats[id].title = named || null;
+  await writeIndex(roomDir, index);
+  return shape(id, index.chats[id], index.active);
+}
+
+// Deleting a conversation takes its transcript and nothing else: whatever the archivist distilled
+// from it is the project's memory, not the conversation's, and it stays. The last conversation
+// cannot be deleted — a room always has somewhere to talk.
+export async function deleteChat(roomDir, id) {
+  const index = await chatIndex(roomDir);
+  if (!index.chats[id]) return null;
+  if (Object.keys(index.chats).length < 2) return { error: 'A room always has one conversation. Start another before deleting this one.' };
+  delete index.chats[id];
+  if (index.active === id) index.active = Object.keys(index.chats)[0];
+  if (id === MAIN_CHAT) await rm(join(roomDir, 'events.jsonl'), { force: true });
+  else await rm(join(roomDir, 'chats', id), { recursive: true, force: true, maxRetries: 6, retryDelay: 60 });
+  await writeIndex(roomDir, index);
+  return { deleted: id, active: index.active };
+}
+
+// What the list shows about a conversation, kept as it happens rather than by reading every
+// ledger to draw a sidebar. A conversation with no name of its own takes the first thing the
+// human said in it, which is what they will look for.
+export async function touchChat(roomDir, id, { text = null, now = new Date().toISOString(), counts = true } = {}) {
+  const index = await chatIndex(roomDir);
+  const entry = index.chats[id];
+  if (!entry) return null;
+  entry.updatedAt = now;
+  if (counts) entry.messages = Number(entry.messages ?? 0) + 1;
+  if (text) {
+    const line = String(text).replace(/\s+/g, ' ').trim().slice(0, 120);
+    if (line) {
+      entry.preview = line;
+      if (!entry.title) entry.title = line.slice(0, CHAT_TITLE_MAX);
+    }
+  }
+  await writeIndex(roomDir, index);
+  return shape(id, entry, index.active);
+}
+
+// Conversations whose folder is on disk but which no index knows about: a room copied by hand, or
+// an index lost. They are listed rather than ignored, because a transcript is not disposable.
+export async function adoptStrays(roomDir) {
+  let folders = [];
+  try { folders = await readdir(join(roomDir, 'chats')); } catch { return { adopted: [] }; }
+  const index = await chatIndex(roomDir);
+  const adopted = [];
+  for (const id of folders) {
+    if (!isChatId(id) || index.chats[id]) continue;
+    index.chats[id] = { title: null, createdAt: null, updatedAt: null, messages: 0, preview: null };
+    adopted.push(id);
+  }
+  if (adopted.length) await writeIndex(roomDir, index);
+  return { adopted };
+}
+
+// The last sequence a ledger reached, read from its tail rather than by loading it. A project
+// numbers its exchanges once across every conversation, so opening one has to know where the
+// others got to; doing that by reading whole ledgers would make opening a conversation cost more
+// the longer the project has been worked in.
+export async function lastSequenceOf(file, { window = 65536 } = {}) {
+  let handle;
+  try {
+    const size = (await stat(file)).size;
+    if (!size) return 0;
+    handle = await open(file, 'r');
+    const length = Math.min(window, size);
+    const buffer = Buffer.alloc(length);
+    await handle.read(buffer, 0, length, size - length);
+    const lines = buffer.toString('utf8').split('\n').filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      try {
+        const event = JSON.parse(lines[i]);
+        if (Number.isInteger(event?.sequence)) return event.sequence;
+      } catch { /* a half line at the window's edge, or a torn write: keep looking back */ }
+    }
+    return 0;
+  } catch {
+    return 0;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+// Where the project's numbering stands, across every conversation but the one being opened.
+export async function projectFloor(roomDir, { except = null } = {}) {
+  const { chats } = await listChats(roomDir);
+  let floor = 0;
+  for (const chat of chats) {
+    if (chat.id === except) continue;
+    floor = Math.max(floor, await lastSequenceOf(chatLedger(roomDir, chat.id)));
+  }
+  return floor;
+}

package/src/checkpoint.mjs

@@ -86,7 +86,7 @@ export async function worktreeTree(root, { exclude = [] } = {}) {
     }
     return (await git(root, ['write-tree'], { env })).trim();
   } finally {
-    await rm(dir, { recursive: true, force: true });
+    await rm(dir, { recursive: true, force: true, maxRetries: 6, retryDelay: 60 });
   }
 }
 

package/src/cold.mjs

@@ -0,0 +1,56 @@
+// Cold zones: the part of the archive nothing has ever reached for.
+//
+// A memory is cold when three things are true at once, and the three together are what make the
+// claim strong enough to act on:
+//
+//   · no turn has ever carried it
+//   · it shares a subject with no other memory, so nothing can reach it sideways either
+//   · the room has reached into the archive often enough since it was written that it has plainly
+//     had its chances
+//
+// That third one is the whole point. Never-recalled is not cold; never-recalled is what every
+// memory is on the day it is written. What makes a memory cold is opportunity that went by: the
+// archive was opened forty times and it was never the answer. Chances are counted in turns that
+// actually reached into the archive, because those are the only chances that existed.
+//
+// Pure functions. The room hands in what it already has.
+
+export const COLD_CHANCES = 12;   // turns that went into the archive without ever taking it
+
+// How many of `times` (ascending) are at or after `from`.
+function after(times, from) {
+  let low = 0;
+  let high = times.length;
+  while (low < high) {
+    const middle = (low + high) >> 1;
+    if (times[middle] < from) low = middle + 1; else high = middle;
+  }
+  return times.length - low;
+}
+
+// Which memories are adrift, and how many chances each one has had. `since` is the day this room
+// started keeping the trail: a memory older than that is only counted from there, because what
+// happened before it was never written down and must not be held against the note.
+export function coldNotes({ notes = [], links = [], batches = [], since = null, chances = COLD_CHANCES } = {}) {
+  const linked = new Set(links.flatMap((link) => [link.a, link.b]));
+  const times = batches.map((at) => Date.parse(at)).filter((at) => Number.isFinite(at)).sort((a, b) => a - b);
+  const floor = since ? Date.parse(since) : 0;
+  const cold = new Map();
+  for (const note of notes) {
+    if (!note || note.kind === 'aberration' || note.refutedBy) continue;   // a refutation is not a cold memory
+    if (Number(note.recalled ?? 0) > 0) continue;
+    if (linked.has(note.id)) continue;
+    const written = Date.parse(note.created);
+    const from = Math.max(Number.isFinite(written) ? written : 0, Number.isFinite(floor) ? floor : 0);
+    const had = after(times, from);
+    if (had >= chances) cold.set(note.id, { chances: had });
+  }
+  return cold;
+}
+
+// What the room should say about it. Never a number on its own: a count of cold memories means
+// nothing without what it is a count of.
+export function coldReading(cold, notes = []) {
+  const standing = notes.filter((note) => note && note.kind !== 'aberration' && !note.refutedBy).length;
+  return { count: cold.size, standing, share: standing > 0 ? Number((cold.size / standing).toFixed(3)) : 0 };
+}

package/src/commands.mjs

@@ -25,8 +25,8 @@ export const COMMANDS = [
     name: 'git',
     module: 'git-pulse',
     title: 'Git Pulse',
-    usage: '/git [status|log|diff|branches]',
-    summary: 'Repository status, recent commits, uncommitted changes and branches, read-only, from the project itself.',
+    usage: '/git [status|log|diff|branches|commit "message"|push [confirm]]',
+    summary: 'Repository status, recent commits, uncommitted changes and branches from the project itself; commit and push by your own hand, with a confirmation before anything leaves.',
     async available({ projectRoot }) {
       return exists(join(projectRoot, '.git'));
     },
@@ -48,8 +48,36 @@ export const COMMANDS = [
         await add('staged (stat)', ['-c', 'color.ui=never', 'diff', '--cached', '--stat']);
       } else if (what === 'branches') {
         await add('branches', ['-c', 'color.ui=never', 'branch', '-avv']);
+      } else if (what === 'commit') {
+        // The human commits what the room produced. Everything in the tree, one message, local: reversible with git.
+        const message = args.slice(1).join(' ').replace(/^["'“]+|["'”]+$/g, '').trim();
+        if (!message) return { ok: false, title: 'Git Pulse · commit', text: 'Give the commit a message: /git commit "what and why".' };
+        // Without an identity git refuses the commit with a wall of advice; say the one thing to do.
+        const email = await run('git', ['config', '--get', 'user.email'], projectRoot);
+        const who = await run('git', ['config', '--get', 'user.name'], projectRoot);
+        if (!email.text.trim() || !who.text.trim()) {
+          return { ok: false, title: 'Git Pulse · commit', text: 'This computer has no git identity, so the commit would have no author. Set it once in your terminal:\n\n  git config --global user.name "Your Name"\n  git config --global user.email you@example.com' };
+        }
+        const staged = await run('git', ['add', '-A', '--', '.'], projectRoot);
+        if (!staged.ok) return { ok: false, title: 'Git Pulse · commit', text: staged.text };
+        const committed = await run('git', ['-c', 'color.ui=never', 'commit', '-m', message], projectRoot);
+        if (!committed.ok) return { ok: false, title: 'Git Pulse · commit', text: committed.text || 'Nothing to commit.' };
+        await add('committed', ['-c', 'color.ui=never', 'show', '--stat', '--format=%h %s', 'HEAD']);
+        return { ok: true, title: 'Git Pulse · commit', text: sections.join('\n\n') };
+      } else if (what === 'push') {
+        // Nothing leaves without the word: first the preview of what would go, then /git push confirm.
+        const upstream = await run('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], projectRoot);
+        if (!upstream.ok) return { ok: false, title: 'Git Pulse · push', text: `This branch has no upstream. Set it once from your terminal: git push -u <remote> <branch>.` };
+        const ahead = await run('git', ['-c', 'color.ui=never', 'log', '--oneline', '@{u}..HEAD'], projectRoot);
+        const commits = ahead.text ? ahead.text.split('\n').filter(Boolean) : [];
+        if (!commits.length) return { ok: true, title: 'Git Pulse · push', text: `Nothing to push: ${upstream.text} already has everything.` };
+        if ((args[1] ?? '').toLowerCase() !== 'confirm') {
+          return { ok: true, title: 'Git Pulse · push · preview', text: `## would leave for ${upstream.text}\n${commits.join('\n')}\n\nThis leaves the machine and cannot be undone by MADRE. Send it with: /git push confirm` };
+        }
+        const pushed = await run('git', ['-c', 'color.ui=never', 'push'], projectRoot, 120000);
+        return { ok: pushed.ok, title: 'Git Pulse · push', text: `## sent to ${upstream.text}\n${commits.join('\n')}\n\n${pushed.text || '(pushed)'}` };
       } else {
-        return { ok: false, title: 'Git Pulse', text: `Unknown subcommand "${what}". Use /git status, /git log [n], /git diff or /git branches.` };
+        return { ok: false, title: 'Git Pulse', text: `Unknown subcommand "${what}". Use /git status, /git log [n], /git diff, /git branches, /git commit "message" or /git push [confirm].` };
       }
       return { ok: true, title: `Git Pulse · ${what}`, text: sections.join('\n\n') };
     },

package/src/conversation-context.mjs

@@ -19,14 +19,44 @@ export function messageEntry(event) {
 
 // `omitSynthetic` drops MADRE's own canned replies (identity, refusals, round-table plans):
 // @madre must never read them back, or a small model starts echoing them.
-export function buildConversationContext(events, { excludeMessageId, maxChars = 16000, omitSynthetic = false } = {}) {
+// How much of the budget a window is cut back to when it finally has to let go of its oldest
+// messages. Dropping one message per turn would move the start of the transcript on every turn;
+// dropping a chunk at once and then holding still is what lets a CLI read most of it back from
+// its own cache. Lower means longer stretches of stability and a leaner average window.
+export const CONTEXT_KEEP = 0.62;
+
+export function buildConversationContext(events, { excludeMessageId, maxChars = 16000, omitSynthetic = false, anchor = null } = {}) {
   const messages = events
     .map((event) => (omitSynthetic && event?.payload?.synthetic ? null : messageEntry(event)))
     .filter((message) => message && message.messageId !== excludeMessageId);
+  const budget = Math.max(0, Number(maxChars) || 0);
+
+  // The window is anchored, not sliding. A sliding window starts one message later on every
+  // turn, so the transcript an agent reads begins with different words every time and none of
+  // it can be matched against what it read last turn. Held still, the whole of it but the tail
+  // is the same bytes as before, which is the difference between paying for it once and paying
+  // for it every turn. It only ever moves when what has been said since no longer fits.
+  const weigh = (from) => {
+    let used = 0;
+    for (let i = from; i < messages.length; i += 1) used += messages[i].sender.length + messages[i].role.length + messages[i].text.length + 4;
+    return used;
+  };
+  let start = 0;
+  if (Number.isInteger(anchor)) {
+    const held = messages.findIndex((message) => message.sequence >= anchor);
+    if (held >= 0 && weigh(held) <= budget) start = held;
+  }
+  if (!start || weigh(start) > budget) {
+    // Let go of a chunk and then hold: back off until the window sits well under its budget, so
+    // there is room for many turns of new words before it has to move again.
+    start = messages.length;
+    while (start > 0 && weigh(start - 1) <= budget * CONTEXT_KEEP) start -= 1;
+  }
+
   const selected = [];
-  let remaining = Math.max(0, Number(maxChars) || 0);
+  let remaining = budget;
 
-  for (let index = messages.length - 1; index >= 0 && remaining > 0; index -= 1) {
+  for (let index = messages.length - 1; index >= start && remaining > 0; index -= 1) {
     const message = messages[index];
     const label = `${message.sender} (${message.role})`;
     const allowance = Math.max(0, remaining - label.length - 2);
@@ -42,6 +72,8 @@ export function buildConversationContext(events, { excludeMessageId, maxChars =
 
   return {
     messages: selected,
+    // Where this window begins, for the next turn to hold on to.
+    anchor: selected[0]?.sequence ?? null,
     omittedMessages: messages.length - selected.length,
     firstSequence: selected[0]?.sequence ?? null,
     throughSequence: selected.at(-1)?.sequence ?? null,

package/src/credentials.mjs

@@ -0,0 +1,145 @@
+// Handing a provider key to a CLI that signs in from its own prompt.
+//
+// MADRE keeps its promise: it never stores a credential of its own. The key the human pastes is
+// written where that CLI looks for it, with the file locked to the owner, and MADRE keeps no
+// copy: not in ~/.pulse/config.json, not in the room's ledger, not in a log line. What the room
+// records is that a key was set, never the key.
+//
+// Every write is verified on the spot by asking the CLI (or MADRE's own probe) whether it is
+// signed in now. If it is not, the previous files are put back, so a format MADRE guessed wrong
+// leaves nothing behind.
+
+import { execFile } from 'node:child_process';
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const OWNER_ONLY = 0o600;
+
+// A key is one opaque token: no spaces, no newlines, and long enough to be one.
+export function normalizeKey(value) {
+  const key = String(value ?? '').trim();
+  if (!key) return { ok: false, error: 'Paste the key first.' };
+  if (/\s/.test(key)) return { ok: false, error: 'That does not look like a key: it has spaces or line breaks.' };
+  if (key.length < 12 || key.length > 400) return { ok: false, error: 'That does not look like a key: check you copied all of it and nothing else.' };
+  return { ok: true, key };
+}
+
+// OpenCode brings no model of its own. These are the providers MADRE can wire with a key;
+// any other still works through `opencode auth login` in a terminal.
+export const OPENCODE_PROVIDERS = [
+  { id: 'anthropic', label: 'Anthropic', keyUrl: 'https://console.anthropic.com/settings/keys' },
+  { id: 'openai', label: 'OpenAI', keyUrl: 'https://platform.openai.com/api-keys' },
+  { id: 'openrouter', label: 'OpenRouter', keyUrl: 'https://openrouter.ai/keys' },
+  { id: 'google', label: 'Google AI Studio', keyUrl: 'https://aistudio.google.com/app/apikey' },
+];
+
+// What the room offers for each agent that cannot be signed in with a click.
+export function keyPlanFor(id) {
+  if (id === 'gemini') {
+    return {
+      agent: 'gemini',
+      label: 'Gemini API key',
+      keyUrl: 'https://aistudio.google.com/app/apikey',
+      writesTo: '~/.gemini/.env',
+      note: 'The key is written where the Gemini CLI looks for it, readable only by you. MADRE keeps no copy.',
+      providers: null,
+    };
+  }
+  if (id === 'opencode') {
+    return {
+      agent: 'opencode',
+      label: 'Provider key',
+      keyUrl: null,
+      writesTo: '~/.local/share/opencode/auth.json',
+      note: 'OpenCode brings no model of its own: pick the provider whose key you are pasting. The key is written where OpenCode looks for it, readable only by you. MADRE keeps no copy.',
+      providers: OPENCODE_PROVIDERS,
+    };
+  }
+  return null;
+}
+
+async function readIfThere(path) {
+  try { return await readFile(path, 'utf8'); } catch { return null; }
+}
+async function restore(path, previous) {
+  if (previous === null) await rm(path, { force: true });
+  else await writeFile(path, previous, { mode: OWNER_ONLY });
+}
+
+// ---- Gemini: a line in ~/.gemini/.env, plus the auth type its settings must select.
+async function applyGeminiKey(key, { home, probe }) {
+  const dir = join(home, '.gemini');
+  const envFile = join(dir, '.env');
+  const settingsFile = join(dir, 'settings.json');
+  await mkdir(dir, { recursive: true });
+  const beforeEnv = await readIfThere(envFile);
+  const beforeSettings = await readIfThere(settingsFile);
+  try {
+    const kept = (beforeEnv ?? '').split('\n').filter((line) => line.trim() && !/^\s*(GEMINI_API_KEY|GOOGLE_API_KEY)\s*=/.test(line));
+    await writeFile(envFile, `${[...kept, `GEMINI_API_KEY=${key}`].join('\n')}\n`, { mode: OWNER_ONLY });
+    await chmod(envFile, OWNER_ONLY).catch(() => {});
+    let settings = {};
+    try { settings = JSON.parse(beforeSettings ?? '{}') ?? {}; } catch { settings = {}; }
+    settings.security = { ...(settings.security ?? {}), auth: { ...(settings.security?.auth ?? {}), selectedType: 'gemini-api-key' } };
+    await writeFile(settingsFile, `${JSON.stringify(settings, null, 2)}\n`, { mode: OWNER_ONLY });
+    const state = await probe();
+    if (state?.state !== 'signed-in') {
+      await restore(envFile, beforeEnv);
+      await restore(settingsFile, beforeSettings);
+      return { ok: false, error: `The key was written but Gemini still reads as ${state?.state ?? 'unknown'}${state?.detail ? ` (${state.detail})` : ''}. Nothing was changed.` };
+    }
+    return { ok: true, detail: state.detail ?? 'via API key' };
+  } catch (error) {
+    await restore(envFile, beforeEnv);
+    await restore(settingsFile, beforeSettings);
+    return { ok: false, error: `The key could not be written: ${error.message}` };
+  }
+}
+
+// ---- OpenCode: an entry in its auth.json, confirmed by asking `opencode auth list`.
+async function applyOpenCodeKey(key, { home, provider, executable, run }) {
+  const known = OPENCODE_PROVIDERS.some((item) => item.id === provider);
+  if (!known) return { ok: false, error: 'Pick the provider this key belongs to.' };
+  const file = join(home, '.local', 'share', 'opencode', 'auth.json');
+  await mkdir(join(home, '.local', 'share', 'opencode'), { recursive: true });
+  const before = await readIfThere(file);
+  try {
+    let auth = {};
+    try { auth = JSON.parse(before ?? '{}') ?? {}; } catch { auth = {}; }
+    auth[provider] = { type: 'api', key };
+    await writeFile(file, `${JSON.stringify(auth, null, 2)}\n`, { mode: OWNER_ONLY });
+    await chmod(file, OWNER_ONLY).catch(() => {});
+    // OpenCode itself is the judge: if its own listing does not show the provider, the shape
+    // MADRE wrote is not the shape it reads, and nothing should be left behind.
+    const listed = await run(executable, ['auth', 'list']);
+    if (!new RegExp(provider, 'i').test(listed)) {
+      await restore(file, before);
+      return { ok: false, error: `OpenCode does not list ${provider} after the key was written, so MADRE put the file back. Run \`opencode auth login\` in a terminal for this one.` };
+    }
+    return { ok: true, detail: `${provider} (api)` };
+  } catch (error) {
+    await restore(file, before);
+    return { ok: false, error: `The key could not be written: ${error.message}` };
+  }
+}
+
+const runOpenCode = async (executable, args) => {
+  try {
+    const { stdout, stderr } = await execFileAsync(executable, args, { timeout: 15000, env: { ...process.env, NO_COLOR: '1' } });
+    return `${stdout}\n${stderr}`;
+  } catch (error) {
+    return `${error.stdout ?? ''}\n${error.stderr ?? error.message}`;
+  }
+};
+
+// Writes the key for one agent and answers whether that agent is signed in now.
+export async function applyKey({ agent, key, provider = null, home = homedir(), probe, executable = 'opencode', run = runOpenCode }) {
+  const checked = normalizeKey(key);
+  if (!checked.ok) return checked;
+  if (agent === 'gemini') return applyGeminiKey(checked.key, { home, probe });
+  if (agent === 'opencode') return applyOpenCodeKey(checked.key, { home, provider, executable, run });
+  return { ok: false, error: `${agent} does not take a key here: it signs in with a click.` };
+}

package/src/dataset.mjs

@@ -8,6 +8,7 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { redact } from './sentinel-errors.mjs';
+import { ABERRATION } from './memory.mjs';
 
 const MIN_ANSWER_CHARS = 40;
 
@@ -82,14 +83,22 @@ export function readiness(events, notes = [], { target = DATASET_TARGET } = {})
   const turns = pairs.filter((pair) => pair.kind === 'turn').length;
   const delegated = pairs.length - turns;
   const good = pairs.filter((pair) => pair.rating === 'good').length;
-  const total = pairs.length + notes.length;
-  return { pairs: total, turns, delegated, notes: notes.length, good, bad, target, ready: total >= target };
+  // Aberrations are counted apart: they never become one of the pairs the model learns to
+  // answer with, so counting them toward readiness would say the room is further along than it is.
+  const standing = notes.filter((note) => note.kind !== ABERRATION && !note.refutedBy);
+  const aberrations = notes.filter((note) => note.kind === ABERRATION).length;
+  const total = pairs.length + standing.length;
+  return { pairs: total, turns, delegated, notes: standing.length, aberrations, good, bad, target, ready: total >= target };
 }
 
 // Distilled notes become recall pairs: "what does the room remember about …" → the note.
+// Two kinds of note never come through here. An aberration is a claim the room decided is false,
+// and teaching a model to recall it would be teaching it the hallucination. A note that has been
+// refuted is no longer what the room believes. Both are still exported, as preference pairs
+// below, where being wrong is the point.
 export function pairsFromNotes(notes, { project = 'project', home, user, privacy = null } = {}) {
   const clean = guard(privacy);
-  return notes.map((note) => ({
+  return notes.filter((note) => note.kind !== ABERRATION && !note.refutedBy).map((note) => ({
     kind: 'note',
     agent: 'madre',
     mode: 1,
@@ -103,6 +112,45 @@ export function pairsFromNotes(notes, { project = 'project', home, user, privacy
   }));
 }
 
+// What the room got wrong, in the shape that trains against it. Each aberration becomes one
+// preference pair: the same ask, the false claim as what to avoid, the correction as what to say
+// instead. A negative on its own teaches a model very little; a pair tells it which of two
+// answers to prefer, which is what DPO and ORPO are built to read.
+export function preferencesFromAberrations(notes, { project = 'project', home, user, privacy = null } = {}) {
+  const clean = guard(privacy);
+  const say = (text) => clean(redact(String(text ?? ''), { home, user }));
+  const byId = new Map(notes.map((note) => [note.id, note]));
+  const pairs = [];
+  for (const note of notes) {
+    if (note.kind !== ABERRATION) continue;
+    // Without something true to put in its place there is nothing to prefer, so it is left out.
+    const truth = note.correction || (note.contradicts && byId.get(note.contradicts)?.text) || null;
+    if (!truth) continue;
+    const claim = say(note.text);
+    const better = say(truth);
+    if (!claim || !better) continue;
+    // A correction that restates the claim teaches nothing, and a model asked to prefer one of
+    // two near-identical answers learns the wrong lesson from the noise between them. A weak
+    // archivist writes these, so they are caught here rather than shipped.
+    const words = (text) => new Set(String(text).toLowerCase().normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^\p{L}\p{N}]+/gu, ' ').trim().split(' ').filter((word) => word.length > 2));
+    const [left, right] = [words(claim), words(better)];
+    if (!left.size || !right.size) continue;
+    let shared = 0;
+    for (const word of right) if (left.has(word)) shared += 1;
+    if (shared / Math.min(left.size, right.size) > 0.8) continue;
+    pairs.push({
+      kind: 'aberration',
+      sequence: note.throughSequence,
+      at: note.created,
+      detector: note.detector ?? null,
+      prompt: `Is this true of the project "${project}"? ${claim}`,
+      rejected: claim,
+      chosen: better,
+    });
+  }
+  return pairs;
+}
+
 // Deterministic split: the sequence decides, so re-exports keep lines on the same side.
 export function split(pairs, { validEvery = 10 } = {}) {
   const train = [];
@@ -114,14 +162,18 @@ export function split(pairs, { validEvery = 10 } = {}) {
 
 export async function exportDataset({ events, notes = [], dir, project = 'project', home, user, privacy = null }) {
   const pairs = [...pairsFromEvents(events, { project, home, user, privacy }), ...pairsFromNotes(notes, { project, home, user, privacy })].sort((a, b) => a.sequence - b.sequence);
+  const preferences = preferencesFromAberrations(notes, { project, home, user, privacy });
   const { train, valid } = split(pairs);
   await mkdir(dir, { recursive: true });
   const line = (pair) => JSON.stringify({ messages: pair.messages });
   await writeFile(join(dir, 'train.jsonl'), train.map(line).join('\n') + (train.length ? '\n' : ''));
   await writeFile(join(dir, 'valid.jsonl'), valid.map(line).join('\n') + (valid.length ? '\n' : ''));
+  // Kept in a file of its own: it is a different shape and a different kind of training, and
+  // nothing that reads the chat files should ever pick it up by accident.
+  await writeFile(join(dir, 'preferences.jsonl'), preferences.map((pair) => JSON.stringify({ prompt: pair.prompt, chosen: pair.chosen, rejected: pair.rejected })).join('\n') + (preferences.length ? '\n' : ''));
   const byAgent = {};
   for (const pair of pairs) byAgent[pair.agent] = (byAgent[pair.agent] ?? 0) + 1;
-  const manifest = { project, exportedAt: new Date().toISOString(), pairs: pairs.length, turns: pairs.filter((p) => p.kind === 'turn').length, delegated: pairs.filter((p) => p.kind === 'delegated').length, good: pairs.filter((p) => p.rating === 'good').length, notes: pairs.filter((p) => p.kind === 'note').length, train: train.length, valid: valid.length, byAgent, files: ['train.jsonl', 'valid.jsonl'], format: 'chat · {"messages":[{role,content}]} · mlx-lm / llama-factory / axolotl' };
+  const manifest = { project, exportedAt: new Date().toISOString(), pairs: pairs.length, turns: pairs.filter((p) => p.kind === 'turn').length, delegated: pairs.filter((p) => p.kind === 'delegated').length, good: pairs.filter((p) => p.rating === 'good').length, notes: pairs.filter((p) => p.kind === 'note').length, aberrations: preferences.length, train: train.length, valid: valid.length, byAgent, files: ['train.jsonl', 'valid.jsonl', 'preferences.jsonl'], format: 'chat · {"messages":[{role,content}]} · mlx-lm / llama-factory / axolotl', preferenceFormat: 'preference · {"prompt","chosen","rejected"} · DPO / ORPO' };
   await writeFile(join(dir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
   return { dir, ...manifest };
 }