@jossuealcala/madre 0.3.3 → 0.4.0

package/src/asking.mjs

@@ -0,0 +1,128 @@
+// What the room should ask next.
+//
+// The maturity reading says where the archive is thin; it does not say what to do about it on a
+// Tuesday afternoon. This does. It reads the archive the room already has and writes the handful
+// of questions whose answers are missing — and it writes them from the archive itself, word for
+// word, never inventing a subject the room has not raised.
+//
+// Three wells, because there are three different kinds of hole:
+//
+//   · questions the archivist already recorded as open, which nobody ever went back to. This is
+//     the archive saying out loud what it does not know.
+//   · cold memories: nothing has ever reached for them. Asking is the only way to find out
+//     whether they are noise or simply never came up, and it is the honest alternative to
+//     forgetting something that was never given a chance.
+//   · a kind of note the archive is short of. A room with forty facts and two decisions is
+//     recording what is true and not what was chosen, and no amount of use fixes that on its own.
+//
+// Nothing here spends a turn or writes anything. It hands the human a question; sending it is
+// theirs, as is ignoring it.
+
+export const ASK_LIMIT = 6;
+export const THIN_SHARE = 0.12;      // a kind under this much of the archive is thin
+export const THIN_FLOOR = 20;        // and only once there is enough archive for shares to mean anything
+
+// Open questions are deliberately not here. An archive short of them is not a problem that
+// asking for more questions solves; what is wanted is answers, and those come from the first
+// well. Only the three kinds a thin archive is genuinely poorer for.
+const KIND_ASK = {
+  decision: 'What have we decided lately that is not written down anywhere?',
+  preference: 'What do I keep asking for that nobody has written down as a preference?',
+  fact: 'What is true about this project that a new agent would have to be told?',
+};
+
+const KIND_WHY = {
+  decision: 'decisions',
+  preference: 'preferences',
+  fact: 'facts',
+};
+
+const quote = (text) => `"${String(text ?? '').replace(/\s+/g, ' ').trim()}"`;
+
+// Two ways of asking the same thing are one question. The archivist writes on several passes and
+// sometimes records a question twice in slightly different words; offering both of them back is
+// how a list of six turns into a list of four.
+const words = (text) => new Set(String(text ?? '').toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').match(/[a-z0-9]{3,}/g) ?? []);
+export function sameQuestion(a, b, floor = 0.72) {
+  const one = words(a);
+  const two = words(b);
+  if (!one.size || !two.size) return false;
+  let shared = 0;
+  for (const word of one) if (two.has(word)) shared += 1;
+  // Against the union, not the shorter of the two: "who owns the billing" and "who owns the
+  // migration" are three words apiece in common and are not the same question at all. But one
+  // question wholly inside another is the same question said at more length, and the union
+  // punishes exactly that, so containment is asked separately and asked strictly.
+  const inside = shared / Math.min(one.size, two.size);
+  return shared / (one.size + two.size - shared) >= floor || inside >= 0.9;
+}
+
+// The questions, most worth asking first, each one traceable to what raised it.
+export function questionsFor({ notes = [], cold = new Map(), dismissed = [], limit = ASK_LIMIT } = {}) {
+  const skip = new Set(dismissed ?? []);
+  const standing = notes.filter((note) => note && note.kind !== 'aberration' && !note.refutedBy);
+  const asks = { open: [], cold: [], thin: [] };
+
+  // What the archive itself recorded as open. One the room keeps reaching for and still has no
+  // answer to is the most worth asking of anything here.
+  for (const note of standing.filter((note) => note.kind === 'question')) {
+    asks.open.push({
+      id: `open:${note.id}`,
+      source: 'open',
+      memoryId: note.id,
+      text: note.text,
+      why: Number(note.recalled ?? 0) > 0
+        ? `the room has carried this open question into ${note.recalled} turn${Number(note.recalled) === 1 ? '' : 's'} and still has no answer`
+        : 'the archivist recorded this as open and nothing has answered it',
+      weight: 100 + Number(note.recalled ?? 0),
+    });
+  }
+
+  // What nothing has ever reached for. Asking settles it either way.
+  for (const note of standing) {
+    const chill = cold.get?.(note.id) ?? null;
+    if (!chill) continue;
+    asks.cold.push({
+      id: `cold:${note.id}`,
+      source: 'cold',
+      memoryId: note.id,
+      text: `Is this still true, and does it still matter here? ${quote(note.text)}`,
+      why: `the archive has been opened ${chill.chances} times since this was written and never once carried it`,
+      weight: 50 + chill.chances,
+    });
+  }
+
+  // What the archive is short of. Not a memory: a shape.
+  if (standing.length >= THIN_FLOOR) {
+    const counts = new Map();
+    for (const note of standing) counts.set(note.kind, (counts.get(note.kind) ?? 0) + 1);
+    for (const kind of Object.keys(KIND_ASK)) {
+      const count = counts.get(kind) ?? 0;
+      if (count / standing.length >= THIN_SHARE) continue;
+      asks.thin.push({
+        id: `thin:${kind}`,
+        source: 'thin',
+        memoryId: null,
+        text: KIND_ASK[kind],
+        why: `${count} of ${standing.length} notes are ${KIND_WHY[kind]}`,
+        weight: 40 - count,
+      });
+    }
+  }
+
+  for (const list of Object.values(asks)) list.sort((a, b) => b.weight - a.weight);
+  // Taken in turn rather than by weight alone, so one full well cannot be the whole list: six
+  // variations on the same cold note is not a plan, it is a loop.
+  const order = ['open', 'cold', 'thin'];
+  const chosen = [];
+  while (chosen.length < limit && order.some((well) => asks[well].length)) {
+    for (const well of order) {
+      if (chosen.length >= limit) break;
+      const next = asks[well].shift();
+      if (!next || skip.has(next.id)) continue;
+      if (chosen.some((already) => sameQuestion(already.text, next.text))) continue;
+      chosen.push(next);
+    }
+  }
+  return chosen;
+}

package/src/auth-probe.mjs

@@ -1,4 +1,5 @@
 import { execFile } from 'node:child_process';
+import { t } from './i18n.mjs';
 import { access, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -78,7 +79,9 @@ export async function probeGemini({ env = process.env } = {}) {
     settings = null;
   }
   const hasOauth = await exists(join(dir, 'oauth_creds.json'));
-  const hasApiKey = Boolean(env.GEMINI_API_KEY || env.GOOGLE_API_KEY) || await geminiHasKeychainKey();
+  // The CLI reads ~/.gemini/.env as well as the environment and the system keychain.
+  const dotEnv = await readFile(join(dir, '.env'), 'utf8').catch(() => '');
+  const hasApiKey = Boolean(env.GEMINI_API_KEY || env.GOOGLE_API_KEY) || /^\s*(GEMINI_API_KEY|GOOGLE_API_KEY)\s*=\s*\S/m.test(dotEnv) || await geminiHasKeychainKey();
   return geminiAuthState({ settings, hasOauth, hasApiKey });
 }
 
@@ -90,26 +93,80 @@ export const AGENT_SETUP = {
     login: ['login'],
     loginNote: 'Opens your browser to sign in with ChatGPT.',
     browser: true,
+    // What a newcomer needs to know before choosing this door: which account, and whether
+    // there is a way in without paying. `paid: null` means it depends on the provider you pick.
+    vendor: 'OpenAI',
+    account: 'Signs in with a ChatGPT account. An OpenAI API key works too.',
+    paid: true,
   },
   claude: {
     install: ['npm install -g @anthropic-ai/claude-code', 'or: brew install --cask claude-code'],
     login: ['auth', 'login'],
     loginNote: 'Opens your browser to sign in with your Claude account.',
     browser: true,
+    vendor: 'Anthropic',
+    account: 'Signs in with a Claude account. An Anthropic API key works too.',
+    paid: true,
   },
   gemini: {
     install: ['npm install -g @google/gemini-cli'],
     login: [],
     loginNote: 'Gemini signs in from its own prompt: run `gemini`, type /auth, pick "Use Gemini API key" (get one at aistudio.google.com/app/apikey) or Google login.',
     interactive: true,
+    vendor: 'Google',
+    account: 'Signs in with a Google account and has a free tier. A Gemini API key from AI Studio works too.',
+    paid: false,
   },
   opencode: {
     install: ['brew install opencode', 'or: npm install -g opencode-ai'],
     login: ['auth', 'login'],
     loginNote: 'Pick a provider and paste its key or complete its OAuth flow.',
+    vendor: 'OpenCode',
+    account: 'Brings no model of its own: you point it at a provider you already use, in the cloud or on this computer.',
+    paid: null,
   },
 };
 
