@jossuealcala/madre 0.3.3 → 0.4.0

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

package/src/distiller.mjs

@@ -3,7 +3,7 @@
 // keeping for every later turn. Pure functions here; the room schedules and
 // invokes. Nothing in this file talks to a model.
 
-import { MEMORY_KINDS } from './memory.mjs';
+import { ABERRATION, MEMORY_KINDS } from './memory.mjs';
 
 // Cheapest first, by the models these CLIs run by default.
 // Ollama, when the room has it, is the cheapest of all: local and free.
@@ -42,11 +42,12 @@ export function distillPrompt({ entries, projectName = 'the project', existing =
     `- fact: a verified statement about the project or its environment that is not obvious from the code`,
     `- preference: how the human wants things done or said`,
     `- question: something left open that a later turn should not forget`,
+    `- aberration: a claim the exchanges themselves showed to be false. Only when it was refuted out loud: someone stated something about this project and someone else corrected it, or the exchanges proved it wrong. Put the false claim in "text" and what turned out to be true in "correction". Never guess, never file a disagreement of opinion, and never file something merely unverified.`,
     'Skip greetings, restatements, transient status, anything a reader of the code would see anyway, and anything the exchanges do not actually establish.',
     json
-      ? `Output one JSON object and nothing else: {"memories":[...]} with at most ${MAX_MEMORIES_PER_RUN} items, each {"kind":"decision|fact|preference|question","text":"one self-contained sentence in the language the room uses, at most ${MAX_MEMORY_CHARS} characters, naming files, agents and numbers exactly","sources":[sequence numbers it comes from]}. If nothing durable was said: {"memories":[]}`
+      ? `Output one JSON object and nothing else: {"memories":[...]} with at most ${MAX_MEMORIES_PER_RUN} items, each {"kind":"${MEMORY_KINDS.join('|')}","text":"one self-contained sentence in the language the room uses, at most ${MAX_MEMORY_CHARS} characters, naming files, agents and numbers exactly","correction":"only on an aberration: what is true instead","sources":[sequence numbers it comes from]}. If nothing durable was said: {"memories":[]}`
       : `Output only JSON lines, one object per memory, at most ${MAX_MEMORIES_PER_RUN}, nothing else:`,
-    json ? null : `{"kind":"decision|fact|preference|question","text":"one self-contained sentence in the language the room uses, at most ${MAX_MEMORY_CHARS} characters, naming files, agents and numbers exactly","sources":[sequence numbers it comes from]}`,
+    json ? null : `{"kind":"${MEMORY_KINDS.join('|')}","text":"one self-contained sentence in the language the room uses, at most ${MAX_MEMORY_CHARS} characters, naming files, agents and numbers exactly","correction":"only on an aberration: what is true instead","sources":[sequence numbers it comes from]}`,
     json ? null : 'If nothing durable was said, output exactly: NONE',
     known,
     '<exchanges>',
@@ -76,13 +77,19 @@ export function parseDistillation(text, { fromSequence, throughSequence } = {})
     if (!parsed || typeof parsed !== 'object') continue;
     const memoryText = String(parsed.text ?? '').replace(/\s+/g, ' ').trim();
     if (!memoryText) continue;
-    const kind = MEMORY_KINDS.includes(parsed.kind) ? parsed.kind : 'fact';
+    // An unknown kind used to be filed as a fact. That was harmless while every kind was
+    // knowledge; now the list has one that is not, and a typo would turn a hallucination into
+    // something the room believes. Anything unrecognised is dropped instead.
+    if (!MEMORY_KINDS.includes(parsed.kind)) continue;
+    const kind = parsed.kind;
     const inRange = (n) => Number.isInteger(n) && (fromSequence == null || n >= fromSequence) && (throughSequence == null || n <= throughSequence);
     const sources = (Array.isArray(parsed.sources) ? parsed.sources : []).map(Number).filter(inRange);
     const key = memoryText.toLowerCase();
     if (seen.has(key)) continue;
     seen.add(key);
-    memories.push({ kind, text: memoryText.length > MAX_MEMORY_CHARS ? `${memoryText.slice(0, MAX_MEMORY_CHARS - 1)}…` : memoryText, sources });
+    const clip = (value) => (value.length > MAX_MEMORY_CHARS ? `${value.slice(0, MAX_MEMORY_CHARS - 1)}…` : value);
+    const correction = kind === ABERRATION ? clip(String(parsed.correction ?? '').replace(/\s+/g, ' ').trim()) : '';
+    memories.push({ kind, text: clip(memoryText), sources, ...(correction ? { correction } : {}) });
     if (memories.length >= MAX_MEMORIES_PER_RUN) break;
   }
   return memories;

package/src/event-store.mjs

@@ -8,16 +8,22 @@ export class EventStore {
   #nextSequence = 1;
   #writeQueue = Promise.resolve();
   #lockDirectory;
+  #floor = 0;
 
-  constructor(file) {
+  // `floor` is the highest sequence the rest of the project has already used. A project keeps one
+  // numbering across all of its conversations, so #1411 means one exchange in this project and
+  // not one in each thread — the memory index, every citation and NOSTROMO all lean on that.
+  // Gaps in a single ledger are fine: sequences are an order, not a count.
+  constructor(file, { floor = 0 } = {}) {
     this.#file = file;
+    this.#floor = Number.isFinite(floor) ? floor : 0;
     this.#lockDirectory = `${file}.lock`;
   }
 
   async initialize() {
     await mkdir(dirname(this.#file), { recursive: true });
     const existing = await this.readAll();
-    this.#nextSequence = (existing.at(-1)?.sequence ?? 0) + 1;
+    this.#nextSequence = Math.max(existing.at(-1)?.sequence ?? 0, this.#floor) + 1;
     return this;
   }
 
@@ -85,14 +91,14 @@ export class EventStore {
         return async () => {
           try {
             const owner = JSON.parse(await readFile(ownerFile, 'utf8'));
-            if (owner.token === token) await rm(this.#lockDirectory, { recursive: true, force: true });
+            if (owner.token === token) await rm(this.#lockDirectory, { recursive: true, force: true, maxRetries: 6, retryDelay: 60 });
           } catch (error) {
             if (error.code !== 'ENOENT') throw error;
           }
         };
       } catch (error) {
         if (created) {
-          await rm(this.#lockDirectory, { recursive: true, force: true });
+          await rm(this.#lockDirectory, { recursive: true, force: true, maxRetries: 6, retryDelay: 60 });
           throw error;
         }
         if (error.code !== 'EEXIST') throw error;
@@ -102,7 +108,7 @@ export class EventStore {
             process.kill(owner.pid, 0);
           } catch (ownerError) {
             if (ownerError.code === 'ESRCH') {
-              await rm(this.#lockDirectory, { recursive: true, force: true });
+              await rm(this.#lockDirectory, { recursive: true, force: true, maxRetries: 6, retryDelay: 60 });
               continue;
             }
           }
@@ -110,7 +116,7 @@ export class EventStore {
           if (ownerError.code !== 'ENOENT' && !(ownerError instanceof SyntaxError)) throw ownerError;
           const lock = await stat(this.#lockDirectory).catch(() => null);
           if (lock && Date.now() - lock.mtimeMs > 10000) {
-            await rm(this.#lockDirectory, { recursive: true, force: true });
+            await rm(this.#lockDirectory, { recursive: true, force: true, maxRetries: 6, retryDelay: 60 });
             continue;
           }
         }
@@ -138,7 +144,7 @@ export class EventStore {
         const temp = `${this.#file}.rewrite-${process.pid}`;
         await writeFile(temp, next.map((event) => JSON.stringify(event)).join('\n') + (next.length ? '\n' : ''));
         await rename(temp, this.#file);
-        this.#nextSequence = (next.at(-1)?.sequence ?? 0) + 1;
+        this.#nextSequence = Math.max(next.at(-1)?.sequence ?? 0, this.#floor) + 1;
         return { total: next.length, changed };
       } finally {
         await release();
@@ -153,7 +159,7 @@ export class EventStore {
       const release = await this.#acquireLock();
       try {
         const existing = await this.#readAllUnlocked();
-        const sequence = (existing.at(-1)?.sequence ?? 0) + 1;
+        const sequence = Math.max(existing.at(-1)?.sequence ?? 0, this.#floor) + 1;
         const event = {
           id: randomUUID(),
           sequence,

package/src/exam.mjs

@@ -0,0 +1,240 @@
+// The three tests that answer "is this room ready to be developed with?"
+//
+// The maturity reading counts what the archive is made of. It cannot tell you whether the archive
+// works, because nothing about a pile of notes says whether the right one comes back when it is
+// needed. Only a test says that, and a test is only worth running if it can fail.
+//
+//   1 · COVERAGE   — when this project asks its own questions, does the archive already hold the
+//                    answer? Real human messages from the ledger, recall run at the point each
+//                    one was asked, scored against the reply that was actually given.
+//   2 · CONSISTENCY — does the archive contradict itself? Contradictions EYECAT is still holding,
+//                    what has been taken out of circulation, and whether aberrations are being
+//                    filed more often lately or less.
+//   3 · MATCH      — does the local model, with this archive behind it, land where the frontier
+//                    CLI landed? Real questions from the ledger, asked again locally, compared
+//                    against the answer that was given at the time.
+//
+// What every one of them refuses to do is grade itself generously. Each reports how it measured
+// (meaning or words), how many cases it had, and the bar it used, because a number without those
+// three is a decoration.
+
+import { t } from './i18n.mjs';
+
+export const COVERAGE_SAMPLE = 30;
+export const COVERAGE_BAR = 0.55;      // cosine between the reply and the closest thing recalled
+export const COVERAGE_WORDS_BAR = 0.25;
+export const MATCH_SAMPLE = 12;        // a local model answering is slow; honesty about that beats a big number
+export const MATCH_BAR = 0.6;
+// Every text in one room is about the same handful of subjects, so any two pieces of it read as
+// similar to an embedder. Measured against a bar alone, the first run of coverage scored thirty
+// out of thirty — a test that cannot fail measures nothing. So each case is also measured against
+// a control: the same question scored against another case's material. To count, what the archive
+// actually handed over has to beat what it would have handed over for something else.
+export const CONTROL_MARGIN = 0.05;
+export const MIN_ASK = 40;             // shorter than this is "ok", "sí", "dale": nothing to answer
+export const PASS = { coverage: 0.7, match: 0.7 };
+
+const rare = (text) => new Set(String(text ?? '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').match(/[a-z0-9][a-z0-9_/.-]{3,}/g) ?? []);
+
+// How close two pieces of text are when there is nothing to embed them with. Not a semantic
+// score and never reported as one: the share of the answer's own uncommon words that were
+// already in front of the room.
+export function wordScore(reference, candidate) {
+  const want = rare(reference);
+  const have = rare(candidate);
+  if (!want.size || !have.size) return 0;
+  let shared = 0;
+  for (const word of want) if (have.has(word)) shared += 1;
+  return shared / want.size;
+}
+
+export function cosine(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dot = 0;
+  let left = 0;
+  let right = 0;
+  for (let i = 0; i < a.length; i += 1) { dot += a[i] * b[i]; left += a[i] * a[i]; right += b[i] * b[i]; }
+  return left && right ? dot / Math.sqrt(left * right) : 0;
+}
+
+// Every human message in the ledger that actually got an answer, oldest first. Ghost turns never
+// happened as far as the archive is concerned, and a one-word message has no answer to find.
+export function exchanges(events = [], { minAsk = MIN_ASK, local = ['madre'] } = {}) {
+  const asked = new Map();
+  const out = [];
+  for (const event of events) {
+    if (!event || event.ghost) continue;
+    const payload = event.payload ?? {};
+    if (event.type !== 'message.created') continue;
+    if (payload.role === 'user' && payload.sender === 'you') {
+      const text = String(payload.text ?? '').trim();
+      if (text.length >= minAsk && !text.startsWith('/')) asked.set(payload.messageId, { sequence: event.sequence, text, target: payload.target });
+      continue;
+    }
+    if (payload.role !== 'assistant') continue;
+    const parent = payload.parentMessageId ?? payload.replyTo ?? payload.inReplyTo ?? null;
+    const question = parent ? asked.get(parent) : null;
+    if (!question) continue;
+    const answer = String(payload.text ?? '').trim();
+    if (answer.length < minAsk) continue;
+    asked.delete(parent);
+    out.push({ sequence: question.sequence, answerSequence: event.sequence, asked: question.text, answered: answer, agent: payload.sender, local: local.includes(payload.sender) });
+  }
+  return out;
+}
+
+// The control partner for each case: far enough down the list that it is a different day and a
+// different subject, and deterministic so a run can be repeated.
+export const controlOf = (index, n) => (n > 1 ? (index + Math.floor(n / 2)) % n : 0);
+
+// A sample spread across the whole ledger rather than taken off the end: fifty questions from one
+// afternoon test one afternoon.
+export function spread(items, size) {
+  if (items.length <= size) return [...items];
+  const step = items.length / size;
+  return Array.from({ length: size }, (_, i) => items[Math.floor(i * step)]);
+}
+
+/* ---------- 1 · COVERAGE ---------- */
+
+// `recall(text, beforeSequence)` hands back what the room would have been given at that moment.
+// `embed(texts)` is optional; without it the scoring says so and uses words.
+export async function coverageExam({ events = [], recall, embed = null, sample = COVERAGE_SAMPLE, bar = null } = {}) {
+  const all = exchanges(events);
+  const cases = spread(all, sample);
+  if (!cases.length) return { id: 'coverage', ran: false, says: t('No exchange in this room is long enough to test with yet.') };
+  const found = [];
+  for (const one of cases) {
+    const held = await recall(one.asked, one.sequence);
+    found.push(held.map((item) => String(item ?? '')).filter(Boolean));
+  }
+  const method = embed ? 'meaning' : 'words';
+  const used = bar ?? (embed ? COVERAGE_BAR : COVERAGE_WORDS_BAR);
+  const scores = [];
+  const controls = [];
+  if (embed) {
+    // One batch for the answers and one for everything that was recalled, so a remote embedder
+    // is asked twice and not sixty times.
+    const flat = found.flat();
+    const vectors = await embed([...cases.map((one) => one.answered), ...flat]);
+    const answers = vectors.slice(0, cases.length);
+    const rest = vectors.slice(cases.length);
+    const sets = [];
+    let at = 0;
+    for (const items of found) { sets.push(rest.slice(at, at + items.length)); at += items.length; }
+    for (let i = 0; i < cases.length; i += 1) {
+      const best = (set) => set.reduce((top, vector) => Math.max(top, cosine(answers[i], vector)), 0);
+      scores.push(best(sets[i]));
+      controls.push(best(sets[controlOf(i, cases.length)]));
+    }
+  } else {
+    for (let i = 0; i < cases.length; i += 1) {
+      const best = (set) => set.reduce((top, text) => Math.max(top, wordScore(cases[i].answered, text)), 0);
+      scores.push(best(found[i]));
+      controls.push(best(found[controlOf(i, cases.length)]));
+    }
+  }
+  // To count, the archive must have handed over this answer's material, and material it would
+  // not have handed over for a different question. With a single case there is nothing to
+  // compare against, and the result says so rather than pretending otherwise.
+  const controlled = cases.length > 1;
+  const hit = scores.map((score, i) => score >= used && (!controlled || score > controls[i] + CONTROL_MARGIN));
+  const hits = hit.filter(Boolean).length;
+  const rate = Number((hits / cases.length).toFixed(3));
+  const mean = (list) => Number((list.reduce((sum, value) => sum + value, 0) / list.length).toFixed(3));
+  return {
+    id: 'coverage', ran: true, at: new Date().toISOString(), n: cases.length, hits, rate, method, bar: used,
+    mean: mean(scores), control: controlled ? mean(controls) : null,
+    passed: rate >= PASS.coverage,
+    says: t('{hits} of {n} questions this room actually asked had their answer already in the archive, matched by {method}{control}.', { hits, n: cases.length, method: t(method), control: controlled ? t(' and against a control') : '' }),
+  };
+}
+
+/* ---------- 2 · CONSISTENCY ---------- */
+
+// Pure. Contradictions still open, how much has been taken out of circulation, and whether the
+// room is filing aberrations more often lately than it used to.
+export function consistencyExam({ findings = [], notes = [], now = Date.now() } = {}) {
+  const standing = notes.filter((note) => note && note.kind !== 'aberration' && !note.refutedBy);
+  const refuted = notes.filter((note) => note && note.refutedBy).length;
+  const aberrations = notes.filter((note) => note && note.kind === 'aberration');
+  const open = findings.filter((finding) => !finding?.settled).length;
+  const times = aberrations.map((note) => Date.parse(note.created)).filter((at) => Number.isFinite(at)).sort((a, b) => a - b);
+  const written = notes.map((note) => Date.parse(note.created)).filter((at) => Number.isFinite(at)).sort((a, b) => a - b);
+  let trend = null;
+  if (written.length > 4 && times.length) {
+    const middle = written[Math.floor(written.length / 2)];
+    const before = times.filter((at) => at < middle).length;
+    const after = times.length - before;
+    trend = after === before ? 'level' : after < before ? 'falling' : 'rising';
+  }
+  const passed = open === 0 && trend !== 'rising';
+  return {
+    id: 'consistency', ran: true, at: new Date(now).toISOString(),
+    open, refuted, standing: standing.length, aberrations: aberrations.length, trend,
+    passed,
+    says: open
+      ? t('EYECAT is holding {n} contradictions nobody has settled.', { n: open })
+      : trend === 'rising'
+        ? t('Nothing is open, but aberrations are being filed more often lately than they used to be.')
+        : t('Nothing contradicts anything: {standing} notes stand, {refuted} were taken out of circulation.', { standing: standing.length, refuted }),
+  };
+}
+
+/* ---------- 3 · MATCH ---------- */
+
+// `ask(question)` is the local model with this archive behind it. `embed` is needed: comparing
+// two answers by their words rewards copying the question back.
+export async function matchExam({ events = [], ask, embed, sample = MATCH_SAMPLE, bar = MATCH_BAR, onProgress = () => {}, stop = () => false } = {}) {
+  if (!embed) return { id: 'match', ran: false, says: t('This test needs embeddings: two answers cannot be compared by their words alone.') };
+  const all = exchanges(events).filter((one) => !one.local);   // a model is not tested against itself
+  const cases = spread(all, sample);
+  if (!cases.length) return { id: 'match', ran: false, says: t('No question in this room was answered by an agent other than the local one yet.') };
+  const mine = [];
+  for (const [index, one] of cases.entries()) {
+    if (stop()) return { id: 'match', ran: false, stopped: true, says: t('Stopped after {index} of {n}.', { index, n: cases.length }) };
+    onProgress({ done: index, total: cases.length });
+    try { mine.push(String((await ask(one.asked)) ?? '')); } catch { mine.push(''); }
+  }
+  onProgress({ done: cases.length, total: cases.length });
+  const vectors = await embed([...cases.map((one) => one.answered), ...mine]);
+  const theirs = vectors.slice(0, cases.length);
+  const ours = vectors.slice(cases.length);
+  const scores = cases.map((_, i) => (mine[i] ? cosine(theirs[i], ours[i]) : 0));
+  // Same control as coverage: an answer that is merely about the same project as every other
+  // answer in the room has not landed anywhere.
+  const controlled = cases.length > 1;
+  const controls = cases.map((_, i) => (mine[i] && controlled ? cosine(ours[i], theirs[controlOf(i, cases.length)]) : 0));
+  const matched = scores.filter((score, i) => score >= bar && (!controlled || score > controls[i] + CONTROL_MARGIN)).length;
+  const rate = Number((matched / cases.length).toFixed(3));
+  const mean = (list) => Number((list.reduce((sum, value) => sum + value, 0) / list.length).toFixed(3));
+  return {
+    id: 'match', ran: true, at: new Date().toISOString(), n: cases.length, matched, rate, mean: mean(scores), control: controlled ? mean(controls) : null, bar,
+    passed: rate >= PASS.match,
+    says: t('On {matched} of {n} real questions the local model landed where the agent of the day landed{control}.', { matched, n: cases.length, control: controlled ? t(', and not merely in the same project') : '' }),
+  };
+}
+
+// A reading that was taken months ago is still read today, and the room may have changed its
+// language since. The numbers are what was measured; the sentence is only how they are said, so
+// it is said again, now, from the fields that were stored. A stored result that predates this
+// keeps whatever sentence it was written with.
+export function saysFor(result) {
+  if (!result?.ran) return result?.says ?? null;
+  if (result.id === 'coverage' && Number.isFinite(result.hits)) {
+    return t('{hits} of {n} questions this room actually asked had their answer already in the archive, matched by {method}{control}.',
+      { hits: result.hits, n: result.n, method: t(result.method ?? 'words'), control: result.control === null || result.control === undefined ? '' : t(' and against a control') });
+  }
+  if (result.id === 'match' && Number.isFinite(result.matched)) {
+    return t('On {matched} of {n} real questions the local model landed where the agent of the day landed{control}.',
+      { matched: result.matched, n: result.n, control: result.control === null || result.control === undefined ? '' : t(', and not merely in the same project') });
+  }
+  if (result.id === 'consistency' && Number.isFinite(result.open)) {
+    return result.open
+      ? t('EYECAT is holding {n} contradictions nobody has settled.', { n: result.open })
+      : result.trend === 'rising'
+        ? t('Nothing is open, but aberrations are being filed more often lately than they used to be.')
+        : t('Nothing contradicts anything: {standing} notes stand, {refuted} were taken out of circulation.', { standing: result.standing, refuted: result.refuted });
+  }
+  return result.says ?? null;
+}

package/src/extensions.mjs

@@ -8,7 +8,7 @@ export const EXTENSIONS = MODULES;
 export const AHP = moduleById('ahp');
 export const IMAGE_STUDIO = moduleById('image-studio');
 export const GIT_PULSE = moduleById('git-pulse');
-export const ASHCODE = moduleById('ashcode');
+export const ASH = moduleById('ash');
 export const RIPLEY = moduleById('ripley');
 export const OLLAMA = moduleById('ollama');
 export const extensionById = moduleById;
@@ -26,9 +26,10 @@ export async function listExtensions({ projectRoot, agents = [], config = {}, im
 
 // Runs one installer inside the project, streaming output lines. `runner`
 // lets tests substitute the real installer with a local script.
+// `npm` and other Node CLIs are .cmd shims on Windows, which cannot be spawned directly.
 export function runInstaller({ command, args, projectRoot, onLine, timeoutMs = 600000, heartbeatMs = 8000, env = process.env }) {
   return new Promise((resolve) => {
-    const child = spawn(command, args, { cwd: projectRoot, env: { ...env, NO_COLOR: '1', CI: '1' }, stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawn(command, args, { cwd: projectRoot, env: { ...env, NO_COLOR: '1', CI: '1' }, stdio: ['ignore', 'pipe', 'pipe'], shell: process.platform === 'win32', windowsHide: true });
     const started = Date.now();
     let lastOutput = started;
     // Installers go quiet for long stretches (npm install, git status); say so.