@jossuealcala/madre 0.3.3 → 0.4.1

package/src/adapters/claude.mjs

@@ -101,8 +101,9 @@ export function parseClaudeOutput(output) {
   }
 }
 
-export function invokeClaude({ executable, projectRoot, prompt, timeoutMs = 120000, signal, model = null, attachments = [], lease = null, scopes = null, imageStudio = null, memoryServer = null, mcpServers = [] }) {
+export function invokeClaude({ executable, projectRoot, prompt, timeoutMs = 120000, signal, model = null, attachments = [], lease = null, scopes = null, imageStudio = null, memoryServer = null, mcpServers = [], onProgress = null }) {
   return runReadonlyProcess({
+    onProgress: onProgress ? (out) => onProgress({ chars: (() => { try { return String(JSON.parse(out)?.result ?? '').length; } catch { return 0; } })() }) : null,
     executable,
     args: buildClaudeArgs({ prompt, model, attachmentsDir: attachments[0]?.dir ?? null, lease, scopes, imageStudio, memoryServer, mcpServers }),
     cwd: projectRoot,

package/src/adapters/codex.mjs

@@ -73,8 +73,9 @@ export function parseCodexOutput(output) {
   return { text: text.trim(), usage };
 }
 
-export function invokeCodex({ executable, projectRoot, prompt, timeoutMs = 120000, signal, model = null, attachments = [], lease = null, scopes = null, memoryServer = null, mcpServers = [] }) {
+export function invokeCodex({ executable, projectRoot, prompt, timeoutMs = 120000, signal, model = null, attachments = [], lease = null, scopes = null, memoryServer = null, mcpServers = [], onProgress = null }) {
   return runReadonlyProcess({
+    onProgress: onProgress ? (out) => onProgress({ chars: parseCodexOutput(out).text.length }) : null,
     executable,
     args: buildCodexArgs({ projectRoot, prompt, model, attachments, lease, scopes, memoryServer, mcpServers }),
     cwd: lease ? lease.outDir : projectRoot,

package/src/adapters/gemini.mjs

@@ -1,4 +1,5 @@
 import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { t } from '../i18n.mjs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { runReadonlyProcess } from './process.mjs';
@@ -215,7 +216,7 @@ export function parseGeminiOutput(output) {
 export async function cleanupRuntimeRoot(runtimeRoot, { attempts = 6, delayMs = 250 } = {}) {
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
     try {
-      await rm(runtimeRoot, { recursive: true, force: true });
+      await rm(runtimeRoot, { recursive: true, force: true, maxRetries: 6, retryDelay: 60 });
       return true;
     } catch (error) {
       if (attempt === attempts) {
@@ -234,21 +235,21 @@ export async function cleanupRuntimeRoot(runtimeRoot, { attempts = 6, delayMs =
 export function diagnoseGeminiStderr(stderr) {
   const text = String(stderr ?? '');
   if (/prepayment credits are depleted/i.test(text)) {
-    return { code: 'CREDITS_DEPLETED', message: 'Google says the AI Studio project behind this Gemini key has no prepaid credits left; every request is refused (HTTP 429) until it is topped up.', hint: 'Add credits at https://ai.studio/projects, or switch the Gemini CLI to another key.' };
+    return { code: 'CREDITS_DEPLETED', message: t('Google says the AI Studio project behind this Gemini key has no prepaid credits left; every request is refused (HTTP 429) until it is topped up.'), hint: t('Add credits at https://ai.studio/projects, or switch the Gemini CLI to another key.') };
   }
   if (/status:\s*429|\b429\b|RESOURCE_EXHAUSTED|rate ?limit|quota exceeded/i.test(text)) {
     const router = /ClassifierStrategy|\.route\b/.test(text);
     return {
       code: 'RATE_LIMITED',
       message: `Google is rate-limiting this Gemini key (HTTP 429)${router ? ' while its "auto" router picked a model' : ''}; the CLI kept retrying with backoff.`,
-      hint: 'Wait a minute, or pick an explicit model such as gemini-3-flash-preview to skip the router; check the key\'s quota at aistudio.google.com.',
+      hint: t('Wait a minute, or pick an explicit model such as gemini-3-flash-preview to skip the router; check the key\'s quota at aistudio.google.com.'),
     };
   }
   if (/status:?\s*503|UNAVAILABLE|high demand/i.test(text)) {
-    return { code: 'UNAVAILABLE', message: 'Google reported the model as unavailable (HTTP 503) and the CLI kept retrying.', hint: 'Try again shortly or choose another model.' };
+    return { code: 'UNAVAILABLE', message: t('Google reported the model as unavailable (HTTP 503) and the CLI kept retrying.'), hint: t('Try again shortly or choose another model.') };
   }
   if (/status:\s*40[13]|PERMISSION_DENIED|API key not valid|IneligibleTierError/i.test(text)) {
-    return { code: 'AUTH', message: 'Google rejected the Gemini credentials.', hint: 'Run `gemini` and use /auth, or check GEMINI_API_KEY.' };
+    return { code: 'AUTH', message: t('Google rejected the Gemini credentials.'), hint: t('Run `gemini` and use /auth, or check GEMINI_API_KEY.') };
   }
   return null;
 }

package/src/adapters/opencode.mjs

@@ -154,8 +154,9 @@ export function parseOpenCodeOutput(output) {
   return { text: text.join('').trim(), usage, ...(error ? { error } : {}) };
 }
 
-export function invokeOpenCode({ executable, projectRoot, prompt, timeoutMs = 120000, signal, model = null, attachments = [], lease = null, scopes = null, imageStudio = null, memoryServer = null, mcpServers = [] }) {
+export function invokeOpenCode({ executable, projectRoot, prompt, timeoutMs = 120000, signal, model = null, attachments = [], lease = null, scopes = null, imageStudio = null, memoryServer = null, mcpServers = [], onProgress = null }) {
   return runReadonlyProcess({
+    onProgress: onProgress ? (out) => onProgress({ chars: out.length }) : null,
     executable,
     args: buildOpenCodeArgs({ projectRoot, prompt, attachments, ...(model ? { model } : {}) }),
     cwd: projectRoot,

package/src/adapters/process.mjs

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { t } from '../i18n.mjs';
 
 function signalProcessGroup(child, signal) {
   if (!child.pid) return false;
@@ -24,6 +25,36 @@ export function terminateProcessTree(child, { graceMs = 2000 } = {}) {
   child.once('close', () => clearTimeout(escalation));
 }
 
+// A number is not a reason. A process that was signalled reports it two ways — node hands the
+// signal itself when it killed the child, and a CLI that handles SIGTERM exits 128+n on its own —
+// and both used to surface as a bare `exited with code 143`, which reads like a crash and is not
+// one: something STOPPED it. Naming the signal is the difference between looking for a bug in the
+// agent and looking for whoever pulled the plug.
+const SIGNAL_MEANING = {
+  SIGTERM: 'was stopped (SIGTERM) — something asked it to quit: STOP ALL, a timeout, or the room shutting down',
+  SIGKILL: 'was killed outright (SIGKILL) — usually this machine running out of memory',
+  SIGINT: 'was interrupted (SIGINT) — a Ctrl+C reached it',
+  SIGHUP: 'lost its terminal (SIGHUP)',
+};
+function endedBy(code, closedBy) {
+  const name = closedBy ?? (Number.isInteger(code) && code > 128 ? Object.keys(SIGNAL_MEANING).find((key) => code === 128 + { SIGHUP: 1, SIGINT: 2, SIGKILL: 9, SIGTERM: 15 }[key]) : null);
+  if (name && SIGNAL_MEANING[name]) return `${SIGNAL_MEANING[name]}.`;
+  if (name) return `ended on ${name}.`;
+  return `exited with code ${code}.`;
+}
+
+// One explanation for a process that never ran, whichever way spawn refused. ENOENT is the
+// ambiguous one: node says it for a missing binary and for a missing working directory alike,
+// so the sentence names both instead of guessing which.
+function couldNotStart(error, { label, executable, cwd }) {
+  if (error?.code === 'ENOENT') {
+    error.message = `${label} could not start: ${error.message}. Check that the project folder ${cwd} exists and that ${executable} is still installed — a CLI that updates itself can move out from under a room that is already open, and reopening it finds the new one.`;
+  } else if (error && !String(error.message ?? '').startsWith(label)) {
+    error.message = `${label} could not start: ${error.message}`;
+  }
+  return error;
+}
+
 export function runReadonlyProcess({
   executable,
   args,
@@ -41,18 +72,33 @@ export function runReadonlyProcess({
   label,
   parse,
   signal,
+  // Called as output arrives, with everything received so far. The adapter decides what that
+  // means: a CLI that streams its answer can be read as it writes, one that hands over a single
+  // blob at the end will simply say nothing until then, and saying nothing is the honest answer.
+  onProgress = null,
 }) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
-      reject(new Error(`${label} was interrupted before it started: ${typeof signal.reason === 'string' ? signal.reason : 'MADRE is shutting down'}.`));
+      reject(new Error(t('{label} was interrupted before it started: {why}.', { label, why: typeof signal.reason === 'string' ? signal.reason : t('MADRE is shutting down') })));
+      return;
+    }
+    // spawn fails two ways, and only one of them used to be explained. The asynchronous one
+    // raises 'error' on the child; the synchronous one throws right here, before there is a
+    // child to listen to — a binary replaced underneath a running room by an app that updates
+    // itself, an option the platform refuses. That path handed the human a bare `spawn … ENOENT`
+    // with nothing to act on, which is how a self-updating CLI looked like a broken product.
+    let child;
+    try {
+      child = spawn(executable, args, {
+        cwd,
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: process.platform !== 'win32',
+      });
+    } catch (error) {
+      reject(couldNotStart(error, { label, executable, cwd }));
       return;
     }
-    const child = spawn(executable, args, {
-      cwd,
-      env,
-      stdio: ['ignore', 'pipe', 'pipe'],
-      detached: process.platform !== 'win32',
-    });
     let stdout = '';
     let stderr = '';
     let settled = false;
@@ -77,8 +123,8 @@ export function runReadonlyProcess({
 
     const onAbort = () => {
       terminateProcessTree(child, { graceMs: killGraceMs });
-      const reason = typeof signal?.reason === 'string' ? signal.reason : 'MADRE is shutting down';
-      finish(() => reject(new Error(`${label} was interrupted: ${reason}.`)));
+      const reason = typeof signal?.reason === 'string' ? signal.reason : t('MADRE is shutting down');
+      finish(() => reject(new Error(t('{label} was interrupted: {why}.', { label, why: reason }))));
     };
     const finish = (operation) => {
       if (settled) return;
@@ -92,7 +138,7 @@ export function runReadonlyProcess({
       terminateProcessTree(child, { graceMs: killGraceMs });
       // The last thing the agent said is usually the reason it was slow.
       const lastLine = `${stderr}\n${stdout}`.split('\n').map((line) => line.trim()).filter(Boolean).at(-1);
-      const error = new Error(`${label} did not respond before the timeout (${Math.round(timeoutMs / 1000)}s).${lastLine ? ` Last output: ${lastLine.slice(0, 200)}` : ''}`);
+      const error = new Error(t('{label} did not respond before the timeout ({seconds}s).', { label, seconds: Math.round(timeoutMs / 1000) }) + (lastLine ? t(' Last output: {output}', { output: lastLine.slice(0, 200) }) : ''));
       error.code = 'TIMEOUT';
       error.partialOutput = stdout;
       error.partialStderr = stderr.slice(-2000);
@@ -103,7 +149,14 @@ export function runReadonlyProcess({
     // Only complete stdout lines count as activity: a CLI's stderr spinner or
     // progress noise must not keep a silent model alive past the idle limit.
     // Blank keep-alive lines are not activity either.
-    child.stdout.on('data', (chunk) => { stdout += chunk; if (/\S/.test(String(chunk)) && String(chunk).includes('\n')) lastActivity = Date.now(); });
+    let toldAt = 0;
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+      if (/\S/.test(String(chunk)) && String(chunk).includes('\n')) lastActivity = Date.now();
+      // Throttled: a chatty CLI can produce hundreds of chunks a second and nobody needs to see
+      // a number move that fast.
+      if (onProgress && Date.now() - toldAt > 400) { toldAt = Date.now(); try { onProgress(stdout); } catch { /* a meter must never break a turn */ } }
+    });
     child.stderr.on('data', (chunk) => {
       stderr += chunk;
       if (!watchStderr || settled) return;
@@ -116,17 +169,23 @@ export function runReadonlyProcess({
       finish(() => reject(verdict));
     });
     armIdle();
-    child.on('error', (error) => finish(() => {
-      // spawn reports ENOENT for a missing cwd as well as a missing binary.
-      if (error.code === 'ENOENT') {
-        error.message = `${label} could not start: ${error.message}. Check that the project folder ${cwd} exists and that ${executable} is still installed.`;
-      }
-      reject(error);
-    }));
-    child.on('close', (code) => finish(() => {
+    child.on('error', (error) => finish(() => reject(couldNotStart(error, { label, executable, cwd }))));
+    child.on('close', (code, closedBy) => finish(() => {
       const response = parse(stdout);
       if (code === 0 && response.text) return resolve(response);
-      reject(new Error(stderr.trim() || response.error || `${label} exited with code ${code}.`));
+      // What happened first, what the CLI printed second, and never one dressed as the other.
+      // This used to be `stderr.trim() || …`, so anything a CLI wrote on the way out became the
+      // reason: a notice about an unrelated setting, a line saying it was reading stdin. The
+      // facts that actually diagnose the turn — the exit code, or a clean exit with nothing to
+      // show — were discarded by the `||` and never reached the human. A warning is not a cause.
+      const printed = stderr.trim();
+      const why = response.error ?? (code === 0
+        ? `${label} exited cleanly without an answer.`
+        : `${label} ${endedBy(code, closedBy)}`);
+      const error = new Error(printed ? `${why}\n\n${label} printed:\n${printed.slice(-600)}` : why);
+      error.partialStderr = printed.slice(-2000);
+      error.exitCode = code;
+      reject(error);
     }));
   });
 }

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