+// Installing a CLI from the room itself. npm is the common denominator: every one of these
+// ships an npm package, and whoever reached MADRE through npx already has npm on the machine.
+// The prose in AGENT_SETUP.install stays as the alternatives a human may prefer.
+export const AGENT_PACKAGE = {
+  codex: '@openai/codex',
+  claude: '@anthropic-ai/claude-code',
+  gemini: '@google/gemini-cli',
+  opencode: 'opencode-ai',
+};
+// One honest line per agent about the account it needs, for the bridge and for CONNECTIONS.
+// Which agents take a pasted key instead of a browser flow.
+export const TAKES_KEY = new Set(['gemini', 'opencode']);
+
+export function accountNoteFor(id) {
+  // Said in the room's language when it is asked for, not when this file is imported.
+  if (id === 'madre') return { account: t("Free and local through Ollama: no account, no tokens. It answers from the room's memory."), paid: false, vendor: 'MADRE' };
+  const setup = AGENT_SETUP[id];
+  return setup ? { account: t(setup.account), paid: setup.paid, vendor: setup.vendor } : null;
+}
+
+// npm cannot always write to the system folders: with Node installed from its own installer,
+// a global install asks for an administrator. Rather than send the human to a terminal with
+// sudo, MADRE installs into a folder of its own and finds the CLI there.
+export const NEEDS_ADMIN = /EACCES|EPERM|permission denied|Missing write access|operation not permitted|npm ERR! code E401.*sudo|need (?:root|sudo)/i;
+export const looksLikeAdminProblem = (output) => NEEDS_ADMIN.test(String(output ?? ''));
+
+export function installPlanFor(agent, { prefix = null } = {}) {
+  const name = AGENT_PACKAGE[agent?.id];
+  if (!name) return null;
+  return {
+    package: name,
+    command: 'npm',
+    args: ['install', '-g', name, '--no-fund', '--no-audit'],
+    display: `npm install -g ${name}`,
+    // The same install, into MADRE's own prefix: no administrator, nothing outside ~/.pulse.
+    fallback: prefix ? { command: 'npm', args: ['install', '-g', name, '--prefix', prefix, '--no-fund', '--no-audit'], display: `npm install -g ${name} --prefix ${prefix}` } : null,
+    alternatives: (AGENT_SETUP[agent.id]?.install ?? []).slice(1),
+  };
+}
+
 // How the room can (re)connect an agent. Codex and Claude sign in with a
 // browser flow their own CLI drives, so the server can run them and stream the
 // URL; Gemini and OpenCode need their interactive prompt, so the user gets the

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

@@ -52,6 +52,12 @@ export const COMMANDS = [
         // 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);

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,