@jossuealcala/madre 0.3.2 → 0.4.0

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';
@@ -27,7 +28,7 @@ export const geminiCredentialFiles = ['oauth_creds.json', 'google_accounts.json'
 // whose file_path argument starts with the lease directory. Plan mode would
 // block every write regardless of policy, so a lease uses approval "default":
 // headless Gemini cannot prompt, so anything the policy does not allow fails.
-export function geminiLeasePolicy(outDir, { control = false, create = false } = {}) {
+export function geminiLeasePolicy(outDir, { control = false, create = false, airlock = false } = {}) {
   const escaped = outDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
   // The whole project is the lease in #2 and #3: MADRE's zones stay out of reach.
   const forbidden = control || create ? `
@@ -40,7 +41,15 @@ interactive = false
 ` : '';
   // CREATE (#2) adds files: write_file only; CONTROL (#3) also replaces and edits.
   const tools = create ? '["write_file"]' : '["write_file", "replace", "edit"]';
-  return `${geminiReadonlyPolicy}
+  // AIRLOCK (#4): commands too; the forbidden-zone rule above still outranks this one.
+  const commands = airlock ? `
+[[rule]]
+toolName = "run_shell_command"
+decision = "allow"
+priority = 1000
+interactive = false
+` : '';
+  return `${geminiReadonlyPolicy}${commands}
 [[rule]]
 toolName = ${tools}
 argsPattern = '"file_path"\\s*:\\s*"${escaped}/'
@@ -58,12 +67,13 @@ priority = 999
 interactive = false
 `;
 
-export function geminiPolicy({ lease = null, scopes = null, imageStudio = null, memoryServer = null } = {}) {
-  return `${lease ? geminiLeasePolicy(lease.outDir, { control: Boolean(lease.control), create: Boolean(lease.create) }) : geminiReadonlyPolicy}${scopes?.web ? geminiWebPolicy : ''}${imageStudio && lease ? geminiImagePolicy(imageStudio) : ''}${memoryServer ? geminiMemoryPolicy(memoryServer) : ''}`;
+export function geminiPolicy({ lease = null, scopes = null, imageStudio = null, memoryServer = null, mcpServers = [] } = {}) {
+  return `${lease ? geminiLeasePolicy(lease.outDir, { control: Boolean(lease.control), create: Boolean(lease.create), airlock: Boolean(lease.airlock) }) : geminiReadonlyPolicy}${scopes?.web ? geminiWebPolicy : ''}${imageStudio && lease ? geminiImagePolicy(imageStudio) : ''}${memoryServer ? geminiMemoryPolicy(memoryServer) : ''}${mcpServers.map(geminiMemoryPolicy).join('')}`;
 }
 
+// Allow rules for a server's tools, by bare name and by server-prefixed name; an open tool list allows the server's prefix.
 export function geminiMemoryPolicy(memoryServer) {
-  const names = memoryServer.tools.flatMap((tool) => [tool, `${memoryServer.name}__${tool}`]);
+  const names = memoryServer.tools?.length ? memoryServer.tools.flatMap((tool) => [tool, `${memoryServer.name}__${tool}`]) : [`${memoryServer.name}__*`];
   return `
 [[rule]]
 toolName = [${names.map((name) => `"${name}"`).join(', ')}]
@@ -112,10 +122,10 @@ export function buildGeminiEnvironment({ runtimeRoot, environment = process.env
   };
 }
 
-export function isolateGeminiSettings(settings, { imageStudio = null, memoryServer = null } = {}) {
+export function isolateGeminiSettings(settings, { imageStudio = null, memoryServer = null, mcpServers = [] } = {}) {
   const auth = settings?.security?.auth;
   const isolated = auth ? { security: { auth } } : {};
-  for (const server of [memoryServer, imageStudio]) {
+  for (const server of [memoryServer, imageStudio, ...mcpServers]) {
     if (!server) continue;
     isolated.mcpServers ??= {};
     isolated.mcpServers[server.name] = { command: server.command, args: server.args, env: server.env, trust: true };
@@ -133,7 +143,7 @@ interactive = false
 `;
 }
 
-export async function prepareGeminiHome({ runtimeRoot, sourceHome = join(homedir(), '.gemini'), imageStudio = null, memoryServer = null }) {
+export async function prepareGeminiHome({ runtimeRoot, sourceHome = join(homedir(), '.gemini'), imageStudio = null, memoryServer = null, mcpServers = [] }) {
   const geminiDir = join(runtimeRoot, '.gemini');
   await mkdir(geminiDir, { recursive: true, mode: 0o700 });
   for (const name of geminiCredentialFiles) {
@@ -147,7 +157,7 @@ export async function prepareGeminiHome({ runtimeRoot, sourceHome = join(homedir
   } catch (error) {
     if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
   }
-  await writeFile(join(geminiDir, 'settings.json'), JSON.stringify(isolateGeminiSettings(settings, { imageStudio, memoryServer })), { mode: 0o600 });
+  await writeFile(join(geminiDir, 'settings.json'), JSON.stringify(isolateGeminiSettings(settings, { imageStudio, memoryServer, mcpServers })), { mode: 0o600 });
   return geminiDir;
 }
 
@@ -206,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) {
@@ -225,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;
 }
@@ -259,6 +269,7 @@ export async function invokeGemini({
   scopes = null,
   imageStudio = null,
   memoryServer = null,
+  mcpServers = [],
   idleTimeoutMs = Number(process.env.PULSE_GEMINI_IDLE_MS ?? 90000),
   retries = Number(process.env.PULSE_GEMINI_RETRIES ?? 1),
   fallbackModel = process.env.PULSE_GEMINI_FALLBACK_MODEL ?? 'gemini-2.5-flash',
@@ -268,8 +279,8 @@ export async function invokeGemini({
   const runtimeRoot = await mkdtemp(join(tmpdir(), 'pulse-gemini-'));
   const policyPath = join(runtimeRoot, 'readonly.toml');
   try {
-    await writeFile(policyPath, geminiPolicy({ lease, scopes, imageStudio: lease ? imageStudio : null, memoryServer }), { mode: 0o600 });
-    await prepareGeminiHome({ runtimeRoot, imageStudio: lease ? imageStudio : null, memoryServer });
+    await writeFile(policyPath, geminiPolicy({ lease, scopes, imageStudio: lease ? imageStudio : null, memoryServer, mcpServers }), { mode: 0o600 });
+    await prepareGeminiHome({ runtimeRoot, imageStudio: lease ? imageStudio : null, memoryServer, mcpServers });
     let attempt = 0;
     let currentModel = model;
     let switched = false;

package/src/adapters/opencode.mjs

@@ -45,7 +45,7 @@ export function writeRules(relativeDir, { control = false, create = false } = {}
   return { '*': 'deny', [dir && dir !== '.' ? `${dir}/**` : '**']: 'allow' };
 }
 
-export function leaseConfig(outDir, { control = false, create = false, relativeDir = null } = {}) {
+export function leaseConfig(outDir, { control = false, create = false, airlock = false, relativeDir = null } = {}) {
   const rules = writeRules(relativeDir ?? outDir, { control, create });
   // OpenCode gates its `write` tool behind the `edit` permission as well (denying edit leaves "no
   // file-writing tool"), so CREATE allows both and the room restores existing files afterwards.
@@ -55,7 +55,9 @@ export function leaseConfig(outDir, { control = false, create = false, relativeD
     agent: {
       'pulse-readonly': {
         ...readonlyConfig.agent['pulse-readonly'],
-        prompt: control
+        prompt: airlock
+          ? 'Answer the user directly. AIRLOCK: you are in command of this project and may run commands in it, including git and deploy CLIs with the sessions already on this machine. Say what will leave the machine before it does. Never print secrets. Do not launch subagents.'
+          : control
           ? 'Answer the user directly. You are in CONTROL of this project: create and edit files anywhere inside it except .git, .pulse, .madre and .env files. Do not run commands, browse the web, or launch subagents.'
           : create
             ? 'Answer the user directly. You may create new files and folders anywhere in this project where they belong; do not modify or delete existing files. Do not run commands, browse the web, or launch subagents.'
@@ -64,14 +66,15 @@ export function leaseConfig(outDir, { control = false, create = false, relativeD
           ...readonlyConfig.agent['pulse-readonly'].permission,
           edit: editRules,
           write: rules,
+          ...(airlock ? { bash: 'allow' } : {}),   // AIRLOCK (#4): commands, git, deploy CLIs
         },
       },
     },
   };
 }
 
-export function openCodeConfig({ lease = null, scopes = null, imageStudio = null, memoryServer = null } = {}) {
-  let config = lease ? leaseConfig(lease.outDir, { control: Boolean(lease.control), create: Boolean(lease.create), relativeDir: lease.relativeDir ?? null }) : readonlyConfig;
+export function openCodeConfig({ lease = null, scopes = null, imageStudio = null, memoryServer = null, mcpServers = [] } = {}) {
+  let config = lease ? leaseConfig(lease.outDir, { control: Boolean(lease.control), create: Boolean(lease.create), airlock: Boolean(lease.airlock), relativeDir: lease.relativeDir ?? null }) : readonlyConfig;
   if (scopes?.web) {
     config = {
       ...config,
@@ -90,17 +93,17 @@ export function openCodeConfig({ lease = null, scopes = null, imageStudio = null
       mcp: { ...(config.mcp ?? {}), [imageStudio.name]: { type: 'local', command: [imageStudio.command, ...imageStudio.args], environment: imageStudio.env, enabled: true } },
     };
   }
-  if (memoryServer) {
+  for (const server of [memoryServer, ...mcpServers].filter(Boolean)) {
     config = {
       ...config,
-      mcp: { ...(config.mcp ?? {}), [memoryServer.name]: { type: 'local', command: [memoryServer.command, ...memoryServer.args], environment: memoryServer.env, enabled: true } },
+      mcp: { ...(config.mcp ?? {}), [server.name]: { type: 'local', command: [server.command, ...(server.args ?? [])], environment: server.env ?? {}, enabled: true } },
       agent: {
         'pulse-readonly': {
           ...config.agent['pulse-readonly'],
           permission: {
             ...config.agent['pulse-readonly'].permission,
-            [`${memoryServer.name}*`]: 'allow',
-            ...Object.fromEntries(memoryServer.tools.map((tool) => [`${memoryServer.name}_${tool}`, 'allow'])),
+            [`${server.name}*`]: 'allow',
+            ...Object.fromEntries((server.tools ?? []).map((tool) => [`${server.name}_${tool}`, 'allow'])),
           },
         },
       },
@@ -109,11 +112,11 @@ export function openCodeConfig({ lease = null, scopes = null, imageStudio = null
   return config;
 }
 
-export function openCodeEnvironment(environment = process.env, { lease = null, scopes = null, imageStudio = null, memoryServer = null } = {}) {
+export function openCodeEnvironment(environment = process.env, { lease = null, scopes = null, imageStudio = null, memoryServer = null, mcpServers = [] } = {}) {
   return {
     ...environment,
     OPENCODE_AUTO_SHARE: 'false',
-    OPENCODE_CONFIG_CONTENT: JSON.stringify(openCodeConfig({ lease, scopes, imageStudio, memoryServer })),
+    OPENCODE_CONFIG_CONTENT: JSON.stringify(openCodeConfig({ lease, scopes, imageStudio, memoryServer, mcpServers })),
     OPENCODE_DISABLE_AUTOUPDATE: 'true',
   };
 }
@@ -151,12 +154,13 @@ 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 }) {
+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,
-    env: openCodeEnvironment(process.env, { lease, scopes, imageStudio, memoryServer }),
+    env: openCodeEnvironment(process.env, { lease, scopes, imageStudio, memoryServer, mcpServers }),
     timeoutMs,
     signal,
     label: 'OpenCode',

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;
@@ -41,10 +42,14 @@ 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;
     }
     const child = spawn(executable, args, {
@@ -77,8 +82,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 +97,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 +108,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;

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/capabilities.mjs

@@ -87,8 +87,9 @@ export const MODES = {
   1: { key: 'exchange', label: 'EXCHANGE', hint: 'read the project and coordinate · default' },
   2: { key: 'create', label: 'CREATE', hint: 'create files and images inside .pulse/out/' },
   3: { key: 'control', label: 'CONTROL', hint: 'modify the project itself · only this agent · needs the override' },
+  4: { key: 'airlock', label: 'AIRLOCK', hint: 'run commands, push, deploy · what leaves the ship does not come back · override, twice' },
 };
-export const MODE_MAX = 3;
+export const MODE_MAX = 4;
 export const normalizeMode = (value, fallback = 1) => {
   const mode = Number(value);
   return Number.isInteger(mode) && mode >= 0 && mode <= MODE_MAX ? mode : fallback;
@@ -110,8 +111,8 @@ export function resolveScopes(agentId, configured = {}) {
   }
   // One ceiling per agent: MAX MODE. Writing follows from it: an agent capped at #1 never
   // writes, one allowed to #2 or #3 does. A `write: false` from an older config reads as #1.
-  const capableMax = scopes.write.capable ? 3 : 1;
-  const legacyCap = configured.write === false ? 1 : 3;
+  const capableMax = scopes.write.capable ? 4 : 1;
+  const legacyCap = configured.write === false ? 1 : 4;
   scopes.maxMode = Math.min(normalizeMode(configured.maxMode, scopes.write.capable ? 2 : 1), legacyCap, capableMax);
   scopes.write.enabled = scopes.write.capable && scopes.maxMode >= 2;
   // One start per agent: DEFAULT MODE, #1 or #2, never above the ceiling. An older